@getcofund/protocol 0.0.0 → 0.1.0

package/dist/evm/simulate/describe.js

@@ -0,0 +1,188 @@
+import { getAddress } from "viem";
+import { SIMULATION_CAVEAT, UNLISTED_SIMULATION_WARNING, } from "../types.js";
+import { cleanReason } from "./revert.js";
+/**
+ * How every surface shows a simulation or an executed effect (the web review,
+ * the signing email, the CLI): one description, rendered by each in its own
+ * layout with its own amount format.
+ */
+/** Every EVM chain Cofund runs on pays gas, and moves value, in ETH. */
+export const NATIVE_SYMBOL = "ETH";
+const NATIVE_DECIMALS = 18;
+const TRAILING_ZEROS = /0+$/;
+/**
+ * The CLI's format: every digit, as ethers writes units. A whole amount keeps
+ * one decimal ("1.0"), trailing zeros go, a token without decimals has no
+ * point.
+ */
+export const formatUnitsAmount = (units, decimals) => {
+    const negative = units < 0n;
+    let digits = (negative ? -units : units).toString();
+    if (decimals === 0) {
+        return `${negative ? "-" : ""}${digits}`;
+    }
+    digits = digits.padStart(decimals + 1, "0");
+    const whole = digits.slice(0, digits.length - decimals);
+    const fraction = digits
+        .slice(digits.length - decimals)
+        .replace(TRAILING_ZEROS, "");
+    return `${negative ? "-" : ""}${whole}.${fraction || "0"}`;
+};
+/**
+ * An asset as approvers read it: the native coin and a token from Cofund's
+ * list by their symbol; any other token by its own claim, in quotes, with its
+ * address (a token's `symbol()` is anyone's to set).
+ */
+export function assetLabel(asset) {
+    if (asset.kind === "native") {
+        return NATIVE_SYMBOL;
+    }
+    if (asset.listed && asset.symbol) {
+        return asset.symbol;
+    }
+    return asset.symbol ? `"${asset.symbol}" (${asset.address})` : asset.address;
+}
+/** "Vault", "Wrapper", or the holder's address. */
+export function holderLabel(change) {
+    if (change.role === "vault") {
+        return "Vault";
+    }
+    return change.role === "wrapper" ? "Wrapper" : change.holder;
+}
+/** An amount of an asset; a token of unknown decimals in base units. `withAddress` adds a listed token's address. */
+function amountOf(asset, units, format, withAddress = false) {
+    const decimals = asset.kind === "native" ? NATIVE_DECIMALS : asset.decimals;
+    const label = assetLabel(asset);
+    if (decimals === null) {
+        return `${units} base units of ${label}`;
+    }
+    const address = withAddress && asset.kind === "erc20" && asset.listed
+        ? ` (${asset.address})`
+        : "";
+    return `${format(units, decimals)} ${label}${address}`;
+}
+/** A change as a signed amount with its asset; none as "no change in" it. */
+export function formatDelta(change, format, { withAddress = false } = {}) {
+    const delta = BigInt(change.delta);
+    if (delta === 0n) {
+        return `no change in ${assetLabel(change.asset)}`;
+    }
+    const sign = delta < 0n ? "-" : "+";
+    const units = delta < 0n ? -delta : delta;
+    return `${sign}${amountOf(change.asset, units, format, withAddress)}`;
+}
+/** The changes per holder, the vault first, then the wrapper, then the others as they came. */
+export function changesByHolder(changes) {
+    const holders = new Map();
+    for (const change of changes) {
+        const key = change.holder.toLowerCase();
+        const entry = holders.get(key) ?? {
+            holder: change.holder,
+            role: change.role,
+            changes: [],
+        };
+        entry.changes.push(change);
+        holders.set(key, entry);
+    }
+    return [...holders.values()];
+}
+/** The vault's own changes in a successful simulation; none otherwise. */
+export function vaultChanges(simulation) {
+    return simulation?.outcome === "success"
+        ? simulation.changes.filter(({ role }) => role === "vault")
+        : [];
+}
+/** The tokens simulations named, by address: a listing over a token's claim, a claim with decimals over one without. */
+export function simulationTokens(...simulations) {
+    const known = new Map();
+    for (const simulation of simulations) {
+        const changes = simulation && "changes" in simulation ? simulation.changes : [];
+        for (const { asset } of changes) {
+            if (asset.kind !== "erc20") {
+                continue;
+            }
+            const address = asset.address.toLowerCase();
+            const seen = known.get(address);
+            if (!seen ||
+                (asset.listed && !seen.listed) ||
+                (seen.decimals === null && asset.decimals !== null)) {
+                known.set(address, asset);
+            }
+        }
+    }
+    return (address) => known.get(address.toLowerCase()) ?? null;
+}
+/**
+ * The hard bound every surface ends with: the vault approves exactly the
+ * signed allowances to the wrapper for this call and resets them, so per
+ * asset it can lose at most the allowance (the last one listed when an asset
+ * repeats). Null allowances (stored ones that do not parse) leave it unknown.
+ */
+export function allowanceBound(allowances, tokens, format) {
+    if (allowances === null) {
+        return "The most this call can take from the vault is unavailable: its allowances could not be read.";
+    }
+    const last = new Map();
+    for (const allowance of allowances) {
+        last.set(allowance.asset.toLowerCase(), allowance);
+    }
+    const amounts = [...last.values()].map(({ asset, amount }) => amountOf({
+        kind: "erc20",
+        address: getAddress(asset),
+        ...(tokens(asset) ?? { symbol: null, decimals: null, listed: false }),
+    }, BigInt(amount), format));
+    return amounts.length === 0
+        ? "The vault approves nothing to this call: it can take nothing from the vault."
+        : `The most this call can take from the vault is what you approve: ${amounts.join(", ")}.`;
+}
+/** What every surface says after the effect: the caveat, and on an unlisted wrapper its warning. */
+export function simulationCaveat(unlisted) {
+    return unlisted
+        ? [SIMULATION_CAVEAT, UNLISTED_SIMULATION_WARNING]
+        : [SIMULATION_CAVEAT];
+}
+/** "2026-10-15 14:00 UTC". */
+export function utcDateTime(iso) {
+    return `${iso.slice(0, 10)} ${iso.slice(11, 16)} UTC`;
+}
+const INCOMPLETE = "It also moves NFTs, or more balances than were read: only these are shown.";
+const NO_NATIVE_LOG = "Native ETH moves leave no log, so they are not shown here.";
+/** `simulation` (or what an executed call did) described, amounts in `format`. */
+export function describeSimulation(simulation, format, { withAddress = false } = {}) {
+    const at = utcDateTime(simulation.at);
+    if ("outcome" in simulation && simulation.outcome === "unavailable") {
+        const notice = `Could not simulate it: ${cleanReason(simulation.reason)}`;
+        return {
+            status: "unavailable",
+            block: null,
+            at,
+            holders: [],
+            notice,
+            notes: [],
+        };
+    }
+    const block = simulation.block.number;
+    if ("outcome" in simulation && simulation.outcome === "revert") {
+        const notice = `Would fail now: ${cleanReason(simulation.reason)}`;
+        return { status: "revert", block, at, holders: [], notice, notes: [] };
+    }
+    const executed = !("outcome" in simulation);
+    const holders = changesByHolder(simulation.changes).map((holder) => ({
+        label: holderLabel(holder),
+        address: holder.holder,
+        role: holder.role,
+        changes: holder.changes.map((c) => formatDelta(c, format, { withAddress })),
+    }));
+    const nothing = executed ? "No balance changed" : "No balance would change";
+    return {
+        status: executed ? "executed" : "success",
+        block,
+        at,
+        holders,
+        notice: holders.length === 0 ? nothing : null,
+        notes: [
+            ...(simulation.incomplete ? [INCOMPLETE] : []),
+            ...(executed ? [NO_NATIVE_LOG] : []),
+        ],
+    };
+}

