@getcofund/protocol 0.0.0-stage → 0.1.0

package/dist/evm/simulate/request.js

@@ -0,0 +1,235 @@
+import { concatHex, decodeFunctionResult, encodeAbiParameters, encodeFunctionData, keccak256, numberToHex, stringToHex, zeroHash, } from "viem";
+import { sameAddress } from "../address.js";
+import { WRAPPER_ENTRYPOINT } from "../eip712.js";
+/**
+ * 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 const STATE_POLICIES_SLOT = 4n;
+/** `Policy.threshold`: the struct's fifth slot, after active, title, policyType and signerIds. */
+const POLICY_THRESHOLD_OFFSET = 4n;
+const UINT256 = 2n ** 256n;
+/** A realistic cap for a preview; the block's limit would let a runaway call pass. */
+export const SIMULATION_GAS = 3000000n;
+const STATE = [
+    {
+        type: "function",
+        name: "policies",
+        stateMutability: "view",
+        inputs: [{ type: "bytes32" }, { type: "string" }],
+        outputs: [
+            { name: "active", type: "bool" },
+            { name: "title", type: "string" },
+            { name: "policyType", type: "string" },
+            { name: "threshold", type: "uint256" },
+            {
+                name: "transactionDetails",
+                type: "tuple",
+                components: [
+                    { name: "wrapper", type: "address" },
+                    { name: "func", type: "string" },
+                ],
+            },
+            {
+                name: "transferDetails",
+                type: "tuple",
+                components: [
+                    { name: "maxAmount", type: "uint256" },
+                    { name: "token", type: "address" },
+                    { name: "recipients", type: "address[]" },
+                ],
+            },
+            { name: "isTransaction", type: "bool" },
+        ],
+    },
+    {
+        type: "function",
+        name: "clientVaults",
+        stateMutability: "view",
+        inputs: [{ type: "bytes32" }],
+        outputs: [
+            { name: "vaultAddress", type: "address" },
+            { name: "vaultTier", type: "string" },
+        ],
+    },
+];
+const VAULT = [
+    {
+        type: "function",
+        name: "executeTransaction",
+        stateMutability: "nonpayable",
+        inputs: [
+            { name: "company", type: "string" },
+            { name: "policyId", type: "string" },
+            { name: "messageType", type: "string" },
+            { name: "wrapper", type: "address" },
+            { name: "func", type: "string" },
+            { name: "instructions", type: "bytes" },
+            {
+                name: "allowances",
+                type: "tuple[]",
+                components: [
+                    { name: "asset", type: "address" },
+                    { name: "amount", type: "uint256" },
+                ],
+            },
+            { name: "authId", type: "string" },
+            { name: "signatures", type: "bytes[]" },
+        ],
+        outputs: [{ type: "bool" }],
+    },
+    {
+        type: "function",
+        name: "state",
+        stateMutability: "view",
+        inputs: [],
+        outputs: [{ type: "address" }],
+    },
+];
+/**
+ * The storage slot of `policies[clientId][policyId].threshold` in State:
+ * `keccak256(bytes(policyId) ‖ keccak256(clientId ‖ 4)) + 4`.
+ */
+export function policyThresholdSlot(clientId, policyId) {
+    const inner = keccak256(encodeAbiParameters([{ type: "bytes32" }, { type: "uint256" }], [clientId, STATE_POLICIES_SLOT]));
+    const base = keccak256(concatHex([stringToHex(policyId), inner]));
+    return numberToHex((BigInt(base) + POLICY_THRESHOLD_OFFSET) % UINT256, {
+        size: 32,
+    });
+}
+/** The vault's `executeTransaction` calldata; `signatures` sorted by signer, or empty for a preview. */
+export function encodeExecuteTransaction(fields, signatures) {
+    return encodeFunctionData({
+        abi: VAULT,
+        functionName: "executeTransaction",
+        args: [
+            fields.company,
+            fields.policyId,
+            fields.messageType,
+            fields.wrapper,
+            WRAPPER_ENTRYPOINT,
+            fields.instructions,
+            fields.allowances.map(({ asset, amount }) => ({
+                asset: asset,
+                amount: BigInt(amount),
+            })),
+            fields.authId,
+            signatures,
+        ],
+    });
+}
+/**
+ * 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 function guardsOf(target) {
+    if (!target.skipSignatures) {
+        return { guards: [] };
+    }
+    const from = target.tx.from;
+    return {
+        overrides: {
+            [target.state]: {
+                stateDiff: {
+                    [policyThresholdSlot(target.clientId, target.policyId)]: zeroHash,
+                },
+            },
+        },
+        guards: [
+            {
+                from,
+                to: target.state,
+                data: encodeFunctionData({
+                    abi: STATE,
+                    functionName: "policies",
+                    args: [target.clientId, target.policyId],
+                }),
+            },
+            {
+                from,
+                to: target.vault,
+                data: encodeFunctionData({ abi: VAULT, functionName: "state" }),
+            },
+            {
+                from,
+                to: target.state,
+                data: encodeFunctionData({
+                    abi: STATE,
+                    functionName: "clientVaults",
+                    args: [target.clientId],
+                }),
+            },
+        ],
+    };
+}
+const ran = (result) => result !== undefined && BigInt(result.status) === 1n;
+/** The guards' verdict: null when the simulation is this call's, else why not. */
+export function guardFailure(target, [policy, vaultState, clientVault]) {
+    if (!target.skipSignatures) {
+        return null;
+    }
+    if (!(ran(policy) && ran(vaultState) && ran(clientVault))) {
+        return "the policy, the vault or State could not be read";
+    }
+    const [active, , , threshold, transactionDetails] = decodeFunctionResult({
+        abi: STATE,
+        functionName: "policies",
+        data: policy.returnData,
+    });
+    if (threshold !== 0n) {
+        return "the signature checks could not be skipped on this chain (the threshold override did not take)";
+    }
+    if (!active) {
+        return "the policy is not active on chain";
+    }
+    if (!sameAddress(transactionDetails.wrapper, target.wrapper)) {
+        return "the policy on chain is bound to another wrapper";
+    }
+    const state = decodeFunctionResult({
+        abi: VAULT,
+        functionName: "state",
+        data: vaultState.returnData,
+    });
+    if (!sameAddress(state, target.state)) {
+        return "the vault answers to another State";
+    }
+    const [vaultAddress] = decodeFunctionResult({
+        abi: STATE,
+        functionName: "clientVaults",
+        data: clientVault.returnData,
+    });
+    return sameAddress(vaultAddress, target.vault)
+        ? null
+        : "State does not name the vault as the cofund's";
+}
+/** The call itself, capped at a preview's gas unless told otherwise. */
+export function txCall(target) {
+    const gas = target.gas === undefined ? SIMULATION_GAS : target.gas;
+    return {
+        ...target.tx,
+        ...(gas !== null && { gas: numberToHex(gas) }),
+    };
+}
+/** The `eth_simulateV1` parameters: one block on top of `head`, no validation, native transfers as logs. */
+export function simulateParams(head, overrides, calls) {
+    return [
+        {
+            blockStateCalls: [
+                {
+                    // Contracts that read `basefee` or `gasprice` see the chain's, not 0.
+                    ...(head.baseFeePerGas && {
+                        blockOverrides: { baseFeePerGas: head.baseFeePerGas },
+                    }),
+                    ...(overrides && { stateOverrides: overrides }),
+                    calls,
+                },
+            ],
+            validation: false,
+            traceTransfers: true,
+        },
+        head.number,
+    ];
+}

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

