@agenticprimitives/payments 0.0.0-alpha.4 → 0.0.0-alpha.6

package/dist/rails/escrow.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Escrow rail (spec 243 §5.5, over PaymentEscrow.sol) — hold-and-capture for an order.
+ *
+ * Powers the deliver-then-pay flow: payer deposits a hold keyed by `orderHash` → provider
+ * fulfils → `release` captures to the payee (and the app mints the entitlement, pay-AFTER-
+ * fulfillment) → on failure/expiry `refund`/`reclaim` returns the funds. Builders emit the
+ * `{to: escrow, value, data}` calls an SA executes; deposit needs a prior `approve`
+ * (`buildErc20Approve`). App reads hold state via `getHold` (readContract), not log scans.
+ */
+import { type Address } from 'viem';
+import type { TransferPlan } from '../transfer.js';
+import type { Hex32 } from '../index.js';
+/** Mirrors PaymentEscrow.Status. */
+export declare enum EscrowStatus {
+    None = 0,
+    Held = 1,
+    Captured = 2,
+    Refunded = 3,
+    Reclaimed = 4
+}
+export declare const ESCROW_ABI: readonly [{
+    readonly type: "function";
+    readonly name: "deposit";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "orderHash";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "asset";
+        readonly type: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+    }, {
+        readonly name: "payee";
+        readonly type: "address";
+    }, {
+        readonly name: "refundTo";
+        readonly type: "address";
+    }, {
+        readonly name: "releaser";
+        readonly type: "address";
+    }, {
+        readonly name: "expiry";
+        readonly type: "uint64";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "release";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "orderHash";
+        readonly type: "bytes32";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "refund";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "orderHash";
+        readonly type: "bytes32";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "reclaim";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "orderHash";
+        readonly type: "bytes32";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "getHold";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "orderHash";
+        readonly type: "bytes32";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "tuple";
+        readonly components: readonly [{
+            readonly name: "payer";
+            readonly type: "address";
+        }, {
+            readonly name: "asset";
+            readonly type: "address";
+        }, {
+            readonly name: "amount";
+            readonly type: "uint256";
+        }, {
+            readonly name: "payee";
+            readonly type: "address";
+        }, {
+            readonly name: "refundTo";
+            readonly type: "address";
+        }, {
+            readonly name: "releaser";
+            readonly type: "address";
+        }, {
+            readonly name: "expiry";
+            readonly type: "uint64";
+        }, {
+            readonly name: "status";
+            readonly type: "uint8";
+        }];
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "statusOf";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "orderHash";
+        readonly type: "bytes32";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint8";
+    }];
+}];
+export interface EscrowDepositInput {
+    escrow: Address;
+    orderHash: Hex32;
+    asset: Address;
+    amount: bigint;
+    payee: Address;
+    /** where refund/reclaim returns; defaults on-chain to the payer (msg.sender) when zero */
+    refundTo?: Address;
+    /** extra address allowed to release besides the payee; 0 = payee-only */
+    releaser?: Address;
+    expiry: number;
+}
+/** The deposit call (the payer SA must `approve` the escrow for `asset` first). */
+export declare function buildEscrowDeposit(input: EscrowDepositInput): TransferPlan;
+/** Capture the hold to the payee (payee or configured releaser executes). */
+export declare function buildEscrowRelease(escrow: Address, orderHash: Hex32): TransferPlan;
+/** Payee-consented refund to the payer, before capture. */
+export declare function buildEscrowRefund(escrow: Address, orderHash: Hex32): TransferPlan;
+/** Payer reclaims after expiry (never released). */
+export declare function buildEscrowReclaim(escrow: Address, orderHash: Hex32): TransferPlan;
+//# sourceMappingURL=escrow.d.ts.map

