@agenticprimitives/payments 0.0.0-alpha.10

package/dist/mandate.js

@@ -0,0 +1,40 @@
+/**
+ * `buildClosedMandate` — construct an unsigned closed (one-shot) PaymentMandate.
+ *
+ * The wallet + invoice rails (and the demo) build a closed mandate, sign it via
+ * `signPaymentMandate`, then settle it with a single transfer. Closed + one-shot per
+ * PMT-10 / PMT-INV-14. `orderHash`/`legId` (EXC-R2) bind the leg to an ExchangeOrder.
+ */
+import { computeMandateId } from './index.js';
+const ZERO32 = ('0x' + '00'.repeat(32));
+/** Build the unsigned closed mandate (signature `'0x'`); sign with `signPaymentMandate`. */
+export function buildClosedMandate(input) {
+    const validFrom = input.validFrom ?? 0;
+    return {
+        mandateId: computeMandateId({ payer: input.payer, nonce: input.nonce, rail: input.rail, chain: input.chain }),
+        payer: input.payer,
+        payee: input.payee,
+        granter: input.granter ?? input.payer,
+        rail: input.rail,
+        amountPolicy: { kind: 'exact', amount: input.amount, asset: input.asset, chain: input.chain },
+        nonce: input.nonce,
+        maxRedemptions: 1,
+        validFrom,
+        expiresAt: input.expiresAt,
+        contextBinding: {
+            ...(input.resource ? { resource: input.resource } : {}),
+            orderHash: input.orderHash,
+            legId: input.legId,
+            chain: input.chain,
+            asset: input.asset,
+            nonce: input.nonce,
+            validFrom,
+            expiresAt: input.expiresAt,
+        },
+        delegationRef: input.delegationRef,
+        mode: 'closed',
+        reasonHash: input.reasonHash ?? ZERO32,
+        signature: '0x',
+    };
+}
+//# sourceMappingURL=mandate.js.map

package/dist/mandate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mandate.js","sourceRoot":"","sources":["../src/mandate.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,gBAAgB,EAAoE,MAAM,YAAY,CAAC;AAEhH,MAAM,MAAM,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAU,CAAC;AAoBjD,4FAA4F;AAC5F,MAAM,UAAU,kBAAkB,CAAC,KAAyB;IAC1D,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,IAAI,CAAC,CAAC;IACvC,OAAO;QACL,SAAS,EAAE,gBAAgB,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC;QAC7G,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,KAAK;QACrC,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,YAAY,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE;QAC7F,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,cAAc,EAAE,CAAC;QACjB,SAAS;QACT,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,cAAc,EAAE;YACd,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACvD,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,SAAS;YACT,SAAS,EAAE,KAAK,CAAC,SAAS;SAC3B;QACD,aAAa,EAAE,KAAK,CAAC,aAAa;QAClC,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE,KAAK,CAAC,UAAU,IAAI,MAAM;QACtC,SAAS,EAAE,IAAI;KAChB,CAAC;AACJ,CAAC"}

