@recta/client 0.1.1 → 0.1.4

package/README.md

@@ -18,7 +18,7 @@ It never receives a key. Before it signs or sends anything it checks it locally,
 npm install @recta/client viem
 ```
 
-`viem` (>= 2.30, < 3) is the only dependency, and you choose its version.
+`viem` (>= 2.38.3, < 3) is the only dependency, and you choose its version.
 
 ## Use
 
@@ -33,9 +33,12 @@ const recta = createRectaClient({
     maxNativeValueWei: 10n ** 15n,   // never attach more than 0.001 native to one route transaction
     minOutputBps: 9900,              // required, 1–10000: the route must guarantee the recipient at least 99 % of the amount sent
   },
+  referrer: "0x…",                   // optional: the integrator that ships this agent (see "Referral for integrators")
 });
 
-// Dry run: evaluates and checks, signs no permit, sends no transaction.
+// Dry run: evaluates and checks, signs no permit, sends no transaction. With Recta's collection on it stops at the
+// fee permit, before the transactions exist (Recta hands them out only after the permit is signed): `preview.fee`
+// carries the permit it would sign and `funds`, whether this wallet can pay it (see "Paying the fee").
 const preview = await recta.run(request, { dryRun: true });
 
 // The whole flow.
@@ -45,10 +48,22 @@ const result = await recta.run(request);
 `request` is Recta's evaluation request (schema in the
 [service descriptor](https://api.recta.build/v1/golden-corridor/commercial-evaluations/schema)); its `sender` must be
 your signer's address. Each step is also available alone: `evaluate`, `authorizeFee`, `check`, `execute`, `report`,
-`ledger`, `payDebt`.
+`ledger`, `payDebt`, `feeFunds`, `feeApproval`.
 
 Your account must be an EOA: Recta's signed requests are EIP-191 signatures recovered to the sender's address.
 
+## Referral for integrators
+
+If you ship Recta inside a plugin, framework or agent template, set your own EVM address once as the `referrer` and
+every agent that runs your integration carries it. Recta fixes it at the agent's first signed evaluation and never
+changes it afterwards. You earn 20 % of the fees Recta actually collects from those agents (confirmed on chain) for
+12 months, up to 200 USDC per agent, whether or not you pay fees yourself. One level only. The agent still pays exactly
+5 % of its verified saving: your share comes out of Recta's 5 %, never on top of it.
+
+The referrer travels in the query of the agent's own signed requests, so nobody relaying them can add, drop or change
+it. It is ignored when it is the agent's own address. Terms and your balance: `GET /v1/referrals/balance`, signed by
+your address, once Recta's referral program is on (it starts together with fee collection).
+
 ### Coinbase CDP accounts
 
 A [Coinbase CDP](https://docs.cdp.coinbase.com) EVM server account (an EOA whose key stays in CDP) works through
@@ -82,6 +97,42 @@ really uses. If your agent bridges through LI.FI (its public API or an aggregato
 wherever the fit check (`GET /v1/golden-corridor/fit`) lists it in `declarable_baselines`; it is refused with
 `latency_class` SECONDS or MINUTES. Recta reads LI.FI's own transaction, its fee included. If that route is already the cheapest, Recta answers with no saving and charges nothing.
 
+## Paying the fee: USDC and the Permit2 allowance on Base
+
+Recta's fee is collected in USDC on Base through Permit2. Signing the permit is not enough: when Recta settles it,
+Permit2 pulls the fee with USDC's own `transferFrom`, so the wallet also needs, on Base, (1) at least the permit's amount
+in USDC and (2) an ERC-20 allowance from USDC to Permit2 (`0x000000000022D473030F116dDEE9F6B43aC78BA3`) of at least that
+amount. A new wallet has neither.
+
+Before it signs a fee or debt permit, the client reads both through `chain.readFeeFunds` (on Base: `viemChainReader`
+uses `publicClients[8453]`) and refuses, with `RectaCheckError` `fee_balance` or `fee_allowance`, when either is short.
+Nothing is signed and no route transaction is sent, so a route never executes with a fee Recta cannot collect.
+
+```ts
+const funds = await recta.feeFunds();      // { ready, balanceUsdcAtomic, permit2AllowanceUsdcAtomic, missing }
+if (funds.missing.includes("allowance")) {
+  const approval = recta.feeApproval();    // USDC.approve(Permit2, maxPermitUsdcAtomic) on Base, for you to send
+  // send `approval` (chainId, to, data, value) with your own wallet
+}
+```
+
+The approval is bounded: `feeApproval` defaults to, and may not exceed, `maxPermitUsdcAtomic`, and
+`permit2ApprovalTransaction` refuses 0 and any "unlimited" amount. The client never approves by itself. Each collected
+fee lowers the allowance; approve again when `feeFunds` reports it short. The check is a snapshot at signing: a wallet
+that later spends its USDC or revokes the allowance leaves the fee unpaid, which Recta records as a debt to settle
+before the next evaluation (`payDebt`).
+
+When the route itself starts from USDC on Base, the transfer spends the same balance before the fee is pulled, so the
+balance must cover the transfer plus the fee: `run` passes the request to `authorizeFee` for that (pass it yourself as
+`authorizeFee(id, { request })` when calling the steps alone), and `execute` checks the funds again, for every fee
+this client authorized or found authorized, right before the first transaction. A reader error never carries the RPC
+URL (it may hold an API key).
+
+Since 0.1.4 `RectaChainReader` requires `readFeeFunds`; `createRectaClient` refuses a reader without it.
+
+A custom `RectaChainReader` must implement `readFeeFunds(owner)`; when it cannot read Base it must throw, and the permit
+is then not signed (a dry run reports `funds: null` and the reason).
+
 ## What is checked before signing
 
 **Pins.** The package carries Recta's fee addresses in its own code: Permit2, x402's `upto` proxy, USDC on Base,
@@ -119,6 +170,10 @@ the declared messaging fee, within `maxNativeValueWei`.
 `RectaDebtError` with the offer. The package never signs a debt by itself: call `payDebt(offer)` if you agree (same
 checks, exact amount).
 
+## What each request identifies
+
+Every request this package sends carries the User-Agent `recta-client/<version>`, so Recta can count real use of the package apart from other clients. It names the package and its version only: never an address, a key or a request body.
+
 ## Limits of this version
 
 - EVM sources and EVM recipients only. Solana, Tron and Bitcoin routes, Relay and deBridge are refused.

package/dist/client.d.ts

@@ -1,5 +1,6 @@
 import { type Hex } from "viem";
 import { type CheckedArtifact, type EvaluationRequestView } from "./artifact.js";
+import { type FeeReadiness, type Permit2Approval } from "./funds.js";
 import type { RectaChainReader, RectaSigner, RectaTypedData } from "./signer.js";
 export interface RectaClientOptions {
     readonly signer: RectaSigner;
@@ -12,6 +13,14 @@ export interface RectaClientOptions {
         /** The least the recipient must be guaranteed, in basis points of the amount sent (e.g. 9950 = 99.5 %). */
         readonly minOutputBps: number;
     };
+    /**
+     * Who referred this agent to Recta (OD-REF-1): an EVM address, usually the author of the plugin, framework or template
+     * that ships this client. Sent as `?referrer=` on the signed evaluation and fee-authorization requests, so it is part
+     * of what the agent's own key signs. Recta fixes it once, at the agent's first signed evaluation, and never changes it;
+     * the agent still pays exactly 5 % of its verified saving (the referrer's share comes out of Recta's 5 %). Ignored
+     * when it is the signer's own address (nobody can refer itself).
+     */
+    readonly referrer?: string;
     /** Defaults to the global fetch. */
     readonly fetch?: typeof fetch;
     /** Milliseconds since the epoch; defaults to Date.now. */
@@ -25,6 +34,8 @@ export declare function signedRequestMessage(f: {
     readonly bodyKeccak256: string;
     readonly issuedAt: number;
 }): string;
+/** The `?referrer=` suffix for a configured referrer: lower-cased, empty when none or when it is the payer itself. */
+export declare function referrerQuery(referrer: string | undefined, payer: string): string;
 export type FeeOutcome = {
     readonly kind: "NOT_REQUIRED";
 } | {
@@ -37,6 +48,8 @@ export type FeeOutcome = {
     readonly kind: "DRY_RUN";
     readonly amountUsdcAtomic: bigint;
     readonly typedData: RectaTypedData;
+    readonly funds: FeeReadiness | null;
+    readonly fundsError?: string;
 };
 /**
  * Recta's flow for an agent that holds its own EOA: evaluate → authorizeFee → execute → report. Every step can be
@@ -49,6 +62,7 @@ export declare function createRectaClient(options: RectaClientOptions): {
     }) => Promise<Record<string, unknown>>;
     authorizeFee: (resultId: string, opts?: {
         readonly dryRun?: boolean;
+        readonly request?: EvaluationRequestView;
     }) => Promise<{
         readonly fee: FeeOutcome;
         readonly artifact: unknown;
@@ -79,6 +93,8 @@ export declare function createRectaClient(options: RectaClientOptions): {
             readonly kind: "DRY_RUN";
             readonly amountUsdcAtomic: bigint;
             readonly typedData: RectaTypedData;
+            readonly funds: FeeReadiness | null;
+            readonly fundsError?: string;
         };
         checked?: never;
     } | {
@@ -115,5 +131,7 @@ export declare function createRectaClient(options: RectaClientOptions): {
         checked?: never;
     }>;
     walletPolicy: () => Promise<void>;
+    feeFunds: (requiredUsdcAtomic?: bigint) => Promise<FeeReadiness>;
+    feeApproval: (amountUsdcAtomic?: bigint) => Permit2Approval;
 };
 export type RectaClient = ReturnType<typeof createRectaClient>;

package/dist/client.js

@@ -1,8 +1,9 @@
 import { keccak256 } from "viem";
 import { checkExecutionArtifact } from "./artifact.js";
-import { ISSUED_AT_HEADER, PATHS, RECTA_ORIGIN, SIGNATURE_HEADER, SIGNED_REQUEST_PREFIX, SIGNER_HEADER } from "./constants.js";
+import { ISSUED_AT_HEADER, PATHS, RECTA_ORIGIN, SIGNATURE_HEADER, SIGNED_REQUEST_PREFIX, SIGNER_HEADER, USER_AGENT } from "./constants.js";
 import { RectaCheckError, RectaDebtError, RectaHttpError } from "./errors.js";
 import { checkFeePermit } from "./fee.js";
+import { assertFeeReady, feeReadiness, permit2ApprovalTransaction, routeReserveOf, safeErrorText } from "./funds.js";
 import { parseWalletPolicy } from "./policy.js";
 /** The text a sender signs for one request (EIP-191), exactly as Recta's server rebuilds it. */
 export function signedRequestMessage(f) {
@@ -16,6 +17,16 @@ export function signedRequestMessage(f) {
     ].join("\n");
 }
 const RESULT_ID = /^[A-Za-z0-9_-]+$/;
+const ADDRESS = /^0x[0-9a-fA-F]{40}$/;
+/** The `?referrer=` suffix for a configured referrer: lower-cased, empty when none or when it is the payer itself. */
+export function referrerQuery(referrer, payer) {
+    if (referrer === undefined)
+        return "";
+    if (!ADDRESS.test(referrer))
+        throw new RectaCheckError("referrer", "the referrer must be a 0x-prefixed 20-byte EVM address");
+    const r = referrer.toLowerCase();
+    return r === payer.toLowerCase() ? "" : `?referrer=${r}`;
+}
 const field = (v, k) => (typeof v === "object" && v !== null ? v[k] : undefined);
 const resultIdOf = (v) => {
     if (!RESULT_ID.test(v))
@@ -33,10 +44,19 @@ export function createRectaClient(options) {
     const now = options.now ?? Date.now;
     const nowUnix = () => BigInt(Math.floor(now() / 1000));
     const payer = signer.address.toLowerCase();
+    const referral = referrerQuery(options.referrer, payer);
+    if (typeof chain.readFeeFunds !== "function") {
+        // Since 0.1.4 (ASTRA T2) a reader must read the fee funds on Base; an older custom reader fails here, clearly.
+        throw new RectaCheckError("chain_reader", "the chain reader has no readFeeFunds(owner): since @recta/client 0.1.4 it must read the payer's USDC balance and Permit2 allowance on Base (viemChainReader does)");
+    }
+    /** The fee permit amount of each decision this client saw authorized: execute() checks the funds against it again
+     *  right before the first transaction (Fable B-1/M-1 on recta #12). */
+    const feeAmounts = new Map();
+    const parseAtomic = (v) => (typeof v === "string" && /^(0|[1-9][0-9]{0,30})$/.test(v) ? BigInt(v) : undefined);
     let policyChecked = false;
     async function call(method, path, body, idempotencyKey, signed = true) {
         const bytes = body === undefined ? new Uint8Array() : new TextEncoder().encode(JSON.stringify(body));
-        const headers = { accept: "application/json" };
+        const headers = { accept: "application/json", "user-agent": USER_AGENT };
         if (body !== undefined)
             headers["content-type"] = "application/json";
         if (idempotencyKey !== undefined)
@@ -72,7 +92,7 @@ export function createRectaClient(options) {
         if (typeof request.sender !== "string" || request.sender.toLowerCase() !== payer)
             throw new RectaCheckError("sender", "the request's sender must be the signer");
         await walletPolicy();
-        const a = await call("POST", PATHS.evaluations, request, opts.idempotencyKey ?? crypto.randomUUID());
+        const a = await call("POST", `${PATHS.evaluations}${referral}`, request, opts.idempotencyKey ?? crypto.randomUUID());
         if (a.status === 402)
             throw new RectaDebtError(a.body, field(a.body, "debt_offer") ?? null);
         if (a.status !== 200)
@@ -81,17 +101,32 @@ export function createRectaClient(options) {
     }
     /**
      * Step 2: the decision's committed transactions. With Recta's collection on, the artifact first asks for the fee
-     * permit: it is checked, rebuilt and signed only if it passes, then stored, and the answer carries the artifact. With
-     * `dryRun`, it stops before signing and returns the typed data it would sign.
+     * permit: it is checked, rebuilt, and signed only if it passes and the payer holds the permit's amount in USDC on
+     * Base with at least that allowance to Permit2 (otherwise RectaCheckError `fee_balance` / `fee_allowance`, nothing
+     * signed; see `feeApproval`); then it is stored and the answer carries the artifact. With `dryRun` and collection on,
+     * it stops at the permit, before the artifact exists, and returns the typed data it would sign and the payer's funds:
+     * the transactions can only be inspected after the permit is signed. Pass the evaluation's `request` so a route that
+     * starts from USDC on Base reserves its own amount from the balance; `execute` checks the funds again either way.
      */
     async function authorizeFee(resultId, opts = {}) {
         const id = resultIdOf(resultId);
         const artifactPath = `${PATHS.evaluations}/${id}/execution-artifact`;
+        const reserve = opts.request === undefined ? 0n : routeReserveOf(opts.request);
         for (let attempt = 0; attempt < 2; attempt += 1) {
             const a = await call("GET", artifactPath);
             if (a.status === 200) {
-                const authorized = field(field(a.body, "fee_authorization"), "status") === "AUTHORIZED";
-                return { fee: { kind: authorized ? "ALREADY_AUTHORIZED" : "NOT_REQUIRED" }, artifact: field(a.body, "artifact") };
+                const fa = field(a.body, "fee_authorization");
+                if (field(fa, "status") === "AUTHORIZED") {
+                    // A permit stored earlier: its amount is the stored cap plus what it carries; the funds are checked again
+                    // before execute() sends anything.
+                    const cap = parseAtomic(field(fa, "max_fee_authorization_usdc_atomic"));
+                    const carried = parseAtomic(field(fa, "carried_usdc_atomic"));
+                    if (cap === undefined || carried === undefined)
+                        throw new RectaCheckError("fee_amount", "the stored fee authorization has no readable amount");
+                    feeAmounts.set(id, cap + carried);
+                    return { fee: { kind: "ALREADY_AUTHORIZED" }, artifact: field(a.body, "artifact") };
+                }
+                return { fee: { kind: "NOT_REQUIRED" }, artifact: field(a.body, "artifact") };
             }
             if (a.status !== 402 || field(a.body, "status") !== "SIGNATURE_REQUIRED")
                 throw new RectaHttpError(a.status, a.body);
@@ -102,10 +137,24 @@ export function createRectaClient(options) {
                 nowUnix: nowUnix(),
                 ...(typeof expiry === "string" && /^[0-9]+$/.test(expiry) ? { commercialExpiryUnix: BigInt(expiry) } : {}),
             });
-            if (opts.dryRun === true)
-                return { fee: { kind: "DRY_RUN", amountUsdcAtomic: checked.amount, typedData: checked.typedData }, artifact: undefined };
+            if (opts.dryRun === true) {
+                // A preview reports the funds; a reader that cannot read Base yields `funds: null` and the reason, never a signature.
+                let funds = null;
+                let fundsError;
+                try {
+                    funds = feeReadiness(await chain.readFeeFunds(signer.address), checked.amount, reserve);
+                }
+                catch (e) {
+                    fundsError = safeErrorText(e);
+                }
+                return { fee: { kind: "DRY_RUN", amountUsdcAtomic: checked.amount, typedData: checked.typedData, funds, ...(fundsError === undefined ? {} : { fundsError }) }, artifact: undefined };
+            }
+            // ASTRA T2: never sign a fee Recta could not collect (no USDC or no Permit2 allowance on Base).
+            assertFeeReady(feeReadiness(await chain.readFeeFunds(signer.address), checked.amount, reserve));
             const signature = await signer.signTypedData(checked.typedData);
-            const s = await call("POST", `${PATHS.evaluations}/${id}/fee-authorization`, { signature, amount_usdc_atomic: checked.amount.toString() });
+            const s = await call("POST", `${PATHS.evaluations}/${id}/fee-authorization${referral}`, { signature, amount_usdc_atomic: checked.amount.toString() });
+            if (s.status === 200 || s.status === 201)
+                feeAmounts.set(id, checked.amount);
             if (s.status === 200 || s.status === 201)
                 return { fee: { kind: "AUTHORIZED", amountUsdcAtomic: checked.amount, signature }, artifact: field(s.body, "artifact") };
             if (!(s.status === 409 && field(s.body, "reason_code") === "OFFER_STALE"))
@@ -120,6 +169,11 @@ export function createRectaClient(options) {
     }
     /** Step 3: checks, then sends the transactions in order, each mined successfully before the next. */
     async function execute(resultId, artifact, request) {
+        // The last moment before anything is sent: with a fee authorized for this decision, the payer must still hold it
+        // in USDC on Base (plus the transfer itself when it starts from Base USDC) with the Permit2 allowance for it.
+        const fee = feeAmounts.get(resultIdOf(resultId));
+        if (fee !== undefined)
+            assertFeeReady(feeReadiness(await chain.readFeeFunds(signer.address), fee, routeReserveOf(request)));
         const checked = await check(resultId, artifact, request);
         let approvalTxHash;
         for (const tx of checked.transactions) {
@@ -163,6 +217,7 @@ export function createRectaClient(options) {
         const debtId = field(offer, "debt_id");
         if (typeof debtId !== "string")
             throw new RectaCheckError("debt", "the offer has no debt_id");
+        assertFeeReady(feeReadiness(await chain.readFeeFunds(signer.address), checked.amount));
         const signature = await signer.signTypedData(checked.typedData);
         const a = await call("POST", PATHS.feeDebts, { debt_id: debtId, deadline_unix: checked.deadline.toString(), signature });
         if (a.status !== 200 && a.status !== 201)
@@ -178,7 +233,7 @@ export function createRectaClient(options) {
         const resultId = field(decision, "result_id");
         if (field(field(decision, "decision"), "state") !== "VERIFIED_POSITIVE" || typeof resultId !== "string")
             return { stage: "NO_ROUTE", decision };
-        const { fee, artifact } = await authorizeFee(resultId, opts.dryRun === true ? { dryRun: true } : {});
+        const { fee, artifact } = await authorizeFee(resultId, opts.dryRun === true ? { dryRun: true, request } : { request });
         if (fee.kind === "DRY_RUN")
             return { stage: "DRY_RUN", decision, fee };
         if (opts.dryRun === true)
@@ -186,5 +241,19 @@ export function createRectaClient(options) {
         const sent = await execute(resultId, artifact, request);
         return { stage: "REPORTED", decision, fee, ...sent, report: await report(resultId, sent.originTxHash, sent.approvalTxHash) };
     }
-    return { evaluate, authorizeFee, check, execute, report, ledger, payDebt, run, walletPolicy };
+    /** The payer's USDC balance and Permit2 allowance on Base against an amount (default: this client's permit limit). */
+    async function feeFunds(requiredUsdcAtomic = limits.maxPermitUsdcAtomic) {
+        return feeReadiness(await chain.readFeeFunds(signer.address), requiredUsdcAtomic);
+    }
+    /**
+     * The bounded approval `USDC.approve(Permit2, amount)` on Base, for the operator to send (`sendTransaction` is not
+     * called here: this client never approves by itself). The amount defaults to, and may not exceed, this client's
+     * permit limit, so the allowance never reaches past what one permit may authorize.
+     */
+    function feeApproval(amountUsdcAtomic = limits.maxPermitUsdcAtomic) {
+        if (amountUsdcAtomic > limits.maxPermitUsdcAtomic)
+            throw new RectaCheckError("fee_approval", `the approval ${amountUsdcAtomic} exceeds your permit limit ${limits.maxPermitUsdcAtomic}`);
+        return permit2ApprovalTransaction(amountUsdcAtomic);
+    }
+    return { evaluate, authorizeFee, check, execute, report, ledger, payDebt, run, walletPolicy, feeFunds, feeApproval };
 }

package/dist/constants.d.ts

@@ -6,6 +6,10 @@
  * Every value is checked equal to the Recta server's own configuration by a test in the Recta repository.
  */
 export declare const RECTA_ORIGIN = "https://api.recta.build";
+/** This package's version (equal to package.json, checked in CI). */
+export declare const CLIENT_VERSION = "0.1.4";
+/** Sent on every request so Recta can count real use of this package apart from other clients (no address, no key). */
+export declare const USER_AGENT = "recta-client/0.1.4";
 /** The fee: x402 `upto` on Base, a Permit2 `permitWitnessTransferFrom`. All lowercase. */
 export declare const FEE_CHAIN_ID = 8453;
 export declare const PERMIT2 = "0x000000000022d473030f116ddee9f6b43ac78ba3";

package/dist/constants.js

@@ -6,6 +6,10 @@
  * Every value is checked equal to the Recta server's own configuration by a test in the Recta repository.
  */
 export const RECTA_ORIGIN = "https://api.recta.build";
+/** This package's version (equal to package.json, checked in CI). */
+export const CLIENT_VERSION = "0.1.4";
+/** Sent on every request so Recta can count real use of this package apart from other clients (no address, no key). */
+export const USER_AGENT = `recta-client/${CLIENT_VERSION}`;
 /** The fee: x402 `upto` on Base, a Permit2 `permitWitnessTransferFrom`. All lowercase. */
 export const FEE_CHAIN_ID = 8453;
 export const PERMIT2 = "0x000000000022d473030f116ddee9f6b43ac78ba3";

package/dist/funds.d.ts

@@ -0,0 +1,88 @@
+import { type Hex } from "viem";
+/**
+ * Whether a fee permit can actually be collected (ASTRA T2). Signing a Permit2 permit is not enough: when Recta settles
+ * it, Permit2 pulls the fee with USDC's own `transferFrom`, which needs (1) the payer's USDC balance on Base and (2) the
+ * payer's ERC-20 allowance from USDC to Permit2. A permit signed without them lets the route execute and then the fee
+ * fail, which leaves a debt that blocks the next evaluation. This package therefore reads both before it signs a fee or
+ * debt permit and refuses when either is short. It never approves anything by itself.
+ */
+/** What the payer holds on Base, read at signing time (both in USDC atomic units, 6 decimals). */
+export interface FeeFunds {
+    readonly balanceUsdcAtomic: bigint;
+    readonly permit2AllowanceUsdcAtomic: bigint;
+}
+export interface FeeReadiness {
+    readonly ready: boolean;
+    /** The permit's amount: the most this fee can pull. */
+    readonly requiredUsdcAtomic: bigint;
+    /** USDC on Base the route itself will spend before the fee is pulled (a route that starts from Base USDC); the
+     *  balance must cover it plus the fee (Fable B-1 on recta #12). */
+    readonly reservedForRouteUsdcAtomic: bigint;
+    readonly balanceUsdcAtomic: bigint;
+    readonly permit2AllowanceUsdcAtomic: bigint;
+    /** What is short, if anything: `balance` (hold more USDC on Base), `allowance` (approve Permit2 for at least the amount). */
+    readonly missing: readonly ("balance" | "allowance")[];
+}
+export declare const ERC20_READ_ABI: readonly [{
+    readonly type: "function";
+    readonly name: "balanceOf";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "owner";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "allowance";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "owner";
+        readonly type: "address";
+    }, {
+        readonly name: "spender";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+}];
+/**
+ * The fee's amount against the payer's funds. `reservedForRouteUsdcAtomic`: USDC on Base the route will spend first
+ * (see `routeReserveOf`); the balance must cover it plus the fee. The allowance only needs to cover the fee: a route's
+ * own approval goes to the bridge, not to Permit2.
+ */
+export declare function feeReadiness(funds: FeeFunds, requiredUsdcAtomic: bigint, reservedForRouteUsdcAtomic?: bigint): FeeReadiness;
+/**
+ * USDC on Base that a route spends before Recta pulls its fee: the request's amount when the route starts from USDC on
+ * Base (the same balance pays both), otherwise 0. Throws when such an amount is not a plain decimal: fail closed.
+ */
+export declare function routeReserveOf(request: {
+    readonly source_network: string;
+    readonly source_asset: string;
+    readonly amount: string;
+}): bigint;
+/** A read error's text without what an RPC URL may carry (an API key in the path or query): viem's short message,
+ *  and any URL replaced (Fable M-2 on recta #12). */
+export declare function safeErrorText(e: unknown): string;
+/** Throws a RectaCheckError naming what is short and how to fix it; nothing has been signed when it throws. */
+export declare function assertFeeReady(r: FeeReadiness): void;
+/** The one transaction that lets Permit2 pull up to `amountUsdcAtomic` of USDC on Base: `USDC.approve(Permit2, amount)`. */
+export interface Permit2Approval {
+    readonly chainId: number;
+    readonly to: Hex;
+    readonly data: Hex;
+    readonly value: bigint;
+    readonly amountUsdcAtomic: bigint;
+}
+/**
+ * Builds the exact approval for the agent's operator to send with their own wallet. Bounded on purpose: it refuses 0
+ * and anything of 2^128 or more, so an "unlimited" approval (2^256 − 1, 2^160 − 1) cannot be built here. Approving
+ * replaces, not adds to, the current allowance; each collected fee lowers it, so approve again when a check reports
+ * `allowance` short.
+ */
+export declare function permit2ApprovalTransaction(amountUsdcAtomic: bigint): Permit2Approval;

package/dist/funds.js

@@ -0,0 +1,77 @@
+import { encodeFunctionData } from "viem";
+import { FEE_CHAIN_ID, PERMIT2, USDC_BASE } from "./constants.js";
+import { RectaCheckError } from "./errors.js";
+export const ERC20_READ_ABI = [
+    { type: "function", name: "balanceOf", stateMutability: "view", inputs: [{ name: "owner", type: "address" }], outputs: [{ name: "", type: "uint256" }] },
+    { type: "function", name: "allowance", stateMutability: "view", inputs: [{ name: "owner", type: "address" }, { name: "spender", type: "address" }], outputs: [{ name: "", type: "uint256" }] },
+];
+const APPROVE_ABI = [
+    { type: "function", name: "approve", stateMutability: "nonpayable", inputs: [{ name: "spender", type: "address" }, { name: "amount", type: "uint256" }], outputs: [{ name: "", type: "bool" }] },
+];
+/**
+ * The fee's amount against the payer's funds. `reservedForRouteUsdcAtomic`: USDC on Base the route will spend first
+ * (see `routeReserveOf`); the balance must cover it plus the fee. The allowance only needs to cover the fee: a route's
+ * own approval goes to the bridge, not to Permit2.
+ */
+export function feeReadiness(funds, requiredUsdcAtomic, reservedForRouteUsdcAtomic = 0n) {
+    const missing = [];
+    if (funds.balanceUsdcAtomic < requiredUsdcAtomic + reservedForRouteUsdcAtomic)
+        missing.push("balance");
+    if (funds.permit2AllowanceUsdcAtomic < requiredUsdcAtomic)
+        missing.push("allowance");
+    return { ready: missing.length === 0, requiredUsdcAtomic, reservedForRouteUsdcAtomic, balanceUsdcAtomic: funds.balanceUsdcAtomic, permit2AllowanceUsdcAtomic: funds.permit2AllowanceUsdcAtomic, missing };
+}
+const DECIMAL_USDC = /^(0|[1-9][0-9]{0,17})(\.[0-9]{1,6})?$/;
+/**
+ * USDC on Base that a route spends before Recta pulls its fee: the request's amount when the route starts from USDC on
+ * Base (the same balance pays both), otherwise 0. Throws when such an amount is not a plain decimal: fail closed.
+ */
+export function routeReserveOf(request) {
+    if (request.source_network !== "base" || request.source_asset.toUpperCase() !== "USDC")
+        return 0n;
+    if (!DECIMAL_USDC.test(request.amount))
+        throw new RectaCheckError("amount", "the request's amount is not a decimal USDC amount");
+    const [whole, frac = ""] = request.amount.split(".");
+    return BigInt(whole) * 1000000n + BigInt(frac.padEnd(6, "0"));
+}
+/** A read error's text without what an RPC URL may carry (an API key in the path or query): viem's short message,
+ *  and any URL replaced (Fable M-2 on recta #12). */
+export function safeErrorText(e) {
+    const short = typeof e === "object" && e !== null && typeof e.shortMessage === "string" ? e.shortMessage : e instanceof Error ? e.message : String(e);
+    return short.replace(/[a-z][a-z0-9+.-]*:\/\/[^\s"'<>]+/gi, "<url>").split("\n")[0].slice(0, 300);
+}
+const usdc = (atomic) => {
+    const whole = atomic / 1000000n;
+    const frac = (atomic % 1000000n).toString().padStart(6, "0").replace(/0+$/, "");
+    return frac === "" ? whole.toString() : `${whole}.${frac}`;
+};
+/** Throws a RectaCheckError naming what is short and how to fix it; nothing has been signed when it throws. */
+export function assertFeeReady(r) {
+    if (r.ready)
+        return;
+    const parts = [];
+    if (r.missing.includes("balance"))
+        parts.push(`hold at least ${usdc(r.requiredUsdcAtomic + r.reservedForRouteUsdcAtomic)} USDC on Base (now ${usdc(r.balanceUsdcAtomic)}${r.reservedForRouteUsdcAtomic > 0n ? `; ${usdc(r.reservedForRouteUsdcAtomic)} of it is the transfer itself, which leaves Base first` : ""})`);
+    if (r.missing.includes("allowance"))
+        parts.push(`approve Permit2 (${PERMIT2}) to spend at least ${usdc(r.requiredUsdcAtomic)} USDC on Base (now ${usdc(r.permit2AllowanceUsdcAtomic)}); permit2ApprovalTransaction(amount) builds that exact, bounded approval for you to send`);
+    throw new RectaCheckError(r.missing.includes("allowance") ? "fee_allowance" : "fee_balance", `Recta could not collect this fee: ${parts.join("; ")}. Nothing was signed.`);
+}
+/**
+ * Builds the exact approval for the agent's operator to send with their own wallet. Bounded on purpose: it refuses 0
+ * and anything of 2^128 or more, so an "unlimited" approval (2^256 − 1, 2^160 − 1) cannot be built here. Approving
+ * replaces, not adds to, the current allowance; each collected fee lowers it, so approve again when a check reports
+ * `allowance` short.
+ */
+export function permit2ApprovalTransaction(amountUsdcAtomic) {
+    if (amountUsdcAtomic <= 0n)
+        throw new RectaCheckError("fee_approval", "the approval must be more than 0");
+    if (amountUsdcAtomic >= 2n ** 128n)
+        throw new RectaCheckError("fee_approval", "refusing an unlimited approval: approve a bounded amount");
+    return {
+        chainId: FEE_CHAIN_ID,
+        to: USDC_BASE,
+        data: encodeFunctionData({ abi: APPROVE_ABI, functionName: "approve", args: [PERMIT2, amountUsdcAtomic] }),
+        value: 0n,
+        amountUsdcAtomic,
+    };
+}

package/dist/index.d.ts

@@ -1,5 +1,6 @@
-export { createRectaClient, signedRequestMessage, type RectaClient, type RectaClientOptions, type FeeOutcome } from "./client.js";
+export { createRectaClient, signedRequestMessage, referrerQuery, type RectaClient, type RectaClientOptions, type FeeOutcome } from "./client.js";
 export { checkFeePermit, type FeePermitLimits } from "./fee.js";
+export { feeReadiness, assertFeeReady, permit2ApprovalTransaction, routeReserveOf, safeErrorText, ERC20_READ_ABI, type FeeFunds, type FeeReadiness, type Permit2Approval } from "./funds.js";
 export { checkExecutionArtifact, pinnedRouteOf, type CheckedArtifact, type EvaluationRequestView, type ArtifactLimits } from "./artifact.js";
 export { PINNED_ROUTES, type PinnedRoute } from "./pinned-routes.js";
 export { parseWalletPolicy, type WalletPolicy, type WalletPolicyNetwork } from "./policy.js";

package/dist/index.js

@@ -1,5 +1,6 @@
-export { createRectaClient, signedRequestMessage } from "./client.js";
+export { createRectaClient, signedRequestMessage, referrerQuery } from "./client.js";
 export { checkFeePermit } from "./fee.js";
+export { feeReadiness, assertFeeReady, permit2ApprovalTransaction, routeReserveOf, safeErrorText, ERC20_READ_ABI } from "./funds.js";
 export { checkExecutionArtifact, pinnedRouteOf } from "./artifact.js";
 export { PINNED_ROUTES } from "./pinned-routes.js";
 export { parseWalletPolicy } from "./policy.js";

package/dist/signer.d.ts

@@ -1,4 +1,5 @@
 import type { Account, Chain, Hex, PublicClient, Transport, TransactionSerializable, WalletClient } from "viem";
+import { type FeeFunds } from "./funds.js";
 /** One EIP-1559 transaction of an execution artifact, as this package asks a signer to send it. */
 export interface RectaTransaction {
     readonly chainId: number;
@@ -34,10 +35,16 @@ export interface RectaSigner {
     /** 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. */
+/** Read access to the chains (the agent's own RPC): receipts, and the payer's USDC on Base before a fee is signed. */
 export interface RectaChainReader {
     /** Waits until the transaction is mined and returns whether it succeeded. */
     waitForSuccess(chainId: number, hash: Hex): Promise<boolean>;
+    /**
+     * The payer's USDC balance on Base and its ERC-20 allowance to Permit2 (ASTRA T2): read before every fee or debt
+     * permit is signed, which is refused when either is below the permit's amount. A reader that cannot answer (no Base
+     * RPC) must throw: the permit is then not signed.
+     */
+    readFeeFunds(owner: Hex): Promise<FeeFunds>;
 }
 /** A RectaSigner from a viem account and one wallet client per chain. */
 export declare function viemSigner(args: {
@@ -100,5 +107,5 @@ 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. */
+/** A RectaChainReader from one viem public client per chain (`publicClientFor(8453)` reads the fee funds on Base). */
 export declare function viemChainReader(publicClientFor: (chainId: number) => PublicClient): RectaChainReader;

package/dist/signer.js

@@ -1,4 +1,6 @@
 import { toAccount } from "viem/accounts";
+import { FEE_CHAIN_ID, PERMIT2, USDC_BASE } from "./constants.js";
+import { ERC20_READ_ABI, safeErrorText } from "./funds.js";
 /** A RectaSigner from a viem account and one wallet client per chain. */
 export function viemSigner(args) {
     const { account } = args;
@@ -85,9 +87,26 @@ export function cdpSigner(args) {
         },
     };
 }
-/** A RectaChainReader from one viem public client per chain. */
+/** A RectaChainReader from one viem public client per chain (`publicClientFor(8453)` reads the fee funds on Base). */
 export function viemChainReader(publicClientFor) {
     return {
         waitForSuccess: async (chainId, hash) => (await publicClientFor(chainId).waitForTransactionReceipt({ hash })).status === "success",
+        readFeeFunds: async (owner) => {
+            const base = publicClientFor(FEE_CHAIN_ID);
+            const chainId = await base.getChainId().catch((e) => { throw new Error(`reading Base's chain id failed: ${safeErrorText(e)}`); });
+            if (chainId !== FEE_CHAIN_ID)
+                throw new Error(`publicClientFor(${FEE_CHAIN_ID}) returned a client on chain ${chainId}`);
+            try {
+                const [balanceUsdcAtomic, permit2AllowanceUsdcAtomic] = await Promise.all([
+                    base.readContract({ address: USDC_BASE, abi: ERC20_READ_ABI, functionName: "balanceOf", args: [owner] }),
+                    base.readContract({ address: USDC_BASE, abi: ERC20_READ_ABI, functionName: "allowance", args: [owner, PERMIT2] }),
+                ]);
+                return { balanceUsdcAtomic, permit2AllowanceUsdcAtomic };
+            }
+            catch (e) {
+                // viem's full message names the RPC URL, which may carry an API key: never pass it on (Fable M-2).
+                throw new Error(`reading USDC on Base failed: ${safeErrorText(e)}`);
+            }
+        },
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@recta/client",
-  "version": "0.1.1",
+  "version": "0.1.4",
   "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)",