s402 0.4.0 → 0.6.0

package/dist/{scheme-tVj4sOr-.d.mts → scheme-CKinOhyx.d.mts}

@@ -60,6 +60,8 @@ interface s402ServerScheme {
  *
  * Critical: each scheme has its OWN verify logic.
  * - Exact: signature recovery + dry-run simulation + balance check
+ * - Upto: deposit PTB validation + maxAmount match + deadline check
+ * - Prepaid: deposit PTB validation + rate/cap match
  * - Stream: stream creation PTB validation + deposit check
  * - Escrow: escrow creation PTB validation + arbiter/deadline check
  * - Unlock: escrow validation (key release is separate PTB)
@@ -109,6 +111,20 @@ interface s402RouteConfig {
   protocolFeeBps?: number;
   /** Require on-chain receipt */
   receiptRequired?: boolean;
+  upto?: {
+    maxAmount: string;
+    settlementDeadlineMs: string;
+    usageReportUrl?: string;
+    estimatedAmount?: string;
+  };
+  prepaid?: {
+    ratePerCall: string;
+    maxCalls?: string;
+    minDeposit: string;
+    withdrawalDelayMs: string; /** Provider Ed25519 pubkey (hex). Enables v0.2 signed receipt mode. @since v0.2 */
+    providerPubkey?: string; /** Dispute window in ms. Required when providerPubkey is set. @since v0.2 */
+    disputeWindowMs?: string;
+  };
   stream?: {
     ratePerSecond: string;
     budgetCap: string;
@@ -124,14 +140,6 @@ interface s402RouteConfig {
     encryptedContentId: string;
     encryptionServiceId: string;
   };
-  prepaid?: {
-    ratePerCall: string;
-    maxCalls?: string;
-    minDeposit: string;
-    withdrawalDelayMs: string; /** Provider Ed25519 pubkey (hex). Enables v0.2 signed receipt mode. @since v0.2 */
-    providerPubkey?: string; /** Dispute window in ms. Required when providerPubkey is set. @since v0.2 */
-    disputeWindowMs?: string;
-  };
 }
 //#endregion
 export { s402ServerScheme as a, s402RouteConfig as i, s402DirectScheme as n, s402SettlementVerification as o, s402FacilitatorScheme as r, s402ClientScheme as t };

package/dist/test-utils.d.mts

@@ -1,5 +1,5 @@
 import { s402PaymentPayload, s402PaymentRequirements, s402SettleResponse, s402VerifyResponse } from "./types.mjs";
-import { a as s402ServerScheme, r as s402FacilitatorScheme, t as s402ClientScheme } from "./scheme-tVj4sOr-.mjs";
+import { a as s402ServerScheme, r as s402FacilitatorScheme, t as s402ClientScheme } from "./scheme-CKinOhyx.mjs";
 
 //#region src/test-utils.d.ts
 /**

package/dist/types.d.mts

@@ -3,8 +3,14 @@ import { s402ErrorCodeType } from "./errors.mjs";
 //#region src/types.d.ts
 /** Current protocol version. Always lowercase s. */
 declare const S402_VERSION: "1";
-/** The five s402 payment schemes */
-type s402Scheme = 'exact' | 'stream' | 'escrow' | 'unlock' | 'prepaid';
+/**
+ * The six s402 payment schemes, ordered by complexity:
+ *
+ * TIER 1 — Single Payment:  exact (fixed amount), upto (variable amount)
+ * TIER 2 — Persistent Balance: prepaid (multi-claim), stream (time-based)
+ * TIER 3 — Conditional Release: escrow (arbiter), unlock (encryption)
+ */
+type s402Scheme = 'exact' | 'upto' | 'prepaid' | 'stream' | 'escrow' | 'unlock';
 /** Settlement mode: facilitator-mediated or direct on-chain */
 type s402SettlementMode = 'facilitator' | 'direct';
 /**
@@ -64,14 +70,18 @@ interface s402PaymentRequirements {
   settlementMode?: s402SettlementMode;
   /** When these requirements expire (Unix timestamp ms). Facilitator MUST reject after this. */
   expiresAt?: number;
+  /** Extra fields for upto scheme (usage-based, variable settlement) */
+  upto?: s402UptoExtra;
+  /** Extra fields for prepaid scheme */
+  prepaid?: s402PrepaidExtra;
   /** Extra fields for stream scheme */
   stream?: s402StreamExtra;
   /** Extra fields for escrow scheme */
   escrow?: s402EscrowExtra;
   /** Extra fields for unlock scheme (pay-to-decrypt encrypted content) */
   unlock?: s402UnlockExtra;
-  /** Extra fields for prepaid scheme */
-  prepaid?: s402PrepaidExtra;
+  /** Settlement overrides (used by upto scheme — server provides actual amount at settle-time) */
+  settlementOverrides?: s402SettlementOverrides;
   /**
    * Arbitrary extension data (forward-compatible extensibility).
    *
@@ -83,34 +93,57 @@ interface s402PaymentRequirements {
    */
   extensions?: Record<string, unknown>;
 }
-/** Stream-specific requirements */
-interface s402StreamExtra {
-  /** Rate in base units per second */
-  ratePerSecond: string;
-  /** Maximum budget cap in base units */
-  budgetCap: string;
-  /** Minimum initial deposit in base units */
-  minDeposit: string;
-  /** URL for stream status checks (phase 2) */
-  streamSetupUrl?: string;
-}
-/** Escrow-specific requirements */
-interface s402EscrowExtra {
-  /** Seller/payee address */
-  seller: string;
-  /** Arbiter address for dispute resolution */
-  arbiter?: string;
-  /** Escrow deadline in milliseconds since epoch */
-  deadlineMs: string;
+/**
+ * Upto-specific requirements (usage-based, variable settlement).
+ *
+ * The client authorizes up to `maxAmount`; the facilitator settles the actual
+ * amount (provided by the server via `settlementOverrides`) at settlement time.
+ * Remainder is returned to the payer on-chain.
+ *
+ * TRUST MODEL: The client can bound its exposure via `settlementCeiling` in the
+ * payment payload — an on-chain-enforced cap tighter than `maxAmount`. The server
+ * advertises `estimatedAmount` so the client can set a tight ceiling (e.g., 1.2x
+ * the estimate). Without `settlementCeiling`, the facilitator can settle up to
+ * `maxAmount`. See ADR-003 §Decision 3 and §Decision 8.
+ *
+ * SEMANTIC CLARITY: `amount` on the parent `s402PaymentRequirements` is the
+ * EXACT price for the `exact` scheme. For `upto`, `maxAmount` here is the
+ * ceiling — the two are intentionally separate fields to avoid the semantic
+ * overloading that x402 suffers from.
+ */
+interface s402UptoExtra {
+  /** Maximum authorized amount in base units. Client deposits this; actual may be less. */
+  maxAmount: string;
+  /**
+   * Deadline for settlement in milliseconds since epoch.
+   * After this time, the payer can reclaim the full deposit via `expire()`.
+   * Must be in the future at verify-time. Facilitator MUST reject expired deposits.
+   */
+  settlementDeadlineMs: string;
+  /** Optional URL where the client can query usage/metering data (informational) */
+  usageReportUrl?: string;
+  /**
+   * Server's estimated cost in base units (advisory, optional).
+   * Helps the client set a tight `settlementCeiling` in the payload.
+   * Must be ≤ maxAmount when present. Not enforced on-chain — purely informational.
+   */
+  estimatedAmount?: string;
 }
-/** Unlock-specific requirements (pay-to-decrypt encrypted content) */
-interface s402UnlockExtra {
-  /** Encryption ID for key servers */
-  encryptionId: string;
-  /** Content identifier for the encrypted blob (e.g., Walrus blob ID, IPFS CID) */
-  encryptedContentId: string;
-  /** Identifier for the encryption service or module (e.g., Sui package ID, EVM contract address) */
-  encryptionServiceId: string;
+/**
+ * Settlement overrides — server provides the actual amount to the facilitator.
+ *
+ * Used by the `upto` scheme: the resource server tells the facilitator how much
+ * of the authorized maximum to actually charge, based on observed usage.
+ * Threaded via `requirements.settlementOverrides` so the facilitator's `process()`
+ * signature (payload, requirements) doesn't need to change.
+ *
+ * TRUST MODEL: The server is trusted to report honest usage. The facilitator
+ * enforces `actualAmount <= maxAmount` but cannot verify usage independently.
+ * On-chain events provide an audit trail for dispute resolution.
+ */
+interface s402SettlementOverrides {
+  /** Actual amount to settle in base units. Must be ≤ maxAmount from UptoExtra. */
+  actualAmount: string;
 }
 /**
  * Prepaid-specific requirements.
@@ -152,6 +185,35 @@ interface s402PrepaidExtra {
    */
   disputeWindowMs?: string;
 }
+/** Stream-specific requirements */
+interface s402StreamExtra {
+  /** Rate in base units per second */
+  ratePerSecond: string;
+  /** Maximum budget cap in base units */
+  budgetCap: string;
+  /** Minimum initial deposit in base units */
+  minDeposit: string;
+  /** URL for stream status checks (phase 2) */
+  streamSetupUrl?: string;
+}
+/** Escrow-specific requirements */
+interface s402EscrowExtra {
+  /** Seller/payee address */
+  seller: string;
+  /** Arbiter address for dispute resolution */
+  arbiter?: string;
+  /** Escrow deadline in milliseconds since epoch */
+  deadlineMs: string;
+}
+/** Unlock-specific requirements (pay-to-decrypt encrypted content) */
+interface s402UnlockExtra {
+  /** Encryption ID for key servers */
+  encryptionId: string;
+  /** Content identifier for the encrypted blob (e.g., Walrus blob ID, IPFS CID) */
+  encryptedContentId: string;
+  /** Identifier for the encryption service or module (e.g., Sui package ID, EVM contract address) */
+  encryptionServiceId: string;
+}
 /** Mandate requirements in a 402 response — tells client what mandate is needed */
 interface s402MandateRequirements {
   /** Whether a mandate is required (true) or optional (false = speeds up if present) */
@@ -193,6 +255,46 @@ interface s402ExactPayload extends s402PaymentPayloadBase {
     signature: string;
   };
 }
+/**
+ * Upto payment: signed deposit transaction for variable-amount settlement.
+ *
+ * The client deposits `maxAmount` into an on-chain UptoDeposit proxy.
+ * The facilitator later calls `settle(actual_amount)` where
+ * `actual ≤ min(maxAmount, settlementCeiling)`, returning the remainder
+ * to the payer. If settlement doesn't happen before the deadline, the
+ * payer can reclaim via `expire()`.
+ */
+interface s402UptoPayload extends s402PaymentPayloadBase {
+  scheme: 'upto';
+  payload: {
+    /** Base64-encoded signed deposit transaction (creates UptoDeposit on-chain) */transaction: string; /** Base64-encoded signature */
+    signature: string; /** Maximum authorized amount (must match requirements.upto.maxAmount) */
+    maxAmount: string;
+    /**
+     * Client-chosen settlement ceiling (optional, on-chain enforced).
+     * The Move contract rejects settlements where `actualAmount > settlementCeiling`.
+     * Must satisfy: `1 <= settlementCeiling <= maxAmount`.
+     * Omit to allow settlement up to `maxAmount` (backwards compatible).
+     *
+     * Servers SHOULD check this before serving expensive resources — if
+     * `settlementCeiling < estimatedCost`, respond with an updated 402.
+     */
+    settlementCeiling?: string;
+  };
+}
+/**
+ * Prepaid payment: agent deposits into a PrepaidBalance shared object.
+ * This is the deposit phase only — claims are provider-initiated (not via HTTP 402).
+ */
+interface s402PrepaidPayload extends s402PaymentPayloadBase {
+  scheme: 'prepaid';
+  payload: {
+    /** Base64-encoded deposit PTB */transaction: string; /** Agent's signature */
+    signature: string; /** Committed rate per call (must match requirements) */
+    ratePerCall: string; /** Committed max calls cap (must match requirements) */
+    maxCalls?: string;
+  };
+}
 /** Stream payment: signed stream creation transaction */
 interface s402StreamPayload extends s402PaymentPayloadBase {
   scheme: 'stream';
@@ -226,21 +328,8 @@ interface s402UnlockPayload extends s402PaymentPayloadBase {
     encryptionId: string;
   };
 }
-/**
- * Prepaid payment: agent deposits into a PrepaidBalance shared object.
- * This is the deposit phase only — claims are provider-initiated (not via HTTP 402).
- */
-interface s402PrepaidPayload extends s402PaymentPayloadBase {
-  scheme: 'prepaid';
-  payload: {
-    /** Base64-encoded deposit PTB */transaction: string; /** Agent's signature */
-    signature: string; /** Committed rate per call (must match requirements) */
-    ratePerCall: string; /** Committed max calls cap (must match requirements) */
-    maxCalls?: string;
-  };
-}
 /** Discriminated union of all payment payloads */
-type s402PaymentPayload = s402ExactPayload | s402StreamPayload | s402EscrowPayload | s402UnlockPayload | s402PrepaidPayload;
+type s402PaymentPayload = s402ExactPayload | s402UptoPayload | s402PrepaidPayload | s402StreamPayload | s402EscrowPayload | s402UnlockPayload;
 interface s402SettleResponse {
   /** Whether settlement was successful */
   success: boolean;
@@ -250,12 +339,16 @@ interface s402SettleResponse {
   receiptId?: string;
   /** Time to finality in milliseconds */
   finalityMs?: number;
+  /** Actual amount settled in base units (for upto scheme — fixes x402's opacity) */
+  actualAmount?: string;
+  /** UptoDeposit object ID (for upto scheme) */
+  depositId?: string;
+  /** PrepaidBalance object ID (for prepaid scheme) */
+  balanceId?: string;
   /** Stream object ID (for stream scheme) */
   streamId?: string;
   /** Escrow object ID (for escrow scheme) */
   escrowId?: string;
-  /** PrepaidBalance object ID (for prepaid scheme) */
-  balanceId?: string;
   /** Error message if settlement failed */
   error?: string;
   /** Typed error code for programmatic failure handling */
@@ -353,7 +446,8 @@ declare const S402_HEADERS: {
   /** Server → client: payment requirements (base64 JSON in 402 response) */readonly PAYMENT_REQUIRED: "payment-required"; /** Client → server: payment payload (base64 JSON) */
   readonly PAYMENT: "x-payment"; /** Server → client: settlement result (base64 JSON) */
   readonly PAYMENT_RESPONSE: "payment-response"; /** Client → server: active stream ID (phase 2 of stream protocol) */
-  readonly STREAM_ID: "x-stream-id";
+  readonly STREAM_ID: "x-stream-id"; /** Client → server: scheme preference negotiation (RFC 7231-style q-values) */
+  readonly ACCEPT_PAYMENT: "accept-payment";
 };
 //#endregion
-export { S402_HEADERS, S402_VERSION, s402Discovery, s402EscrowExtra, s402EscrowPayload, s402ExactPayload, s402Mandate, s402MandateRequirements, s402PaymentPayload, s402PaymentPayloadBase, s402PaymentRequirements, s402PaymentSession, s402PrepaidExtra, s402PrepaidPayload, s402RegistryQuery, s402Scheme, s402ServiceEntry, s402SettleResponse, s402SettlementMode, s402StreamExtra, s402StreamPayload, s402UnlockExtra, s402UnlockPayload, s402VerifyResponse };
+export { S402_HEADERS, S402_VERSION, s402Discovery, s402EscrowExtra, s402EscrowPayload, s402ExactPayload, s402Mandate, s402MandateRequirements, s402PaymentPayload, s402PaymentPayloadBase, s402PaymentRequirements, s402PaymentSession, s402PrepaidExtra, s402PrepaidPayload, s402RegistryQuery, s402Scheme, s402ServiceEntry, s402SettleResponse, s402SettlementMode, s402SettlementOverrides, s402StreamExtra, s402StreamPayload, s402UnlockExtra, s402UnlockPayload, s402UptoExtra, s402UptoPayload, s402VerifyResponse };

package/dist/types.mjs

@@ -10,7 +10,8 @@ const S402_HEADERS = {
 	PAYMENT_REQUIRED: "payment-required",
 	PAYMENT: "x-payment",
 	PAYMENT_RESPONSE: "payment-response",
-	STREAM_ID: "x-stream-id"
+	STREAM_ID: "x-stream-id",
+	ACCEPT_PAYMENT: "accept-payment"
 };
 
 //#endregion

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "s402",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "type": "module",
-  "description": "s402 — Chain-agnostic HTTP 402 wire format. Types, HTTP encoding, and scheme registry for five payment schemes. Wire-compatible with x402. Zero runtime dependencies.",
+  "description": "s402 — Chain-agnostic HTTP 402 wire format. Types, HTTP encoding, and scheme registry for six payment schemes. Wire-compatible with x402. Zero runtime dependencies.",
   "license": "Apache-2.0",
   "author": "SweeInc <daniel@sweeinc.com> (https://s402-protocol.org)",
   "repository": {
@@ -75,6 +75,13 @@
       },
       "default": "./dist/compat.mjs"
     },
+    "./compat-mpp": {
+      "import": {
+        "types": "./dist/compat-mpp.d.mts",
+        "default": "./dist/compat-mpp.mjs"
+      },
+      "default": "./dist/compat-mpp.mjs"
+    },
     "./errors": {
       "import": {
         "types": "./dist/errors.d.mts",
@@ -89,6 +96,13 @@
       },
       "default": "./dist/receipts.mjs"
     },
+    "./extensions": {
+      "import": {
+        "types": "./dist/extensions.d.mts",
+        "default": "./dist/extensions.mjs"
+      },
+      "default": "./dist/extensions.mjs"
+    },
     "./test-utils": {
       "import": {
         "types": "./dist/test-utils.d.mts",

package/test/conformance/vectors/body-transport.json

@@ -73,6 +73,48 @@
     },
     "shouldReject": false
   },
+  {
+    "description": "Upto requirements body with estimatedAmount",
+    "input": {
+      "type": "requirements",
+      "value": {
+        "s402Version": "1",
+        "accepts": [
+          "upto"
+        ],
+        "network": "sui:mainnet",
+        "asset": "0x2::sui::SUI",
+        "amount": "1000000",
+        "payTo": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
+        "upto": {
+          "maxAmount": "10000000",
+          "settlementDeadlineMs": "1700000000000",
+          "usageReportUrl": "https://api.example.com/usage",
+          "estimatedAmount": "7500000"
+        }
+      }
+    },
+    "expected": {
+      "body": "{\"s402Version\":\"1\",\"accepts\":[\"upto\"],\"network\":\"sui:mainnet\",\"asset\":\"0x2::sui::SUI\",\"amount\":\"1000000\",\"payTo\":\"0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890\",\"upto\":{\"maxAmount\":\"10000000\",\"settlementDeadlineMs\":\"1700000000000\",\"usageReportUrl\":\"https://api.example.com/usage\",\"estimatedAmount\":\"7500000\"}}",
+      "decoded": {
+        "s402Version": "1",
+        "accepts": [
+          "upto"
+        ],
+        "network": "sui:mainnet",
+        "asset": "0x2::sui::SUI",
+        "amount": "1000000",
+        "payTo": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
+        "upto": {
+          "maxAmount": "10000000",
+          "settlementDeadlineMs": "1700000000000",
+          "usageReportUrl": "https://api.example.com/usage",
+          "estimatedAmount": "7500000"
+        }
+      }
+    },
+    "shouldReject": false
+  },
   {
     "description": "Payload body encode/decode",
     "input": {

package/test/conformance/vectors/compat-normalize.json

@@ -18,7 +18,8 @@
       "network": "sui:mainnet",
       "asset": "0x2::sui::SUI",
       "amount": "1000000",
-      "payTo": "0xrecipient123"
+      "payTo": "0xrecipient123",
+      "expiresAt": 1700000060000
     },
     "shouldReject": false
   },

package/test/conformance/vectors/payload-decode.json

@@ -47,6 +47,39 @@
     },
     "shouldReject": false
   },
+  {
+    "description": "Decode upto payload with settlementCeiling",
+    "input": {
+      "header": "eyJzNDAyVmVyc2lvbiI6IjEiLCJzY2hlbWUiOiJ1cHRvIiwicGF5bG9hZCI6eyJ0cmFuc2FjdGlvbiI6ImRYQjBiMTkwZUE9PSIsInNpZ25hdHVyZSI6ImRYQjBiMTl6YVdjPSIsIm1heEFtb3VudCI6IjEwMDAwMDAwIiwic2V0dGxlbWVudENlaWxpbmciOiI4MDAwMDAwIn19"
+    },
+    "expected": {
+      "s402Version": "1",
+      "scheme": "upto",
+      "payload": {
+        "transaction": "dXB0b190eA==",
+        "signature": "dXB0b19zaWc=",
+        "maxAmount": "10000000",
+        "settlementCeiling": "8000000"
+      }
+    },
+    "shouldReject": false
+  },
+  {
+    "description": "Decode upto payload without settlementCeiling",
+    "input": {
+      "header": "eyJzNDAyVmVyc2lvbiI6IjEiLCJzY2hlbWUiOiJ1cHRvIiwicGF5bG9hZCI6eyJ0cmFuc2FjdGlvbiI6ImRYQjBiMTkwZUE9PSIsInNpZ25hdHVyZSI6ImRYQjBiMTl6YVdjPSIsIm1heEFtb3VudCI6IjUwMDAwMDAifX0="
+    },
+    "expected": {
+      "s402Version": "1",
+      "scheme": "upto",
+      "payload": {
+        "transaction": "dXB0b190eA==",
+        "signature": "dXB0b19zaWc=",
+        "maxAmount": "5000000"
+      }
+    },
+    "shouldReject": false
+  },
   {
     "description": "Decode stream payload",
     "input": {

package/test/conformance/vectors/payload-encode.json

@@ -31,6 +31,39 @@
     },
     "shouldReject": false
   },
+  {
+    "description": "Upto payload with maxAmount and settlementCeiling",
+    "input": {
+      "s402Version": "1",
+      "scheme": "upto",
+      "payload": {
+        "transaction": "dXB0b190eA==",
+        "signature": "dXB0b19zaWc=",
+        "maxAmount": "10000000",
+        "settlementCeiling": "8000000"
+      }
+    },
+    "expected": {
+      "header": "eyJzNDAyVmVyc2lvbiI6IjEiLCJzY2hlbWUiOiJ1cHRvIiwicGF5bG9hZCI6eyJ0cmFuc2FjdGlvbiI6ImRYQjBiMTkwZUE9PSIsInNpZ25hdHVyZSI6ImRYQjBiMTl6YVdjPSIsIm1heEFtb3VudCI6IjEwMDAwMDAwIiwic2V0dGxlbWVudENlaWxpbmciOiI4MDAwMDAwIn19"
+    },
+    "shouldReject": false
+  },
+  {
+    "description": "Upto payload without settlementCeiling (backwards compatible)",
+    "input": {
+      "s402Version": "1",
+      "scheme": "upto",
+      "payload": {
+        "transaction": "dXB0b190eA==",
+        "signature": "dXB0b19zaWc=",
+        "maxAmount": "5000000"
+      }
+    },
+    "expected": {
+      "header": "eyJzNDAyVmVyc2lvbiI6IjEiLCJzY2hlbWUiOiJ1cHRvIiwicGF5bG9hZCI6eyJ0cmFuc2FjdGlvbiI6ImRYQjBiMTkwZUE9PSIsInNpZ25hdHVyZSI6ImRYQjBiMTl6YVdjPSIsIm1heEFtb3VudCI6IjUwMDAwMDAifX0="
+    },
+    "shouldReject": false
+  },
   {
     "description": "Stream payload",
     "input": {

package/test/conformance/vectors/requirements-decode.json

@@ -38,6 +38,50 @@
     },
     "shouldReject": false
   },
+  {
+    "description": "Decode upto scheme with estimatedAmount",
+    "input": {
+      "header": "eyJzNDAyVmVyc2lvbiI6IjEiLCJhY2NlcHRzIjpbInVwdG8iXSwibmV0d29yayI6InN1aTptYWlubmV0IiwiYXNzZXQiOiIweDI6OnN1aTo6U1VJIiwiYW1vdW50IjoiMTAwMDAwMCIsInBheVRvIjoiMHhhYmNkZWYxMjM0NTY3ODkwYWJjZGVmMTIzNDU2Nzg5MGFiY2RlZjEyMzQ1Njc4OTBhYmNkZWYxMjM0NTY3ODkwIiwidXB0byI6eyJtYXhBbW91bnQiOiIxMDAwMDAwMCIsInNldHRsZW1lbnREZWFkbGluZU1zIjoiMTcwMDAwMDAwMDAwMCIsInVzYWdlUmVwb3J0VXJsIjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20vdXNhZ2UiLCJlc3RpbWF0ZWRBbW91bnQiOiI3NTAwMDAwIn19"
+    },
+    "expected": {
+      "s402Version": "1",
+      "accepts": [
+        "upto"
+      ],
+      "network": "sui:mainnet",
+      "asset": "0x2::sui::SUI",
+      "amount": "1000000",
+      "payTo": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
+      "upto": {
+        "maxAmount": "10000000",
+        "settlementDeadlineMs": "1700000000000",
+        "usageReportUrl": "https://api.example.com/usage",
+        "estimatedAmount": "7500000"
+      }
+    },
+    "shouldReject": false
+  },
+  {
+    "description": "Decode upto scheme minimal",
+    "input": {
+      "header": "eyJzNDAyVmVyc2lvbiI6IjEiLCJhY2NlcHRzIjpbInVwdG8iXSwibmV0d29yayI6InN1aTptYWlubmV0IiwiYXNzZXQiOiIweDI6OnN1aTo6U1VJIiwiYW1vdW50IjoiMTAwMDAwMCIsInBheVRvIjoiMHhhYmNkZWYxMjM0NTY3ODkwYWJjZGVmMTIzNDU2Nzg5MGFiY2RlZjEyMzQ1Njc4OTBhYmNkZWYxMjM0NTY3ODkwIiwidXB0byI6eyJtYXhBbW91bnQiOiI1MDAwMDAwIiwic2V0dGxlbWVudERlYWRsaW5lTXMiOiIxNzAwMDAwMDAwMDAwIn19"
+    },
+    "expected": {
+      "s402Version": "1",
+      "accepts": [
+        "upto"
+      ],
+      "network": "sui:mainnet",
+      "asset": "0x2::sui::SUI",
+      "amount": "1000000",
+      "payTo": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
+      "upto": {
+        "maxAmount": "5000000",
+        "settlementDeadlineMs": "1700000000000"
+      }
+    },
+    "shouldReject": false
+  },
   {
     "description": "Decode escrow scheme",
     "input": {

package/test/conformance/vectors/requirements-encode.json

@@ -38,6 +38,50 @@
     },
     "shouldReject": false
   },
+  {
+    "description": "Upto scheme with estimatedAmount",
+    "input": {
+      "s402Version": "1",
+      "accepts": [
+        "upto"
+      ],
+      "network": "sui:mainnet",
+      "asset": "0x2::sui::SUI",
+      "amount": "1000000",
+      "payTo": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
+      "upto": {
+        "maxAmount": "10000000",
+        "settlementDeadlineMs": "1700000000000",
+        "usageReportUrl": "https://api.example.com/usage",
+        "estimatedAmount": "7500000"
+      }
+    },
+    "expected": {
+      "header": "eyJzNDAyVmVyc2lvbiI6IjEiLCJhY2NlcHRzIjpbInVwdG8iXSwibmV0d29yayI6InN1aTptYWlubmV0IiwiYXNzZXQiOiIweDI6OnN1aTo6U1VJIiwiYW1vdW50IjoiMTAwMDAwMCIsInBheVRvIjoiMHhhYmNkZWYxMjM0NTY3ODkwYWJjZGVmMTIzNDU2Nzg5MGFiY2RlZjEyMzQ1Njc4OTBhYmNkZWYxMjM0NTY3ODkwIiwidXB0byI6eyJtYXhBbW91bnQiOiIxMDAwMDAwMCIsInNldHRsZW1lbnREZWFkbGluZU1zIjoiMTcwMDAwMDAwMDAwMCIsInVzYWdlUmVwb3J0VXJsIjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20vdXNhZ2UiLCJlc3RpbWF0ZWRBbW91bnQiOiI3NTAwMDAwIn19"
+    },
+    "shouldReject": false
+  },
+  {
+    "description": "Upto scheme minimal (no estimatedAmount)",
+    "input": {
+      "s402Version": "1",
+      "accepts": [
+        "upto"
+      ],
+      "network": "sui:mainnet",
+      "asset": "0x2::sui::SUI",
+      "amount": "1000000",
+      "payTo": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
+      "upto": {
+        "maxAmount": "5000000",
+        "settlementDeadlineMs": "1700000000000"
+      }
+    },
+    "expected": {
+      "header": "eyJzNDAyVmVyc2lvbiI6IjEiLCJhY2NlcHRzIjpbInVwdG8iXSwibmV0d29yayI6InN1aTptYWlubmV0IiwiYXNzZXQiOiIweDI6OnN1aTo6U1VJIiwiYW1vdW50IjoiMTAwMDAwMCIsInBheVRvIjoiMHhhYmNkZWYxMjM0NTY3ODkwYWJjZGVmMTIzNDU2Nzg5MGFiY2RlZjEyMzQ1Njc4OTBhYmNkZWYxMjM0NTY3ODkwIiwidXB0byI6eyJtYXhBbW91bnQiOiI1MDAwMDAwIiwic2V0dGxlbWVudERlYWRsaW5lTXMiOiIxNzAwMDAwMDAwMDAwIn19"
+    },
+    "shouldReject": false
+  },
   {
     "description": "Escrow scheme with extras",
     "input": {

package/test/conformance/vectors/roundtrip.json

@@ -123,6 +123,58 @@
     },
     "shouldReject": false
   },
+  {
+    "description": "Upto requirements with estimatedAmount roundtrip",
+    "input": {
+      "type": "requirements",
+      "transport": "header",
+      "value": {
+        "s402Version": "1",
+        "accepts": [
+          "upto"
+        ],
+        "network": "sui:mainnet",
+        "asset": "0x2::sui::SUI",
+        "amount": "1000000",
+        "payTo": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
+        "upto": {
+          "maxAmount": "10000000",
+          "settlementDeadlineMs": "1700000000000",
+          "usageReportUrl": "https://api.example.com/usage",
+          "estimatedAmount": "7500000"
+        }
+      }
+    },
+    "expected": {
+      "firstEncode": "eyJzNDAyVmVyc2lvbiI6IjEiLCJhY2NlcHRzIjpbInVwdG8iXSwibmV0d29yayI6InN1aTptYWlubmV0IiwiYXNzZXQiOiIweDI6OnN1aTo6U1VJIiwiYW1vdW50IjoiMTAwMDAwMCIsInBheVRvIjoiMHhhYmNkZWYxMjM0NTY3ODkwYWJjZGVmMTIzNDU2Nzg5MGFiY2RlZjEyMzQ1Njc4OTBhYmNkZWYxMjM0NTY3ODkwIiwidXB0byI6eyJtYXhBbW91bnQiOiIxMDAwMDAwMCIsInNldHRsZW1lbnREZWFkbGluZU1zIjoiMTcwMDAwMDAwMDAwMCIsInVzYWdlUmVwb3J0VXJsIjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20vdXNhZ2UiLCJlc3RpbWF0ZWRBbW91bnQiOiI3NTAwMDAwIn19",
+      "reEncode": "eyJzNDAyVmVyc2lvbiI6IjEiLCJhY2NlcHRzIjpbInVwdG8iXSwibmV0d29yayI6InN1aTptYWlubmV0IiwiYXNzZXQiOiIweDI6OnN1aTo6U1VJIiwiYW1vdW50IjoiMTAwMDAwMCIsInBheVRvIjoiMHhhYmNkZWYxMjM0NTY3ODkwYWJjZGVmMTIzNDU2Nzg5MGFiY2RlZjEyMzQ1Njc4OTBhYmNkZWYxMjM0NTY3ODkwIiwidXB0byI6eyJtYXhBbW91bnQiOiIxMDAwMDAwMCIsInNldHRsZW1lbnREZWFkbGluZU1zIjoiMTcwMDAwMDAwMDAwMCIsInVzYWdlUmVwb3J0VXJsIjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20vdXNhZ2UiLCJlc3RpbWF0ZWRBbW91bnQiOiI3NTAwMDAwIn19",
+      "identical": true
+    },
+    "shouldReject": false
+  },
+  {
+    "description": "Upto payload with settlementCeiling roundtrip",
+    "input": {
+      "type": "payload",
+      "transport": "header",
+      "value": {
+        "s402Version": "1",
+        "scheme": "upto",
+        "payload": {
+          "transaction": "dXB0b190eA==",
+          "signature": "dXB0b19zaWc=",
+          "maxAmount": "10000000",
+          "settlementCeiling": "8000000"
+        }
+      }
+    },
+    "expected": {
+      "firstEncode": "eyJzNDAyVmVyc2lvbiI6IjEiLCJzY2hlbWUiOiJ1cHRvIiwicGF5bG9hZCI6eyJ0cmFuc2FjdGlvbiI6ImRYQjBiMTkwZUE9PSIsInNpZ25hdHVyZSI6ImRYQjBiMTl6YVdjPSIsIm1heEFtb3VudCI6IjEwMDAwMDAwIiwic2V0dGxlbWVudENlaWxpbmciOiI4MDAwMDAwIn19",
+      "reEncode": "eyJzNDAyVmVyc2lvbiI6IjEiLCJzY2hlbWUiOiJ1cHRvIiwicGF5bG9hZCI6eyJ0cmFuc2FjdGlvbiI6ImRYQjBiMTkwZUE9PSIsInNpZ25hdHVyZSI6ImRYQjBiMTl6YVdjPSIsIm1heEFtb3VudCI6IjEwMDAwMDAwIiwic2V0dGxlbWVudENlaWxpbmciOiI4MDAwMDAwIn19",
+      "identical": true
+    },
+    "shouldReject": false
+  },
   {
     "description": "Complex requirements with extensions roundtrip",
     "input": {