docs(cardano): make exact scheme vendor-neutral, add masumi extension

[adacapo21]

Status

Draft. Opened for review by the Cardano Foundation before any upstream proposal to x402-foundation/x402.

Review feedback addressed (2026-04-24):

• Supplementary docs in docs/ have been removed from the PR tree (commit d8f1d6d4). Their content is preserved in this PR description below.
• A full end-to-end example of the cardano-masumi extension has been added to specs/extensions/cardano_masumi.md (commit adab35d6).

Summary

Revise the Cardano exact payment scheme so that its core compliance surface is facilitator-neutral, vendor-neutral, and implementation-agnostic. Move Masumi-specific semantics out of the core scheme and into a new cardano-masumi extension that follows the existing x402 v2 extensions architecture.

Masumi support is preserved in full — only its placement in the specification changes.

Motivation

The Cardano scheme merged upstream in x402-foundation/x402#1093 embeds Masumi-specific semantics directly into the core scheme:

• assetTransferMethod: "default" | "masumi" | "script" — a core enum that names a specific third-party protocol as a peer of generic Cardano primitives.
• Masumi-specific fields inlined into PaymentRequirements.extra (sellerVkey, paymentType: "Web3CardanoV1", blockchainIdentifier, payByTime, submitResultTime, unlockTime, externalDisputeUnlockTime, agentIdentifier, inputHash, identifierFromPurchaser).

This couples the Cardano x402 core to one ecosystem implementation. Every Cardano facilitator has to reason about Masumi-specific fields even when it does not support Masumi; additional Cardano agent-payment or escrow protocols would need either their own enum value or second-class status; future Masumi evolution forces revisions of a core scheme document.

The x402 v2 spec already defines the canonical mechanism for this: the extensions object in PaymentRequired, PaymentPayload, and SettlementResponse. Every other chain in the repo (eip155, svm, sui, aptos, algorand, stellar, hedera) keeps its core scheme focused on ledger primitives and uses extensions for cross-cutting or ecosystem-specific behaviour. Cardano should follow the same pattern.

Rationale — why this is a standards-boundary correction, not a rejection of Masumi

Core schemes should describe MUST-support behaviour only

An x402 scheme document defines the minimum surface every conformant implementation must understand to interoperate. When vendor-specific semantics leak into that surface:

• Every implementation pays the cost. A facilitator that never intends to handle Masumi still has to parse, schema-validate, and ignore Masumi-specific fields because they live in the core extra object. This inflates the conformance surface.
• Naming a vendor in an enum privileges it. assetTransferMethod: "masumi" is qualitatively different from "default" or "script": it treats one ecosystem project as a peer of generic Cardano primitives. Future ecosystem projects would either negotiate their own enum value (turning the standard into a vendor registry) or accept second-class status.
• Standards boundaries calcify. Once a vendor field is in core, removing it is a breaking change. Moving it to an extension while the scheme is young and adoption is still small is much cheaper than doing so later.

Script-parameterized payments belong in core; off-chain semantics do not

Plutus scripts with applied parameters are a generic Cardano primitive, not a vendor feature. Any Cardano-native payment flow — Masumi's escrow, an alternative agent-payment protocol, a milestone-release protocol, a subscription escrow, a vault — ultimately expresses itself as a payment to a script address with some datum and redeemer. The core scheme needs to describe "pay to a script address, with the client able to reconstruct that address from the declared script and parameters." It does not need to describe the off-chain semantics attached to any particular script.

Interoperability payoffs

• Multi-facilitator. A facilitator can claim conformance with the Cardano exact scheme without committing to any specific agent-payment protocol.
• Multi-ecosystem. Other Cardano agent-payment or escrow protocols can publish extensions alongside cardano-masumi without a spec change.
• Cleaner client contracts. A client library targeting the Cardano exact scheme has a small, stable contract: address-to-address and script-parameterized payments. Ecosystem-specific stacks are opt-in via extension libraries.
• Predictable evolution. When Masumi evolves (a Web3CardanoV2, new windows, new identifiers), the core Cardano scheme does not need to version. The extension versions independently.

This is not anti-Masumi

Masumi is one of the earliest substantial Cardano agent-payment deployments. The proposal preserves Masumi on Cardano x402 in full — via a named, versioned extension — and gives Masumi a cleaner place to evolve on its own cadence, decoupled from the core scheme's cadence.

What changed

Modified

• specs/schemes/exact/scheme_exact_cardano.md — rewritten so the core describes only generic Cardano primitives:
  • Address-to-address payments (ADA via reserved "lovelace" asset, or Cardano native tokens).
  • Script-parameterized payments (generic Plutus scripts with applied parameters).
  • Facilitator verification rules (network, recipient, amount, asset, nonce/replay, TTL).
  • Explicit statement that ecosystem-specific semantics MUST travel via the x402 v2 extensions model.
  • assetTransferMethod enum removed; "default" and "script" are now described via field-shape rather than vendor-adjacent enum values.
  • Corrected the mermaid submission notes and step 6 wording: the node accepts a submitted tx into its mempool synchronously; block inclusion is asynchronous and probabilistic. The prior wording ("included in mempool or block") contradicted the spec's own finality warning.

