@reinconsole/x402-rails 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rein contributors
+
+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,35 @@
+# @reinconsole/x402-rails
+
+The real payment rails for **[Rein](https://github.com/bugiiiii11/rein)** — [x402](https://www.x402.org) on Base Sepolia. An EIP-3009 payer that signs real USDC payments (gasless for the agent — the facilitator submits the tx), an HTTP client for the hosted x402.org facilitator, a strict x402-v1 in-process vendor, and an on-chain indexer that reconciles USDC transfers back to the exact intents the policy engine allowed.
+
+> **Status: v0.1 — early open-source infrastructure, live on testnet.** Real USDC settled on Base Sepolia through the hosted facilitator — no API key needed. APIs may change before 1.0.
+
+## Install
+
+```bash
+npm install @reinconsole/x402-rails
+```
+
+## What's in it
+
+```ts
+import {
+  createX402Payer,     // EIP-3009/EIP-712 signer — plugs into @reinconsole/sdk's guard as its `payer`
+  FacilitatorClient,   // verify/settle against the hosted x402.org facilitator
+  OnchainIndexer,      // getLogs polling; reconciles transfers to intents via the nonce memo
+  createRealVendor,    // strict x402-v1 in-process vendor
+  intentNonce,         // keccak256(intent.id) — the on-chain memo
+  generateWallet, createBaseSepoliaClient, getUsdcBalance, // wallet + chain helpers
+} from '@reinconsole/x402-rails';
+```
+
+- **Gasless for the agent.** The payer signs an EIP-3009 `transferWithAuthorization`; the facilitator submits the transaction and pays gas. A funded USDC balance is all the agent wallet needs ([free testnet USDC](https://faucet.circle.com)).
+- **An on-chain memo, no fuzzy matching.** The authorization nonce is derived as `keccak256(intent.id)`; USDC emits it back in `AuthorizationUsed` on settlement, so the indexer reconciles each transfer to the exact intent the engine allowed — and flags everything else from managed wallets as **shadow spend**.
+- **The hosted facilitator, for free.** `FacilitatorClient` speaks the x402.org dialect (`DEFAULT_FACILITATOR_URL`, no API key). The same client powers [`@reinconsole/gate`](https://www.npmjs.com/package/@reinconsole/gate)'s real-rails settlement via `facilitatorClientRails`.
+- **Wire schemas included** — payment payloads, verify/settle responses, header codecs; all zod-validated.
+
+Behind a TLS-intercepting proxy or antivirus, point Node at your local root CA (`NODE_EXTRA_CA_CERTS`) before any live run.
+
+The [monorepo](https://github.com/bugiiiii11/rein)'s Sepolia demos run this end to end — a guarded $0.01 payment settled on-chain, then a guard-bypassing payment caught by the indexer.
+
+MIT © Rein contributors · [Repository](https://github.com/bugiiiii11/rein) · [Issues](https://github.com/bugiiiii11/rein/issues)

package/dist/index.d.ts

@@ -0,0 +1,507 @@
+import { z } from 'zod';
+import { Hex, Address, PublicClient, HttpTransport } from 'viem';
+import { Payer, FetchLike, PaymentRequirement } from '@reinconsole/sdk';
+import { ReinEvent, Chain, Agent } from '@reinconsole/core';
+import { baseSepolia } from 'viem/chains';
+
+/** The EIP-3009 TransferWithAuthorization message, decimal-stringified. */
+declare const ExactEvmAuthorization: z.ZodObject<{
+    from: z.ZodString;
+    to: z.ZodString;
+    /** Atomic-unit amount, mirroring the requirement's maxAmountRequired. */
+    value: z.ZodString;
+    validAfter: z.ZodString;
+    validBefore: z.ZodString;
+    /** bytes32 — Rein derives it from the intent id (see nonce.ts). */
+    nonce: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    from: string;
+    to: string;
+    value: string;
+    validAfter: string;
+    validBefore: string;
+    nonce: string;
+}, {
+    from: string;
+    to: string;
+    value: string;
+    validAfter: string;
+    validBefore: string;
+    nonce: string;
+}>;
+type ExactEvmAuthorization = z.infer<typeof ExactEvmAuthorization>;
+declare const ExactEvmPayload: z.ZodObject<{
+    /** 65-byte EIP-712 signature over the authorization. */
+    signature: z.ZodString;
+    authorization: z.ZodObject<{
+        from: z.ZodString;
+        to: z.ZodString;
+        /** Atomic-unit amount, mirroring the requirement's maxAmountRequired. */
+        value: z.ZodString;
+        validAfter: z.ZodString;
+        validBefore: z.ZodString;
+        /** bytes32 — Rein derives it from the intent id (see nonce.ts). */
+        nonce: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        from: string;
+        to: string;
+        value: string;
+        validAfter: string;
+        validBefore: string;
+        nonce: string;
+    }, {
+        from: string;
+        to: string;
+        value: string;
+        validAfter: string;
+        validBefore: string;
+        nonce: string;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    signature: string;
+    authorization: {
+        from: string;
+        to: string;
+        value: string;
+        validAfter: string;
+        validBefore: string;
+        nonce: string;
+    };
+}, {
+    signature: string;
+    authorization: {
+        from: string;
+        to: string;
+        value: string;
+        validAfter: string;
+        validBefore: string;
+        nonce: string;
+    };
+}>;
+type ExactEvmPayload = z.infer<typeof ExactEvmPayload>;
+/** The full X-PAYMENT header body (x402 spec v1 envelope). */
+declare const PaymentPayload: z.ZodObject<{
+    x402Version: z.ZodLiteral<1>;
+    scheme: z.ZodString;
+    network: z.ZodString;
+    payload: z.ZodObject<{
+        /** 65-byte EIP-712 signature over the authorization. */
+        signature: z.ZodString;
+        authorization: z.ZodObject<{
+            from: z.ZodString;
+            to: z.ZodString;
+            /** Atomic-unit amount, mirroring the requirement's maxAmountRequired. */
+            value: z.ZodString;
+            validAfter: z.ZodString;
+            validBefore: z.ZodString;
+            /** bytes32 — Rein derives it from the intent id (see nonce.ts). */
+            nonce: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            from: string;
+            to: string;
+            value: string;
+            validAfter: string;
+            validBefore: string;
+            nonce: string;
+        }, {
+            from: string;
+            to: string;
+            value: string;
+            validAfter: string;
+            validBefore: string;
+            nonce: string;
+        }>;
+    }, "strip", z.ZodTypeAny, {
+        signature: string;
+        authorization: {
+            from: string;
+            to: string;
+            value: string;
+            validAfter: string;
+            validBefore: string;
+            nonce: string;
+        };
+    }, {
+        signature: string;
+        authorization: {
+            from: string;
+            to: string;
+            value: string;
+            validAfter: string;
+            validBefore: string;
+            nonce: string;
+        };
+    }>;
+}, "strip", z.ZodTypeAny, {
+    x402Version: 1;
+    scheme: string;
+    network: string;
+    payload: {
+        signature: string;
+        authorization: {
+            from: string;
+            to: string;
+            value: string;
+            validAfter: string;
+            validBefore: string;
+            nonce: string;
+        };
+    };
+}, {
+    x402Version: 1;
+    scheme: string;
+    network: string;
+    payload: {
+        signature: string;
+        authorization: {
+            from: string;
+            to: string;
+            value: string;
+            validAfter: string;
+            validBefore: string;
+            nonce: string;
+        };
+    };
+}>;
+type PaymentPayload = z.infer<typeof PaymentPayload>;
+/** Facilitator POST /verify response. Reason strings stay lenient on purpose. */
+declare const VerifyResponse: z.ZodObject<{
+    isValid: z.ZodBoolean;
+    invalidReason: z.ZodOptional<z.ZodString>;
+    payer: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    isValid: boolean;
+    invalidReason?: string | undefined;
+    payer?: string | undefined;
+}, {
+    isValid: boolean;
+    invalidReason?: string | undefined;
+    payer?: string | undefined;
+}>;
+type VerifyResponse = z.infer<typeof VerifyResponse>;
+/** Facilitator POST /settle response (also what X-PAYMENT-RESPONSE carries). */
+declare const SettleResponse: z.ZodObject<{
+    success: z.ZodBoolean;
+    errorReason: z.ZodOptional<z.ZodString>;
+    payer: z.ZodOptional<z.ZodString>;
+    /** The on-chain tx hash (the guard surfaces this on the receipt). */
+    transaction: z.ZodString;
+    network: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    network: string;
+    success: boolean;
+    transaction: string;
+    payer?: string | undefined;
+    errorReason?: string | undefined;
+}, {
+    network: string;
+    success: boolean;
+    transaction: string;
+    payer?: string | undefined;
+    errorReason?: string | undefined;
+}>;
+type SettleResponse = z.infer<typeof SettleResponse>;
+declare function encodePaymentHeader(payload: PaymentPayload): string;
+declare function decodePaymentHeader(raw: string): PaymentPayload;
+declare function encodeSettlementHeader(response: SettleResponse): string;
+
+/**
+ * Deterministic EIP-3009 nonce: keccak256(utf8(intent.id)).
+ *
+ * This is the on-chain memo. EIP-3009 only requires per-authorizer uniqueness
+ * (intent ids are ULIDs, so collisions are off the table), and USDC emits
+ * `AuthorizationUsed(authorizer, nonce)` on settlement — so the indexer can
+ * recompute this for every allowed intent and reconcile transfers exactly,
+ * the same memo-first semantics the mock rails get from a ledger memo field.
+ */
+declare function intentNonce(intentId: string): Hex;
+
+declare function chainIdForNetwork(network: string): number | undefined;
+
+/** The EIP-3009 type tuple USDC's FiatTokenV2 verifies against. */
+declare const transferWithAuthorizationTypes: {
+    readonly TransferWithAuthorization: readonly [{
+        readonly name: "from";
+        readonly type: "address";
+    }, {
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "value";
+        readonly type: "uint256";
+    }, {
+        readonly name: "validAfter";
+        readonly type: "uint256";
+    }, {
+        readonly name: "validBefore";
+        readonly type: "uint256";
+    }, {
+        readonly name: "nonce";
+        readonly type: "bytes32";
+    }];
+};
+interface X402PayerOptions {
+    /** The agent wallet's private key (a local account; never leaves the process). */
+    privateKey: Hex;
+    /** How far into the past validAfter reaches, absorbing clock skew. */
+    validAfterSkewSeconds?: number;
+    /** validBefore window when the requirement omits maxTimeoutSeconds. */
+    defaultTimeoutSeconds?: number;
+    /** Injectable clock (unix seconds) for deterministic tests. */
+    now?: () => number;
+}
+/**
+ * The real x402 `Payer`: signs an EIP-3009 TransferWithAuthorization for the
+ * requirement's token (EIP-712, fully offline — no RPC) and returns the v1
+ * X-PAYMENT header. Gasless for the agent: the facilitator submits the tx.
+ *
+ * The authorization nonce is derived from the intent id, which is what lets
+ * the on-chain indexer reconcile the settlement back to the decision that
+ * allowed it (see nonce.ts).
+ */
+declare function createX402Payer(options: X402PayerOptions): Payer;
+
+/** Coinbase's hosted testnet facilitator: free, no API key, v1 + base-sepolia. */
+declare const DEFAULT_FACILITATOR_URL = "https://x402.org/facilitator";
+interface FacilitatorClientOptions {
+    /** Facilitator base URL. Defaults to the hosted x402.org testnet facilitator. */
+    url?: string;
+    /** Transport override (tests inject a stub here). Defaults to global fetch. */
+    fetch?: FetchLike;
+}
+/** Any x402 payment envelope — the POST's x402Version is read off of it. */
+type AnyPaymentPayload = PaymentPayload | ({
+    x402Version: number;
+} & Record<string, unknown>);
+/** Requirements in whichever dialect matches the payload (v1 or v2 shape). */
+type AnyPaymentRequirements = PaymentRequirement | Record<string, unknown>;
+/**
+ * HTTP client for a real x402 facilitator (v1 AND v2 — x402.org serves both).
+ * The vendor side of the rails: verify checks the payment signature against
+ * the requirement, settle submits the EIP-3009 authorization on-chain (the
+ * facilitator pays gas) and returns the tx hash. The POST's `x402Version` is
+ * derived from the payload envelope itself, and the caller must pass
+ * requirements in the SAME dialect (v2 payload → v2 `amount`/CAIP-2 shape;
+ * @reinconsole/gate's facilitatorClientRails does this conversion).
+ */
+declare class FacilitatorClient {
+    readonly url: string;
+    private readonly fetch;
+    constructor(options?: FacilitatorClientOptions);
+    verify(payload: AnyPaymentPayload, requirements: AnyPaymentRequirements): Promise<VerifyResponse>;
+    settle(payload: AnyPaymentPayload, requirements: AnyPaymentRequirements): Promise<SettleResponse>;
+    /** The facilitator's advertised (x402Version, scheme, network) kinds. */
+    supported(): Promise<unknown>;
+    private post;
+}
+
+interface RealVendorOptions {
+    facilitator: FacilitatorClient;
+    /** Price in atomic units (e.g. "10000" = 0.01 USDC at 6 decimals). */
+    atomicPrice: string;
+    /** Where the vendor wants to be paid (a real EVM address). */
+    payTo: string;
+    network?: string;
+    /** Token contract address. Defaults to USDC on Base Sepolia. */
+    asset?: string;
+    description?: string;
+    maxTimeoutSeconds?: number;
+    /** EIP-712 domain hints for the payer. Defaults to Base Sepolia USDC's. */
+    extra?: Record<string, unknown>;
+    /** JSON body served once payment settles. */
+    body?: unknown;
+}
+interface VendorCall {
+    url: string;
+    payment: string | null;
+}
+interface RealVendor {
+    /** Drop-in fetch for the guard's vendor-facing side. */
+    fetch: FetchLike;
+    /** Every request the vendor saw, in order. */
+    calls: VendorCall[];
+    /** The payment requirement this vendor quotes for a given URL. */
+    requirementFor(url: string): PaymentRequirement;
+}
+/**
+ * An in-process x402 vendor wired to a REAL facilitator: quotes a 402 with
+ * payment requirements until the request carries X-PAYMENT, then verifies and
+ * settles through the facilitator — a real on-chain USDC transfer — and serves
+ * the content with the settlement (tx hash included) in X-PAYMENT-RESPONSE.
+ *
+ * Unlike the mock vendor, the quoted requirement is fully populated: the
+ * hosted facilitator validates it strictly (resource must be a URL,
+ * description/mimeType/maxTimeoutSeconds required, real addresses).
+ */
+declare function createRealVendor(options: RealVendorOptions): RealVendor;
+
+/** The slice of the policy engine the indexer subscribes to (NATS in prod). */
+interface EngineEvents {
+    onEvent(handler: (event: ReinEvent) => void): void;
+}
+/** The two FiatTokenV2 events one transferWithAuthorization settlement emits. */
+declare const railEventsAbi: readonly [{
+    readonly name: "Transfer";
+    readonly type: "event";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "from";
+        readonly indexed: true;
+    }, {
+        readonly type: "address";
+        readonly name: "to";
+        readonly indexed: true;
+    }, {
+        readonly type: "uint256";
+        readonly name: "value";
+    }];
+}, {
+    readonly name: "AuthorizationUsed";
+    readonly type: "event";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "authorizer";
+        readonly indexed: true;
+    }, {
+        readonly type: "bytes32";
+        readonly name: "nonce";
+        readonly indexed: true;
+    }];
+}];
+/** The decoded log shape the indexer consumes. */
+interface RailLog {
+    eventName: 'Transfer' | 'AuthorizationUsed';
+    transactionHash: Hex | null;
+    blockNumber: bigint | null;
+    args: {
+        from?: Address;
+        to?: Address;
+        value?: bigint;
+        authorizer?: Address;
+        nonce?: Hex;
+    };
+}
+/**
+ * What the indexer needs from a chain: current head + decoded event logs.
+ * viem's PublicClient satisfies this structurally; tests inject a fake.
+ */
+interface ChainReader {
+    getBlockNumber(): Promise<bigint>;
+    getLogs(args: {
+        address: Address;
+        events: typeof railEventsAbi;
+        fromBlock: bigint;
+        toBlock: bigint;
+    }): Promise<readonly RailLog[]>;
+}
+interface OnchainIndexerOptions {
+    client: ChainReader;
+    /** Token contract whose transfers are watched. Defaults to Base Sepolia USDC. */
+    usdcAddress?: Address;
+    /** The Rein chain tag recorded on events (testnets map to mainnet). */
+    chain?: Chain;
+    /**
+     * Directory of managed agents and their wallets (the agents service in
+     * prod). Called per transfer, so agents registered later are still seen.
+     */
+    agents: () => readonly Agent[];
+    /** Recorded as SettledPayment.facilitator on reconciled payments. */
+    facilitator?: string;
+    pollIntervalMs?: number;
+    /** First block to scan. Defaults to the chain head at start(). */
+    fromBlock?: bigint;
+    /** Token decimals for amount conversion. */
+    decimals?: number;
+    /** RPC errors are retried next tick; surface them here if you care. */
+    onError?: (err: unknown) => void;
+}
+/** A `shadow.spend` event, extracted for convenience accessors. */
+type ShadowSpend = Extract<ReinEvent, {
+    type: 'shadow.spend';
+}>;
+/**
+ * The real indexer: polls token logs on Base Sepolia and classifies every
+ * transfer that leaves a managed agent wallet — the same semantics as the
+ * mock indexer, against a real chain.
+ *
+ * Reconciliation is memo-first via the EIP-3009 nonce: Rein's payer derives
+ * the authorization nonce from the intent id, and settlement emits
+ * `AuthorizationUsed(authorizer, nonce)` alongside the `Transfer`. A transfer
+ * whose nonce resolves to an allowed, unsettled intent of the same agent is
+ * `payment.settled`; anything else leaving a managed wallet — random nonce,
+ * replay, plain transfer, no ALLOW behind it — is `shadow.spend`. There is no
+ * fuzzy fallback on-chain: the nonce IS the memo.
+ */
+declare class OnchainIndexer {
+    private readonly options;
+    private readonly bus;
+    private readonly emitted;
+    /** Every intent the engine has seen, by id (from `intent.created`). */
+    private readonly intents;
+    /** Intents with an ALLOW decision, by id. */
+    private readonly allowed;
+    private readonly settledIntents;
+    /** Expected on-chain nonce -> intent id, for every allowed intent. */
+    private readonly nonceToIntent;
+    private timer;
+    private nextBlock;
+    private scanning;
+    constructor(options: OnchainIndexerOptions);
+    /** Subscribe to a policy engine's event stream to learn which intents were allowed. */
+    connectEngine(engine: EngineEvents): void;
+    /** Begin polling. Scans from `fromBlock` (default: the current head). */
+    start(): Promise<void>;
+    stop(): void;
+    onEvent(handler: (event: ReinEvent) => void): void;
+    /** Everything the indexer has emitted, oldest first. */
+    events(): readonly ReinEvent[];
+    settledPayments(): {
+        chain: "base" | "solana" | "polygon" | "bnb";
+        intentId: string;
+        txHash: string;
+        blockNumber: bigint;
+        confirmedAt: Date;
+        facilitator?: string | undefined;
+        feePaid?: string | undefined;
+    }[];
+    shadowSpends(): ShadowSpend[];
+    /** Resolve when an event (past or future) matches; reject on timeout. */
+    waitFor(predicate: (event: ReinEvent) => boolean, timeoutMs?: number): Promise<ReinEvent>;
+    /** One poll: fetch logs since the last scanned block and classify them. */
+    scan(): Promise<void>;
+    private emit;
+    private agentFor;
+    private observe;
+    private reconcile;
+}
+
+/** USDC (FiatTokenV2) on Base Sepolia. */
+declare const BASE_SEPOLIA_USDC: Address;
+/** Circle's testnet faucet — funds Base Sepolia USDC for free. */
+declare const CIRCLE_FAUCET_URL = "https://faucet.circle.com";
+declare const basescanTxUrl: (txHash: string) => string;
+interface GeneratedWallet {
+    privateKey: Hex;
+    address: Address;
+}
+/** A fresh local account — fund it with faucet USDC; it never needs ETH. */
+declare function generateWallet(): GeneratedWallet;
+type BaseSepoliaClient = PublicClient<HttpTransport, typeof baseSepolia>;
+declare function createBaseSepoliaClient(rpcUrl?: string): BaseSepoliaClient;
+/** Atomic-unit USDC balance (6 decimals). */
+declare function getUsdcBalance(client: BaseSepoliaClient, address: Address, usdc?: Address): Promise<bigint>;
+
+type RailsErrorCode = 'malformed_payment' | 'unsupported_network';
+/** A payload or requirement these rails refuse to handle, with a machine-readable code. */
+declare class RailsError extends Error {
+    readonly code: RailsErrorCode;
+    constructor(code: RailsErrorCode, message: string);
+}
+/** The facilitator answered with a non-2xx status; body kept for forensics. */
+declare class FacilitatorHttpError extends Error {
+    readonly status: number;
+    readonly body: string;
+    constructor(status: number, body: string);
+}
+
+export { BASE_SEPOLIA_USDC, type BaseSepoliaClient, CIRCLE_FAUCET_URL, type ChainReader, DEFAULT_FACILITATOR_URL, type EngineEvents, ExactEvmAuthorization, ExactEvmPayload, FacilitatorClient, type FacilitatorClientOptions, FacilitatorHttpError, type GeneratedWallet, OnchainIndexer, type OnchainIndexerOptions, PaymentPayload, type RailLog, RailsError, type RailsErrorCode, type RealVendor, type RealVendorOptions, SettleResponse, type ShadowSpend, type VendorCall, VerifyResponse, type X402PayerOptions, basescanTxUrl, chainIdForNetwork, createBaseSepoliaClient, createRealVendor, createX402Payer, decodePaymentHeader, encodePaymentHeader, encodeSettlementHeader, generateWallet, getUsdcBalance, intentNonce, railEventsAbi, transferWithAuthorizationTypes };