docs(agentic-payments): production patterns for x402 + MPP

[Eras256]

Fresh proposal per Kaan's note closing #14: that PR targeted files removed in the #17 restructure, so it couldn't be rebased. He confirmed the current skills/agentic-payments/SKILL.md doesn't yet cover four of the patterns from the old PR, and invited a fresh PR proposing them individually. This is that — re-verified against a service that's been running x402 and MPP Charge in production, not copied from the old diff.

Landing against x402.md and mpp.md (the detail files SKILL.md routes to), not SKILL.md itself, since it's a decision table and these are implementation patterns.

What changed and why each one still holds up (re-checked today, not assumed from the old PR):

• Multi-route pricing with paymentMiddlewareFromConfig (x402.md) — the seller example in the skill prices a single route. This documents the config-object form for pricing several routes behind one middleware call, with the route-keyed shape and scheme/facilitator wiring spelled out — including an explicit FACILITATOR_URL fallback, since @x402/core's HTTPFacilitatorClient silently falls back to its own generic x402.org facilitator (no Stellar scheme support) when that env var is unset. Matches what's running behind a production endpoint pricing three routes at three different amounts, cited with its first on-chain settlement.

• Recipient resolution: recover at boot, fail closed per request (mpp.md) — two separate failure surfaces. Booting: a server that throws at import time because STELLAR_RECIPIENT is unset breaks CI and any environment without secrets provisioned yet, so that case is recovered instead — including a secret key (S...) landing in the public-key env var by accident, recovered with a loud warning instead of a cryptic downstream throw, and a malformed G... rejected with StrKey.isValidEd25519PublicKey() instead of throwing deep in the SDK. Billing: once the server is up, a paid route with no payment instance behind it now returns 503, never a silent 200 — an earlier draft of this PR had that backwards, caught in review and fixed (also fixed in the real service this doc reflects).

• Optional dual-intent server (mpp.md) — reframed from the old PR, not copied. The old version implied running Charge and Session together in production; that's not accurate today. What is true and worth documenting: each intent gets its own SDK instance, gated independently by its own env vars — including recipient/currency verification, strongly recommended by the library's own types and easy to leave out since both are optional — with route middleware failing closed, never serving unpriced content, when its instance is null.

• /info runtime configuration-status endpoint (mpp.md) — reports which intents were actually initialized (!!chargeInstance), not a static claim that can drift from reality. Deliberately not called a health check: it reports whether each Mppx instance was constructed at startup, not whether the RPC, facilitator, or store backend it depends on are reachable right now.

Verified: pnpm lint:ts, pnpm lint, pnpm sync:skills, and pnpm generate:llms-txt all pass clean against the new content.

Happy to split this into separate PRs per pattern if that's easier to review — bundled them here since the recipient-resolution section is referenced from the pricing section via anchor link, but they don't otherwise depend on each other.

Co-Authored-By: Claude Sonnet 5 noreply@anthropic.com

[kaankacar]

🤖 Automated message from Kaan's Automated Triage Bot.

👀 Picked this up — a review will follow shortly.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds practical documentation for configuring paid routes with x402 and for running MPP Charge/Session together in production without crashing on missing/mis-set secrets.

Changes:

• Document paymentMiddlewareFromConfig for pricing multiple x402 routes with per-route prices.
• Add “Production patterns” guidance for MPP (fail-open recipient resolution, optional dual-intent setup, and an /info discovery endpoint).

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
skills/agentic-payments/x402.md	Adds multi-route pricing example using paymentMiddlewareFromConfig and guidance to fail open when recipient config is missing.
skills/agentic-payments/mpp.md	Adds production-ready patterns and example code for resilient configuration and runtime discovery.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Eras256]

Addressed Copilot's 4 review comments:

• Removed the stray + line-join artifact after paymentMiddleware in x402.md.
• Aligned the pre-existing server env var names in mpp.md (CHANNEL_CONTRACT/COMMITMENT_PUBKEY) to what the service actually reads — MPP_CHANNEL_CONTRACT/MPP_COMMITMENT_KEY, verified against our own running middleware rather than guessed. The new examples had it right; the older table in the same file didn't.
• Added the missing imports to the dual-intent snippet, plus a note on why Channel's server adapter needs an alias (stellarChannel) — both it and Charge's server adapter export their namespace as stellar.

[Eras256]

