s402 0.1.8 → 0.2.1

package/CHANGELOG.md

@@ -5,6 +5,58 @@ 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.1] - 2026-03-02
+
+### Added
+
+- **Conformance test vectors ship in npm package** — 133 machine-readable JSON test vectors across 12 files now included via `test/conformance/vectors`. Cross-language implementors (Go, Python, Rust) can `npm pack s402` to get the vectors without cloning the repo.
+- **API stability declaration** — `API-STABILITY.md` classifies all 83 exports as stable, experimental, or internal.
+
+### Fixed
+
+- Barrel export JSDoc updated to chain-agnostic wording (was "Sui-native").
+
+## [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).
+- **Conformance test suite** — 133 machine-readable JSON test vectors across 12 files for cross-language implementation verification. Covers encode/decode, body transport, compat normalization, receipt format/parse, validation rejection, key-stripping, and roundtrip identity. Vectors ship in the npm package.
+- **API stability declaration** — `API-STABILITY.md` classifies all 83 exports as stable/experimental/internal.
+- 405 tests across 12 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 +129,10 @@ _Version bump for npm publish after license change._
 - Property-based fuzz testing via fast-check
 - 207 tests, zero runtime dependencies
 
+[0.2.1]: https://github.com/s402-protocol/core/compare/v0.2.0...v0.2.1
+[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,25 @@ 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.
 
+## Conformance Testing
+
+s402 ships 133 machine-readable JSON test vectors for cross-language conformance. If you're implementing s402 in Go, Python, Rust, or any other language, use these vectors to verify your implementation matches the spec.
+
+```bash
+# Vectors are in the npm package
+ls node_modules/s402/test/conformance/vectors/
+
+# Or clone the repo
+ls test/conformance/vectors/
+```
+
+See [`test/conformance/README.md`](./test/conformance/README.md) for the vector format, encoding scheme, and implementation guide.
+
+## 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.1",
   "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": {
@@ -36,7 +36,8 @@
     "README.md",
     "LICENSE",
     "CHANGELOG.md",
-    "SECURITY.md"
+    "SECURITY.md",
+    "test/conformance/vectors"
   ],
   "main": "./dist/index.mjs",
   "module": "./dist/index.mjs",
@@ -76,6 +77,13 @@
         "default": "./dist/errors.mjs"
       },
       "default": "./dist/errors.mjs"
