@recta/client 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Recta
+
+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

@@ -1,3 +1,139 @@
-# Temporary Holding Version
+# @recta/client
 
-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.
+A client for [Recta](https://api.recta.build/llms.txt): before your agent moves stablecoins between blockchains, Recta
+finds a cheaper route it can prove against the route you would use anyway, and charges exactly 5 % of the saving it
+verifies on chain after you execute. No saving, no charge.
+
+This package runs Recta's four steps with the wallet your agent already has:
+
+```
+evaluate → authorizeFee → execute → report
+```
+
+It never receives a key. Before it signs or sends anything it checks it locally, and those checks cannot be turned off.
+
+## Install
+
+```
+npm install @recta/client viem
+```
+
+`viem` (>= 2.30, < 3) is the only dependency, and you choose its version.
+
+## Use
+
+```ts
+import { createRectaClient, viemSigner, viemChainReader } from "@recta/client";
+
+const recta = createRectaClient({
+  signer: viemSigner({ account, walletClientFor: (chainId) => walletClients[chainId] }),
+  chain: viemChainReader((chainId) => publicClients[chainId]),
+  limits: {
+    maxPermitUsdcAtomic: 5_000_000n, // never authorize more than 5 USDC in one fee permit
+    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
+  },
+});
+
+// Dry run: evaluates and checks, signs no permit, sends no transaction.
+const preview = await recta.run(request, { dryRun: true });
+
+// The whole flow.
+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`.
+
+Your account must be an EOA: Recta's signed requests are EIP-191 signatures recovered to the sender's address.
+
+### Coinbase CDP accounts
+
+A [Coinbase CDP](https://docs.cdp.coinbase.com) EVM server account (an EOA whose key stays in CDP) works through
+`cdpSigner`. This package does not depend on the CDP SDK:
+
+```ts
+import { CdpClient } from "@coinbase/cdp-sdk";
+import { createRectaClient, cdpSigner, viemChainReader } from "@recta/client";
+
+const cdp = new CdpClient();
+const account = await cdp.evm.getOrCreateAccount({ name: "my-agent" });
+
+const recta = createRectaClient({
+  signer: cdpSigner({ account }),
+  chain: viemChainReader((chainId) => publicClients[chainId]),
+  limits: { maxPermitUsdcAtomic: 5_000_000n, maxNativeValueWei: 10n ** 15n, minOutputBps: 9900 },
+});
+```
+
+CDP signs Recta's requests and the fee permit. On Ethereum, Base, Arbitrum, Optimism, Polygon and Avalanche, CDP also
+sends each route transaction once this package has checked it. On any other chain, pass `walletClientFor` as well:
+CDP then signs the transaction and your RPC sends it.
+
+To limit the account to Recta's contracts at CDP's side too, apply the
+[CDP Policy Engine policy Recta serves](https://api.recta.build/v1/golden-corridor/wallet-policy/cdp). CDP refuses
+anything that policy does not allow, and it allows sending only on those six chains: with the policy applied, a route
+on any other chain is refused by CDP unless you add your own rule for it.
+
+The saving is measured against `baseline_provider`: the route your agent would use without Recta. Declare the one it
+really uses. If your agent bridges through LI.FI (its public API or an aggregator built on it), declare `lifi`
+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.
+
+## 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,
+Recta's fee recipient and Recta's facilitator. Recta's wallet policy is read live and must agree with them; if it does
+not, nothing is signed.
+
+**The fee permit** (Permit2 `PermitWitnessTransferFrom` on Base) is signed only if the domain is Permit2 on Base, the
+types are exactly Recta's, the spender is the `upto` proxy, the token is USDC, `witness.to` is Recta's recipient,
+`witness.facilitator` is Recta's sender, the amount is the decision's cap plus what it carries from earlier unpaid fees
+and is within `maxPermitUsdcAtomic`, and the deadline is in the future and no later than the commercial expiry plus 37
+days. The typed data signed is rebuilt from those checked fields, not taken as the server sent it. Recta settles exactly
+5 % of the verified saving, never more than the permit.
+
+**The fee permit is signed before the route can be reviewed.** Recta hands out a decision's transactions only once its
+fee authorization is stored, so the permit comes first. Its ceiling (`max_fee_authorization` plus earlier unpaid fees,
+never more than `maxPermitUsdcAtomic`) is the most you can owe for a decision; Recta still settles only 5 % of a saving
+it verifies on chain, so a route you refuse below and never execute owes nothing.
+
+**Every route transaction** is checked against a route table pinned in this package, generated from Recta's own server
+configuration: for each EVM corridor, the source and destination tokens and the only contracts a route may approve
+and call, with the destination each call must name. The wallet policy Recta serves never adds to it. A transaction is
+sent only if: it is EIP-1559 with an empty access list, on the source chain, from your signer, within your request's
+gas price ceilings; an approval is `approve` of the pinned source token, for exactly the transfer amount, to the pinned
+contract the execution then calls; the execution decodes as that contract's own call (Across `deposit`, CCTP V2
+`depositForBurn` or LayerZero OFT/Stargate `send`) naming your sender, your recipient, the source token and the exact
+amount, the pinned destination (Across chain id and output token, with no message; CCTP domain, completable by
+anyone; LayerZero endpoint id, with no executor options, compose message or OFT command), and a guaranteed output of at least `minOutputBps` of the
+amount (Across `outputAmount`, CCTP amount minus `maxFee`, LayerZero `minAmountLD`); native value is allowed only as
+the declared messaging fee, within `maxNativeValueWei`.
+
+`report` returns `stage`: `ACCRUED` (Recta verified and recorded the saving), `PENDING` (report again later) or
+`REFUSED` (Recta will not accrue this execution; see `body.reason_code`).
+
+**Debts.** If Recta refuses a new evaluation because an earlier fee could not be collected, `evaluate` throws
+`RectaDebtError` with the offer. The package never signs a debt by itself: call `payDebt(offer)` if you agree (same
+checks, exact amount).
+
+## Limits of this version
+
+- EVM sources and EVM recipients only. Solana, Tron and Bitcoin routes, Relay and deBridge are refused.
+- A corridor or contract Recta adds after this release is refused until a new release pins it.
+- Smart accounts (EIP-1271) cannot sign Recta's requests.
+
+## Provenance
+
+Every release is published from [RectaBuild/recta](https://github.com/RectaBuild/recta) by GitHub Actions with npm
+provenance and no long-lived token. Check it before you trust a version:
+
+```
+npm audit signatures
+```
+
+## License
+
+MIT

package/dist/artifact.d.ts

@@ -0,0 +1,55 @@
+import { type PinnedRoute } from "./pinned-routes.js";
+import type { RectaTransaction } from "./signer.js";
+/** The fields of the evaluation request this package checks the artifact against. */
+export interface EvaluationRequestView {
+    readonly source_network: string;
+    readonly source_asset: string;
+    readonly destination_network: string;
+    readonly destination_asset?: string;
+    readonly amount: string;
+    readonly sender: string;
+    readonly recipient: string;
+    readonly execution_authority?: {
+        readonly source_max_fee_per_gas_wei?: string;
+        readonly source_max_priority_fee_per_gas_wei?: string;
+    };
+}
+export interface ArtifactLimits {
+    readonly signer: string;
+    readonly nowUnix: bigint;
+    /** The most native value (wei) this agent agrees to attach to one transaction (LayerZero-based routes pay their
+     *  messaging fee this way; Across and CCTP attach none). */
+    readonly maxNativeValueWei: bigint;
+    /** The least the recipient must be guaranteed to receive, in basis points of the amount sent (e.g. 9950 = 99.5 %):
+     *  Across's `outputAmount`, CCTP's amount minus its `maxFee`, LayerZero's `minAmountLD`. Required. */
+    readonly minOutputBps: number;
+}
+export interface CheckedArtifact {
+    readonly resultId: string;
+    readonly transactions: readonly (RectaTransaction & {
+        readonly role: "APPROVAL" | "EXECUTION";
+    })[];
+}
+/** The pinned route of a request's corridor, or a refusal. */
+export declare function pinnedRouteOf(request: Pick<EvaluationRequestView, "source_network" | "source_asset" | "destination_network" | "destination_asset">): PinnedRoute;
+/**
+ * Checks every transaction of an execution artifact before any is sent, against the request the agent made and the
+ * route table pinned in this package (generated from Recta's server configuration; a served wallet policy never adds
+ * to it):
+ *  - the artifact is Recta's, of this decision, and not expired; approvals come first and there is exactly one execution;
+ *  - every transaction is EIP-1559 with an empty access list, on the source chain, from the signer, within the request's
+ *    own gas price ceilings;
+ *  - an approval is `approve` of the pinned source token to a pinned contract of the corridor, for exactly the transfer
+ *    amount, and its spender is the contract the execution calls;
+ *  - the execution calls a pinned contract of the corridor and decodes as that contract's protocol call (Across
+ *    `deposit`, CCTP V2 `depositForBurn`, LayerZero OFT/Stargate `send`) naming the request's sender, recipient, source
+ *    token and exact amount, the pinned destination (Across chain id and output token, CCTP domain with any caller, OFT
+ *    endpoint id), and a guaranteed output of at least `minOutputBps` of the amount; its native value is the one the
+ *    call declares, within the agent's limit.
+ * Anything else is refused.
+ */
+export declare function checkExecutionArtifact(artifact: unknown, args: {
+    readonly resultId: string;
+    readonly request: EvaluationRequestView;
+    readonly limits: ArtifactLimits;
+}): CheckedArtifact;

package/dist/artifact.js

@@ -0,0 +1,207 @@
+import { decodeFunctionData, padHex, parseAbi, parseUnits } from "viem";
+import { EXECUTION_ARTIFACT_SCHEMA } from "./constants.js";
+import { RectaCheckError } from "./errors.js";
+import { PINNED_ROUTES } from "./pinned-routes.js";
+const APPROVE_ABI = parseAbi(["function approve(address spender, uint256 amount)"]);
+const ACROSS_DEPOSIT_ABI = parseAbi([
+    "function deposit(bytes32 depositor, bytes32 recipient, bytes32 inputToken, bytes32 outputToken, uint256 inputAmount, uint256 outputAmount, uint256 destinationChainId, bytes32 exclusiveRelayer, uint32 quoteTimestamp, uint32 fillDeadline, uint32 exclusivityParameter, bytes message)",
+]);
+const CCTP_DEPOSIT_FOR_BURN_ABI = parseAbi([
+    "function depositForBurn(uint256 amount, uint32 destinationDomain, bytes32 mintRecipient, address burnToken, bytes32 destinationCaller, uint256 maxFee, uint32 minFinalityThreshold)",
+]);
+const OFT_SEND_ABI = parseAbi([
+    "struct SendParam { uint32 dstEid; bytes32 to; uint256 amountLD; uint256 minAmountLD; bytes extraOptions; bytes composeMsg; bytes oftCmd; }",
+    "struct MessagingFee { uint256 nativeFee; uint256 lzTokenFee; }",
+    "function send(SendParam _sendParam, MessagingFee _fee, address _refundAddress) payable",
+]);
+const UINT = /^(0|[1-9][0-9]{0,77})$/;
+const ADDRESS = /^0x[0-9a-fA-F]{40}$/;
+const ZERO_WORD = `0x${"0".repeat(64)}`;
+const word = (a) => padHex(a.toLowerCase(), { size: 32 }).toLowerCase();
+const same = (a, b) => typeof a === "string" && a.toLowerCase() === b.toLowerCase();
+/** The pinned route of a request's corridor, or a refusal. */
+export function pinnedRouteOf(request) {
+    const key = `${request.source_network}:${request.source_asset}>${request.destination_network}:${request.destination_asset ?? request.source_asset}`;
+    const route = Object.hasOwn(PINNED_ROUTES, key) ? PINNED_ROUTES[key] : undefined;
+    if (route === undefined)
+        throw new RectaCheckError("corridor", `${key} is not an EVM corridor this release of the package knows`);
+    return route;
+}
+/**
+ * Checks every transaction of an execution artifact before any is sent, against the request the agent made and the
+ * route table pinned in this package (generated from Recta's server configuration; a served wallet policy never adds
+ * to it):
+ *  - the artifact is Recta's, of this decision, and not expired; approvals come first and there is exactly one execution;
+ *  - every transaction is EIP-1559 with an empty access list, on the source chain, from the signer, within the request's
+ *    own gas price ceilings;
+ *  - an approval is `approve` of the pinned source token to a pinned contract of the corridor, for exactly the transfer
+ *    amount, and its spender is the contract the execution calls;
+ *  - the execution calls a pinned contract of the corridor and decodes as that contract's protocol call (Across
+ *    `deposit`, CCTP V2 `depositForBurn`, LayerZero OFT/Stargate `send`) naming the request's sender, recipient, source
+ *    token and exact amount, the pinned destination (Across chain id and output token, CCTP domain with any caller, OFT
+ *    endpoint id), and a guaranteed output of at least `minOutputBps` of the amount; its native value is the one the
+ *    call declares, within the agent's limit.
+ * Anything else is refused.
+ */
+export function checkExecutionArtifact(artifact, args) {
+    const fail = (check, message) => { throw new RectaCheckError(check, message); };
+    const { request, limits } = args;
+    if (!Number.isInteger(limits.minOutputBps) || limits.minOutputBps < 1 || limits.minOutputBps > 10_000)
+        fail("limits", "minOutputBps must be an integer from 1 to 10000");
+    const a = typeof artifact === "object" && artifact !== null ? artifact : fail("artifact", "the artifact is not an object");
+    if (a["schema"] !== EXECUTION_ARTIFACT_SCHEMA)
+        fail("artifact", `the artifact schema is ${String(a["schema"])}, not ${EXECUTION_ARTIFACT_SCHEMA}`);
+    if (a["result_id"] !== args.resultId)
+        fail("artifact", "the artifact belongs to another decision");
+    const expiry = typeof a["commercial_expiry_unix"] === "string" && UINT.test(a["commercial_expiry_unix"]) ? BigInt(a["commercial_expiry_unix"]) : fail("artifact", "commercial_expiry_unix is not an integer");
+    if (expiry <= limits.nowUnix)
+        fail("artifact_expired", "the decision's commercial expiry has passed");
+    const signer = limits.signer.toLowerCase();
+    if (!same(request.sender, signer))
+        fail("sender", "the request's sender is not the signer");
+    if (!ADDRESS.test(request.recipient))
+        fail("recipient", "this version only checks EVM recipients (0x addresses)");
+    const route = pinnedRouteOf(request);
+    const amount = parseUnits(request.amount, route.source_decimals);
+    const minimum = { amount, bps: BigInt(limits.minOutputBps), route };
+    const maxFee = request.execution_authority?.source_max_fee_per_gas_wei;
+    const maxPriority = request.execution_authority?.source_max_priority_fee_per_gas_wei;
+    const raw = Array.isArray(a["transactions"]) ? a["transactions"] : fail("artifact", "transactions is not a list");
+    const out = [];
+    let executionTo;
+    const approvalSpenders = [];
+    for (const [i, item] of raw.entries()) {
+        const t = typeof item === "object" && item !== null ? item : fail("transaction", `transaction ${i} is not an object`);
+        if (t["role"] !== "APPROVAL" && t["role"] !== "EXECUTION")
+            fail("transaction", `transaction ${i} has role ${String(t["role"])}`);
+        const role = t["role"];
+        if (executionTo !== undefined)
+            fail("transaction_order", role === "APPROVAL" ? "an approval follows the execution" : "more than one execution");
+        if (t["transaction_type"] !== "EIP1559" || !Array.isArray(t["access_list"]) || t["access_list"].length !== 0)
+            fail("transaction_type", `transaction ${i} is not EIP-1559 with an empty access list`);
+        const n = (k) => (typeof t[k] === "string" && UINT.test(t[k]) ? BigInt(t[k]) : fail("transaction", `transaction ${i}: ${k} is not an integer`));
+        if (n("chain_id") !== BigInt(route.source_chain_id))
+            fail("transaction_chain", `transaction ${i} is not on ${request.source_network} (${route.source_chain_id})`);
+        if (!same(t["from"], signer))
+            fail("transaction_from", `transaction ${i} is not from the signer`);
+        const to = typeof t["to"] === "string" && ADDRESS.test(t["to"]) ? t["to"].toLowerCase() : fail("transaction", `transaction ${i}: to is not an address`);
+        const data = typeof t["data"] === "string" && /^0x([0-9a-fA-F]{2})*$/.test(t["data"]) ? t["data"] : fail("transaction", `transaction ${i}: data is not hex`);
+        const value = n("value_wei");
+        const fee = n("max_fee_per_gas_wei");
+        const priority = n("max_priority_fee_per_gas_wei");
+        if (maxFee !== undefined && fee > BigInt(maxFee))
+            fail("transaction_gas_price", `transaction ${i} pays more per gas than the request allows`);
+        if (maxPriority !== undefined && priority > BigInt(maxPriority))
+            fail("transaction_gas_price", `transaction ${i} tips more per gas than the request allows`);
+        if (role === "APPROVAL") {
+            if (to !== route.source_token || value !== 0n)
+                fail("approval", `transaction ${i} is not an approval on the source token`);
+            const d = (() => { try {
+                return decodeFunctionData({ abi: APPROVE_ABI, data });
+            }
+            catch {
+                return fail("approval", `transaction ${i} is not approve(spender, amount)`);
+            } })();
+            const spender = d.args[0].toLowerCase();
+            if (!route.contracts.some((c) => c.address === spender))
+                fail("approval_spender", `transaction ${i} approves ${spender}, which is not a pinned contract of this corridor`);
+            if (d.args[1] !== amount)
+                fail("approval_amount", `transaction ${i} approves ${d.args[1]}, not exactly the transfer amount ${amount}`);
+            approvalSpenders.push(spender);
+        }
+        else {
+            const candidates = route.contracts.filter((c) => c.address === to);
+            if (candidates.length === 0)
+                fail("execution_target", `the execution calls ${to}, which is not a pinned contract of this corridor`);
+            checkExecutionCall(data, value, candidates, { token: route.source_token, sender: signer, recipient: request.recipient, maxNativeValueWei: limits.maxNativeValueWei, minimum });
+            executionTo = to;
+        }
+        out.push({ role, chainId: route.source_chain_id, to: to, data, value, gas: n("gas_limit"), maxFeePerGas: fee, maxPriorityFeePerGas: priority });
+    }
+    if (executionTo === undefined)
+        fail("transaction_order", "the artifact has no execution");
+    if (approvalSpenders.some((s) => s !== executionTo))
+        fail("approval_spender", "an approval's spender is not the contract the execution calls");
+    return { resultId: args.resultId, transactions: out };
+}
+/** The least output allowed, in output-token units: ⌈amount · bps / 10 000⌉ scaled from source to output decimals. */
+function minimumOutput(m, inOutputUnits) {
+    const inSource = (m.amount * m.bps + 9999n) / 10000n;
+    if (!inOutputUnits)
+        return inSource;
+    const d = m.route.output_decimals - m.route.source_decimals;
+    return d >= 0 ? inSource * 10n ** BigInt(d) : (inSource + 10n ** BigInt(-d) - 1n) / 10n ** BigInt(-d);
+}
+function checkExecutionCall(data, value, candidates, e) {
+    const fail = (check, message) => { throw new RectaCheckError(check, message); };
+    const amount = e.minimum.amount;
+    const destinations = (protocol) => candidates.filter((c) => c.protocol === protocol).map((c) => c.destination_id);
+    const decode = (abi) => { try {
+        return decodeFunctionData({ abi: abi, data });
+    }
+    catch {
+        return undefined;
+    } };
+    const across = destinations("across").length > 0 ? decode(ACROSS_DEPOSIT_ABI) : undefined;
+    if (across !== undefined) {
+        const [depositor, recipient, inputToken, outputToken, inputAmount, outputAmount, destinationChainId, , , , , message] = across.args;
+        if (depositor.toLowerCase() !== word(e.sender) || recipient.toLowerCase() !== word(e.recipient))
+            fail("execution_parties", "the Across deposit does not name the request's sender and recipient");
+        if (inputToken.toLowerCase() !== word(e.token) || inputAmount !== amount)
+            fail("execution_amount", "the Across deposit is not the request's token and amount");
+        if (!destinations("across").some((id) => BigInt(id) === destinationChainId))
+            fail("execution_destination", `the Across deposit goes to chain ${destinationChainId}, not the request's destination`);
+        if (outputToken.toLowerCase() !== word(e.minimum.route.output_token))
+            fail("execution_destination", "the Across deposit's output token is not the request's destination token");
+        if (message !== "0x")
+            fail("execution_destination", "the Across deposit carries a message (the recipient would run it as a handler)");
+        if (outputAmount < minimumOutput(e.minimum, true))
+            fail("execution_min_output", `the Across deposit guarantees ${outputAmount}, less than your minimum`);
+        if (value !== 0n)
+            fail("execution_value", "the Across deposit attaches native value");
+        return;
+    }
+    const cctp = destinations("cctp_v2").length > 0 ? decode(CCTP_DEPOSIT_FOR_BURN_ABI) : undefined;
+    if (cctp !== undefined) {
+        const [burnAmount, domain, mintRecipient, burnToken, destinationCaller, maxFee] = cctp.args;
+        if (mintRecipient.toLowerCase() !== word(e.recipient))
+            fail("execution_parties", "the CCTP burn does not mint to the request's recipient");
+        if (!same(burnToken, e.token) || burnAmount !== amount)
+            fail("execution_amount", "the CCTP burn is not the request's token and amount");
+        if (!destinations("cctp_v2").includes(domain))
+            fail("execution_destination", `the CCTP burn goes to domain ${domain}, not the request's destination`);
+        if (destinationCaller.toLowerCase() !== ZERO_WORD)
+            fail("execution_destination", "the CCTP burn restricts who may complete it");
+        if (maxFee >= burnAmount || burnAmount - maxFee < minimumOutput(e.minimum, true))
+            fail("execution_min_output", "the CCTP burn's max fee leaves less than your minimum");
+        if (value !== 0n)
+            fail("execution_value", "the CCTP burn attaches native value");
+        return;
+    }
+    const oft = destinations("oft").length > 0 ? decode(OFT_SEND_ABI) : undefined;
+    if (oft !== undefined) {
+        const [param, fee, refund] = oft.args;
+        if (param.to.toLowerCase() !== word(e.recipient) || !same(refund, e.sender))
+            fail("execution_parties", "the OFT send does not name the request's recipient and refund the sender");
+        if (param.amountLD !== amount)
+            fail("execution_amount", "the OFT send is not the request's amount");
+        if (!destinations("oft").includes(param.dstEid))
+            fail("execution_destination", `the OFT send goes to endpoint ${param.dstEid}, not the request's destination`);
+        // Recta's own OFT routes are plain sends: no executor options (which could add a native drop to another address),
+        // no compose message, no OFT command.
+        if (param.composeMsg !== "0x")
+            fail("execution_destination", "the OFT send carries a compose message");
+        if (param.extraOptions !== "0x")
+            fail("execution_destination", "the OFT send carries executor options");
+        if (param.oftCmd !== "0x")
+            fail("execution_destination", "the OFT send carries an OFT command");
+        if (param.minAmountLD < minimumOutput(e.minimum, false))
+            fail("execution_min_output", `the OFT send guarantees ${param.minAmountLD}, less than your minimum`);
+        if (fee.lzTokenFee !== 0n || fee.nativeFee !== value)
+            fail("execution_value", "the OFT send's native fee is not the value it attaches");
+        if (value > e.maxNativeValueWei)
+            fail("execution_value_limit", `the OFT send attaches ${value} wei, more than your limit ${e.maxNativeValueWei}`);
+        return;
+    }
+    fail("execution_call", "the execution is not the reviewed call of this contract (Across deposit, CCTP V2 depositForBurn, OFT send)");
+}

package/dist/client.d.ts

@@ -0,0 +1,119 @@
+import { type Hex } from "viem";
+import { type CheckedArtifact, type EvaluationRequestView } from "./artifact.js";
+import type { RectaChainReader, RectaSigner, RectaTypedData } from "./signer.js";
+export interface RectaClientOptions {
+    readonly signer: RectaSigner;
+    readonly chain: RectaChainReader;
+    readonly limits: {
+        /** The most one fee permit may authorize, in USDC atomic units (6 decimals): e.g. 5_000_000n for 5 USDC. */
+        readonly maxPermitUsdcAtomic: bigint;
+        /** The most native value (wei) one route transaction may attach (LayerZero messaging fees). */
+        readonly maxNativeValueWei: bigint;
+        /** The least the recipient must be guaranteed, in basis points of the amount sent (e.g. 9950 = 99.5 %). */
+        readonly minOutputBps: number;
+    };
+    /** Defaults to the global fetch. */
+    readonly fetch?: typeof fetch;
+    /** Milliseconds since the epoch; defaults to Date.now. */
+    readonly now?: () => number;
+}
+/** The text a sender signs for one request (EIP-191), exactly as Recta's server rebuilds it. */
+export declare function signedRequestMessage(f: {
+    readonly method: string;
+    readonly path: string;
+    readonly idempotencyKey: string;
+    readonly bodyKeccak256: string;
+    readonly issuedAt: number;
+}): string;
+export type FeeOutcome = {
+    readonly kind: "NOT_REQUIRED";
+} | {
+    readonly kind: "ALREADY_AUTHORIZED";
+} | {
+    readonly kind: "AUTHORIZED";
+    readonly amountUsdcAtomic: bigint;
+    readonly signature: Hex;
+} | {
+    readonly kind: "DRY_RUN";
+    readonly amountUsdcAtomic: bigint;
+    readonly typedData: RectaTypedData;
+};
+/**
+ * Recta's flow for an agent that holds its own EOA: evaluate → authorizeFee → execute → report. Every step can be
+ * called alone. Nothing is signed or sent before this package's own checks pass (see `checkFeePermit` and
+ * `checkExecutionArtifact`); they cannot be turned off.
+ */
+export declare function createRectaClient(options: RectaClientOptions): {
+    evaluate: (request: EvaluationRequestView & Record<string, unknown>, opts?: {
+        readonly idempotencyKey?: string;
+    }) => Promise<Record<string, unknown>>;
+    authorizeFee: (resultId: string, opts?: {
+        readonly dryRun?: boolean;
+    }) => Promise<{
+        readonly fee: FeeOutcome;
+        readonly artifact: unknown;
+    }>;
+    check: (resultId: string, artifact: unknown, request: EvaluationRequestView) => Promise<CheckedArtifact>;
+    execute: (resultId: string, artifact: unknown, request: EvaluationRequestView) => Promise<{
+        readonly approvalTxHash?: Hex;
+        readonly originTxHash: Hex;
+    }>;
+    report: (resultId: string, originTxHash: Hex, approvalTxHash?: Hex) => Promise<{
+        readonly stage: "ACCRUED" | "PENDING" | "REFUSED";
+        readonly body: Record<string, unknown>;
+    }>;
+    ledger: () => Promise<Record<string, unknown>>;
+    payDebt: (offer: unknown) => Promise<Record<string, unknown>>;
+    run: (request: EvaluationRequestView & Record<string, unknown>, opts?: {
+        readonly dryRun?: boolean;
+        readonly idempotencyKey?: string;
+    }) => Promise<{
+        stage: "NO_ROUTE";
+        decision: Record<string, unknown>;
+        fee?: never;
+        checked?: never;
+    } | {
+        stage: "DRY_RUN";
+        decision: Record<string, unknown>;
+        fee: {
+            readonly kind: "DRY_RUN";
+            readonly amountUsdcAtomic: bigint;
+            readonly typedData: RectaTypedData;
+        };
+        checked?: never;
+    } | {
+        stage: "DRY_RUN";
+        decision: Record<string, unknown>;
+        fee: {
+            readonly kind: "NOT_REQUIRED";
+        } | {
+            readonly kind: "ALREADY_AUTHORIZED";
+        } | {
+            readonly kind: "AUTHORIZED";
+            readonly amountUsdcAtomic: bigint;
+            readonly signature: Hex;
+        };
+        checked: CheckedArtifact;
+    } | {
+        report: {
+            readonly stage: "ACCRUED" | "PENDING" | "REFUSED";
+            readonly body: Record<string, unknown>;
+        };
+        approvalTxHash?: Hex;
+        originTxHash: Hex;
+        stage: "REPORTED";
+        decision: Record<string, unknown>;
+        fee: {
+            readonly kind: "NOT_REQUIRED";
+        } | {
+            readonly kind: "ALREADY_AUTHORIZED";
+        } | {
+            readonly kind: "AUTHORIZED";
+            readonly amountUsdcAtomic: bigint;
+            readonly signature: Hex;
+        };
+        checked?: never;
+    }>;
+    walletPolicy: () => Promise<void>;
+};
+export type RectaClient = ReturnType<typeof createRectaClient>;