@getcofund/cli 0.0.0 → 0.1.0

package/dist/commands/btc.js

@@ -0,0 +1,293 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { BtcVaultDefinitionSchema, BtcVaultTypeSchema, BtcXpub, broadcast, buildSpendPsbt, buildTaprootForNetwork, COFUND_LEAF_INDEX, checkPsbt, combinePsbts, createBip341NumsRecipe, esploraReader, extractTx, finalizePsbt, ORDERING_XPUB_CODEPOINT_V2, selectCoins, serializeAccountBasedData, signPsbt, vaultSpendInputVbytes, verifyBtcVault, } from "@getcofund/protocol/btc";
+import { btcLeafSigner } from "@getcofund/protocol/keys";
+import { z } from "zod";
+import { approved, keystore, line, setting, } from "../context.js";
+import { USAGE } from "../usage.js";
+/**
+ * `btc vault create`: a vault's definition from its members' account xpubs,
+ * and the address it derives. `btc spend build`: the vault's coins selected
+ * through Esplora and an unsigned PSBT paying one address. `sign`, `combine`,
+ * `finalize` and `broadcast`: the rest of the spend. Every command that takes
+ * a vault file rebuilds the vault from its definition first, and refuses one
+ * that does not derive its address.
+ */
+/** Each network's address and key prefixes, as the vault builder takes them. */
+const NETWORKS = {
+    mainnet: { bech32: "bc", pubKeyHash: 0x00, scriptHash: 0x05, wif: 0x80 },
+    testnet: { bech32: "tb", pubKeyHash: 0x6f, scriptHash: 0xc4, wif: 0xef },
+    regtest: { bech32: "bcrt", pubKeyHash: 0x6f, scriptHash: 0xc4, wif: 0xef },
+};
+const POSITIVE = /^[1-9]\d*$/;
+const PSBT_MAGIC = "70736274ff";
+const HEX = /^(?:[0-9a-fA-F]{2})+$/;
+const list = (text) => (text ?? "")
+    .split(",")
+    .map((each) => each.trim())
+    .filter(Boolean);
+/** Sats from a flag: a positive whole number. */
+function sats(value, flag) {
+    if (!(value && POSITIVE.test(value))) {
+        throw new Error(`${flag} takes sats, a positive whole number`);
+    }
+    return BigInt(value);
+}
+/** Write a file the command made; an existing one is never overwritten. */
+function writeNew(path, text) {
+    try {
+        writeFileSync(path, text, { flag: "wx" });
+    }
+    catch (error) {
+        if (error.code === "EEXIST") {
+            throw new Error(`${path} exists; pass another --out`);
+        }
+        throw error;
+    }
+}
+const VaultFileSchema = z.object({
+    id: z.string().min(1),
+    address: z.string().min(1),
+    definition: BtcVaultDefinitionSchema,
+});
+/** A vault file, rebuilt from its definition: refused unless it derives its address. */
+function loadVault(path) {
+    if (!path) {
+        throw new Error("Pass --vault <file>, the vault's definition");
+    }
+    let json;
+    try {
+        json = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`${path}: not a vault file (${error instanceof Error ? error.message : String(error)})`);
+    }
+    const parsed = VaultFileSchema.safeParse(json);
+    if (!parsed.success) {
+        const issue = parsed.error.issues[0];
+        throw new Error(`${path}: not a vault file (${issue.path.join(".") || "file"}: ${issue.message})`);
+    }
+    return verifyBtcVault(parsed.data, parsed.data.definition.network);
+}
+function vaultLine(vault) {
+    const { vaultType, threshold, members } = vault.definition;
+    return line("vault", `${vault.address}: ${threshold} of ${members.length} (${vaultType})`);
+}
+/** A PSBT file: base64, as wallets and bitcoind write them, or the raw bytes. */
+function readPsbt(path) {
+    const bytes = readFileSync(path);
+    if (bytes.subarray(0, 5).toString("hex") === PSBT_MAGIC) {
+        return new Uint8Array(bytes);
+    }
+    const decoded = Buffer.from(bytes.toString("utf8").trim(), "base64");
+    if (decoded.subarray(0, 5).toString("hex") !== PSBT_MAGIC) {
+        throw new Error(`${path} is not a PSBT`);
+    }
+    return new Uint8Array(decoded);
+}
+const writePsbt = (path, psbt) => writeNew(path, `${Buffer.from(psbt).toString("base64")}\n`);
+/** What a spend pays, as the build and every signer show it. */
+function spendLines(summary) {
+    const held = summary.inputs.reduce((sum, { value }) => sum + value, 0n);
+    const rate = Number(summary.fee) / summary.vsize;
+    return [
+        ...summary.payees.map(({ address, amount }) => line("pay", `${amount} sats to ${address}`)),
+        line("inputs", `${summary.inputs.length} of the vault's coins, ${held} sats`),
+        line("fee", `${summary.fee} sats (${rate.toFixed(2)} sat/vB of ${summary.vsize} vB)`),
+        line("change", summary.change === 0n
+            ? "none"
+            : `${summary.change} sats back to the vault`),
+    ];
+}
+/** The network a new vault's address is on: COFUND_BTC_NETWORK, else its xpubs' (xpub mainnet, tpub testnet). */
+function networkFor(io, xpubs) {
+    const mainnet = xpubs[0].startsWith("xpub");
+    const network = io.env.COFUND_BTC_NETWORK ?? (mainnet ? "mainnet" : "testnet");
+    if (!(network in NETWORKS)) {
+        throw new Error("COFUND_BTC_NETWORK is mainnet, testnet or regtest");
+    }
+    if (xpubs.some((xpub) => xpub.startsWith("xpub") !== (network === "mainnet"))) {
+        throw new Error(`A ${network} vault takes ${network === "mainnet" ? "xpubs" : "tpubs"} only`);
+    }
+    return network;
+}
+export function btcVaultCreate(io, flags) {
+    const xpubs = list(flags.xpubs);
+    const admins = list(flags.admins);
+    const { out, threshold } = flags;
+    if (xpubs.length === 0 || !threshold || !out) {
+        io.err(USAGE);
+        return 1;
+    }
+    for (const xpub of [...xpubs, ...admins]) {
+        if (!BtcXpub.safeParse(xpub).success) {
+            throw new Error(`Not an account xpub: ${xpub}`);
+        }
+    }
+    if (new Set(xpubs).size !== xpubs.length) {
+        throw new Error("--xpubs lists a member twice");
+    }
+    const stray = admins.find((admin) => !xpubs.includes(admin));
+    if (stray) {
+        throw new Error(`--admins names ${stray}, which --xpubs does not list`);
+    }
+    const network = networkFor(io, xpubs);
+    const recipe = createBip341NumsRecipe();
+    const definition = BtcVaultDefinitionSchema.parse({
+        vaultType: BtcVaultTypeSchema.parse(flags.type ?? "ALL"),
+        network: network === "mainnet" ? "mainnet" : "testnet",
+        threshold: Number(threshold),
+        participantOrdering: ORDERING_XPUB_CODEPOINT_V2,
+        nums: { scheme: recipe.scheme, version: recipe.version, r: recipe.r },
+        members: xpubs.map((accountXpub) => ({
+            id: randomUUID(),
+            role: admins.includes(accountXpub) ? "admin" : "member",
+            accountXpub,
+        })),
+    });
+    const { members, ...rest } = definition;
+    const { address } = buildTaprootForNetwork(serializeAccountBasedData({
+        accountBased: true,
+        ...rest,
+        companyUsers: members,
+    }), NETWORKS[network]);
+    const vault = { id: randomUUID(), address, definition };
+    const verified = verifyBtcVault(vault, definition.network);
+    writeNew(out, `${JSON.stringify(vault, null, 2)}\n`);
+    io.out(vaultLine(verified));
+    for (const member of definition.members) {
+        io.out(line(member.role, member.accountXpub));
+    }
+    io.out(line("wrote", `${out}: every member keeps it, and signs against it`));
+    return 0;
+}
+export async function btcSpendBuild(io, flags) {
+    const { to, out } = flags;
+    if (!(to && out)) {
+        io.err(USAGE);
+        return 1;
+    }
+    const amount = sats(flags.amount, "--amount");
+    const vault = loadVault(flags.vault);
+    const reader = esploraReader(setting(io, flags, "esplora"));
+    const feeRate = flags["fee-rate"] === undefined
+        ? await reader.feeRate()
+        : Number(flags["fee-rate"]);
+    if (!(Number.isFinite(feeRate) && feeRate > 0)) {
+        throw new Error("--fee-rate takes sat/vB, above 0");
+    }
+    const coins = await reader.utxos(vault.address);
+    const confirmed = coins.filter((coin) => coin.confirmed);
+    if (confirmed.length === 0 && coins.length > 0) {
+        throw new Error(`The vault's ${coins.length} coin(s) are unconfirmed: wait for a block`);
+    }
+    const { selected, fee } = selectCoins({
+        utxos: confirmed,
+        amount,
+        feeRate,
+        inputVbytes: vaultSpendInputVbytes(vault),
+    });
+    const payees = [{ address: to, amount }];
+    const psbt = buildSpendPsbt({ vault, inputs: selected, payees, fee });
+    for (const text of [
+        vaultLine(vault),
+        ...spendLines(checkPsbt(psbt, vault, { payees })),
+    ]) {
+        io.out(text);
+    }
+    writePsbt(out, psbt);
+    io.out(line("wrote", `${out}: each signer signs it with \`btc spend sign\``));
+    return 0;
+}
+/**
+ * The keystore's Bitcoin account as a PSBT signer: its xpub, and the
+ * Cofund leaf key at a leaf's branch (`m/86'/coin'/0'/<branch>/<leaf index>`).
+ */
+function keystoreSigner(keys) {
+    const leaves = btcLeafSigner(keys);
+    return {
+        xpub: () => Promise.resolve(keys.btc.accountXpub),
+        signTaprootLeaf(sighash, [branch, index]) {
+            if (index !== COFUND_LEAF_INDEX) {
+                throw new Error(`The keystore signs Cofund leaves only, not index ${index}`);
+            }
+            return Promise.resolve(leaves.signDigest(branch, sighash));
+        },
+    };
+}
+export async function btcSpendSign(io, flags, [path, ...rest]) {
+    const { to, out } = flags;
+    if (!(path && rest.length === 0 && to && out)) {
+        io.err(USAGE);
+        return 1;
+    }
+    const amount = sats(flags.amount, "--amount");
+    const vault = loadVault(flags.vault);
+    const keys = keystore(io, flags);
+    const member = vault.definition.members.find(({ accountXpub }) => accountXpub === keys.btc.accountXpub);
+    if (!member) {
+        throw new Error(`This keystore's xpub is not a member of vault ${vault.address}`);
+    }
+    const psbt = readPsbt(path);
+    // What the signer was told the spend pays: anything else is refused.
+    const expectations = { payees: [{ address: to, amount }] };
+    for (const text of [
+        vaultLine(vault),
+        ...spendLines(checkPsbt(psbt, vault, expectations)),
+        line("you", `sign as ${member.role} ${keys.btc.accountXpub}`),
+    ]) {
+        io.out(text);
+    }
+    if (!(await approved(io, flags, {
+        question: "Sign this spend?",
+        action: "sign it",
+    }))) {
+        return 1;
+    }
+    writePsbt(out, await signPsbt(psbt, vault, keystoreSigner(keys), expectations));
+    io.out(line("wrote", `${out}: combine it with the other signers'`));
+    return 0;
+}
+export function btcSpendCombine(io, flags, paths) {
+    const { out } = flags;
+    if (paths.length === 0 || !out) {
+        io.err(USAGE);
+        return 1;
+    }
+    writePsbt(out, combinePsbts(paths.map(readPsbt)));
+    io.out(line("wrote", `${out}: ${paths.length} PSBT(s) combined`));
+    return 0;
+}
+export function btcSpendFinalize(io, flags, [path, ...rest]) {
+    const { out } = flags;
+    if (!(path && rest.length === 0 && out)) {
+        io.err(USAGE);
+        return 1;
+    }
+    const vault = loadVault(flags.vault);
+    const hex = extractTx(finalizePsbt(readPsbt(path), vault));
+    io.out(vaultLine(vault));
+    writeNew(out, `${hex}\n`);
+    io.out(line("wrote", `${out}: the signed transaction, ${hex.length / 2} bytes; \`btc spend broadcast\` sends it`));
+    return 0;
+}
+export async function btcSpendBroadcast(io, flags, [arg, ...rest]) {
+    if (!arg || rest.length > 0) {
+        io.err(USAGE);
+        return 1;
+    }
+    const hex = (existsSync(arg) ? readFileSync(arg, "utf8") : arg).trim();
+    if (!HEX.test(hex)) {
+        throw new Error(`${arg} is neither a transaction's hex nor a file of it`);
+    }
+    const url = setting(io, flags, "esplora");
+    io.out(line("send", `a ${hex.length / 2}-byte transaction through Esplora`));
+    if (!(await approved(io, flags, {
+        question: "Broadcast it?",
+        action: "broadcast it",
+    }))) {
+        return 1;
+    }
+    io.out(line("sent", await broadcast(hex, esploraReader(url))));
+    return 0;
+}