+    },
+    "./receipts": {
+      "import": {
+        "types": "./dist/receipts.d.mts",
+        "default": "./dist/receipts.mjs"
+      },
+      "default": "./dist/receipts.mjs"
     }
   },
   "scripts": {

package/test/conformance/README.md

@@ -0,0 +1,172 @@
+# s402 Conformance Test Vectors
+
+Machine-readable test vectors that define s402-compliant behavior. Use these to verify any s402 implementation — TypeScript, Go, Python, Rust, etc.
+
+## Getting the Vectors
+
+The vectors ship with the `s402` npm package:
+
+```bash
+npm pack s402
+tar xzf s402-*.tgz
+ls package/test/conformance/vectors/
+```
+
+Or clone the repo directly:
+
+```bash
+git clone https://github.com/s402-protocol/core.git
+ls core/test/conformance/vectors/
+```
+
+## Vector Format
+
+Each JSON file contains an array of test cases:
+
+```json
+[
+  {
+    "description": "Human-readable test name",
+    "input": { ... },
+    "expected": { ... },
+    "shouldReject": false
+  }
+]
+```
+
+### Accept vectors (`shouldReject: false`)
+
+The implementation MUST produce `expected` when given `input`.
+
+### Reject vectors (`shouldReject: true`)
+
+The implementation MUST reject the input with an error. The `expectedErrorCode` field indicates which error:
+
+```json
+{
+  "description": "Rejects negative amount",
+  "input": { "header": "base64-encoded-malformed-json" },
+  "shouldReject": true,
+  "expectedErrorCode": "INVALID_PAYLOAD"
+}
+```
+
+## Vector Files
+
+| File | Tests | Description |
+|------|-------|-------------|
+| `requirements-encode.json` | Encode | `s402PaymentRequirements` object → base64 header string |
+| `requirements-decode.json` | Decode | base64 header string → `s402PaymentRequirements` object |
+| `payload-encode.json` | Encode | `s402PaymentPayload` object → base64 header string |
+| `payload-decode.json` | Decode | base64 header string → `s402PaymentPayload` object |
+| `settle-encode.json` | Encode | `s402SettleResponse` object → base64 header string |
+| `settle-decode.json` | Decode | base64 header string → `s402SettleResponse` object |
+| `body-transport.json` | Both | Requirements/payload/settle via JSON body (no base64) |
+| `compat-normalize.json` | Normalize | x402 V1/V2 input → normalized s402 output |
+| `receipt-format.json` | Format | Receipt fields → `X-S402-Receipt` header string |
+| `receipt-parse.json` | Parse | `X-S402-Receipt` header string → parsed receipt fields |
+| `validation-reject.json` | Reject | Malformed inputs that MUST be rejected |
+| `roundtrip.json` | Roundtrip | encode → decode → re-encode = identical output |
+
+## Encoding Scheme
+
+s402 uses **Unicode-safe base64** for HTTP header transport:
+
+1. JSON-serialize the object: `JSON.stringify(obj)`
+2. UTF-8 encode the string: `TextEncoder.encode(json)`
+3. Base64 encode the bytes: `btoa(bytes.map(b => String.fromCharCode(b)).join(''))`
+
+For ASCII-only content (the common case), this produces the same output as plain `btoa(json)`.
+
+Body transport uses raw JSON (no base64).
+
+## Receipt Header Format
+
+The `X-S402-Receipt` header uses colon-separated fields:
+
+```
+v2:base64(signature):callNumber:timestampMs:base64(responseHash)
+```
+
+- `v2` — version prefix (always "v2" for signed receipts)
+- `signature` — 64-byte Ed25519 signature, base64-encoded
+- `callNumber` — sequential call number (1-indexed, bigint string)
+- `timestampMs` — Unix timestamp in milliseconds (bigint string)
+- `responseHash` — response body hash (typically SHA-256, 32 bytes), base64-encoded
+
+In the vector JSON files, `signature` and `responseHash` are represented as arrays of byte values (0-255) since JSON has no binary type.
+
+## Implementing in Another Language
+
+1. Load the JSON vector files
+2. For each vector where `shouldReject` is `false`:
+   - Feed `input` to your encode/decode function
+   - Compare the result to `expected`
+3. For each vector where `shouldReject` is `true`:
+   - Feed `input` to your decode function
+   - Verify it throws/returns an error with the matching error code
+4. For roundtrip vectors:
+   - Verify `expected.identical` is `true`
+   - Verify `expected.firstEncode === expected.reEncode`
+
+### Key stripping on decode
+
+All three decode functions (`decodePaymentRequired`, `decodePaymentPayload`, `decodeSettleResponse`) MUST strip unknown top-level keys. Only known fields should survive the decode. This is a defense-in-depth measure at the HTTP trust boundary.
+
+**Requirements known top-level keys:** `s402Version`, `accepts`, `network`, `asset`, `amount`, `payTo`, `facilitatorUrl`, `mandate`, `protocolFeeBps`, `protocolFeeAddress`, `receiptRequired`, `settlementMode`, `expiresAt`, `stream`, `escrow`, `unlock`, `prepaid`, `extensions`.
+
+**Requirements sub-object known keys** (also stripped of unknowns):
+- `mandate`: `required`, `minPerTx`, `coinType`
+- `stream`: `ratePerSecond`, `budgetCap`, `minDeposit`, `streamSetupUrl`
+- `escrow`: `seller`, `arbiter`, `deadlineMs`
+- `unlock`: `encryptionId`, `walrusBlobId`, `encryptionPackageId`
+- `prepaid`: `ratePerCall`, `maxCalls`, `minDeposit`, `withdrawalDelayMs`, `providerPubkey`, `disputeWindowMs`
+
+**Payload known top-level keys:** `s402Version`, `scheme`, `payload`.
+
+**Payload inner keys** (per scheme):
+- `exact`, `stream`, `escrow`: `transaction`, `signature`
+- `unlock`: `transaction`, `signature`, `encryptionId`
+- `prepaid`: `transaction`, `signature`, `ratePerCall`, `maxCalls`
+
+**Settle response known keys:** `success`, `txDigest`, `receiptId`, `finalityMs`, `streamId`, `escrowId`, `balanceId`, `error`, `errorCode`.
+
+### JSON key ordering
+
+s402 vectors use JavaScript's `JSON.stringify()` key ordering (insertion order). Cross-language implementations MUST serialize keys in the same order as the vector files to produce identical base64 output. If your language's JSON serializer uses alphabetical ordering by default, you'll need ordered serialization (e.g., Go's `json.Marshal` on a struct with ordered fields, Python's `json.dumps` with `sort_keys=False`).
+
+Note: **decode also reorders keys**. The decode functions iterate their allowlist in the order listed above, not the input order. If the input JSON has keys in a different order, the decoded output follows the allowlist order. This affects roundtrip tests — the re-encoded output uses the allowlist order, which may differ from the original input order.
+
+### Header size limits
+
+Implementations SHOULD enforce a maximum header size of **64 KiB** (`MAX_HEADER_BYTES = 65536`). Headers exceeding this limit indicate abuse or misconfiguration and SHOULD be rejected before base64 decoding.
+
+### Rejection vector dispatch
+
+Rejection vectors are dispatched in this precedence order:
+
+1. If `expectedErrorCode` is `"RECEIPT_PARSE_ERROR"` → test `parseReceiptHeader`. Note: receipts throw a plain `Error`, not an `s402Error`, since receipts are a separate subsystem.
+2. If `input.decodeAs` is `"payload"` → test `decodePaymentPayload`
+3. If `input.decodeAs` is `"compat"` → test `normalizeRequirements` with the raw JSON (not base64)
+4. Otherwise → test `decodePaymentRequired` (the default)
+
+### Error codes
+
+Rejection vectors use `expectedErrorCode` values from the s402 error code enum:
+
+- `INVALID_PAYLOAD` — malformed or invalid input
+- `RECEIPT_PARSE_ERROR` — malformed receipt header (vector convention for receipt-specific parsing errors)
+
+## Regenerating Vectors
+
+If you modify the s402 encoding logic, regenerate vectors:
+
+```bash
+npx tsx test/conformance/generate-vectors.ts
+```
+
+Then run the conformance tests to verify:
+
+```bash
+pnpm run test
+```