@recta/client 0.0.0-stage → 0.1.0

package/dist/policy.d.ts

@@ -0,0 +1,21 @@
+export interface WalletPolicyNetwork {
+    readonly network: string;
+    readonly chain_id: number;
+    readonly approvals: readonly {
+        readonly asset: string;
+        readonly token: string;
+        readonly spenders: readonly string[];
+    }[];
+    readonly call_targets: readonly {
+        readonly address: string;
+    }[];
+}
+export interface WalletPolicy {
+    readonly networks: readonly WalletPolicyNetwork[];
+}
+/**
+ * Reads Recta's wallet policy (`/v1/golden-corridor/wallet-policy`) into the shape the artifact checks use, and refuses
+ * it unless its fee block names exactly this package's pinned network, Permit2, spender, token and recipient. A policy
+ * that disagrees with the pins means the server is not the Recta this release was built for: nothing is signed.
+ */
+export declare function parseWalletPolicy(body: unknown): WalletPolicy;

package/dist/policy.js

@@ -0,0 +1,47 @@
+import { FEE_CHAIN_ID, FEE_RECEIVER, PERMIT2, UPTO_PROXY, USDC_BASE, WALLET_POLICY_SCHEMA } from "./constants.js";
+import { RectaCheckError } from "./errors.js";
+const ADDRESS = /^0x[0-9a-fA-F]{40}$/;
+/**
+ * Reads Recta's wallet policy (`/v1/golden-corridor/wallet-policy`) into the shape the artifact checks use, and refuses
+ * it unless its fee block names exactly this package's pinned network, Permit2, spender, token and recipient. A policy
+ * that disagrees with the pins means the server is not the Recta this release was built for: nothing is signed.
+ */
+export function parseWalletPolicy(body) {
+    const fail = (message) => { throw new RectaCheckError("wallet_policy", message); };
+    const p = typeof body === "object" && body !== null ? body : fail("not an object");
+    if (p["schema"] !== WALLET_POLICY_SCHEMA)
+        fail(`schema ${String(p["schema"])}, not ${WALLET_POLICY_SCHEMA}`);
+    const fee = typeof p["recta_fee"] === "object" && p["recta_fee"] !== null ? p["recta_fee"] : fail("no recta_fee");
+    const pinned = [
+        ["chain_id", fee["chain_id"], FEE_CHAIN_ID],
+        ["permit2", lower(fee["permit2"]), PERMIT2],
+        ["spender", lower(fee["spender"]), UPTO_PROXY],
+        ["token", lower(fee["token"]), USDC_BASE],
+        ["recipient", lower(fee["recipient"]), FEE_RECEIVER],
+    ];
+    for (const [field, served, pin] of pinned)
+        if (served !== pin)
+            fail(`recta_fee.${field} is ${String(served)}, not the pinned ${pin}`);
+    const networks = Array.isArray(p["networks"]) ? p["networks"] : fail("networks is not a list");
+    return {
+        networks: networks.map((raw, i) => {
+            const n = typeof raw === "object" && raw !== null ? raw : fail(`networks[${i}] is not an object`);
+            if (typeof n["network"] !== "string" || !Number.isSafeInteger(n["chain_id"]))
+                fail(`networks[${i}] has no network or chain_id`);
+            const approvals = Array.isArray(n["approvals"]) ? n["approvals"] : fail(`networks[${i}].approvals is not a list`);
+            const targets = Array.isArray(n["call_targets"]) ? n["call_targets"] : fail(`networks[${i}].call_targets is not a list`);
+            return {
+                network: n["network"],
+                chain_id: n["chain_id"],
+                approvals: approvals.map((a) => ({
+                    asset: typeof a["asset"] === "string" ? a["asset"] : fail(`networks[${i}]: an approval has no asset`),
+                    token: address(a["token"], fail),
+                    spenders: Array.isArray(a["spenders"]) ? a["spenders"].map((s) => address(s, fail)) : fail(`networks[${i}]: an approval has no spenders`),
+                })),
+                call_targets: targets.map((t) => ({ address: address(t["address"], fail) })),
+            };
+        }),
+    };
+}
+const lower = (v) => (typeof v === "string" ? v.toLowerCase() : v);
+const address = (v, fail) => (typeof v === "string" && ADDRESS.test(v) ? v.toLowerCase() : fail(`${String(v)} is not an address`));

package/dist/signer.d.ts

