@agenticprimitives/payments 0.0.0-alpha.3 → 0.0.0-alpha.5

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

@@ -0,0 +1 @@
+{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../../../src/rails/x402/resource.ts"],"names":[],"mappings":"AAIA,OAAO,EAAkC,KAAK,OAAO,EAAE,MAAM,MAAM,CAAC;AAEpE,MAAM,MAAM,KAAK,GAAG,KAAK,MAAM,EAAE,CAAC;AAClC,eAAO,MAAM,SAAS,EAAE,KAA4E,CAAC;AAErG;;oEAEoE;AACpE,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,GAAG,KAAK,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,KAAK,CAAC;IAChB,YAAY,EAAE,OAAO,CAAC;IACtB,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,KAAK,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;2BAE2B;AAC3B,wBAAgB,2BAA2B,CAAC,CAAC,EAAE,eAAe,GAAG,KAAK,CAmCrE;AAED,iGAAiG;AACjG,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,GAAG,KAAK,CAI5E;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE;IAC3C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,KAAK,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,CAgB9D"}

package/dist/rails/x402/resource.js

@@ -0,0 +1,71 @@
+// Spec 272 PAY-WIRE-5/6 — the resource binding (the security-critical object: bind the payment to the
+// EXACT request, not just the amount) + metadata redaction. ONE shared canonicalizer for HTTP + A2A so
+// workers never hand-roll URL/body hashing.
+import { encodeAbiParameters, keccak256 } from 'viem';
+export const ZERO_HASH = '0x0000000000000000000000000000000000000000000000000000000000000000';
+/** keccak256 over an ABI-encoded canonical tuple of every binding field. Deterministic across HTTP +
+ *  A2A. NOTE: `quoteId` is NOT an input here (it's derived FROM this hash — see quote.ts) to avoid a
+ *  circular dependency. */
+export function canonicalizePaymentResource(r) {
+    return keccak256(encodeAbiParameters([
+        { type: 'string' }, // protocol
+        { type: 'string' }, // method
+        { type: 'string' }, // url
+        { type: 'bytes32' }, // bodyHash
+        { type: 'address' }, // serviceAgent
+        { type: 'address' }, // treasury
+        { type: 'string' }, // skillId
+        { type: 'bytes32' }, // taskId
+        { type: 'address' }, // asset
+        { type: 'uint256' }, // amount
+        { type: 'uint256' }, // chainId
+        { type: 'uint256' }, // expiresAt
+        { type: 'uint256' }, // nonce
+    ], [
+        r.protocol,
+        r.method,
+        r.url,
+        r.bodyHash,
+        r.serviceAgent,
+        r.treasury,
+        r.skillId,
+        r.taskId,
+        r.asset,
+        r.amount,
+        BigInt(r.chainId),
+        BigInt(r.expiresAt),
+        r.nonce,
+    ]));
+}
+/** keccak256 of a request body (or ZERO_HASH for empty). The ONLY way bodies enter a binding. */
+export function hashRequestBody(body) {
+    if (body === undefined || body.length === 0)
+        return ZERO_HASH;
+    const bytes = typeof body === 'string' ? new TextEncoder().encode(body) : body;
+    return keccak256(bytes);
+}
+/**
+ * PAY-WIRE-6 — strip everything that must never leave the trust boundary in payment metadata (402
+ * bodies, receipts, on-chain events, accepts[] extras): licensed text, user queries, PII, full
+ * sensitive URLs. Returns a safe projection: the path WITHOUT query string + a hash of the full URL.
+ * A platform-level guarantee, not per-app discipline.
+ */
+export function redactPaymentMetadata(input) {
+    let safeRoute = '';
+    let urlHash = ZERO_HASH;
+    if (input.url) {
+        urlHash = keccak256(new TextEncoder().encode(input.url));
+        try {
+            const u = new URL(input.url);
+            safeRoute = `${u.origin}${u.pathname}`; // drop query + fragment (may carry the user's query/content)
+        }
+        catch {
+            safeRoute = '';
+        }
+    }
+    // A description is allowed ONLY if it's a generic label; callers must not pass licensed text. We pass
+    // it through verbatim but truncate to discourage smuggling licensed content into "description".
+    const description = input.description ? input.description.slice(0, 80) : undefined;
+    return { safeRoute, urlHash, description };
+}
+//# sourceMappingURL=resource.js.map

package/dist/rails/x402/resource.js.map

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

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

@@ -0,0 +1,81 @@
+import type { Address } from 'viem';
+import type { PaymentMandate } from '../../index.js';
+import type { Hex32 } from './resource.js';
+import type { PaymentQuote } from './quote.js';
+export declare const X402_VERSION: 2;
+export declare const HEADER_PAYMENT_REQUIRED = "PAYMENT-REQUIRED";
+export declare const HEADER_PAYMENT_SIGNATURE = "PAYMENT-SIGNATURE";
+export declare const HEADER_PAYMENT_RESPONSE = "PAYMENT-RESPONSE";
+export declare const ASSET_TRANSFER_METHOD: "erc7710-delegation";
+/** One x402 `accepts[]` entry — our delegation-native variant of `scheme: 'exact'`. */
+export interface PaymentRequirements {
+    scheme: 'exact';
+    network: string;
+    amount: string;
+    asset: Address;
+    payTo: Address;
+    maxTimeoutSeconds: number;
+    resource: {
+        route: string;
+        description?: string;
+        mimeType?: string;
+    };
+    extra: {
+        assetTransferMethod: typeof ASSET_TRANSFER_METHOD;
+        quoteId: Hex32;
+        mandateTemplate: {
+            resourceHash: Hex32;
+            nonce: string;
+            expiresAt: number;
+        };
+    };
+}
+export interface PaymentRequiredBody {
+    x402Version: typeof X402_VERSION;
+    error?: string;
+    accepts: PaymentRequirements[];
+}
+export interface SettlementResponse {
+    success: boolean;
+    settlementHash?: Hex32;
+    mandateId?: Hex32;
+    network: string;
+    payer?: Address;
+    error?: string;
+}
+export declare function serializeMandate(m: PaymentMandate): Record<string, unknown>;
+export declare function deserializeMandate(raw: unknown): PaymentMandate;
+export declare function buildPaymentRequired(quote: PaymentQuote, opts?: {
+    error?: string;
+    description?: string;
+    mimeType?: string;
+}): {
+    status: 402;
+    headers: Record<string, string>;
+    body: PaymentRequiredBody;
+};
+/** Client-side: decode a PAYMENT-REQUIRED header back to the body (for tests + the reader's agent). */
+export declare function parsePaymentRequired(headerValue: string): PaymentRequiredBody;
+export interface PaymentSignaturePayload {
+    x402Version: typeof X402_VERSION;
+    accepted: PaymentRequirements;
+    payload: {
+        mandate: PaymentMandate;
+    };
+}
+/** Build the PAYMENT-SIGNATURE header (client side). */
+export declare function buildPaymentSignature(accepted: PaymentRequirements, mandate: PaymentMandate): Record<string, string>;
+/**
+ * Server side: decode + validate the PAYMENT-SIGNATURE header. Fail-closed (returns null) on a missing
+ * header, an unknown x402Version, a non-'exact' scheme, or an unsupported assetTransferMethod. NO v1
+ * `X-PAYMENT` fallback (ADR-0013).
+ */
+export declare function parsePaymentSignature(headers: {
+    get?(name: string): string | null;
+} | Record<string, string | undefined>): {
+    accepted: PaymentRequirements;
+    mandate: PaymentMandate;
+} | null;
+export declare function buildPaymentResponse(r: SettlementResponse): Record<string, string>;
+export declare function parsePaymentResponse(headerValue: string): SettlementResponse;
+//# sourceMappingURL=wire.d.ts.map

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

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

package/dist/rails/x402/wire.js

@@ -0,0 +1,125 @@
+// Spec 272 PAY-WIRE-1/2/3 — x402 v2 HTTP wire. Headers: PAYMENT-REQUIRED (402) / PAYMENT-SIGNATURE
+// (client→server) / PAYMENT-RESPONSE (server→client), all base64 JSON, CAIP-2 networks, `accepts[]`
+// shape. The v1 `X-PAYMENT` names are dead — we never parse them (ADR-0013: one wire, fail-closed).
+export const X402_VERSION = 2;
+export const HEADER_PAYMENT_REQUIRED = 'PAYMENT-REQUIRED';
+export const HEADER_PAYMENT_SIGNATURE = 'PAYMENT-SIGNATURE';
+export const HEADER_PAYMENT_RESPONSE = 'PAYMENT-RESPONSE';
+export const ASSET_TRANSFER_METHOD = 'erc7710-delegation'; // Wave 1; 'eip3009' is the Wave-5 sibling
+// ── base64 JSON codec (bigint-safe) ──
+function b64encode(obj) {
+    const json = JSON.stringify(obj, (_k, v) => (typeof v === 'bigint' ? v.toString() : v));
+    return typeof btoa === 'function' ? btoa(json) : Buffer.from(json, 'utf8').toString('base64');
+}
+function b64decode(b64) {
+    const json = typeof atob === 'function' ? atob(b64) : Buffer.from(b64, 'base64').toString('utf8');
+    return JSON.parse(json);
+}
+// ── PaymentMandate wire (de)serialize — the bigint fields become decimal strings on the wire ──
+export function serializeMandate(m) {
+    return JSON.parse(JSON.stringify(m, (_k, v) => (typeof v === 'bigint' ? v.toString() : v)));
+}
+export function deserializeMandate(raw) {
+    const o = raw;
+    const ap = o.amountPolicy;
+    const cb = o.contextBinding;
+    const mc = o.mandateConstraints;
+    const big = (v) => BigInt(v);
+    return {
+        ...o,
+        nonce: big(o.nonce),
+        amountPolicy: {
+            ...ap,
+            ...(ap.amount !== undefined ? { amount: big(ap.amount) } : {}),
+            ...(ap.minAmount !== undefined ? { minAmount: big(ap.minAmount) } : {}),
+            ...(ap.maxAmount !== undefined ? { maxAmount: big(ap.maxAmount) } : {}),
+        },
+        contextBinding: { ...cb, nonce: big(cb.nonce) },
+        ...(mc && mc.maxAggregateAmount !== undefined
+            ? { mandateConstraints: { ...mc, maxAggregateAmount: big(mc.maxAggregateAmount) } }
+            : {}),
+    };
+}
+// ── PAY-WIRE-1: build the 402 ──
+export function buildPaymentRequired(quote, opts) {
+    const requirements = {
+        scheme: 'exact',
+        network: quote.network,
+        amount: quote.amount.toString(),
+        asset: quote.asset,
+        payTo: quote.payTo,
+        maxTimeoutSeconds: quote.maxTimeoutSeconds,
+        // safe route only (no query string) — PAY-WIRE-6
+        resource: { route: safeRoute(quote.resource.url), description: opts?.description, mimeType: opts?.mimeType },
+        extra: {
+            assetTransferMethod: ASSET_TRANSFER_METHOD,
+            quoteId: quote.quoteId,
+            mandateTemplate: { resourceHash: quote.resourceHash, nonce: quote.nonce.toString(), expiresAt: quote.expiresAt },
+        },
+    };
+    const body = { x402Version: X402_VERSION, error: opts?.error, accepts: [requirements] };
+    return { status: 402, headers: { [HEADER_PAYMENT_REQUIRED]: b64encode(body) }, body };
+}
+/** Client-side: decode a PAYMENT-REQUIRED header back to the body (for tests + the reader's agent). */
+export function parsePaymentRequired(headerValue) {
+    const body = b64decode(headerValue);
+    if (body.x402Version !== X402_VERSION)
+        throw new Error(`[x402] unsupported x402Version ${body.x402Version}`);
+    return body;
+}
+/** Build the PAYMENT-SIGNATURE header (client side). */
+export function buildPaymentSignature(accepted, mandate) {
+    const body = { x402Version: X402_VERSION, accepted, payload: { mandate: serializeMandate(mandate) } };
+    return { [HEADER_PAYMENT_SIGNATURE]: b64encode(body) };
+}
+/**
+ * Server side: decode + validate the PAYMENT-SIGNATURE header. Fail-closed (returns null) on a missing
+ * header, an unknown x402Version, a non-'exact' scheme, or an unsupported assetTransferMethod. NO v1
+ * `X-PAYMENT` fallback (ADR-0013).
+ */
+export function parsePaymentSignature(headers) {
+    const raw = headerValue(headers, HEADER_PAYMENT_SIGNATURE);
+    if (!raw)
+        return null;
+    let body;
+    try {
+        body = b64decode(raw);
+    }
+    catch {
+        return null;
+    }
+    if (body.x402Version !== X402_VERSION)
+        return null;
+    if (body.accepted?.scheme !== 'exact')
+        return null;
+    if (body.accepted?.extra?.assetTransferMethod !== ASSET_TRANSFER_METHOD)
+        return null;
+    if (!body.payload?.mandate)
+        return null;
+    return { accepted: body.accepted, mandate: deserializeMandate(body.payload.mandate) };
+}
+// ── PAY-WIRE-3: build the settlement response (a projection of the durable receipt) ──
+export function buildPaymentResponse(r) {
+    return { [HEADER_PAYMENT_RESPONSE]: b64encode(r) };
+}
+export function parsePaymentResponse(headerValue) {
+    return b64decode(headerValue);
+}
+// ── helpers ──
+function headerValue(headers, name) {
+    if (typeof headers.get === 'function') {
+        return headers.get(name) ?? undefined;
+    }
+    const rec = headers;
+    return rec[name] ?? rec[name.toLowerCase()];
+}
+function safeRoute(url) {
+    try {
+        const u = new URL(url);
+        return `${u.origin}${u.pathname}`;
+    }
+    catch {
+        return '';
+    }
+}
+//# sourceMappingURL=wire.js.map

package/dist/rails/x402/wire.js.map

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

package/dist/receipt.d.ts

@@ -0,0 +1,36 @@
+/**
+ * X402-D9.3 / spec 243 §7 — PaymentReceipt verifiable credential.
+ *
+ * Every successful redemption (charge, refund, split-out, escrow release) produces
+ * an immutable `PaymentReceipt` VC (PMT-INV-11 — no revoke entrypoint; settlement is
+ * final). The receipt is evidence-symmetric (273 EXC-D3): a refund leg is the same
+ * shape as the charge it reverses, linked by `provenance.refunds`.
+ *
+ * This builds the UNSIGNED credential (vc envelope is type-only here per the package
+ * boundary); the app/rail signs it via `@agenticprimitives/verifiable-credentials`
+ * `signCredential` and asserts it via the `attestations` client.
+ */
+import type { UnsignedCredential } from '@agenticprimitives/verifiable-credentials';
+import type { Address } from '@agenticprimitives/types';
+import type { PaymentMandate, Hex32 } from './index.js';
+export declare const PAYMENT_RECEIPT_TYPE = "PaymentReceipt";
+/** Coarsen a settlement time to a UTC-day bucket — receipts leak no finer timing (privacy posture §6). */
+export declare function settlementEpochBucket(settledAtSeconds: number): number;
+export interface PaymentReceiptInput {
+    /** the settled mandate */
+    mandate: PaymentMandate;
+    /** the rail executor's SA (VC issuer) */
+    issuer: Address;
+    /** tx hash, or off-chain settlement id */
+    settlementHash: Hex32;
+    /** ISO-8601 settlement time */
+    settledAt: string;
+    /** provenance — set on a refund leg to the original charge's mandateId (EXC-D3) */
+    refundsMandateId?: Hex32;
+}
+/**
+ * Build the unsigned `PaymentReceipt` credential. The subject id is the payer SA; the
+ * full context binding is folded into `contextBindingHash` (never the body — privacy §6).
+ */
+export declare function buildPaymentReceiptCredential(input: PaymentReceiptInput): UnsignedCredential;
+//# sourceMappingURL=receipt.d.ts.map

package/dist/receipt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"receipt.d.ts","sourceRoot":"","sources":["../src/receipt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2CAA2C,CAAC;AACpF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAExD,OAAO,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExD,eAAO,MAAM,oBAAoB,mBAAmB,CAAC;AAGrD,0GAA0G;AAC1G,wBAAgB,qBAAqB,CAAC,gBAAgB,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED,MAAM,WAAW,mBAAmB;IAClC,0BAA0B;IAC1B,OAAO,EAAE,cAAc,CAAC;IACxB,yCAAyC;IACzC,MAAM,EAAE,OAAO,CAAC;IAChB,0CAA0C;IAC1C,cAAc,EAAE,KAAK,CAAC;IACtB,+BAA+B;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,mFAAmF;IACnF,gBAAgB,CAAC,EAAE,KAAK,CAAC;CAC1B;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,mBAAmB,GAAG,kBAAkB,CAyB5F"}

package/dist/receipt.js

@@ -0,0 +1,50 @@
+/**
+ * X402-D9.3 / spec 243 §7 — PaymentReceipt verifiable credential.
+ *
+ * Every successful redemption (charge, refund, split-out, escrow release) produces
+ * an immutable `PaymentReceipt` VC (PMT-INV-11 — no revoke entrypoint; settlement is
+ * final). The receipt is evidence-symmetric (273 EXC-D3): a refund leg is the same
+ * shape as the charge it reverses, linked by `provenance.refunds`.
+ *
+ * This builds the UNSIGNED credential (vc envelope is type-only here per the package
+ * boundary); the app/rail signs it via `@agenticprimitives/verifiable-credentials`
+ * `signCredential` and asserts it via the `attestations` client.
+ */
+import { hashContextBinding, mandateAmount } from './mandate-sign.js';
+export const PAYMENT_RECEIPT_TYPE = 'PaymentReceipt';
+const CREDENTIALS_V2_CONTEXT = 'https://www.w3.org/ns/credentials/v2';
+/** Coarsen a settlement time to a UTC-day bucket — receipts leak no finer timing (privacy posture §6). */
+export function settlementEpochBucket(settledAtSeconds) {
+    return Math.floor(settledAtSeconds / 86_400);
+}
+/**
+ * Build the unsigned `PaymentReceipt` credential. The subject id is the payer SA; the
+ * full context binding is folded into `contextBindingHash` (never the body — privacy §6).
+ */
+export function buildPaymentReceiptCredential(input) {
+    const { mandate } = input;
+    const settledSeconds = Math.floor(Date.parse(input.settledAt) / 1000);
+    const credential = {
+        '@context': [CREDENTIALS_V2_CONTEXT],
+        type: ['VerifiableCredential', PAYMENT_RECEIPT_TYPE],
+        issuer: input.issuer,
+        validFrom: input.settledAt,
+        credentialSubject: {
+            id: mandate.payer,
+            mandateId: mandate.mandateId,
+            rail: mandate.rail,
+            payee: mandate.payee,
+            amount: mandateAmount(mandate).toString(),
+            asset: mandate.amountPolicy.asset.id,
+            chain: mandate.contextBinding.chain,
+            orderHash: mandate.contextBinding.orderHash ?? null,
+            legId: mandate.contextBinding.legId ?? null,
+            contextBindingHash: hashContextBinding(mandate.contextBinding),
+            settlementHash: input.settlementHash,
+            settlementEpochBucket: settlementEpochBucket(settledSeconds),
+            ...(input.refundsMandateId ? { provenance: { refunds: input.refundsMandateId } } : {}),
+        },
+    };
+    return credential;
+}
+//# sourceMappingURL=receipt.js.map

package/dist/receipt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"receipt.js","sourceRoot":"","sources":["../src/receipt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAGtE,MAAM,CAAC,MAAM,oBAAoB,GAAG,gBAAgB,CAAC;AACrD,MAAM,sBAAsB,GAAG,sCAAsC,CAAC;AAEtE,0GAA0G;AAC1G,MAAM,UAAU,qBAAqB,CAAC,gBAAwB;IAC5D,OAAO,IAAI,CAAC,KAAK,CAAC,gBAAgB,GAAG,MAAM,CAAC,CAAC;AAC/C,CAAC;AAeD;;;GAGG;AACH,MAAM,UAAU,6BAA6B,CAAC,KAA0B;IACtE,MAAM,EAAE,OAAO,EAAE,GAAG,KAAK,CAAC;IAC1B,MAAM,cAAc,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC,CAAC;IACtE,MAAM,UAAU,GAAG;QACjB,UAAU,EAAE,CAAC,sBAAsB,CAAC;QACpC,IAAI,EAAE,CAAC,sBAAsB,EAAE,oBAAoB,CAAC;QACpD,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,iBAAiB,EAAE;YACjB,EAAE,EAAE,OAAO,CAAC,KAAK;YACjB,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,MAAM,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE;YACzC,KAAK,EAAE,OAAO,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE;YACpC,KAAK,EAAE,OAAO,CAAC,cAAc,CAAC,KAAK;YACnC,SAAS,EAAE,OAAO,CAAC,cAAc,CAAC,SAAS,IAAI,IAAI;YACnD,KAAK,EAAE,OAAO,CAAC,cAAc,CAAC,KAAK,IAAI,IAAI;YAC3C,kBAAkB,EAAE,kBAAkB,CAAC,OAAO,CAAC,cAAc,CAAC;YAC9D,cAAc,EAAE,KAAK,CAAC,cAAc;YACpC,qBAAqB,EAAE,qBAAqB,CAAC,cAAc,CAAC;YAC5D,GAAG,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,EAAE,OAAO,EAAE,KAAK,CAAC,gBAAgB,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACvF;KACF,CAAC;IACF,OAAO,UAA2C,CAAC;AACrD,CAAC"}

package/dist/refund.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Refunds (spec 243 §5.5) — a receipt-linked reverse leg, no enforcer.
+ *
+ * The treasury (payee) signs a transfer payee → payer carrying `provenance.refunds`
+ * pointing at the original charge's mandateId. It emits its OWN PaymentReceipt
+ * (audit-equal evidence, 273 EXC-D3). Build the refund receipt with
+ * `buildPaymentReceiptCredential({ ..., refundsMandateId })`.
+ */
+import type { Address } from '@agenticprimitives/types';
+import { type TransferPlan } from './transfer.js';
+import type { Hex32 } from './index.js';
+export interface RefundInput {
+    asset: Address;
+    /** refund amount — MUST be ≤ the original charge (caller-enforced) */
+    amount: bigint;
+    /** where the refund returns — the original charge's payer */
+    payer: Address;
+    /** the original charge this reverses (provenance) */
+    originalMandateId: Hex32;
+}
+export interface RefundPlan {
+    plan: TransferPlan;
+    provenance: {
+        refunds: Hex32;
+    };
+}
+/** Build the reverse leg: the treasury executes a transfer back to the original payer. */
+export declare function buildRefund(input: RefundInput): RefundPlan;
+//# sourceMappingURL=refund.d.ts.map

package/dist/refund.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refund.d.ts","sourceRoot":"","sources":["../src/refund.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AACtE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,OAAO,CAAC;IACf,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,KAAK,EAAE,OAAO,CAAC;IACf,qDAAqD;IACrD,iBAAiB,EAAE,KAAK,CAAC;CAC1B;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,YAAY,CAAC;IACnB,UAAU,EAAE;QAAE,OAAO,EAAE,KAAK,CAAA;KAAE,CAAC;CAChC;AAED,0FAA0F;AAC1F,wBAAgB,WAAW,CAAC,KAAK,EAAE,WAAW,GAAG,UAAU,CAM1D"}

package/dist/refund.js

@@ -0,0 +1,19 @@
+/**
+ * Refunds (spec 243 §5.5) — a receipt-linked reverse leg, no enforcer.
+ *
+ * The treasury (payee) signs a transfer payee → payer carrying `provenance.refunds`
+ * pointing at the original charge's mandateId. It emits its OWN PaymentReceipt
+ * (audit-equal evidence, 273 EXC-D3). Build the refund receipt with
+ * `buildPaymentReceiptCredential({ ..., refundsMandateId })`.
+ */
+import { buildErc20Transfer } from './transfer.js';
+/** Build the reverse leg: the treasury executes a transfer back to the original payer. */
+export function buildRefund(input) {
+    if (input.amount <= 0n)
+        throw new Error('[refund] amount must be > 0');
+    return {
+        plan: buildErc20Transfer(input.asset, input.payer, input.amount),
+        provenance: { refunds: input.originalMandateId },
+    };
+}
+//# sourceMappingURL=refund.js.map

package/dist/refund.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refund.js","sourceRoot":"","sources":["../src/refund.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,kBAAkB,EAAqB,MAAM,eAAe,CAAC;AAkBtE,0FAA0F;AAC1F,MAAM,UAAU,WAAW,CAAC,KAAkB;IAC5C,IAAI,KAAK,CAAC,MAAM,IAAI,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;IACvE,OAAO;QACL,IAAI,EAAE,kBAAkB,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC;QAChE,UAAU,EAAE,EAAE,OAAO,EAAE,KAAK,CAAC,iBAAiB,EAAE;KACjD,CAAC;AACJ,CAAC"}

package/dist/split.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Split payouts (spec 243 §5.5) — app-triggered payout fan-out.
+ *
+ * One amount split to N recipients by basis points (Seaport recipient-specific-consideration
+ * pattern). `bps` MUST sum to 10000; the rounding remainder is assigned to the first recipient
+ * so the legs total EXACTLY `amount` (no dust left in the treasury). Each leg is its own
+ * transfer plan (and its own receipt). Connected-account onboarding / KYB stays app layer.
+ */
+import type { Address } from '@agenticprimitives/types';
+import { type TransferPlan } from './transfer.js';
+export interface SplitRecipient {
+    to: Address;
+    bps: number;
+}
+export interface SplitLeg {
+    to: Address;
+    bps: number;
+    amount: bigint;
+    plan: TransferPlan;
+}
+export declare const BPS_DENOMINATOR = 10000;
+export declare function buildSplitPayout(input: {
+    asset: Address;
+    amount: bigint;
+    recipients: SplitRecipient[];
+}): SplitLeg[];
+//# sourceMappingURL=split.d.ts.map

package/dist/split.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"split.d.ts","sourceRoot":"","sources":["../src/split.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAEtE,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,OAAO,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,OAAO,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,YAAY,CAAC;CACpB;AAED,eAAO,MAAM,eAAe,QAAS,CAAC;AAEtC,wBAAgB,gBAAgB,CAAC,KAAK,EAAE;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,cAAc,EAAE,CAAA;CAAE,GAAG,QAAQ,EAAE,CAkBpH"}

package/dist/split.js

@@ -0,0 +1,33 @@
+/**
+ * Split payouts (spec 243 §5.5) — app-triggered payout fan-out.
+ *
+ * One amount split to N recipients by basis points (Seaport recipient-specific-consideration
+ * pattern). `bps` MUST sum to 10000; the rounding remainder is assigned to the first recipient
+ * so the legs total EXACTLY `amount` (no dust left in the treasury). Each leg is its own
+ * transfer plan (and its own receipt). Connected-account onboarding / KYB stays app layer.
+ */
+import { buildErc20Transfer } from './transfer.js';
+export const BPS_DENOMINATOR = 10_000;
+export function buildSplitPayout(input) {
+    const { asset, amount, recipients } = input;
+    if (recipients.length === 0)
+        throw new Error('[split] at least one recipient required');
+    if (amount <= 0n)
+        throw new Error('[split] amount must be > 0');
+    const totalBps = recipients.reduce((s, r) => s + r.bps, 0);
+    if (totalBps !== BPS_DENOMINATOR)
+        throw new Error(`[split] bps must sum to ${BPS_DENOMINATOR}, got ${totalBps}`);
+    for (const r of recipients)
+        if (r.bps <= 0)
+            throw new Error('[split] each recipient bps must be > 0');
+    const amounts = recipients.map((r) => (amount * BigInt(r.bps)) / BigInt(BPS_DENOMINATOR));
+    const remainder = amount - amounts.reduce((s, a) => s + a, 0n);
+    amounts[0] += remainder; // assign rounding dust to the first recipient → legs total exactly `amount`
+    return recipients.map((r, i) => ({
+        to: r.to,
+        bps: r.bps,
+        amount: amounts[i],
+        plan: buildErc20Transfer(asset, r.to, amounts[i]),
+    }));
+}
+//# sourceMappingURL=split.js.map

package/dist/split.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"split.js","sourceRoot":"","sources":["../src/split.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,kBAAkB,EAAqB,MAAM,eAAe,CAAC;AActE,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC;AAEtC,MAAM,UAAU,gBAAgB,CAAC,KAAuE;IACtG,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,KAAK,CAAC;IAC5C,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;IACxF,IAAI,MAAM,IAAI,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;IAChE,MAAM,QAAQ,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IAC3D,IAAI,QAAQ,KAAK,eAAe;QAAE,MAAM,IAAI,KAAK,CAAC,2BAA2B,eAAe,SAAS,QAAQ,EAAE,CAAC,CAAC;IACjH,KAAK,MAAM,CAAC,IAAI,UAAU;QAAE,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;IAEtG,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC;IAC1F,MAAM,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC;IAC/D,OAAO,CAAC,CAAC,CAAE,IAAI,SAAS,CAAC,CAAC,4EAA4E;IAEtG,OAAO,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;QAC/B,EAAE,EAAE,CAAC,CAAC,EAAE;QACR,GAAG,EAAE,CAAC,CAAC,GAAG;QACV,MAAM,EAAE,OAAO,CAAC,CAAC,CAAE;QACnB,IAAI,EAAE,kBAAkB,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC,CAAE,CAAC;KACnD,CAAC,CAAC,CAAC;AACN,CAAC"}

package/dist/transfer.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Shared transfer-plan plumbing for the non-x402 rails (spec 243 §5.5).
+ *
+ * A `TransferPlan` is the inner call an SA executes (`AgentAccount.execute(to, value, data)`
+ * or a UserOp / wallet tx) — the same `{to, value, data}` shape the x402 rail's
+ * `buildRedemptionCalldata` returns. Wallet / invoice / refund / split all reduce to one or
+ * more ERC-20 transfers from the payer or treasury SA.
+ */
+import { type Address, type Hex } from 'viem';
+export interface TransferPlan {
+    to: Address;
+    value: bigint;
+    data: Hex;
+}
+export declare const ERC20_TRANSFER_ABI: readonly [{
+    readonly type: "function";
+    readonly name: "transfer";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "bool";
+    }];
+}];
+/** A single ERC-20 transfer: the executing SA calls `asset.transfer(to, amount)`. */
+export declare function buildErc20Transfer(asset: Address, to: Address, amount: bigint): TransferPlan;
+/** A native-value transfer (the executing SA sends `amount` wei to `to`). */
+export declare function buildNativeTransfer(to: Address, amount: bigint): TransferPlan;
+export declare const ERC20_APPROVE_ABI: readonly [{
+    readonly type: "function";
+    readonly name: "approve";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "spender";
+        readonly type: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "bool";
+    }];
+}];
+/** An ERC-20 approval — needed before the escrow `deposit` pulls funds via `transferFrom`. */
+export declare function buildErc20Approve(asset: Address, spender: Address, amount: bigint): TransferPlan;
+//# sourceMappingURL=transfer.d.ts.map

