@getcofund/protocol 0.0.0-stage → 0.1.0

package/dist/evm/reads.js

@@ -0,0 +1,131 @@
+import { zeroAddress } from "viem";
+import { policiesAbi } from "./abis/policies.js";
+import { stateAbi } from "./abis/state.js";
+import { usersAbi } from "./abis/users.js";
+import { vaultFactoryAbi } from "./abis/vault-factory.js";
+import { readContract } from "./chain.js";
+/** `State.getUser`: null when `userId` was never seated in the cofund. */
+export async function readUser(reader, deployment, clientId, userId) {
+    const user = await readContract(reader, {
+        address: deployment.state,
+        abi: stateAbi,
+        functionName: "getUser",
+        args: [clientId, userId],
+    });
+    return user.addr === zeroAddress
+        ? null
+        : {
+            address: user.addr,
+            position: user.position,
+            isAdmin: user.isAdmin,
+            active: user.active,
+        };
+}
+/** `State.getUserIdByAddress`: the user id `address` holds in the cofund, active or not; null when none. */
+export async function readUserIdByAddress(reader, deployment, clientId, address) {
+    const userId = await readContract(reader, {
+        address: deployment.state,
+        abi: stateAbi,
+        functionName: "getUserIdByAddress",
+        args: [address, clientId],
+    });
+    return userId === "" ? null : userId;
+}
+/** `State.getPolicy`: null when no policy was ever activated under `policyId`. */
+export async function readPolicy(reader, deployment, clientId, policyId) {
+    const policy = await readContract(reader, {
+        address: deployment.state,
+        abi: stateAbi,
+        functionName: "getPolicy",
+        args: [clientId, policyId],
+    });
+    return policy.title === ""
+        ? null
+        : {
+            active: policy.active,
+            title: policy.title,
+            policyType: policy.policyType,
+            signerIds: [...policy.signerIds],
+            threshold: Number(policy.threshold),
+            transaction: { ...policy.transactionDetails },
+            transfer: {
+                maxAmount: policy.transferDetails.maxAmount,
+                token: policy.transferDetails.token,
+                recipients: [...policy.transferDetails.recipients],
+            },
+            isTransaction: policy.isTransaction,
+        };
+}
+/** `State.clientVaults`: the cofund's vault and its subscription tier; null before it is created. */
+export async function readClientVault(reader, deployment, clientId) {
+    const [vault, tier] = await readContract(reader, {
+        address: deployment.state,
+        abi: stateAbi,
+        functionName: "clientVaults",
+        args: [clientId],
+    });
+    return vault === zeroAddress ? null : { vault, tier };
+}
+/** `State.onboardingComplete`: whether the cofund's onboarding phase is closed. */
+export async function readOnboardingComplete(reader, deployment, clientId) {
+    return await readContract(reader, {
+        address: deployment.state,
+        abi: stateAbi,
+        functionName: "onboardingComplete",
+        args: [clientId],
+    });
+}
+/** `State.getActiveAdmins`: the cofund's active admins. */
+export async function readActiveAdmins(reader, deployment, clientId) {
+    return Number(await readContract(reader, {
+        address: deployment.state,
+        abi: stateAbi,
+        functionName: "getActiveAdmins",
+        args: [clientId],
+    }));
+}
+/** `State.helperContracts(kind)`: zero when none is registered. */
+export async function readHelperContract(reader, deployment, kind) {
+    return await readContract(reader, {
+        address: deployment.state,
+        abi: stateAbi,
+        functionName: "helperContracts",
+        args: [kind],
+    });
+}
+/** `State.getClientContractAuthID`: whether `authId` is spent for the cofund (one use, across every helper and the vault). */
+export async function readAuthIdSpent(reader, deployment, clientId, authId) {
+    return await readContract(reader, {
+        address: deployment.state,
+        abi: stateAbi,
+        functionName: "getClientContractAuthID",
+        args: [clientId, authId],
+    });
+}
+/** `Users.requiredAdminInviteSignatures`: admin signatures an admin seat needs, the inviter's included. */
+export async function readRequiredAdminInviteSignatures(reader, deployment, clientId) {
+    return Number(await readContract(reader, {
+        address: deployment.users,
+        abi: usersAbi,
+        functionName: "requiredAdminInviteSignatures",
+        args: [clientId],
+    }));
+}
+/** `Policies.requiredPolicyActivationSignatures`: admin signatures activating a policy of `threshold` needs. */
+export async function readRequiredPolicyActivationSignatures(reader, deployment, clientId, threshold) {
+    return Number(await readContract(reader, {
+        address: deployment.policies,
+        abi: policiesAbi,
+        functionName: "requiredPolicyActivationSignatures",
+        args: [clientId, BigInt(threshold)],
+    }));
+}
+/** `VaultFactory.predictVault`: the address a cofund's vault has, or will have once it is created. */
+export async function readPredictedVault(reader, deployment, clientId) {
+    return await readContract(reader, {
+        address: deployment.vaults,
+        abi: vaultFactoryAbi,
+        functionName: "predictVault",
+        args: [clientId],
+    });
+}

