docs: fix x402 guide verification section and wallet adapter imports

tenequm · tenequm · commit 44bf1d66101e · 2026-03-05T18:59:07.000Z
- Use listFeedbacks (has taskRef) instead of searchFeedback (doesn't)
- Add missing hexToBytes import in server-side wallet adapter code
- Both verified against actual SDK types and x402 API source
diff --git a/docs/guides/x402-feedback.md b/docs/guides/x402-feedback.md
@@ -5,20 +5,159 @@ description: Link feedback directly to x402 payment transactions
 
 # x402 Payment Feedback
 
-::: warning Coming Soon
-This guide is under active development. SATI is designed as the feedback extension for [x402](https://x402.org) payments (see [PR #1024](https://github.com/coinbase/x402/pull/1024)), but the end-to-end integration guide is not yet ready.
-:::
+SATI is designed as the feedback extension for [x402](https://x402.org) payments. The payment transaction signature becomes the `taskRef`, creating a cryptographic link between payment and feedback.
 
-## What This Will Cover
+## How It Works
 
-- Linking feedback attestations to x402 payment transaction hashes
-- The payment-as-taskRef model: the payment tx becomes the deterministic reference for feedback
-- Who pays for on-chain submission (agent pays for positive, client pays for negative)
-- Integrating SATI feedback into x402 seller and buyer flows
+1. Client pays for a service via x402 (HTTP 402 flow)
+2. Facilitator settles the payment on Solana, producing a transaction signature
+3. After service delivery, the facilitator (or client) submits SATI feedback with the payment signature as `taskRef`
+4. Feedback is permanently linked to the payment transaction on-chain
 
-## In the Meantime
+## taskRef Derivation
 
-- Read [How It Works](/how-it-works) to understand blind feedback and proof of participation
-- See the [Agent Marketplace](/guides/agent-marketplace) guide for the general feedback flow
-- Check the [sati-agent0-sdk reference](/reference/sati-agent0-sdk) for `giveFeedback` and `prepareFeedback` API details
-- Follow progress on [GitHub](https://github.com/cascade-protocol/sati)
+SATI's `taskRef` is 32 bytes. Solana transaction signatures are 64 bytes. To link them, hash the signature:
+
+```typescript
+import { keccak_256 } from "@noble/hashes/sha3";
+import bs58 from "bs58";
+
+// x402 settlement gives you a base58 transaction signature
+const txSignature = settlementResponse.transaction; // e.g. "5Kj..."
+
+// Hash to 32 bytes for SATI taskRef
+const sigBytes = bs58.decode(txSignature);
+const taskRef = keccak_256(sigBytes);
+```
+
+This is deterministic - the same payment signature always produces the same `taskRef`. Anyone with the payment tx can verify the link.
+
+## Facilitator Integration
+
+The facilitator is the natural feedback manager - already in the payment flow, trusted by both parties. Use x402's `onAfterSettle` lifecycle hook:
+
+```typescript
+import { x402ResourceServer } from "@x402/core";
+import { Sati, Outcome, address } from "@cascade-fyi/sati-sdk";
+import { keccak_256 } from "@noble/hashes/sha3";
+import { createKeyPairSignerFromBytes } from "@solana/kit";
+import bs58 from "bs58";
+
+const sati = new Sati({ network: "mainnet" });
+const facilitatorPayer = await createKeyPairSignerFromBytes(keypairBytes);
+
+const server = new x402ResourceServer(facilitatorClient);
+
+server.onAfterSettle(async (context) => {
+  const txSignature = context.result.transaction;
+  const sigBytes = bs58.decode(txSignature);
+  const taskRef = keccak_256(sigBytes);
+
+  // The facilitator's payTo address is the agent's payment wallet.
+  // Map it to the agent's SATI mint address (your registry lookup).
+  const agentMint = await lookupAgentMint(context.requirements.payTo);
+
+  if (agentMint) {
+    await sati.giveFeedback({
+      payer: facilitatorPayer,
+      agentMint: address(agentMint),
+      taskRef,
+      outcome: Outcome.Positive,
+      value: 100,
+      tag1: "x402",
+      endpoint: context.paymentPayload.resource?.url,
+    });
+  }
+});
+```
+
+## Client-Side Feedback (After Service Delivery)
+
+If the client rates the service after receiving it, pass the payment tx as `taskRef`:
+
+```typescript
+import { Sati, Outcome, address } from "@cascade-fyi/sati-sdk";
+import { keccak_256 } from "@noble/hashes/sha3";
+import bs58 from "bs58";
+
+const sati = new Sati({ network: "mainnet" });
+
+// paymentTxSignature from the x402 settlement response
+const taskRef = keccak_256(bs58.decode(paymentTxSignature));
+
+await sati.giveFeedback({
+  payer: clientKeypair,
+  agentMint: address("AgentMint..."),
+  taskRef,
+  outcome: Outcome.Positive,
+  value: 85,
+  tag1: "starred",
+  message: "Fast response, accurate results",
+});
+```
+
+## Browser Wallet Flow (Marketplace)
+
+For marketplaces where the user rates via browser wallet after an x402 purchase:
+
+```typescript
+// Server: prepare feedback with the payment's taskRef
+const taskRef = keccak_256(bs58.decode(paymentTxSignature));
+
+const prepared = await sati.prepareFeedback({
+  counterparty: address(userWalletAddress),
+  agentMint: address("AgentMint..."),
+  taskRef,
+  outcome: Outcome.Positive,
+  value: 85,
+  tag1: "starred",
+});
+
+// Send messageBytes to frontend for signing (see Wallet Adapter section in SKILL.md)
+```
+
+## Verifying Payment-Feedback Links
+
+Given a feedback attestation, verify it links to a specific payment:
+
+```typescript
+const result = await sati.listFeedbacks({
+  agentMint: address("AgentMint...") as Address,
+});
+
+const expectedTaskRef = keccak_256(bs58.decode(paymentTxSignature));
+
+for (const fb of result.items) {
+  // fb.data.taskRef is the 32-byte hash stored on-chain
+  const ref = fb.data.taskRef;
+  const matches = ref.length === expectedTaskRef.length &&
+    ref.every((b, i) => b === expectedTaskRef[i]);
+}
+```
+
+## REST API
+
+Submit feedback with a payment link via the REST API (no wallet needed):
+
+```bash
+curl -X POST https://sati.cascade.fyi/api/feedback \
+  -H "Content-Type: application/json" \
+  -d '{
+    "agentMint": "AgentMint...",
+    "value": 85,
+    "tag1": "x402",
+    "outcome": 2,
+    "message": "Paid via x402, service delivered correctly"
+  }'
+```
+
+Note: The REST API generates a random `taskRef` - it does not accept a custom one. For deterministic payment linking, use the SDK.
+
+## Cost Structure
+
+| Operation | Cost |
+|-----------|------|
+| Feedback attestation | ~0.00001 SOL (ZK compressed) |
+| x402 payment (separate) | Varies by facilitator |
+
+Feedback costs are negligible compared to the x402 payment itself. Facilitators can batch feedback submissions to reduce per-transaction overhead.
diff --git a/skills/sati/SKILL.md b/skills/sati/SKILL.md
@@ -230,37 +230,102 @@ For proof-of-participation, use the **FeedbackV1** schema (DualSignature mode).
 
 The platform server prepares a SIWS (Sign In With Solana) message, the user signs it in their browser wallet, and the platform submits the transaction.
 
+Uses `@solana/wallet-adapter-react` (works with Phantom, Solflare, Backpack, and any wallet implementing the Wallet Standard `signMessage` feature).
+
+```bash
+npm install @solana/wallet-adapter-react @solana/wallet-adapter-wallets @solana/wallet-adapter-react-ui
+```
+
+**Server (API route):**
+
 ```typescript
+import { Sati, Outcome, address, bytesToHex, hexToBytes } from "@cascade-fyi/sati-sdk";
+
+const sati = new Sati({ network: "mainnet" });
+
+// POST /api/prepare-feedback
+async function handlePrepare(req) {
+  const { walletAddress, agentMint, value, tag1, outcome } = req.body;
+
+  const prepared = await sati.prepareFeedback({
+    counterparty: address(walletAddress),
+    agentMint: address(agentMint),
+    outcome: outcome ?? Outcome.Positive,
+    value,
+    tag1,
+  });
+
+  // Store `prepared` server-side (e.g. in session or cache keyed by walletAddress + agentMint)
+  await cache.set(`feedback:${walletAddress}:${agentMint}`, prepared);
+
+  // Only send the SIWS message bytes to the frontend
+  return { messageHex: bytesToHex(prepared.messageBytes) };
+}
+
+// POST /api/submit-feedback
+async function handleSubmit(req) {
+  const { walletAddress, agentMint, signatureHex } = req.body;
+
+  const prepared = await cache.get(`feedback:${walletAddress}:${agentMint}`);
+  const result = await sati.submitPreparedFeedback({
+    payer: platformPayer,
+    prepared,
+    counterpartySignature: hexToBytes(signatureHex),
+  });
+
+  return { signature: result.signature, attestationAddress: result.attestationAddress };
+}
+```
+
+**Frontend (React component):**
+
+```tsx
+import { useWallet } from "@solana/wallet-adapter-react";
 import { hexToBytes, bytesToHex } from "@cascade-fyi/sati-sdk";
 
-// Step 1: Server prepares feedback data
-const prepared = await sati.prepareFeedback({
-  counterparty: address("UserWallet..."),
-  agentMint: address("Agent..."),
-  outcome: Outcome.Positive,
-  value: 90,
-  tag1: "starred",
-});
+function FeedbackButton({ agentMint }: { agentMint: string }) {
+  const { publicKey, signMessage, connected } = useWallet();
+
+  async function handleFeedback() {
+    if (!publicKey || !signMessage) return;
+
+    // 1. Server prepares the SIWS message
+    const { messageHex } = await fetch("/api/prepare-feedback", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        walletAddress: publicKey.toBase58(),
+        agentMint,
+        value: 85,
+        tag1: "starred",
+      }),
+    }).then((r) => r.json());
+
+    // 2. User signs with wallet (Phantom/Solflare popup)
+    const messageBytes = hexToBytes(messageHex);
+    const signature = await signMessage(messageBytes); // Returns Uint8Array (64-byte Ed25519)
+
+    // 3. Server submits the transaction
+    await fetch("/api/submit-feedback", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        walletAddress: publicKey.toBase58(),
+        agentMint,
+        signatureHex: bytesToHex(signature),
+      }),
+    });
+  }
 
-// Step 2: Send to frontend (only messageBytes needs to cross the wire)
-// The server keeps the full `prepared` object; only send what the frontend needs to sign.
-const payload = {
-  messageHex: bytesToHex(prepared.messageBytes),
-};
-
-// Step 3: Frontend - user signs with wallet adapter
-const messageBytes = hexToBytes(payload.messageHex);
-const signature = await wallet.signMessage(messageBytes); // Returns Uint8Array (Ed25519 signature)
-
-// Step 4: Server submits with platform payer (uses the full `prepared` object kept server-side)
-const result = await sati.submitPreparedFeedback({
-  payer: platformPayer,           // Platform pays gas
-  prepared,                       // Full PreparedFeedbackData from step 1
-  counterpartySignature: signature, // User's 64-byte Ed25519 signature
-});
+  return (
+    <button onClick={handleFeedback} disabled={!connected}>
+      Rate Agent
+    </button>
+  );
+}
 ```
 
-> **Note:** `PreparedFeedbackData` contains multiple `Uint8Array` fields (`messageBytes`, `taskRef`, `dataHash`, `content`). If you need to serialize the entire object to JSON (e.g. for a stateless API), convert all `Uint8Array` fields with `bytesToHex()` and restore with `hexToBytes()`. The recommended pattern above avoids this by keeping `prepared` server-side.
+> **Note:** `signMessage` is `undefined` if the connected wallet doesn't support message signing. Always check `signMessage` before calling it. `PreparedFeedbackData` contains multiple `Uint8Array` fields (`messageBytes`, `taskRef`, `dataHash`, `content`). If you need to serialize the entire object to JSON (e.g. for a stateless API), convert all `Uint8Array` fields with `bytesToHex()` and restore with `hexToBytes()`. The recommended pattern above avoids this by keeping `prepared` server-side.
 
 #### Revoke feedback
 