package/dist/rails/escrow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"escrow.d.ts","sourceRoot":"","sources":["../../src/rails/escrow.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAsB,KAAK,OAAO,EAAE,MAAM,MAAM,CAAC;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC,oCAAoC;AACpC,oBAAY,YAAY;IACtB,IAAI,IAAI;IACR,IAAI,IAAI;IACR,QAAQ,IAAI;IACZ,QAAQ,IAAI;IACZ,SAAS,IAAI;CACd;AAED,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyCb,CAAC;AAEX,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,KAAK,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;IACf,0FAA0F;IAC1F,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;CAChB;AAID,mFAAmF;AACnF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,kBAAkB,GAAG,YAAY,CAU1E;AAMD,6EAA6E;AAC7E,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,GAAG,YAAY,CAElF;AACD,2DAA2D;AAC3D,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,GAAG,YAAY,CAEjF;AACD,oDAAoD;AACpD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,GAAG,YAAY,CAElF"}

package/dist/rails/escrow.js

@@ -0,0 +1,90 @@
+/**
+ * Escrow rail (spec 243 §5.5, over PaymentEscrow.sol) — hold-and-capture for an order.
+ *
+ * Powers the deliver-then-pay flow: payer deposits a hold keyed by `orderHash` → provider
+ * fulfils → `release` captures to the payee (and the app mints the entitlement, pay-AFTER-
+ * fulfillment) → on failure/expiry `refund`/`reclaim` returns the funds. Builders emit the
+ * `{to: escrow, value, data}` calls an SA executes; deposit needs a prior `approve`
+ * (`buildErc20Approve`). App reads hold state via `getHold` (readContract), not log scans.
+ */
+import { encodeFunctionData } from 'viem';
+/** Mirrors PaymentEscrow.Status. */
+export var EscrowStatus;
+(function (EscrowStatus) {
+    EscrowStatus[EscrowStatus["None"] = 0] = "None";
+    EscrowStatus[EscrowStatus["Held"] = 1] = "Held";
+    EscrowStatus[EscrowStatus["Captured"] = 2] = "Captured";
+    EscrowStatus[EscrowStatus["Refunded"] = 3] = "Refunded";
+    EscrowStatus[EscrowStatus["Reclaimed"] = 4] = "Reclaimed";
+})(EscrowStatus || (EscrowStatus = {}));
+export const ESCROW_ABI = [
+    {
+        type: 'function',
+        name: 'deposit',
+        stateMutability: 'nonpayable',
+        inputs: [
+            { name: 'orderHash', type: 'bytes32' },
+            { name: 'asset', type: 'address' },
+            { name: 'amount', type: 'uint256' },
+            { name: 'payee', type: 'address' },
+            { name: 'refundTo', type: 'address' },
+            { name: 'releaser', type: 'address' },
+            { name: 'expiry', type: 'uint64' },
+        ],
+        outputs: [],
+    },
+    { type: 'function', name: 'release', stateMutability: 'nonpayable', inputs: [{ name: 'orderHash', type: 'bytes32' }], outputs: [] },
+    { type: 'function', name: 'refund', stateMutability: 'nonpayable', inputs: [{ name: 'orderHash', type: 'bytes32' }], outputs: [] },
+    { type: 'function', name: 'reclaim', stateMutability: 'nonpayable', inputs: [{ name: 'orderHash', type: 'bytes32' }], outputs: [] },
+    {
+        type: 'function',
+        name: 'getHold',
+        stateMutability: 'view',
+        inputs: [{ name: 'orderHash', type: 'bytes32' }],
+        outputs: [
+            {
+                type: 'tuple',
+                components: [
+                    { name: 'payer', type: 'address' },
+                    { name: 'asset', type: 'address' },
+                    { name: 'amount', type: 'uint256' },
+                    { name: 'payee', type: 'address' },
+                    { name: 'refundTo', type: 'address' },
+                    { name: 'releaser', type: 'address' },
+                    { name: 'expiry', type: 'uint64' },
+                    { name: 'status', type: 'uint8' },
+                ],
+            },
+        ],
+    },
+    { type: 'function', name: 'statusOf', stateMutability: 'view', inputs: [{ name: 'orderHash', type: 'bytes32' }], outputs: [{ type: 'uint8' }] },
+];
+const ZERO = '0x0000000000000000000000000000000000000000';
+/** The deposit call (the payer SA must `approve` the escrow for `asset` first). */
+export function buildEscrowDeposit(input) {
+    return {
+        to: input.escrow,
+        value: 0n,
+        data: encodeFunctionData({
+            abi: ESCROW_ABI,
+            functionName: 'deposit',
+            args: [input.orderHash, input.asset, input.amount, input.payee, input.refundTo ?? ZERO, input.releaser ?? ZERO, BigInt(input.expiry)],
+        }),
+    };
+}
+function call(escrow, fn, orderHash) {
+    return { to: escrow, value: 0n, data: encodeFunctionData({ abi: ESCROW_ABI, functionName: fn, args: [orderHash] }) };
+}
+/** Capture the hold to the payee (payee or configured releaser executes). */
+export function buildEscrowRelease(escrow, orderHash) {
+    return call(escrow, 'release', orderHash);
+}
+/** Payee-consented refund to the payer, before capture. */
+export function buildEscrowRefund(escrow, orderHash) {
+    return call(escrow, 'refund', orderHash);
+}
+/** Payer reclaims after expiry (never released). */
+export function buildEscrowReclaim(escrow, orderHash) {
+    return call(escrow, 'reclaim', orderHash);
+}
+//# sourceMappingURL=escrow.js.map

