@getcofund/protocol 0.0.0 → 0.1.0

package/dist/evm/stocks/stock-pools.js

@@ -0,0 +1,179 @@
+/**
+ * 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 const USDG = {
+    symbol: "USDG",
+    name: "Global Dollar",
+    address: "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168",
+    decimals: 6,
+};
+/** Robinhood Stock Tokens are 18 decimals. */
+export const STOCK_TOKEN_DECIMALS = 18;
+/** Uniswap V4 Quoter on 4663 (`quoteExactInputSingle`). */
+export const V4_QUOTER_ADDRESS = "0x8Dc178eFB8111BB0973Dd9d722ebeFF267c98F94";
+/** Slippage bound signed into every swap: 1% for equities. */
+export const STOCK_SWAP_SLIPPAGE_BPS = 100;
+/**
+ * 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 const STOCK_POOLS = {
+    AAPL: {
+        symbol: "AAPL",
+        name: "Apple Inc.",
+        label: "Apple",
+        color: "#A2AAAD",
+        address: "0xaF3D76f1834A1d425780943C99Ea8A608f8a93f9",
+        fee: 10_000,
+        tickSpacing: 200,
+    },
+    NVDA: {
+        symbol: "NVDA",
+        name: "NVIDIA Corp.",
+        label: "NVIDIA",
+        color: "#76B900",
+        address: "0xd0601CE157Db5bdC3162BbaC2a2C8aF5320D9EEC",
+        fee: 3000,
+        tickSpacing: 60,
+    },
+    MSFT: {
+        symbol: "MSFT",
+        name: "Microsoft Corp.",
+        label: "Microsoft",
+        color: "#00A4EF",
+        address: "0xe93237C50D904957Cf27E7B1133b510C669c2e74",
+        fee: 3000,
+        tickSpacing: 60,
+    },
+    TSLA: {
+        symbol: "TSLA",
+        name: "Tesla, Inc.",
+        label: "Tesla",
+        color: "#CC0000",
+        address: "0x322F0929c4625eD5bAd873c95208D54E1c003b2d",
+        fee: 3000,
+        tickSpacing: 60,
+    },
+    SPY: {
+        symbol: "SPY",
+        name: "SPDR S&P 500 ETF Trust",
+        label: "S&P 500 ETF",
+        color: "#7A60E5",
+        address: "0x117cc2133c37B721F49dE2A7a74833232B3B4C0C",
+        fee: 3000,
+        tickSpacing: 60,
+        etf: true,
+    },
+    AMZN: {
+        symbol: "AMZN",
+        name: "Amazon.com, Inc.",
+        label: "Amazon",
+        color: "#FF9900",
+        address: "0x12f190a9F9d7D37a250758b26824B97CE941bF54",
+        fee: 3000,
+        tickSpacing: 60,
+    },
+    GOOGL: {
+        symbol: "GOOGL",
+        name: "Alphabet Inc. Class A",
+        label: "Alphabet",
+        color: "#4285F4",
+        address: "0x2e0847E8910a9732eB3fb1bb4b70a580ADAD4FE3",
+        fee: 3000,
+        tickSpacing: 60,
+    },
+    META: {
+        symbol: "META",
+        name: "Meta Platforms, Inc.",
+        label: "Meta",
+        color: "#0081FB",
+        address: "0xc0D6457C16Cc70d6790Dd43521C899C87ce02f35",
+        fee: 3000,
+        tickSpacing: 60,
+    },
+    AMD: {
+        symbol: "AMD",
+        name: "Advanced Micro Devices",
+        label: "AMD",
+        color: "#ED1C24",
+        address: "0x86923f96303D656E4aa86D9d42D1e57ad2023fdC",
+        fee: 10_000,
+        tickSpacing: 200,
+    },
+    PLTR: {
+        symbol: "PLTR",
+        name: "Palantir Technologies",
+        label: "Palantir",
+        color: "#9CA3AF",
+        address: "0x894E1EC2D74FFE5AEF8Dc8A9e84686acCB964F2A",
+        fee: 10_000,
+        tickSpacing: 200,
+    },
+    ORCL: {
+        symbol: "ORCL",
+        name: "Oracle Corp.",
+        label: "Oracle",
+        color: "#F80000",
+        address: "0xb0992820E760d836549ba69BC7598b4af75dEE03",
+        fee: 10_000,
+        tickSpacing: 200,
+    },
+    MU: {
+        symbol: "MU",
+        name: "Micron Technology",
+        label: "Micron",
+        color: "#2D8CFF",
+        address: "0xfF080c8ce2E5feadaCa0Da81314Ae59D232d4afD",
+        fee: 10_000,
+        tickSpacing: 200,
+    },
+    SNDK: {
+        symbol: "SNDK",
+        name: "Sandisk Corp.",
+        label: "Sandisk",
+        color: "#E11D48",
+        address: "0xB90A19fF0Af67f7779afF50A882A9CfF42446400",
+        fee: 10_000,
+        tickSpacing: 200,
+    },
+    SPCX: {
+        symbol: "SPCX",
+        name: "Space Exploration Technologies",
+        label: "SpaceX",
+        color: "#C4C4C4",
+        address: "0x4a0E65A3EcceC6dBe60AE065F2e7bb85Fae35eEa",
+        fee: 10_000,
+        tickSpacing: 200,
+    },
+};
+export const TRADABLE_STOCK_SYMBOLS = Object.keys(STOCK_POOLS);
+export function isTradableStock(symbol) {
+    return symbol in STOCK_POOLS;
+}
+/** Pool fee as a percentage string, e.g. "0.3%". */
+export function poolFeeLabel(pool) {
+    return `${pool.fee / 10_000}%`;
+}
+/**
+ * `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 const STOCK_SWAP_WRAPPER_MAINNET = "0xf21C3C4Cb339bA038c0B374b55F47Fa22ce4d419";
+export function stockSwapWrapperAddress() {
+    return STOCK_SWAP_WRAPPER_MAINNET;
+}

package/dist/evm/submitters.d.ts

@@ -0,0 +1,32 @@
+import { type Hex } from "viem";
+import type { EvmSubmitter, EvmWallet } from "./chain.ts";
+import type { EvmDeployment } from "./deployment.ts";
+/**
+ * The two submitters the package ships, both over a wallet the consumer
+ * gives it (a viem `WalletClient` with its account). Sponsoring through a
+ * gas manager is another `EvmSubmitter` the consumer writes.
+ */
+/** A call the chain refused: `reason` names the contract's error, `data` is the revert data. */
+export declare class CallRevertedError extends Error {
+    readonly reason: string;
+    readonly data: Hex;
+    constructor(reason: string, data: Hex, options?: {
+        cause?: unknown;
+    });
+}
+/** The revert data an error carries anywhere in its causes: a viem error's, a node's, an ethers error's. */
+export declare function revertDataOf(error: unknown): Hex | null;
+/**
+ * The wallet sends the call itself and pays its gas. The policies helper and
+ * the signature-only users calls accept any sender; a vault accepts any
+ * active member of its cofund (or a Cofund admin); `createClient` and
+ * `addUser` refuse it unless the wallet is a Cofund admin.
+ */
+export declare function directSubmitter(wallet: EvmWallet): EvmSubmitter;
+/**
+ * The call wrapped in `sponsorGuard.relay(target, data)` and sent by the
+ * wallet, which the deployment's guard must accept as a sponsor. The guard
+ * reaches the users and policies helpers and the cofunds' vaults, and is the
+ * sender `createClient` and `addUser` accept from the platform.
+ */
+export declare function guardSubmitter(wallet: EvmWallet, deployment: Pick<EvmDeployment, "sponsorGuard" | "chainId">): EvmSubmitter;