package/dist/evm/simulate/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * A protocol call's effect, simulated before anyone signs it (`simulateCall`,
+ * the same code Cofund's server and an agent's own node run), what an
+ * executed call did (`effectFromLogs`), and how every surface describes
+ * either.
+ */
+export { type BalanceLog, RpcLogSchema, RpcQuantity, type TokenInfo, } from "./balances.ts";
+export { type AmountFormat, allowanceBound, describeSimulation, formatUnitsAmount, type SimulationView, simulationCaveat, simulationTokens, type TokenLookup, vaultChanges, } from "./describe.ts";
+export { compareSimulations, type OwnNode, type OwnNodeCall, type OwnRpc, SimulationMismatchError, simulateOnOwnNode, } from "./own-node.ts";
+export { type ExecuteTransactionFields, encodeExecuteTransaction, policyThresholdSlot, type SimulationTarget, } from "./request.ts";
+export { type ErrorDecoder, revertReason } from "./revert.ts";
+export { type EvmNode, effectFromLogs, type JsonRpcSend, nodeSend, type SimulationOptions, simulateCall, } from "./run.ts";

package/dist/evm/simulate/index.js

@@ -0,0 +1,13 @@
+/**
+ * A protocol call's effect, simulated before anyone signs it (`simulateCall`,
+ * the same code Cofund's server and an agent's own node run), what an
+ * executed call did (`effectFromLogs`), and how every surface describes
+ * either.
+ */
+// biome-ignore lint/performance/noBarrelFile: the simulation part of the `./evm` entry
+export { RpcLogSchema, RpcQuantity, } from "./balances.js";
+export { allowanceBound, describeSimulation, formatUnitsAmount, simulationCaveat, simulationTokens, vaultChanges, } from "./describe.js";
+export { compareSimulations, SimulationMismatchError, simulateOnOwnNode, } from "./own-node.js";
+export { encodeExecuteTransaction, policyThresholdSlot, } from "./request.js";
+export { revertReason } from "./revert.js";
+export { effectFromLogs, nodeSend, simulateCall, } from "./run.js";