package/dist/rails/escrow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"escrow.js","sourceRoot":"","sources":["../../src/rails/escrow.ts"],"names":[],"mappings":"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"}

package/dist/rails/invoice.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Invoice rail (spec 243 §5.5, new) — request-for-payment (Request-Network pattern).
+ *
+ * A push artifact: the issuer publishes an `Invoice` (line items + total + payee + due);
+ * the payer reviews and pays it via the wallet rail, deriving a closed mandate bound to
+ * `invoiceId`/`orderHash`. The receipt links invoice ↔ settlement; "is this invoice paid?"
+ * resolves from receipts, never `eth_getLogs` (ADR-0012). No protocol dependency.
+ */
+import { type Address } from 'viem';
+import type { TransferPlan } from '../transfer.js';
+import type { PaymentMandate, AssetRef, Hex32 } from '../index.js';
+export interface InvoiceLineItem {
+    description: string;
+    amount: bigint;
+}
+export interface Invoice {
+    invoiceId: Hex32;
+    issuer: Address;
+    /** treasury that receives payment — MAY differ from the issuer */
+    payTo: Address;
+    lineItems: InvoiceLineItem[];
+    amount: bigint;
+    asset: AssetRef;
+    chain: number;
+    /** due time (unix seconds) — becomes the mandate's expiry at pay time */
+    dueAt: number;
+    /** hash of the memo body (body lives in a vault — privacy §6) */
+    memoHash: Hex32;
+    /** optional ExchangeOrder linkage (273/274); defaults to `invoiceId` at pay time */
+    orderHash?: Hex32;
+}
+export interface InvoiceInput {
+    issuer: Address;
+    payTo: Address;
+    lineItems: InvoiceLineItem[];
+    asset: AssetRef;
+    chain: number;
+    dueAt: number;
+    nonce: bigint;
+    memo?: string;
+    orderHash?: Hex32;
+}
+export declare function computeInvoiceId(args: {
+    issuer: Address;
+    payTo: Address;
+    amount: bigint;
+    asset: Address;
+    chain: number;
+    nonce: bigint;
+}): Hex32;
+/** Build an invoice; `amount` = sum of line items. */
+export declare function buildInvoice(input: InvoiceInput): Invoice;
+/**
+ * Pay an invoice via the wallet rail. Derives a closed mandate bound to the invoice
+ * (`orderHash = invoice.orderHash ?? invoiceId`) + the transfer plan. Sign the returned
+ * mandate with `signPaymentMandate`, then submit `plan`.
+ */
+export declare function payInvoice(invoice: Invoice, payer: Address, opts: {
+    nonce: bigint;
+    validFrom?: number;
+}): {
+    mandate: PaymentMandate;
+    plan: TransferPlan;
+};
+//# sourceMappingURL=invoice.d.ts.map

