@recta/client 0.1.0 → 0.1.2

package/README.md

@@ -33,6 +33,7 @@ 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.
@@ -49,6 +50,18 @@ your signer's address. Each step is also available alone: `evaluate`, `authorize
 
 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
@@ -78,7 +91,9 @@ anything that policy does not allow, and it allows sending only on those six cha
 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 that route is already the cheapest, Recta answers with no saving and charges nothing.
+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
 

package/dist/client.d.ts

@@ -12,6 +12,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 +33,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";
 } | {

package/dist/client.js

@@ -16,6 +16,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,6 +43,7 @@ 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);
     let policyChecked = false;
     async function call(method, path, body, idempotencyKey, signed = true) {
         const bytes = body === undefined ? new Uint8Array() : new TextEncoder().encode(JSON.stringify(body));
@@ -72,7 +83,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)
@@ -105,7 +116,7 @@ export function createRectaClient(options) {
             if (opts.dryRun === true)
                 return { fee: { kind: "DRY_RUN", amountUsdcAtomic: checked.amount, typedData: checked.typedData }, artifact: undefined };
             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)
                 return { fee: { kind: "AUTHORIZED", amountUsdcAtomic: checked.amount, signature }, artifact: field(s.body, "artifact") };
             if (!(s.status === 409 && field(s.body, "reason_code") === "OFFER_STALE"))

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-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 { checkExecutionArtifact, pinnedRouteOf, type CheckedArtifact, type EvaluationRequestView, type ArtifactLimits } from "./artifact.js";
 export { PINNED_ROUTES, type PinnedRoute } from "./pinned-routes.js";

package/dist/index.js

@@ -1,4 +1,4 @@
-export { createRectaClient, signedRequestMessage } from "./client.js";
+export { createRectaClient, signedRequestMessage, referrerQuery } from "./client.js";
 export { checkFeePermit } from "./fee.js";
 export { checkExecutionArtifact, pinnedRouteOf } from "./artifact.js";
 export { PINNED_ROUTES } from "./pinned-routes.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@recta/client",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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)",
@@ -45,7 +45,7 @@
     "build": "tsc -p tsconfig.build.json"
   },
   "peerDependencies": {
-    "viem": ">=2.56.3 <3"
+    "viem": ">=2.38.3 <3"
   },
   "publishConfig": {
     "access": "public",