s402 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+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.1.0] - 2026-02-15
+
+### Added
+
+- Five payment scheme types: exact, prepaid, escrow, unlock, stream
+- HTTP header encoding/decoding (base64 JSON wire format)
+- Client, server, and facilitator scheme registries
+- Optional x402 compat layer (`s402/compat`) — normalizes V1 and V2 formats
+- Typed error codes with `retryable` flag and `suggestedAction` for agent self-recovery
+- Sub-path exports: `s402/types`, `s402/http`, `s402/compat`, `s402/errors`
+- Property-based fuzz testing via fast-check
+- 207 tests, zero runtime dependencies
+
+[0.1.0]: https://github.com/s402-protocol/core/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pixel Drift Co
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,322 @@
+# s402
+
+**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.
+
+```bash
+npm install s402
+pnpm add s402
+bun add s402
+deno add npm:s402
+```
+
+> **ESM-only.** This package ships ES modules only (`"type": "module"`). Requires Node.js >= 18. CommonJS `require()` is not supported.
+
+## Why s402?
+
+HTTP 402 ("Payment Required") has been reserved since 1999 — waiting for a payment protocol that actually works. Coinbase's x402 proved the concept on EVM. s402 takes it further by leveraging what makes Sui different.
+
+### s402 vs x402
+
+| | x402 (Coinbase) | s402 |
+|---|---|---|
+| **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) |
+| **Coin handling** | approve + transferFrom | Native `coinWithBalance` + `splitCoins` |
+| **Agent auth** | None | AP2 mandate delegation |
+| **Direct mode** | No | Yes (no facilitator needed) |
+| **Receipts** | Off-chain | On-chain NFT proofs |
+| **Compatibility** | n/a | Optional x402 compat layer (`s402/compat`) |
+
+**s402 is Sui-native by design.** These advantages come from Sui's object model, PTBs, and sub-second finality. They can't be replicated on EVM — and they don't need to be. x402 already handles EVM well. s402 handles Sui better.
+
+## Architecture
+
+```
+s402          <-- You are here. Protocol spec. Zero runtime deps.
+  |
+  |-- Types         Payment requirements, payloads, responses
+  |-- Schemes       Client/Server/Facilitator interfaces per scheme
+  |-- HTTP          Encode/decode for HTTP headers (base64 JSON)
+  |-- Compat        Optional x402 migration aid
+  |-- Errors        Typed error codes with recovery hints
+  |
+@sweepay/sui        <-- Sui-specific implementations (coming soon)
+@sweepay/sdk        <-- High-level DX (coming soon)
+```
+
+`s402` is **chain-agnostic protocol plumbing**. It defines _what_ gets sent over HTTP. The Sui-specific _how_ will live in `@sweepay/sui` (coming soon).
+
+## Payment Schemes
+
+### Exact (v0.1)
+
+One-shot payment. Client builds a signed transfer PTB, facilitator verifies + broadcasts atomically.
+
+```
+Client                    Server                  Facilitator
+  |--- GET /api/data ------->|                         |
+  |<-- 402 + requirements ---|                         |
+  |                          |                         |
+  |  (build PTB, sign)       |                         |
+  |--- GET + x-payment ----->|--- verify + settle ---->|
+  |                          |<--- { success, tx } ----|
+  |<-- 200 + data -----------|                         |
+```
+
+This is the x402-compatible baseline. An x402 client can talk to an s402 server using this scheme with zero modifications.
+
+### Prepaid (v0.1)
+
+Deposit-based access. Agent deposits funds into an on-chain Balance shared object targeted at a specific provider. API calls happen off-chain. Provider batch-claims accumulated usage. Move module enforces rate caps — no trust required.
+
+```
+Phase 1 (deposit — one on-chain TX):
+  Agent deposits 10 SUI → Balance shared object created
+  Gas: ~$0.007
+
+Phase 2 (usage — off-chain, zero gas):
+  Agent makes 1,000 API calls
+  Server tracks usage, no on-chain TX per call
+
+Phase 3 (claim — one on-chain TX):
+  Provider claims accumulated $1.00 from Balance
+  Gas: ~$0.007
+  ─────────────────────────────────────────────────────
+  Total gas: $0.014 for 1,000 calls
+  Per-call effective gas: $0.000014
+```
+
+This is the agent-native payment pattern. Without prepaid, per-call settlement costs $7.00 in gas for $1.00 of API usage (economically impossible). With prepaid, it costs $0.014 (economically trivial).
+
+Use cases: AI agent API budgets, high-frequency API access, compute metering.
+
+### Escrow (v0.1)
+
+Time-locked vault with arbiter dispute resolution. Full state machine: `ACTIVE -> DISPUTED -> RELEASED / REFUNDED`.
+
+- Buyer deposits funds, locked until release or deadline
+- Buyer confirms delivery -> funds release to seller (receipt minted)
+- Deadline passes -> permissionless refund (anyone can trigger)
+- Either party disputes -> arbiter resolves
+
+Use cases: digital goods delivery, freelance payments, trustless commerce.
+
+### Unlock
+
+Pay-to-decrypt encrypted content. Escrow + encrypted content delivery. The buyer pays into escrow; on release, the `EscrowReceipt` unlocks encrypted content stored on [Walrus](https://docs.walrus.site). Currently powered by [Sui SEAL](https://docs.sui.io/concepts/cryptography/seal).
+
+This scheme depends on encryption key server infrastructure and is under active development.
+
+### Stream
+
+Per-second micropayments via on-chain `StreamingMeter`. Client deposits funds into a shared object; recipient claims accrued tokens over time.
+
+```
+Phase 1 (402 exchange):
+  Client builds stream creation PTB --> facilitator broadcasts
+  Result: StreamingMeter shared object on-chain
+
+Phase 2 (ongoing access):
+  Client includes x-stream-id header --> server checks on-chain balance
+  Server grants access as long as stream has funds
+```
+
+Use cases: AI inference sessions, video streaming, real-time data feeds.
+
+## Quick Start
+
+### Types only (most common)
+
+```typescript
+import type {
+  s402PaymentRequirements,
+  s402PaymentPayload,
+  s402SettleResponse,
+} from 's402';
+```
+
+### HTTP header encoding
+
+```typescript
+import {
+  encodePaymentRequired,
+  decodePaymentRequired,
+  encodePaymentPayload,
+  decodePaymentPayload,
+  detectProtocol,
+} from 's402';
+
+// Server: build 402 response
+const requirements: s402PaymentRequirements = {
+  s402Version: '1',
+  accepts: ['exact', 'stream'],
+  network: 'sui:mainnet',
+  asset: '0x2::sui::SUI',
+  amount: '1000000', // 0.001 SUI in MIST
+  payTo: '0xrecipient...',
+};
+
+response.status = 402;
+response.headers.set('payment-required', encodePaymentRequired(requirements));
+
+// Client: read 402 response
+const header = response.headers.get('payment-required')!;
+const reqs = decodePaymentRequired(header);
+console.log(reqs.accepts); // ['exact', 'stream']
+console.log(reqs.amount);  // '1000000'
+```
+
+### x402 compat (opt-in)
+
+```typescript
+import {
+  normalizeRequirements,
+  isS402,
+  isX402,
+  toX402Requirements,
+  fromX402Requirements,
+} from 's402/compat';
+
+// Normalize x402 JSON (V1 or V2) to s402 format
+const requirements = normalizeRequirements(rawJsonObject);
+
+// Convert s402 -> x402 V1 for legacy clients
+const x402Reqs = toX402Requirements(requirements);
+```
+
+### Error handling
+
+```typescript
+import { s402Error, s402ErrorCode } from 's402';
+
+try {
+  await facilitator.settle(payload, requirements);
+} catch (e) {
+  if (e instanceof s402Error) {
+    console.log(e.code);            // 'INSUFFICIENT_BALANCE'
+    console.log(e.retryable);       // false
+    console.log(e.suggestedAction); // 'Top up wallet balance...'
+  }
+}
+```
+
+### Scheme registry (client)
+
+```typescript
+import { s402Client } from 's402';
+
+const client = new s402Client();
+
+// Register scheme implementations (from @sweepay/sui or your own)
+client.register('sui:mainnet', exactScheme);
+client.register('sui:mainnet', streamScheme);
+
+// Auto-selects best scheme from server's accepts array
+const payload = await client.createPayment(requirements);
+```
+
+### Scheme registry (facilitator)
+
+```typescript
+import { s402Facilitator } from 's402';
+
+const facilitator = new s402Facilitator();
+facilitator.register('sui:mainnet', exactFacilitatorScheme);
+
+// Atomic verify + settle
+const result = await facilitator.process(payload, requirements);
+if (result.success) {
+  console.log(result.txDigest); // Sui transaction digest
+}
+```
+
+## Sub-path Exports
+
+```typescript
+import { ... } from 's402';         // Everything
+import type { ... } from 's402/types';   // Types + constants only
+import { ... } from 's402/http';     // HTTP encode/decode
+import { ... } from 's402/compat';   // x402 interop
+import { ... } from 's402/errors';   // Error types
+```
+
+## Implementing a Scheme
+
+s402 is designed as a plugin system. Each payment scheme implements three interfaces:
+
+```typescript
+import type {
+  s402ClientScheme,       // Client: build payment payload
+  s402ServerScheme,       // Server: build payment requirements
+  s402FacilitatorScheme,  // Facilitator: verify + settle
+  s402DirectScheme,       // Optional: settle without facilitator
+} from 's402';
+```
+
+The reference Sui implementation of all five schemes will be available in `@sweepay/sui` (coming soon).
+
+## Wire Format
+
+s402 uses the same HTTP headers as x402 V1:
+
+| Header | Direction | Content |
+|--------|-----------|---------|
+| `payment-required` | Server -> Client | Base64-encoded `s402PaymentRequirements` JSON |
+| `x-payment` | Client -> Server | Base64-encoded `s402PaymentPayload` JSON |
+| `payment-response` | Server -> Client | Base64-encoded `s402SettleResponse` JSON |
+
+> **Note:** x402 V2 renamed the client payment header to `payment-signature`. s402 uses `x-payment` (matching x402 V1). All header names are lowercase per HTTP/2 (RFC 9113 §8.2.1). x402 V2 servers accept both headers, so s402 clients work with both versions. If your server needs to accept x402 V2 clients, also check `payment-signature`.
+
+The presence of `s402Version` in the decoded JSON distinguishes s402 from x402. Clients and servers can auto-detect the protocol using `detectProtocol()`.
+
+## Discovery
+
+Servers can advertise s402 support at `/.well-known/s402.json`:
+
+```json
+{
+  "s402Version": "1",
+  "schemes": ["exact", "stream", "escrow", "unlock", "prepaid"],
+  "networks": ["sui:mainnet"],
+  "assets": ["0x2::sui::SUI", "0xdba...::usdc::USDC"],
+  "directSettlement": true,
+  "mandateSupport": true,
+  "protocolFeeBps": 50
+}
+```
+
+## Security
+
+**HTTPS is required.** s402 payment data (requirements, payloads, settlement responses) travels in HTTP headers as base64-encoded JSON. Without TLS, this data is visible to any network observer. All production deployments MUST use HTTPS.
+
+**Requirements expiration.** Servers SHOULD set `expiresAt` on payment requirements to prevent replay of stale 402 responses. The facilitator rejects expired requirements before processing.
+
+```typescript
+const requirements: s402PaymentRequirements = {
+  s402Version: '1',
+  accepts: ['exact'],
+  network: 'sui:mainnet',
+  asset: '0x2::sui::SUI',
+  amount: '1000000',
+  payTo: '0xrecipient...',
+  expiresAt: Date.now() + 5 * 60 * 1000, // 5-minute window
+};
+```
+
+## Design Principles
+
+1. **Protocol-agnostic core, Sui-native reference.** `s402` defines chain-agnostic protocol types and HTTP encoding. The reference implementation (`@sweepay/sui`, coming soon) will exploit Sui's unique properties — PTBs, object model, sub-second finality. Other chains can implement s402 schemes using their own primitives.
+
+2. **Optional x402 compat.** The `s402/compat` subpath provides a migration aid for codebases with x402-formatted JSON. It normalizes x402 V1 (`maxAmountRequired`) and V2 (`amount`) to s402 format. This is opt-in — the core protocol has no x402 dependency.
+
+3. **Scheme-specific verification.** Each scheme has its own verify logic. Exact verify (signature recovery + dry-run) is fundamentally different from stream verify (deposit check + rate validation). The facilitator dispatches — it doesn't share logic.
+
+4. **Zero runtime dependencies.** `s402` is pure TypeScript protocol definitions. No Sui SDK, no crypto libraries, no HTTP framework. Chain-specific code belongs in adapters.
+
+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.
+
+## License
+
+MIT

package/SECURITY.md

@@ -0,0 +1,41 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+**Please do not open public issues for security vulnerabilities.**
+
+If you discover a security issue in s402, please report it privately:
+
+- **Email:** dannydevs@proton.me
+- **Subject line:** `[s402 security] <brief description>`
+
+You will receive an acknowledgment within 48 hours. We aim to provide a fix or mitigation plan within 7 days of confirmation.
+
+## Scope
+
+This policy covers the `s402` npm package — the protocol types, HTTP encoding/decoding, scheme registry, and compat layer.
+
+Security issues in downstream packages (`@sweepay/sui`, `@sweepay/sdk`, etc.) should be reported to the same email.
+
+## What qualifies
+
+- Wire format parsing vulnerabilities (header injection, base64 decode exploits)
+- Type confusion that could lead to incorrect payment verification
+- Compat layer normalization bugs that silently alter payment amounts
+- Anything that could cause funds loss, incorrect settlement, or unauthorized access
+
+## What does not qualify
+
+- Bugs in example code or documentation
+- Denial-of-service via malformed input (we validate and throw typed errors)
+- Issues in development dependencies (vitest, tsdown, etc.)
+
+## Disclosure
+
+We follow coordinated disclosure. Once a fix is released, we will:
+
+1. Credit the reporter (unless anonymity is requested)
+2. Publish a security advisory on GitHub
+3. Release a patched version on npm
+
+Thank you for helping keep s402 secure.

package/dist/compat.d.mts

@@ -0,0 +1,114 @@
+import { s402ExactPayload, s402PaymentPayload, s402PaymentRequirements } from "./types.mjs";
+
+//#region src/compat.d.ts
+/**
+ * x402 PaymentRequirements shape — supports both V1 and V2 wire formats.
+ *
+ * V1 wire format uses `maxAmountRequired`; V2 uses `amount`.
+ * Both versions require `maxTimeoutSeconds`.
+ * V1 includes resource metadata (`resource`, `description`, `mimeType`) inline;
+ * V2 hoists these to the `PaymentRequired` envelope.
+ */
+interface x402PaymentRequirements {
+  x402Version: number;
+  scheme: string;
+  network: string;
+  asset: string;
+  /** V2 amount field (base units). */
+  amount?: string;
+  /** V1 amount field (renamed to `amount` in V2). */
+  maxAmountRequired?: string;
+  payTo: string;
+  /** Required in x402. Seconds the facilitator will wait before rejecting. */
+  maxTimeoutSeconds?: number;
+  /** V1-only: resource URL. V2 moves this to the PaymentRequired envelope. */
+  resource?: string;
+  /** V1-only: human-readable description. */
+  description?: string;
+  facilitatorUrl?: string;
+  extensions?: Record<string, unknown>;
+}
+/**
+ * x402 V2 PaymentRequired envelope — wraps an array of requirements.
+ * In V2, `x402Version` lives on this envelope, not on individual requirements.
+ * Resource metadata and extensions are also at the envelope level.
+ */
+interface x402PaymentRequiredEnvelope {
+  x402Version: number;
+  accepts: x402PaymentRequirements[];
+  resource?: {
+    url?: string;
+    mimeType?: string;
+    description?: string;
+  };
+  extensions?: Record<string, unknown>;
+  error?: string;
+}
+/** Minimal x402 PaymentPayload shape */
+interface x402PaymentPayload {
+  x402Version: number;
+  scheme: string;
+  payload: {
+    transaction: string;
+    signature: string;
+  };
+}
+/**
+ * Convert inbound x402 requirements to s402 format.
+ * Handles both V1 (`maxAmountRequired`) and V2 (`amount`) wire formats.
+ * Maps x402's single scheme to s402's accepts array.
+ */
+declare function fromX402Requirements(x402: x402PaymentRequirements): s402PaymentRequirements;
+/**
+ * Convert inbound x402 payment payload to s402 format.
+ * Validates that required fields are present and correctly typed.
+ */
+declare function fromX402Payload(x402: x402PaymentPayload): s402ExactPayload;
+/**
+ * Convert outbound s402 requirements to x402 V1 wire format.
+ * Strips s402-only fields (mandate, stream, escrow, unlock extensions).
+ * Only works for "exact" scheme — other schemes have no x402 equivalent.
+ *
+ * Includes both `maxAmountRequired` (V1) and `amount` (V2) for maximum interop.
+ * Includes `maxTimeoutSeconds` (required in x402, defaults to 60s).
+ * V1 metadata fields (`resource`, `description`) default to empty strings.
+ */
+declare function toX402Requirements(s402: s402PaymentRequirements, overrides?: {
+  maxTimeoutSeconds?: number;
+  resource?: string;
+  description?: string;
+}): x402PaymentRequirements;
+/**
+ * Convert outbound s402 payload to x402 format.
+ * Only works for exact scheme payloads.
+ */
+declare function toX402Payload(s402: s402PaymentPayload): x402PaymentPayload | null;
+/**
+ * Check if a decoded JSON object is s402 format.
+ */
+declare function isS402(obj: Record<string, unknown>): boolean;
+/**
+ * Check if a decoded JSON object is x402 format (V1 flat or V2 envelope).
+ */
+declare function isX402(obj: Record<string, unknown>): boolean;
+/**
+ * Check if a decoded JSON object is an x402 V2 envelope (has `accepts` array).
+ * V2 envelopes wrap requirements in an `accepts` array instead of flat fields.
+ */
+declare function isX402Envelope(obj: Record<string, unknown>): boolean;
+/**
+ * Convert an x402 V2 envelope to s402 format.
+ * Picks the first requirement from the `accepts` array.
+ * Copies `x402Version` from the envelope onto the requirement for downstream processing.
+ */
+declare function fromX402Envelope(envelope: x402PaymentRequiredEnvelope): s402PaymentRequirements;
+/**
+ * Auto-detect and normalize: if x402, convert to s402. If already s402, validate and pass through.
+ * Handles x402 V1 (flat), x402 V2 (envelope with accepts array), and s402 formats.
+ * Validates required fields to catch malformed/malicious payloads at the trust boundary.
+ *
+ * Returns a clean object with only known s402 fields — unknown top-level keys are stripped.
+ */
+declare function normalizeRequirements(obj: Record<string, unknown>): s402PaymentRequirements;
+//#endregion
+export { fromX402Envelope, fromX402Payload, fromX402Requirements, isS402, isX402, isX402Envelope, normalizeRequirements, toX402Payload, toX402Requirements, x402PaymentPayload, x402PaymentRequiredEnvelope, x402PaymentRequirements };

package/dist/compat.mjs

@@ -0,0 +1,152 @@
+import { S402_VERSION } from "./types.mjs";
+import { s402Error } from "./errors.mjs";
+import { isValidAmount, pickRequirementsFields, validateRequirementsShape } from "./http.mjs";
+
+//#region src/compat.ts
+/**
+* Convert inbound x402 requirements to s402 format.
+* Handles both V1 (`maxAmountRequired`) and V2 (`amount`) wire formats.
+* Maps x402's single scheme to s402's accepts array.
+*/
+function fromX402Requirements(x402) {
+	const amount = x402.amount ?? x402.maxAmountRequired;
+	if (!amount) throw new s402Error("INVALID_PAYLOAD", "x402 requirements missing both \"amount\" (V2) and \"maxAmountRequired\" (V1)");
+	if (!isValidAmount(amount)) throw new s402Error("INVALID_PAYLOAD", `Invalid amount "${amount}": must be a non-negative integer string`);
+	return {
+		s402Version: S402_VERSION,
+		accepts: ["exact"],
+		network: x402.network,
+		asset: x402.asset,
+		amount,
+		payTo: x402.payTo,
+		facilitatorUrl: x402.facilitatorUrl,
+		extensions: x402.extensions
+	};
+}
+/**
+* Convert inbound x402 payment payload to s402 format.
+* Validates that required fields are present and correctly typed.
+*/
+function fromX402Payload(x402) {
+	if (x402.payload == null || typeof x402.payload !== "object") throw new s402Error("INVALID_PAYLOAD", "x402 payload missing or not an object");
+	if (typeof x402.payload.transaction !== "string") throw new s402Error("INVALID_PAYLOAD", `x402 payload.transaction must be a string, got ${typeof x402.payload.transaction}`);
+	if (typeof x402.payload.signature !== "string") throw new s402Error("INVALID_PAYLOAD", `x402 payload.signature must be a string, got ${typeof x402.payload.signature}`);
+	return {
+		s402Version: S402_VERSION,
+		scheme: "exact",
+		payload: {
+			transaction: x402.payload.transaction,
+			signature: x402.payload.signature
+		}
+	};
+}
+/**
+* Convert outbound s402 requirements to x402 V1 wire format.
+* Strips s402-only fields (mandate, stream, escrow, unlock extensions).
+* Only works for "exact" scheme — other schemes have no x402 equivalent.
+*
+* Includes both `maxAmountRequired` (V1) and `amount` (V2) for maximum interop.
+* Includes `maxTimeoutSeconds` (required in x402, defaults to 60s).
+* V1 metadata fields (`resource`, `description`) default to empty strings.
+*/
+function toX402Requirements(s402, overrides) {
+	return {
+		x402Version: 1,
+		scheme: "exact",
+		network: s402.network,
+		asset: s402.asset,
+		amount: s402.amount,
+		maxAmountRequired: s402.amount,
+		payTo: s402.payTo,
+		facilitatorUrl: s402.facilitatorUrl,
+		maxTimeoutSeconds: overrides?.maxTimeoutSeconds ?? 60,
+		resource: overrides?.resource ?? "",
+		description: overrides?.description ?? "",
+		extensions: s402.extensions
+	};
+}
+/**
+* Convert outbound s402 payload to x402 format.
+* Only works for exact scheme payloads.
+*/
+function toX402Payload(s402) {
+	if (s402.scheme !== "exact") return null;
+	const exact = s402;
+	return {
+		x402Version: 1,
+		scheme: "exact",
+		payload: {
+			transaction: exact.payload.transaction,
+			signature: exact.payload.signature
+		}
+	};
+}
+/**
+* Check if a decoded JSON object is s402 format.
+*/
+function isS402(obj) {
+	return "s402Version" in obj;
+}
+/**
+* Check if a decoded JSON object is x402 format (V1 flat or V2 envelope).
+*/
+function isX402(obj) {
+	return "x402Version" in obj && !("s402Version" in obj);
+}
+/**
+* Check if a decoded JSON object is an x402 V2 envelope (has `accepts` array).
+* V2 envelopes wrap requirements in an `accepts` array instead of flat fields.
+*/
+function isX402Envelope(obj) {
+	return "x402Version" in obj && Array.isArray(obj.accepts) && !("s402Version" in obj);
+}
+/**
+* Convert an x402 V2 envelope to s402 format.
+* Picks the first requirement from the `accepts` array.
+* Copies `x402Version` from the envelope onto the requirement for downstream processing.
+*/
+function fromX402Envelope(envelope) {
+	if (!envelope.accepts || envelope.accepts.length === 0) throw new s402Error("INVALID_PAYLOAD", "x402 V2 envelope has empty accepts array");
+	const req = {
+		...envelope.accepts[0],
+		x402Version: envelope.x402Version
+	};
+	validateX402Shape(req);
+	return fromX402Requirements(req);
+}
+/**
+* Auto-detect and normalize: if x402, convert to s402. If already s402, validate and pass through.
+* Handles x402 V1 (flat), x402 V2 (envelope with accepts array), and s402 formats.
+* Validates required fields to catch malformed/malicious payloads at the trust boundary.
+*
+* Returns a clean object with only known s402 fields — unknown top-level keys are stripped.
+*/
+function normalizeRequirements(obj) {
+	if (isS402(obj)) {
+		validateRequirementsShape(obj);
+		return pickRequirementsFields(obj);
+	}
+	if (isX402Envelope(obj)) return fromX402Envelope(obj);
+	if (isX402(obj)) {
+		validateX402Shape(obj);
+		return fromX402Requirements(obj);
+	}
+	throw new s402Error("INVALID_PAYLOAD", "Unrecognized payment requirements format: missing s402Version or x402Version");
+}
+/** Validate that an x402 object has required fields (supports V1 and V2). */
+function validateX402Shape(obj) {
+	const missing = [];
+	if (typeof obj.scheme !== "string") missing.push("scheme (string)");
+	if (typeof obj.network !== "string") missing.push("network (string)");
+	if (typeof obj.asset !== "string") missing.push("asset (string)");
+	if (typeof obj.payTo !== "string") missing.push("payTo (string)");
+	if (typeof obj.amount !== "string" && typeof obj.maxAmountRequired !== "string") missing.push("amount or maxAmountRequired (string)");
+	else {
+		const amt = typeof obj.amount === "string" ? obj.amount : obj.maxAmountRequired;
+		if (!isValidAmount(amt)) throw new s402Error("INVALID_PAYLOAD", `Invalid amount "${amt}": must be a non-negative integer string`);
+	}
+	if (missing.length > 0) throw new s402Error("INVALID_PAYLOAD", `Malformed x402 requirements: missing or invalid fields: ${missing.join(", ")}`);
+}
+
+//#endregion
+export { fromX402Envelope, fromX402Payload, fromX402Requirements, isS402, isX402, isX402Envelope, normalizeRequirements, toX402Payload, toX402Requirements };