@oathbuild/x402 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,24 @@
-# Temporary Holding Version
+# @oathbuild/x402
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+OATH is a Transaction Builder for autonomous agents. It builds complete agent transaction flows across MCP, x402 and onchain actions, with authorization built into the execution path.
+
+```bash
+npm install @oathbuild/x402 viem
+```
+
+```ts
+import { createX402 } from "@oathbuild/x402"
+
+const x402 = createX402({ oath, payer: agent })
+const res = await x402.fetch(url)   // answers a 402 by paying, if the OATH allows it
+```
+
+Supports the exact scheme over EIP-3009 and Permit2, and x402 over MCP. A payment outside the service's cap or the OATH's limit is refused before anything is signed. OATH integrates x402 as it exists; it does not define its own payment standard.
+
+## Links
+
+- Docs: https://oathbuild.net/docs
+- Contract addresses: https://oathbuild.net/docs#/deployments
+- App: https://oathbuild.net/app
+
+MIT licensed.

package/dist/index.d.ts

@@ -0,0 +1,168 @@
+import { type KeyObject } from 'node:crypto';
+import { type Address, type Hex, type LocalAccount } from 'viem';
+import type { Oath, ActionInput } from '@oathbuild/core';
+export type PaymentRequirements = {
+    scheme: string;
+    network: string;
+    amount: string;
+    asset: string;
+    payTo: string;
+    maxTimeoutSeconds: number;
+    extra?: {
+        name?: string;
+        version?: string;
+        assetTransferMethod?: string;
+        [k: string]: unknown;
+    };
+};
+export type PaymentRequired = {
+    x402Version: number;
+    error?: string;
+    resource?: {
+        url: string;
+        description?: string;
+        mimeType?: string;
+    };
+    accepts: PaymentRequirements[];
+};
+export type PaymentPayload = {
+    x402Version: 2;
+    resource?: PaymentRequired['resource'];
+    accepted: PaymentRequirements;
+    payload: unknown;
+};
+export type Payment = {
+    serviceId: string;
+    url: string;
+    scheme: string;
+    network: string;
+    asset: string;
+    amount: bigint;
+    payTo: string;
+    settlement: unknown;
+    timestamp: number;
+};
+export declare class X402Error extends Error {
+    code: string;
+    constructor(code: string, message: string);
+}
+export declare const decodePaymentRequired: (header: string) => PaymentRequired;
+export type SchemeContext = {
+    oath: Oath;
+    payer: LocalAccount;
+};
+export type Scheme = {
+    name: string;
+    /** Whether this scheme can pay the requirement at all (scope and budget are checked separately). */
+    supports(req: PaymentRequirements, ctx: SchemeContext): boolean;
+    /** Produces the scheme-specific payload. */
+    pay(req: PaymentRequirements, ctx: SchemeContext): Promise<unknown>;
+    /** Extra request headers some bindings need, computed over the final PAYMENT-SIGNATURE value. */
+    headers?(paymentHeader: string, url: URL): Record<string, string>;
+};
+/** exact / EIP-3009: the payer signs a transferWithAuthorization the facilitator submits. */
+export declare const exactEip3009: Scheme;
+export declare const PERMIT2_ADDRESS: Address;
+/** The spender x402 requires for Permit2 payments: the proxy, never the facilitator. */
+export declare const X402_PERMIT2_PROXY: Address;
+export declare const PERMIT2_WITNESS_TYPES: {
+    readonly PermitWitnessTransferFrom: readonly [{
+        readonly name: 'permitted';
+        readonly type: 'TokenPermissions';
+    }, {
+        readonly name: 'spender';
+        readonly type: 'address';
+    }, {
+        readonly name: 'nonce';
+        readonly type: 'uint256';
+    }, {
+        readonly name: 'deadline';
+        readonly type: 'uint256';
+    }, {
+        readonly name: 'witness';
+        readonly type: 'Witness';
+    }];
+    readonly TokenPermissions: readonly [{
+        readonly name: 'token';
+        readonly type: 'address';
+    }, {
+        readonly name: 'amount';
+        readonly type: 'uint256';
+    }];
+    readonly Witness: readonly [{
+        readonly name: 'to';
+        readonly type: 'address';
+    }, {
+        readonly name: 'validAfter';
+        readonly type: 'uint256';
+    }];
+};
+/** exact / Permit2: a witness transfer that can only pay `payTo`, through the x402 proxy. */
+export declare const exactPermit2: Scheme;
+/**
+ * batch-settlement on the cloudflare:402 network: the only published binding of that scheme.
+ * Credit-backed and offchain: the client commits to an amount in fiat, signs the request with an
+ * Ed25519 HTTP Message Signature (RFC 9421, Web Bot Auth), and Cloudflare bills the registered
+ * account later. No token moves and no chain is involved, so nothing here is bounded onchain: the
+ * only OATH limit that applies is the service's maxSpend, counted in the requirement's own units
+ * (cents for USD), enforced by this adapter.
+ * Needs a Cloudflare account with the signature agent registered.
+ */
+export declare function cloudflareBatchSettlement(opts: {
+    signatureAgent: string;
+    keyId: string;
+    privateKey: KeyObject | string;
+    validForSeconds?: number;
+}): Scheme;
+export type X402Options = {
+    oath: Oath;
+    /** Signs payments. For the onchain schemes it holds the balance payments are made from. */
+    payer: LocalAccount;
+    /** Maps a URL to a service id in the OATH. Defaults to the URL's host. */
+    serviceId?: (url: URL) => string;
+    /** Tried in order for each accepted requirement. Defaults to EIP-3009, then Permit2. */
+    schemes?: Scheme[];
+    fetch?: typeof fetch;
+};
+export declare function createX402(opts: X402Options): {
+    fetch: (input: string | URL, init?: RequestInit) => Promise<Response>;
+    pay: (required: PaymentRequired, serviceId: string, url?: string) => Promise<{
+        paymentPayload: PaymentPayload;
+        accepted: PaymentRequirements;
+        scheme: Scheme;
+        settled: (settlement: unknown) => Payment;
+    }>;
+    /** Every payment a service accepted. */
+    payments: Payment[];
+    spent: (serviceId?: string) => bigint;
+    /**
+     * The transfer that funds the payer's float: an ordinary token transfer from the OATH Account, to
+     * go in the workflow before the paid calls. Fund what the plan's payments add up to and no more;
+     * the account measures it against the OATH's spend limit like any other outflow.
+     */
+    float: (asset: Address, amount: bigint, id?: string) => ActionInput;
+    /**
+     * Sends whatever is left of the float back to the OATH Account. Run it when the workflow ends, so
+     * no balance is left sitting on the agent key. The payer pays the gas for this one transaction.
+     * Returned funds do not restore the OATH's spend allowance: the limit counts what left the account.
+     */
+    sweep(chain: {
+        public: {
+            readContract: (a: any) => Promise<unknown>;
+            waitForTransactionReceipt: (a: {
+                hash: Hex;
+            }) => Promise<unknown>;
+        };
+        wallet: (account: LocalAccount) => {
+            writeContract: (a: any) => Promise<Hex>;
+        };
+    }, asset: Address): Promise<{
+        amount: bigint;
+        txHash?: Hex;
+    }>;
+    /** Token payments as X402_PAYMENT nodes, for the Builder's graph and receipts. */
+    actions: () => ActionInput[];
+};
+export type X402 = ReturnType<typeof createX402>;
+/** Wraps fetch. Shorthand for createX402(opts).fetch. */
+export declare const withX402: (fetchImpl: typeof fetch, opts: Omit<X402Options, 'fetch'>) => (input: string | URL, init?: RequestInit) => Promise<Response>;

