fix(x402): correct Solana instruction assertion and blockhash commitment

- Use compiledInstructions on MessageV0 — tx.message.instructions throws TypeError
- Recommend getLatestBlockhash('finalized') to reduce validator timing rejections
- Document CDP's 'payer' field in rejections refers to the agent wallet, not feePayer

Author: simonlucalandi

skills/cryptorefills-x402/SKILL.md

@@ -375,7 +375,7 @@ const feePayer     = new PublicKey(extra.feePayer);         // CDP signs this sl
 
 const senderAta    = await getAssociatedTokenAddress(mint, signer.publicKey);
 const recipientAta = await getAssociatedTokenAddress(mint, owner);
-const {blockhash}  = await conn.getLatestBlockhash();
+const {blockhash}  = await conn.getLatestBlockhash('finalized');  // 'finalized' is older but accepted by all validators — reduces timing sensitivity
 
 const message = new TransactionMessage({
   payerKey:        feePayer,
@@ -390,6 +390,10 @@ const message = new TransactionMessage({
 
 const tx = new VersionedTransaction(message);
 tx.sign([signer]);                                    // partial — leaves feePayer slot
+// Assert on the pre-compilation array — MessageV0 exposes `compiledInstructions`, not `instructions`.
+// Reading `tx.message.instructions` throws TypeError. Use the source array passed to TransactionMessage.
+if (message.version !== 0) throw new Error('expected v0 message');
+if (tx.message.compiledInstructions.length !== 3) throw new Error('expected exactly 3 instructions');
 if (tx.serialize().length > 1232) throw new Error('tx too large');
 
 const txB64       = Buffer.from(tx.serialize()).toString('base64');     // inner: plain base64

skills/cryptorefills-x402/references/protocol.md

@@ -225,7 +225,7 @@ The CDP facilitator enforces a 3-to-6 instruction range and rejects payloads out
 | Field | Value |
 |---|---|
 | `payerKey` | `extra.feePayer` from PAYMENT-REQUIRED — CDP signs this slot |
-| `recentBlockhash` | Fresh from a Solana RPC (default `https://api.mainnet-beta.solana.com`); validity ~60–90 s on the Solana network, but the gateway session TTL is 60 s — that's the binding deadline |
+| `recentBlockhash` | Fresh from a Solana RPC (default `https://api.mainnet-beta.solana.com`) at commitment `'finalized'` — older but accepted by every validator, reducing timing-sensitivity rejections. Validity ~60–90 s on the Solana network, but the gateway session TTL is 60 s — that's the binding deadline |
 | `instructions` | The 3 above, in order |
 | Compile to | v0 message — `compileToV0Message()` |
 | Wrap in | `new VersionedTransaction(message)` |
@@ -268,7 +268,7 @@ The 60-second blockhash window is short. Don't insert any user prompts between P
 - **Verify `extra.feePayer` (Solana)**: must match the CDP-published value. A wrong feePayer means CDP refuses to settle.
 - **Nonce uniqueness (Base)**: never reuse a nonce — cryptographically random per transaction.
 - **Blockhash freshness (Solana)**: re-fetch the blockhash immediately before partial-signing, never reuse.
-- **Instruction-count assertion (Solana)**: assert exactly 3 instructions before serializing.
+- **Instruction-count assertion (Solana)**: assert exactly 3 instructions before serializing. Assert on `tx.message.compiledInstructions.length` (or the pre-compilation array passed to `TransactionMessage`) — `MessageV0` does not expose `tx.message.instructions`; reading it throws `TypeError`.
 - **Domain verification (Base)**: EIP-712 domain must match USDC on Base (chain 8453).
 - **Wallet isolation**: dedicated wallet, limited balance per rail.
 - **No rail mixing**: a session is pinned to the rail chosen in Phase 1. Don't try to switch rails on Phase 2 — the session ID won't match and the signature is rejected.

skills/cryptorefills-x402/references/troubleshooting.md

@@ -27,6 +27,7 @@ Error handling and recovery for x402 autonomous purchases. Organized by category
 | `unknown_error` from `/verify` | You used SPL `Transfer` (tag `0x03`). Switch to `createTransferCheckedInstruction` (tag `0x0c`). |
 | `transaction instructions length mismatch: 1 < 3 or 1 > 6` | Wrong instruction count. Use the exact 3-instruction preamble: ComputeBudget set-limit + ComputeBudget set-price + TransferChecked. |
 | `feePayer not managed` | The `extra.feePayer` you used is not recognised by CDP. Restart Phase 1 to get a fresh `extra.feePayer` and use it verbatim. |
+| CDP rejection echoes a `"payer":"<pubkey>"` field that doesn't match your `payerKey` | Not a bug. CDP's rejection messages use `"payer"` to mean **the paying agent's wallet** (the SPL `TransferChecked` authority / signer), not the Solana fee payer. The transaction's `payerKey` correctly stays set to `extra.feePayer` (CDP's key) — the field name collision is just CDP's terminology. Don't change `payerKey` in response to this. |
 | `blockhash expired` | You took longer than ~60 s between fetching the blockhash and submitting Phase 2. Re-fetch the blockhash and re-sign. |
 | Phase 2 rejected with "X-Session-Id required" | You omitted `X-Session-Id` on Solana Phase 2. Echo the UUID from the Phase 1 `X-Session-Id` response header. |
 | Wrong `payTo` interpretation | `payTo` is the **owner pubkey, not an ATA**. Derive the recipient ATA from `(payTo, mint)` via `getAssociatedTokenAddress`. |