package/dist/evm/submitters.js

@@ -0,0 +1,105 @@
+import { encodeFunctionData } from "viem";
+import { policiesAbi } from "./abis/policies.js";
+import { sponsorGuardAbi } from "./abis/sponsor-guard.js";
+import { stateAbi } from "./abis/state.js";
+import { usersAbi } from "./abis/users.js";
+import { vaultAbi } from "./abis/vault.js";
+import { revertReason } from "./simulate/revert.js";
+/**
+ * The two submitters the package ships, both over a wallet the consumer
+ * gives it (a viem `WalletClient` with its account). Sponsoring through a
+ * gas manager is another `EvmSubmitter` the consumer writes.
+ */
+/** A call the chain refused: `reason` names the contract's error, `data` is the revert data. */
+export class CallRevertedError extends Error {
+    reason;
+    data;
+    constructor(reason, data, options) {
+        super(`The call reverts: ${reason}`, options);
+        this.name = "CallRevertedError";
+        this.reason = reason;
+        this.data = data;
+    }
+}
+const PROTOCOL_ERRORS = [
+    usersAbi,
+    policiesAbi,
+    vaultAbi,
+    sponsorGuardAbi,
+    stateAbi,
+];
+const HEX = /^0x(?:[0-9a-fA-F]{2})*$/;
+/** The revert data an error carries anywhere in its causes: a viem error's, a node's, an ethers error's. */
+export function revertDataOf(error) {
+    const seen = new Set();
+    let current = error;
+    while (current && typeof current === "object" && !seen.has(current)) {
+        seen.add(current);
+        const { data, cause, error: inner, } = current;
+        if (typeof data === "string" && HEX.test(data)) {
+            return data;
+        }
+        const nested = data?.data;
+        if (typeof nested === "string" && HEX.test(nested)) {
+            return nested;
+        }
+        current = cause ?? inner;
+    }
+    return null;
+}
+/** `wallet` sending `call`; a revert is a `CallRevertedError` naming the contract's error. */
+async function send(wallet, call) {
+    const account = wallet.account;
+    if (!account) {
+        throw new Error("The wallet client has no account to send from");
+    }
+    try {
+        return await wallet.sendTransaction({
+            account,
+            chain: wallet.chain ?? null,
+            to: call.to,
+            data: call.data,
+            ...(call.value !== undefined && { value: call.value }),
+        });
+    }
+    catch (error) {
+        const data = revertDataOf(error);
+        if (data === null) {
+            throw error;
+        }
+        throw new CallRevertedError(revertReason(data, { errors: PROTOCOL_ERRORS }), data, { cause: error });
+    }
+}
+/**
+ * The wallet sends the call itself and pays its gas. The policies helper and
+ * the signature-only users calls accept any sender; a vault accepts any
+ * active member of its cofund (or a Cofund admin); `createClient` and
+ * `addUser` refuse it unless the wallet is a Cofund admin.
+ */
+export function directSubmitter(wallet) {
+    return { send: (call) => send(wallet, call) };
+}
+/**
+ * The call wrapped in `sponsorGuard.relay(target, data)` and sent by the
+ * wallet, which the deployment's guard must accept as a sponsor. The guard
+ * reaches the users and policies helpers and the cofunds' vaults, and is the
+ * sender `createClient` and `addUser` accept from the platform.
+ */
+export function guardSubmitter(wallet, deployment) {
+    return {
+        send(call) {
+            if (wallet.chain && wallet.chain.id !== deployment.chainId) {
+                throw new Error(`The wallet is on chain ${wallet.chain.id}, the deployment on ${deployment.chainId}`);
+            }
+            return send(wallet, {
+                to: deployment.sponsorGuard,
+                data: encodeFunctionData({
+                    abi: sponsorGuardAbi,
+                    functionName: "relay",
+                    args: [call.to, call.data],
+                }),
+                ...(call.value !== undefined && { value: call.value }),
+            });
+        },
+    };
+}