package/dist/ops.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Payment ops core (spec 243 §5.5) — the plumbing every mature payment stack needs:
+ * an idempotent event model + webhook-style subscribers, reconciliation/payment-detection,
+ * and receipt export. In-process for W1 (the app delivers webhooks later). Pure — no I/O.
+ */
+import type { Address } from '@agenticprimitives/types';
+import type { Hex32 } from './index.js';
+export type PaymentEventType = 'payment.created' | 'payment.reserved' | 'payment.settling' | 'payment.settled' | 'payment.failed' | 'payment.refunded' | 'payment.expired' | 'payment.disputed' | 'entitlement.issued' | 'entitlement.consumed';
+export interface PaymentEvent {
+    /** dedupe key — re-emitting the same key is a no-op (at-least-once producers, exactly-once consumers) */
+    idempotencyKey: string;
+    type: PaymentEventType;
+    at: number;
+    orderHash?: Hex32;
+    mandateId?: Hex32;
+    data?: Record<string, unknown>;
+}
+export interface PaymentEventLog {
+    /** Returns `{ accepted: false }` when `idempotencyKey` was already seen (no re-emit, no re-notify). */
+    emit(event: PaymentEvent): {
+        accepted: boolean;
+    };
+    list(): PaymentEvent[];
+    byType(type: PaymentEventType): PaymentEvent[];
+    byOrder(orderHash: Hex32): PaymentEvent[];
+    /** Webhook-style subscriber — invoked once per ACCEPTED event. Returns an unsubscribe fn. */
+    subscribe(fn: (event: PaymentEvent) => void): () => void;
+}
+export declare function createPaymentEventLog(): PaymentEventLog;
+export interface ReceiptRow {
+    mandateId: Hex32;
+    payer: Address;
+    payee: Address;
+    asset: Address;
+    amount: bigint;
+    settlementHash: Hex32;
+    at: number;
+    orderHash?: Hex32;
+    /** set on a refund leg — the original charge it reverses */
+    refunds?: Hex32;
+}
+export interface ReceiptFilter {
+    payer?: Address;
+    payee?: Address;
+    orderHash?: Hex32;
+    asset?: Address;
+}
+export declare function listReceiptsBy(receipts: ReceiptRow[], filter: ReceiptFilter): ReceiptRow[];
+/** Net balance change for `account` across the receipt set (incoming as payee − outgoing as payer). */
+export declare function balanceDelta(receipts: ReceiptRow[], account: Address): bigint;
+/** Payment detection: is `orderHash` paid (optionally to ≥ `expectedAmount`)? From receipts, not logs. */
+export declare function isOrderPaid(receipts: ReceiptRow[], orderHash: Hex32, expectedAmount?: bigint): boolean;
+export declare function exportReceiptsJSON(receipts: ReceiptRow[]): string;
+export declare function exportReceiptsCSV(receipts: ReceiptRow[]): string;
+//# sourceMappingURL=ops.d.ts.map

package/dist/ops.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ops.d.ts","sourceRoot":"","sources":["../src/ops.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC,MAAM,MAAM,gBAAgB,GACxB,iBAAiB,GACjB,kBAAkB,GAClB,kBAAkB,GAClB,iBAAiB,GACjB,gBAAgB,GAChB,kBAAkB,GAClB,iBAAiB,GACjB,kBAAkB,GAClB,oBAAoB,GACpB,sBAAsB,CAAC;AAE3B,MAAM,WAAW,YAAY;IAC3B,yGAAyG;IACzG,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,gBAAgB,CAAC;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,CAAC,EAAE,KAAK,CAAC;IAClB,SAAS,CAAC,EAAE,KAAK,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,eAAe;IAC9B,uGAAuG;IACvG,IAAI,CAAC,KAAK,EAAE,YAAY,GAAG;QAAE,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAC;IACjD,IAAI,IAAI,YAAY,EAAE,CAAC;IACvB,MAAM,CAAC,IAAI,EAAE,gBAAgB,GAAG,YAAY,EAAE,CAAC;IAC/C,OAAO,CAAC,SAAS,EAAE,KAAK,GAAG,YAAY,EAAE,CAAC;IAC1C,6FAA6F;IAC7F,SAAS,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CAC1D;AAED,wBAAgB,qBAAqB,IAAI,eAAe,CAoBvD;AAID,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,KAAK,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,KAAK,CAAC;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,CAAC,EAAE,KAAK,CAAC;IAClB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,KAAK,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,SAAS,CAAC,EAAE,KAAK,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAID,wBAAgB,cAAc,CAAC,QAAQ,EAAE,UAAU,EAAE,EAAE,MAAM,EAAE,aAAa,GAAG,UAAU,EAAE,CAQ1F;AAED,uGAAuG;AACvG,wBAAgB,YAAY,CAAC,QAAQ,EAAE,UAAU,EAAE,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAO7E;AAED,0GAA0G;AAC1G,wBAAgB,WAAW,CAAC,QAAQ,EAAE,UAAU,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAMtG;AAID,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,UAAU,EAAE,GAAG,MAAM,CAMjE;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,UAAU,EAAE,GAAG,MAAM,CAMhE"}