@kaankacar the merge conflict on this one is resolved — rebased onto current upstream/main, which had independently split mpp.md into a router + restructured discovery section while this branch was adding the production-patterns content. Kept both: the discovery/registry section stays as-is, the production patterns land right before it, and I renamed my own /info subsection (it was also called "Discovery," which would've read as the same feature as the OpenAPI-based one two sections down). gh pr view now reports mergeStateStatus: CLEAN.

Separately, #103 is small and unrelated — a real bug, not a docs addition: 27 of 28 ECOSYSTEM_CARDS entries pointed copyValue at a GitHub blob HTML page instead of raw content, so generate-llms-txt.mjs was writing a rendered-HTML URL straight into llms.txt's "Community Built" section for any agent that fetched it. Already reports clean/mergeable, no dependency on this one.

Whenever you get to either, no rush on my end.

[kaankacar]

🤖 Automated message from Kaan's Automated Triage Bot.

Thanks for this — the fail-open recipient pattern is genuinely good, and the S...-key recovery is the kind of thing docs usually skip.

I checked the new API claims against the published packages and they hold up: the paymentMiddlewareFromConfig signature, PaywallConfig.appName/testnet, the path-keyed createAuthHeaders, the unmatched-route fall-through to next(), and the stellar namespace collision that forces the stellarChannel alias. Tx 3134a51c…7558bc is a successful USDC transfer on mainnet, ledger 63403784. The env var rename is clean — no CHANNEL_CONTRACT or COMMITMENT_PUBKEY is left anywhere in skills/.

Two things before this can land:

1. description sits in the wrong object. All three routes put it inside accepts. PaymentOption has no description field. The resource server reads routeConfig.description, one level up. Nested, it is silently dropped and the 402 response carries an empty description. The single-route example 30 lines above already puts it beside accepts. Please move it.

2. The Nirium mention needs a maintainer. The x402 section points at "Nirium's own mainnet endpoint", and you own Eras256/Nirium. Naming your own project inside an official skill is a listing call I should not make. @kaankacar decides that one. I opened a tracking issue.

Small suggestion: MPP_COMMITMENT_KEY drops the public/secret distinction that COMMITMENT_PUBKEY carried, and the client var is still COMMITMENT_SECRET. MPP_COMMITMENT_PUBKEY would keep the pair readable. Your call.

Copilot's four earlier points all look correctly addressed.

[kaankacar]

🤖 Automated message from Kaan's Automated Triage Bot.

Thanks for the quick turnaround — the fix is exactly right.

I checked 0174883 against the published types. In @x402/express@2.24.0, paymentMiddlewareFromConfig takes a RoutesConfig. RouteConfig declares description?: string. PaymentOption declares only scheme, payTo, price, network, maxTimeoutSeconds and extra. All three routes now put description beside accepts, which matches the single-route example above it. I also grepped skills/ — no other snippet repeats the old shape.

This push changed only those three lines, so the earlier verification still stands.

One item is left, and it is not yours to fix. The x402 section credits Nirium's mainnet endpoint, and you own Eras256/Nirium. Naming your own project in an official skill is a listing call, so @kaankacar decides it. The tracking issue stays open until he does.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 6 comments.

Suppressed comments (3)

skills/agentic-payments/x402.md:168

• Failing open here turns a missing production secret into a payment bypass: every configured paid route can reach its handler without an x402 challenge. Keep process startup resilient, but install a guard that returns 503 for paid routes until the recipient is configured instead of calling next().

**Fail open, not crash, when the recipient isn't configured.** A server
that throws at boot because `STELLAR_RECIPIENT` is unset breaks CI and
any environment that hasn't provisioned secrets yet. See
[Recipient resolution](mpp.md#recipient-resolution-fail-open-not-crash)
in mpp.md for the fuller pattern — it applies here too: wrap middleware
initialization in a check, and fall through to `next()` when the
recipient is missing instead of throwing.

skills/agentic-payments/mpp.md:254

• Non-S... input is returned without validation, so a typo, a C... address, or any arbitrary nonempty value still reaches the SDK and can throw—the failure mode this helper claims to prevent. Validate the public key in this branch and disable MPP on parse failure too.

  return raw;

skills/agentic-payments/mpp.md:288

• The dual-intent guidance repeats the same fail-open payment bypass: a null instance must not let a paid handler run unpriced. Route middleware should return 503 for that intent while leaving unrelated public routes available.

level. Give each mode its own `Mppx` instance, initialize it only when
its full config is present, and let route middleware no-op — not
throw — when the instance for that intent is `null`. Charge's and

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 6 comments.

Suppressed comments (4)

skills/agentic-payments/mpp.md:147

• stellar.channel expects commitmentKey to be a Stellar G... public key (or a Keypair), but this example documents and passes raw 64-character hex. A user following it will reach runtime signature-verification failures. Require the environment variable to contain the encoded G... key, or explicitly convert the hex with StrKey.encodeEd25519PublicKey.

      commitmentKey: process.env.MPP_COMMITMENT_KEY,   // 64-char hex ed25519 public key

skills/agentic-payments/mpp.md:312

• The initializer checks MPP_SECRET_KEY but never passes it to Mppx.create, so the configured verification key is ignored. This also contradicts both complete server examples above, which set secretKey at the Mppx.create level.

const chargeMppx = (RECIPIENT && process.env.MPP_SECRET_KEY)
  ? Mppx.create({ methods: [stellar.charge({ recipient: RECIPIENT, /* ... */ })] })
  : null;

skills/agentic-payments/mpp.md:320

• Session is not independently gated here: it unnecessarily requires RECIPIENT, even though the standalone Session configuration and stellarChannel.channel do not use that value. It also checks MPP_SECRET_KEY without supplying it to Mppx.create. A valid Session-only deployment would therefore remain disabled, while its configured verification key would be ignored.

  RECIPIENT &&
  process.env.MPP_SECRET_KEY
)
  ? Mppx.create({ methods: [stellarChannel.channel({ channel: process.env.MPP_CHANNEL_CONTRACT, /* ... */ })] })

skills/agentic-payments/x402.md:168

• Falling through to next() when a priced route's recipient is missing serves the protected response without payment. That is a billing bypass caused by configuration failure; keep startup resilient, but fail closed with a non-200 response for matched paid routes.

initialization in a check, and fall through to `next()` when the
recipient is missing instead of throwing.

[kaankacar]

🤖 Automated message from Kaan's Automated Triage Bot.

Thanks for this — flipping to fail closed is the right call, and the reasoning you wrote into the code comment is clearer than most production code gets. I checked 23c7988: the 503 path, the /info reframe as configuration state, and both new eval scenarios. They match the schema of 01–03 and satisfy the evals/ rule in README.md:117. site-ci is green at this head.

Three things I would like you to look at.

1. x402.md still teaches fail open. The commit updated the anchor on line 165. The prose around it did not change. Line 162 still reads "Fail open, not crash", and line 167 still says to "fall through to next() when the recipient is missing". That link now points at a section that calls exactly this a silent payment bypass. The two files give opposite instructions. Please apply the same fail-closed rewrite here.

2. Session is gated on a variable the file never lists. In the dual-intent snippet, sessionMppx requires RECIPIENT. The Session env list on line 216 names only MPP_CHANNEL_CONTRACT, MPP_COMMITMENT_KEY, MPP_SECRET_KEY and FEE_PAYER_SECRET. The prose then says Session works "once its four env vars are set". The code needs five values.

Copilot asked you to drop the check. I disagree. channel() in @stellar/mpp@0.7.1 takes an optional recipient, and its type doc calls it strongly recommended, because it rejects a channel whose payout address differs. Keep the gate. Please pass recipient: RECIPIENT in the snippet, and add STELLAR_RECIPIENT to the Session env list.

3. commitmentKey is a G... key, not hex. Line 147 comments the value as "64-char hex ed25519 public key". Channel.js runs Keypair.fromPublicKey() on a string commitmentKey, and the SDK example shows commitmentKey: 'GABC...'. Hex throws there. Your own client snippet on line 178 already converts the hex seed with fromRawEd25519Seed. This one predates your PR, but your commit touches that line, so it is worth fixing here.

Smaller point, your call: resolveRecipient() returns raw unchecked. A typo'd G... key still reaches the SDK and throws, which is the failure the helper says it prevents.

The Nirium item is unchanged. The x402 section credits Nirium's mainnet endpoint, and you own Eras256/Nirium. That listing call is @kaankacar's. The tracking issue stays open until he decides.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

Suppressed comments (3)

skills/agentic-payments/mpp.md:273

• Non-S... values are returned without validation. stellar.charge() accepts the string during construction, so a malformed recipient leaves chargeMppx truthy and /info reports Charge enabled instead of disabling it and serving the intended 503. Validate the required G... public key before returning it.

  return raw;

skills/agentic-payments/mpp.md:297

• When chargeMppx exists, this branch neither invokes the payment handler nor calls next() or sends a response, so every correctly configured paid request hangs. Delegate to the instance's Express handler here.

    // ... normal charge flow

skills/agentic-payments/mpp.md:336

• Checking only that MPP_COMMITMENT_KEY is nonempty does not make optional Session initialization fail-safe: malformed/non-64-character hex throws during key encoding or channel construction, crashing the whole Charge server before sessionMppx can become null. Catch initialization failures and keep only Session disabled as the section promises.

const sessionMppx = (
  process.env.MPP_CHANNEL_CONTRACT &&
  process.env.MPP_COMMITMENT_KEY &&
  RECIPIENT &&
  process.env.MPP_SECRET_KEY

[Eras256]

@kaankacar all four points addressed, across two commits (23b0968, then 2bde1e9 for the smaller one):

1. x402.md rewritten. The "Fail open, not crash" heading and prose are gone — it now says the same thing mpp.md's linked section says: never throw at boot, but return 503 (not next()) per request once the payment instance is null. The anchor and the text it points at agree now.

2. STELLAR_RECIPIENT added to the Session env var list, and recipient: RECIPIENT wired explicitly into both the Session server example and the dual-intent snippet's channel() call — matching what you flagged: it's optional in the type but there for a real reason (rejecting a channel whose payout address doesn't match). Also added currency alongside it, same rationale, same type doc.

3. commitmentKey hex bug fixed in the pre-existing Session-mode example (the one that predates this PR, line 147 in the old numbering) — same StrKey.encodeEd25519PublicKey() re-encoding already used elsewhere, plus filled in the dual-intent snippet's previously-elided commitmentKey. Also closed a gap that made this harder to catch: the testnet runbook generated the client's seed but never showed how the server's hex public key actually gets derived from it — added that command and labeled which env var belongs to which side.

4. resolveRecipient() now validates format — StrKey.isValidEd25519PublicKey() as the last check before returning, so a typo'd G... fails there with context instead of throwing deep inside Mppx.create(). Took the "your call" — added it, since it's cheap and consistent with the fail-loud pattern the rest of this function already uses.

All four are also fixed in the real service this doc is drawn from, not just here — packages/agent/src/middleware/mpp.ts, private repo, same session (the fail-closed billing fix plus the commitmentKey/recipient/validation follow-up). Point 1's fix extends to the actual mainnet-settling x402 route too, which had the identical fail-open bug — found while fixing the MPP one, confirmed live, fixed there as well.

Assistance disclosure: Claude Sonnet 5 was used for the review, the fixes, and this comment. Verified independently before each one landed — the real .d.ts types for commitmentKey/recipient/currency, a hand-run round-trip of the hex→G-address conversion, and the private service's actual source — not assumed from the review alone.

[kaankacar]

🤖 Automated message from Kaan's Automated Triage Bot.

Thanks — all three items are fixed, and the runbook derivation step you added on your own was a good call.

I checked 23b0968 against the published types:

• x402.md now teaches recover at boot, 503 per request. No "fail open" text is left anywhere under skills/.
• channel.Parameters in @stellar/mpp@0.7.1 declares recipient? and currency?. Its own doc comment says "Strongly recommended; when omitted ... a startup warning is logged". Your code comment matches it.
• commitmentKey is typed string | Keypair and documented as a G... key. StrKey.encodeEd25519PublicKey(data: Buffer) is the correct conversion.
• CBIELTK6…HMXQDAMA is the SAC for USDC-GBBD47IF…LFLA5 on testnet. It agrees with cctp.md and SKILL.md.
• Keypair.fromRawEd25519Seed(Buffer) and rawPublicKey(): Buffer both exist, and process.argv[1] is the first argument after node -e.
• site-ci is green at this head.

One small item is left. Line 366 still says Session works "once its four env vars are set". The Session env list on line 234 now names five. FEE_PAYER_SECRET is a real fifth one: feePayer is required to handle close actions. Please make the sentence and the list agree.

Copilot's new secretKey point is not a defect, so I did not pass it on. Mppx.create reads MPP_SECRET_KEY from the environment and throws when neither the option nor the variable is set. Your gate is right, and omitting secretKey from the short snippet is fine.

The Nirium item is unchanged. The x402 section credits Nirium's mainnet endpoint, and you own Eras256/Nirium. That listing call is @kaankacar's, and the tracking issue stays open until he decides.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

Suppressed comments (4)

skills/agentic-payments/mpp.md:306

• On the configured path this middleware neither invokes chargeMppx.charge(...) nor calls next(), so every request hangs. Delegate to the per-route MPP handler here.

    // ... normal charge flow

skills/agentic-payments/mpp.md:356

• A non-empty but malformed MPP_COMMITMENT_KEY passes the enablement guard, then Buffer.from/encodeEd25519PublicKey can throw during module initialization. That defeats this section's recover-at-boot pattern. Validate exactly 64 hex characters and catch conversion/adapter initialization failures, leaving sessionMppx null so its middleware can return 503.

          commitmentKey: StrKey.encodeEd25519PublicKey(
            Buffer.from(process.env.MPP_COMMITMENT_KEY, "hex")
          ),

skills/agentic-payments/mpp.md:367

• This section promises fail-closed middleware for each intent, but only exposes Session's status; it never demonstrates a Session route wrapper. Add a mppSessionMiddleware factory that returns 503 when sessionMppx is null and otherwise returns sessionMppx.channel({ amount, description }), so readers do not accidentally mount an unprotected fallback route.

export const isSessionEnabled = () => !!sessionMppx;

skills/agentic-payments/x402.md:152

• The example still constructs the middleware unconditionally with an undefined payTo, despite the added guidance and scenario requiring initialization to be gated. Add a guard around middleware creation and a fallback that returns 503 only for requests matching PAID_ROUTES; unmatched routes must still call next().

  paymentMiddlewareFromConfig(
    PAID_ROUTES,
    facilitator,
    [{ network: NETWORK, server: new ExactStellarScheme() }],
    { appName: "My API", testnet: NETWORK === "stellar:testnet" },

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

Suppressed comments (2)

Previously missed (2) — in code that hasn't changed since the last review.

skills/agentic-payments/x402.md:212

• The fallback is also selected when STELLAR_RECIPIENT is present but malformed, so both messages incorrectly say it is “not set.” Use “missing or invalid” for the server warning and a configuration-neutral 503 response for callers.

  console.warn("STELLAR_RECIPIENT not set — paid routes return 503 instead of pricing");
  x402Middleware = (req, res) => {
    res.status(503).json({ error: "x402 payment middleware unavailable — STELLAR_RECIPIENT not set" });

skills/agentic-payments/x402.md:140

• This normalization removes quotes anywhere in the value, not just surrounding quotes. A malformed key such as GBBD...WK"7P... is therefore converted into a valid, different input before StrKey validates it, contradicting the fail-closed behavior described below. Strip only matching outer quotes so embedded or unmatched quotes remain invalid.

  let raw = (process.env.STELLAR_RECIPIENT || "").trim().replace(/['"]/g, "");

[kaankacar]

🤖 Automated message from Kaan's Automated Triage Bot.

Thanks — the store comment points at the right place now. I followed it: mpp.md:51 and mpp.md:174 both show store: Store.memory() in full. site-ci is green at c4e5010, and the diff is still the same four files.

Copilot reviewed this head. One of its points is real.

The Session gate accepts any MPP_CHANNEL_CONTRACT value. The gate at mpp.md:399 tests presence only. I read channel() in @stellar/mpp@0.7.1: it validates store at Channel.js:72-77 and nothing else. channelAddress goes into store keys, and only reaches new Contract(channelAddress) at Channel.js:347 and :410. That throws Invalid contract ID at request time.

So a typo'd C... builds sessionMppx, /info reports Session enabled: true, and the first paid request fails deep in the SDK. That is the failure your recipient section exists to prevent.

StrKey.isValidContract() returns a boolean and never throws. It fits the gate beside your commitmentKey and feePayerSigner checks. Eval 05 is worth naming it in the same commit.

Small: two warnings say "not set" when the value can also be invalid.

• x402.md:212 — resolveRecipient() returns "" for a malformed G... too, and it logs its own reason one line earlier. The warning then contradicts it.
• mpp.md:300 — same wording, same cause.

"missing or invalid" fixes both.

I did not pass on Copilot's quote-stripping point (mpp.md:267, x402.md:140). It says .replace(/['"]/g, "") can repair a corrupt key into a valid one. The result still has to pass StrKey's base32 decode and CRC16 checksum. So it can only recover the key the operator meant; anything else returns "" and fails closed.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

Suppressed comments (8)

Previously missed (3) — in code that hasn't changed since the last review.

skills/agentic-payments/mpp.md:607

• This new client/server distinction conflicts with the later “Session: wrong commitment key format” guidance, which still says without qualification that the commitment key is the raw seed. A server operator following that later fix could put COMMITMENT_SECRET into MPP_COMMITMENT_KEY; the server would encode the seed bytes as a different public key, causing signature failures and exposing the client secret. Update that pitfall to distinguish both values.

6. Derive the corresponding public key from that same seed — this is
   `MPP_COMMITMENT_KEY`, what the **server** holds, stored as hex the same
   way (the server code above re-encodes it to a G... address at startup).
   Export the seed from step 5 first, then read it from the environment

evals/scenarios/agentic-payments/05-production-hardening.json:18

• This assertion's rationale does not match the documented implementation: Keypair.fromSecret() is called during the standalone validation block before the Mppx.create() branch, not inside that call. Keep the eval focused on the observable requirement so the judge does not require an incorrect code structure.

    "Validates FEE_PAYER_SECRET with StrKey.isValidEd25519SecretSeed() before calling Keypair.fromSecret() on it, same pattern as commitmentKey's hex regex — Keypair.fromSecret() throws synchronously on a malformed secret, and since that call sits inside the Mppx.create() branch, an unvalidated bad key throws at import time and crashes chargeMppx along with it, not just Session",

skills/agentic-payments/x402.md:140

• This removes quote characters anywhere in the credential rather than only stripping surrounding quotes. An otherwise malformed value containing an embedded quote can therefore be transformed into a valid public or secret key and bypass the intended validation. Strip only a matching outer quote pair so unexpected internal characters fail closed.

  let raw = (process.env.STELLAR_RECIPIENT || "").trim().replace(/['"]/g, "");

skills/agentic-payments/x402.md:53

• The || change avoids the library's generic fallback, but this hard-coded testnet URL still breaks the documented mainnet configuration when STELLAR_NETWORK=stellar:pubnet and FACILITATOR_URL is empty: pubnet requirements are sent to the OZ testnet facilitator. Derive the OZ default from NETWORK so both supported networks have a valid fallback.

  url: process.env.FACILITATOR_URL || "https://channels.openzeppelin.com/x402/testnet",

skills/agentic-payments/x402.md:126

• This production pattern has the same mainnet failure as the seller example: with NETWORK set to stellar:pubnet and an empty/unset URL, it silently chooses the OZ testnet endpoint. Make the explicit fallback network-aware; otherwise the change only replaces one unsupported facilitator with another for mainnet.

  url: process.env.FACILITATOR_URL || "https://channels.openzeppelin.com/x402/testnet",

skills/agentic-payments/mpp.md:267

• This removes every quote character, although the pattern is described as stripping surrounding quotes. That can turn an invalid value with an embedded quote into a valid key before StrKey sees it. Limit normalization to a matching outer quote pair so malformed credentials are rejected.

  let raw = (process.env.STELLAR_RECIPIENT || "").trim().replace(/['"]/g, "");

skills/agentic-payments/mpp.md:298

• Checking only for presence does not satisfy the promised boot-safe behavior. Mppx.create() calls SecretKey.assert(), which throws synchronously when MPP_SECRET_KEY is under 32 bytes, so a malformed value still crashes the process instead of leaving chargeMppx null and returning 503. Validate the byte length before construction (or catch construction errors).

if (RECIPIENT && process.env.MPP_SECRET_KEY) {
  chargeMppx = Mppx.create({ /* ... */ });

skills/agentic-payments/mpp.md:355

• The dual-intent example also gates on non-emptiness only. A short MPP_SECRET_KEY makes the first Mppx.create() throw synchronously, so neither intent reaches the fail-closed state and the process exits. Validate the key's minimum 32-byte length once and use that result in both the Charge and Session gates, or catch each construction independently.

const chargeMppx = (RECIPIENT && process.env.MPP_SECRET_KEY)
  ? Mppx.create({ methods: [stellar.charge({ recipient: RECIPIENT, /* ... */ })] })

[kaankacar]

🤖 Automated message from Kaan's Automated Triage Bot.

Thanks — the StrKey.isValidContract() gate is the right shape, and I checked it: @stellar/stellar-base@15.0.0 declares isValidContract(address: string): boolean, and its isValid helper catches the decode, so it never throws. Both warnings now say "missing or invalid", which matches resolveRecipient(). site-ci is green at c555866.

Copilot generated no new comments. Its suppressed block carries two real points.

1. The commitment-key pitfall still tells the server to hold the seed. Line 627 says "the commitment key is a raw ed25519 seed as a 64-char hex string". Your new runbook splits that into two values: COMMITMENT_SECRET (the seed, client only) and MPP_COMMITMENT_KEY (the derived public key, server). A server operator who reads that pitfall puts the seed in MPP_COMMITMENT_KEY. Your own code then encodes the seed bytes as a G-address, so every commitment signature fails to verify, and the client secret sits in the server's environment. Line 627 is the only place left in skills/ with the old wording. Could you name both values there?

2. The install line does not pin mppx, and that decides your no-throw promise. npm install … @stellar/mpp mppx … (line 25) resolves mppx to 0.9.1 today. @stellar/mpp@0.7.1 declares peerDependencies.mppx: ^0.6.29, so npm answers ERESOLVE. It matters here:

• mppx@0.6.31 Mppx.create throws only on a missing secret key.
• mppx@0.9.1 adds SecretKey.assert(secretKey) right after that guard.

So "no intent's setup may throw at import time" holds on 0.6.x and breaks on 0.9.x. Pinning mppx@^0.6.31 on line 25 keeps it true. The ERESOLVE pitfall at line 623 is the second place to name the pin.

Small: eval 05's feePayerSigner line still says the Keypair.fromSecret() call "sits inside the Mppx.create() branch". d79ebb5 moved it out into the validation block above.

I did not pass on two of Copilot's points:

• The short MPP_SECRET_KEY throw. SecretKey.assert is mppx 0.9.x only, so your presence check is correct at the pinned version. See item 2.
• The network-aware facilitator default. The env-var list and the mainnet switch section both name the pubnet URL, so a reader who follows them sets FACILITATOR_URL. A nicer default, not a defect.

[Eras256]

Fixed all three, pushed at b998c8e.

1. Commitment-key wording (line 627, now split): COMMITMENT_SECRET (client, the raw seed) and MPP_COMMITMENT_KEY (server, the derived public key) are now named separately, matching the runbook and server code — the pitfall block was the one place still describing them as one value.
2. mppx pin: the install line now pins mppx@^0.6.31, and the ERESOLVE pitfall names both @stellar/mpp@0.7.1's peerDependencies.mppx: ^0.6.29 and the pin. Confirmed independently via npm view: mppx's latest tag is 0.9.2 today, so an unpinned install would have resolved outside that peer range.
3. Eval 05's stale line: updated to match the current code — the Keypair.fromSecret() call isn't inside the Mppx.create() branch anymore since d79ebb5, so the eval no longer says it is.

Agreed on both points you didn't pass on — no change needed there.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

Suppressed comments (3)

skills/agentic-payments/mpp.md:300

• This gate accepts any nonempty MPP_SECRET_KEY, including a trivially guessable value such as x. In this pinned mppx release there is no minimum-length assertion; the newer guard requires at least 32 bytes because this key authenticates HMAC-bound challenge IDs. Validate the byte length here and leave chargeMppx null on failure so startup remains recoverable without weakening payment verification.

if (RECIPIENT && process.env.MPP_SECRET_KEY) {
  chargeMppx = Mppx.create({ /* ... */ });
} else {
  console.warn("MPP_SECRET_KEY missing, or STELLAR_RECIPIENT missing or invalid — MPP charge middleware disabled");

skills/agentic-payments/mpp.md:356

• The dual-intent Charge gate also treats a one-character MPP_SECRET_KEY as valid, bypassing the 32-byte minimum added by newer mppx releases for HMAC-bound challenge IDs. Apply the same explicit byte-length validation here before constructing the instance.

const chargeMppx = (RECIPIENT && process.env.MPP_SECRET_KEY)
  ? Mppx.create({ methods: [stellar.charge({ recipient: RECIPIENT, /* ... */ })] })
  : null;

skills/agentic-payments/mpp.md:419

• The Session gate repeats the weak-secret issue: any nonempty MPP_SECRET_KEY enables sessionMppx under mppx 0.6.31. Require at least 32 UTF-8 bytes here as well; otherwise a misconfigured short HMAC key is reported as an enabled production intent.

  process.env.MPP_SECRET_KEY &&
  feePayerSigner

[kaankacar]

🤖 Automated message from Kaan's Automated Triage Bot.

Thanks — all three items from the last round are fixed, and I checked each one.

• @stellar/mpp@0.7.1 declares peerDependencies.mppx: ^0.6.29, and mppx latest is 0.9.2. So ^0.6.31 is the right pin, and 0.6.31 is the newest 0.6.x.
• mppx@0.6.31 throws only on a falsy secret key. mppx@0.9.2 calls SecretKey.assert(secretKey) at Mppx.js:59. Your note is accurate.
• The commitment-key pitfall now matches the runbook. Keypair.fromRawEd25519Seed(seed).rawPublicKey() gives the public key, and skills/ holds no other copy of the old wording.
• Eval 05's feePayerSigner line matches the code. site-ci is green at b998c8e.

Two items are left. Copilot raised both, and both are real.

1. mpp.md:574 still installs unpinned. npm install @stellar/mpp mppx @stellar/stellar-sdk resolves mppx@0.9.2 and @stellar/stellar-sdk@17.0.1 today. Both sit outside @stellar/mpp@0.7.1's peer ranges. So that command fails with the exact ERESOLVE your new pitfall describes. Please pin it the way line 25 does. Copilot named SDK 16; latest is 17.0.1.

2. The doc pins below the guard, and never names the rule. Line 29 says mppx@0.9.x adds SecretKey.assert(). That assert needs 32 UTF-8 bytes:

const minimumBytes = 32;
// "Secret key must be at least 32 bytes. Generate one with `openssl rand -base64 32`"

mppx@0.6.31 has no such check. So a one-character MPP_SECRET_KEY is accepted, and it signs every HMAC challenge. Could you name the 32-byte minimum and openssl rand -base64 32 where the env var appears? A length check in the gates is optional, but it would match your commitmentKey and feePayerSigner pattern.

Small: /info reports process.env.MPP_CHANNEL_CONTRACT at line 503, not the validated channelAddress. A rejected value still shows there, beside enabled: false.

Copilot's other two comments repeat the MPP_SECRET_KEY point at lines 356 and 419, so item 2 covers all three.

[Eras256]

Both fixed, plus the small one, pushed at 3d464a6.

1. mpp.md:574 pinned: npm install @stellar/mpp mppx@^0.6.31 @stellar/stellar-sdk@^15, with the same peer-range explanation as the Charge mode install. Re-checked live: @stellar/stellar-sdk's latest tag is 17.0.1 today (not 16 — matches what you corrected from Copilot), still outside @stellar/mpp@0.7.1's ^15.1.0 peer requirement.
2. 32-byte minimum named: added where MPP_SECRET_KEY first appears (Charge mode), with openssl rand -base64 32, and cross-referenced at Session's env var list. Left the gates as truthy-only, per your note that a length check there is optional.
3. /info fixed: now reports channelAddress (the validated value, undefined on a rejected MPP_CHANNEL_CONTRACT) instead of the raw env var.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

Suppressed comments (2)

skills/agentic-payments/mpp.md:107

• The 32-byte requirement is only documented, not enforced by the examples: the production gates below merely test process.env.MPP_SECRET_KEY for truthiness, and the pinned mppx@0.6.31 only rejects a missing key. Consequently, a one-byte value still initializes both intents and weakens HMAC challenge authentication. Add one shared byte-length validator and pass its validated value to every Mppx.create()/initialization gate.

> **`MPP_SECRET_KEY` must be at least 32 bytes.** `mppx@0.6.31`'s `Mppx.create()` only checks it's present, not its length — a one-character value is accepted and then signs every HMAC challenge. Generate one with `openssl rand -base64 32`. (`mppx@0.9.x` adds this check itself via `SecretKey.assert()`; pinned to `0.6.31` per the install note above, this doc's own examples don't get it for free.)

skills/agentic-payments/mpp.md:520

• This overstates what /info guarantees. The preceding paragraph explicitly says it does not check RPC or store reachability, so enabled: true identifies an initialized intent, not necessarily a working one. Reword this to avoid encouraging clients to treat configuration status as health.

An agent that reads this before its first request can pick a working
intent instead of finding out from a 503 that Session was never
configured.

[kaankacar]

🤖 Automated message from Kaan's Automated Triage Bot.

Thanks — all three items are fixed. I checked each one against the packages.

• Line 581 now matches line 25. ^0.6.31 resolves to 0.6.31, the newest 0.6.x. ^15 resolves to 15.1.0, which meets @stellar/mpp@0.7.1's ^15.1.0 peer range.
• The 32-byte note is exact. mppx@0.6.31's create() throws only on a falsy key, and Challenge.js uses that key as the HMAC-SHA256 key for every challenge ID. mppx@0.9.2's SecretKey.assert() sets minimumBytes = 32 and names openssl rand -base64 32.
• /info now reads channelAddress, so a rejected MPP_CHANNEL_CONTRACT shows null.

I also swept every npm install line in skills/. Only these two carried the peer-range problem, and both are pinned now. The x402 lines are safe: @x402/stellar keeps @stellar/stellar-sdk as a normal dependency, not a peer. All four StrKey/Keypair calls in the new snippets exist in SDK 15.1.0. site-ci is green at 3d464a6.

One small item is left, then I can merge.

mpp.md:518 says "pick a working intent". The paragraph just above says the opposite: /info reports only whether each Mppx instance was constructed at startup, not live health. /info lets a client rule out an intent that will 503. It cannot promise the RPC or store behind an enabled intent is reachable. Could you change "working" to "configured"? The rest of the sentence already says exactly that.

Copilot asked again for a byte-length check inside the gates. I still read that as optional, and your note now names the rule, so it does not block.

[Eras256]

Fixed, pushed at 1cbcf79 — "working" → "configured", matching the sentence right above it.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

Suppressed comments (1)

skills/agentic-payments/mpp.md:107

• The examples below still gate Mppx.create() only on whether MPP_SECRET_KEY is present. Because the pinned mppx@0.6.31 performs no length validation, a one-character or whitespace-only value initializes both intents and /info reports them enabled despite this stated minimum. Please validate the UTF-8 byte length once and use that validated result in every Charge/Session construction gate (with an explicit warning for an undersized key).

> **`MPP_SECRET_KEY` must be at least 32 bytes.** `mppx@0.6.31`'s `Mppx.create()` only checks it's present, not its length — a one-character value is accepted and then signs every HMAC challenge. Generate one with `openssl rand -base64 32`. (`mppx@0.9.x` adds this check itself via `SecretKey.assert()`; pinned to `0.6.31` per the install note above, this doc's own examples don't get it for free.)

[kaankacar]

🤖 Automated message from Kaan's Automated Triage Bot.

Thanks — that was the last item, and it clears the PR.

I checked 1cbcf79. The sentence now reads "pick a configured intent", which agrees with the paragraph above it: /info reports what was constructed at startup, not live health. The push changed only that word, so the earlier verification still stands.

At this head I also confirmed:

• The diff is still the same four files.
• site-ci is green.
• No product name and no transaction link is left under skills/. Kaan's listing decision holds.
• Both npm install lines pin mppx@^0.6.31 and @stellar/stellar-sdk@^15.
• The Recipient resolution anchor from x402.md resolves to the real heading in mpp.md.

Copilot reviewed this head and generated no new comments. Its one suppressed point asks again for a byte-length gate on MPP_SECRET_KEY. The doc names the 32-byte minimum and openssl rand -base64 32 where the variable appears, so I still read that as optional, not a blocker.

Thank you for the many careful rounds on this one. Merging.

[kaankacar]

Verified at 1cbcf79. See the review comment above.

[Eras256]

Thanks for the thorough review across all these rounds, @kaankacar — genuinely made the doc better each time. Appreciate the patience.