package/dist/commands/calls.js

@@ -0,0 +1,194 @@
+import { randomUUID } from "node:crypto";
+import { allowanceBound, cofundClientId, describeSimulation, executeTransactionCall, formatUnitsAmount, readClientVault, simulateCall, simulationCaveat, simulationTokens, vaultAbi, } from "@getcofund/protocol/evm";
+import { encodeFunctionData, getAddress, isHex, keccak256, } from "viem";
+import { amountText, baseUnits, tokenInfo } from "../chain.js";
+import { evmChain, keystore, line, send, sender, } from "../context.js";
+import { pickCompany, requirePinned } from "../keystore.js";
+import { loadSignatures } from "../signature-file.js";
+import { USAGE } from "../usage.js";
+import { cofundLine, signedByLines } from "./lines.js";
+import { policyLine, signVaultMessage, spendingPolicy, vaultLine, } from "./transfers.js";
+/**
+ * `calls sign`: a signer of a call policy signs a call through its wrapper,
+ * new from the flags or the one in a file. `calls send`: sent from the vault
+ * once signed often enough. `calls simulate`: its effect, simulated before
+ * it is sent.
+ */
+async function callLines(evm, message, instructions) {
+    const allowances = [];
+    for (const { asset, amount } of message.allowances) {
+        allowances.push(line("allows", `${amountText(BigInt(amount), await tokenInfo(evm, getAddress(asset)))} to the wrapper`));
+    }
+    return [
+        cofundLine(message.company),
+        await policyLine(evm, message.company, message.policyId),
+        line("calls", `wrapper ${message.wrapper}, function ${message.func}`),
+        line("with", `${(instructions.length - 2) / 2} bytes of instructions, keccak256 ${message.instructionsHash}`),
+        ...(allowances.length > 0 ? allowances : [line("allows", "nothing")]),
+        await vaultLine(evm, message.company),
+    ];
+}
+/** `--allowance <token>:<amount>`: whole tokens of the token, approved to the wrapper for the call. */
+async function allowancesFrom(evm, flags) {
+    const allowances = [];
+    for (const each of flags.allowance ?? []) {
+        const [asset, amount] = each.split(":");
+        if (!(asset && amount)) {
+            throw new Error(`--allowance takes <token>:<amount>, not ${each}`);
+        }
+        const token = await tokenInfo(evm, getAddress(asset));
+        allowances.push({
+            asset: token.address,
+            amount: baseUnits(amount, token, "--allowance").toString(),
+        });
+    }
+    return allowances;
+}
+export async function callsSign(io, flags, files) {
+    const keys = keystore(io, flags);
+    const evm = await evmChain(io, flags);
+    let message;
+    let instructions;
+    let signed = [];
+    if (files.length > 0) {
+        signed = await loadSignatures(files, evm.deployment, ["Transaction"]);
+        message = signed[0].message;
+        instructions = signed[0].instructions;
+        requirePinned(keys, message.company, flags.company);
+        await spendingPolicy(evm, message.company, message.policyId, "call");
+    }
+    else {
+        const { policy: policyId } = flags;
+        if (!(policyId && flags.instructions)) {
+            io.err(USAGE);
+            return 1;
+        }
+        if (!isHex(flags.instructions, { strict: true }) ||
+            flags.instructions.length % 2) {
+            throw new Error("--instructions takes the wrapper's instructions as 0x hex");
+        }
+        instructions = flags.instructions;
+        const company = pickCompany(keys, flags.company);
+        const policy = await spendingPolicy(evm, company, policyId, "call");
+        message = {
+            company,
+            policyId,
+            messageType: policy.policyType,
+            wrapper: policy.transaction.wrapper,
+            func: policy.transaction.func,
+            allowances: await allowancesFrom(evm, flags),
+            instructionsHash: keccak256(instructions),
+            authId: randomUUID(),
+        };
+    }
+    return await signVaultMessage(io, flags, {
+        evm,
+        keys,
+        type: "Transaction",
+        message,
+        signed,
+        lines: await callLines(evm, message, instructions),
+        instructions,
+    });
+}
+export async function callsSend(io, flags, files) {
+    if (files.length === 0) {
+        io.err(USAGE);
+        return 1;
+    }
+    const evm = await evmChain(io, flags);
+    const signed = await loadSignatures(files, evm.deployment, ["Transaction"]);
+    const message = signed[0].message;
+    const instructions = signed[0].instructions;
+    const via = sender(io, flags, evm);
+    for (const text of [
+        ...(await callLines(evm, message, instructions)),
+        ...(await signedByLines(evm, message.company, signed)),
+    ]) {
+        io.out(text);
+    }
+    const call = await executeTransactionCall(evm, {
+        message,
+        instructions,
+        signatures: signed.map(({ signature }) => signature),
+    });
+    io.out(line("call", `executeTransaction on the vault ${call.to}`));
+    return await send(io, flags, { evm, via, call }, {
+        question: "Send this call?",
+        action: "send it",
+    });
+}
+/**
+ * `calls simulate <file>`: the call as its sender would send it (the vault
+ * from a member's key, or the guard's relay), run on the node with
+ * `eth_simulateV1` before the signers' threshold is met: the policy's
+ * threshold is overridden, and the balances it moves read before and after.
+ */
+export async function callsSimulate(io, flags, files) {
+    if (files.length === 0) {
+        io.err(USAGE);
+        return 1;
+    }
+    const evm = await evmChain(io, flags);
+    const signed = await loadSignatures(files, evm.deployment, ["Transaction"]);
+    const message = signed[0].message;
+    const instructions = signed[0].instructions;
+    const clientId = cofundClientId(message.company);
+    const vault = await readClientVault(evm.reader, evm.deployment, clientId);
+    if (!vault) {
+        throw new Error(`No cofund "${message.company}" on this chain`);
+    }
+    const via = sender(io, flags, evm);
+    const tx = via.transaction({
+        to: vault.vault,
+        data: encodeFunctionData({
+            abi: vaultAbi,
+            functionName: "executeTransaction",
+            args: [
+                message.company,
+                message.policyId,
+                message.messageType,
+                getAddress(message.wrapper),
+                message.func,
+                instructions,
+                message.allowances.map(({ asset, amount }) => ({
+                    asset: getAddress(asset),
+                    amount: BigInt(amount),
+                })),
+                message.authId,
+                [],
+            ],
+        }),
+    });
+    for (const text of await callLines(evm, message, instructions)) {
+        io.out(text);
+    }
+    const simulation = await simulateCall(evm.reader, {
+        state: evm.deployment.state,
+        clientId,
+        policyId: message.policyId,
+        vault: vault.vault,
+        wrapper: message.wrapper,
+        tx: { from: via.address, to: tx.to, data: tx.data },
+        skipSignatures: true,
+    });
+    const view = describeSimulation(simulation, formatUnitsAmount, {
+        withAddress: true,
+    });
+    const ran = view.status === "success";
+    io.out(line("simulated", `${view.block === null ? view.at : `block ${view.block} ${view.at}`}: ${ran ? "success" : view.notice}`));
+    for (const holder of view.holders) {
+        for (const change of holder.changes) {
+            io.out(line("", `${holder.label} ${change}`));
+        }
+    }
+    for (const note of [
+        ...(ran && view.notice ? [view.notice] : []),
+        ...view.notes,
+        ...simulationCaveat(false),
+        allowanceBound(message.allowances, simulationTokens(simulation), formatUnitsAmount),
+    ]) {
+        io.out(line("", note));
+    }
+    return ran ? 0 : 1;
+}