@@ -0,0 +1,104 @@
+import type { Account, Chain, Hex, PublicClient, Transport, TransactionSerializable, WalletClient } from "viem";
+/** One EIP-1559 transaction of an execution artifact, as this package asks a signer to send it. */
+export interface RectaTransaction {
+    readonly chainId: number;
+    readonly to: Hex;
+    readonly data: Hex;
+    readonly value: bigint;
+    readonly gas: bigint;
+    readonly maxFeePerGas: bigint;
+    readonly maxPriorityFeePerGas: bigint;
+}
+/** EIP-712 typed data of a Recta fee permit, as this package rebuilds it after its checks. */
+export interface RectaTypedData {
+    readonly domain: {
+        readonly name: "Permit2";
+        readonly chainId: number;
+        readonly verifyingContract: Hex;
+    };
+    readonly types: Record<string, readonly {
+        readonly name: string;
+        readonly type: string;
+    }[]>;
+    readonly primaryType: "PermitWitnessTransferFrom";
+    readonly message: Record<string, unknown>;
+}
+/**
+ * What this package needs from a wallet, and nothing more. It never receives or stores a key. The account must be an
+ * EOA: Recta's signed requests are EIP-191 signatures recovered to the sender's address (smart accounts cannot).
+ */
+export interface RectaSigner {
+    readonly address: Hex;
+    signMessage(message: string): Promise<Hex>;
+    signTypedData(typedData: RectaTypedData): Promise<Hex>;
+    /** Sends one transaction on `tx.chainId` and returns its hash. */
+    sendTransaction(tx: RectaTransaction): Promise<Hex>;
+}
+/** Read access to the source chain (the agent's own RPC): receipts. */
+export interface RectaChainReader {
+    /** Waits until the transaction is mined and returns whether it succeeded. */
+    waitForSuccess(chainId: number, hash: Hex): Promise<boolean>;
+}
+/** A RectaSigner from a viem account and one wallet client per chain. */
+export declare function viemSigner(args: {
+    readonly account: Account;
+    readonly walletClientFor: (chainId: number) => WalletClient<Transport, Chain | undefined, Account | undefined>;
+}): RectaSigner;
+/**
+ * What this package uses of a Coinbase CDP EVM server account (`await cdp.evm.getOrCreateAccount({ name })` in
+ * `@coinbase/cdp-sdk`): an EOA whose key stays in CDP and whose operations CDP's Policy Engine can restrict. Typed by
+ * shape only, so this package does not depend on the CDP SDK.
+ */
+export interface CdpEvmAccountLike {
+    readonly address: Hex;
+    signMessage(args: {
+        message: string;
+    }): Promise<Hex>;
+    signTypedData(args: {
+        domain: Record<string, unknown>;
+        types: Record<string, unknown>;
+        primaryType: string;
+        message: Record<string, unknown>;
+    }): Promise<Hex>;
+    signTransaction(transaction: TransactionSerializable): Promise<Hex>;
+    sendTransaction(args: {
+        network: CdpSendNetwork;
+        transaction: {
+            to: Hex;
+            data: Hex;
+            value: bigint;
+            gas: bigint;
+            maxFeePerGas: bigint;
+            maxPriorityFeePerGas: bigint;
+            type: "eip1559";
+        };
+    }): Promise<{
+        transactionHash: Hex;
+    }>;
+}
+/**
+ * EVM chains on which CDP itself sends a transaction (`sendEvmTransaction`, @coinbase/cdp-sdk 1.61.0), by chain id:
+ * exactly the networks of the CDP policy Recta serves (Fable #262 B-2), so every transaction CDP sends is one that
+ * policy can allow.
+ */
+export declare const CDP_SEND_NETWORKS: Readonly<{
+    readonly 1: "ethereum";
+    readonly 10: "optimism";
+    readonly 137: "polygon";
+    readonly 8453: "base";
+    readonly 42161: "arbitrum";
+    readonly 43114: "avalanche";
+}>;
+export type CdpSendNetwork = (typeof CDP_SEND_NETWORKS)[keyof typeof CDP_SEND_NETWORKS];
+/**
+ * A RectaSigner from a Coinbase CDP EVM server account. CDP signs the requests and the fee permit. A route transaction,
+ * after this package's checks like any other, is sent by CDP (`sendEvmTransaction`, which Recta's CDP policy at
+ * `/v1/golden-corridor/wallet-policy/cdp` restricts) on the chains CDP sends on; on any other chain it is signed by CDP
+ * (`signEvmTransaction`) and sent through `walletClientFor`, and without one it is refused.
+ */
+export declare function cdpSigner(args: {
+    readonly account: CdpEvmAccountLike;
+    readonly walletClientFor?: (chainId: number) => WalletClient<Transport, Chain | undefined, Account | undefined>;
+}): RectaSigner;
+/** A RectaChainReader from one viem public client per chain. */
+export declare function viemChainReader(publicClientFor: (chainId: number) => PublicClient): RectaChainReader;

package/dist/signer.js