package/dist/ops.js

@@ -0,0 +1,66 @@
+/**
+ * Payment ops core (spec 243 §5.5) — the plumbing every mature payment stack needs:
+ * an idempotent event model + webhook-style subscribers, reconciliation/payment-detection,
+ * and receipt export. In-process for W1 (the app delivers webhooks later). Pure — no I/O.
+ */
+export function createPaymentEventLog() {
+    const events = [];
+    const seen = new Set();
+    const subs = new Set();
+    return {
+        emit(event) {
+            if (seen.has(event.idempotencyKey))
+                return { accepted: false };
+            seen.add(event.idempotencyKey);
+            events.push(event);
+            for (const fn of subs)
+                fn(event);
+            return { accepted: true };
+        },
+        list: () => [...events],
+        byType: (type) => events.filter((e) => e.type === type),
+        byOrder: (orderHash) => events.filter((e) => e.orderHash?.toLowerCase() === orderHash.toLowerCase()),
+        subscribe(fn) {
+            subs.add(fn);
+            return () => subs.delete(fn);
+        },
+    };
+}
+const eq = (a, b) => (a && b ? a.toLowerCase() === b.toLowerCase() : a === b);
+export function listReceiptsBy(receipts, filter) {
+    return receipts.filter((r) => (filter.payer === undefined || eq(r.payer, filter.payer)) &&
+        (filter.payee === undefined || eq(r.payee, filter.payee)) &&
+        (filter.asset === undefined || eq(r.asset, filter.asset)) &&
+        (filter.orderHash === undefined || eq(r.orderHash, filter.orderHash)));
+}
+/** Net balance change for `account` across the receipt set (incoming as payee − outgoing as payer). */
+export function balanceDelta(receipts, account) {
+    let delta = 0n;
+    for (const r of receipts) {
+        if (eq(r.payee, account))
+            delta += r.amount;
+        if (eq(r.payer, account))
+            delta -= r.amount;
+    }
+    return delta;
+}
+/** Payment detection: is `orderHash` paid (optionally to ≥ `expectedAmount`)? From receipts, not logs. */
+export function isOrderPaid(receipts, orderHash, expectedAmount) {
+    const charges = receipts.filter((r) => eq(r.orderHash, orderHash) && !r.refunds);
+    if (charges.length === 0)
+        return false;
+    if (expectedAmount === undefined)
+        return true;
+    const total = charges.reduce((s, r) => s + r.amount, 0n);
+    return total >= expectedAmount;
+}
+// ── export ──────────────────────────────────────────────────────────
+export function exportReceiptsJSON(receipts) {
+    return JSON.stringify(receipts.map((r) => ({ ...r, amount: r.amount.toString() })), null, 2);
+}
+export function exportReceiptsCSV(receipts) {
+    const header = 'mandateId,payer,payee,asset,amount,settlementHash,at,orderHash,refunds';
+    const rows = receipts.map((r) => [r.mandateId, r.payer, r.payee, r.asset, r.amount.toString(), r.settlementHash, r.at, r.orderHash ?? '', r.refunds ?? ''].join(','));
+    return [header, ...rows].join('\n');
+}
+//# sourceMappingURL=ops.js.map