package/dist/evm/types.d.ts

@@ -0,0 +1,146 @@
+/**
+ * What the protocol's EVM values look like, as zod schemas: addresses, hex,
+ * base units, chain names, and a call's effect as a simulation or its own
+ * logs show it. Every type is inferred from them.
+ */
+import { z } from "zod";
+/** An EVM address in any casing. */
+export declare const Address: z.ZodString;
+export declare const Bytes32: z.ZodString;
+/** 0x and whole bytes. */
+export declare const Hex: z.ZodString;
+export declare const BaseUnits: z.ZodString;
+export declare const PositiveBaseUnits: z.ZodString;
+/** Signed base units: a gain (positive) or a loss (negative); |x| fits a uint256. */
+export declare const SignedBaseUnits: z.ZodString;
+/** A token's decimals, as an ERC-20 reports them. */
+export declare const TokenDecimals: z.ZodNumber;
+/** A token's ticker. */
+export declare const TokenSymbol: z.ZodString;
+export declare const IsoDateTime: z.ZodISODateTime;
+/** A human-readable refusal or failure. */
+export declare const ErrorMessage: z.ZodString;
+export declare const ChainNameSchema: z.ZodEnum<{
+    BTC: "BTC";
+    ETHEREUM: "ETHEREUM";
+    BASE: "BASE";
+    ARBITRUM: "ARBITRUM";
+    ROBINHOOD: "ROBINHOOD";
+}>;
+export type ChainName = z.infer<typeof ChainNameSchema>;
+export declare const EvmChainNameSchema: z.ZodEnum<{
+    ETHEREUM: "ETHEREUM";
+    BASE: "BASE";
+    ARBITRUM: "ARBITRUM";
+    ROBINHOOD: "ROBINHOOD";
+}>;
+export type EvmChainName = z.infer<typeof EvmChainNameSchema>;
+/** One deployment: the chain id and that chain's State. */
+export type ChainPin = {
+    chainId: number;
+    state: string;
+};
+export type ChainPins = Partial<Record<EvmChainName, ChainPin>>;
+/** One holder's net change in one asset: the vault, the call's wrapper, or anyone else. */
+export declare const BalanceChangeSchema: z.ZodObject<{
+    holder: z.ZodString;
+    role: z.ZodEnum<{
+        vault: "vault";
+        wrapper: "wrapper";
+        other: "other";
+    }>;
+    asset: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"native">;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"erc20">;
+        address: z.ZodString;
+        listed: z.ZodBoolean;
+        symbol: z.ZodNullable<z.ZodString>;
+        decimals: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>], "kind">;
+    delta: z.ZodString;
+}, z.core.$strip>;
+export type BalanceChange = z.infer<typeof BalanceChangeSchema>;
+/**
+ * A call's effect as a simulation saw it: on success every balance it moves
+ * (`incomplete` when it also moved an NFT, or more balances than are read);
+ * on a revert, why; `unavailable` when the chain could not be read, or the
+ * simulation could not be trusted to be the call's.
+ */
+export declare const CallSimulationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    outcome: z.ZodLiteral<"success">;
+    at: z.ZodISODateTime;
+    block: z.ZodObject<{
+        number: z.ZodString;
+        hash: z.ZodString;
+    }, z.core.$strip>;
+    gasUsed: z.ZodString;
+    changes: z.ZodArray<z.ZodObject<{
+        holder: z.ZodString;
+        role: z.ZodEnum<{
+            vault: "vault";
+            wrapper: "wrapper";
+            other: "other";
+        }>;
+        asset: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"native">;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"erc20">;
+            address: z.ZodString;
+            listed: z.ZodBoolean;
+            symbol: z.ZodNullable<z.ZodString>;
+            decimals: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strip>], "kind">;
+        delta: z.ZodString;
+    }, z.core.$strip>>;
+    incomplete: z.ZodBoolean;
+}, z.core.$strip>, z.ZodObject<{
+    outcome: z.ZodLiteral<"revert">;
+    at: z.ZodISODateTime;
+    block: z.ZodObject<{
+        number: z.ZodString;
+        hash: z.ZodString;
+    }, z.core.$strip>;
+    reason: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    outcome: z.ZodLiteral<"unavailable">;
+    at: z.ZodISODateTime;
+    reason: z.ZodString;
+}, z.core.$strip>], "outcome">;
+export type CallSimulation = z.infer<typeof CallSimulationSchema>;
+/**
+ * What an executed call did, summed from its own logs: ERC-20 transfers and
+ * WETH-style deposits and withdrawals (the native coin moves without a log).
+ */
+export declare const CallEffectSchema: z.ZodObject<{
+    at: z.ZodISODateTime;
+    block: z.ZodObject<{
+        number: z.ZodString;
+        hash: z.ZodString;
+    }, z.core.$strip>;
+    hash: z.ZodString;
+    changes: z.ZodArray<z.ZodObject<{
+        holder: z.ZodString;
+        role: z.ZodEnum<{
+            vault: "vault";
+            wrapper: "wrapper";
+            other: "other";
+        }>;
+        asset: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"native">;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"erc20">;
+            address: z.ZodString;
+            listed: z.ZodBoolean;
+            symbol: z.ZodNullable<z.ZodString>;
+            decimals: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strip>], "kind">;
+        delta: z.ZodString;
+    }, z.core.$strip>>;
+    incomplete: z.ZodBoolean;
+}, z.core.$strip>;
+export type CallEffect = z.infer<typeof CallEffectSchema>;
+/** What every surface showing a call's simulated effect says after it, before the allowance bound. */
+export declare const SIMULATION_CAVEAT = "Simulated against the chain at that block. The real result can differ: prices and balances change, and a contract can behave differently when it runs for real.";
+/** Added after the caveat on a call to an unlisted contract. */
+export declare const UNLISTED_SIMULATION_WARNING = "Cofund hasn't reviewed this contract; it can show one result here and do another on execution.";