package/dist/transfer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transfer.d.ts","sourceRoot":"","sources":["../src/transfer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAsB,KAAK,OAAO,EAAE,KAAK,GAAG,EAAE,MAAM,MAAM,CAAC;AAElE,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,GAAG,CAAC;CACX;AAED,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;EAWrB,CAAC;AAEX,qFAAqF;AACrF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,YAAY,CAM5F;AAED,6EAA6E;AAC7E,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,YAAY,CAE7E;AAED,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;EAWpB,CAAC;AAEX,8FAA8F;AAC9F,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,YAAY,CAMhG"}

package/dist/transfer.js

@@ -0,0 +1,54 @@
+/**
+ * Shared transfer-plan plumbing for the non-x402 rails (spec 243 §5.5).
+ *
+ * A `TransferPlan` is the inner call an SA executes (`AgentAccount.execute(to, value, data)`
+ * or a UserOp / wallet tx) — the same `{to, value, data}` shape the x402 rail's
+ * `buildRedemptionCalldata` returns. Wallet / invoice / refund / split all reduce to one or
+ * more ERC-20 transfers from the payer or treasury SA.
+ */
+import { encodeFunctionData } from 'viem';
+export const ERC20_TRANSFER_ABI = [
+    {
+        type: 'function',
+        name: 'transfer',
+        stateMutability: 'nonpayable',
+        inputs: [
+            { name: 'to', type: 'address' },
+            { name: 'amount', type: 'uint256' },
+        ],
+        outputs: [{ type: 'bool' }],
+    },
+];
+/** A single ERC-20 transfer: the executing SA calls `asset.transfer(to, amount)`. */
+export function buildErc20Transfer(asset, to, amount) {
+    return {
+        to: asset,
+        value: 0n,
+        data: encodeFunctionData({ abi: ERC20_TRANSFER_ABI, functionName: 'transfer', args: [to, amount] }),
+    };
+}
+/** A native-value transfer (the executing SA sends `amount` wei to `to`). */
+export function buildNativeTransfer(to, amount) {
+    return { to, value: amount, data: '0x' };
+}
+export const ERC20_APPROVE_ABI = [
+    {
+        type: 'function',
+        name: 'approve',
+        stateMutability: 'nonpayable',
+        inputs: [
+            { name: 'spender', type: 'address' },
+            { name: 'amount', type: 'uint256' },
+        ],
+        outputs: [{ type: 'bool' }],
+    },
+];
+/** An ERC-20 approval — needed before the escrow `deposit` pulls funds via `transferFrom`. */
+export function buildErc20Approve(asset, spender, amount) {
+    return {
+        to: asset,
+        value: 0n,
+        data: encodeFunctionData({ abi: ERC20_APPROVE_ABI, functionName: 'approve', args: [spender, amount] }),
+    };
+}
+//# sourceMappingURL=transfer.js.map