Added

• specs/extensions/cardano_masumi.md — new extension carrying Masumi-specific fields under extensions["cardano-masumi"].info, with schema, field semantics, client/server/facilitator responsibilities, explicit core-compatibility rules so a non-Masumi stack can still verify the underlying script-parameterized payment, and a full end-to-end worked example of the flow.

What moved from core to extension

Element	Was (core extra)	Now (extension)
assetTransferMethod: "masumi"	core enum value	removed; replaced by extension presence
sellerVkey	core extra	extensions["cardano-masumi"].info.sellerVkey
paymentType: "Web3CardanoV1"	core extra	extensions["cardano-masumi"].info.paymentType
blockchainIdentifier	core extra	extensions["cardano-masumi"].info.blockchainIdentifier
agentIdentifier	core extra	extensions["cardano-masumi"].info.agentIdentifier
identifierFromPurchaser	core extra	extensions["cardano-masumi"].info.identifierFromPurchaser
inputHash	core extra	extensions["cardano-masumi"].info.inputHash
payByTime / submitResultTime / unlockTime / externalDisputeUnlockTime	core extra	extensions["cardano-masumi"].info.*

What stays in core

• Network identifiers cardano:mainnet / cardano:preprod / cardano:preview.
• asset format ${policyId}.${assetNameHex}, plus reserved "lovelace" for native ADA.
• payTo (regular or script address).
• maxTimeoutSeconds, TTL checks.
• payload.transaction (Base64 CBOR) and payload.nonce (UTXO reference for replay prevention).
• Facilitator verification rules.
• Script-parameterized payments (extra.scriptHash, extra.script, extra.parameters) as a generic Cardano primitive.

Commits

Four commits on top of cardano-foundation/x402:main, two files changed:

• 84353d56 — docs(cardano): make exact scheme vendor-neutral, add masumi extension
• caf790b8 — fix(cardano): correct mempool-vs-block-inclusion wording in exact scheme
• d8f1d6d4 — docs(cardano): drop supplementary rationale docs from PR tree (per review)
• adab35d6 — docs(cardano): add end-to-end masumi extension example (per review)

An earlier iteration of this branch also contained a merge of x402-foundation/x402:main, which inflated the diff with 44 unrelated upstream commits; that merge was dropped from the proposal so the diff isolates the Cardano-neutrality changes. Bringing cardano-foundation/x402:main up to date with upstream is tracked separately and can be handled as a plain sync PR.

Review path

1. Cardano Foundation review (Fabian) + community discussion in the open office hours.
2. Any required revisions on this branch.
3. Upstream proposal to x402-foundation/x402.

Backward compatibility

• On-chain transaction shape is unchanged.
• Masumi integrators move fields from extra to extensions["cardano-masumi"].info; this is a mechanical client/server adjustment.
• Facilitators that only implement the core scheme continue to verify payments correctly (they just don't enforce Masumi-specific off-chain invariants, which they were never in a position to enforce anyway).

Non-goals

• No change to Masumi's on-chain protocol or off-chain rules.
• No change to any chain, scheme, or facilitator implementation outside the spec.
• No position on which Cardano agent-payment protocol implementations should be preferred.

Open questions (non-blocking)

• Extension naming: cardano-masumi vs. masumi vs. cardano.masumi. Worth aligning with any emerging convention.
• "lovelace" reserved value for native ADA: should be sanity-checked against existing Cardano SDK idioms in the repo.
• Whether a Cardano-flavoured analog of the offer-receipt extension would be useful later (CIP-8 / CIP-30 signing formats are not in that extension's current format set).

[fabianbormann]

I appreciate the more exact wording. Removing the docs folder and getting consensus about the extensions in the open office hour would be required to proceed with this as is, otherwise if we come to the conclusion to keep masumi as part of the core, let's keep the wording changes in any case as they really make a lot of sense.

[fabianbormann]

Thank you for adding the context here. I would suggest to remove the docs folder from the PR as it would otherwise end up in the x402 foundation once merged and this is probably not the intention. If the text stays as part of the PR description in GitHub I guess that's fine.

[adacapo21]

Done — both files removed in commit d8f1d6d4. The rationale and summary content has been moved into the PR description so it stays with the PR but does not flow upstream as files.

[fabianbormann]

Makes sense, but let's discuss this with the community in the open office hours session

[adacapo21]

Acknowledged — happy to walk the community through the extension shape and the rationale in the open office hours, and to adjust the proposal based on the discussion. A full end-to-end example (PaymentRequired → PAYMENT-SIGNATURE → SettlementResponse) has also been added to this file in adab35d6 so the conversation has concrete JSON to point at.

[fabianbormann]

Could you provide here also an example of a full request using the masumi extension as an example?

[adacapo21]

Added — see commit adab35d6. The cardano-masumi extension spec now includes an End-to-End Example section that walks through a complete Masumi-routed flow: the 402 Payment Required body with the extension populated, the decoded PAYMENT-SIGNATURE header payload showing the client echoing the extension, and the PAYMENT-RESPONSE/SettlementResponse. There is also a short note on what a non-Masumi-aware stack sees of the same flow (generic script-parameterized payment).