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 1 Sum 2

[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?