package/dist/evm/simulate/own-node.d.ts

@@ -0,0 +1,62 @@
+import type { EvmReader } from "../chain.ts";
+import type { CallSimulation, ChainPins, EvmChainName } from "../types.ts";
+import { type ExecuteTransactionFields } from "./request.ts";
+import { type JsonRpcSend } from "./run.ts";
+/**
+ * The agent's own check: a call simulated on the agent's own node with the
+ * same code, trusting Cofund for nothing but the request's own fields, and
+ * compared with the simulation Cofund reports.
+ */
+/** A node of the caller's own: a URL, a reader (a viem public client), or a provider with `send`. */
+export type OwnRpc = string | EvmReader | {
+    send: JsonRpcSend;
+};
+/** The caller's nodes per chain, and the address it simulates from: its own, an active member's. */
+export type OwnNode = {
+    rpc: Partial<Record<EvmChainName, OwnRpc>>;
+    from: string;
+};
+/**
+ * How far two simulations of one call at different blocks may differ in an
+ * amount (basis points of the larger) before they disagree: interest accrues
+ * and prices move between blocks, but not by more than this in seconds.
+ */
+export declare const SIMULATION_TOLERANCE_BPS = 100n;
+/** Base units two simulations may differ by whatever the amount: a rebasing token's rounding. */
+export declare const SIMULATION_DUST = 2n;
+/** A vault's `executeTransaction`, to simulate: its chain, the vault, and the fields its members sign. */
+export type OwnNodeCall = {
+    chain: EvmChainName;
+    vault: string;
+    /** `company` is the pinned one. */
+    fields: ExecuteTransactionFields;
+    /** The wrapper is one Cofund hasn't reviewed (`SimulationOptions.unlisted`). */
+    unlisted: boolean;
+};
+/**
+ * `call`'s simulation on the caller's own node: the vault called directly
+ * from `node.from` (the vault admits any active member as the broadcaster),
+ * under the pinned State, chain id and company. Never throws.
+ */
+export declare function simulateOnOwnNode(call: OwnNodeCall, { pins, node }: {
+    pins: ChainPins;
+    node: OwnNode;
+}): Promise<CallSimulation>;
+type Ran = Exclude<CallSimulation, {
+    outcome: "unavailable";
+}>;
+/**
+ * Where two simulations of one call disagree beyond what a block's difference
+ * explains: a different outcome, or a holder's amount of an asset off by more
+ * than `SIMULATION_TOLERANCE_BPS` of the larger and more than dust (one in one
+ * and not the other included). Empty when they agree, both reverting
+ * included.
+ */
+export declare function compareSimulations(cofund: Ran, own: Ran): string[];
+/** Cofund's simulation of a call disagrees with the caller's own node's. */
+export declare class SimulationMismatchError extends Error {
+    readonly own: CallSimulation;
+    readonly differences: string[];
+    constructor(own: CallSimulation, differences: string[]);
+}
+export {};

package/dist/evm/simulate/own-node.js