package/dist/rails/invoice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invoice.d.ts","sourceRoot":"","sources":["../../src/rails/invoice.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAA2C,KAAK,OAAO,EAAE,MAAM,MAAM,CAAC;AAG7E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAInE,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,OAAO;IACtB,SAAS,EAAE,KAAK,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,kEAAkE;IAClE,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,QAAQ,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,KAAK,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,QAAQ,EAAE,KAAK,CAAC;IAChB,oFAAoF;IACpF,SAAS,CAAC,EAAE,KAAK,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,KAAK,EAAE,QAAQ,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,KAAK,CAAC;CACnB;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,KAAK,CAO/I;AAED,sDAAsD;AACtD,wBAAgB,YAAY,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAezD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,cAAc,CAAC;IAAC,IAAI,EAAE,YAAY,CAAA;CAAE,CAiBzJ"}

package/dist/rails/invoice.js

@@ -0,0 +1,57 @@
+/**
+ * Invoice rail (spec 243 §5.5, new) — request-for-payment (Request-Network pattern).
+ *
+ * A push artifact: the issuer publishes an `Invoice` (line items + total + payee + due);
+ * the payer reviews and pays it via the wallet rail, deriving a closed mandate bound to
+ * `invoiceId`/`orderHash`. The receipt links invoice ↔ settlement; "is this invoice paid?"
+ * resolves from receipts, never `eth_getLogs` (ADR-0012). No protocol dependency.
+ */
+import { keccak256, encodeAbiParameters, toBytes } from 'viem';
+import { buildClosedMandate } from '../mandate.js';
+import { buildWalletTransferPlan } from './wallet.js';
+const ZERO32 = ('0x' + '00'.repeat(32));
+export function computeInvoiceId(args) {
+    return keccak256(encodeAbiParameters([{ type: 'address' }, { type: 'address' }, { type: 'uint256' }, { type: 'address' }, { type: 'uint256' }, { type: 'uint256' }], [args.issuer, args.payTo, args.amount, args.asset, BigInt(args.chain), args.nonce]));
+}
+/** Build an invoice; `amount` = sum of line items. */
+export function buildInvoice(input) {
+    const amount = input.lineItems.reduce((s, li) => s + li.amount, 0n);
+    if (amount <= 0n)
+        throw new Error('[invoice] amount must be > 0');
+    return {
+        invoiceId: computeInvoiceId({ issuer: input.issuer, payTo: input.payTo, amount, asset: input.asset.id, chain: input.chain, nonce: input.nonce }),
+        issuer: input.issuer,
+        payTo: input.payTo,
+        lineItems: input.lineItems,
+        amount,
+        asset: input.asset,
+        chain: input.chain,
+        dueAt: input.dueAt,
+        memoHash: input.memo ? keccak256(toBytes(input.memo)) : ZERO32,
+        orderHash: input.orderHash,
+    };
+}
+/**
+ * Pay an invoice via the wallet rail. Derives a closed mandate bound to the invoice
+ * (`orderHash = invoice.orderHash ?? invoiceId`) + the transfer plan. Sign the returned
+ * mandate with `signPaymentMandate`, then submit `plan`.
+ */
+export function payInvoice(invoice, payer, opts) {
+    const orderHash = invoice.orderHash ?? invoice.invoiceId;
+    const mandate = buildClosedMandate({
+        rail: 'wallet',
+        payer,
+        payee: invoice.payTo,
+        asset: invoice.asset,
+        amount: invoice.amount,
+        chain: invoice.chain,
+        nonce: opts.nonce,
+        validFrom: opts.validFrom,
+        expiresAt: invoice.dueAt,
+        orderHash,
+        legId: invoice.invoiceId,
+        reasonHash: invoice.memoHash,
+    });
+    return { mandate, plan: buildWalletTransferPlan(mandate) };
+}
+//# sourceMappingURL=invoice.js.map