@@ -0,0 +1,29 @@
+import { type Abi } from "viem";
+/**
+ * `text` as a reason Cofund shows: no control or formatting characters, no
+ * URLs (an RPC URL can carry a key), whitespace collapsed, at most 200
+ * characters, and never empty.
+ */
+export declare function cleanReason(text: string): string;
+/**
+ * Anything that names a custom error from its revert data: a viem `Abi`, or a
+ * decoder with ethers' `Interface.parseError`.
+ */
+export type ErrorDecoder = Abi | {
+    parseError(data: string): {
+        name: string;
+    } | null;
+};
+/**
+ * Why `data` reverts: the revert string, the panic, a known error's name
+ * (the relay's, then the caller's own contracts' `errors`), else a short
+ * message with the selector; never the error's arguments (addresses,
+ * amounts). An unreviewed contract's (`unlisted`) own message is not shown:
+ * only an error's name, a panic or a selector.
+ */
+export declare function revertReason(data: string, { unlisted, errors, }?: {
+    unlisted?: boolean;
+    errors?: ErrorDecoder[];
+}): string;
+/** A node failure as a short, clean reason: its message, never a URL. */
+export declare function nodeFailure(error: unknown): string;

package/dist/evm/simulate/revert.js

@@ -0,0 +1,192 @@
+import { decodeAbiParameters, decodeErrorResult, hexToBytes, parseAbi, } from "viem";
+/**
+ * Why a call reverts, and what a node said, made safe to show: revert data
+ * and node messages are anyone's text, and they reach the web, email, the CLI
+ * and webhooks.
+ */
+/**
+ * The errors a relayed call can revert with, by name: the vault's and State's
+ * (their reverts bubble), the sponsor guard's, and OpenZeppelin's ERC-20,
+ * SafeERC20 and ECDSA errors.
+ */
+const RELAY_ERRORS = parseAbi([
+    "error AmountExceedsPolicy()",
+    "error ECDSAInvalidSignature()",
+    "error ECDSAInvalidSignatureLength(uint256)",
+    "error ECDSAInvalidSignatureS(bytes32)",
+    "error InactivePolicy()",
+    "error InvalidAmount()",
+    "error InvalidCompany()",
+    "error InvalidPolicyType()",
+    "error InvalidSignature()",
+    "error InvalidSigner()",
+    "error InvalidToken()",
+    "error InvalidType()",
+    "error RecipientNotAllowed()",
+    "error SafeERC20FailedOperation(address)",
+    "error ThresholdNotMet()",
+    "error UnauthorizedCaller(string)",
+    "error KeyExists()",
+    "error InactiveUser()",
+    "error InvalidPolicy()",
+    "error InvalidClient()",
+    "error CallNotAllowed()",
+    "error GuardPaused()",
+    "error InvalidCall()",
+    "error NotASponsor()",
+    "error ERC20InsufficientBalance(address,uint256,uint256)",
+    "error ERC20InsufficientAllowance(address,uint256,uint256)",
+    "error ERC20InvalidSender(address)",
+    "error ERC20InvalidReceiver(address)",
+    "error ERC20InvalidApprover(address)",
+    "error ERC20InvalidSpender(address)",
+]);
+/** `Error(string)`: a `require` or `revert` with a message. */
+const ERROR_STRING = "0x08c379a0";
+const MAX_REASON = 200;
+const URLS = /\b(?:https?|wss?):\/\/\S+/gi;
+const UNPRINTABLE = /[\p{C}]+/gu;
+const SPACES = /\s+/g;
+/**
+ * `text` as a reason Cofund shows: no control or formatting characters, no
+ * URLs (an RPC URL can carry a key), whitespace collapsed, at most 200
+ * characters, and never empty.
+ */
+export function cleanReason(text) {
+    const clean = text
+        .replace(URLS, "<link>")
+        .replace(UNPRINTABLE, " ")
+        .replace(SPACES, " ")
+        .trim()
+        .slice(0, MAX_REASON)
+        .trim();
+    return clean || "no reason given";
+}
+/** The error `data` encodes, by name, from the first decoder that knows it. */
+function errorName(data, decoders) {
+    for (const decoder of decoders) {
+        try {
+            if (Array.isArray(decoder)) {
+                return decodeErrorResult({ abi: decoder, data: data })
+                    .errorName;
+            }
+            const parsed = decoder.parseError(data);
+            if (parsed) {
+                return parsed.name;
+            }
+        }
+        catch {
+            // Not this contract's.
+        }
+    }
+    return null;
+}
+/** ethers' names for Solidity's panic codes. */
+const PANIC_REASONS = {
+    0: "GENERIC_PANIC",
+    1: "ASSERT_FALSE",
+    17: "OVERFLOW",
+    18: "DIVIDE_BY_ZERO",
+    33: "ENUM_RANGE_ERROR",
+    34: "BAD_STORAGE_DATA",
+    49: "STACK_UNDERFLOW",
+    50: "ARRAY_RANGE_ERROR",
+    65: "OUT_OF_MEMORY",
+    81: "UNINITIALIZED_FUNCTION_CALL",
+};
+const PANIC = "0x4e487b71";
+const STRICT_UTF8 = new TextDecoder("utf-8", { fatal: true });
+/**
+ * What a revert's data says on its own, as ethers reads a call exception: a
+ * `require` or `revert` message, a panic, nothing at all (`require(false)`),
+ * else a short message for data it cannot read.
+ */
+function builtinReason(data) {
+    if (!data) {
+        return { reason: null, shortMessage: "missing revert data" };
+    }
+    const bytes = hexToBytes(data);
+    const shortMessage = "execution reverted";
+    if (bytes.length === 0) {
+        return {
+            reason: "require(false)",
+            shortMessage: `${shortMessage} (no data present; likely require(false) occurred`,
+        };
+    }
+    if (bytes.length % 32 !== 4) {
+        return {
+            reason: null,
+            shortMessage: `${shortMessage} (could not decode reason; invalid data length)`,
+        };
+    }
+    const selector = data.slice(0, 10).toLowerCase();
+    const args = `0x${data.slice(10)}`;
+    if (selector === ERROR_STRING) {
+        try {
+            const [raw] = decodeAbiParameters([{ type: "bytes" }], args);
+            return { reason: STRICT_UTF8.decode(hexToBytes(raw)), shortMessage };
+        }
+        catch {
+            return {
+                reason: null,
+                shortMessage: `${shortMessage} (could not decode reason; invalid string data)`,
+            };
+        }
+    }
+    if (selector === PANIC) {
+        try {
+            const [code] = decodeAbiParameters([{ type: "uint256" }], args);
+            const n = Number(code);
+            return {
+                reason: `Panic due to ${PANIC_REASONS[n] ?? "UNKNOWN"}(${n})`,
+                shortMessage,
+            };
+        }
+        catch {
+            return {
+                reason: null,
+                shortMessage: `${shortMessage} (could not decode panic code)`,
+            };
+        }
+    }
+    return {
+        reason: null,
+        shortMessage: `${shortMessage} (unknown custom error)`,
+    };
+}
+/**
+ * Why `data` reverts: the revert string, the panic, a known error's name
+ * (the relay's, then the caller's own contracts' `errors`), else a short
+ * message with the selector; never the error's arguments (addresses,
+ * amounts). An unreviewed contract's (`unlisted`) own message is not shown:
+ * only an error's name, a panic or a selector.
+ */
+export function revertReason(data, { unlisted = false, errors = [], } = {}) {
+    const builtin = builtinReason(data);
+    const message = data.toLowerCase().startsWith(ERROR_STRING);
+    if (message && unlisted) {
+        return "reverted with a message from a contract Cofund hasn't reviewed";
+    }
+    if (builtin.reason !== null) {
+        return cleanReason(builtin.reason);
+    }
+    const name = errorName(data, [RELAY_ERRORS, ...errors]);
+    if (name) {
+        return name;
+    }
+    const selector = data.length >= 10 ? ` (${data.slice(0, 10)})` : "";
+    return cleanReason(`${builtin.shortMessage}${selector}`);
+}
+/** A node failure as a short, clean reason: its message, never a URL. */
+export function nodeFailure(error) {
+    const nested = error?.error?.message;
+    let message = String(error);
+    if (typeof nested === "string") {
+        message = nested;
+    }
+    else if (error instanceof Error) {
+        message =
+            error.shortMessage ?? error.message;
+    }
+    return cleanReason(message);
+}

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