package/dist/commands/found.js

@@ -0,0 +1,61 @@
+import { randomUUID } from "node:crypto";
+import { cofundClientId, createClientCall, INVITE_USER_TYPES, inviteExpiresAt, normalizeCompanyName, readPredictedVault, typedData, } from "@getcofund/protocol/evm";
+import { evmWallet } from "@getcofund/protocol/keys";
+import { evmChain, line, send, sender, } from "../context.js";
+import { keystorePath, pinCompany, readKeystore } from "../keystore.js";
+import { USAGE } from "../usage.js";
+import { cofundLine, expiryText } from "./lines.js";
+/** The tier a cofund is founded on unless --tier names another: the one Cofund's app founds on. */
+const DEFAULT_TIER = "BUSINESS";
+/**
+ * `found`: the founder signs their own admin seat (`InviteUser` over
+ * themselves) and sends `createClient`, which creates the cofund and its
+ * vault. The company is pinned in the keystore once it lands.
+ */
+export async function found(io, flags) {
+    if (!(flags.name || flags.company)) {
+        io.err(USAGE);
+        return 1;
+    }
+    const company = flags.company ?? normalizeCompanyName(flags.name ?? "");
+    if (!company) {
+        io.err(`--name "${flags.name}" makes no company: pass --company`);
+        return 1;
+    }
+    const path = keystorePath(io.env, flags.keystore);
+    const founder = evmWallet(readKeystore(path));
+    const evm = await evmChain(io, flags);
+    const via = sender(io, flags, evm);
+    const userId = randomUUID();
+    const message = {
+        company,
+        callerId: userId,
+        userId,
+        userIsAdmin: true,
+        userPosition: "admin",
+        expiresAt: inviteExpiresAt(),
+        authId: randomUUID(),
+    };
+    const tier = flags.tier ?? DEFAULT_TIER;
+    const vault = await readPredictedVault(evm.reader, evm.deployment, cofundClientId(company));
+    io.out(cofundLine(company));
+    io.out(line("founder", `${userId} (admin) at ${founder.address}`));
+    io.out(line("vault", `${vault}, tier ${tier}`));
+    io.out(line("signed", `your own seat, valid ${expiryText(message.expiresAt)}`));
+    const call = await createClientCall(evm, {
+        message,
+        founder: founder.address,
+        signature: await founder.signTypedData(typedData(evm.deployment.eip712Domain, INVITE_USER_TYPES, message)),
+        tier,
+    });
+    io.out(line("call", `createClient on the users helper ${call.to}`));
+    const sent = await send(io, flags, { evm, via, call }, {
+        question: "Found this cofund?",
+        action: "found it",
+    });
+    if (sent === 0) {
+        pinCompany(path, company);
+        io.out(line("pinned", `company "${company}" in ${path}`));
+    }
+    return sent;
+}