remesso-sdk 0.1.0 → 0.2.0

package/README.md

@@ -210,6 +210,40 @@ await agent.requests.pay(requestId); // its reference goes in the memo, so the r
   (`privateKeyToAccount`). The agent's key pays its own gas: send it a little
   CELO.
 
+## Builder codes
+
+Celo credits on-chain volume to the app that caused it, by the ERC-8021 code
+on each transaction
+([attribution tags](https://github.com/celo-org/attribution-tags)). Pass your
+own, and every transaction this client sends carries it after Remesso's.
+Remesso's executor then carries it on every run of each schedule the client
+creates, so the volume a schedule moves counts for you too, for as long as it
+runs.
+
+```ts
+import { createRemesso } from "remesso-sdk";
+import { privateKeyToAccount } from "viem/accounts";
+
+const payer = createRemesso({
+  account: privateKeyToAccount(process.env.PAYER_KEY as `0x${string}`),
+  builderCodes: ["your_code"],
+});
+const s = await payer.schedules.create({ to: "0xRecipient", amount: "5", token: "USDT", every: "month", runs: 12 });
+
+// A minute later, what Remesso read from the transaction that created it:
+const { events } = await payer.events.list({ role: "from", kinds: ["schedule_created"] });
+console.log(events.find((e) => e.refId === s.id.toString())?.details?.builderCodes); // ["your_code"]
+```
+
+- Up to three codes, each 1 to 32 of `a-z`, `0-9` and `_`. The SDK refuses
+  anything else before signing, by the rules the executor applies.
+- Without the SDK, tag your own `createSchedule` transaction with
+  `toDataSuffix` or `withAttribution` from `@celo/attribution-tags`. Only
+  Schema 0, the one they write, is read. A schedule created through an
+  ERC-4337 bundle isn't read yet: the codes come from the outer transaction.
+- The suffix sits after the calldata, where the EVM ignores it. A code
+  changes who is credited, never what a payment does.
+
 ## What it costs
 
 - **0.25% of each scheduled payment**, taken from it and rounded up: a 1 USDT
@@ -241,6 +275,7 @@ await agent.requests.pay(requestId); // its reference goes in the memo, so the r
 | `store` | Where agent payments are recorded so a retry pays once. Default: memory. |
 | `fetchText` | Reads an https or ipfs registration file for `agents.find`: pass `safeFetchText`. |
 | `attribution` | Tag transactions for ERC-8021 attribution. Default true. |
+| `builderCodes` | Your own ERC-8021 codes, up to three: on every transaction this client sends, and on every run of the schedules it creates (see Builder codes). |
 
 The client:
 
@@ -296,6 +331,7 @@ The client:
 | `CHAIN_ID`, `EXECUTOR`, `ALLOWANCE`, `REGISTRY`, `CURRENT_EXECUTOR`, `FEE_BPS` | The chain, the contracts, Remesso's trigger sentinel and the commission. |
 | `executorAbi`, `allowanceAbi`, `erc20Abi`, `registryAbi` | ABIs. |
 | `ATTRIBUTION` | The ERC-8021 suffix the SDK adds to transactions. |
+| `attributionFor(builderCodes)` | That suffix with your codes after ours, checked by the executor's rules: for a transaction you send yourself. |
 | `CADENCES` | `week`, `fortnight`, `month` and `quarter`, in seconds. |
 | `RemessoError` | Every refusal; see the codes below. |
 

package/dist/attribution.d.ts

@@ -1 +1,3 @@
+import type { Hex } from "viem";
 export declare const ATTRIBUTION: "0x72656d6573736f2c63656c6f5f356364333563613535626166190080218021802180218021802180218021";
+export declare function attributionFor(builderCodes?: readonly string[], ours?: boolean): Hex | undefined;

package/dist/attribution.js

@@ -1,8 +1,29 @@
-/// ERC-8021 attribution, after the calldata where the EVM ignores it:
-/// Remesso's code plus the one Loops issued for Agents on Open Rails. It
-/// credits the app that caused a transaction and changes nothing it does.
-/// The same suffix the Remesso app and the plugin wallet put on every write.
-/// Byte-identical to `toDataSuffix(["remesso", "celo_5cd35ca55baf"])` from
-/// `@celo/attribution-tags`; `test/attribution.test.ts` pins it to the
-/// backend's own encoder.
+import { RemessoError } from "./errors.js";
+import { CODE, MAX_INTEGRATOR_CODES, OWN_CODES, suffixFor } from "./vendor/erc8021.js";
 export const ATTRIBUTION = "0x72656d6573736f2c63656c6f5f356364333563613535626166190080218021802180218021802180218021";
+/// What `ATTRIBUTION` carries.
+const OURS = ["remesso", "celo_5cd35ca55baf"];
+/// The suffix with your own builder codes after ours. Put on the transaction
+/// that creates a schedule, they ride on every run of it too: Remesso's
+/// executor reads them and tags each run with them, so Celo counts the volume
+/// for you as well as for us.
+///
+/// Checked by the rules the backend applies (`vendor/erc8021.ts`), so a code
+/// accepted here is one the runs carry: Celo's charset, none of Remesso's own,
+/// no repeats, at most three. `ours: false` leaves our codes out.
+export function attributionFor(builderCodes = [], ours = true) {
+    for (const code of builderCodes) {
+        if (!CODE.test(code)) {
+            throw new RemessoError("invalid", `builder code ${JSON.stringify(code)}: 1 to 32 of a-z, 0-9 and _, as Celo's attribution codes are`);
+        }
+        if (OWN_CODES.includes(code))
+            throw new RemessoError("invalid", `${code} is Remesso's own code: pass yours`);
+    }
+    if (new Set(builderCodes).size !== builderCodes.length)
+        throw new RemessoError("invalid", "a builder code is repeated");
+    if (builderCodes.length > MAX_INTEGRATOR_CODES) {
+        throw new RemessoError("invalid", `at most ${MAX_INTEGRATOR_CODES} builder codes ride on a schedule's runs`);
+    }
+    const codes = [...(ours ? OURS : []), ...builderCodes];
+    return codes.length ? suffixFor(codes) : undefined;
+}

package/dist/client.d.ts

@@ -26,6 +26,14 @@ export type RemessoOptions = {
     fetchText?: (url: string) => Promise<string>;
     /** Tag transactions for ERC-8021 attribution. Default true. */
     attribution?: boolean;
+    /**
+     * Your own ERC-8021 builder codes, up to three, carried after Remesso's on
+     * every transaction this client sends. Remesso's executor also carries them
+     * on every run of the schedules you create, so Celo counts that volume for
+     * you. Throws on a code outside Celo's charset, one of Remesso's own, a
+     * repeat, or more than three.
+     */
+    builderCodes?: string[];
     /** For tests: another Remesso backend, and the app origin links point at. */
     functionsUrl?: string;
     appOrigin?: string;

package/dist/client.js

@@ -2,7 +2,7 @@
 import { createPublicClient, createWalletClient, http } from "viem";
 import { celo } from "viem/chains";
 import { makeAgents } from "./agents.js";
-import { ATTRIBUTION } from "./attribution.js";
+import { attributionFor } from "./attribution.js";
 import { makeCtx } from "./context.js";
 import { deployment } from "./deployment.js";
 import { makeEvents } from "./events.js";
@@ -31,7 +31,7 @@ export function createRemesso(opts = {}) {
         },
         appOrigin,
         fetch: opts.fetch ?? globalThis.fetch.bind(globalThis),
-        dataSuffix: opts.attribution === false ? undefined : ATTRIBUTION,
+        dataSuffix: attributionFor(opts.builderCodes, opts.attribution !== false),
         store: opts.store ?? memoryStore(),
         fetchText: opts.fetchText,
     });

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export { RemessoError, type RemessoErrorCode } from "./errors.js";
 export { ALLOWANCE, CHAIN_ID, CURRENT_EXECUTOR, deployment, EXECUTOR, FEE_BPS, findToken, formatAmount, REGISTRY, runLimits, type Token, token, toUnits, } from "./deployment.js";
 export { feeOf, grossFor, netOf } from "./vendor/fee.js";
 export { allowanceAbi, erc20Abi, executorAbi, registryAbi } from "./abi.js";
-export { ATTRIBUTION } from "./attribution.js";
+export { ATTRIBUTION, attributionFor } from "./attribution.js";
 export { CADENCES, type Cadence, type CreatedSchedule, type CreateScheduleInput, type Schedule } from "./schedules.js";
 export { memo32, type PayInput, type PaymentResult } from "./payments.js";
 export type { CreatePolicyInput, Policy } from "./policies.js";

package/dist/index.js

@@ -7,7 +7,7 @@ export { RemessoError } from "./errors.js";
 export { ALLOWANCE, CHAIN_ID, CURRENT_EXECUTOR, deployment, EXECUTOR, FEE_BPS, findToken, formatAmount, REGISTRY, runLimits, token, toUnits, } from "./deployment.js";
 export { feeOf, grossFor, netOf } from "./vendor/fee.js";
 export { allowanceAbi, erc20Abi, executorAbi, registryAbi } from "./abi.js";
-export { ATTRIBUTION } from "./attribution.js";
+export { ATTRIBUTION, attributionFor } from "./attribution.js";
 export { CADENCES } from "./schedules.js";
 export { memo32 } from "./payments.js";
 export { parseWebhook, verifyWebhook, webhookHandler, } from "./webhooks.js";

package/dist/vendor/erc8021.d.ts

@@ -0,0 +1,9 @@
+export declare const MARKER = "80218021802180218021802180218021";
+export declare const CODE: RegExp;
+export declare const OWN_CODES: readonly string[];
+export declare const MAX_INTEGRATOR_CODES = 3;
+export declare function suffixFor(codes: string | readonly string[]): `0x${string}` | undefined;
+export declare function parseSuffix(input: string): {
+    codes: string[];
+} | null;
+export declare function integratorCodes(codes: readonly string[], own?: readonly string[]): string[];

package/dist/vendor/erc8021.js

@@ -0,0 +1,82 @@
+// Copied from supabase/functions/_shared/erc8021.ts by scripts/build-sdk.ts. Edit the original and re-run;
+// `build-sdk.ts --check` fails while the two differ.
+/// ERC-8021 Schema 0: writing a suffix, reading one back, and which of the
+/// codes an integrator's transaction carries ride on the runs that follow it.
+///
+/// Pure, with no environment, so `remesso-sdk` carries an exact copy
+/// (`scripts/build-sdk.ts`): a builder code the SDK accepts is one the backend
+/// keeps. `attribution.ts` adds Remesso's own configured codes on top.
+/// `attribution.test.ts` pins both directions to `@celo/attribution-tags`.
+/// `[code:N][length:1][schema:1][marker:16]`
+export const MARKER = "80218021802180218021802180218021";
+const SCHEMA_0 = "00";
+/// What Celo's SDK accepts in `toDataSuffix`.
+export const CODE = /^[a-z0-9_]{1,32}$/;
+/// Remesso's own codes, whether or not they're carried today. `remesso-sdk`
+/// 0.1.0 writes both on every transaction, so a schedule created with it
+/// after the event code leaves `ATTRIBUTION_CODE` must not hand that code
+/// back to our runs as if it were an integrator's.
+export const OWN_CODES = ["remesso", "celo_5cd35ca55baf"];
+/// How many of an integrator's codes ride on each run. Each costs calldata
+/// gas on every run, and three cover an app, a wallet and one partner.
+export const MAX_INTEGRATOR_CODES = 3;
+/// The suffix for one code or several, or `undefined` if none is usable.
+///
+/// Never throws: a malformed tag must not be the reason a remittance fails to
+/// go out. A bad code is dropped and the rest still tag — a typo in one must
+/// not cost the other its credit, since an untagged transaction stays
+/// untagged forever. A comma inside a single code is refused rather than read
+/// as a list; a list is passed as an array.
+export function suffixFor(codes) {
+    const list = (typeof codes === "string" ? [codes] : codes).filter((code) => {
+        if (CODE.test(code))
+            return true;
+        console.error("attribution code must be 1-32 of [a-z0-9_]:", code);
+        return false;
+    });
+    if (list.length === 0)
+        return undefined;
+    const field = list.join(",");
+    // The length is one byte.
+    if (field.length > 255)
+        return undefined;
+    const hex = [...new TextEncoder().encode(field)]
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+    const length = field.length.toString(16).padStart(2, "0");
+    return `0x${hex}${length}${SCHEMA_0}${MARKER}`;
+}
+/// The codes in a transaction's Schema 0 suffix, read from the end the way
+/// Celo's `fromDataSuffix` reads them: the marker, the schema byte, the length
+/// byte, then that many bytes of comma-joined codes, returned as written.
+///
+/// Null when there is no suffix, when it is another schema (Schema 2's roles
+/// aren't read), or when the length runs past the start of the input. ox
+/// reads whatever bytes are there in that last case; nothing honest writes it.
+export function parseSuffix(input) {
+    const hex = input.toLowerCase().replace(/^0x/, "");
+    if (hex.length % 2 !== 0 || hex.length < 36 || !/^[0-9a-f]*$/.test(hex))
+        return null;
+    if (hex.slice(-32) !== MARKER || hex.slice(-34, -32) !== SCHEMA_0)
+        return null;
+    const length = parseInt(hex.slice(-36, -34), 16);
+    if (length === 0 || hex.length < 36 + length * 2)
+        return null;
+    const field = hex.slice(-36 - length * 2, -36);
+    const bytes = Uint8Array.from(field.match(/../g), (b) => parseInt(b, 16));
+    return { codes: new TextDecoder().decode(bytes).split(",") };
+}
+/// Which of a creating transaction's codes ride on a schedule's runs: Celo's
+/// charset, none of Remesso's own (they're carried anyway), no repeats, and
+/// the first three in the order written.
+export function integratorCodes(codes, own = OWN_CODES) {
+    const out = [];
+    for (const code of codes) {
+        if (!CODE.test(code) || own.includes(code) || out.includes(code))
+            continue;
+        out.push(code);
+        if (out.length === MAX_INTEGRATOR_CODES)
+            break;
+    }
+    return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "remesso-sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Recurring and agent payments on Celo: schedules a payer signs once, agent payments capped on-chain by their human, payment requests, payment events and signed webhooks. TypeScript, on viem.",
   "type": "module",
   "exports": {