@@ -0,0 +1,51 @@
+import type { EvmReader } from "../chain.ts";
+import { type CallEffect, type CallSimulation } from "../types.ts";
+import { type BalanceLog, type HolderRoles, type TokenInfo } from "./balances.ts";
+import { type SimulationTarget } from "./request.ts";
+/**
+ * A call's effect, simulated before anyone signs it. The call runs as it
+ * would execute with `eth_simulateV1` on top of the latest block, its
+ * signature checks skipped by the threshold override (`request.ts`), the
+ * guards read in the same block; a second request of the same block reads
+ * every touched (token, holder) balance before and after it, so the changes
+ * are exact for rebasing and fee-on-transfer tokens too. It must run the same
+ * way both times. Nothing here holds a node: Cofund's server passes its
+ * provider's, an agent its own.
+ */
+/** A JSON-RPC request to one node, as `send(method, params)`. */
+export type JsonRpcSend = (method: string, params: unknown[]) => Promise<unknown>;
+/** A node to simulate on: a reader (a viem public client, any EIP-1193 provider) or a `send`. */
+export type EvmNode = EvmReader | JsonRpcSend;
+/** `node` as a `send`. */
+export declare function nodeSend(node: EvmNode): JsonRpcSend;
+export type SimulationOptions = {
+    /** Cofund's token table: a listed token's symbol and decimals, null for any other. */
+    listedToken?: (address: string) => {
+        symbol: string;
+        decimals: number;
+    } | null;
+    /** The wrapper is one Cofund hasn't reviewed: its own revert messages are not shown. */
+    unlisted?: boolean;
+    now?: () => Date;
+};
+/**
+ * Simulate `target` on `node`: the call's balance changes, or why it
+ * reverts, or `unavailable` (the node failed, a guard did not hold, the call
+ * ran differently twice, or the result is not one the API can carry). Never
+ * throws.
+ */
+export declare function simulateCall(node: EvmNode, target: SimulationTarget, options?: SimulationOptions): Promise<CallSimulation>;
+/**
+ * What an executed call did, from its own logs (a sponsored operation's, not
+ * its bundle's): summed per holder, the tokens named by `token`. The native
+ * coin moves without a log, so its moves are not in it.
+ */
+export declare function effectFromLogs(input: {
+    logs: BalanceLog[];
+    roles: HolderRoles;
+    block: {
+        number: bigint;
+        hash: string;
+    };
+    hash: string;
+}, token: (address: string) => TokenInfo | null, now?: Date): CallEffect | null;