@agenticprimitives/payments 0.0.0-alpha.10

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

package/dist/transfer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transfer.js","sourceRoot":"","sources":["../src/transfer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,kBAAkB,EAA0B,MAAM,MAAM,CAAC;AAQlE,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC;QACE,IAAI,EAAE,UAAU;QAChB,IAAI,EAAE,UAAU;QAChB,eAAe,EAAE,YAAY;QAC7B,MAAM,EAAE;YACN,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE;YAC/B,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE;SACpC;QACD,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;KAC5B;CACO,CAAC;AAEX,qFAAqF;AACrF,MAAM,UAAU,kBAAkB,CAAC,KAAc,EAAE,EAAW,EAAE,MAAc;IAC5E,OAAO;QACL,EAAE,EAAE,KAAK;QACT,KAAK,EAAE,EAAE;QACT,IAAI,EAAE,kBAAkB,CAAC,EAAE,GAAG,EAAE,kBAAkB,EAAE,YAAY,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,MAAM,CAAC,EAAE,CAAC;KACpG,CAAC;AACJ,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,mBAAmB,CAAC,EAAW,EAAE,MAAc;IAC7D,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AAC3C,CAAC;AAED,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B;QACE,IAAI,EAAE,UAAU;QAChB,IAAI,EAAE,SAAS;QACf,eAAe,EAAE,YAAY;QAC7B,MAAM,EAAE;YACN,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE;YACpC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE;SACpC;QACD,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;KAC5B;CACO,CAAC;AAEX,8FAA8F;AAC9F,MAAM,UAAU,iBAAiB,CAAC,KAAc,EAAE,OAAgB,EAAE,MAAc;IAChF,OAAO;QACL,EAAE,EAAE,KAAK;QACT,KAAK,EAAE,EAAE;QACT,IAAI,EAAE,kBAAkB,CAAC,EAAE,GAAG,EAAE,iBAAiB,EAAE,YAAY,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,EAAE,CAAC;KACvG,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@agenticprimitives/payments",
+  "version": "0.0.0-alpha.10",
+  "description": "PaymentMandate + ContextBinding + MandateConstraints + open/closed mode discrimination. Three W1 rails (x402, wallet, sponsored-userop). PaymentReceipt asserted into AttestationRegistry per ADR-0023.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agentictrustlabs/agenticprimitives.git",
+    "directory": "packages/payments"
+  },
+  "homepage": "https://github.com/agentictrustlabs/agenticprimitives/tree/master/packages/payments",
+  "bugs": {
+    "url": "https://github.com/agentictrustlabs/agenticprimitives/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "LICENSE",
+    "dist",
+    "spec.md",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "viem": "^2.52.2"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.8",
+    "viem": "^2.52.2"
+  },
+  "keywords": [
+    "agentic",
+    "primitives",
+    "payments"
+  ],
+  "dependencies": {
+    "@noble/hashes": "^2.2.0",
+    "@noble/curves": "^2.2.0",
+    "@agenticprimitives/attestations": "0.0.0-alpha.10",
+    "@agenticprimitives/delegation": "1.0.0-alpha.14",
+    "@agenticprimitives/types": "1.0.0-alpha.14",
+    "@agenticprimitives/verifiable-credentials": "0.0.0-alpha.11"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:unit": "vitest run test/unit --passWithNoTests",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist"
+  }
+}

package/spec.md

@@ -0,0 +1,5 @@
+# Spec pointer
+
+Canonical spec: [`../../specs/243-*.md`](../../specs/)
+
+Owning layers (per [coordination-substrate.md](../../docs/architecture/coordination-substrate.md)): layer-9b.