@@ -0,0 +1,93 @@
+import { toAccount } from "viem/accounts";
+/** A RectaSigner from a viem account and one wallet client per chain. */
+export function viemSigner(args) {
+    const { account } = args;
+    if (account.signMessage === undefined || account.signTypedData === undefined) {
+        // A JSON-RPC account signs through the wallet client of the fee chain.
+        const client = args.walletClientFor(8453);
+        return {
+            address: account.address,
+            signMessage: (message) => client.signMessage({ account, message }),
+            signTypedData: (td) => client.signTypedData({ account, ...td }),
+            sendTransaction: (tx) => sendWith(args.walletClientFor(tx.chainId), account, tx),
+        };
+    }
+    return {
+        address: account.address,
+        signMessage: (message) => account.signMessage({ message }),
+        signTypedData: (td) => account.signTypedData(td),
+        sendTransaction: (tx) => sendWith(args.walletClientFor(tx.chainId), account, tx),
+    };
+}
+async function sendWith(client, account, tx) {
+    const chainId = await client.getChainId();
+    if (chainId !== tx.chainId)
+        throw new Error(`walletClientFor(${tx.chainId}) returned a client on chain ${chainId}`);
+    return client.sendTransaction({
+        account,
+        chain: client.chain ?? null,
+        to: tx.to,
+        data: tx.data,
+        value: tx.value,
+        gas: tx.gas,
+        maxFeePerGas: tx.maxFeePerGas,
+        maxPriorityFeePerGas: tx.maxPriorityFeePerGas,
+        type: "eip1559",
+    });
+}
+/**
+ * EVM chains on which CDP itself sends a transaction (`sendEvmTransaction`, @coinbase/cdp-sdk 1.61.0), by chain id:
+ * exactly the networks of the CDP policy Recta serves (Fable #262 B-2), so every transaction CDP sends is one that
+ * policy can allow.
+ */
+export const CDP_SEND_NETWORKS = Object.freeze({ 1: "ethereum", 10: "optimism", 137: "polygon", 8453: "base", 42161: "arbitrum", 43114: "avalanche" });
+/** Integers as decimal strings: CDP's API carries typed data as JSON, which has no bigint. The EIP-712 hash is the same. */
+function jsonSafe(value) {
+    if (typeof value === "bigint")
+        return value.toString();
+    if (Array.isArray(value))
+        return value.map(jsonSafe);
+    if (typeof value === "object" && value !== null)
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, jsonSafe(v)]));
+    return value;
+}
+/**
+ * A RectaSigner from a Coinbase CDP EVM server account. CDP signs the requests and the fee permit. A route transaction,
+ * after this package's checks like any other, is sent by CDP (`sendEvmTransaction`, which Recta's CDP policy at
+ * `/v1/golden-corridor/wallet-policy/cdp` restricts) on the chains CDP sends on; on any other chain it is signed by CDP
+ * (`signEvmTransaction`) and sent through `walletClientFor`, and without one it is refused.
+ */
+export function cdpSigner(args) {
+    const cdp = args.account;
+    const account = toAccount({
+        address: cdp.address,
+        signMessage: async ({ message }) => {
+            if (typeof message !== "string")
+                throw new Error("cdpSigner signs text messages only");
+            return cdp.signMessage({ message });
+        },
+        signTypedData: async (typedData) => cdp.signTypedData(jsonSafe(typedData)),
+        signTransaction: async (transaction) => cdp.signTransaction(transaction),
+    });
+    return {
+        address: cdp.address,
+        signMessage: (message) => account.signMessage({ message }),
+        signTypedData: (td) => account.signTypedData(td),
+        sendTransaction: async (tx) => {
+            const network = CDP_SEND_NETWORKS[tx.chainId];
+            if (network !== undefined) {
+                const { to, data, value, gas, maxFeePerGas, maxPriorityFeePerGas } = tx;
+                return (await cdp.sendTransaction({ network, transaction: { to, data, value, gas, maxFeePerGas, maxPriorityFeePerGas, type: "eip1559" } })).transactionHash;
+            }
+            if (args.walletClientFor === undefined)
+                throw new Error(`CDP does not send on chain ${tx.chainId}: give cdpSigner a walletClientFor`);
+            return sendWith(args.walletClientFor(tx.chainId), account, tx);
+        },
+    };
+}
+/** A RectaChainReader from one viem public client per chain. */
+export function viemChainReader(publicClientFor) {
+    return {
+        waitForSuccess: async (chainId, hash) => (await publicClientFor(chainId).waitForTransactionReceipt({ hash })).status === "success",
+    };
+}

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@recta/client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Client for Recta (api.recta.build): evaluate a cross-chain stablecoin transfer, authorize Recta's 5 %-of-verified-saving fee, execute the committed route and report it, with local checks before every signature.",
+  "license": "MIT",
+  "author": "Recta (https://recta.build)",
+  "homepage": "https://github.com/RectaBuild/recta/tree/main/packages/client#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RectaBuild/recta.git",
+    "directory": "packages/client"
+  },
+  "bugs": {
+    "url": "https://github.com/RectaBuild/recta/issues"
+  },
+  "keywords": [
+    "recta",
+    "ai-agent",
+    "cross-chain",
+    "bridge",
+    "stablecoin",
+    "usdc",
+    "x402",
+    "viem"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "peerDependencies": {
+    "viem": ">=2.56.3 <3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}