package/dist/evm/signatures.d.ts

@@ -0,0 +1,57 @@
+import { type Address, type Hex } from "viem";
+/**
+ * Recovering a signer the way the contracts do, and refusing a call the way
+ * they would.
+ */
+/**
+ * A call the contract would revert. `reason` is the error it would revert
+ * with (`ThresholdNotMet`, `InvalidSignature`, ...), the message says why.
+ */
+export declare class CallRefusedError extends Error {
+    readonly reason: string;
+    constructor(reason: string, detail: string);
+}
+/** `throw new CallRefusedError(...)`, as an expression. */
+export declare function refuse(reason: string, detail: string): never;
+/** Why OpenZeppelin's `ECDSA.tryRecover` fails a signature: its `RecoverError`. */
+export type RecoverFailure = "InvalidSignatureLength" | "InvalidSignatureS" | "InvalidSignature";
+/**
+ * The address `signature` recovers to over `digest`, as OpenZeppelin's
+ * `ECDSA.tryRecover` decides it: 65 bytes `r ‖ s ‖ v`, `v` 27 or 28, `s` in
+ * the lower half, and a point `ecrecover` accepts. EIP-2098 compact
+ * signatures are refused, as the contracts refuse them.
+ */
+export declare function tryRecover(digest: Hex, signature: string): Promise<{
+    signer: Address;
+} | {
+    failure: RecoverFailure;
+}>;
+/**
+ * How a contract names a signature `tryRecover` fails: the helpers map every
+ * failure to their own `InvalidSignature()`; the vault uses `ECDSA.recover`,
+ * which reverts with OpenZeppelin's own `ECDSA…` errors.
+ */
+export type RecoverErrors = "helper" | "vault";
+/** The signer of `signature` over `digest`, or the contract's refusal. `what` names the signature. */
+export declare function recoverSigner(digest: Hex, signature: string, { what, errors }: {
+    what: string;
+    errors?: RecoverErrors;
+}): Promise<Address>;
+/** A signature and the address it recovers to. */
+export type SignedBy = {
+    signature: Hex;
+    signer: Address;
+};
+/**
+ * `signatures` in the order the contracts walk them: strictly ascending by
+ * recovered address, which is also their uniqueness check (`signer <= prev`
+ * reverts `InvalidSignature`). The order is derived here, never assumed from
+ * the order the signatures were collected in; two from one signer are
+ * refused.
+ */
+export declare function ascendingSigners(digest: Hex, signatures: readonly string[], { what, errors }: {
+    what: string;
+    errors?: RecoverErrors;
+}): Promise<SignedBy[]>;
+/** Address order as Solidity compares `address` values: numerically. */
+export declare function compareAddresses(a: string, b: string): number;