package/dist/ops.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ops.js","sourceRoot":"","sources":["../src/ops.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAqCH,MAAM,UAAU,qBAAqB;IACnC,MAAM,MAAM,GAAmB,EAAE,CAAC;IAClC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,IAAI,GAAG,IAAI,GAAG,EAA6B,CAAC;IAClD,OAAO;QACL,IAAI,CAAC,KAAK;YACR,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,cAAc,CAAC;gBAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;YAC/D,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;YAC/B,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACnB,KAAK,MAAM,EAAE,IAAI,IAAI;gBAAE,EAAE,CAAC,KAAK,CAAC,CAAC;YACjC,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;QAC5B,CAAC;QACD,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC;QACvB,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC;QACvD,OAAO,EAAE,CAAC,SAAS,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,EAAE,WAAW,EAAE,KAAK,SAAS,CAAC,WAAW,EAAE,CAAC;QACpG,SAAS,CAAC,EAAE;YACV,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACb,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAC/B,CAAC;KACF,CAAC;AACJ,CAAC;AAwBD,MAAM,EAAE,GAAG,CAAC,CAAU,EAAE,CAAU,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;AAEhG,MAAM,UAAU,cAAc,CAAC,QAAsB,EAAE,MAAqB;IAC1E,OAAO,QAAQ,CAAC,MAAM,CACpB,CAAC,CAAC,EAAE,EAAE,CACJ,CAAC,MAAM,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;QACzD,CAAC,MAAM,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;QACzD,CAAC,MAAM,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;QACzD,CAAC,MAAM,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC,CACxE,CAAC;AACJ,CAAC;AAED,uGAAuG;AACvG,MAAM,UAAU,YAAY,CAAC,QAAsB,EAAE,OAAgB;IACnE,IAAI,KAAK,GAAG,EAAE,CAAC;IACf,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzB,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,EAAE,OAAO,CAAC;YAAE,KAAK,IAAI,CAAC,CAAC,MAAM,CAAC;QAC5C,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,EAAE,OAAO,CAAC;YAAE,KAAK,IAAI,CAAC,CAAC,MAAM,CAAC;IAC9C,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,0GAA0G;AAC1G,MAAM,UAAU,WAAW,CAAC,QAAsB,EAAE,SAAgB,EAAE,cAAuB;IAC3F,MAAM,OAAO,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IACjF,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACvC,IAAI,cAAc,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IAC9C,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACzD,OAAO,KAAK,IAAI,cAAc,CAAC;AACjC,CAAC;AAED,uEAAuE;AAEvE,MAAM,UAAU,kBAAkB,CAAC,QAAsB;IACvD,OAAO,IAAI,CAAC,SAAS,CACnB,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,EAC5D,IAAI,EACJ,CAAC,CACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,QAAsB;IACtD,MAAM,MAAM,GAAG,wEAAwE,CAAC;IACxF,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAC9B,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,cAAc,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,SAAS,IAAI,EAAE,EAAE,CAAC,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CACpI,CAAC;IACF,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACtC,CAAC"}

package/dist/rails/escrow.d.ts

@@ -0,0 +1,156 @@
+/**
+ * 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: "payer";
+        readonly type: "address";
+    }, {
+        readonly name: "orderHash";
+        readonly type: "bytes32";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "refund";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "payer";
+        readonly type: "address";
+    }, {
+        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: "payer";
+        readonly type: "address";
+    }, {
+        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: "payer";
+        readonly type: "address";
+    }, {
+        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). EXT-PMT-3: holds are keyed by
+ *  (payer, orderHash), so the releasing party must pass the payer. Cannot release at/after expiry. */
+export declare function buildEscrowRelease(escrow: Address, payer: Address, orderHash: Hex32): TransferPlan;
+/** Payee-consented refund to the payer, before capture. */
+export declare function buildEscrowRefund(escrow: Address, payer: Address, orderHash: Hex32): TransferPlan;
+/** Payer reclaims after expiry (never released). Payer-initiated → keyed off msg.sender on-chain. */
+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;AAED;sGACsG;AACtG,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,GAAG,YAAY,CAElG;AACD,2DAA2D;AAC3D,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,GAAG,YAAY,CAEjG;AACD,qGAAqG;AACrG,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,GAAG,YAAY,CAElF"}

package/dist/rails/escrow.js