package/dist/evm/types.js

@@ -0,0 +1,128 @@
+/**
+ * What the protocol's EVM values look like, as zod schemas: addresses, hex,
+ * base units, chain names, and a call's effect as a simulation or its own
+ * logs show it. Every type is inferred from them.
+ */
+import { z } from "zod";
+/** An EVM address in any casing. */
+export const Address = z
+    .string()
+    .regex(/^0x[0-9a-fA-F]{40}$/, "an EVM address");
+export const Bytes32 = z
+    .string()
+    .regex(/^0x[0-9a-fA-F]{64}$/, "32 bytes of hex");
+/** 0x and whole bytes. */
+export const Hex = z.string().regex(/^0x(?:[0-9a-fA-F]{2})*$/, "hex bytes");
+const UINT256_MAX = 2n ** 256n - 1n;
+/**
+ * A uint256: 78 digits at most, checked before it is parsed (the format check
+ * aborts, so `BigInt` never sees anything but digits).
+ */
+const fitsUint256 = (units) => BigInt(units) <= UINT256_MAX;
+const MINUS = /^-/;
+export const BaseUnits = z
+    .string()
+    .regex(/^(?:0|[1-9]\d{0,77})$/, {
+    message: "base units, a non-negative integer",
+    abort: true,
+})
+    .refine(fitsUint256, "more than a uint256 holds");
+export const PositiveBaseUnits = z
+    .string()
+    .regex(/^[1-9]\d{0,77}$/, {
+    message: "base units, a positive integer",
+    abort: true,
+})
+    .refine(fitsUint256, "more than a uint256 holds");
+/** Signed base units: a gain (positive) or a loss (negative); |x| fits a uint256. */
+export const SignedBaseUnits = z
+    .string()
+    .regex(/^(?:0|-?[1-9]\d{0,77})$/, {
+    message: "signed base units",
+    abort: true,
+})
+    .refine((units) => fitsUint256(units.replace(MINUS, "")), "more than a uint256 holds");
+/** A token's decimals, as an ERC-20 reports them. */
+export const TokenDecimals = z.number().int().min(0).max(36);
+/** A token's ticker. */
+export const TokenSymbol = z
+    .string()
+    .regex(/^[A-Za-z0-9.$_-]{1,32}$/, "a token symbol");
+export const IsoDateTime = z.iso.datetime();
+/** A human-readable refusal or failure. */
+export const ErrorMessage = z.string().min(1);
+export const ChainNameSchema = z.enum([
+    "ETHEREUM",
+    "BASE",
+    "ARBITRUM",
+    "ROBINHOOD",
+    "BTC",
+]);
+export const EvmChainNameSchema = ChainNameSchema.exclude(["BTC"]);
+/**
+ * A balance a call moves: the native coin, or an ERC-20. A listed token's
+ * symbol and decimals are Cofund's token table's; any other's are the token's
+ * own claim (null when it is not a plain symbol, or the read failed).
+ */
+const SimulatedAsset = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("native") }),
+    z.object({
+        kind: z.literal("erc20"),
+        address: Address,
+        listed: z.boolean(),
+        symbol: TokenSymbol.nullable(),
+        decimals: TokenDecimals.nullable(),
+    }),
+]);
+/** One holder's net change in one asset: the vault, the call's wrapper, or anyone else. */
+export const BalanceChangeSchema = z.object({
+    holder: Address,
+    role: z.enum(["vault", "wrapper", "other"]),
+    asset: SimulatedAsset,
+    delta: SignedBaseUnits,
+});
+/** The block a simulation ran on top of: the chain's state at its end. */
+const SimulatedBlock = z.object({ number: BaseUnits, hash: Bytes32 });
+/**
+ * A call's effect as a simulation saw it: on success every balance it moves
+ * (`incomplete` when it also moved an NFT, or more balances than are read);
+ * on a revert, why; `unavailable` when the chain could not be read, or the
+ * simulation could not be trusted to be the call's.
+ */
+export const CallSimulationSchema = z.discriminatedUnion("outcome", [
+    z.object({
+        outcome: z.literal("success"),
+        at: IsoDateTime,
+        block: SimulatedBlock,
+        gasUsed: BaseUnits,
+        changes: z.array(BalanceChangeSchema).max(100),
+        incomplete: z.boolean(),
+    }),
+    z.object({
+        outcome: z.literal("revert"),
+        at: IsoDateTime,
+        block: SimulatedBlock,
+        reason: ErrorMessage,
+    }),
+    z.object({
+        outcome: z.literal("unavailable"),
+        at: IsoDateTime,
+        reason: ErrorMessage,
+    }),
+]);
+/**
+ * What an executed call did, summed from its own logs: ERC-20 transfers and
+ * WETH-style deposits and withdrawals (the native coin moves without a log).
+ */
+export const CallEffectSchema = z.object({
+    at: IsoDateTime,
+    block: SimulatedBlock,
+    /** The transaction that carried it; a sponsored operation's is its bundle. */
+    hash: Bytes32,
+    changes: z.array(BalanceChangeSchema).max(100),
+    incomplete: z.boolean(),
+});
+/** What every surface showing a call's simulated effect says after it, before the allowance bound. */
+export const SIMULATION_CAVEAT = "Simulated against the chain at that block. The real result can differ: prices and balances change, and a contract can behave differently when it runs for real.";
+/** Added after the caveat on a call to an unlisted contract. */
+export const UNLISTED_SIMULATION_WARNING = "Cofund hasn't reviewed this contract; it can show one result here and do another on execution.";