package/dist/evm/signatures.js

@@ -0,0 +1,105 @@
+import { recoverAddress } from "viem";
+/**
+ * Recovering a signer the way the contracts do, and refusing a call the way
+ * they would.
+ */
+/**
+ * A call the contract would revert. `reason` is the error it would revert
+ * with (`ThresholdNotMet`, `InvalidSignature`, ...), the message says why.
+ */
+export class CallRefusedError extends Error {
+    reason;
+    constructor(reason, detail) {
+        super(`${reason}: ${detail}`);
+        this.name = "CallRefusedError";
+        this.reason = reason;
+    }
+}
+/** `throw new CallRefusedError(...)`, as an expression. */
+export function refuse(reason, detail) {
+    throw new CallRefusedError(reason, detail);
+}
+/** 65 bytes of hex: `r ‖ s ‖ v`. */
+const SIGNATURE = /^0x[0-9a-fA-F]{130}$/;
+/** secp256k1's n / 2: OpenZeppelin's ECDSA refuses an `s` above it (malleability). */
+const HALF_ORDER = 0x7fffffffffffffffffffffffffffffff5d576e7357a4501ddfe92f46681b20a0n;
+/**
+ * The address `signature` recovers to over `digest`, as OpenZeppelin's
+ * `ECDSA.tryRecover` decides it: 65 bytes `r ‖ s ‖ v`, `v` 27 or 28, `s` in
+ * the lower half, and a point `ecrecover` accepts. EIP-2098 compact
+ * signatures are refused, as the contracts refuse them.
+ */
+export async function tryRecover(digest, signature) {
+    if (!SIGNATURE.test(signature)) {
+        return { failure: "InvalidSignatureLength" };
+    }
+    const s = BigInt(`0x${signature.slice(66, 130)}`);
+    const v = Number.parseInt(signature.slice(130, 132), 16);
+    if (s > HALF_ORDER) {
+        return { failure: "InvalidSignatureS" };
+    }
+    if (v !== 27 && v !== 28) {
+        return { failure: "InvalidSignature" };
+    }
+    try {
+        return {
+            signer: await recoverAddress({
+                hash: digest,
+                signature: signature,
+            }),
+        };
+    }
+    catch {
+        return { failure: "InvalidSignature" };
+    }
+}
+const VAULT_ERRORS = {
+    InvalidSignatureLength: "ECDSAInvalidSignatureLength",
+    InvalidSignatureS: "ECDSAInvalidSignatureS",
+    InvalidSignature: "ECDSAInvalidSignature",
+};
+/** The signer of `signature` over `digest`, or the contract's refusal. `what` names the signature. */
+export async function recoverSigner(digest, signature, { what, errors = "helper" }) {
+    const recovered = await tryRecover(digest, signature);
+    if ("failure" in recovered) {
+        const detail = {
+            InvalidSignatureLength: `${what} is not a 65-byte signature`,
+            InvalidSignatureS: `${what} has a high s value (malleable)`,
+            InvalidSignature: `${what} does not recover to an address`,
+        }[recovered.failure];
+        return refuse(errors === "vault" ? VAULT_ERRORS[recovered.failure] : "InvalidSignature", detail);
+    }
+    return recovered.signer;
+}
+/**
+ * `signatures` in the order the contracts walk them: strictly ascending by
+ * recovered address, which is also their uniqueness check (`signer <= prev`
+ * reverts `InvalidSignature`). The order is derived here, never assumed from
+ * the order the signatures were collected in; two from one signer are
+ * refused.
+ */
+export async function ascendingSigners(digest, signatures, { what, errors = "helper" }) {
+    const signed = await Promise.all(signatures.map(async (signature, i) => ({
+        signature: signature,
+        signer: await recoverSigner(digest, signature, {
+            what: `${what} ${i + 1}`,
+            errors,
+        }),
+    })));
+    signed.sort((a, b) => compareAddresses(a.signer, b.signer));
+    for (let i = 1; i < signed.length; i += 1) {
+        if (compareAddresses(signed[i - 1].signer, signed[i].signer) === 0) {
+            refuse("InvalidSignature", `${signed[i].signer} signed twice`);
+        }
+    }
+    return signed;
+}
+/** Address order as Solidity compares `address` values: numerically. */
+export function compareAddresses(a, b) {
+    const x = BigInt(a);
+    const y = BigInt(b);
+    if (x === y) {
+        return 0;
+    }
+    return x < y ? -1 : 1;
+}

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