@@ -0,0 +1,122 @@
+import { createPublicClient, http } from "viem";
+import { cofundClientId } from "../eip712.js";
+import { NATIVE_ASSET } from "./balances.js";
+import { assetLabel, formatDelta, formatUnitsAmount, holderLabel, simulationTokens, } from "./describe.js";
+import { encodeExecuteTransaction, } from "./request.js";
+import { nodeSend, simulateCall } from "./run.js";
+/**
+ * How far two simulations of one call at different blocks may differ in an
+ * amount (basis points of the larger) before they disagree: interest accrues
+ * and prices move between blocks, but not by more than this in seconds.
+ */
+export const SIMULATION_TOLERANCE_BPS = 100n;
+/** Base units two simulations may differ by whatever the amount: a rebasing token's rounding. */
+export const SIMULATION_DUST = 2n;
+/** `rpc` as a `send`: a URL over viem's HTTP transport, a reader's `request`, a provider's `send`. */
+function ownSend(rpc) {
+    if (typeof rpc === "string") {
+        return nodeSend(createPublicClient({ transport: http(rpc, { retryCount: 0 }) }));
+    }
+    return "request" in rpc
+        ? nodeSend(rpc)
+        : (method, params) => rpc.send(method, params);
+}
+/**
+ * `call`'s simulation on the caller's own node: the vault called directly
+ * from `node.from` (the vault admits any active member as the broadcaster),
+ * under the pinned State, chain id and company. Never throws.
+ */
+export async function simulateOnOwnNode(call, { pins, node }) {
+    const at = new Date().toISOString();
+    const pin = pins[call.chain];
+    const rpc = node.rpc[call.chain];
+    if (!(pin && rpc)) {
+        const reason = pin
+            ? `No node of yours is set for ${call.chain}`
+            : `No chain id and State are pinned for ${call.chain}`;
+        return { outcome: "unavailable", at, reason };
+    }
+    const send = ownSend(rpc);
+    try {
+        const chainId = Number(BigInt(String(await send("eth_chainId", []))));
+        if (chainId !== pin.chainId) {
+            const reason = `Your ${call.chain} node is on chain ${chainId}, not ${pin.chainId}`;
+            return { outcome: "unavailable", at, reason };
+        }
+        return await simulateCall(send, {
+            state: pin.state,
+            clientId: cofundClientId(call.fields.company),
+            policyId: call.fields.policyId,
+            vault: call.vault,
+            wrapper: call.fields.wrapper,
+            tx: {
+                from: node.from,
+                to: call.vault,
+                data: encodeExecuteTransaction(call.fields, []),
+            },
+            skipSignatures: true,
+        }, { unlisted: call.unlisted });
+    }
+    catch {
+        const reason = `Your ${call.chain} node could not be read`;
+        return { outcome: "unavailable", at, reason };
+    }
+}
+const changeKey = (change) => `${change.holder.toLowerCase()}|${change.asset.kind === "native"
+    ? NATIVE_ASSET
+    : change.asset.address.toLowerCase()}`;
+const abs = (x) => (x < 0n ? -x : x);
+/** Two amounts that differ by no more than a block's difference, or dust. */
+function close(a, b) {
+    if (abs(a - b) <= SIMULATION_DUST) {
+        return true;
+    }
+    const sameSign = a > 0n === b > 0n && a < 0n === b < 0n;
+    const larger = abs(a) > abs(b) ? abs(a) : abs(b);
+    return sameSign && abs(a - b) * 10000n <= larger * SIMULATION_TOLERANCE_BPS;
+}
+/**
+ * Where two simulations of one call disagree beyond what a block's difference
+ * explains: a different outcome, or a holder's amount of an asset off by more
+ * than `SIMULATION_TOLERANCE_BPS` of the larger and more than dust (one in one
+ * and not the other included). Empty when they agree, both reverting
+ * included.
+ */
+export function compareSimulations(cofund, own) {
+    if (cofund.outcome !== own.outcome) {
+        const said = (s) => s.outcome === "revert" ? `would revert (${s.reason})` : "succeeds";
+        return [`Cofund's simulation ${said(cofund)}; your node's ${said(own)}`];
+    }
+    if (cofund.outcome !== "success" || own.outcome !== "success") {
+        return [];
+    }
+    const theirs = new Map(cofund.changes.map((c) => [changeKey(c), c]));
+    const ours = new Map(own.changes.map((c) => [changeKey(c), c]));
+    const named = simulationTokens(cofund, own);
+    const differences = [];
+    for (const key of new Set([...theirs.keys(), ...ours.keys()])) {
+        const a = BigInt(theirs.get(key)?.delta ?? "0");
+        const b = BigInt(ours.get(key)?.delta ?? "0");
+        if (close(a, b)) {
+            continue;
+        }
+        const change = (theirs.get(key) ?? ours.get(key));
+        const asset = change.asset.kind === "erc20"
+            ? { ...change.asset, ...named(change.asset.address) }
+            : change.asset;
+        const show = (delta) => formatDelta({ asset, delta: delta.toString() }, formatUnitsAmount);
+        differences.push(`${holderLabel(change)} ${assetLabel(asset)}: Cofund ${show(a)}, your node ${show(b)}`);
+    }
+    return differences;
+}
+/** Cofund's simulation of a call disagrees with the caller's own node's. */
+export class SimulationMismatchError extends Error {
+    own;
+    differences;
+    constructor(own, differences) {
+        super(`Cofund's simulation disagrees with your node's: ${differences.join("; ")}`);
+        this.name = "SimulationMismatchError";
+        this.own = own;
+        this.differences = differences;
+    }
+}

