s402 0.1.8 → 0.2.0

package/CHANGELOG.md

@@ -5,6 +5,45 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2026-03-01
+
+### Added
+
+- **Receipt HTTP helpers** — `s402/receipts` sub-path export with `formatReceiptHeader()`, `parseReceiptHeader()`, `S402_RECEIPT_HEADER`. Chain-agnostic receipt wire format (`v2:base64(sig):callNumber:timestampMs:base64(hash)`) for v0.2 signed usage receipts.
+- **S7 chain-agnostic boundary invariant** — formal safety invariant enforced by `test/boundary.test.ts`. Greps `src/` for chain-specific patterns (Sui address regex, Solana base58, Ethereum imports) and fails the build if any are found.
+- **v0.2 prepaid type extensions** — `providerPubkey` and `disputeWindowMs` fields on `s402PrepaidExtra` for signed receipt mode.
+- **Body transport** — `application/s402+json` content type for large payloads that don't fit in HTTP headers.
+- **Formal safety invariants** (S1-S7) documented in AGENTS.md.
+
+### Fixed
+
+- **Chain-agnostic payTo/protocolFeeAddress validation** — removed Sui-specific address regex (`/^0x[0-9a-fA-F]{64}$/`) from `http.ts`. Replaced with chain-agnostic checks (non-empty string, no control characters). Chain-specific validation belongs in `@sweefi/sui`.
+- **x402 compat validation parity** — `normalizeRequirements()` now runs `validateRequirementsShape()` on x402 conversion output, ensuring identical validation regardless of input format.
+- **Prepaid pairing invariant enforcement** — `providerPubkey` and `disputeWindowMs` must both be present (v0.2) or both absent (v0.1). Was documented in JSDoc but not enforced at wire decode.
+- **Receipt BigInt coercion** — `parseReceiptHeader()` rejects empty strings and whitespace-only strings that JavaScript's `BigInt()` would silently coerce to `0n`.
+- **Removed Sui default for `asset`** — `s402RouteConfig.asset` is now required (was optional with `'0x2::sui::SUI'` default). Chain-specific defaults don't belong in the protocol layer.
+
+### Changed
+
+- **BREAKING**: `s402RouteConfig.asset` is now required (was optional).
+- JSDoc on `s402PaymentRequirements` updated to chain-agnostic wording (network, asset, amount fields).
+- 258 tests across 11 suites (was 207 at v0.1.0).
+
+## [0.1.8] - 2026-02-27
+
+### Added
+
+- Body transport (`application/s402+json`) for large payloads
+- v0.2 prepaid type extensions (`providerPubkey`, `disputeWindowMs`)
+- `FUNDING.yml` and cross-linked SweeFi in README
+
+## [0.1.7] - 2026-02-25
+
+### Added
+
+- Formal safety invariants (Lamport-style proofs)
+- `isValidU64Amount()` magnitude checks
+
 ## [0.1.6] - 2026-02-19
 
 ### Fixed
@@ -77,6 +116,9 @@ _Version bump for npm publish after license change._
 - Property-based fuzz testing via fast-check
 - 207 tests, zero runtime dependencies
 
+[0.2.0]: https://github.com/s402-protocol/core/compare/v0.1.8...v0.2.0
+[0.1.8]: https://github.com/s402-protocol/core/compare/v0.1.7...v0.1.8
+[0.1.7]: https://github.com/s402-protocol/core/compare/v0.1.6...v0.1.7
 [0.1.6]: https://github.com/s402-protocol/core/compare/v0.1.5...v0.1.6
 [0.1.5]: https://github.com/s402-protocol/core/compare/v0.1.4...v0.1.5
 [0.1.4]: https://github.com/s402-protocol/core/compare/v0.1.3...v0.1.4

package/README.md

@@ -5,7 +5,7 @@
 
 **Sui-native HTTP 402 protocol.** Atomic settlement via Sui's Programmable Transaction Blocks (PTBs). Includes an optional compat layer (`s402/compat`) for normalizing x402 input.
 