@@ -0,0 +1,76 @@
+import { z } from "zod";
+import { type BalanceChange } from "../types.ts";
+/**
+ * Logs to balances: which (asset, holder) pairs a call moves, netted, the
+ * vault's first, and the tokens' own claims about themselves.
+ */
+/** How `traceTransfers` and this module name the native coin. */
+export declare const NATIVE_ASSET = "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee";
+/** The most (token, holder) balances one simulation reads exactly. */
+export declare const MAX_SIMULATED_BALANCES = 50;
+/** A JSON-RPC quantity: 0x and hex digits. */
+export declare const RpcQuantity: z.ZodString;
+/** A log as a node returns it. */
+export declare const RpcLogSchema: z.ZodObject<{
+    address: z.ZodString;
+    topics: z.ZodArray<z.ZodString>;
+    data: z.ZodString;
+}, z.core.$strip>;
+export type BalanceLog = z.infer<typeof RpcLogSchema>;
+/** One holder's net movement in one asset (`NATIVE_ASSET` for the native coin), lowercased. */
+export type NetBalance = {
+    asset: string;
+    holder: string;
+    delta: bigint;
+};
+/** Whose balance it is: the vault, the call's wrapper, or anyone else. */
+export type HolderRoles = {
+    vault: string;
+    wrapper: string;
+};
+/** A token's name and decimals, and whether they are Cofund's listing or its own claim. */
+export type TokenInfo = {
+    symbol: string | null;
+    decimals: number | null;
+    listed: boolean;
+};
+/**
+ * Every balance the logs move, netted per (asset, holder) in first-seen order:
+ * an ERC-20 `Transfer` (3 topics, one word of data) or `traceTransfers`'
+ * native one moves both ends (not the zero address: a mint or burn); a
+ * WETH-style `Deposit` mints to its `dst` and `Withdrawal` burns from its
+ * `src`. An ERC-721 `Transfer` (4 topics) or an ERC-1155 event leaves the
+ * result `incomplete`: NFTs are not counted. Zero nets are kept here: a
+ * touched balance can still change (a rebasing token), which the exact pass
+ * reads.
+ */
+export declare function decodeBalanceLogs(logs: BalanceLog[]): {
+    balances: NetBalance[];
+    incomplete: boolean;
+};
+/** The vault's first, then the wrapper's, then everyone else's, each as they came. */
+export declare function byRole<T extends {
+    role: BalanceChange["role"];
+}>(items: T[]): T[];
+/** The most balances read exactly: the vault's and the wrapper's before anyone else's. */
+export declare function capBalances(balances: NetBalance[], roles: HolderRoles): {
+    kept: NetBalance[];
+    dropped: boolean;
+};
+/** The changes to report: non-zero nets, each with its role and asset, the vault first. */
+export declare function toChanges(balances: NetBalance[], roles: HolderRoles, token: (address: string) => TokenInfo | null): BalanceChange[];
+/** The `balanceOf`, `symbol()` and `decimals()` reads a pass makes. */
+export declare const tokenReads: {
+    balanceOf: (holder: string) => `0x${string}`;
+    symbol: `0x${string}`;
+    decimals: `0x${string}`;
+};
+/** A token's own `symbol()`: a plain symbol, or null (a bytes32 one, NUL-padded, is read too). */
+export declare function claimedSymbol(data: string): string | null;
+/** A token's own `decimals()`, or null when it is not one. */
+export declare function claimedDecimals(data: string): number | null;
+/** A balance read's value, or null when the read failed or is not a word. */
+export declare function balanceOf(result: {
+    status: string;
+    returnData: string;
+}): bigint | null;

