@getcofund/protocol 0.0.0 → 0.1.0

package/dist/btc-policies/policy.d.ts

@@ -0,0 +1,55 @@
+import { z } from "zod";
+import type { PsbtSpendSummary } from "../btc/psbt.ts";
+import type { VerifiedBtcVault } from "../btc/spend.ts";
+/**
+ * A Bitcoin transfer policy, a plain value its users store: who signs (each
+ * by the account xpub the vault commits to), how many of them, the most one
+ * spend pays, and, when listed, the only addresses it may pay.
+ */
+export declare const BtcPolicySchema: z.ZodObject<{
+    id: z.ZodUUID;
+    name: z.ZodString;
+    type: z.ZodString;
+    signers: z.ZodArray<z.ZodString>;
+    threshold: z.ZodNumber;
+    maxAmount: z.ZodString;
+    recipients: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type BtcPolicy = z.infer<typeof BtcPolicySchema>;
+/**
+ * Throws unless `policy` is a policy `vault` can carry out, as the app refuses
+ * one at creation (`assertSignersInBtcVault`, which the policy form mirrors
+ * in `getBtcPolicySignersIssue`, vault-signer-ids.ts:132-194): the
+ * policy parses (`BtcPolicySchema`), every signer is one of the vault's
+ * members, the threshold is at least the vault's, and on an admin template
+ * an admin signs.
+ */
+export declare function checkPolicyForVault(policy: BtcPolicy, vault: VerifiedBtcVault): void;
+/**
+ * Throws unless the checked spend (`checkPsbt`'s summary) is one `policy`
+ * allows out of `vault`: the policy fits the vault (`checkPolicyForVault`), it
+ * pays only the policy's recipients when it lists any, and its payees' total
+ * is within the cap. The extra outputs (a fee you charge), the change and the
+ * network fee are not counted, as the app counts a transfer's amount alone.
+ */
+export declare function checkSpendAgainstPolicy(summary: PsbtSpendSummary, policy: BtcPolicy, vault: VerifiedBtcVault): void;
+/** One tapleaf on which the policy's signers have signed enough. */
+export type PolicyApproval = {
+    /** The leaf, hex. */
+    leafHash: string;
+    /** The policy's signers whose signatures cover every input on it, by account xpub. */
+    signers: string[];
+};
+/**
+ * Whether the policy's signers, not just any of the vault's, have signed the
+ * PSBT enough: the app's server waits for this beyond the script's k
+ * (`findVerifiedApprovalPlan`, `app/api/bitcoin/nonces/finalizeTx.ts:316-361`).
+ * The first leaf on which at least `threshold` of the policy's signers each
+ * have a signature that verifies over every input, by distinct keys, and
+ * among whom the leaf's own rule (k, and its admin on `ADMINS_REQUIRED`) can
+ * be met; null when no leaf has that.
+ *
+ * `finalizePsbt` uses every signature that verifies, so to put exactly these
+ * signers' on the witness, combine only their PSBTs.
+ */
+export declare function policySignersSigned(psbt: Uint8Array, policy: BtcPolicy, vault: VerifiedBtcVault): PolicyApproval | null;

package/dist/btc-policies/policy.js

@@ -0,0 +1,210 @@
+import { bytesToHex } from "@noble/hashes/utils";
+import * as btc from "@scure/btc-signer";
+import { equalBytes } from "@scure/btc-signer/utils.js";
+import { z } from "zod";
+import { BtcXpub, Uuid } from "../btc/types.js";
+import { BTC_VAULT_MAX_PARTICIPANTS } from "../btc/vault/limits.js";
+import { vaultSpendSighash } from "../btc/vault/spend.js";
+import { leafScriptPolicy, selectHardThresholdSignerIds, signerSlotsForScript, verifyPartialSignatureAgainstMsg, } from "../btc/witness.js";
+/**
+ * A Bitcoin spending policy as the same rules Cofund's app holds its Bitcoin
+ * transfers to. No script checks them: a vault's script asks for k of its
+ * keys and nothing else. They bind only the parties that check a spend
+ * against them before signing, and that wait for the policy's signers.
+ *
+ * The app files cited are under `apps/cofund/src/`:
+ * `actions/create-policy/assert-btc-vault-signers.ts`,
+ * `lib/bitcoin/vault-signer-ids.ts`,
+ * `app/api/documents/transfer/create-transfer-doc.ts` and
+ * `app/api/bitcoin/nonces/finalizeTx.ts`.
+ */
+const BtcAddress = z
+    .string()
+    .regex(/^(?:(?:bc|tb|bcrt)1[02-9ac-hj-np-z]{6,87}|[123mn][1-9A-HJ-NP-Za-km-z]{25,34})$/, "a Bitcoin address");
+const distinct = (items, key) => new Set(items.map(key)).size === items.length;
+/**
+ * A Bitcoin transfer policy, a plain value its users store: who signs (each
+ * by the account xpub the vault commits to), how many of them, the most one
+ * spend pays, and, when listed, the only addresses it may pay.
+ */
+export const BtcPolicySchema = z
+    .object({
+    id: Uuid,
+    name: z.string().min(2).max(100),
+    /** What the policy is for, e.g. `Contractor_Stipend`; its activation commits to it. */
+    type: z.string().min(1).max(100),
+    signers: z
+        .array(BtcXpub)
+        .min(1)
+        .max(BTC_VAULT_MAX_PARTICIPANTS)
+        // assert-btc-vault-signers.ts:24-27: the same signer twice.
+        .refine((xpubs) => distinct(xpubs, (xpub) => xpub), "Each signer once"),
+    /** Signatures by the policy's signers a spend waits for. */
+    threshold: z.number().int().min(1),
+    /** The most one spend pays its payees, in sats. */
+    maxAmount: z
+        .string()
+        .regex(/^[1-9]\d{0,29}$/, "sats, a positive integer of at most 30 digits"),
+    /** The only addresses a spend may pay; absent or empty: any. */
+    recipients: z
+        .array(BtcAddress)
+        .max(100)
+        .refine((list) => distinct(list, (address) => address.toLowerCase()), "Each recipient once")
+        .optional(),
+})
+    // assert-btc-vault-signers.ts:37-45: no more than the signers can give.
+    .refine(({ threshold, signers }) => threshold <= signers.length, {
+    message: "The threshold is more than the policy's signers",
+    path: ["threshold"],
+});
+/**
+ * Throws unless `policy` is a policy `vault` can carry out, as the app refuses
+ * one at creation (`assertSignersInBtcVault`, which the policy form mirrors
+ * in `getBtcPolicySignersIssue`, vault-signer-ids.ts:132-194): the
+ * policy parses (`BtcPolicySchema`), every signer is one of the vault's
+ * members, the threshold is at least the vault's, and on an admin template
+ * an admin signs.
+ */
+export function checkPolicyForVault(policy, vault) {
+    const { signers, threshold } = BtcPolicySchema.parse(policy);
+    const { members, vaultType } = vault.definition;
+    // assert-btc-vault-signers.ts:29-35 (vault-signer-ids.ts:163-167).
+    const outsiders = signers.filter((xpub) => !members.some(({ accountXpub }) => accountXpub === xpub));
+    if (outsiders.length > 0) {
+        throw new Error(`Signers not in vault ${vault.address}: ${outsiders.join(", ")}`);
+    }
+    // assert-btc-vault-signers.ts:37-45 (vault-signer-ids.ts:169-171): the
+    // script takes k signatures whatever the policy says, so never fewer.
+    if (threshold < vault.definition.threshold) {
+        throw new Error(`The policy's threshold of ${threshold} is below vault ${vault.address}'s ${vault.definition.threshold}`);
+    }
+    // assert-btc-vault-signers.ts:47-60 (vault-signer-ids.ts:99-110).
+    if (vaultType === "ADMINS_INCLUDED" || vaultType === "ADMINS_REQUIRED") {
+        const admin = members.some(({ role, accountXpub }) => role === "admin" && signers.includes(accountXpub));
+        if (!admin) {
+            throw new Error(`An ${vaultType} vault's policy needs at least one of its admins among its signers`);
+        }
+    }
+}
+/**
+ * Throws unless the checked spend (`checkPsbt`'s summary) is one `policy`
+ * allows out of `vault`: the policy fits the vault (`checkPolicyForVault`), it
+ * pays only the policy's recipients when it lists any, and its payees' total
+ * is within the cap. The extra outputs (a fee you charge), the change and the
+ * network fee are not counted, as the app counts a transfer's amount alone.
+ */
+export function checkSpendAgainstPolicy(summary, policy, vault) {
+    if (summary.vault !== vault.address) {
+        throw new Error(`The spend is from ${summary.vault}, not vault ${vault.address}`);
+    }
+    checkPolicyForVault(policy, vault);
+    // create-transfer-doc.ts:191-196: the amount over the cap. One spend is one
+    // transfer, so its payees count together (the app's payroll run caps each
+    // contractor's own transfer, cron/payroll-run.worker.ts:806).
+    const total = summary.payees.reduce((sum, { amount }) => sum + amount, 0n);
+    if (total > BigInt(policy.maxAmount)) {
+        throw new Error(`The spend pays ${total} sats, over the policy's maximum of ${policy.maxAmount}`);
+    }
+    // create-transfer-doc.ts:224-240: an allowlist, when the policy has one,
+    // compared case-insensitively.
+    const allowlist = (policy.recipients ?? []).map((a) => a.toLowerCase());
+    if (allowlist.length > 0) {
+        for (const { address } of summary.payees) {
+            if (!allowlist.includes(address.toLowerCase())) {
+                throw new Error(`Recipient ${address} is not in the policy's recipient allowlist`);
+            }
+        }
+    }
+}
+/** leaf hash → member id → the inputs a signature of theirs that verifies covers (finalizeTx.ts:242-269). */
+function signatureCoverage(tx, vault) {
+    const coverage = new Map();
+    const add = (leaf, index, pubKey) => {
+        const key = bytesToHex(leaf.leafHash);
+        const perLeaf = coverage.get(key) ?? new Map();
+        for (const { id, xonly } of leaf.signers) {
+            if (equalBytes(xonly, pubKey)) {
+                perLeaf.set(id, (perLeaf.get(id) ?? new Set()).add(index));
+            }
+        }
+        coverage.set(key, perLeaf);
+    };
+    for (let index = 0; index < tx.inputsLength; index++) {
+        const sigs = tx.getInput(index).tapScriptSig ?? [];
+        for (const [{ pubKey, leafHash }, signature] of sigs) {
+            const leaf = vault.leaves.find((entry) => equalBytes(entry.leaf.leafHash, leafHash))?.leaf;
+            const sighash = leaf && vaultSpendSighash(tx, index, leaf.script);
+            if (sighash &&
+                verifyPartialSignatureAgainstMsg(sighash, pubKey, signature)) {
+                add(leaf, index, pubKey);
+            }
+        }
+    }
+    return coverage;
+}
+/**
+ * The leaf's script slots held by a policy signer whose signatures cover every
+ * input, each key counted once (`verifiedApproverIdsForLeaf`,
+ * finalizeTx.ts:271-303).
+ */
+function leafApprovers(leaf, perLeaf, policySignerIds, inputCount) {
+    const script = leafScriptPolicy(leaf);
+    if (!script) {
+        return [];
+    }
+    const countedKeys = new Set();
+    const approvers = [];
+    for (const [index, signer] of signerSlotsForScript(leaf, script.signatureKeys).entries()) {
+        const key = bytesToHex(script.signatureKeys[index]);
+        if (signer &&
+            policySignerIds.has(signer.id) &&
+            perLeaf.get(signer.id)?.size === inputCount &&
+            !countedKeys.has(key)) {
+            countedKeys.add(key);
+            approvers.push(signer.id);
+        }
+    }
+    return approvers;
+}
+/**
+ * Whether the policy's signers, not just any of the vault's, have signed the
+ * PSBT enough: the app's server waits for this beyond the script's k
+ * (`findVerifiedApprovalPlan`, `app/api/bitcoin/nonces/finalizeTx.ts:316-361`).
+ * The first leaf on which at least `threshold` of the policy's signers each
+ * have a signature that verifies over every input, by distinct keys, and
+ * among whom the leaf's own rule (k, and its admin on `ADMINS_REQUIRED`) can
+ * be met; null when no leaf has that.
+ *
+ * `finalizePsbt` uses every signature that verifies, so to put exactly these
+ * signers' on the witness, combine only their PSBTs.
+ */
+export function policySignersSigned(psbt, policy, vault) {
+    // finalizeTx.ts:323-325.
+    if (!Number.isInteger(policy.threshold) || policy.threshold < 1) {
+        return null;
+    }
+    const tx = btc.Transaction.fromPSBT(psbt);
+    for (let index = 0; index < tx.inputsLength; index++) {
+        const prevout = tx.getInput(index).witnessUtxo;
+        if (!(prevout && equalBytes(prevout.script, vault.script))) {
+            throw new Error(`Input ${index} does not spend vault ${vault.address}`);
+        }
+    }
+    const xpubOf = new Map(vault.definition.members
+        .filter(({ accountXpub }) => policy.signers.includes(accountXpub))
+        .map(({ id, accountXpub }) => [id, accountXpub]));
+    const coverage = signatureCoverage(tx, vault);
+    for (const { leaf } of vault.leaves) {
+        const leafHash = bytesToHex(leaf.leafHash);
+        const approvers = leafApprovers(leaf, coverage.get(leafHash) ?? new Map(), new Set(xpubOf.keys()), tx.inputsLength);
+        // finalizeTx.ts:346-355.
+        if (approvers.length >= policy.threshold &&
+            selectHardThresholdSignerIds(leaf, vault.definition.vaultType, new Set(approvers))) {
+            return {
+                leafHash,
+                signers: approvers.flatMap((id) => xpubOf.get(id) ?? []),
+            };
+        }
+    }
+    return null;
+}

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

@@ -0,0 +1,10 @@
+/**
+ * The contracts' ABIs, generated from cofund-solidity's Foundry artifacts
+ * (`scripts/gen-evm-abis.mjs`), typed `as const` for viem.
+ */
+export { policiesAbi } from "./policies.ts";
+export { sponsorGuardAbi } from "./sponsor-guard.ts";
+export { stateAbi } from "./state.ts";
+export { usersAbi } from "./users.ts";
+export { vaultAbi } from "./vault.ts";
+export { vaultFactoryAbi } from "./vault-factory.ts";

package/dist/evm/abis/index.js

@@ -0,0 +1,11 @@
+/**
+ * The contracts' ABIs, generated from cofund-solidity's Foundry artifacts
+ * (`scripts/gen-evm-abis.mjs`), typed `as const` for viem.
+ */
+// biome-ignore lint/performance/noBarrelFile: the ABIs' part of the `./evm` entry
+export { policiesAbi } from "./policies.js";
+export { sponsorGuardAbi } from "./sponsor-guard.js";
+export { stateAbi } from "./state.js";
+export { usersAbi } from "./users.js";
+export { vaultAbi } from "./vault.js";
+export { vaultFactoryAbi } from "./vault-factory.js";

package/dist/evm/abis/policies.d.ts

@@ -0,0 +1,279 @@
+export declare const policiesAbi: readonly [{
+    readonly type: "constructor";
+    readonly inputs: readonly [{
+        readonly name: "_stateContract";
+        readonly type: "address";
+        readonly internalType: "address";
+    }];
+    readonly stateMutability: "nonpayable";
+}, {
+    readonly type: "function";
+    readonly name: "activateTransactionPolicy";
+    readonly inputs: readonly [{
+        readonly name: "args";
+        readonly type: "tuple";
+        readonly internalType: "struct CFHelpersPoliciesv1.TransactionPolicyArgs";
+        readonly components: readonly [{
+            readonly name: "clientId";
+            readonly type: "bytes32";
+            readonly internalType: "bytes32";
+        }, {
+            readonly name: "company";
+            readonly type: "string";
+            readonly internalType: "string";
+        }, {
+            readonly name: "policyId";
+            readonly type: "string";
+            readonly internalType: "string";
+        }, {
+            readonly name: "title";
+            readonly type: "string";
+            readonly internalType: "string";
+        }, {
+            readonly name: "policyType";
+            readonly type: "string";
+            readonly internalType: "string";
+        }, {
+            readonly name: "signerIds";
+            readonly type: "string[]";
+            readonly internalType: "string[]";
+        }, {
+            readonly name: "threshold";
+            readonly type: "uint256";
+            readonly internalType: "uint256";
+        }, {
+            readonly name: "wrapper";
+            readonly type: "address";
+            readonly internalType: "address";
+        }, {
+            readonly name: "func";
+            readonly type: "string";
+            readonly internalType: "string";
+        }];
+    }, {
+        readonly name: "authId";
+        readonly type: "string";
+        readonly internalType: "string";
+    }, {
+        readonly name: "signatures";
+        readonly type: "bytes[]";
+        readonly internalType: "bytes[]";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+        readonly internalType: "bool";
+    }];
+    readonly stateMutability: "nonpayable";
+}, {
+    readonly type: "function";
+    readonly name: "activateTransferPolicy";
+    readonly inputs: readonly [{
+        readonly name: "args";
+        readonly type: "tuple";
+        readonly internalType: "struct CFHelpersPoliciesv1.TransferPolicyArgs";
+        readonly components: readonly [{
+            readonly name: "clientId";
+            readonly type: "bytes32";
+            readonly internalType: "bytes32";
+        }, {
+            readonly name: "company";
+            readonly type: "string";
+            readonly internalType: "string";
+        }, {
+            readonly name: "policyId";
+            readonly type: "string";
+            readonly internalType: "string";
+        }, {
+            readonly name: "title";
+            readonly type: "string";
+            readonly internalType: "string";
+        }, {
+            readonly name: "policyType";
+            readonly type: "string";
+            readonly internalType: "string";
+        }, {
+            readonly name: "signerIds";
+            readonly type: "string[]";
+            readonly internalType: "string[]";
+        }, {
+            readonly name: "threshold";
+            readonly type: "uint256";
+            readonly internalType: "uint256";
+        }, {
+            readonly name: "token";
+            readonly type: "address";
+            readonly internalType: "address";
+        }, {
+            readonly name: "maxAmount";
+            readonly type: "uint256";
+            readonly internalType: "uint256";
+        }, {
+            readonly name: "recipients";
+            readonly type: "address[]";
+            readonly internalType: "address[]";
+        }];
+    }, {
+        readonly name: "authId";
+        readonly type: "string";
+        readonly internalType: "string";
+    }, {
+        readonly name: "signatures";
+        readonly type: "bytes[]";
+        readonly internalType: "bytes[]";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+        readonly internalType: "bool";
+    }];
+    readonly stateMutability: "nonpayable";
+}, {
+    readonly type: "function";
+    readonly name: "deactivatePolicy";
+    readonly inputs: readonly [{
+        readonly name: "clientId";
+        readonly type: "bytes32";
+        readonly internalType: "bytes32";
+    }, {
+        readonly name: "company";
+        readonly type: "string";
+        readonly internalType: "string";
+    }, {
+        readonly name: "policyId";
+        readonly type: "string";
+        readonly internalType: "string";
+    }, {
+        readonly name: "authId";
+        readonly type: "string";
+        readonly internalType: "string";
+    }, {
+        readonly name: "adminSignature";
+        readonly type: "bytes";
+        readonly internalType: "bytes";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+        readonly internalType: "bool";
+    }];
+    readonly stateMutability: "nonpayable";
+}, {
+    readonly type: "function";
+    readonly name: "eip712Domain";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "fields";
+        readonly type: "bytes1";
+        readonly internalType: "bytes1";
+    }, {
+        readonly name: "name";
+        readonly type: "string";
+        readonly internalType: "string";
+    }, {
+        readonly name: "version";
+        readonly type: "string";
+        readonly internalType: "string";
+    }, {
+        readonly name: "chainId";
+        readonly type: "uint256";
+        readonly internalType: "uint256";
+    }, {
+        readonly name: "verifyingContract";
+        readonly type: "address";
+        readonly internalType: "address";
+    }, {
+        readonly name: "salt";
+        readonly type: "bytes32";
+        readonly internalType: "bytes32";
+    }, {
+        readonly name: "extensions";
+        readonly type: "uint256[]";
+        readonly internalType: "uint256[]";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "requiredPolicyActivationSignatures";
+    readonly inputs: readonly [{
+        readonly name: "clientId";
+        readonly type: "bytes32";
+        readonly internalType: "bytes32";
+    }, {
+        readonly name: "threshold";
+        readonly type: "uint256";
+        readonly internalType: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+        readonly internalType: "uint256";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "stateContract";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+        readonly internalType: "contract ICofundHelperState";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "error";
+    readonly name: "DuplicatePolicySigner";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "InactiveUser";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "InvalidAdmin";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "InvalidCompany";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "InvalidPolicySigner";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "InvalidPolicyType";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "InvalidSignature";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "InvalidSigner";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "InvalidThreshold";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "InvalidTitle";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "InvalidType";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "SignerCountMismatch";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "SignersLength";
+    readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "UnauthorizedCaller";
+    readonly inputs: readonly [];
+}];