@@ -0,0 +1,88 @@
+/**
+ * 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: 'payer', type: 'address' }, { name: 'orderHash', type: 'bytes32' }], outputs: [] },
+    { type: 'function', name: 'refund', stateMutability: 'nonpayable', inputs: [{ name: 'payer', type: 'address' }, { 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: 'payer', type: 'address' }, { 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: 'payer', type: 'address' }, { 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)],
+        }),
+    };
+}
+/** Capture the hold to the payee (payee or configured releaser executes). EXT-PMT-3: holds are keyed by
+ *  (payer, orderHash), so the releasing party must pass the payer. Cannot release at/after expiry. */
+export function buildEscrowRelease(escrow, payer, orderHash) {
+    return { to: escrow, value: 0n, data: encodeFunctionData({ abi: ESCROW_ABI, functionName: 'release', args: [payer, orderHash] }) };
+}
+/** Payee-consented refund to the payer, before capture. */
+export function buildEscrowRefund(escrow, payer, orderHash) {
+    return { to: escrow, value: 0n, data: encodeFunctionData({ abi: ESCROW_ABI, functionName: 'refund', args: [payer, orderHash] }) };
+}
+/** Payer reclaims after expiry (never released). Payer-initiated → keyed off msg.sender on-chain. */
+export function buildEscrowReclaim(escrow, orderHash) {
+    return { to: escrow, value: 0n, data: encodeFunctionData({ abi: ESCROW_ABI, functionName: 'reclaim', args: [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":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,kBAAkB,EAAgB,MAAM,MAAM,CAAC;AAIxD,oCAAoC;AACpC,MAAM,CAAN,IAAY,YAMX;AAND,WAAY,YAAY;IACtB,+CAAQ,CAAA;IACR,+CAAQ,CAAA;IACR,uDAAY,CAAA;IACZ,uDAAY,CAAA;IACZ,yDAAa,CAAA;AACf,CAAC,EANW,YAAY,KAAZ,YAAY,QAMvB;AAED,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB;QACE,IAAI,EAAE,UAAU;QAChB,IAAI,EAAE,SAAS;QACf,eAAe,EAAE,YAAY;QAC7B,MAAM,EAAE;YACN,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,EAAE;YACtC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE;YAClC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE;YACnC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE;YAClC,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE;YACrC,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE;YACrC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE;SACnC;QACD,OAAO,EAAE,EAAE;KACZ;IACD,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE;IACvK,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE;IACtK,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE;IACnI;QACE,IAAI,EAAE,UAAU;QAChB,IAAI,EAAE,SAAS;QACf,eAAe,EAAE,MAAM;QACvB,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QACpF,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,OAAO;gBACb,UAAU,EAAE;oBACV,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE;oBAClC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE;oBAClC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE;oBACnC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE;oBAClC,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE;oBACrC,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE;oBACrC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE;oBAClC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE;iBAClC;aACF;SACF;KACF;IACD,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE;CAC3K,CAAC;AAeX,MAAM,IAAI,GAAG,4CAAuD,CAAC;AAErE,mFAAmF;AACnF,MAAM,UAAU,kBAAkB,CAAC,KAAyB;IAC1D,OAAO;QACL,EAAE,EAAE,KAAK,CAAC,MAAM;QAChB,KAAK,EAAE,EAAE;QACT,IAAI,EAAE,kBAAkB,CAAC;YACvB,GAAG,EAAE,UAAU;YACf,YAAY,EAAE,SAAS;YACvB,IAAI,EAAE,CAAC,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,IAAI,IAAI,EAAE,KAAK,CAAC,QAAQ,IAAI,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;SACtI,CAAC;KACH,CAAC;AACJ,CAAC;AAED;sGACsG;AACtG,MAAM,UAAU,kBAAkB,CAAC,MAAe,EAAE,KAAc,EAAE,SAAgB;IAClF,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,kBAAkB,CAAC,EAAE,GAAG,EAAE,UAAU,EAAE,YAAY,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,CAAC,EAAE,CAAC;AACrI,CAAC;AACD,2DAA2D;AAC3D,MAAM,UAAU,iBAAiB,CAAC,MAAe,EAAE,KAAc,EAAE,SAAgB;IACjF,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,kBAAkB,CAAC,EAAE,GAAG,EAAE,UAAU,EAAE,YAAY,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,CAAC,EAAE,CAAC;AACpI,CAAC;AACD,qGAAqG;AACrG,MAAM,UAAU,kBAAkB,CAAC,MAAe,EAAE,SAAgB;IAClE,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,kBAAkB,CAAC,EAAE,GAAG,EAAE,UAAU,EAAE,YAAY,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,CAAC;AAC9H,CAAC"}

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"}