@agenticprimitives/payments 0.0.0-alpha.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agentic Trust Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,44 @@
+# @agenticprimitives/payments
+
+> **Status: STUB** (Wave 0.5 of the W1 implementation wave). Typed primitives and invariant guards ship today; the EIP-712 mandate signer and the three W1 rails land in Wave 6 per the [w1 implementation wave plan](../../docs/architecture/w1-implementation-wave-plan.md). A recent self-audit flagged this package's docs for overclaiming ([NEW-PMT-1](../../docs/audits/findings.yaml)); this README is written to the actual surface.
+
+Machine payments arrived. x402 made HTTP-native pay-per-request real; Google's AP2 defined mandates for agent-initiated spend. What neither ships — what nobody ships — is machine payments scoped by the *same* delegation, custody, and audit substrate that governs everything else the agent does. "This agent may spend up to this amount, for this task, on this rail, until Friday — signed by a smart account, bound to the work it pays for, receipted into an attestation registry" is the combination the agent economy actually needs, and it only exists when payments are a layer of one system rather than a bolted-on rail.
+
+This package is the designed payments slice of that substrate — spine Layer 9b, the `PaymentMandate` — spec'd in full, scaffolded now, landing in the implementation waves.
+
+Part of [agenticprimitives](../../README.md) — the trust substrate for the agent economy: one canonical Smart Agent identity with custody, delegation, naming, credentials, and audit evidence designed as one system.
+
+## What ships today
+
+Typed primitives and pure invariant guards — no signing, no execution, no money moves:
+
+- **`PaymentMandate` type** — payer, payee, granter, rail, `AmountPolicy` (exact / range / formula), `maxRedemptions`, validity window, `mode`, and an optional `delegationRef` linking the mandate to the delegation that authorized it.
+- **`ContextBinding` + `assertContextBindingValid`** — PMT-3.1 enforced: every mandate must bind to at least one of intent / agreement / task / artifact / HTTP resource. No context-free spend.
+- **`MandateConstraints`** — AP2-aligned aggregate scope: cumulative caps, redemption frequency windows, category allow/deny, geo-fencing.
+- **Open/closed mode discrimination + `assertClosedMandateInvariants`** — PMT-INV-14 enforced: a closed (final-charge) mandate is always one-shot.
+- **`computeMandateId`** — deterministic keccak-256 mandate identity over payer + nonce + rail + chain.
+- **`PaymentRailExecutor` interface + `registerRail` / `getRail`** — the extension point every rail (current and future, including the reserved confidential family) implements.
+
+## What lands in Wave 6 (designed, not shipped)
+
+The EIP-712 typed-data builder, SA signing and ERC-1271 verification (no raw EOA signatures — PMT-INV-12), `redeemPaymentMandate`, and the three W1 rails: `rails/wallet` (SA-to-SA transfer via UserOp), `rails/x402` (HTTP-native per [x402.org](https://www.x402.org/) + reference facilitator), and `rails/sponsored-userop` (paymaster-sponsored, no value moved). Plus `PaymentReceipt` — an immutable, non-revocable credential asserted into the attestation registry per [ADR-0023](../../docs/architecture/decisions/0023-attestation-registry-eas-aligned-bilateral-consent.md), so every redemption leaves first-class evidence. Confidential rails (Aztec-style, Zcash-style, ZK paymasters) are a reserved W2 sub-module family.
+
+## Where this is heading / market context
+
+- **x402** proved HTTP-native machine payments; it is one of our three W1 rails, not a competitor.
+- **Google AP2** defined mandate semantics for agent spend; `MandateConstraints` is deliberately AP2-aligned so the substrate speaks the emerging lingua franca.
+- The gap both leave open: x402 and AP2 authorize a *payment*; neither anchors it to a canonical on-chain identity with custody policy, a revocable delegation chain, and an audit trail behind it. Delegation-scoped machine payments — mandate references delegation, delegation references the Smart Agent, every step receipted — is the combination this layer exists to ship.
+
+**Authoritative spec:** [spec 243 — payments](../../specs/243-payments.md) (see [`spec.md`](./spec.md)). Owns spine layer 9b; bounded surface in `CLAUDE.md` and `capability.manifest.json`.
+
+## Build
+
+```bash
+pnpm --filter @agenticprimitives/payments typecheck
+pnpm --filter @agenticprimitives/payments test
+pnpm --filter @agenticprimitives/payments build
+```
+
+## Status — honest version
+
+STUB. Nothing here signs or settles a payment today; treat the rails and the EIP-712 surface as spec'd commitments. The audit finding that this package's docs once claimed more ([NEW-PMT-1](../../docs/audits/findings.yaml)) is public — transparency about the gap is the point. Wave sequencing: [w1-implementation-wave-plan.md](../../docs/architecture/w1-implementation-wave-plan.md).

package/dist/index.d.ts

@@ -0,0 +1,112 @@
+/**
+ * @agenticprimitives/payments — PaymentMandate + rail abstraction.
+ * Spine Layer 9b.
+ *
+ * Authoritative spec: specs/243-payments.md
+ */
+import type { Address, Hex } from '@agenticprimitives/types';
+export declare const PACKAGE_NAME = "@agenticprimitives/payments";
+export declare const PACKAGE_STATUS: "w1-foundational";
+export declare const SPEC_REF = "specs/243-payments.md";
+export type Hex32 = `0x${string}`;
+export type PaymentRail = 'x402' | 'wallet' | 'sponsored-userop' | 'escrow' | 'invoice' | 'confidential-aztec' | 'confidential-zcash' | 'confidential-zk-paymaster';
+export interface AssetRef {
+    id: string;
+    symbol?: string;
+    decimals?: number;
+}
+export type AmountPolicy = {
+    kind: 'exact';
+    amount: bigint;
+    asset: AssetRef;
+    chain: number;
+} | {
+    kind: 'range';
+    minAmount: bigint;
+    maxAmount: bigint;
+    asset: AssetRef;
+    chain: number;
+} | {
+    kind: 'formula';
+    formulaId: Hex32;
+    maxAmount: bigint;
+    asset: AssetRef;
+    chain: number;
+};
+export interface MandateConstraints {
+    maxAggregateAmount?: bigint;
+    frequency?: {
+        maxRedemptionsPerWindow: number;
+        windowSeconds: number;
+    };
+    categories?: string[];
+    excludedCategories?: string[];
+    geoFence?: string[];
+}
+export interface ContextBinding {
+    intentId?: string;
+    agreementCommitment?: Hex32;
+    taskId?: Hex32;
+    artifactHash?: Hex32;
+    resource?: {
+        method: string;
+        url: string;
+        requestBodyHash: Hex32;
+    };
+    chain: number;
+    asset: AssetRef;
+    nonce: bigint;
+    validFrom: number;
+    expiresAt: number;
+}
+export type PaymentMandateMode = 'open' | 'closed';
+export interface PaymentMandate {
+    mandateId: Hex32;
+    payer: Address;
+    payee: Address;
+    granter: Address;
+    rail: PaymentRail;
+    railConfig?: Record<string, unknown>;
+    amountPolicy: AmountPolicy;
+    mandateConstraints?: MandateConstraints;
+    nonce: bigint;
+    maxRedemptions: number;
+    validFrom: number;
+    expiresAt: number;
+    contextBinding: ContextBinding;
+    delegationRef?: Hex32;
+    mode: PaymentMandateMode;
+    requiresClosedMandateForFinalCharge?: boolean;
+    reasonHash: Hex32;
+    signature: Hex;
+}
+/** PMT-3.1: at least one context-binding handle MUST be populated. */
+export declare function assertContextBindingValid(cb: ContextBinding): void;
+/** PMT-INV-14 / PMT-10.1: closed mandates are always one-shot. */
+export declare function assertClosedMandateInvariants(mandate: PaymentMandate): void;
+export declare function computeMandateId(args: {
+    payer: Address;
+    nonce: bigint;
+    rail: PaymentRail;
+    chain: number;
+}): Hex32;
+export interface PaymentRailExecutor {
+    rail: PaymentRail;
+    verifyMandate(mandate: PaymentMandate): Promise<{
+        valid: boolean;
+        reason?: string;
+    }>;
+    prepareRedemption(mandate: PaymentMandate): Promise<{
+        planId: Hex32;
+        details: Record<string, unknown>;
+    }>;
+    executeRedemption(plan: {
+        planId: Hex32;
+    }): Promise<{
+        receiptHash: Hex32;
+        settlementHash: Hex32;
+    }>;
+}
+export declare function registerRail(executor: PaymentRailExecutor): void;
+export declare function getRail(rail: PaymentRail): PaymentRailExecutor | undefined;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,40 @@
+/**
+ * @agenticprimitives/payments — PaymentMandate + rail abstraction.
+ * Spine Layer 9b.
+ *
+ * Authoritative spec: specs/243-payments.md
+ */
+import { keccak_256 } from '@noble/hashes/sha3.js';
+import { utf8ToBytes } from '@noble/hashes/utils.js';
+export const PACKAGE_NAME = '@agenticprimitives/payments';
+export const PACKAGE_STATUS = 'w1-foundational';
+export const SPEC_REF = 'specs/243-payments.md';
+/** PMT-3.1: at least one context-binding handle MUST be populated. */
+export function assertContextBindingValid(cb) {
+    const any = cb.intentId || cb.agreementCommitment || cb.taskId || cb.artifactHash || cb.resource;
+    if (!any) {
+        throw new Error('[payments/PMT-3.1] ContextBinding MUST populate at least one of intentId / agreementCommitment / taskId / artifactHash / resource');
+    }
+}
+/** PMT-INV-14 / PMT-10.1: closed mandates are always one-shot. */
+export function assertClosedMandateInvariants(mandate) {
+    if (mandate.mode === 'closed' && mandate.maxRedemptions !== 1) {
+        throw new Error(`[payments/PMT-INV-14] closed mandate MUST have maxRedemptions = 1`);
+    }
+}
+export function computeMandateId(args) {
+    const blob = `${args.payer.toLowerCase()}:${args.nonce}:${args.rail}:${args.chain}`;
+    const digest = keccak_256(utf8ToBytes(blob));
+    let hex = '0x';
+    for (const v of digest)
+        hex += v.toString(16).padStart(2, '0');
+    return hex;
+}
+const _rails = new Map();
+export function registerRail(executor) {
+    _rails.set(executor.rail, executor);
+}
+export function getRail(rail) {
+    return _rails.get(rail);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAGrD,MAAM,CAAC,MAAM,YAAY,GAAG,6BAA6B,CAAC;AAC1D,MAAM,CAAC,MAAM,cAAc,GAAG,iBAA0B,CAAC;AACzD,MAAM,CAAC,MAAM,QAAQ,GAAG,uBAAuB,CAAC;AAqEhD,sEAAsE;AACtE,MAAM,UAAU,yBAAyB,CAAC,EAAkB;IAC1D,MAAM,GAAG,GAAG,EAAE,CAAC,QAAQ,IAAI,EAAE,CAAC,mBAAmB,IAAI,EAAE,CAAC,MAAM,IAAI,EAAE,CAAC,YAAY,IAAI,EAAE,CAAC,QAAQ,CAAC;IACjG,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CACb,mIAAmI,CACpI,CAAC;IACJ,CAAC;AACH,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,6BAA6B,CAAC,OAAuB;IACnE,IAAI,OAAO,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAO,CAAC,cAAc,KAAK,CAAC,EAAE,CAAC;QAC9D,MAAM,IAAI,KAAK,CAAC,mEAAmE,CAAC,CAAC;IACvF,CAAC;AACH,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,IAKhC;IACC,MAAM,IAAI,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;IACpF,MAAM,MAAM,GAAG,UAAU,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC;IAC7C,IAAI,GAAG,GAAG,IAAI,CAAC;IACf,KAAK,MAAM,CAAC,IAAI,MAAM;QAAE,GAAG,IAAI,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC/D,OAAO,GAAY,CAAC;AACtB,CAAC;AASD,MAAM,MAAM,GAAG,IAAI,GAAG,EAAoC,CAAC;AAC3D,MAAM,UAAU,YAAY,CAAC,QAA6B;IACxD,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;AACtC,CAAC;AACD,MAAM,UAAU,OAAO,CAAC,IAAiB;IACvC,OAAO,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@agenticprimitives/payments",
+  "version": "0.0.0-alpha.3",
+  "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",
+    "@agenticprimitives/attestations": "0.0.0-alpha.3",
+    "@agenticprimitives/delegation": "1.0.0-alpha.7",
+    "@agenticprimitives/verifiable-credentials": "0.0.0-alpha.3",
+    "@agenticprimitives/types": "1.0.0-alpha.7"
+  },
+  "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.