specs(exact): propose TON exact scheme for x402 v2 (spec-only)

[ohld]

Description

Adds formal specification for the exact payment scheme on TON blockchain, following the same structure as existing network-specific scheme documents (EVM, SVM, Stellar, Aptos).

• Adds specs/schemes/exact/scheme_exact_ton.md -- full spec for TON exact scheme
• Updates specs/schemes/exact/scheme_exact.md -- adds TON validation rules to the index
• No SDK/runtime implementation changes
• Implementation PR follows after spec approval

Tests

No code affected.

Checklist

• My commits are signed (required for merge)

Why TON

• 950M+ Telegram users with built-in TON wallets
• USDT on TON: 60B+ total transfer volume
• Sub-second finality, <0.01 USD transaction fees
• W5 wallet standard enables native gasless transactions -- architecturally equivalent to EIP-3009
• Natural fit for AI agent payments in Telegram ecosystem

Working proof

• Demo repo: https://github.com/ohld/x402-ton-poc
• On-chain USDT payment via x402 flow: https://tonviewer.com/transaction/ba96f62d4ea651a21da4282809f2541ea42481ca35018129f29b406ef3fe36c0

Key design decisions

1. W5+ wallet internal_signed -- TON equivalent of EIP-3009. Client signs, relay submits. Facilitator cannot modify destination or amount.
2. Gasless relay sponsors gas -- client never pays TON for fees, only the token amount. Non-sponsored flow also documented.
3. Relay-agnostic design -- TONAPI is a reference implementation, not a requirement. Any entity can act as relay.
4. TEP-74 Jetton transfers only -- stablecoins first (USDT), expandable to any TEP-74 token.
5. CAIP-2 identifiers -- uses official TVM namespace: tvm:-239 (mainnet), tvm:-3 (testnet) per https://namespaces.chainagnostic.org/tvm/caip2

v2 alignment

• Uses v2 headers: PAYMENT-REQUIRED, PAYMENT-SIGNATURE, PAYMENT-RESPONSE
• Uses x402Version: 2 and PaymentRequirements.amount
• Includes explicit facilitator safety/relay sponsorship rules
• /settle performs full verification independently (does not trust prior /verify)
• Full JSON examples matching x402 style

Review request

Please review the scheme design, payload shape, and verification/settlement safety constraints. Once aligned, I will open a separate implementation PR in TypeScript.

[cb-heimdall]

🟡 Heimdall Review Status

Requirement	Status	More Info
Reviews	🟡 0/1	Denominator calculation Show calculation 1 if user is bot 0 1 if user is external 0 2 if repo is sensitive 0 From .codeflow.yml 1 Additional review requirements Show calculation Max 0 0 From CODEOWNERS 0 Global minimum 0 Max 1 1 1 if commit is unverified 0 Sum 1

[vercel]

@ohld is attempting to deploy a commit to the Coinbase Team on Vercel.

A member of the Team first needs to authorize it.

[arjun215-eng]

Really excited to see TON getting a proper x402 spec — the W5/internal_signed <=> EIP-3009 mapping is elegant. A few things I noticed that might be worth addressing before the implementation PR:

1. >= vs == and the exact scheme semantics
scheme_exact.md requires amount MUST equal requirements.amount exactly, but the TON addition uses >= in both the index and the spec body (verification rules §1 and §3). I'm guessing this is because the relay commission is bundled into the same jetton_transfer, pushing the gross transfer slightly above requirements.amount — but if so, it probably needs to be called out explicitly, and some bound on overpayment defined. Otherwise >= requirements.amount could pass for any amount, which feels at odds with the scheme name.

2. stateInit (seqno == 0) — worth adding a code hash check
Step 7 mentions including stateInit for new wallet deployments, but there's no rule telling facilitators to verify the deployed contract is actually a W5 wallet. A malicious client could potentially submit a stateInit for an arbitrary contract. Might be worth adding: facilitator MUST verify the code hash matches the canonical W5 v5r1 hash before accepting a seqno-0 payload.

3. Relay commission amount is undefined
Verification rule 4 says the W5 message "MUST NOT contain additional unrelated actions beyond the payment transfer and relay commission" — but the commission amount isn't communicated anywhere in PaymentRequirements or PaymentPayload. Without it, how does a facilitator distinguish a valid commission from an inflated one? Maybe extra.relayCommission in PaymentRequirements, or a specified max ratio?

[ohld]

Thanks for the thorough review, these are all great catches.

1. >= → == (exact amount)

You're right — >= was wrong here. The relay commission on TON is a separate jetton_transfer action in the W5 batch, not bundled into the payment transfer amount. So the payment to the recipient is exactly requirements.amount, and the commission goes to extra.relayAddress independently. Fixed both the spec and the index to use strict equality, matching SVM/Stellar/EVM.

2. stateInit code hash check

Good call. I didn't want to hardcode a specific hash in the spec since W5 has revisions (v5r1, potentially v5r2) and a hardcoded hash would become outdated when TON Foundation ships a new version. Instead I added: facilitator MUST verify that the contract code in stateInit matches a known W5 wallet contract, and SHOULD maintain an allowlist of accepted wallet code hashes. This follows how SVM handles program IDs — the validation logic is in the facilitator implementation, not frozen in the spec.

3. Relay commission bounds

Added extra.maxRelayCommission (optional) to PaymentRequirements. When the resource server sets it, the facilitator rejects W5 batches where the commission transfer exceeds that cap. When absent, the facilitator applies its own policy. This gives resource servers explicit control without hardcoding a ratio that would break as gas prices change.

Also tightened rule §4: the W5 message must contain exactly two actions (payment transfer + optional commission transfer), anything else is rejected.

All changes in the latest commit + updated the demo repo to enforce exact amount matching (30/30 tests passing).