@getcofund/protocol 0.0.0 → 0.1.0

package/dist/evm/simulate/run.js

@@ -0,0 +1,214 @@
+import { z } from "zod";
+import { Bytes32, CallEffectSchema, CallSimulationSchema, Hex, } from "../types.js";
+import { balanceOf, capBalances, claimedDecimals, claimedSymbol, decodeBalanceLogs, NATIVE_ASSET, RpcLogSchema, RpcQuantity, toChanges, tokenReads, } from "./balances.js";
+import { guardFailure, guardsOf, simulateParams, txCall, } from "./request.js";
+import { cleanReason, nodeFailure, revertReason } from "./revert.js";
+/** `node` as a `send`. */
+export function nodeSend(node) {
+    return typeof node === "function"
+        ? node
+        : (method, params) => node.request({ method, params });
+}
+const SimulatedCallResult = z.object({
+    status: RpcQuantity,
+    returnData: Hex,
+    gasUsed: RpcQuantity,
+    logs: z.array(RpcLogSchema).default([]),
+    error: z
+        .object({
+        message: z.string().max(10_000).optional(),
+        data: Hex.optional(),
+    })
+        .loose()
+        .optional(),
+});
+const SimulateResult = z
+    .array(z.object({ calls: z.array(SimulatedCallResult) }).loose())
+    .length(1);
+const BlockHead = z
+    .object({
+    number: RpcQuantity,
+    hash: Bytes32,
+    baseFeePerGas: RpcQuantity.optional(),
+})
+    .loose();
+const unavailable = (reason) => ({
+    outcome: "unavailable",
+    reason,
+});
+/**
+ * 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 async function simulateCall(node, target, options = {}) {
+    const at = (options.now?.() ?? new Date()).toISOString();
+    let outcome;
+    try {
+        outcome = await run(nodeSend(node), target, options);
+    }
+    catch (error) {
+        outcome = unavailable(nodeFailure(error));
+    }
+    const parsed = CallSimulationSchema.safeParse({ ...outcome, at });
+    return parsed.success
+        ? parsed.data
+        : {
+            outcome: "unavailable",
+            at,
+            reason: "the simulation's result could not be reported",
+        };
+}
+async function run(send, target, options) {
+    const head = BlockHead.parse(await send("eth_getBlockByNumber", ["latest", false]));
+    const block = { number: BigInt(head.number).toString(), hash: head.hash };
+    const { overrides, guards } = guardsOf(target);
+    const pass = { head, overrides, guards };
+    const first = await simulateBlock(send, pass, [
+        ...pass.guards,
+        txCall(target),
+    ]);
+    const failure = guardFailure(target, first);
+    if (failure) {
+        return unavailable(failure);
+    }
+    const result = first[pass.guards.length];
+    if (!result) {
+        return unavailable("the node returned no result for the call");
+    }
+    if (BigInt(result.status) !== 1n) {
+        return { outcome: "revert", block, reason: reasonOf(result, options) };
+    }
+    const roles = { vault: target.vault, wrapper: target.wrapper };
+    const decoded = decodeBalanceLogs(result.logs);
+    const { kept, dropped } = capBalances(decoded.balances, roles);
+    const exact = await exactPass({ send, target, pass, options }, kept, result.logs);
+    if (typeof exact === "string") {
+        return unavailable(exact);
+    }
+    return {
+        outcome: "success",
+        block,
+        gasUsed: BigInt(result.gasUsed).toString(),
+        changes: toChanges(exact.balances, roles, exact.token),
+        incomplete: decoded.incomplete || dropped || exact.incomplete,
+    };
+}
+/** Why a simulated call reverted: its revert data decoded, else the node's message (out of gas). */
+function reasonOf(result, { unlisted }) {
+    const data = result.returnData !== "0x"
+        ? result.returnData
+        : (result.error?.data ?? "0x");
+    if (data === "0x" && result.error?.message) {
+        return cleanReason(result.error.message);
+    }
+    return revertReason(data, { unlisted });
+}
+async function simulateBlock(send, pass, calls) {
+    const [blockResult] = SimulateResult.parse(await send("eth_simulateV1", simulateParams(pass.head, pass.overrides, calls)));
+    return blockResult.calls;
+}
+const sameLogs = (a, b) => a.length === b.length &&
+    a.every((log, i) => log.address.toLowerCase() === b[i].address.toLowerCase() &&
+        log.data.toLowerCase() === b[i].data.toLowerCase() &&
+        log.topics.join().toLowerCase() === b[i].topics.join().toLowerCase());
+/**
+ * The same block again with every kept ERC-20 balance read before and after
+ * the call, and the unlisted tokens' own symbol and decimals: the deltas are
+ * these reads. A native balance is its transfers' net, which is exact. A
+ * balance that cannot be read keeps its logs' net, and marks it incomplete.
+ * Why not, when the guards fail or the call does not run as it did.
+ */
+async function exactPass({ send, target, pass, options }, kept, logs) {
+    const from = target.tx.from;
+    const erc20 = kept.filter(({ asset }) => asset !== NATIVE_ASSET);
+    const unlisted = [
+        ...new Set(erc20.map(({ asset }) => asset).filter((a) => !options.listedToken?.(a))),
+    ];
+    const meta = unlisted.flatMap((token) => [
+        { from, to: token, data: tokenReads.symbol },
+        { from, to: token, data: tokenReads.decimals },
+    ]);
+    const reads = erc20.map(({ asset, holder }) => ({
+        from,
+        to: asset,
+        data: tokenReads.balanceOf(holder),
+    }));
+    const results = await simulateBlock(send, pass, [
+        ...pass.guards,
+        ...meta,
+        ...reads,
+        txCall(target),
+        ...reads,
+    ]);
+    const callAt = pass.guards.length + meta.length + reads.length;
+    const call = results[callAt];
+    if (guardFailure(target, results) ||
+        !call ||
+        BigInt(call.status) !== 1n ||
+        !sameLogs(call.logs, logs)) {
+        return "the call did not run the same way twice in one block";
+    }
+    const claims = new Map(unlisted.map((token, i) => {
+        const [symbol, decimals] = results.slice(pass.guards.length + 2 * i, pass.guards.length + 2 * i + 2);
+        return [
+            token,
+            {
+                symbol: BigInt(symbol.status) === 1n
+                    ? claimedSymbol(symbol.returnData)
+                    : null,
+                decimals: BigInt(decimals.status) === 1n
+                    ? claimedDecimals(decimals.returnData)
+                    : null,
+                listed: false,
+            },
+        ];
+    }));
+    let incomplete = false;
+    const exact = new Map();
+    erc20.forEach(({ asset, holder }, i) => {
+        const before = balanceOf(results[callAt - reads.length + i]);
+        const after = balanceOf(results[callAt + 1 + i]);
+        if (before === null || after === null) {
+            incomplete = true;
+        }
+        else {
+            exact.set(`${asset}|${holder}`, after - before);
+        }
+    });
+    return {
+        balances: kept.map((b) => ({
+            ...b,
+            delta: exact.get(`${b.asset}|${b.holder}`) ?? b.delta,
+        })),
+        token: (address) => {
+            const listed = options.listedToken?.(address);
+            return listed
+                ? { ...listed, listed: true }
+                : (claims.get(address) ?? {
+                    symbol: null,
+                    decimals: null,
+                    listed: false,
+                });
+        },
+        incomplete,
+    };
+}
+/**
+ * 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 function effectFromLogs(input, token, now = new Date()) {
+    const decoded = decodeBalanceLogs(input.logs);
+    const { kept, dropped } = capBalances(decoded.balances, input.roles);
+    const parsed = CallEffectSchema.safeParse({
+        at: now.toISOString(),
+        block: { number: input.block.number.toString(), hash: input.block.hash },
+        hash: input.hash,
+        changes: toChanges(kept, input.roles, token),
+        incomplete: decoded.incomplete || dropped,
+    });
+    return parsed.success ? parsed.data : null;
+}

package/dist/evm/stocks/decode-stock-swap.d.ts

@@ -0,0 +1,32 @@
+/**
+ * HOOD: read a StockSwap protocol call back from its signed instructions, so
+ * the Requests table, the review drawer and the emails can say "Buy TSLA with
+ * 2.50 USDG" instead of "StockSwap · N/A". Pure: no server imports, so the
+ * client-side table can use it too.
+ */
+export type DecodedStockSwap = {
+    side: "buy" | "sell";
+    symbol: string;
+    /** Issuer name from the pool table, or null for an unknown token. */
+    name: string | null;
+    /** Base units: USDG (6 dec) on a buy, shares (18 dec) on a sell. */
+    amountIn: string;
+    /** Base units: shares on a buy, USDG on a sell. */
+    minOut: string;
+};
+/** Null when the payload is not a wrapper swap (foreign protocol, bad hex). */
+export declare function decodeStockSwap(instructions: unknown): DecodedStockSwap | null;
+export type StockSwapCopy = {
+    /** "Buy TSLA with 2.50 USDG" / "Sell 0.007 TSLA for USDG". */
+    title: string;
+    /** "Buy" / "Sell". */
+    action: string;
+    /** What leaves the vault: the USDG on a buy, the shares on a sell. */
+    amountLabel: string;
+    rows: {
+        label: string;
+        value: string;
+    }[];
+};
+/** Plain-English copy for a decoded swap, shared by table, drawer and mail. */
+export declare function describeStockSwap(swap: DecodedStockSwap): StockSwapCopy;