package/dist/rails/invoice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invoice.js","sourceRoot":"","sources":["../../src/rails/invoice.ts"],"names":[],"mappings":"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"}

package/dist/rails/recurring.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Recurring profile (spec 243 §5.5 / PMT-10) — NOT a rail, a mandate pattern.
+ *
+ * The payer authorizes ONCE (an open payment delegation whose caveats carry the per-charge
+ * cap + the frequency window + the aggregate cap); each period derives a CLOSED per-charge
+ * mandate settled via the wallet rail. The `PaymentEnforcer`'s on-chain frequency window +
+ * aggregate cap do the real enforcement — `recurringCaveatParams` returns the values the app
+ * feeds to `delegation.buildPaymentMandateCaveats` (payments doesn't runtime-import delegation).
+ */
+import type { Address } from '@agenticprimitives/types';
+import type { TransferPlan } from '../transfer.js';
+import type { PaymentMandate, AssetRef, Hex32 } from '../index.js';
+export interface RecurringInput {
+    payer: Address;
+    payee: Address;
+    asset: AssetRef;
+    chain: number;
+    amountPerPeriod: bigint;
+    windowSeconds: number;
+    /** total spend ceiling across all periods (aggregate cap) */
+    totalCap: bigint;
+    validFrom: number;
+    validUntil: number;
+    /** base nonce; period N's charge uses `startNonce + N` */
+    startNonce: bigint;
+}
+export interface RecurringTemplate extends RecurringInput {
+    templateId: Hex32;
+    /** number of periods the totalCap covers at amountPerPeriod */
+    periods: number;
+}
+export declare function buildRecurringTemplate(input: RecurringInput): RecurringTemplate;
+export interface RecurringCaveatParams {
+    maxAmountPerCharge: bigint;
+    maxAggregate: bigint;
+    maxRedemptionsPerWindow: number;
+    windowSeconds: number;
+    validUntil: number;
+}
+/** The values the app feeds to `delegation.buildPaymentMandateCaveats` for the one-time authorization. */
+export declare function recurringCaveatParams(t: RecurringTemplate): RecurringCaveatParams;
+/** The time window in which period N may be charged (the enforcer rejects an early re-charge). */
+export declare function periodWindow(t: RecurringTemplate, period: number): {
+    start: number;
+    end: number;
+};
+/** Derive the closed per-charge mandate + transfer plan for period N. Sign the mandate, then settle. */
+export declare function deriveScheduledCharge(t: RecurringTemplate, period: number): {
+    mandate: PaymentMandate;
+    plan: TransferPlan;
+    window: {
+        start: number;
+        end: number;
+    };
+};
+//# sourceMappingURL=recurring.d.ts.map

package/dist/rails/recurring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recurring.d.ts","sourceRoot":"","sources":["../../src/rails/recurring.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAIxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEnE,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,QAAQ,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,6DAA6D;IAC7D,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iBAAkB,SAAQ,cAAc;IACvD,UAAU,EAAE,KAAK,CAAC;IAClB,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,cAAc,GAAG,iBAAiB,CAW/E;AAED,MAAM,WAAW,qBAAqB;IACpC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,uBAAuB,EAAE,MAAM,CAAC;IAChC,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,0GAA0G;AAC1G,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,iBAAiB,GAAG,qBAAqB,CAQjF;AAED,kGAAkG;AAClG,wBAAgB,YAAY,CAAC,CAAC,EAAE,iBAAiB,EAAE,MAAM,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAGjG;AAED,wGAAwG;AACxG,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,iBAAiB,EAAE,MAAM,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,cAAc,CAAC;IAAC,IAAI,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAiBnK"}

package/dist/rails/recurring.js

@@ -0,0 +1,58 @@
+/**
+ * Recurring profile (spec 243 §5.5 / PMT-10) — NOT a rail, a mandate pattern.
+ *
+ * The payer authorizes ONCE (an open payment delegation whose caveats carry the per-charge
+ * cap + the frequency window + the aggregate cap); each period derives a CLOSED per-charge
+ * mandate settled via the wallet rail. The `PaymentEnforcer`'s on-chain frequency window +
+ * aggregate cap do the real enforcement — `recurringCaveatParams` returns the values the app
+ * feeds to `delegation.buildPaymentMandateCaveats` (payments doesn't runtime-import delegation).
+ */
+import { keccak256, encodeAbiParameters } from 'viem';
+import { buildClosedMandate } from '../mandate.js';
+import { buildWalletTransferPlan } from './wallet.js';
+export function buildRecurringTemplate(input) {
+    if (input.amountPerPeriod <= 0n)
+        throw new Error('[recurring] amountPerPeriod must be > 0');
+    if (input.totalCap < input.amountPerPeriod)
+        throw new Error('[recurring] totalCap must be >= amountPerPeriod');
+    if (input.windowSeconds <= 0)
+        throw new Error('[recurring] windowSeconds must be > 0');
+    const templateId = keccak256(encodeAbiParameters([{ type: 'address' }, { type: 'address' }, { type: 'uint256' }, { type: 'uint256' }, { type: 'uint256' }], [input.payer, input.payee, input.amountPerPeriod, BigInt(input.windowSeconds), input.startNonce]));
+    return { ...input, templateId, periods: Number(input.totalCap / input.amountPerPeriod) };
+}
+/** The values the app feeds to `delegation.buildPaymentMandateCaveats` for the one-time authorization. */
+export function recurringCaveatParams(t) {
+    return {
+        maxAmountPerCharge: t.amountPerPeriod,
+        maxAggregate: t.totalCap,
+        maxRedemptionsPerWindow: 1, // one charge per window
+        windowSeconds: t.windowSeconds,
+        validUntil: t.validUntil,
+    };
+}
+/** The time window in which period N may be charged (the enforcer rejects an early re-charge). */
+export function periodWindow(t, period) {
+    const start = t.validFrom + period * t.windowSeconds;
+    return { start, end: start + t.windowSeconds };
+}
+/** Derive the closed per-charge mandate + transfer plan for period N. Sign the mandate, then settle. */
+export function deriveScheduledCharge(t, period) {
+    if (period < 0 || period >= t.periods)
+        throw new Error(`[recurring] period out of range [0, ${t.periods})`);
+    const window = periodWindow(t, period);
+    const mandate = buildClosedMandate({
+        rail: 'wallet',
+        payer: t.payer,
+        payee: t.payee,
+        asset: t.asset,
+        amount: t.amountPerPeriod,
+        chain: t.chain,
+        nonce: t.startNonce + BigInt(period),
+        validFrom: window.start,
+        expiresAt: window.end,
+        orderHash: t.templateId,
+        legId: ('0x' + period.toString(16).padStart(64, '0')),
+    });
+    return { mandate, plan: buildWalletTransferPlan(mandate), window };
+}
+//# sourceMappingURL=recurring.js.map

package/dist/rails/recurring.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recurring.js","sourceRoot":"","sources":["../../src/rails/recurring.ts"],"names":[],"mappings":"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"}

package/dist/rails/wallet.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Wallet rail (spec 243 §5.3/§5.5) — direct SA→SA transfer of a CLOSED mandate.
+ *
+ * Plain "checkout" pay: no budget delegation, no 402 round-trip. The payer SA executes a
+ * single ERC-20 transfer to the payee. Nullifier + receipt are identical to x402 (EXC-D3
+ * evidence symmetry). Ports the smart-agent `PledgeRegistry` cryptographic-rail pattern.
+ */
+import { type ClosedMandateInput } from '../mandate.js';
+import { type TransferPlan } from '../transfer.js';
+import type { PaymentMandate } from '../index.js';
+export declare const WALLET_RAIL: "wallet";
+/** Build an unsigned closed wallet-rail mandate (sign with `signPaymentMandate`). */
+export declare function buildWalletMandate(input: Omit<ClosedMandateInput, 'rail'>): PaymentMandate;
+/** The settlement plan for a closed wallet mandate: a direct transfer payer → payee. */
+export declare function buildWalletTransferPlan(mandate: PaymentMandate): TransferPlan;
+//# sourceMappingURL=wallet.d.ts.map

package/dist/rails/wallet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wallet.d.ts","sourceRoot":"","sources":["../../src/rails/wallet.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAC5E,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACvE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,eAAO,MAAM,WAAW,EAAG,QAAiB,CAAC;AAE7C,qFAAqF;AACrF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,IAAI,CAAC,kBAAkB,EAAE,MAAM,CAAC,GAAG,cAAc,CAE1F;AAED,wFAAwF;AACxF,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,cAAc,GAAG,YAAY,CAE7E"}

package/dist/rails/wallet.js

@@ -0,0 +1,20 @@
+/**
+ * Wallet rail (spec 243 §5.3/§5.5) — direct SA→SA transfer of a CLOSED mandate.
+ *
+ * Plain "checkout" pay: no budget delegation, no 402 round-trip. The payer SA executes a
+ * single ERC-20 transfer to the payee. Nullifier + receipt are identical to x402 (EXC-D3
+ * evidence symmetry). Ports the smart-agent `PledgeRegistry` cryptographic-rail pattern.
+ */
+import { mandateAmount } from '../mandate-sign.js';
+import { buildClosedMandate } from '../mandate.js';
+import { buildErc20Transfer } from '../transfer.js';
+export const WALLET_RAIL = 'wallet';
+/** Build an unsigned closed wallet-rail mandate (sign with `signPaymentMandate`). */
+export function buildWalletMandate(input) {
+    return buildClosedMandate({ ...input, rail: 'wallet' });
+}
+/** The settlement plan for a closed wallet mandate: a direct transfer payer → payee. */
+export function buildWalletTransferPlan(mandate) {
+    return buildErc20Transfer(mandate.amountPolicy.asset.id, mandate.payee, mandateAmount(mandate));
+}
+//# sourceMappingURL=wallet.js.map

package/dist/rails/wallet.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wallet.js","sourceRoot":"","sources":["../../src/rails/wallet.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,kBAAkB,EAA2B,MAAM,eAAe,CAAC;AAC5E,OAAO,EAAE,kBAAkB,EAAqB,MAAM,gBAAgB,CAAC;AAGvE,MAAM,CAAC,MAAM,WAAW,GAAG,QAAiB,CAAC;AAE7C,qFAAqF;AACrF,MAAM,UAAU,kBAAkB,CAAC,KAAuC;IACxE,OAAO,kBAAkB,CAAC,EAAE,GAAG,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;AAC1D,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,uBAAuB,CAAC,OAAuB;IAC7D,OAAO,kBAAkB,CAAC,OAAO,CAAC,YAAY,CAAC,KAAK,CAAC,EAAa,EAAE,OAAO,CAAC,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC;AAC7G,CAAC"}

package/dist/rails/x402/executor.d.ts

@@ -68,6 +68,22 @@ export interface X402RailDeps {
     }) => Promise<{
         settlementHash: Hex32;
     }>;