package/dist/index.js

@@ -0,0 +1,217 @@
+// @oathbuild/x402 — pays x402 V2 services inside an OATH's budget.
+//
+// Uses x402 as specified: PAYMENT-REQUIRED / PAYMENT-SIGNATURE / PAYMENT-RESPONSE headers
+// (base64 JSON) over HTTP, and _meta["x402/payment"] over MCP. No OATH-specific headers.
+//
+// Schemes:
+//   exact + EIP-3009                 built in
+//   exact + Permit2                  built in (the payer must have approved Permit2 once)
+//   batch-settlement, cloudflare:402 opt in with cloudflareBatchSettlement(...)
+//
+// Funding model for the onchain schemes: payments are signed by the agent's own key from a balance
+// the agent holds. That balance is topped up by an ordinary transfer inside an OATH bundle, which the
+// account measures against the spend limit. So the onchain bound on x402 spend is the amount moved to
+// the agent; the per-service caps below are enforced here, by the adapter.
+import { sign as edSign, createPrivateKey } from 'node:crypto';
+import { toHex, hexToBigInt, isAddress, encodeFunctionData, erc20Abi } from 'viem';
+export class X402Error extends Error {
+    code;
+    constructor(code, message) { super(message); this.code = code; }
+}
+const b64encode = (v) => Buffer.from(JSON.stringify(v)).toString('base64');
+const b64decode = (s) => JSON.parse(Buffer.from(s, 'base64').toString('utf8'));
+export const decodePaymentRequired = (header) => b64decode(header);
+const randomHex = (bytes) => toHex(crypto.getRandomValues(new Uint8Array(bytes)));
+const nowSeconds = () => Math.floor(Date.now() / 1000);
+const onChain = (req, ctx) => req.scheme === 'exact' && req.network === `eip155:${ctx.oath.chainId}` && isAddress(req.asset);
+const deadline = (req, ctx) => Math.min(nowSeconds() + req.maxTimeoutSeconds, Number(ctx.oath.validUntil));
+/** exact / EIP-3009: the payer signs a transferWithAuthorization the facilitator submits. */
+export const exactEip3009 = {
+    name: 'exact/eip3009',
+    supports: (req, ctx) => onChain(req, ctx) && (req.extra?.assetTransferMethod ?? 'eip3009') === 'eip3009',
+    async pay(req, ctx) {
+        const authorization = { from: ctx.payer.address, to: req.payTo, value: req.amount, validAfter: '0', validBefore: String(deadline(req, ctx)), nonce: randomHex(32) };
+        const signature = await ctx.payer.signTypedData({
+            domain: { name: req.extra?.name, version: req.extra?.version, chainId: Number(ctx.oath.chainId), verifyingContract: req.asset },
+            types: { TransferWithAuthorization: [
+                    { name: 'from', type: 'address' }, { name: 'to', type: 'address' }, { name: 'value', type: 'uint256' },
+                    { name: 'validAfter', type: 'uint256' }, { name: 'validBefore', type: 'uint256' }, { name: 'nonce', type: 'bytes32' },
+                ] },
+            primaryType: 'TransferWithAuthorization',
+            message: { from: authorization.from, to: req.payTo, value: BigInt(req.amount), validAfter: 0n, validBefore: BigInt(authorization.validBefore), nonce: authorization.nonce },
+        });
+        return { signature, authorization };
+    },
+};
+export const PERMIT2_ADDRESS = '0x000000000022D473030F116dDEE9F6B43aC78BA3';
+/** The spender x402 requires for Permit2 payments: the proxy, never the facilitator. */
+export const X402_PERMIT2_PROXY = '0x402085c248EeA27D92E8b30b2C58ed07f9E20001';
+export const PERMIT2_WITNESS_TYPES = {
+    PermitWitnessTransferFrom: [
+        { name: 'permitted', type: 'TokenPermissions' }, { name: 'spender', type: 'address' },
+        { name: 'nonce', type: 'uint256' }, { name: 'deadline', type: 'uint256' }, { name: 'witness', type: 'Witness' },
+    ],
+    TokenPermissions: [{ name: 'token', type: 'address' }, { name: 'amount', type: 'uint256' }],
+    Witness: [{ name: 'to', type: 'address' }, { name: 'validAfter', type: 'uint256' }],
+};
+/** exact / Permit2: a witness transfer that can only pay `payTo`, through the x402 proxy. */
+export const exactPermit2 = {
+    name: 'exact/permit2',
+    supports: (req, ctx) => onChain(req, ctx) && req.extra?.assetTransferMethod === 'permit2',
+    async pay(req, ctx) {
+        const permit2Authorization = {
+            permitted: { token: req.asset, amount: req.amount },
+            from: ctx.payer.address,
+            spender: X402_PERMIT2_PROXY,
+            nonce: hexToBigInt(randomHex(32)).toString(), // Permit2 nonces are unordered: any unused value
+            deadline: String(deadline(req, ctx)),
+            witness: { to: req.payTo, validAfter: String(nowSeconds() - 60) },
+        };
+        const signature = await ctx.payer.signTypedData({
+            domain: { name: 'Permit2', chainId: Number(ctx.oath.chainId), verifyingContract: PERMIT2_ADDRESS },
+            types: PERMIT2_WITNESS_TYPES,
+            primaryType: 'PermitWitnessTransferFrom',
+            message: {
+                permitted: { token: req.asset, amount: BigInt(req.amount) }, spender: X402_PERMIT2_PROXY,
+                nonce: BigInt(permit2Authorization.nonce), deadline: BigInt(permit2Authorization.deadline),
+                witness: { to: req.payTo, validAfter: BigInt(permit2Authorization.witness.validAfter) },
+            },
+        });
+        return { signature, permit2Authorization };
+    },
+};
+/**
+ * batch-settlement on the cloudflare:402 network: the only published binding of that scheme.
+ * Credit-backed and offchain: the client commits to an amount in fiat, signs the request with an
+ * Ed25519 HTTP Message Signature (RFC 9421, Web Bot Auth), and Cloudflare bills the registered
+ * account later. No token moves and no chain is involved, so nothing here is bounded onchain: the
+ * only OATH limit that applies is the service's maxSpend, counted in the requirement's own units
+ * (cents for USD), enforced by this adapter.
+ * Needs a Cloudflare account with the signature agent registered.
+ */
+export function cloudflareBatchSettlement(opts) {
+    const key = typeof opts.privateKey === 'string' ? createPrivateKey(opts.privateKey) : opts.privateKey;
+    return {
+        name: 'batch-settlement/cloudflare',
+        supports: (req) => req.scheme === 'batch-settlement' && req.network === 'cloudflare:402',
+        pay: async (req) => ({ amount: req.amount, asset: req.asset }),
+        headers(paymentHeader, url) {
+            const created = nowSeconds(), expires = created + (opts.validForSeconds ?? 300);
+            const params = `("@authority" "signature-agent" "payment-signature");created=${created};expires=${expires};keyid="${opts.keyId}";tag="web-bot-auth"`;
+            const base = [`"@authority": ${url.host}`, `"signature-agent": ${opts.signatureAgent}`, `"payment-signature": ${paymentHeader}`, `"@signature-params": ${params}`].join('\n');
+            return { 'Signature-Agent': opts.signatureAgent, 'Signature-Input': `sig=${params}`, Signature: `sig=:${edSign(null, Buffer.from(base), key).toString('base64')}:` };
+        },
+    };
+}
+export function createX402(opts) {
+    const { oath, payer } = opts;
+    const baseFetch = opts.fetch ?? fetch;
+    const schemes = opts.schemes ?? [exactEip3009, exactPermit2];
+    const ctx = { oath, payer };
+    const payments = [];
+    const sum = (f) => payments.filter(f).reduce((n, p) => n + p.amount, 0n);
+    const same = (a, b) => a.toLowerCase() === b.toLowerCase();
+    /** Picks a requirement a scheme can pay and the OATH allows. Throws with the reason otherwise. */
+    function select(required, serviceId) {
+        if (nowSeconds() >= Number(oath.validUntil))
+            throw new X402Error('OATH_EXPIRED', 'The OATH has expired.');
+        const service = oath.services.find((s) => s.serviceId === serviceId);
+        if (!service)
+            throw new X402Error('SERVICE_NOT_ALLOWED', `Service "${serviceId}" is not in the OATH.`);
+        const payable = required.accepts.flatMap((accepted) => { const scheme = schemes.find((s) => s.supports(accepted, ctx)); return scheme ? [{ accepted, scheme }] : []; });
+        if (!payable.length)
+            throw new X402Error('NO_SUPPORTED_SCHEME', `No accepted scheme is supported (configured: ${schemes.map((s) => s.name).join(', ')}).`);
+        let reason;
+        for (const option of payable) {
+            const r = option.accepted, amount = BigInt(r.amount);
+            // The service cap counts in the asset's own units. One service is expected to bill in one asset.
+            if (sum((p) => p.serviceId === serviceId && same(p.asset, r.asset)) + amount > service.maxSpend) {
+                reason = new X402Error('SPEND_LIMIT_EXCEEDED', `Payment would exceed the cap for "${serviceId}".`);
+                continue;
+            }
+            if (isAddress(r.asset)) { // a token: also bounded by the OATH's spend limit for that token
+                const limit = oath.spendLimits.find((l) => same(l.asset, r.asset));
+                if (!limit) {
+                    reason = new X402Error('ASSET_NOT_ALLOWED', `Asset ${r.asset} has no spend limit in the OATH.`);
+                    continue;
+                }
+                if (sum((p) => same(p.asset, r.asset)) + amount > limit.amount) {
+                    reason = new X402Error('SPEND_LIMIT_EXCEEDED', `Payment would exceed the OATH spend limit for ${r.asset}.`);
+                    continue;
+                }
+            }
+            return option;
+        }
+        throw reason;
+    }
+    /** Authorizes one payment for a requirement. Nothing is signed unless the OATH allows it.
+     *  Call `settled` once the service has accepted it; only then does it count as spent. */
+    async function pay(required, serviceId, url = required.resource?.url ?? '') {
+        const { accepted, scheme } = select(required, serviceId);
+        const paymentPayload = { x402Version: 2, resource: required.resource, accepted, payload: await scheme.pay(accepted, ctx) };
+        const settled = (settlement) => {
+            const payment = { serviceId, url, scheme: scheme.name, network: accepted.network, asset: accepted.asset, amount: BigInt(accepted.amount), payTo: accepted.payTo, settlement, timestamp: nowSeconds() };
+            payments.push(payment);
+            return payment;
+        };
+        return { paymentPayload, accepted, scheme, settled };
+    }
+    /** fetch that answers 402 Payment Required once, if the OATH allows the payment. */
+    async function paidFetch(input, init = {}) {
+        const url = new URL(String(input));
+        const first = await baseFetch(url, init);
+        const header = first.headers.get('PAYMENT-REQUIRED');
+        if (first.status !== 402 || !header)
+            return first;
+        const serviceId = (opts.serviceId ?? ((u) => u.host))(url);
+        const { paymentPayload, scheme, settled } = await pay(decodePaymentRequired(header), serviceId, url.href);
+        const paymentHeader = b64encode(paymentPayload);
+        const headers = new Headers(init.headers);
+        headers.set('PAYMENT-SIGNATURE', paymentHeader);
+        for (const [k, v] of Object.entries(scheme.headers?.(paymentHeader, url) ?? {}))
+            headers.set(k, v);
+        const second = await baseFetch(url, { ...init, headers });
+        // A service that still answers 402 did not accept the payment; nothing is recorded as spent.
+        if (second.status !== 402) {
+            const response = second.headers.get('PAYMENT-RESPONSE');
+            settled(response ? b64decode(response) : null);
+        }
+        return second;
+    }
+    return {
+        fetch: paidFetch,
+        pay,
+        /** Every payment a service accepted. */
+        payments,
+        spent: (serviceId) => sum((p) => !serviceId || p.serviceId === serviceId),
+        /**
+         * The transfer that funds the payer's float: an ordinary token transfer from the OATH Account, to
+         * go in the workflow before the paid calls. Fund what the plan's payments add up to and no more;
+         * the account measures it against the OATH's spend limit like any other outflow.
+         */
+        float: (asset, amount, id = 'x402-float') => ({
+            id, type: 'TOKEN_TRANSFER', label: 'fund x402 float', target: asset, spend: { asset, amount },
+            payload: encodeFunctionData({ abi: erc20Abi, functionName: 'transfer', args: [payer.address, amount] }),
+        }),
+        /**
+         * Sends whatever is left of the float back to the OATH Account. Run it when the workflow ends, so
+         * no balance is left sitting on the agent key. The payer pays the gas for this one transaction.
+         * Returned funds do not restore the OATH's spend allowance: the limit counts what left the account.
+         */
+        async sweep(chain, asset) {
+            const amount = await chain.public.readContract({ address: asset, abi: erc20Abi, functionName: 'balanceOf', args: [payer.address] });
+            if (amount === 0n)
+                return { amount };
+            const txHash = await chain.wallet(payer).writeContract({ address: asset, abi: erc20Abi, functionName: 'transfer', args: [oath.account, amount], chain: null, account: payer });
+            await chain.public.waitForTransactionReceipt({ hash: txHash });
+            return { amount, txHash };
+        },
+        /** Token payments as X402_PAYMENT nodes, for the Builder's graph and receipts. */
+        actions: () => payments.map((p, i) => ({
+            id: `x402-${i + 1}`, type: 'X402_PAYMENT', label: `x402 ${p.serviceId}`, target: p.serviceId, scheme: p.scheme.startsWith('batch') ? 'batch' : 'exact',
+            ...(isAddress(p.asset) ? { spend: { asset: p.asset, amount: p.amount } } : {}),
+        })),
+    };
+}
+/** Wraps fetch. Shorthand for createX402(opts).fetch. */
+export const withX402 = (fetchImpl, opts) => createX402({ ...opts, fetch: fetchImpl }).fetch;

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@oathbuild/x402",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "OATH x402 adapter: pay x402 services inside the budget a signed OATH allows.",
+  "keywords": [
+    "oath",
+    "agents",
+    "transaction-builder",
+    "mcp",
+    "x402",
+    "robinhood-chain",
+    "eip-712"
+  ],
+  "homepage": "https://oathbuild.net/docs",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/*.tsbuildinfo",
+    "!dist/.tsbuildinfo"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@oathbuild/core": "0.1.0",
+    "viem": "^2.21.0"
+  }
 }