package/dist/evm/stocks/decode-stock-swap.js

@@ -0,0 +1,79 @@
+import { decodeAbiParameters, formatUnits } from "viem";
+import { SWAP_PARAMS } from "./encode-swap.js";
+import { STOCK_POOLS, STOCK_SWAP_SLIPPAGE_BPS, STOCK_TOKEN_DECIMALS, USDG, } from "./stock-pools.js";
+function poolForToken(address) {
+    const lower = address.toLowerCase();
+    return Object.values(STOCK_POOLS).find((p) => p.address.toLowerCase() === lower);
+}
+/** Null when the payload is not a wrapper swap (foreign protocol, bad hex). */
+export function decodeStockSwap(instructions) {
+    if (typeof instructions !== "string") {
+        return null;
+    }
+    try {
+        const [tokenIn, tokenOut, amountIn, minOut] = decodeAbiParameters(SWAP_PARAMS, instructions);
+        const isBuy = String(tokenIn).toLowerCase() === USDG.address.toLowerCase();
+        const pool = poolForToken(String(isBuy ? tokenOut : tokenIn));
+        return {
+            side: isBuy ? "buy" : "sell",
+            symbol: pool?.symbol ?? "?",
+            name: pool?.name ?? null,
+            amountIn: String(amountIn),
+            minOut: String(minOut),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function usdgLabel(units) {
+    const value = Number(formatUnits(BigInt(units), USDG.decimals));
+    return `${value.toLocaleString("en-US", {
+        minimumFractionDigits: 2,
+        maximumFractionDigits: 2,
+    })} ${USDG.symbol}`;
+}
+function sharesLabel(units, symbol) {
+    const value = Number(formatUnits(BigInt(units), STOCK_TOKEN_DECIMALS));
+    return `${value.toLocaleString("en-US", { maximumFractionDigits: 4 })} ${symbol}`;
+}
+/** Plain-English copy for a decoded swap, shared by table, drawer and mail. */
+export function describeStockSwap(swap) {
+    const slippage = `${STOCK_SWAP_SLIPPAGE_BPS / 100}% slippage`;
+    const stock = swap.name ? `${swap.symbol} · ${swap.name}` : swap.symbol;
+    const venue = "Uniswap v4 · Robinhood Chain";
+    if (swap.side === "buy") {
+        const pay = usdgLabel(swap.amountIn);
+        return {
+            title: `Buy ${swap.symbol} with ${pay}`,
+            action: "Buy",
+            amountLabel: pay,
+            rows: [
+                { label: "Action", value: "Buy" },
+                { label: "Stock", value: stock },
+                { label: "You pay", value: pay },
+                {
+                    label: "Minimum received",
+                    value: `${sharesLabel(swap.minOut, swap.symbol)} (${slippage})`,
+                },
+                { label: "Venue", value: venue },
+            ],
+        };
+    }
+    const sell = sharesLabel(swap.amountIn, swap.symbol);
+    return {
+        title: `Sell ${sell} for ${USDG.symbol}`,
+        action: "Sell",
+        amountLabel: sell,
+        rows: [
+            { label: "Action", value: "Sell" },
+            { label: "Stock", value: stock },
+            { label: "You sell", value: sell },
+            {
+                label: "Minimum received",
+                value: `${usdgLabel(swap.minOut)} (${slippage})`,
+            },
+            { label: "Venue", value: venue },
+        ],
+    };
+}

package/dist/evm/stocks/encode-swap.d.ts

@@ -0,0 +1,45 @@
+import { type Hex } from "viem";
+import { type StockPool } from "./stock-pools.ts";
+/**
+ * HOOD: instruction encoding for `GroupCashSwapWrapperV4.routerWrapper`.
+ * The wrapper decodes exactly
+ *   (address tokenIn, address tokenOut, uint256 amountIn, uint256 minOut,
+ *    uint24 fee, int24 tickSpacing)
+ * pulls `amountIn` of tokenIn from the calling vault, swaps on the v4 pool
+ * identified by (fee, tickSpacing) and reverts unless the vault receives at
+ * least `minOut`. The approvers therefore sign the economic bounds, not a
+ * price.
+ */
+export type SwapSide = "buy" | "sell";
+/** The wrapper's six-field instructions. */
+export declare const SWAP_PARAMS: readonly [{
+    readonly type: "address";
+}, {
+    readonly type: "address";
+}, {
+    readonly type: "uint256";
+}, {
+    readonly type: "uint256";
+}, {
+    readonly type: "uint24";
+}, {
+    readonly type: "int24";
+}];
+export type SwapLegs = {
+    tokenIn: string;
+    tokenOut: string;
+    decimalsIn: number;
+    decimalsOut: number;
+};
+/** Which token goes in and out for a buy (USDG -> stock) or sell. */
+export declare function swapLegs(pool: StockPool, side: SwapSide): SwapLegs;
+export declare function encodeV4SwapInstructions(params: {
+    tokenIn: string;
+    tokenOut: string;
+    amountIn: bigint;
+    minOut: bigint;
+    fee: number;
+    tickSpacing: number;
+}): Hex;
+/** Minimum acceptable output for a quoted amount, floored. */
+export declare function applySlippage(amountOut: bigint, bps?: number): bigint;

package/dist/evm/stocks/encode-swap.js

@@ -0,0 +1,45 @@
+import { encodeAbiParameters } from "viem";
+import { STOCK_SWAP_SLIPPAGE_BPS, STOCK_TOKEN_DECIMALS, USDG, } from "./stock-pools.js";
+/** The wrapper's six-field instructions. */
+export const SWAP_PARAMS = [
+    { type: "address" },
+    { type: "address" },
+    { type: "uint256" },
+    { type: "uint256" },
+    { type: "uint24" },
+    { type: "int24" },
+];
+/** Which token goes in and out for a buy (USDG -> stock) or sell. */
+export function swapLegs(pool, side) {
+    if (side === "buy") {
+        return {
+            tokenIn: USDG.address,
+            tokenOut: pool.address,
+            decimalsIn: USDG.decimals,
+            decimalsOut: STOCK_TOKEN_DECIMALS,
+        };
+    }
+    return {
+        tokenIn: pool.address,
+        tokenOut: USDG.address,
+        decimalsIn: STOCK_TOKEN_DECIMALS,
+        decimalsOut: USDG.decimals,
+    };
+}
+export function encodeV4SwapInstructions(params) {
+    if (params.amountIn <= 0n || params.minOut <= 0n) {
+        throw new Error("Swap amounts must be positive");
+    }
+    return encodeAbiParameters(SWAP_PARAMS, [
+        params.tokenIn,
+        params.tokenOut,
+        params.amountIn,
+        params.minOut,
+        params.fee,
+        params.tickSpacing,
+    ]);
+}
+/** Minimum acceptable output for a quoted amount, floored. */
+export function applySlippage(amountOut, bps = STOCK_SWAP_SLIPPAGE_BPS) {
+    return amountOut - (amountOut * BigInt(bps)) / 10000n;
+}

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

@@ -0,0 +1,9 @@
+/**
+ * The StockSwap verb on Robinhood Chain: the pool table, the wrapper's
+ * instruction encoder and decoder, and the quote. Shared by the webapp and the
+ * SDK, so a request the app shows and one the CLI signs decode the same way.
+ */
+export * from "./decode-stock-swap.ts";
+export * from "./encode-swap.ts";
+export * from "./quote.ts";
+export * from "./stock-pools.ts";

package/dist/evm/stocks/index.js

@@ -0,0 +1,10 @@
+/**
+ * The StockSwap verb on Robinhood Chain: the pool table, the wrapper's
+ * instruction encoder and decoder, and the quote. Shared by the webapp and the
+ * SDK, so a request the app shows and one the CLI signs decode the same way.
+ */
+// biome-ignore lint/performance/noBarrelFile: the stock swap part of the `./evm` entry
+export * from "./decode-stock-swap.js";
+export * from "./encode-swap.js";
+export * from "./quote.js";
+export * from "./stock-pools.js";

package/dist/evm/stocks/quote.d.ts

@@ -0,0 +1,19 @@
+import { type SwapSide } from "./encode-swap.ts";
+import { type StockPool } from "./stock-pools.ts";
+/** An `eth_call` on Robinhood Chain: any provider's `call`. */
+export type EthCall = (tx: {
+    to: string;
+    data: string;
+}) => Promise<string>;
+/**
+ * A live quote from the Uniswap V4 Quoter on Robinhood Chain, and the minimum
+ * output signed into the swap. `quoteExactInputSingle` is not a view function
+ * (it unlocks the PoolManager and reverts internally to surface the amount),
+ * so it is read through eth_call, never sent.
+ */
+export declare function quoteStockSwap(call: EthCall, pool: StockPool, side: SwapSide, 
+/** Exact input in base units (USDG 6-dec for buys, stock 18-dec for sells). */
+amountIn: bigint): Promise<{
+    amountOut: bigint;
+    minOut: bigint;
+}>;

package/dist/evm/stocks/quote.js

@@ -0,0 +1,46 @@
+import { decodeFunctionResult, encodeFunctionData, parseAbi, zeroAddress, } from "viem";
+import { applySlippage, swapLegs } from "./encode-swap.js";
+import { V4_QUOTER_ADDRESS } from "./stock-pools.js";
+const QUOTER = parseAbi([
+    "function quoteExactInputSingle(((address currency0, address currency1, uint24 fee, int24 tickSpacing, address hooks) poolKey, bool zeroForOne, uint128 exactAmount, bytes hookData) params) returns (uint256 amountOut, uint256 gasEstimate)",
+]);
+/**
+ * A live quote from the Uniswap V4 Quoter on Robinhood Chain, and the minimum
+ * output signed into the swap. `quoteExactInputSingle` is not a view function
+ * (it unlocks the PoolManager and reverts internally to surface the amount),
+ * so it is read through eth_call, never sent.
+ */
+export async function quoteStockSwap(call, pool, side, 
+/** Exact input in base units (USDG 6-dec for buys, stock 18-dec for sells). */
+amountIn) {
+    const { tokenIn, tokenOut } = swapLegs(pool, side);
+    // v4 orders the pair by address; zeroForOne says which way we cross it.
+    const zeroForOne = tokenIn.toLowerCase() < tokenOut.toLowerCase();
+    const [currency0, currency1] = zeroForOne
+        ? [tokenIn, tokenOut]
+        : [tokenOut, tokenIn];
+    const data = encodeFunctionData({
+        abi: QUOTER,
+        functionName: "quoteExactInputSingle",
+        args: [
+            {
+                poolKey: {
+                    currency0: currency0,
+                    currency1: currency1,
+                    fee: pool.fee,
+                    tickSpacing: pool.tickSpacing,
+                    hooks: zeroAddress,
+                },
+                zeroForOne,
+                exactAmount: amountIn,
+                hookData: "0x",
+            },
+        ],
+    });
+    const [amountOut] = decodeFunctionResult({
+        abi: QUOTER,
+        functionName: "quoteExactInputSingle",
+        data: (await call({ to: V4_QUOTER_ADDRESS, data })),
+    });
+    return { amountOut, minOut: applySlippage(amountOut) };
+}

package/dist/evm/stocks/stock-pools.d.ts

@@ -0,0 +1,61 @@
+/**
+ * HOOD: Robinhood Chain mainnet (4663) swap venue — USDG <> tokenized stocks
+ * through Uniswap v4, executed by the `GroupCashSwapWrapperV4` wrapper that
+ * has been live since July 2026. Everything Robinhood-specific hangs off this
+ * module so the feature can be lifted out in one piece.
+ *
+ * Every pool below was live-quoted through the V4 Quoter on Sept 6, 2026
+ * (100 USDG in). A pool that stops quoting means its fee / tickSpacing
+ * changed or liquidity left — re-probe before changing anything here. The
+ * token addresses match the seeded Token rows in
+ * `packages/database/prisma/src/eth-token-metadata.ts`; update both together.
+ */
+/** Quote and settlement token on Robinhood Chain (there is no USDC). */
+export declare const USDG: {
+    readonly symbol: "USDG";
+    readonly name: "Global Dollar";
+    readonly address: "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168";
+    readonly decimals: 6;
+};
+/** Robinhood Stock Tokens are 18 decimals. */
+export declare const STOCK_TOKEN_DECIMALS = 18;
+/** Uniswap V4 Quoter on 4663 (`quoteExactInputSingle`). */
+export declare const V4_QUOTER_ADDRESS = "0x8Dc178eFB8111BB0973Dd9d722ebeFF267c98F94";
+/** Slippage bound signed into every swap: 1% for equities. */
+export declare const STOCK_SWAP_SLIPPAGE_BPS = 100;
+export type StockPool = {
+    symbol: string;
+    /** Issuer name, e.g. "Apple Inc." */
+    name: string;
+    /** Short label, e.g. "Apple" */
+    label: string;
+    /** Brand-ish accent for avatars and charts. */
+    color: string;
+    /** Robinhood Stock Token contract (matches the seeded Token row). */
+    address: string;
+    /** Uniswap v4 pool fee in hundredths of a bip (3000 = 0.3%). */
+    fee: number;
+    tickSpacing: number;
+    /** True for ETFs (SPY); equities otherwise. */
+    etf?: boolean;
+};
+/**
+ * Stocks with a real USDG pool, in display order. NFLX is seeded as a token
+ * but has no pool, so it is deliberately absent: offering it would sign
+ * proposals that can only revert.
+ */
+export declare const STOCK_POOLS: Record<string, StockPool>;
+export declare const TRADABLE_STOCK_SYMBOLS: string[];
+export declare function isTradableStock(symbol: string): boolean;
+/** Pool fee as a percentage string, e.g. "0.3%". */
+export declare function poolFeeLabel(pool: StockPool): string;
+/**
+ * `GroupCashSwapWrapperV4` on Robinhood Chain mainnet — the contract every
+ * swap policy is activated against and every swap calls. Live since July
+ * 2026 (GroupCash). Deliberately NOT read from NEXT_PUBLIC_STOCK_SWAP_WRAPPER:
+ * the Vercel rows for that variable predate mainnet and point at a retired
+ * testnet mock with no code on 4663, so honoring them would pin new swap
+ * policies to a dead address.
+ */
+export declare const STOCK_SWAP_WRAPPER_MAINNET = "0xf21C3C4Cb339bA038c0B374b55F47Fa22ce4d419";
+export declare function stockSwapWrapperAddress(): string;