@agent-score/commerce 1.1.0 → 1.3.0

package/README.md

@@ -16,7 +16,7 @@ bun add @agent-score/commerce
 Framework + protocol packages are optional peer deps — install only what you use:
 
 ```bash
-npm install hono mppx @x402/core @x402/evm @x402/svm stripe   # whatever your stack needs
+npm install hono mppx @x402/core @x402/evm @solana/mpp @solana/kit stripe   # whatever your stack needs
 ```
 
 ## What's in the package
@@ -24,8 +24,8 @@ npm install hono mppx @x402/core @x402/evm @x402/svm stripe   # whatever your st
 | Subpath | What it provides |
 |---|---|
 | `/identity/{hono,express,fastify,nextjs,web}` | Trust gate middleware: KYC, sanctions, age, jurisdiction. `agentscoreGate(...)`, `getAgentScoreData(c)`, `captureWallet(...)`, `verifyWalletSignerMatch(...)`. Plus shared denial helpers: `denialReasonStatus`, `denialReasonToBody`, `buildSignerMismatchBody`, `buildContactSupportNextSteps`, `verificationAgentInstructions`, `isFixableDenial`, `FIXABLE_DENIAL_REASONS`. |
-| `/payment` | `networks`, `USDC`, `rails` registries; `paymentDirective`, `buildPaymentDirective`, `wwwAuthenticateHeader`, `paymentRequiredHeader`, `aliasAmountFields` (v1↔v2 amount field shim — emits both `amount` and `maxAmountRequired` so v1-only x402 parsers like Coinbase awal can read v2 bodies), `settlementOverrideHeader`, `dispatchSettlementByNetwork`, `extractPaymentSigner` (returns `{address, network}`); `createX402Server`, `createMppxServer`; drop-in x402 helpers: `validateX402NetworkConfig` (boot-time guard), `verifyX402Request` (parse + validate inbound X-Payment), `processX402Settle` (verify-then-settle with one call). |
-| `/discovery` | `isDiscoveryProbeRequest`, `buildDiscoveryProbeResponse` (with optional `x402Sample` for x402-aware crawlers — `awal x402 details` etc.), `sampleX402AcceptForNetwork` (USDC sample-accept builder for known CAIP-2 networks), `buildWellKnownMpp`, `buildLlmsTxt` + `llmsTxtIdentitySection` + `llmsTxtPaymentSection` (compact + verbose modes), `agentscoreOpenApiSnippets`, `createBazaarDiscovery`, `noindexNonDiscoveryPaths` (Hono middleware that emits `X-Robots-Tag: noindex` on every path except the agent-discovery surfaces — defaults cover `/openapi.json`, `/llms.txt`, `/.well-known/{mpp.json,agent-card.json,ucp}`, `/favicon.{png,ico}`; pure helpers `isDiscoveryPath` + `defaultDiscoveryPaths` for non-Hono frameworks). |
+| `/payment` | `networks`, `USDC`, `rails` registries; `paymentDirective`, `buildPaymentDirective`, `wwwAuthenticateHeader`, `paymentRequiredHeader`, `aliasAmountFields` (v1↔v2 amount field shim — emits both `amount` and `maxAmountRequired` so v1-only x402 parsers like Coinbase awal can read v2 bodies), `settlementOverrideHeader`, `dispatchSettlementByNetwork`, `extractPaymentSigner` (returns `{address, network}`); `createX402Server`, `createMppxServer`; drop-in x402 helpers: `validateX402NetworkConfig` (boot-time guard), `verifyX402Request` (parse + validate inbound X-Payment), `processX402Settle` (verify-then-settle with one call), `classifyX402SettleResult` (maps the tagged settle result to a recommended HTTP status / code / nextSteps so merchants get a controlled envelope without coupling to facilitator-specific error text). |
+| `/discovery` | `isDiscoveryProbeRequest`, `buildDiscoveryProbeResponse` (with optional `x402Sample` for x402-aware crawlers — `awal x402 details` etc.), `sampleX402AcceptForNetwork` (USDC sample-accept builder for known CAIP-2 networks), `buildWellKnownMpp`, `buildLlmsTxt` + `llmsTxtIdentitySection` + `llmsTxtPaymentSection` (compact + verbose modes), `buildSkillMd` (Claude-Skill-compatible `/skill.md` agent-discovery manifest — strictly agent-facing data only, no internal posture), `agentscoreOpenApiSnippets`, `createBazaarDiscovery`, `noindexNonDiscoveryPaths` (Hono middleware that emits `X-Robots-Tag: noindex` on every path except the agent-discovery surfaces — defaults cover `/openapi.json`, `/llms.txt`, `/skill.md`, `/.well-known/{mpp.json,agent-card.json,ucp}`, `/favicon.{png,ico}`; pure helpers `isDiscoveryPath` + `defaultDiscoveryPaths` for non-Hono frameworks). |
 | `/challenge` | `build402Body`, `buildAcceptedMethods`, `buildIdentityMetadata`, `buildHowToPay`, `buildAgentInstructions` (auto-emits per-rail `compatible_clients` — smoke-verified CLIs the agent should use; vendor override supported), `buildPricingBlock`, `firstEncounterAgentMemory`, `OrderReceipt`; `respond402` — drop-in 402 emit that preserves mppx's `WWW-Authenticate` and layers x402's `PAYMENT-REQUIRED`. `buildValidationError` — structured 4xx body builder (`{error: {code, message}, required_fields?, example_body?, next_steps?, ...extra}`) so vendors compose body shapes by name instead of inlining at every validation site. |
 | `/stripe-multichain` | `createMultichainPaymentIntent`, `getDepositAddress`, `simulateCryptoDeposit`, `createMppxStripe`; `createPiCache` (TTL'd PI / deposit-address cache, Redis-backed when `redisUrl` set, in-memory otherwise), `simulateDepositIfTestMode` (gates on `sk_test_` and looks up the PI for you), `STRIPE_TEST_TX_HASH_SUCCESS` / `STRIPE_TEST_TX_HASH_FAILED` constants. Peer dep on `stripe`. |
 | `/api` | Everything from `@agent-score/sdk` re-exported in one place: `AgentScore` + `AgentScoreError`, `AGENTSCORE_TEST_ADDRESSES` + `isAgentScoreTestAddress`. **Don't add `@agent-score/sdk` as a separate dep** — the two can drift versions and cause subtle type mismatches. |
@@ -89,13 +89,16 @@ import {
 
 // Build paymentauth.org directives by symbolic rail name (decimals + currency from registry)
 const directives = [
-  buildPaymentDirective({ rail: "tempo-mainnet",       id: "chg_t", realm: "ex.com", recipient: TEMPO_ADDR, amountUsd: 0.01 }),
-  buildPaymentDirective({ rail: "x402-base-mainnet",   id: "chg_b", realm: "ex.com", recipient: BASE_ADDR,  amountUsd: 0.01 }),
-  buildPaymentDirective({ rail: "x402-solana-mainnet", id: "chg_s", realm: "ex.com", recipient: SOL_ADDR,   amountUsd: 0.01 }),
+  buildPaymentDirective({ rail: "tempo-mainnet",     id: "chg_t", realm: "ex.com", recipient: TEMPO_ADDR, amountUsd: 0.01 }),
+  buildPaymentDirective({ rail: "x402-base-mainnet", id: "chg_b", realm: "ex.com", recipient: BASE_ADDR,  amountUsd: 0.01 }),
+  buildPaymentDirective({ rail: "mpp-solana-mainnet", id: "chg_s", realm: "ex.com", recipient: SOL_ADDR,  amountUsd: 0.01 }),
 ];
 const wwwAuth = wwwAuthenticateHeader(directives);
 
-// Recover the on-chain signer from the inbound credential — returns {address, network}
+// Recover the on-chain signer from the inbound credential — returns {address, network}.
+// Covers x402 EIP-3009 (EVM `from` address), Tempo MPP (`did:pkh:eip155` source),
+// and Solana MPP `solana/charge` (via `did:pkh:solana` source when set, else by
+// decoding the credential's signed-tx payload — `@solana/kit` optional peer).
 const signer = await extractPaymentSigner(req, req.headers.get("x-payment") ?? undefined);
 ```
 
@@ -106,12 +109,17 @@ import { createX402Server, createMppxServer } from "@agent-score/commerce/paymen
 
 const x402 = await createX402Server({
   facilitator: "coinbase",  // or "http", or pass a custom facilitator instance
-  rails: ["x402-base-mainnet", "x402-solana-mainnet", "x402-base-mainnet-upto"],
+  rails: ["x402-base-mainnet", "x402-base-mainnet-upto"],
 });
 
 const mppx = await createMppxServer({
   rails: {
     tempo: { recipient: process.env.TEMPO_RECIPIENT! },
+    solana: {
+      recipient: process.env.SOLANA_RECIPIENT!,
+      // Optional fee sponsor — pass any `TransactionPartialSigner` from `@solana/kit`.
+      // signer: solanaFeePayerSigner,
+    },
     stripe: { profileId: process.env.STRIPE_PROFILE_ID!, secretKey: process.env.STRIPE_SECRET_KEY! },
   },
   secretKey: process.env.MPP_SECRET_KEY!,
@@ -132,7 +140,7 @@ import {
 const acceptedMethods = buildAcceptedMethods({
   tempo: { recipient: TEMPO_ADDR },
   x402_base: { recipient: BASE_ADDR },
-  x402_solana: { recipient: SOL_ADDR },
+  solana_mpp: { recipient: SOL_ADDR, feePayerKey: SOLANA_FEE_PAYER },
   stripe: { profileId: STRIPE_PROFILE_ID },
 });
 
@@ -236,6 +244,7 @@ await simulateDepositIfTestMode({
 
 ```typescript
 import {
+  classifyX402SettleResult,
   processX402Settle,
   validateX402NetworkConfig,
   verifyX402Request,
@@ -243,7 +252,7 @@ import {
 import { respond402 } from "@agent-score/commerce/challenge";
 
 // Boot-time guard — raises if a configured network isn't supported.
-validateX402NetworkConfig({ baseNetwork: X402_BASE, svmNetwork: X402_SVM });
+validateX402NetworkConfig({ baseNetwork: X402_BASE });
 
 app.post("/purchase", async (c) => {
   // Path A — agent presented an x402 X-Payment header
@@ -251,7 +260,7 @@ app.post("/purchase", async (c) => {
     const verified = await verifyX402Request({
       request: c.req.raw,
       isCachedAddress: piCache.hasAddress,
-      acceptedNetworks: { base: X402_BASE, svm: X402_SVM },
+      acceptedNetwork: X402_BASE,
     });
     if (!verified.ok) return c.json(verified.body, verified.status);
 
@@ -261,7 +270,13 @@ app.post("/purchase", async (c) => {
       resourceConfig: { scheme: "exact", network: verified.signedNetwork, price: `$${total}`, payTo: verified.signedPayTo, maxTimeoutSeconds: 300 },
       resourceMeta: { url: c.req.url, mimeType: "application/json" },
     });
-    if (!settle.success) return c.json({ error: { code: "payment_proof_invalid", phase: settle.phase } }, 400);
+    const classified = classifyX402SettleResult(settle);
+    if (classified) {
+      // Log raw `settle` server-side; return controlled phase-based response to the agent.
+      console.error("[x402-settle]", { phase: settle.success ? null : settle.phase, raw: settle });
+      return c.json({ error: { code: classified.code, message: classified.message }, next_steps: classified.nextSteps }, classified.status);
+    }
+    if (!settle.success) throw new Error("unreachable: classified covers every non-success phase");
 
     const headers: Record<string, string> = {};
     if (settle.paymentResponseHeader) headers["payment-response"] = settle.paymentResponseHeader;

package/dist/{_response-RpEB7-vl.d.ts → _response-C2yFQoIA.d.ts}

@@ -77,7 +77,7 @@ declare function buildSignerMismatchBody(input: SignerMismatchBodyInput): Record
  *   return c.json({
  *     error: { code: 'compliance_denied', message: '...' },
  *     reasons,
- *     next_steps: buildContactSupportNextSteps('support@martinestate.com'),
+ *     next_steps: buildContactSupportNextSteps('support@example.com'),
  *   }, 403);
  */
 declare function buildContactSupportNextSteps(supportEmail: string, message?: string): {

package/dist/{_response-DS-LR590.d.mts → _response-DpB-cm2c.d.mts}

@@ -77,7 +77,7 @@ declare function buildSignerMismatchBody(input: SignerMismatchBodyInput): Record
  *   return c.json({
  *     error: { code: 'compliance_denied', message: '...' },
  *     reasons,
- *     next_steps: buildContactSupportNextSteps('support@martinestate.com'),
+ *     next_steps: buildContactSupportNextSteps('support@example.com'),
  *   }, 403);
  */
 declare function buildContactSupportNextSteps(supportEmail: string, message?: string): {

package/dist/agent_instructions-DiMSGkdm.d.mts

@@ -0,0 +1,133 @@
+interface HowToPayRailEntry {
+    setup?: string[];
+    prerequisite?: string;
+    command: string;
+    alternative_command?: string;
+    what_it_does: string;
+}
+interface HowToPayStripeEntry {
+    prerequisite: string;
+    instructions: string;
+    setup_link_cli?: string[];
+    command_link_cli?: string[];
+    what_it_does_link_cli?: string;
+    note?: string;
+}
+interface HowToPayBlock {
+    tempo?: HowToPayRailEntry;
+    x402_base?: HowToPayRailEntry;
+    solana_mpp?: HowToPayRailEntry;
+    stripe?: HowToPayStripeEntry;
+}
+interface BuildHowToPayInput {
+    /** The merchant's full URL (e.g., 'https://agents.merchant.example/api/buy'). */
+    url: string;
+    /** JSON string of the body the agent should retry with — typically the original request body. */
+    retryBodyJson: string;
+    /** Total amount in USD (string or number). Used to compute max-spend defaults and stripe context. */
+    totalUsd: string | number;
+    /** Per-rail config — each is optional. Pass only the rails you support. */
+    rails: {
+        tempo?: {
+            recipient: string;
+            networkName?: string;
+            chainId?: number;
+            recommend?: 'tempo' | 'agentscore-pay' | 'both';
+        };
+        x402_base?: {
+            recipient: string;
+            network?: string;
+        };
+        solana_mpp?: {
+            recipient: string;
+            network?: string;
+        };
+        stripe?: {
+            profileId?: string | null;
+            productName?: string;
+        };
+    };
+    /** Placeholder text for the operator token in commands. Defaults to '<your_opc_token>'. */
+    opTokenPlaceholder?: string;
+    /** Override max-spend value used in commands. Default: ceil(totalUsd) + 1. */
+    maxSpend?: string | number;
+}
+/**
+ * Build the agent_instructions.how_to_pay block. Generates per-rail setup/command/what_it_does
+ * boilerplate so agents see concrete commands per rail in the 402 body. Vendors pass the rails
+ * they support; the helper produces the right command for each.
+ *
+ * Tool recommendations (tempo CLI vs agentscore-pay vs link-cli) are configurable per rail.
+ */
+declare function buildHowToPay(input: BuildHowToPayInput): HowToPayBlock;
+
+/** Map of rail key (e.g. 'x402_base', 'tempo_mpp', 'stripe') → list of client identifiers
+ *  that have been smoke-verified by the merchant against the protocol shape they emit.
+ *  Strings are display labels, not install commands — agents already get install commands
+ *  via `how_to_pay.<rail>.setup`. Use these as a "what's known to work" hint. */
+type CompatibleClients = Record<string, string[]>;
+interface BuildAgentInstructionsInput {
+    /** Per-rail commands. Build with `buildHowToPay`. */
+    howToPay: HowToPayBlock;
+    /** Tool recommendations as human-readable strings. Defaults to a sensible set covering tempo + agentscore-pay. */
+    recommendedTools?: string[];
+    /** Wallet-stack compatibility note for the agent. Default: rail-neutral, no specific wallet stack required. */
+    walletCompatibility?: string;
+    /** How long the merchant will wait for payment after the 402. Default 300 (5 minutes). */
+    timeoutSeconds?: number;
+    /** Warnings about common footguns. Defaults include tempo wallet transfer + raw on-chain x402 deposits. */
+    warnings?: string[];
+    /** Additional warnings appended to the default protocol-footgun set. Use this when you want
+     *  to keep the SDK's protocol warnings AND add merchant-specific notes (e.g., a per-order
+     *  rail-availability message). Ignored when `warnings` is set explicitly. */
+    extraWarnings?: string[];
+    /** Recommended rail (e.g., 'tempo', 'x402_base'). Surfaced for agents to default to. */
+    recommended?: string;
+    /** Per-rail list of client names the merchant has verified work end-to-end. Vendors set
+     *  this from their own smoke matrix — defaults to none (avoids vouching for clients the
+     *  merchant has not tested). When omitted, the field is not emitted. */
+    compatibleClients?: CompatibleClients;
+    /** Arbitrary additional fields the vendor wants merged into the agent_instructions object. */
+    extra?: Record<string, unknown>;
+}
+interface AgentInstructions {
+    how_to_pay: HowToPayBlock;
+    recommended_tools: string[];
+    wallet_compatibility: string;
+    timeout_seconds: number;
+    warnings: string[];
+    recommended?: string;
+    compatible_clients?: CompatibleClients;
+    [key: string]: unknown;
+}
+/**
+ * Default `compatible_clients` derived from the rails declared in `howToPay`. Lists
+ * clients the AgentScore team has smoke-verified end-to-end against an `@agent-score/commerce`
+ * merchant; entries appear only for rails the vendor actually offers. Vendors override
+ * this in `buildAgentInstructions({compatibleClients: {...}})` to add their own tested
+ * clients or remove entries that don't fit their endpoint.
+ *
+ * Verified state as of the SDK release. The same data is also published as a docs page
+ * for humans (rationale, per-rail commands, why some clients don't fully work, last
+ * verified date) — this default keeps the merchant-side surface in sync.
+ */
+/** Symbolic rail keys agent-facing surfaces use to talk about a rail without spelling out
+ *  network/scheme details. Same keys as `CompatibleClients` map keys. */
+type RailKey = 'tempo_mpp' | 'x402_base' | 'solana_mpp' | 'stripe';
+/** Returns the smoke-verified client list for a set of rail keys. The single source of
+ *  truth for "which CLIs we've verified end-to-end on each rail" — consumed both by the
+ *  402-body builder (`defaultCompatibleClients`) and by discovery surfaces (skill.md,
+ *  llms.txt, etc.). Update here, every surface inherits. */
+declare function compatibleClientsByRails(rails: readonly RailKey[]): CompatibleClients | undefined;
+/**
+ * Build the agent_instructions object for the 402 body. Combines how_to_pay with
+ * recommended tools, warnings, wallet-compatibility note, and timeout.
+ *
+ * Defaults adapt to the rails declared in `howToPay`: only tempo-relevant warnings/tools
+ * appear if `howToPay.tempo` is set, only x402-relevant ones if `x402_base` is set.
+ * Stripe-only merchants get neither rail-specific warning. Vendors override
+ * `warnings`/`recommendedTools` for full control.
+ */
+declare function buildAgentInstructions(input: BuildAgentInstructionsInput): AgentInstructions;
+
+export { type AgentInstructions as A, type BuildAgentInstructionsInput as B, type CompatibleClients as C, type HowToPayBlock as H, type RailKey as R, type BuildHowToPayInput as a, type HowToPayRailEntry as b, type HowToPayStripeEntry as c, buildAgentInstructions as d, buildHowToPay as e, compatibleClientsByRails as f };

package/dist/agent_instructions-DiMSGkdm.d.ts

@@ -0,0 +1,133 @@
+interface HowToPayRailEntry {
+    setup?: string[];
+    prerequisite?: string;
+    command: string;
+    alternative_command?: string;
+    what_it_does: string;
+}
+interface HowToPayStripeEntry {
+    prerequisite: string;
+    instructions: string;
+    setup_link_cli?: string[];
+    command_link_cli?: string[];
+    what_it_does_link_cli?: string;
+    note?: string;
+}
+interface HowToPayBlock {
+    tempo?: HowToPayRailEntry;
+    x402_base?: HowToPayRailEntry;
+    solana_mpp?: HowToPayRailEntry;
+    stripe?: HowToPayStripeEntry;
+}
+interface BuildHowToPayInput {
+    /** The merchant's full URL (e.g., 'https://agents.merchant.example/api/buy'). */
+    url: string;
+    /** JSON string of the body the agent should retry with — typically the original request body. */
+    retryBodyJson: string;
+    /** Total amount in USD (string or number). Used to compute max-spend defaults and stripe context. */
+    totalUsd: string | number;
+    /** Per-rail config — each is optional. Pass only the rails you support. */
+    rails: {
+        tempo?: {
+            recipient: string;
+            networkName?: string;
+            chainId?: number;
+            recommend?: 'tempo' | 'agentscore-pay' | 'both';
+        };
+        x402_base?: {
+            recipient: string;
+            network?: string;
+        };
+        solana_mpp?: {
+            recipient: string;
+            network?: string;
+        };
+        stripe?: {
+            profileId?: string | null;
+            productName?: string;
+        };
+    };
+    /** Placeholder text for the operator token in commands. Defaults to '<your_opc_token>'. */
+    opTokenPlaceholder?: string;
+    /** Override max-spend value used in commands. Default: ceil(totalUsd) + 1. */
+    maxSpend?: string | number;
+}
+/**
+ * Build the agent_instructions.how_to_pay block. Generates per-rail setup/command/what_it_does
+ * boilerplate so agents see concrete commands per rail in the 402 body. Vendors pass the rails
+ * they support; the helper produces the right command for each.
+ *
+ * Tool recommendations (tempo CLI vs agentscore-pay vs link-cli) are configurable per rail.
+ */
+declare function buildHowToPay(input: BuildHowToPayInput): HowToPayBlock;
+
+/** Map of rail key (e.g. 'x402_base', 'tempo_mpp', 'stripe') → list of client identifiers
+ *  that have been smoke-verified by the merchant against the protocol shape they emit.
+ *  Strings are display labels, not install commands — agents already get install commands
+ *  via `how_to_pay.<rail>.setup`. Use these as a "what's known to work" hint. */
+type CompatibleClients = Record<string, string[]>;
+interface BuildAgentInstructionsInput {
+    /** Per-rail commands. Build with `buildHowToPay`. */
+    howToPay: HowToPayBlock;
+    /** Tool recommendations as human-readable strings. Defaults to a sensible set covering tempo + agentscore-pay. */
+    recommendedTools?: string[];
+    /** Wallet-stack compatibility note for the agent. Default: rail-neutral, no specific wallet stack required. */
+    walletCompatibility?: string;
+    /** How long the merchant will wait for payment after the 402. Default 300 (5 minutes). */
+    timeoutSeconds?: number;
+    /** Warnings about common footguns. Defaults include tempo wallet transfer + raw on-chain x402 deposits. */
+    warnings?: string[];
+    /** Additional warnings appended to the default protocol-footgun set. Use this when you want
+     *  to keep the SDK's protocol warnings AND add merchant-specific notes (e.g., a per-order
+     *  rail-availability message). Ignored when `warnings` is set explicitly. */
+    extraWarnings?: string[];
+    /** Recommended rail (e.g., 'tempo', 'x402_base'). Surfaced for agents to default to. */
+    recommended?: string;
+    /** Per-rail list of client names the merchant has verified work end-to-end. Vendors set
+     *  this from their own smoke matrix — defaults to none (avoids vouching for clients the
+     *  merchant has not tested). When omitted, the field is not emitted. */
+    compatibleClients?: CompatibleClients;
+    /** Arbitrary additional fields the vendor wants merged into the agent_instructions object. */
+    extra?: Record<string, unknown>;
+}
+interface AgentInstructions {
+    how_to_pay: HowToPayBlock;
+    recommended_tools: string[];
+    wallet_compatibility: string;
+    timeout_seconds: number;
+    warnings: string[];
+    recommended?: string;
+    compatible_clients?: CompatibleClients;
+    [key: string]: unknown;
+}
+/**
+ * Default `compatible_clients` derived from the rails declared in `howToPay`. Lists
+ * clients the AgentScore team has smoke-verified end-to-end against an `@agent-score/commerce`
+ * merchant; entries appear only for rails the vendor actually offers. Vendors override
+ * this in `buildAgentInstructions({compatibleClients: {...}})` to add their own tested
+ * clients or remove entries that don't fit their endpoint.
+ *
+ * Verified state as of the SDK release. The same data is also published as a docs page
+ * for humans (rationale, per-rail commands, why some clients don't fully work, last
+ * verified date) — this default keeps the merchant-side surface in sync.
+ */
+/** Symbolic rail keys agent-facing surfaces use to talk about a rail without spelling out
+ *  network/scheme details. Same keys as `CompatibleClients` map keys. */
+type RailKey = 'tempo_mpp' | 'x402_base' | 'solana_mpp' | 'stripe';
+/** Returns the smoke-verified client list for a set of rail keys. The single source of
+ *  truth for "which CLIs we've verified end-to-end on each rail" — consumed both by the
+ *  402-body builder (`defaultCompatibleClients`) and by discovery surfaces (skill.md,
+ *  llms.txt, etc.). Update here, every surface inherits. */
+declare function compatibleClientsByRails(rails: readonly RailKey[]): CompatibleClients | undefined;
+/**
+ * Build the agent_instructions object for the 402 body. Combines how_to_pay with
+ * recommended tools, warnings, wallet-compatibility note, and timeout.
+ *
+ * Defaults adapt to the rails declared in `howToPay`: only tempo-relevant warnings/tools
+ * appear if `howToPay.tempo` is set, only x402-relevant ones if `x402_base` is set.
+ * Stripe-only merchants get neither rail-specific warning. Vendors override
+ * `warnings`/`recommendedTools` for full control.
+ */
+declare function buildAgentInstructions(input: BuildAgentInstructionsInput): AgentInstructions;
+
+export { type AgentInstructions as A, type BuildAgentInstructionsInput as B, type CompatibleClients as C, type HowToPayBlock as H, type RailKey as R, type BuildHowToPayInput as a, type HowToPayRailEntry as b, type HowToPayStripeEntry as c, buildAgentInstructions as d, buildHowToPay as e, compatibleClientsByRails as f };

package/dist/challenge/index.d.mts

@@ -1,3 +1,5 @@
+import { A as AgentInstructions } from '../agent_instructions-DiMSGkdm.mjs';
+export { B as BuildAgentInstructionsInput, a as BuildHowToPayInput, C as CompatibleClients, H as HowToPayBlock, b as HowToPayRailEntry, c as HowToPayStripeEntry, R as RailKey, d as buildAgentInstructions, e as buildHowToPay, f as compatibleClientsByRails } from '../agent_instructions-DiMSGkdm.mjs';
 import { AgentMemoryHint } from '../core.mjs';
 export { buildAgentMemoryHint } from '../core.mjs';
 import { P as PaymentRequiredHeaderInput } from '../wwwauthenticate-CU1eNvMQ.mjs';
@@ -20,12 +22,21 @@ interface X402MethodEntry {
     decimals: number;
     pay_to: string;
 }
+interface SolanaMppMethodEntry {
+    method: 'solana/charge';
+    network: string;
+    token: string;
+    symbol: string;
+    decimals: number;
+    pay_to: string;
+    fee_payer_key?: string;
+}
 interface StripeMethodEntry {
     method: 'stripe/charge';
     rails: ('card' | 'link' | 'shared_payment_token')[];
     profile_id: string | null;
 }
-type AcceptedMethodEntry = TempoMethodEntry | X402MethodEntry | StripeMethodEntry;
+type AcceptedMethodEntry = TempoMethodEntry | X402MethodEntry | SolanaMppMethodEntry | StripeMethodEntry;
 interface BuildAcceptedMethodsInput {
     tempo?: {
         recipient: string;
@@ -43,12 +54,13 @@ interface BuildAcceptedMethodsInput {
         symbol?: string;
         decimals?: number;
     };
-    x402_solana?: {
+    solana_mpp?: {
         recipient: string;
         network?: string;
         token?: string;
         symbol?: string;
         decimals?: number;
+        feePayerKey?: string;
     };
     stripe?: {
         profileId?: string | null;
@@ -95,115 +107,6 @@ interface IdentityMetadataBlock {
  */
 declare function buildIdentityMetadata(input: IdentityMetadataInput): IdentityMetadataBlock;
 
-interface HowToPayRailEntry {
-    setup?: string[];
-    prerequisite?: string;
-    command: string;
-    alternative_command?: string;
-    what_it_does: string;
-}
-interface HowToPayStripeEntry {
-    prerequisite: string;
-    instructions: string;
-    setup_link_cli?: string[];
-    command_link_cli?: string[];
-    what_it_does_link_cli?: string;
-    note?: string;
-}
-interface HowToPayBlock {
-    tempo?: HowToPayRailEntry;
-    x402_base?: HowToPayRailEntry;
-    x402_solana?: HowToPayRailEntry;
-    stripe?: HowToPayStripeEntry;
-}
-interface BuildHowToPayInput {
-    /** The merchant's full URL (e.g., 'https://agents.merchant.example/api/buy'). */
-    url: string;
-    /** JSON string of the body the agent should retry with — typically the original request body. */
-    retryBodyJson: string;
-    /** Total amount in USD (string or number). Used to compute max-spend defaults and stripe context. */
-    totalUsd: string | number;
-    /** Per-rail config — each is optional. Pass only the rails you support. */
-    rails: {
-        tempo?: {
-            recipient: string;
-            networkName?: string;
-            chainId?: number;
-            recommend?: 'tempo' | 'agentscore-pay' | 'both';
-        };
-        x402_base?: {
-            recipient: string;
-            network?: string;
-        };
-        x402_solana?: {
-            recipient: string;
-            network?: string;
-        };
-        stripe?: {
-            profileId?: string | null;
-            productName?: string;
-        };
-    };
-    /** Placeholder text for the operator token in commands. Defaults to '<your_opc_token>'. */
-    opTokenPlaceholder?: string;
-    /** Override max-spend value used in commands. Default: ceil(totalUsd) + 1. */
-    maxSpend?: string | number;
-}
-/**
- * Build the agent_instructions.how_to_pay block. Generates per-rail setup/command/what_it_does
- * boilerplate so agents see concrete commands per rail in the 402 body. Vendors pass the rails
- * they support; the helper produces the right command for each.
- *
- * Tool recommendations (tempo CLI vs agentscore-pay vs link-cli) are configurable per rail.
- */
-declare function buildHowToPay(input: BuildHowToPayInput): HowToPayBlock;
-
-/** Map of rail key (e.g. 'x402_base', 'tempo_mpp', 'stripe') → list of client identifiers
- *  that have been smoke-verified by the merchant against the protocol shape they emit.
- *  Strings are display labels, not install commands — agents already get install commands
- *  via `how_to_pay.<rail>.setup`. Use these as a "what's known to work" hint. */
-type CompatibleClients = Record<string, string[]>;
-interface BuildAgentInstructionsInput {
-    /** Per-rail commands. Build with `buildHowToPay`. */
-    howToPay: HowToPayBlock;
-    /** Tool recommendations as human-readable strings. Defaults to a sensible set covering tempo + agentscore-pay. */
-    recommendedTools?: string[];
-    /** Wallet-stack compatibility note for the agent. Default: rail-neutral, no specific wallet stack required. */
-    walletCompatibility?: string;
-    /** How long the merchant will wait for payment after the 402. Default 300 (5 minutes). */
-    timeoutSeconds?: number;
-    /** Warnings about common footguns. Defaults include tempo wallet transfer + raw on-chain x402 deposits. */
-    warnings?: string[];
-    /** Recommended rail (e.g., 'tempo', 'x402_base'). Surfaced for agents to default to. */
-    recommended?: string;
-    /** Per-rail list of client names the merchant has verified work end-to-end. Vendors set
-     *  this from their own smoke matrix — defaults to none (avoids vouching for clients the
-     *  merchant has not tested). When omitted, the field is not emitted. */
-    compatibleClients?: CompatibleClients;
-    /** Arbitrary additional fields the vendor wants merged into the agent_instructions object. */
-    extra?: Record<string, unknown>;
-}
-interface AgentInstructions {
-    how_to_pay: HowToPayBlock;
-    recommended_tools: string[];
-    wallet_compatibility: string;
-    timeout_seconds: number;
-    warnings: string[];
-    recommended?: string;
-    compatible_clients?: CompatibleClients;
-    [key: string]: unknown;
-}
-/**
- * Build the agent_instructions object for the 402 body. Combines how_to_pay with
- * recommended tools, warnings, wallet-compatibility note, and timeout.
- *
- * Defaults adapt to the rails declared in `howToPay`: only tempo-relevant warnings/tools
- * appear if `howToPay.tempo` is set, only x402-relevant ones if `x402_base`/`x402_solana`
- * are set. Stripe-only merchants get neither rail-specific warning. Vendors override
- * `warnings`/`recommendedTools` for full control.
- */
-declare function buildAgentInstructions(input: BuildAgentInstructionsInput): AgentInstructions;
-
 /**
  * Helpers for emitting the cross-merchant `agent_memory` hint on merchant 402 responses.
  *
@@ -366,10 +269,9 @@ declare function build402Body(input: Build402BodyInput): Record<string, unknown>
 /**
  * Canonical order-receipt shape returned to agents on the 200 after a successful settlement.
  *
- * Merchants own their order schema, but converging on this shape across every AgentScore-gated
- * merchant (Martin Estate today; Commerce7 / WooCommerce / Shopify plugins tomorrow) means
- * agents can render and post-process orders consistently. Lift this type, fill the fields you
- * care about, and ignore (or extend via `extras`) what you don't.
+ * Merchants own their order schema, but converging on this shape across AgentScore-gated
+ * merchants means agents can render and post-process orders consistently. Lift this type,
+ * fill the fields you care about, and ignore (or extend via `extras`) what you don't.
  *
  * All money fields are dollar-strings (e.g. `"250.00"`). Use `buildPricingBlock` from
  * `@agent-score/commerce/challenge` to compose the pricing fields from cents.
@@ -520,4 +422,4 @@ interface ValidationErrorBody {
  */
 declare function buildValidationError(input: BuildValidationErrorInput): ValidationErrorBody;
 
-export { type AcceptedMethodEntry, type AgentInstructions, AgentMemoryHint, type Build402BodyInput, type BuildAcceptedMethodsInput, type BuildAgentInstructionsInput, type BuildHowToPayInput, type BuildPricingBlockInput, type BuildValidationErrorInput, type CompatibleClients, type FirstEncounterAgentMemoryInput, type HowToPayBlock, type HowToPayRailEntry, type HowToPayStripeEntry, type IdentityMetadataBlock, type IdentityMetadataInput, type IdentityMode, type OrderReceipt, type PricingBlock, type Respond402Input, type SignerMatchResultLike, type StripeMethodEntry, type TempoMethodEntry, type ValidationErrorBody, type X402MethodEntry, build402Body, buildAcceptedMethods, buildAgentInstructions, buildHowToPay, buildIdentityMetadata, buildPricingBlock, buildValidationError, firstEncounterAgentMemory, respond402 };
+export { type AcceptedMethodEntry, AgentInstructions, AgentMemoryHint, type Build402BodyInput, type BuildAcceptedMethodsInput, type BuildPricingBlockInput, type BuildValidationErrorInput, type FirstEncounterAgentMemoryInput, type IdentityMetadataBlock, type IdentityMetadataInput, type IdentityMode, type OrderReceipt, type PricingBlock, type Respond402Input, type SignerMatchResultLike, type SolanaMppMethodEntry, type StripeMethodEntry, type TempoMethodEntry, type ValidationErrorBody, type X402MethodEntry, build402Body, buildAcceptedMethods, buildIdentityMetadata, buildPricingBlock, buildValidationError, firstEncounterAgentMemory, respond402 };