package/dist/evm/simulate/balances.js

@@ -0,0 +1,201 @@
+import { decodeFunctionResult, encodeFunctionData, getAddress, hexToBytes, parseAbi, size, sliceHex, toEventSelector, zeroAddress, } from "viem";
+import { z } from "zod";
+import { sameAddress } from "../address.js";
+import { Address, Bytes32, Hex, TokenDecimals, TokenSymbol, } from "../types.js";
+/**
+ * Logs to balances: which (asset, holder) pairs a call moves, netted, the
+ * vault's first, and the tokens' own claims about themselves.
+ */
+/** How `traceTransfers` and this module name the native coin. */
+export const NATIVE_ASSET = "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee";
+/** The most (token, holder) balances one simulation reads exactly. */
+export const MAX_SIMULATED_BALANCES = 50;
+const TRANSFER = toEventSelector("Transfer(address,address,uint256)");
+const DEPOSIT = toEventSelector("Deposit(address,uint256)");
+const WITHDRAWAL = toEventSelector("Withdrawal(address,uint256)");
+const TRANSFER_SINGLE = toEventSelector("TransferSingle(address,address,address,uint256,uint256)");
+const TRANSFER_BATCH = toEventSelector("TransferBatch(address,address,address,uint256[],uint256[])");
+const ERC20 = parseAbi([
+    "function balanceOf(address) view returns (uint256)",
+    "function symbol() view returns (string)",
+    "function decimals() view returns (uint8)",
+]);
+/** Invalid UTF-8 is no symbol: refused, not replaced. */
+const STRICT_UTF8 = new TextDecoder("utf-8", { fatal: true });
+/** A JSON-RPC quantity: 0x and hex digits. */
+export const RpcQuantity = z
+    .string()
+    .regex(/^0x[0-9a-fA-F]{1,64}$/, "a hex quantity");
+/** A log as a node returns it. */
+export const RpcLogSchema = z.object({
+    address: Address,
+    topics: z.array(Bytes32).max(4),
+    data: Hex,
+});
+const topicAddress = (topic) => sliceHex(topic, 12).toLowerCase();
+const isWord = (data) => size(data) === 32;
+/**
+ * Every balance the logs move, netted per (asset, holder) in first-seen order:
+ * an ERC-20 `Transfer` (3 topics, one word of data) or `traceTransfers`'
+ * native one moves both ends (not the zero address: a mint or burn); a
+ * WETH-style `Deposit` mints to its `dst` and `Withdrawal` burns from its
+ * `src`. An ERC-721 `Transfer` (4 topics) or an ERC-1155 event leaves the
+ * result `incomplete`: NFTs are not counted. Zero nets are kept here: a
+ * touched balance can still change (a rebasing token), which the exact pass
+ * reads.
+ */
+export function decodeBalanceLogs(logs) {
+    const net = new Map();
+    let incomplete = false;
+    for (const log of logs) {
+        const moves = logMoves(log);
+        if (moves === "nft") {
+            incomplete = true;
+            continue;
+        }
+        for (const { asset, holder, delta } of moves) {
+            if (holder === zeroAddress) {
+                continue;
+            }
+            const key = `${asset}|${holder}`;
+            const entry = net.get(key) ?? { asset, holder, delta: 0n };
+            entry.delta += delta;
+            net.set(key, entry);
+        }
+    }
+    return { balances: [...net.values()], incomplete };
+}
+/** The balances one log moves; "nft" for an NFT's, none for any other log. */
+function logMoves(log) {
+    const [topic, ...indexed] = log.topics.map((t) => t.toLowerCase());
+    const asset = log.address.toLowerCase();
+    if (topic === TRANSFER_SINGLE || topic === TRANSFER_BATCH) {
+        return "nft";
+    }
+    if (topic === TRANSFER && indexed.length === 3) {
+        return "nft";
+    }
+    if (!isWord(log.data)) {
+        return [];
+    }
+    const amount = BigInt(log.data);
+    if (topic === TRANSFER && indexed.length === 2) {
+        return [
+            { asset, holder: topicAddress(indexed[0]), delta: -amount },
+            { asset, holder: topicAddress(indexed[1]), delta: amount },
+        ];
+    }
+    const mint = topic === DEPOSIT ? amount : null;
+    const delta = topic === WITHDRAWAL ? -amount : mint;
+    return delta !== null && indexed.length === 1
+        ? [{ asset, holder: topicAddress(indexed[0]), delta }]
+        : [];
+}
+const roleOf = (holder, roles) => {
+    if (sameAddress(holder, roles.vault)) {
+        return "vault";
+    }
+    return sameAddress(holder, roles.wrapper) ? "wrapper" : "other";
+};
+const ROLE_ORDER = {
+    vault: 0,
+    wrapper: 1,
+    other: 2,
+};
+/** The vault's first, then the wrapper's, then everyone else's, each as they came. */
+export function byRole(items) {
+    return items
+        .map((item, i) => ({ item, i }))
+        .sort((a, b) => ROLE_ORDER[a.item.role] - ROLE_ORDER[b.item.role] || a.i - b.i)
+        .map(({ item }) => item);
+}
+/** The most balances read exactly: the vault's and the wrapper's before anyone else's. */
+export function capBalances(balances, roles) {
+    const ordered = byRole(balances.map((b) => ({ ...b, role: roleOf(b.holder, roles) })));
+    return {
+        kept: ordered.slice(0, MAX_SIMULATED_BALANCES),
+        dropped: ordered.length > MAX_SIMULATED_BALANCES,
+    };
+}
+/** The changes to report: non-zero nets, each with its role and asset, the vault first. */
+export function toChanges(balances, roles, token) {
+    return byRole(balances
+        .filter(({ delta }) => delta !== 0n)
+        .map(({ asset, holder, delta }) => ({
+        holder: getAddress(holder),
+        role: roleOf(holder, roles),
+        asset: asset === NATIVE_ASSET
+            ? { kind: "native" }
+            : {
+                kind: "erc20",
+                address: getAddress(asset),
+                ...(token(asset) ?? {
+                    symbol: null,
+                    decimals: null,
+                    listed: false,
+                }),
+            },
+        delta: delta.toString(),
+    })));
+}
+/** The `balanceOf`, `symbol()` and `decimals()` reads a pass makes. */
+export const tokenReads = {
+    balanceOf: (holder) => encodeFunctionData({
+        abi: ERC20,
+        functionName: "balanceOf",
+        args: [holder],
+    }),
+    symbol: encodeFunctionData({ abi: ERC20, functionName: "symbol" }),
+    decimals: encodeFunctionData({ abi: ERC20, functionName: "decimals" }),
+};
+/** `symbol()`'s result as the bytes a `string` is encoded as. */
+const BYTES_RESULT = parseAbi(["function symbol() view returns (bytes)"]);
+/** A token's own `symbol()`: a plain symbol, or null (a bytes32 one, NUL-padded, is read too). */
+export function claimedSymbol(data) {
+    let symbol = null;
+    try {
+        // Read as bytes, so invalid UTF-8 is refused rather than replaced.
+        const raw = decodeFunctionResult({
+            abi: BYTES_RESULT,
+            functionName: "symbol",
+            data: data,
+        });
+        symbol = STRICT_UTF8.decode(hexToBytes(raw));
+    }
+    catch {
+        if (isWord(data)) {
+            const bytes = hexToBytes(data);
+            const end = bytes.indexOf(0);
+            try {
+                symbol = STRICT_UTF8.decode(end === -1 ? bytes : bytes.slice(0, end));
+            }
+            catch {
+                symbol = null;
+            }
+        }
+    }
+    return symbol !== null && TokenSymbol.safeParse(symbol).success
+        ? symbol
+        : null;
+}
+/** A token's own `decimals()`, or null when it is not one. */
+export function claimedDecimals(data) {
+    try {
+        const decimals = decodeFunctionResult({
+            abi: ERC20,
+            functionName: "decimals",
+            data: data,
+        });
+        const parsed = TokenDecimals.safeParse(Number(decimals));
+        return parsed.success ? parsed.data : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** A balance read's value, or null when the read failed or is not a word. */
+export function balanceOf(result) {
+    return BigInt(result.status) === 1n && isWord(result.returnData)
+        ? BigInt(result.returnData)
+        : null;
+}

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

@@ -0,0 +1,79 @@
+import { type BalanceChange, type CallEffect, type CallSimulation } from "../types.ts";
+import type { TokenInfo } from "./balances.ts";
+/**
+ * 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 declare const NATIVE_SYMBOL = "ETH";
+/** A token's name and decimals by address, null when unknown. */
+export type TokenLookup = (address: string) => TokenInfo | null;
+/** Base units as a decimal amount, in a surface's own format. */
+export type AmountFormat = (units: bigint, decimals: number) => string;
+/**
+ * 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 declare const formatUnitsAmount: AmountFormat;
+/**
+ * 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 declare function assetLabel(asset: BalanceChange["asset"]): string;
+/** "Vault", "Wrapper", or the holder's address. */
+export declare function holderLabel(change: Pick<BalanceChange, "holder" | "role">): string;
+/** A change as a signed amount with its asset; none as "no change in" it. */
+export declare function formatDelta(change: Pick<BalanceChange, "asset" | "delta">, format: AmountFormat, { withAddress }?: {
+    withAddress?: boolean;
+}): string;
+/** One holder and its changes. */
+export type HolderEffect = {
+    holder: string;
+    role: BalanceChange["role"];
+    changes: BalanceChange[];
+};
+/** The changes per holder, the vault first, then the wrapper, then the others as they came. */
+export declare function changesByHolder(changes: BalanceChange[]): HolderEffect[];
+/** The vault's own changes in a successful simulation; none otherwise. */
+export declare function vaultChanges(simulation: CallSimulation | null | undefined): BalanceChange[];
+/** The tokens simulations named, by address: a listing over a token's claim, a claim with decimals over one without. */
+export declare function simulationTokens(...simulations: (CallSimulation | CallEffect | null | undefined)[]): TokenLookup;
+/**
+ * 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 declare function allowanceBound(allowances: {
+    asset: string;
+    amount: string;
+}[] | null, tokens: TokenLookup, format: AmountFormat): string;
+/** What every surface says after the effect: the caveat, and on an unlisted wrapper its warning. */
+export declare function simulationCaveat(unlisted: boolean): string[];
+/** "2026-10-15 14:00 UTC". */
+export declare function utcDateTime(iso: string): string;
+/** A simulation or an executed effect as every surface lays it out. */
+export type SimulationView = {
+    status: "success" | "revert" | "unavailable" | "executed";
+    /** The block it ran on top of (or landed in); null when unavailable. */
+    block: string | null;
+    at: string;
+    /** Each holder's changes, the vault first. */
+    holders: {
+        label: string;
+        address: string;
+        role: BalanceChange["role"];
+        changes: string[];
+    }[];
+    /** Why it would fail, why it could not be simulated, or that nothing moves. */
+    notice: string | null;
+    /** What it does not show. */
+    notes: string[];
+};
+/** `simulation` (or what an executed call did) described, amounts in `format`. */
+export declare function describeSimulation(simulation: CallSimulation | CallEffect, format: AmountFormat, { withAddress }?: {
+    withAddress?: boolean;
+}): SimulationView;