+    /** PAY-RAIL-6 — dry-run the redemption (eth_call / estimateGas) BEFORE the nonce is burned, so a
+     *  reverting or griefing settlement is rejected without consuming the one-shot mandate. Injected by
+     *  the app; omit to skip simulation. Returns ok + optional gas estimate. */
+    simulate?: (plan: {
+        to: Address;
+        value: bigint;
+        data: Hex;
+    }) => Promise<{
+        ok: boolean;
+        reason?: string;
+        gas?: bigint;
+    }>;
+    /** Anti-griefing: reject a settlement whose simulated gas exceeds this cap. */
+    maxGasPerSettlement?: bigint;
+    /** Anti-griefing: abort `submitRedemption` if it doesn't resolve within this many ms (settlement timeout). */
+    settlementTimeoutMs?: number;
     now?: () => number;
 }
 export type SettleResult = {
@@ -79,7 +95,7 @@ export type SettleResult = {
     ok: false;
     reason: string;
 };
-/** The staged x402 rail. `settle` runs verify → revoke → reserve(nullifier) → prepare → submit →
+/** The staged x402 rail. `settle` runs verify → revoke → reserve(nullifier) → simulate → submit →
  *  receipt; a safe retry of an already-settled request returns the original receipt (idempotent). */
 export declare function createX402Rail(deps: X402RailDeps): {
     rail: "x402";

package/dist/rails/x402/executor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../../src/rails/x402/executor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../../src/rails/x402/executor.ts"],"names":[],"mappings":"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"}

package/dist/rails/x402/executor.js

@@ -146,7 +146,13 @@ export function buildRedemptionCalldata(args) {
     });
     return { to: args.delegationManager, value: 0n, data };
 }
