@stableyard/mppx-stableyard 0.1.0

package/specs/draft-stableyard-charge-00.md

@@ -0,0 +1,607 @@
+---
+title: Stableyard Charge Intent for HTTP Payment Authentication
+abbrev: Stableyard Charge Intent
+docname: draft-stableyard-charge-00
+version: 00
+category: info
+ipr: noModificationTrust200902
+submissiontype: independent
+consensus: false
+
+author:
+  - name: Mitesh Metha
+    ins: M. Metha
+    email: mitesh@stableyard.fi
+    org: Stableyard
+
+normative:
+  RFC2119:
+  RFC3339:
+  RFC4648:
+  RFC8174:
+  RFC8259:
+  RFC8785:
+  RFC9457:
+  I-D.payment-intent-charge:
+    title: "'charge' Intent for HTTP Payment Authentication"
+    target: https://datatracker.ietf.org/doc/draft-payment-intent-charge/
+    author:
+      - name: Jake Moxey
+      - name: Brendan Ryan
+      - name: Tom Meagher
+    date: 2026
+  I-D.httpauth-payment:
+    title: "The 'Payment' HTTP Authentication Scheme"
+    target: https://datatracker.ietf.org/doc/draft-ietf-httpauth-payment/
+    author:
+      - name: Jake Moxey
+    date: 2026-01
+
+informative:
+  EIP-712:
+    title: "Typed structured data hashing and signing"
+    target: https://eips.ethereum.org/EIPS/eip-712
+    author:
+      - org: Ethereum Foundation
+    date: 2017
+  W3C-DID:
+    title: "Decentralized Identifiers (DIDs) v1.0"
+    target: https://www.w3.org/TR/did-core/
+    author:
+      - org: W3C
+    date: 2022
+---
+
+--- abstract
+
+This document defines the "charge" intent for the "stableyard"
+payment method within the Payment HTTP Authentication Scheme
+{{I-D.httpauth-payment}}. The server issues a challenge specifying
+amount and destination; the client fulfills it by creating a
+Stableyard payment session from any supported blockchain, then
+presents the session identifier as a credential.
+
+Stableyard settles cross-chain: the client pays from whichever chain
+it holds funds on (Base, Arbitrum, Polygon, Ethereum, Solana, or
+Movement), and the merchant receives on their preferred chain, token,
+or fiat currency. The server verifies payment via Stableyard's
+settlement API without needing chain-specific logic.
+
+--- middle
+
+# Introduction
+
+HTTP Payment Authentication {{I-D.httpauth-payment}} defines a
+challenge-response mechanism that gates access to resources behind
+payments. This document registers the "charge" intent for the
+"stableyard" payment method.
+
+Existing payment methods in MPP are chain-specific: "tempo" requires
+funds on Tempo chain, "lightning" requires a Lightning wallet. The
+"stableyard" method removes this constraint — an agent pays from
+any supported chain and the merchant receives on any other chain.
+
+The flow proceeds as follows:
+
+~~~
+   Client                    Server                  Stableyard
+      |                         |                         |
+      |  (1) GET /resource      |                         |
+      |---------------------->  |                         |
+      |                         |                         |
+      |  (2) 402 Payment        |                         |
+      |      Required           |                         |
+      |      (amount, dest)     |                         |
+      |<----------------------  |                         |
+      |                         |                         |
+      |  (3) Create session                               |
+      |      {amount, dest, sourceChain}                  |
+      |---------------------------------------------->    |
+      |  (4) Session + deposit address                    |
+      |<----------------------------------------------    |
+      |                         |                         |
+      |  (5) Send USDC to                                 |
+      |      deposit address                              |
+      |---------------------------------------------->    |
+      |  (6) Submit tx hash                               |
+      |---------------------------------------------->    |
+      |                         |                         |
+      |                         |  (7) Stableyard routes  |
+      |                         |      cross-chain        |
+      |                         |                         |
+      |  (8) GET /resource      |                         |
+      |      credential:        |                         |
+      |      {sessionId}        |                         |
+      |---------------------->  |                         |
+      |                         |  (9) Verify session     |
+      |                         |---------------------->  |
+      |                         |  (10) {verified: true}  |
+      |                         |<----------------------  |
+      |                         |                         |
+      |  (11) 200 OK            |                         |
+      |       (resource)        |                         |
+      |<----------------------  |                         |
+      |                         |                         |
+~~~
+
+## Relationship to the Charge Intent
+
+This document inherits the shared request semantics of the "charge"
+intent from {{I-D.payment-intent-charge}}. It defines only the
+stableyard-specific `methodDetails`, credential payload, and
+verification procedure.
+
+
+# Requirements Language
+
+{::boilerplate bcp14-tagged}
+
+
+# Terminology
+
+Session:
+: A Stableyard payment session representing a single payment intent.
+  Sessions track status from creation through settlement.
+
+Deposit Address:
+: A blockchain address generated by Stableyard's Intent Engine where
+  the client sends funds. May be a direct wallet address (same-chain)
+  or a gateway contract address (cross-chain).
+
+Settlement:
+: The process by which Stableyard routes funds from the source chain
+  to the merchant's preferred destination chain, token, or fiat
+  currency.
+
+Intent Engine:
+: Stableyard's cross-chain routing system that generates deposit
+  addresses, monitors payments, and executes settlement via a
+  solver network.
+
+Payment Address:
+: A human-readable identifier in the format `name@stableyard` that
+  resolves to an account with configured settlement preferences.
+
+Vault:
+: An optional Gnosis Safe smart contract wallet enabling gasless
+  payments via EIP-712 signed messages.
+
+
+# Intent Identifier
+
+The intent identifier for this specification is "charge".
+
+
+# Intent: "charge"
+
+The "charge" intent represents a one-time payment for resource access.
+The client creates a Stableyard session, funds it from any supported
+chain, and presents the settled session ID as proof of payment.
+
+
+# Encoding Conventions {#encoding}
+
+All JSON values in challenges and credentials MUST be serialized
+using JSON Canonicalization Scheme (JCS) {{RFC8785}} and encoded
+with base64url {{RFC4648}} without padding, consistent with the
+base specification {{I-D.httpauth-payment}}.
+
+
+# Request Schema
+
+The challenge `request` parameter is a base64url-encoded JSON object
+containing the following fields:
+
+## Shared Fields
+
+These fields follow the shared charge intent schema from
+{{I-D.payment-intent-charge}}:
+
+amount:
+: REQUIRED. String. Amount in base units (smallest denomination).
+  For USDC with 6 decimals, "100000" represents $0.10.
+
+currency:
+: REQUIRED. String. Currency identifier. MUST be "USDC" or "USDT".
+
+decimals:
+: REQUIRED. Number. Decimal places for the currency. MUST be 6 for
+  USDC and USDT.
+
+destination:
+: REQUIRED. String. Stableyard payment address. Either a
+  human-readable address (e.g., "merchant@stableyard") or a wallet
+  address (e.g., "0x742d...fA99").
+
+description:
+: OPTIONAL. String. Human-readable description of the payment
+  purpose. Maximum 500 characters.
+
+externalId:
+: OPTIONAL. String. Merchant-defined reference for reconciliation.
+
+
+## Method Details
+
+No additional `methodDetails` fields are required for the stableyard
+charge intent. The method is chain-agnostic — the client selects its
+source chain when creating the Stableyard session.
+
+## Example Request (Decoded)
+
+~~~json
+{
+  "amount": "100000",
+  "currency": "USDC",
+  "decimals": 6,
+  "destination": "merchant@stableyard"
+}
+~~~
+
+
+# Credential Schema
+
+The credential `payload` field is a JSON object containing:
+
+sessionId:
+: REQUIRED. String. The Stableyard session identifier (e.g.,
+  "ses_b6afc57b153e2ae1f8fb1025"). This serves as the proof of
+  payment — the server verifies it via Stableyard's API.
+
+txHash:
+: OPTIONAL. String. The on-chain transaction hash with "0x" prefix.
+  Included for transparency and auditability. Not required for
+  verification — the session ID is sufficient.
+
+## Example Credential Payload
+
+~~~json
+{
+  "sessionId": "ses_b6afc57b153e2ae1f8fb1025",
+  "txHash": "0xbeaf32d41f8f7573e02653a79e02bf56a73ae667dca203acb9e5c181116914a9"
+}
+~~~
+
+
+# Verification Procedure {#verification}
+
+Upon receiving a credential with method "stableyard" and intent
+"charge", the server MUST execute the following steps:
+
+1. Extract `sessionId` from `credential.payload`.
+
+2. Call `POST /v2/sessions/{sessionId}/verify` on the Stableyard
+   API with the server's API key.
+
+3. The Stableyard API returns `{verified: true}` if and only if:
+   - The session exists and is in "settled" status
+   - The session amount matches the challenge amount
+   - The session destination matches the challenge destination
+   - The session has a `resource` field matching the challenge realm
+
+4. If verification succeeds, the server MUST invalidate the
+   challenge and return HTTP 200 with the resource.
+
+5. If verification fails (session not settled, amount mismatch,
+   or API error), the server MUST return HTTP 402 with a fresh
+   challenge and a Problem Details {{RFC9457}} body.
+
+## Challenge Binding
+
+The server SHOULD set the `resource` field when the client creates
+the Stableyard session, binding the session to the specific API
+endpoint being paid for. The Stableyard verify endpoint checks this
+field to prevent session reuse across different resources.
+
+## Delegated Verification
+
+Unlike methods where the server independently verifies a
+cryptographic proof (e.g., preimage in Lightning, signed transaction
+in Tempo), the stableyard method delegates verification to
+Stableyard's API. This is analogous to how the "stripe" method
+delegates verification to Stripe's API.
+
+This design choice enables:
+- Chain-agnostic verification (server needs no blockchain RPC)
+- Cross-chain settlement (Stableyard handles routing)
+- Unified merchant experience (one API for all chains)
+
+
+# Settlement Procedure
+
+Settlement is handled entirely by Stableyard's Intent Engine:
+
+1. Client creates a session with `sourceChain` parameter.
+2. Stableyard returns a deposit address on the specified chain.
+3. Client sends the requested amount to the deposit address.
+4. Client calls `POST /v2/sessions/{id}/submit-tx` with the
+   transaction hash for faster detection.
+5. Stableyard detects the payment and routes it to the merchant's
+   configured settlement destination.
+
+Settlement timing depends on the route:
+
+| Route | Estimated Time |
+|-------|---------------|
+| Same-chain (e.g., Base to Base) | ~1 second |
+| Cross-chain (e.g., Polygon to Base) | ~15 seconds |
+
+## Deposit Types
+
+Stableyard returns one of two deposit types based on the route:
+
+direct_transfer:
+: Same-chain payments. Client sends an ERC20 `transfer()` to the
+  deposit address.
+
+gasyard:
+: Cross-chain payments via Stableyard's gateway contract. Client
+  executes `approve()` + `deposit()` transactions. Gateway calldata
+  is provided in the session response.
+
+## Gasless Payments
+
+If the client has an active Stableyard Vault (Gnosis Safe), it MAY
+pay via `POST /v2/sessions/{id}/pay` with an EIP-712 {{EIP-712}}
+signed message. This enables zero-gas payments — Stableyard executes
+the transaction on behalf of the client.
+
+## Receipt Generation
+
+Upon successful verification, the server MUST return a
+`Payment-Receipt` header containing:
+
+~~~json
+{
+  "method": "stableyard",
+  "status": "success",
+  "reference": "ses_b6afc57b153e2ae1f8fb1025",
+  "timestamp": "2026-03-19T16:38:34Z"
+}
+~~~
+
+The `reference` field contains the Stableyard session ID, which can
+be used for reconciliation via the Stableyard merchant dashboard.
+
+
+# Error Responses
+
+Failed payment attempts MUST return HTTP 402 with a fresh challenge
+and a Problem Details {{RFC9457}} body. Error types:
+
+verification-failed:
+: Session is not in "settled" status, or amount/destination mismatch.
+
+invalid-session:
+: Session ID is unknown or expired.
+
+malformed-credential:
+: Credential payload is missing `sessionId` or is not valid JSON.
+
+settlement-failed:
+: Stableyard detected the payment but settlement routing failed.
+  This triggers an automatic refund via Stableyard.
+
+
+# Security Considerations
+
+## Transport Security
+
+All interactions between client, server, and Stableyard API MUST
+use TLS 1.2 or later. Stableyard API endpoints enforce HTTPS.
+
+## Session Uniqueness
+
+Each Stableyard session is single-use. Once verified, the session
+transitions to a consumed state and cannot be reused for another
+challenge. The Stableyard API enforces this server-side.
+
+## Amount Verification
+
+Clients SHOULD verify that the requested amount, currency, and
+destination are reasonable before creating a session and sending
+funds. The Stableyard API validates that the payment amount matches
+the session amount during settlement.
+
+## API Key Security
+
+Server-side API keys (`sy_secret_*`) MUST be treated as secrets.
+They MUST NOT be exposed in client-side code, logs, or error
+responses. Client-side operations SHOULD use public keys
+(`sy_pub_*`) which have restricted permissions.
+
+## Replay Protection
+
+Replay attacks are prevented at two levels:
+1. MPP challenge IDs are HMAC-bound and single-use per the base
+   specification {{I-D.httpauth-payment}}.
+2. Stableyard sessions are single-use — once verified, the session
+   cannot be presented again.
+
+## Destination Verification
+
+Servers MUST verify that the `destination` in the credential's
+session matches the `destination` in the original challenge. The
+Stableyard verify endpoint performs this check automatically.
+
+
+# IANA Considerations
+
+## Payment Method Registration
+
+This document requests registration of the following payment method
+in the "HTTP Payment Methods" registry:
+
+Method: stableyard
+
+Description: Cross-chain stablecoin payments via Stableyard
+settlement network. Supports USDC and USDT across multiple EVM
+chains, Solana, and Movement, with fiat settlement available.
+
+Reference: This document
+
+Contact: Mitesh Metha (mitesh@stableyard.fi)
+
+
+## Payment Intent Registration
+
+This document requests registration of the following payment intent
+for the "stableyard" method:
+
+Intent: charge
+
+Method: stableyard
+
+Description: One-time cross-chain payment for resource access.
+Client creates a Stableyard session, funds it from any supported
+chain, and presents the session ID as proof.
+
+Reference: This document
+
+Contact: Mitesh Metha (mitesh@stableyard.fi)
+
+
+# Examples
+
+## Initial Request and 402 Challenge
+
+Client requests a protected resource:
+
+~~~
+GET /api/market-data HTTP/1.1
+Host: api.example.com
+~~~
+
+Server responds with a payment challenge:
+
+~~~
+HTTP/1.1 402 Payment Required
+WWW-Authenticate: Payment id="POudmDHUpiZKtSqrMfFHAdEtLTsc",
+    realm="api.example.com",
+    method="stableyard",
+    intent="charge",
+    request="eyJhbW91bnQiOiIxMDAwMDAiLCJjdXJyZW5jeSI6IlVTRE
+        MiLCJkZWNpbWFscyI6NiwiZGVzdGluYXRpb24iOiJtZXJjaGFu
+        dEBzdGFibGV5YXJkIn0",
+    description="Market data feed",
+    expires="2026-03-19T16:49:52Z"
+Cache-Control: no-store
+Content-Type: application/problem+json
+
+{
+  "type": "https://paymentauth.org/problems/payment-required",
+  "title": "Payment Required",
+  "status": 402,
+  "detail": "Payment is required (Market data feed)."
+}
+~~~
+
+The decoded `request` parameter contains:
+
+~~~json
+{
+  "amount": "100000",
+  "currency": "USDC",
+  "decimals": 6,
+  "destination": "merchant@stableyard"
+}
+~~~
+
+
+## Client Payment Flow
+
+The client creates a Stableyard session:
+
+~~~
+POST /v2/sessions HTTP/1.1
+Host: api.stableyard.fi
+Authorization: Bearer sy_secret_...
+Content-Type: application/json
+
+{
+  "amount": 100000,
+  "destination": "merchant@stableyard",
+  "sourceChain": "base",
+  "resource": "api.example.com/charge"
+}
+~~~
+
+Stableyard responds with deposit info:
+
+~~~json
+{
+  "id": "ses_b6afc57b153e2ae1f8fb1025",
+  "status": "open",
+  "deposit": {
+    "type": "direct_transfer",
+    "address": "0xdfd4ab80e163d6864e26f37540563cbf2e52a582",
+    "chainId": 8453,
+    "token": {
+      "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+      "symbol": "USDC",
+      "decimals": 6
+    },
+    "amount": {
+      "raw": "100000",
+      "formatted": "0.10"
+    }
+  }
+}
+~~~
+
+The client sends 0.10 USDC to the deposit address on Base, then
+submits the transaction hash. After settlement (~1 second for
+same-chain), the client retries with the credential.
+
+
+## Retry with Credential
+
+~~~
+GET /api/market-data HTTP/1.1
+Host: api.example.com
+Authorization: Payment eyJjaGFsbGVuZ2UiOnsiY2hhbGxlbmdlSWQi
+    OiJQT3VkbURIVXBpWkt0U3FyTWZGSEFkRXRMVHNjIiwibWV0aG9kIj
+    oic3RhYmxleWFyZCIsImludGVudCI6ImNoYXJnZSJ9LCJwYXlsb2FkI
+    jp7InNlc3Npb25JZCI6InNlc19iNmFmYzU3YjE1M2UyYWUxZjhmYjEw
+    MjUifX0
+~~~
+
+Server verifies via Stableyard API:
+
+~~~
+POST /v2/sessions/ses_b6afc57b153e2ae1f8fb1025/verify HTTP/1.1
+Host: api.stableyard.fi
+Authorization: Bearer sy_secret_...
+~~~
+
+~~~json
+{
+  "verified": true,
+  "sessionId": "ses_b6afc57b153e2ae1f8fb1025",
+  "resource": "api.example.com/charge"
+}
+~~~
+
+Server returns the resource with a receipt:
+
+~~~
+HTTP/1.1 200 OK
+Payment-Receipt: eyJtZXRob2QiOiJzdGFibGV5YXJkIiwic3RhdHVzIj
+    oic3VjY2VzcyIsInJlZmVyZW5jZSI6InNlc19iNmFmYzU3YjE1M2Uy
+    YWUxZjhmYjEwMjUiLCJ0aW1lc3RhbXAiOiIyMDI2LTAzLTE5VDE2Oj
+    Mzjoy...
+Content-Type: application/json
+
+{
+  "data": {
+    "btc": {"price": 98450.23, "change24h": 2.1},
+    "eth": {"price": 3842.67, "change24h": -0.5}
+  }
+}
+~~~
+
+
+# Acknowledgements
+
+The Machine Payments Protocol was created by Jake Moxey, Brendan
+Ryan, Tom Meagher, and the teams at Tempo and Stripe.