package/dist/evm/simulate/request.d.ts

@@ -0,0 +1,86 @@
+import { type Hex } from "viem";
+/**
+ * What a simulation sends: the vault's calldata, the one State storage
+ * override that lets it run before anyone signs, the reads that prove the
+ * override took for this call, and the `eth_simulateV1` parameters.
+ */
+/** `CFHelpersStatev1.policies`: storage slot 4 (State is not a proxy; its layout is fixed for v1). */
+export declare const STATE_POLICIES_SLOT = 4n;
+/** A realistic cap for a preview; the block's limit would let a runaway call pass. */
+export declare const SIMULATION_GAS = 3000000n;
+/**
+ * The storage slot of `policies[clientId][policyId].threshold` in State:
+ * `keccak256(bytes(policyId) ‖ keccak256(clientId ‖ 4)) + 4`.
+ */
+export declare function policyThresholdSlot(clientId: string, policyId: string): string;
+/** The fields `executeTransaction` takes, as a request or a stored call carries them. */
+export type ExecuteTransactionFields = {
+    company: string;
+    policyId: string;
+    messageType: string;
+    wrapper: string;
+    instructions: string;
+    allowances: {
+        asset: string;
+        amount: string;
+    }[];
+    authId: string;
+};
+/** The vault's `executeTransaction` calldata; `signatures` sorted by signer, or empty for a preview. */
+export declare function encodeExecuteTransaction(fields: ExecuteTransactionFields, signatures: string[]): Hex;
+/** What to simulate. */
+export type SimulationTarget = {
+    /** The chain's State: the threshold override's target. */
+    state: string;
+    clientId: string;
+    policyId: string;
+    vault: string;
+    wrapper: string;
+    /** The transaction: the relay through the guard (Cofund), or the vault called by a member (an agent). */
+    tx: {
+        from: string;
+        to: string;
+        data: string;
+    };
+    /**
+     * True before the threshold: the calldata carries no signature, and the
+     * policy's threshold is overridden to 0. False with the real signatures:
+     * no override and no guard, the exact call as broadcast.
+     */
+    skipSignatures: boolean;
+    /** The transaction's gas; null for the node's own cap. */
+    gas?: bigint | null;
+};
+export type SimCall = {
+    from: string;
+    to: string;
+    data: string;
+    gas?: string;
+};
+export type StateOverrides = Record<string, {
+    stateDiff: Record<string, string>;
+}>;
+/** A call's result as the guard reads it. */
+type ReadResult = {
+    status: string;
+    returnData: string;
+};
+/**
+ * The override, and the reads that prove it took for this call, in the same
+ * block before it: State's policy (active, bound to the wrapper, threshold 0),
+ * the vault's State, and State's vault for the cofund.
+ */
+export declare function guardsOf(target: SimulationTarget): {
+    overrides?: StateOverrides;
+    guards: SimCall[];
+};
+/** The guards' verdict: null when the simulation is this call's, else why not. */
+export declare function guardFailure(target: SimulationTarget, [policy, vaultState, clientVault]: ReadResult[]): string | null;
+/** The call itself, capped at a preview's gas unless told otherwise. */
+export declare function txCall(target: SimulationTarget): SimCall;
+/** The `eth_simulateV1` parameters: one block on top of `head`, no validation, native transfers as logs. */
+export declare function simulateParams(head: {
+    number: string;
+    baseFeePerGas?: string;
+}, overrides: StateOverrides | undefined, calls: SimCall[]): [unknown, string];
+export {};