-/** The staged x402 rail. `settle` runs verify → revoke → reserve(nullifier) → prepare → submit →
+function withTimeout(p, ms) {
+    return new Promise((resolve, reject) => {
+        const t = setTimeout(() => reject(new Error(`settlement timed out after ${ms}ms`)), ms);
+        p.then((v) => { clearTimeout(t); resolve(v); }, (e) => { clearTimeout(t); reject(e); });
+    });
+}
+/** The staged x402 rail. `settle` runs verify → revoke → reserve(nullifier) → simulate → submit →
  *  receipt; a safe retry of an already-settled request returns the original receipt (idempotent). */
 export function createX402Rail(deps) {
     const now = deps.now ?? (() => Math.floor(Date.now() / 1000));
@@ -183,9 +189,25 @@ export function createX402Rail(deps) {
             asset: deps.asset,
             resourceHash: quote.resourceHash,
         });
+        // PAY-RAIL-6 — simulate before burning the nonce: a reverting or over-gas settlement is
+        // rejected as RETRYABLE so the one-shot mandate survives for a corrected resubmit.
+        if (deps.simulate) {
+            const sim = await deps.simulate(plan);
+            if (!sim.ok) {
+                await deps.nonceStore.markFailed(nullifier, true);
+                return { ok: false, reason: `simulation reverted${sim.reason ? `: ${sim.reason}` : ''}` };
+            }
+            if (deps.maxGasPerSettlement !== undefined && sim.gas !== undefined && sim.gas > deps.maxGasPerSettlement) {
+                await deps.nonceStore.markFailed(nullifier, true);
+                return { ok: false, reason: `settlement gas ${sim.gas} exceeds cap ${deps.maxGasPerSettlement}` };
+            }
+        }
         await deps.nonceStore.markSettling(nullifier);
         try {
-            const { settlementHash } = await deps.submitRedemption(plan);
+            const submit = deps.submitRedemption(plan);
+            const { settlementHash } = deps.settlementTimeoutMs
+                ? await withTimeout(submit, deps.settlementTimeoutMs)
+                : await submit;
             const receipt = { settlementHash, mandateId: mandate.mandateId };
             await deps.nonceStore.markSettled(nullifier, receipt);
             return { ok: true, settlementHash, mandateId: mandate.mandateId, idempotent: false };