package/dist/keys/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `@getcofund/protocol/keys`: a member's keys, the signers derived from them,
+ * and the proof that a BTC xpub is the member's.
+ */
+export * from "./keys.ts";
+export * from "./xpub-ownership.ts";

package/dist/keys/index.js

@@ -0,0 +1,7 @@
+/**
+ * `@getcofund/protocol/keys`: a member's keys, the signers derived from them,
+ * and the proof that a BTC xpub is the member's.
+ */
+// biome-ignore lint/performance/noBarrelFile: the package's `./keys` entry
+export * from "./keys.js";
+export * from "./xpub-ownership.js";

package/dist/keys/keys.d.ts

@@ -0,0 +1,63 @@
+import { type PrivateKeyAccount } from "viem/accounts";
+export type BtcNetwork = "mainnet" | "testnet";
+/** A Bitcoin vault as verified when it was pinned: its address and the hash of its definition. */
+export type BtcVaultPin = {
+    address: string;
+    definitionHash: string;
+};
+/**
+ * A member's signing keys, generated and kept on their machine. Cofund never
+ * sees them: the API receives addresses, xpubs and signatures only.
+ *
+ * Plain JSON written with mode 0600. `cofunds` pins, per cofund, the
+ * `company` string its payloads must carry, recorded when its invite was
+ * accepted.
+ */
+export type Keystore = {
+    version: 1;
+    evm: {
+        privateKey: string;
+        address: string;
+    };
+    btc: {
+        network: BtcNetwork;
+        mnemonic: string;
+        accountXpub: string;
+    };
+    cofunds: Record<string, {
+        company: string;
+    }>;
+    /** Bitcoin vaults verified and pinned by id (`pinVault`); absent in a keystore from before. */
+    vaults?: Record<string, BtcVaultPin>;
+};
+export declare function generateKeystore(network: BtcNetwork): Keystore;
+/** The EVM key as a viem account: an EIP-712 signer (`TypedDataSigner`) and a wallet client's account. */
+export declare function evmWallet(keystore: Keystore): PrivateKeyAccount;
+/**
+ * The xpub and its ownership proof: a BIP-340 signature by the account's /0/0
+ * key — the leaf vaults use — over the challenge bound to `userId` and the xpub.
+ */
+export declare function btcOwnershipProof(keystore: Keystore, userId: string): {
+    xpub: string;
+    proof: string;
+};
+/** Signs a message as a Bitcoin Signed Message; returns the compact signature, hex. */
+export type BtcMessageSigner = {
+    signMessage(message: string): Promise<string>;
+};
+/** The BTC key's Cofund leaf as a message signer: what a BTC policy approval is. */
+export declare function btcMessageSigner(keystore: Keystore): BtcMessageSigner;
+/**
+ * BIP-340 signatures by the Cofund leaf key at a tapleaf's derivation branch:
+ * what a BTC transfer's partials are. A keystore, an HSM or a remote signer.
+ * (A PSBT is signed through `./btc`'s `BtcLeafSigner`.)
+ */
+export type BtcLeafKeySigner = {
+    network: BtcNetwork;
+    /** The x-only public key at `branch`. */
+    leafKey(branch: number): Uint8Array;
+    /** A BIP-340 signature over a 32-byte sighash. */
+    signDigest(branch: number, digest: Uint8Array): Uint8Array;
+};
+/** The keystore's BTC key as a tapleaf signer; the seed is derived once, here. */
+export declare function btcLeafSigner(keystore: Keystore): BtcLeafKeySigner;