@getcofund/protocol 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cofund
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,415 @@
-# Temporary Holding Version
+# @getcofund/protocol
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Cofund protocol on chain: Bitcoin vaults and the EVM contracts behind
+State. It talks to the chain only. There is no Cofund API in it, no database,
+and no Cofund deployment built in.
+
+```sh
+npm i @getcofund/protocol viem
+```
+
+## Entries
+
+| Entry | Holds |
+|---|---|
+| `@getcofund/protocol/evm` | The deployment config and its check, the EIP-712 messages (`InviteUser`, `Transfer`, `Transaction`, the policy activations and the rest) and their domain, a call builder per contract entry point with the contract's checks, State's reads, the two submitters, the contracts' ABIs, the company name and the client id it derives, a vault call's simulation over `eth_simulateV1` and how it reads, the StockSwap verb, and the values these are made of as zod schemas |
+| `@getcofund/protocol/btc` | A vault's taproot tree and address from its definition, the vault checked against that definition, and its spends: coins selected, a PSBT built, checked and signed, combined, finalized and broadcast |
+| `@getcofund/protocol/btc-policies` | Optional: Bitcoin spending policies (signers, a threshold, a cap, recipients) a spend is checked against before it is signed, and what an admin signs to activate one. No script enforces them; they bind only the parties that use them |
+| `@getcofund/protocol/keys` | A member's keys (an EVM key and a BIP-86 Bitcoin account), the signers derived from them, and the proof that an xpub is the member's |
+
+Every entry runs in a browser as well as in Node: nothing here reaches a Node
+built-in. EVM code is written on viem.
+
+## What you bring
+
+The package ships no deployment and picks no provider, key store or relayer.
+You bring the deployment, a reader, signers and a submitter. Co-signers
+exchange signatures over whatever channel you choose: every message is plain
+EIP-712 typed data.
+
+### The deployment
+
+The shape of cofund-solidity's `deployments/<chainId>.json`, which its deploy
+script (`script/DeployCore.s.sol`) prints:
+
+```ts
+type EvmDeployment = {
+  chainId: number;
+  state: Address;        // CFHelpersStatev1, every message's verifying contract
+  users: Address;        // helperContracts("users")
+  policies: Address;     // helperContracts("policies")
+  vaults: Address;       // the vault factory, helperContracts("vaults")
+  sponsorGuard: Address; // helperContracts("sponsorGuard")
+  eip712Domain: { name: string; version: string; chainId: number; verifyingContract: Address };
+};
+```
+
+`loadEvmDeployment(config, reader)` checks a config before anything is signed
+under it, and refuses one that differs anywhere with every difference
+(`DeploymentMismatchError.differences`): the domain's chain id and verifying
+contract are the config's chain id and State, the reader is on that chain,
+each helper is the one State registers, and the domain's name and version are
+the ones the users helper reports (ERC-5267). Other fields in the file (gov,
+the sponsor, dates) pass unread.
+
+```ts
+import deployment1 from "./deployments/1.json" with { type: "json" };
+const reader = createPublicClient({ chain: mainnet, transport: http(rpcUrl) });
+const deployment = await loadEvmDeployment(deployment1, reader);
+const ctx = { deployment, reader };
+```
+
+### The interfaces
+
+```ts
+type EvmReader = {         // a viem PublicClient, any EIP-1193 provider
+  request(args: { method: string; params?: unknown }): Promise<unknown>;
+};
+type TypedDataSigner = {   // a viem Account: a local key, a Ledger, a KMS adapter
+  readonly address: Address;
+  signTypedData(data: TypedData): Promise<Hex>;
+};
+type EvmSubmitter = {      // who sends a call and pays for it
+  send(call: { to: Address; data: Hex; value?: bigint }): Promise<Hash>;
+};
+```
+
+A viem `PublicClient` is an `EvmReader` and a viem `Account` a
+`TypedDataSigner` as they are; a `WalletClient` signs through
+`walletSigner(client)`. An ethers provider reads through
+`{ request: ({ method, params }) => provider.send(method, params) }`.
+`typedData(domain, types, message)` builds what a signer signs, with the
+primary type read from `types`; `typedDataDigest` hashes it as the contracts
+do.
+
+### The submitters
+
+- **`directSubmitter(walletClient)`:** the wallet sends the call itself and
+  pays gas. The policies helper and the users helper's signature-only calls
+  (`removeUser`, `rotateUser`, `completeOnboarding`) accept any sender; a vault
+  accepts any active member of its cofund, a Cofund admin or the guard.
+- **`guardSubmitter(walletClient, deployment)`:** the call wrapped in
+  `sponsorGuard.relay(target, data)`, sent by a wallet the deployment's guard
+  accepts as a sponsor. `createClient` and `addUser` accept only the guard or a
+  Cofund admin as their sender, so they go this way.
+
+A call the chain refuses throws `CallRevertedError`, its `reason` the
+contract's error by name. Sponsoring through a gas manager is an
+`EvmSubmitter` you write.
+
+## Calls
+
+One builder per contract entry point. Each reads what it needs through the
+reader, checks the call as the contract will, and returns `{ to, data }` for a
+submitter; a call the contract would revert is refused before anything is
+sent, with `CallRefusedError`, its `reason` the error the contract would revert
+with. Multi-signature arrays are put in the order the contracts walk them
+(ascending by recovered address); a signer counted twice is refused. Every
+signature is recovered as OpenZeppelin's `ECDSA` recovers it (65 bytes, low
+`s`, `v` 27 or 28). The checks that turn on `msg.sender` are the submitter's.
+
+| Builder | Takes | Refuses, as the contract does |
+|---|---|---|
+| `createClientCall` | the founder's `InviteUser` over themselves, the founder's address and signature, a tier | an invite window not open now or more than 30 days long (`InviteExpired`, `InvalidParams`); an empty `authId`; a message not naming the founder as admin, a signature not the founder's (`InvalidSignature`); a spent `authId` (`KeyExists`); an existing cofund (`ClientExists`); an unknown tier (`InvalidTier`); a taken seat or key (`UserExists`, `AddressExists`) |
+| `addUserCall` | an `InviteUser`, the inviting admin's signature, co-signatures, the invitee's address and signature | the window; an inviting signature that is not the `callerId`'s seat (`UnauthorizedCaller`), an inactive or non-admin inviter; a spent `authId`; for an admin seat fewer than `requiredAdminInviteSignatures` (`ThresholdNotMet`) or a co-signer who is the inviter or no active admin; an invitee signature not the invitee's; a taken seat or key |
+| `removeUserCall` | a `RemoveUser`, admin signatures | fewer than two for an admin while more than one admin is active (`ThresholdNotMet`); a signer who is no active admin; a spent `authId`; an unknown or removed user; the last admin (`InvalidSetting`) |
+| `rotateUserCall` | a `RotateUser`, the new key's signature, and the current key's or (for a lost key) admins' | a new-key signature not the new address's; both authorizations at once (`InvalidParams`); a current key not the one State holds; too few admins; a new key that holds a seat |
+| `completeOnboardingCall` | a `CompleteOnboarding`, an admin's signature | a stranger (`UnauthorizedCaller`), an inactive admin, a member; a spent `authId`; a closed phase (`OnboardingAlreadyComplete`) |
+| `activateTransferPolicyCall`, `activateTransactionPolicyCall` | the activation, admin signatures | an unsupported type, an empty title, a zero threshold, fewer signers than the threshold, a zero token or wrapper; a spent `authId`; fewer than `requiredPolicyActivationSignatures` (`SignerCountMismatch`); a signer who is no active admin; an existing policy id, a signer id that is no active user, listed twice, a zero recipient |
+| `deactivatePolicyCall` | a `PolicyDeactivation`, an admin's signature | a spent `authId`; a stranger, an inactive admin, a member (`UnauthorizedCaller`, `InactiveUser`, `InvalidAdmin`); a policy that is not active |
+| `executeTransferCall` | a `Transfer`, the signers' signatures | a company with no vault; an inactive policy, a transaction policy, an amount over the cap, another token, another type, fewer signatures than the threshold, a recipient off the allowlist; a spent `authId`; a signer State does not resolve to an active signer of the policy; a vault short of the amount and the tier's fee on top |
+| `executeTransactionCall` | a `Transaction`, its instructions, the signers' signatures | the same policy checks with the policy's wrapper; instructions other than the signed hash; an allowance of the zero address or of 0 |
+
+```ts
+const message = { company, callerId: me, userId, userIsAdmin: false, userPosition: "Engineer", expiresAt, authId };
+const call = await addUserCall(ctx, {
+  message,
+  adminSignature: await admin.signTypedData(typedData(deployment.eip712Domain, INVITE_USER_TYPES, message)),
+  invitee: member.address,
+  inviteeSignature: await member.signTypedData(typedData(deployment.eip712Domain, INVITE_USER_TYPES, message)),
+});
+await guardSubmitter(sponsorWallet, deployment).send(call);
+```
+
+## Reads
+
+Typed State getters through the reader: `readUser`, `readUserIdByAddress`,
+`readPolicy`, `readClientVault`, `readOnboardingComplete`, `readActiveAdmins`,
+`readHelperContract`, `readAuthIdSpent`, the helpers' rules
+(`readRequiredAdminInviteSignatures`, `readRequiredPolicyActivationSignatures`)
+and `readPredictedVault`. There is no index: history or speed is yours to
+bring. The ABIs (`stateAbi`, `usersAbi`, `policiesAbi`, `vaultAbi`,
+`vaultFactoryAbi`, `sponsorGuardAbi`) are generated from cofund-solidity's
+build by `scripts/gen-evm-abis.mjs`.
+
+## An open guard
+
+Which guard a deployment registers, and whom it accepts, is the deployer's
+choice. For a deployment where anyone may found a cofund or seat a member
+(the signatures still authorize each call), a guard without the sponsor
+allowlist:
+
+```solidity
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.28;
+
+interface IState {
+    function helperContracts(string calldata) external view returns (address);
+    function clientVaults(bytes32) external view returns (address, string memory);
+}
+
+/// CFSponsorGuardv1 without `isAuthorizedSponsor`: anyone relays, and pays gas.
+contract OpenGuard {
+    error CallNotAllowed();
+    error GuardPaused();
+    error InvalidCall();
+    error UnauthorizedCaller();
+
+    IState public immutable state;
+    bool public paused;
+
+    constructor(address _state) { state = IState(_state); }
+
+    function setPaused(bool value) external {
+        if (msg.sender != state.helperContracts("gov")) revert UnauthorizedCaller();
+        paused = value;
+    }
+
+    function relay(address target, bytes calldata data) external payable returns (bytes memory) {
+        if (paused) revert GuardPaused();
+        if (data.length < 4) revert InvalidCall();
+        if (!_isHelper(target) && !_isKnownVault(target)) revert CallNotAllowed();
+        (bool ok, bytes memory ret) = target.call{value: msg.value}(data);
+        if (!ok) assembly { revert(add(ret, 0x20), mload(ret)) }
+        return ret;
+    }
+
+    function _isHelper(address target) internal view returns (bool) {
+        return target != address(0)
+            && (target == state.helperContracts("users") || target == state.helperContracts("policies"));
+    }
+
+    function _isKnownVault(address target) internal view returns (bool) {
+        if (target == address(0) || target.code.length == 0) return false;
+        (bool ok, bytes memory ret) = target.staticcall(abi.encodeWithSignature("clientId()"));
+        if (!ok || ret.length != 32) return false;
+        (address registered, ) = state.clientVaults(abi.decode(ret, (bytes32)));
+        return registered == target;
+    }
+}
+```
+
+Register it with `gov.setHelperContract("sponsorGuard", openGuard)` and put
+its address in the deployment's `sponsorGuard`; `guardSubmitter` then works
+with any wallet. It keeps the guard's one rule: it reaches the users and
+policies helpers and the cofunds' own vaults, nothing else, never State.
+
+## Tests
+
+`pnpm test` runs the unit tests: each builder's calldata against vectors
+`cast calldata` encoded (`test/vectors/gen-calls.mjs`), each refusal, the
+deployment check, the submitters, and `cofund-protocol`'s EVM message vectors
+(`test/vectors/conformance`). The integration test deploys the contracts to a
+throwaway Anvil with cofund-solidity's `script/e2e-deploy.sh` and runs a
+cofund's life through this package, every call sent directly where the
+contracts allow it and through the guard:
+
+```sh
+PROTOCOL_ANVIL=1 COFUND_SOLIDITY_DIR=../cofund-solidity pnpm --filter @getcofund/protocol test
+```
+
+It needs Foundry (`anvil`, `forge`, `cast`); the contracts build into
+`COFUND_FOUNDRY_CACHE_DIR` (default under the OS temp dir), never into the
+checkout.
+
+The Bitcoin integration test builds a vault of each template from fresh keys,
+funds it, spends it through PSBTs signed by separate signers, and checks the
+outputs on chain. It mines, so give it a regtest bitcoind of its own:
+
+```sh
+PROTOCOL_REGTEST_RPC=http://user:pass@127.0.0.1:18443 pnpm --filter @getcofund/protocol test
+```
+
+## Bitcoin spends
+
+A spend is five plain functions on the vault verified from its definition
+(`verifyBtcVault`): select the coins, build a PSBT, sign it, combine and
+finalize it, broadcast it. Co-signers pass the PSBT around as bytes over any
+channel; each checks it against its own copy of the vault, and against what it
+was told the spend pays, before it signs.
+
+### A 2-of-3 vault, three signers on three machines
+
+```ts
+import { base64 } from "@scure/base";
+import {
+  broadcast,
+  buildSpendPsbt,
+  combinePsbts,
+  esploraReader,
+  extractTx,
+  finalizePsbt,
+  localLeafSigner,
+  selectCoins,
+  signPsbt,
+  vaultSpendInputVbytes,
+  verifyBtcVault,
+} from "@getcofund/protocol/btc";
+
+// Every machine: the vault, rebuilt from the definition its members share.
+const vault = verifyBtcVault({ id: "treasury", address, definition }, "mainnet");
+const reader = esploraReader("https://mempool.space/api");
+
+// What the spend pays, agreed out of band. Each signer checks the PSBT against it.
+const expectations = {
+  payees: [{ address: "bc1q…", amount: 1_000_000n }],
+  extraOutputs: [{ address: "bc1p…", amount: 5_000n }], // e.g. a fee you charge
+  maxFeeRate: 50, // sat/vB
+};
+
+// Machine A selects coins and builds the PSBT.
+const utxos = (await reader.utxos(vault.address)).filter((u) => u.confirmed);
+const { selected, fee } = selectCoins({
+  utxos,
+  amount: 1_000_000n,
+  extraOutputs: [5_000n],
+  feeRate: await reader.feeRate(),
+  inputVbytes: vaultSpendInputVbytes(vault),
+});
+const unsigned = base64.encode(
+  buildSpendPsbt({
+    vault,
+    inputs: selected,
+    payees: expectations.payees,
+    extraOutputs: expectations.extraOutputs,
+    fee,
+  }),
+);
+// …and sends `unsigned` to B and C.
+
+// A, B and C each sign their own copy with their own key, and send it back.
+const signer = localLeafSigner(accountXprv); // or a wallet, or a Ledger
+const signed = base64.encode(
+  await signPsbt(base64.decode(unsigned), vault, signer, expectations),
+);
+
+// Whoever collects them: two signatures meet the threshold; a third is ignored.
+const final = finalizePsbt(
+  combinePsbts([signedA, signedB, signedC].map((psbt) => base64.decode(psbt))),
+  vault,
+);
+const txid = await broadcast(extractTx(final), reader);
+```
+
+### Each step
+
+| Function | Does |
+|---|---|
+| `selectCoins({ utxos, amount, feeRate, inputVbytes, payeeCount?, extraOutputs?, consolidate? })` | Coins for the spend, largest first, until they cover the outputs and the fee for that many inputs; with `consolidate`, every coin. The fee is the spend's vsize with a change output, each input sized by the vault's largest leaf (`vaultSpendInputVbytes`), at `feeRate`, times `FEE_SAFETY_MULTIPLIER`. It locks nothing: keeping two spends off the same coins is yours |
+| `buildSpendPsbt({ vault, inputs, payees, extraOutputs?, fee })` | The unsigned PSBT: the payees, then the extra outputs, then change to the vault unless it is below `VAULT_CHANGE_DUST` (then it goes to the fee). The inputs are in their canonical order, and each carries its prevout (`witnessUtxo`), every leaf with its control block (`tapLeafScript`), the internal key and merkle root, and every leaf key's origin (`tapBip32Derivation`). The package adds no output of its own |
+| `checkPsbt(psbt, vault, expectations)` | Every input spends the vault's script, none twice; the outputs are the payees, then the extra outputs, then at most change to the vault; the network fee is at most `maxFeeRate` (default 1000) sat/vB. Returns what the spend pays; throws on the first thing that does not hold |
+| `signPsbt(psbt, vault, signer, expectations)` | `checkPsbt`, then a BIP-340 signature (`tapScriptSig`, SIGHASH_DEFAULT) per input for each leaf that holds the signer's key, each verified against that key before it is added |
+| `combinePsbts(psbts)` | One PSBT with every signature; refuses PSBTs of different spends, or that disagree on a prevout |
+| `finalizePsbt(psbt, vault)` | Each input's witness, once one leaf has its threshold on every input: k of the leaf's keys, and on an `ADMINS_REQUIRED` leaf its admin and k − 1 more. Only signatures that verify count. `ADMINS_INCLUDED` has the same script as `ALL`: its admin rule binds only those who apply it. Throws, saying what each leaf lacks, when none is met |
+| `extractTx(psbt)` | The finalized transaction, as hex |
+| `broadcast(hex, reader)` | Sends it through the reader; returns its txid |
+
+The witness assembly the finalizer uses (`tryFinalizeAny`, `leafScriptPolicy`,
+`finalizeWithWitness` and the rest) is exported too, for signatures collected
+some other way.
+
+### What you bring
+
+A **reader**, `BtcReader`: `utxos(address)`, `tx(txid)`, `feeRate()` and
+`broadcast(hex)`. `esploraReader(baseUrl, { feeTarget? })` is one over any
+Esplora API with `fetch` alone; a node's RPC or another indexer fits the same
+four functions.
+
+A **signer** per member, `BtcLeafSigner`: `xpub()`, the account xpub the
+vault's definition lists for the member, and `signTaprootLeaf(sighash,
+derivation)`, a BIP-340 signature by the key at `derivation` below that account
+(`[branch, 376864517]`). `localLeafSigner(accountXprv)` holds an account key in
+memory; derive one from a seed with `@scure/bip32`, e.g.
+`HDKey.fromMasterSeed(seed).derive("m/86'/0'/0'").privateExtendedKey` (with
+`BIP32_VERSIONS.testnet` off mainnet).
+
+A vault's definition holds account xpubs, not their wallets' master
+fingerprints, so each `tapBip32Derivation` names its key's origin from the
+account: the account xpub's fingerprint, then `branch/376864517`. A wallet that
+looks its keys up by master fingerprint finds them at
+`m/86'/coin'/0'/branch/376864517`.
+
+## Bitcoin policies
+
+`@getcofund/protocol/btc-policies` gives Bitcoin the policy shape the EVM
+policies helper has: signers, a threshold, a cap per spend and an optional
+recipient allowlist. No script checks them: a vault's script asks for k of its
+keys and nothing else. A policy binds only the parties that check each spend
+against it before they sign and wait for its signers before they finalize.
+The checks are the ones Cofund's app makes on its Bitcoin transfers.
+
+```ts
+import { checkPsbt, combinePsbts, finalizePsbt, signPsbt } from "@getcofund/protocol/btc";
+import {
+  activationDataFor,
+  BtcPolicySchema,
+  btcPolicyActivationMessage,
+  checkSpendAgainstPolicy,
+  policySignersSigned,
+  verifyActivationSignature,
+} from "@getcofund/protocol/btc-policies";
+import { btcMessageSigner } from "@getcofund/protocol/keys";
+
+// A plain value you store and share with its signers.
+const policy = BtcPolicySchema.parse({
+  id: crypto.randomUUID(),
+  name: "Contractor payouts",
+  type: "Contractor_Stipend",
+  signers: [aliceXpub, bobXpub, carolXpub], // account xpubs the vault commits to
+  threshold: 2,
+  maxAmount: "5000000", // sats per spend
+  recipients: ["bc1q…"], // absent or empty: any
+});
+
+// Activation: an admin signs with their BTC key's Cofund leaf, and anyone
+// checks the approval against that admin's account xpub.
+const data = activationDataFor(policy, { company: "Acme Inc" });
+const approval = await btcMessageSigner(keystore).signMessage(btcPolicyActivationMessage(data));
+verifyActivationSignature(data, approval, adminXpub); // true
+
+// Before signing: the PSBT checked, then the spend against the policy.
+const summary = checkPsbt(psbt, vault, expectations);
+checkSpendAgainstPolicy(summary, policy, vault); // throws, saying why
+const signed = await signPsbt(psbt, vault, signer, expectations);
+
+// Before finalizing: enough of the policy's signers, not any k of the vault's.
+const combined = combinePsbts(copies);
+if (policySignersSigned(combined, policy, vault)) {
+  finalizePsbt(combined, vault);
+}
+```
+
+| Function | Does |
+|---|---|
+| `BtcPolicySchema` | The policy: a UUID id, a name, a type, its signers (distinct account xpubs), a threshold no higher than their count, `maxAmount` in sats, and `recipients`, each once |
+| `checkPolicyForVault(policy, vault)` | Throws unless the policy parses, every signer is a member of the vault, the threshold is at least the vault's k, and on an `ADMINS_INCLUDED` or `ADMINS_REQUIRED` vault an admin is among the signers |
+| `checkSpendAgainstPolicy(summary, policy, vault)` | `checkPolicyForVault`, then: the spend (`checkPsbt`'s summary) is the vault's, its payees' total is at most `maxAmount`, and with recipients listed every payee is one of them, compared case-insensitively. The extra outputs, the change and the network fee are not counted |
+| `policySignersSigned(psbt, policy, vault)` | The first leaf on which at least `threshold` of the policy's signers each have a signature that verifies over every input, each key counted once, and among whom the leaf's own rule can be met; `{ leafHash, signers }`, or null |
+| `activationDataFor(policy, { company })` | The activation: `clientId` the company's sha256, the policy's id as `authId`, each signer's Cofund leaf key and the recipients in codepoint order, the cap, the token `BTC`, no wrapper |
+| `verifyActivationSignature(data, signature, xpub)` | Whether the signature (64-byte compact, hex) is the Cofund leaf of `xpub` signing the activation message as a Bitcoin Signed Message; false, never a throw, on a malformed one |
+
+`btcPolicyActivationDigest`, `btcPolicyActivationMessage`,
+`btcPolicyActivationSigningHash` and `bitcoinSignedMessageHash` give the bytes
+underneath: a length-prefixed sha256 of the fields, its hex as the message,
+and the message's BIP-137 hash, which a Ledger's Bitcoin app signs too.
+
+One call verifies one approval. Whose approvals activate a policy, and how
+many, is yours: Cofund's app takes its cofund's admins, one while it is
+onboarding and two after (every admin for a threshold-1 policy).
+
+`finalizePsbt` uses every signature that verifies; to put only the policy's
+signers on the witness, combine only their PSBTs.
+
+## License
+
+MIT

package/dist/btc/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `@getcofund/protocol/btc`: a vault's taproot tree from its definition, and
+ * its spends: coins selected, built into a PSBT, checked and signed, combined,
+ * finalized and broadcast.
+ */
+export * from "./psbt.ts";
+export * from "./reader.ts";
+export * from "./select.ts";
+export * from "./spend.ts";
+export * from "./types.ts";
+export * from "./vault/index.ts";
+export * from "./witness.ts";

package/dist/btc/index.js

@@ -0,0 +1,13 @@
+/**
+ * `@getcofund/protocol/btc`: a vault's taproot tree from its definition, and
+ * its spends: coins selected, built into a PSBT, checked and signed, combined,
+ * finalized and broadcast.
+ */
+// biome-ignore lint/performance/noBarrelFile: the package's `./btc` entry
+export * from "./psbt.js";
+export * from "./reader.js";
+export * from "./select.js";
+export * from "./spend.js";
+export * from "./types.js";
+export * from "./vault/index.js";
+export * from "./witness.js";

package/dist/btc/psbt.d.ts

@@ -0,0 +1,121 @@
+import type { VerifiedBtcVault } from "./spend.ts";
+/**
+ * A vault spend as a PSBT (BIP-174, with BIP-371's taproot fields): what
+ * co-signers pass around, over whatever channel they choose, until one leaf
+ * has its threshold.
+ *
+ *   select (`selectCoins`) → `buildSpendPsbt` → `signPsbt`, once per signer →
+ *   `combinePsbts` → `finalizePsbt` → `extractTx` → `broadcast`
+ *
+ * Every step takes the vault verified against its definition
+ * (`verifyBtcVault`): a signer reads the vault's script and leaves off its
+ * own rebuild of the tree, never off the PSBT.
+ */
+/** An output: an address on the vault's network and the sats it is paid. */
+export type BtcPayment = {
+    address: string;
+    amount: bigint | number;
+};
+/**
+ * Signs for a member's account key: a wallet, a Ledger, a local key. `xpub` is
+ * the account xpub the vault's definition lists for the member, and
+ * `signTaprootLeaf` returns a BIP-340 signature over `sighash` by the key at
+ * `derivation` below that account: `[branch, COFUND_LEAF_INDEX]`, the leaf's
+ * branch and the Cofund leaf index.
+ */
+export type BtcLeafSigner = {
+    xpub(): Promise<string>;
+    signTaprootLeaf(sighash: Uint8Array, derivation: number[]): Promise<Uint8Array>;
+};
+/** A {@link BtcLeafSigner} over an account xprv (tprv off mainnet), `m/86'/coin'/0'`, held in memory. */
+export declare function localLeafSigner(accountXprv: string): BtcLeafSigner;
+/** Change below this many sats is left to the fee: a P2TR output under it is dust. */
+export declare const VAULT_CHANGE_DUST = 330n;
+export type SpendPsbtRequest = {
+    vault: VerifiedBtcVault;
+    /** The vault's coins it spends (`selectCoins`); `value` in sats. */
+    inputs: readonly {
+        txid: string;
+        vout: number;
+        value: bigint | number;
+    }[];
+    /** Paid first, in this order. */
+    payees: readonly BtcPayment[];
+    /** Paid after the payees, in this order: a fee to an address, say. The package adds none of its own. */
+    extraOutputs?: readonly BtcPayment[];
+    /** The network fee, in sats (`selectCoins`). */
+    fee: bigint | number;
+};
+/**
+ * The unsigned spend as a PSBT: the payees, then the extra outputs, then
+ * change back to the vault when it is not dust (the inputs less the outputs
+ * less `fee`); the inputs in their canonical order (`buildVaultSpend`, by
+ * `txid:vout`). Each input carries its prevout (`witnessUtxo`), every leaf of
+ * the vault with its control block (`tapLeafScript`), the internal key and
+ * merkle root, and each leaf key's origin (`tapBip32Derivation`).
+ */
+export declare function buildSpendPsbt(request: SpendPsbtRequest): Uint8Array;
+/** What a signer expects a spend to pay. */
+export type PsbtExpectations = {
+    /** The first outputs, in this order. */
+    payees: readonly BtcPayment[];
+    /** The outputs right after the payees, in this order. */
+    extraOutputs?: readonly BtcPayment[];
+    /** The network fee's ceiling, in sat/vB of the spend's vsize (default 1000). */
+    maxFeeRate?: number;
+};
+/** What a checked PSBT spends and pays; sats throughout. */
+export type PsbtSpendSummary = {
+    vault: string;
+    inputs: {
+        txid: string;
+        vout: number;
+        value: bigint;
+    }[];
+    payees: {
+        address: string;
+        amount: bigint;
+    }[];
+    extraOutputs: {
+        address: string;
+        amount: bigint;
+    }[];
+    /** Back to the vault; 0 without a change output. */
+    change: bigint;
+    fee: bigint;
+    /** As the fee is priced: every input witnessed by the vault's largest leaf. */
+    vsize: number;
+};
+/**
+ * Check a PSBT against the verified vault and what the consumer expects;
+ * throws on the first thing that does not hold:
+ *
+ * - every input spends the vault's script (`witnessUtxo`), and none twice: a
+ *   prevout the PSBT misstates only makes every signature over it invalid,
+ *   since BIP-341 commits to each prevout's script and amount;
+ * - the outputs are the payees, then the extra outputs, each its address and
+ *   amount, then at most one more: change back to the vault;
+ * - the network fee (the inputs less the outputs) is at most `maxFeeRate`
+ *   sat/vB of the spend's vsize as it is priced.
+ */
+export declare function checkPsbt(psbt: Uint8Array, vault: VerifiedBtcVault, expectations: PsbtExpectations): PsbtSpendSummary;
+/**
+ * The signer's BIP-340 signatures added to the PSBT (`tapScriptSig`), one per
+ * input for each leaf that holds the signer's key, over the BIP-341 sighash
+ * (SIGHASH_DEFAULT) of the spend with the verified leaf's script. First the
+ * PSBT is checked (`checkPsbt`); each signature is verified against the
+ * signer's key in the leaf before it is added.
+ */
+export declare function signPsbt(psbt: Uint8Array, vault: VerifiedBtcVault, signer: BtcLeafSigner, expectations: PsbtExpectations): Promise<Uint8Array>;
+/** One PSBT with the signatures of all of them; they must be the same spend of the same prevouts. */
+export declare function combinePsbts(psbts: readonly Uint8Array[]): Uint8Array;
+/**
+ * Assemble each input's witness once one leaf has its threshold on every
+ * input, by the template's rules (`tryFinalizeAny`): k of the leaf's keys, and
+ * on an ADMINS_REQUIRED leaf its admin plus k − 1 of the rest. Only signatures
+ * that verify over the spend count. Returns the finalized PSBT, its signing
+ * fields cleared; throws when no leaf is met.
+ */
+export declare function finalizePsbt(psbt: Uint8Array, vault: VerifiedBtcVault): Uint8Array;
+/** A finalized PSBT's transaction, as raw hex to broadcast. */
+export declare function extractTx(psbt: Uint8Array): string;