-s402 is the Sui-native implementation of HTTP 402 (Payment Required) — an open protocol that lets AI agents pay for API calls in a single HTTP request with no per-call on-chain transaction. Unlike Coinbase's x402 on Ethereum, s402 uses Sui's Programmable Transaction Blocks to reduce 1,000 payments to just 2 on-chain transactions via the Prepaid scheme, cutting per-call effective gas from $0.007 to $0.000014 and making micropayments economically viable for AI agents for the first time.
+s402 is the Sui-native implementation of HTTP 402 (Payment Required) — an open protocol that lets AI agents pay for API calls in a single HTTP request with no per-call on-chain transaction. Unlike Coinbase's x402 on Base (EVM L2), s402 uses Sui's Programmable Transaction Blocks to reduce 1,000 payments to just 2 on-chain transactions via the Prepaid scheme, cutting per-call effective gas from $0.007 to $0.000014 and making micropayments economically viable for AI agents for the first time.
 
 ```bash
 npm install s402
@@ -27,7 +27,7 @@ HTTP 402 ("Payment Required") has been reserved since 1999 — waiting for a pay
 | **Settlement** | Two-step: verify then settle (temporal gap) | Atomic: verify + settle in one PTB |
 | **Finality** | 12+ second blocks (EVM L1) | ~400ms (Sui) |
 | **Payment models** | Exact (one-shot) only | Five schemes: Exact, Prepaid, Escrow, Unlock, Stream |
-| **Micro-payments** | $7.00 gas per 1K calls (broken) | $0.014 gas per 1K calls (prepaid) |
+| **Micro-payments** | ~$1.60 gas per 1K calls on Base (broken) | $0.014 gas per 1K calls (prepaid) |
 | **Coin handling** | approve + transferFrom | Native `coinWithBalance` + `splitCoins` |
 | **Agent auth** | None | AP2 mandate delegation |
 | **Direct mode** | No | Yes (no facilitator needed) |
@@ -325,6 +325,11 @@ const requirements: s402PaymentRequirements = {
 
 5. **Errors tell you what to do.** Every error code includes `retryable` (can the client try again?) and `suggestedAction` (what should it do?). Agents can self-recover.
 
+## Related
+
+- **[SweeFi](https://github.com/sweeinc/sweefi)** — Open-source payment SDK built on s402. 10 packages including PTB builders, MCP tools, CLI, and UI components.
+- **[Sui Gas Station](https://github.com/Danny-Devs/sui-gas-station)** — Sponsored transaction infrastructure for Sui.
+
 ## License
 
 Apache-2.0 — see [LICENSE](./LICENSE) for details.

package/dist/compat.mjs

@@ -133,10 +133,16 @@ function normalizeRequirements(obj) {
 		validateRequirementsShape(obj);
 		return pickRequirementsFields(obj);
 	}
-	if (isX402Envelope(obj)) return fromX402Envelope(obj);
+	if (isX402Envelope(obj)) {
+		const record = fromX402Envelope(obj);
+		validateRequirementsShape(record);
+		return pickRequirementsFields(record);
+	}
 	if (isX402(obj)) {
 		validateX402Shape(obj);
-		return fromX402Requirements(obj);
+		const record = fromX402Requirements(obj);
+		validateRequirementsShape(record);
+		return pickRequirementsFields(record);
 	}
 	throw new s402Error("INVALID_PAYLOAD", "Unrecognized payment requirements format: missing s402Version or x402Version");
 }

package/dist/http.mjs

@@ -318,10 +318,16 @@ function validatePrepaidShape(value) {
 	assertString(obj, "minDeposit", "prepaid");
 	if (typeof obj.minDeposit === "string" && !isValidAmount(obj.minDeposit)) throw new s402Error("INVALID_PAYLOAD", `prepaid.minDeposit must be a non-negative integer string, got "${obj.minDeposit}"`);
 	assertString(obj, "withdrawalDelayMs", "prepaid");
-	if (typeof obj.withdrawalDelayMs === "string" && !isValidAmount(obj.withdrawalDelayMs)) throw new s402Error("INVALID_PAYLOAD", `prepaid.withdrawalDelayMs must be a non-negative integer string (milliseconds), got "${obj.withdrawalDelayMs}"`);
+	if (typeof obj.withdrawalDelayMs === "string") {
+		if (!isValidAmount(obj.withdrawalDelayMs)) throw new s402Error("INVALID_PAYLOAD", `prepaid.withdrawalDelayMs must be a non-negative integer string (milliseconds), got "${obj.withdrawalDelayMs}"`);
+		const delayMs = BigInt(obj.withdrawalDelayMs);
+		if (delayMs < 60000n || delayMs > 604800000n) throw new s402Error("INVALID_PAYLOAD", `prepaid.withdrawalDelayMs must be between 60000 (1 min) and 604800000 (7 days), got "${obj.withdrawalDelayMs}"`);
+	}
 	assertOptionalString(obj, "maxCalls", "prepaid");
 	assertOptionalString(obj, "providerPubkey", "prepaid");
 	assertOptionalString(obj, "disputeWindowMs", "prepaid");
+	const hasPubkey = typeof obj.providerPubkey === "string";
+	if (hasPubkey !== (typeof obj.disputeWindowMs === "string")) throw new s402Error("INVALID_PAYLOAD", `prepaid: providerPubkey and disputeWindowMs must both be present (v0.2) or both absent (v0.1), got ${hasPubkey ? "providerPubkey only" : "disputeWindowMs only"}`);
 }
 /**
 * Validate all optional sub-objects on a requirements record.
@@ -347,10 +353,11 @@ function validateRequirementsShape(obj) {
 	if (typeof record.amount !== "string") missing.push("amount (string)");
 	else if (!isValidU64Amount(record.amount)) throw new s402Error("INVALID_PAYLOAD", `Invalid amount "${record.amount}": must be a non-negative integer string within u64 range`);
 	if (typeof record.payTo !== "string") missing.push("payTo (string)");
-	else if (!/^0x[0-9a-fA-F]{64}$/.test(record.payTo)) throw new s402Error("INVALID_PAYLOAD", `payTo must be a 32-byte Sui address (0x + 64 hex chars), got "${record.payTo.substring(0, 20)}..."`);
+	else if (record.payTo.length === 0) throw new s402Error("INVALID_PAYLOAD", "payTo must be a non-empty string");
 	if (missing.length > 0) throw new s402Error("INVALID_PAYLOAD", `Malformed payment requirements: missing ${missing.join(", ")}`);
 	if (/[\x00-\x1f\x7f]/.test(record.network)) throw new s402Error("INVALID_PAYLOAD", "network contains control characters");
 	if (/[\x00-\x1f\x7f]/.test(record.asset)) throw new s402Error("INVALID_PAYLOAD", "asset contains control characters");
+	if (/[\x00-\x1f\x7f]/.test(record.payTo)) throw new s402Error("INVALID_PAYLOAD", "payTo contains control characters");
 	if (Array.isArray(record.accepts) && record.accepts.length === 0) throw new s402Error("INVALID_PAYLOAD", "accepts array must contain at least one scheme");
 	const accepts = record.accepts;
 	for (const scheme of accepts) if (typeof scheme !== "string") throw new s402Error("INVALID_PAYLOAD", `Invalid entry in accepts array: expected string, got ${typeof scheme}`);
@@ -361,7 +368,8 @@ function validateRequirementsShape(obj) {
 		if (typeof record.expiresAt !== "number" || !Number.isFinite(record.expiresAt) || record.expiresAt <= 0) throw new s402Error("INVALID_PAYLOAD", `expiresAt must be a positive finite number (Unix timestamp ms), got ${record.expiresAt}`);
 	}
 	if (record.protocolFeeAddress !== void 0) {
-		if (typeof record.protocolFeeAddress !== "string" || !/^0x[0-9a-fA-F]{64}$/.test(record.protocolFeeAddress)) throw new s402Error("INVALID_PAYLOAD", `protocolFeeAddress must be a 32-byte Sui address (0x + 64 hex chars), got "${String(record.protocolFeeAddress).substring(0, 20)}..."`);
+		if (typeof record.protocolFeeAddress !== "string" || record.protocolFeeAddress.length === 0) throw new s402Error("INVALID_PAYLOAD", `protocolFeeAddress must be a non-empty string, got ${JSON.stringify(record.protocolFeeAddress)}`);
+		if (/[\x00-\x1f\x7f]/.test(record.protocolFeeAddress)) throw new s402Error("INVALID_PAYLOAD", "protocolFeeAddress contains control characters");
 	}
 	if (record.facilitatorUrl !== void 0) {
 		if (typeof record.facilitatorUrl !== "string") throw new s402Error("INVALID_PAYLOAD", `facilitatorUrl must be a string, got ${typeof record.facilitatorUrl}`);

package/dist/index.d.mts

@@ -1,6 +1,7 @@
 import { createS402Error, s402Error, s402ErrorCode, s402ErrorCodeType, s402ErrorInfo } from "./errors.mjs";
 import { 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 } from "./types.mjs";
 import { S402_CONTENT_TYPE, decodePayloadBody, decodePaymentPayload, decodePaymentRequired, decodeRequirementsBody, decodeSettleBody, decodeSettleResponse, detectProtocol, detectTransport, encodePayloadBody, encodePaymentPayload, encodePaymentRequired, encodeRequirementsBody, encodeSettleBody, encodeSettleResponse, extractRequirementsFromResponse, isValidAmount, isValidU64Amount, validateRequirementsShape } from "./http.mjs";
+import { S402_RECEIPT_HEADER, formatReceiptHeader, parseReceiptHeader, s402Receipt, s402ReceiptSigner, s402ReceiptVerifier } from "./receipts.mjs";
 
 //#region src/scheme.d.ts
 /** Implemented by each scheme on the client side */
@@ -49,14 +50,14 @@ interface s402DirectScheme {
 interface s402RouteConfig {
   /** Which payment scheme(s) to accept. Always includes "exact" for x402 compat. */
   schemes: s402Scheme[];
-  /** Amount in base units, same as wire format (e.g., "1000000" for 0.001 SUI in MIST) */
+  /** Amount in base units, same as wire format (e.g., "1000000") */
   price: string;
-  /** Sui network */
+  /** Network identifier (e.g., "sui:mainnet", "solana:mainnet-beta") */
   network: string;
-  /** Recipient address */
+  /** Recipient address (chain-specific format, validated by chain adapter) */
   payTo: string;
-  /** Move coin type */
-  asset?: string;
+  /** Asset/coin type identifier (chain-specific, e.g., Sui Move type or Solana mint address) */
+  asset: string;
   /** Facilitator URL (optional for direct settlement) */
   facilitatorUrl?: string;
   /** Settlement mode preference */
@@ -89,7 +90,9 @@ interface s402RouteConfig {
     ratePerCall: string;
     maxCalls?: string;
     minDeposit: string;
-    withdrawalDelayMs: 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
@@ -192,4 +195,4 @@ declare class s402ResourceServer {
   process(payload: s402PaymentPayload, requirements: s402PaymentRequirements): Promise<s402SettleResponse>;
 }
 //#endregion
-export { S402_CONTENT_TYPE, S402_HEADERS, S402_VERSION, createS402Error, decodePayloadBody, decodePaymentPayload, decodePaymentRequired, decodeRequirementsBody, decodeSettleBody, decodeSettleResponse, detectProtocol, detectTransport, encodePayloadBody, encodePaymentPayload, encodePaymentRequired, encodeRequirementsBody, encodeSettleBody, encodeSettleResponse, extractRequirementsFromResponse, isValidAmount, isValidU64Amount, s402Client, type s402ClientScheme, type s402DirectScheme, type s402Discovery, s402Error, s402ErrorCode, type s402ErrorCodeType, type s402ErrorInfo, type s402EscrowExtra, type s402EscrowPayload, type s402ExactPayload, s402Facilitator, type s402FacilitatorScheme, type s402Mandate, type s402MandateRequirements, type s402PaymentPayload, type s402PaymentPayloadBase, type s402PaymentRequirements, type s402PaymentSession, type s402PrepaidExtra, type s402PrepaidPayload, type s402RegistryQuery, s402ResourceServer, type s402RouteConfig, type s402Scheme, type s402ServerScheme, type s402ServiceEntry, type s402SettleResponse, type s402SettlementMode, type s402StreamExtra, type s402StreamPayload, type s402UnlockExtra, type s402UnlockPayload, type s402VerifyResponse, validateRequirementsShape };
+export { S402_CONTENT_TYPE, S402_HEADERS, S402_RECEIPT_HEADER, S402_VERSION, createS402Error, decodePayloadBody, decodePaymentPayload, decodePaymentRequired, decodeRequirementsBody, decodeSettleBody, decodeSettleResponse, detectProtocol, detectTransport, encodePayloadBody, encodePaymentPayload, encodePaymentRequired, encodeRequirementsBody, encodeSettleBody, encodeSettleResponse, extractRequirementsFromResponse, formatReceiptHeader, isValidAmount, isValidU64Amount, parseReceiptHeader, s402Client, type s402ClientScheme, type s402DirectScheme, type s402Discovery, s402Error, s402ErrorCode, type s402ErrorCodeType, type s402ErrorInfo, type s402EscrowExtra, type s402EscrowPayload, type s402ExactPayload, s402Facilitator, type s402FacilitatorScheme, type s402Mandate, type s402MandateRequirements, type s402PaymentPayload, type s402PaymentPayloadBase, type s402PaymentRequirements, type s402PaymentSession, type s402PrepaidExtra, type s402PrepaidPayload, type s402Receipt, type s402ReceiptSigner, type s402ReceiptVerifier, type s402RegistryQuery, s402ResourceServer, type s402RouteConfig, type s402Scheme, type s402ServerScheme, type s402ServiceEntry, type s402SettleResponse, type s402SettlementMode, type s402StreamExtra, type s402StreamPayload, type s402UnlockExtra, type s402UnlockPayload, type s402VerifyResponse, validateRequirementsShape };

package/dist/index.mjs

@@ -1,6 +1,7 @@
 import { S402_HEADERS, S402_VERSION } from "./types.mjs";
 import { createS402Error, s402Error, s402ErrorCode } from "./errors.mjs";
 import { S402_CONTENT_TYPE, decodePayloadBody, decodePaymentPayload, decodePaymentRequired, decodeRequirementsBody, decodeSettleBody, decodeSettleResponse, detectProtocol, detectTransport, encodePayloadBody, encodePaymentPayload, encodePaymentRequired, encodeRequirementsBody, encodeSettleBody, encodeSettleResponse, extractRequirementsFromResponse, isValidAmount, isValidU64Amount, validateRequirementsShape } from "./http.mjs";
+import { S402_RECEIPT_HEADER, formatReceiptHeader, parseReceiptHeader } from "./receipts.mjs";
 
 //#region src/client.ts
 var s402Client = class {
@@ -81,7 +82,7 @@ var s402ResourceServer = class {
 			s402Version: S402_VERSION,
 			accepts: [...new Set([...config.schemes, "exact"])],
 			network: config.network,
-			asset: config.asset ?? "0x2::sui::SUI",
+			asset: config.asset,
 			amount: config.price,
 			payTo: config.payTo,
 			facilitatorUrl: config.facilitatorUrl,
@@ -317,4 +318,4 @@ var s402Facilitator = class {
 };
 
 //#endregion
-export { S402_CONTENT_TYPE, S402_HEADERS, S402_VERSION, createS402Error, decodePayloadBody, decodePaymentPayload, decodePaymentRequired, decodeRequirementsBody, decodeSettleBody, decodeSettleResponse, detectProtocol, detectTransport, encodePayloadBody, encodePaymentPayload, encodePaymentRequired, encodeRequirementsBody, encodeSettleBody, encodeSettleResponse, extractRequirementsFromResponse, isValidAmount, isValidU64Amount, s402Client, s402Error, s402ErrorCode, s402Facilitator, s402ResourceServer, validateRequirementsShape };
+export { S402_CONTENT_TYPE, S402_HEADERS, S402_RECEIPT_HEADER, S402_VERSION, createS402Error, decodePayloadBody, decodePaymentPayload, decodePaymentRequired, decodeRequirementsBody, decodeSettleBody, decodeSettleResponse, detectProtocol, detectTransport, encodePayloadBody, encodePaymentPayload, encodePaymentRequired, encodeRequirementsBody, encodeSettleBody, encodeSettleResponse, extractRequirementsFromResponse, formatReceiptHeader, isValidAmount, isValidU64Amount, parseReceiptHeader, s402Client, s402Error, s402ErrorCode, s402Facilitator, s402ResourceServer, validateRequirementsShape };

package/dist/receipts.d.mts

@@ -0,0 +1,61 @@
+//#region src/receipts.d.ts
+/**
+ * s402 Receipt HTTP Helpers — chain-agnostic receipt header format/parse.
+ *
+ * Providers sign each API response with Ed25519. The signature, call number,
+ * timestamp, and response hash are transported as a single HTTP header:
+ *
+ *   X-S402-Receipt: v2:base64(signature):callNumber:timestampMs:base64(responseHash)
+ *
+ * This module handles the header wire format ONLY. It does not:
+ * - Construct BCS messages (chain-specific — see @sweefi/sui receipts.ts)
+ * - Generate Ed25519 keys (implementations provide their own)
+ * - Accumulate receipts (client-side concern — see @sweefi/sui ReceiptAccumulator)
+ *
+ * Zero runtime dependencies. Uses built-in btoa/atob.
+ *
+ * @see docs/schemes/prepaid.md — v0.2 spec
+ */
+/** Receipt data extracted from an HTTP header. */
+interface s402Receipt {
+  /** Header version — always 'v2' for signed receipts. */
+  version: 'v2';
+  /** 64-byte Ed25519 signature over the BCS-encoded receipt message. */
+  signature: Uint8Array;
+  /** Sequential call number (1-indexed). */
+  callNumber: bigint;
+  /** Unix timestamp in milliseconds when the response was generated. */
+  timestampMs: bigint;
+  /** Hash of the response body (typically SHA-256, 32 bytes). */
+  responseHash: Uint8Array;
+}
+/** Signing function — implementations inject their own Ed25519 signer. */
+type s402ReceiptSigner = (message: Uint8Array) => Promise<Uint8Array>;
+/** Verification function — implementations inject their own Ed25519 verifier. */
+type s402ReceiptVerifier = (message: Uint8Array, signature: Uint8Array) => Promise<boolean>;
+/** HTTP header name for s402 signed usage receipts. */
+declare const S402_RECEIPT_HEADER = "X-S402-Receipt";
+/**
+ * Encode receipt fields into the `X-S402-Receipt` HTTP header value.
+ *
+ * Format: `v2:base64(signature):callNumber:timestampMs:base64(responseHash)`
+ *
+ * @param receipt - Receipt fields to encode
+ * @returns Header string ready for HTTP response
+ */
+declare function formatReceiptHeader(receipt: {
+  signature: Uint8Array;
+  callNumber: bigint;
+  timestampMs: bigint;
+  responseHash: Uint8Array;
+}): string;
+/**
+ * Decode an `X-S402-Receipt` header value back into typed fields.
+ *
+ * @param header - Raw header value string
+ * @returns Parsed receipt with typed fields
+ * @throws On empty string, wrong number of parts, or unknown version
+ */
+declare function parseReceiptHeader(header: string): s402Receipt;
+//#endregion
+export { S402_RECEIPT_HEADER, formatReceiptHeader, parseReceiptHeader, s402Receipt, s402ReceiptSigner, s402ReceiptVerifier };

package/dist/receipts.mjs

@@ -0,0 +1,62 @@
+//#region src/receipts.ts
+/** HTTP header name for s402 signed usage receipts. */
+const S402_RECEIPT_HEADER = "X-S402-Receipt";
+const HEADER_VERSION = "v2";
+/** Encode a Uint8Array to base64 using built-in btoa. */
+function uint8ToBase64(bytes) {
+	let binary = "";
+	for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+	return btoa(binary);
+}
+/** Decode a base64 string to Uint8Array using built-in atob. */
+function base64ToUint8(b64) {
+	const binary = atob(b64);
+	const bytes = new Uint8Array(binary.length);
+	for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+	return bytes;
+}
+/**
+* Encode receipt fields into the `X-S402-Receipt` HTTP header value.
+*
+* Format: `v2:base64(signature):callNumber:timestampMs:base64(responseHash)`
+*
+* @param receipt - Receipt fields to encode
+* @returns Header string ready for HTTP response
+*/
+function formatReceiptHeader(receipt) {
+	return [
+		HEADER_VERSION,
+		uint8ToBase64(receipt.signature),
+		receipt.callNumber.toString(),
+		receipt.timestampMs.toString(),
+		uint8ToBase64(receipt.responseHash)
+	].join(":");
+}
+/**
+* Decode an `X-S402-Receipt` header value back into typed fields.
+*
+* @param header - Raw header value string
+* @returns Parsed receipt with typed fields
+* @throws On empty string, wrong number of parts, or unknown version
+*/
+function parseReceiptHeader(header) {
+	if (!header) throw new Error("Empty receipt header");
+	const parts = header.split(":");
+	if (parts.length !== 5) throw new Error(`Malformed receipt header: expected 5 colon-separated parts, got ${parts.length}`);
+	const [version, sigB64, callNumberStr, timestampMsStr, hashB64] = parts;
+	if (version !== HEADER_VERSION) throw new Error(`Unknown receipt header version: "${version}" (expected "${HEADER_VERSION}")`);
+	const callNumber = BigInt(callNumberStr);
+	const timestampMs = BigInt(timestampMsStr);
+	if (callNumber <= 0n) throw new Error(`Invalid receipt callNumber: must be positive, got ${callNumber}`);
+	if (timestampMs <= 0n) throw new Error(`Invalid receipt timestampMs: must be positive, got ${timestampMs}`);
+	return {
+		version: "v2",
+		signature: base64ToUint8(sigB64),
+		callNumber,
+		timestampMs,
+		responseHash: base64ToUint8(hashB64)
+	};
+}
+
+//#endregion
+export { S402_RECEIPT_HEADER, formatReceiptHeader, parseReceiptHeader };

package/dist/types.d.mts

@@ -16,11 +16,11 @@ interface s402PaymentRequirements {
   s402Version: typeof S402_VERSION;
   /** Which payment schemes the server accepts. Always includes "exact" for x402 compat. */
   accepts: s402Scheme[];
-  /** Sui network (e.g., "sui:testnet", "sui:mainnet") */
+  /** Network identifier (e.g., "sui:mainnet", "solana:mainnet-beta", "eip155:8453") */
   network: string;
-  /** Move coin type (e.g., "0x2::sui::SUI") */
+  /** Asset/coin type identifier (chain-specific format, opaque to s402 core) */
   asset: string;
-  /** Amount in base units (MIST for SUI, 6-decimal for USDC) */
+  /** Amount in base units as a non-negative integer string */
   amount: string;
   /** Recipient address */
   payTo: string;
@@ -115,6 +115,11 @@ interface s402UnlockExtra {
  * Move cannot verify calls actually happened. Agent's protection: rate cap,
  * max_calls, deposit ceiling, small deposits + short refill cycles, reputation.
  * v0.2 adds signed usage receipts for cryptographic fraud proofs. See ADR-007.
+ *
+ * PAIRING INVARIANT: `providerPubkey` and `disputeWindowMs` are a pair.
+ * Both must be present (v0.2 signed receipt mode) or both absent (v0.1 default).
+ * Setting `providerPubkey` without `disputeWindowMs` (or vice versa) is invalid
+ * and will be rejected by the on-chain contract at deposit time.
  */
 interface s402PrepaidExtra {
   /** Maximum base units per API call (rate cap) */

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "s402",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "type": "module",
-  "description": "s402 — Sui-native 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 five payment schemes. Wire-compatible with x402. Zero runtime dependencies.",
   "license": "Apache-2.0",
   "author": "SweeInc <daniel@sweeinc.com> (https://s402-protocol.org)",
   "repository": {
@@ -76,24 +76,30 @@
         "default": "./dist/errors.mjs"
       },
       "default": "./dist/errors.mjs"
+    },
+    "./receipts": {
+      "import": {
+        "types": "./dist/receipts.d.mts",
+        "default": "./dist/receipts.mjs"
+      },
+      "default": "./dist/receipts.mjs"
     }
   },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^3.2.4",
+    "fast-check": "^4.5.3",
+    "tsdown": "^0.20.3",
+    "typescript": "^5.7.0",
+    "vitepress": "^1.6.4",
+    "vitest": "^3.0.5"
+  },
   "scripts": {
     "build": "tsdown",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
-    "prepublishOnly": "npm run build && npm run typecheck && npm run test",
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs",
     "docs:preview": "vitepress preview docs"
-  },
-  "devDependencies": {
-    "@vitest/coverage-v8": "^3.2.4",
-    "fast-check": "^4.5.3",
-    "tsdown": "^0.20.3",
-    "typescript": "^5.7.0",
-    "vitepress": "^1.6.4",
-    "vitest": "^3.0.5"
   }
-}
+}