Vault API Reference

Vault Creation

createVault(options)

End-to-end vault creation — fetches validator keys, builds tapscripts, and derives the P2TR address.

const vault = await createVault({
  network: "regtest",
  userWallet,
  validators: { endpoint: "https://rpc-regtest.tachibtc.com/tachi_validators" }, // or https://rpc-signet.tachibtc.com/tachi_validators for signet
  // csvBlocks: 1008, // optional: override exit-leaf CSV
});

Option	Type	Description
network	VaultNetworkName	mainnet / signet / regtest
userWallet	Wallet	Wallet from @tachibtc/taurus-wallet-aggregator
validators	{ endpoint: string }	KDHT validator endpoint
nodePubkeys	string[]	Alternative: pass pubkeys directly, skip HTTP fetch
csvBlocks	number	Exit-leaf CSV blocks (default: 1008)

verifyVaultP2tr(p2tr)

Re-derives both leaves, the NUMS internal key, and the tweaked output key. Throws on any mismatch.

verifyVaultP2tr(vault.p2tr); // throws if invalid

depositToVault(options)

Funds a vault from a P2WPKH wallet.

const deposit = await depositToVault({
  vault,
  userWallet,
  rpc,
  amountSats: 100_000n,
  feeRateSatVb: 2,
});

Registration & Discovery

createVault is local — it derives an address and nothing else knows about it. Registering the funded vault on-ledger is what makes it discoverable from any device.

registerVault(options)

Registers a funded vault by building, signing, and broadcasting a TxVaultOpen. Orchestrates payload → nonce → build → sign → broadcast in one call, then returns the derived VaultID.

const reg = await registerVault({
  vault,
  outpoint: { txid: deposit.txid, vout: 0 },
  userSigner,
  inputs, // ledger VTXOs paying the (typically zero) open fee
  outputs, // change VTXOs from the open spend
  feeSats: 0n,
  broadcast: { url: `${DAEMON_URL}/tachi_txBroadcastSync` },
  confirm: { baseUrl: DAEMON_URL }, // see note below
  name: "cold storage", // optional display label
});

console.log(reg.vaultIdHex);

Option	Type	Description
vault	Vault	Must be built from a compressed user key — TxVaultOpen commits the 33-byte owner key
outpoint	{ txid, vout }	The vault's confirmed L1 funding outpoint
userSigner	TaprootSigner	Signs the TxVaultOpen; x-only key must equal vault.userKey.xOnly
inputs	VaultOpenSpendInput[]	Ledger VTXOs paying the open fee — onboard one first if the account holds none
outputs	VaultOpenChangeOutput[]	Change VTXOs; sum(inputs) - sum(outputs) must equal feeSats
feeSats	bigint	Open fee in sats (commonly 0n)
broadcast	{ url }	Tachi REST broadcast endpoint
confirm	{ baseUrl }	Poll until the tx commits before resolving — see below
name	string	Optional 1–64 byte printable-ASCII display label, no leading/trailing space
nonce	bigint	Explicit nonce; fetched via account when omitted
account	GetAccountNonceOptions	How to fetch the nonce when nonce is omitted

Pass confirm. Without it, registerVault resolves as soon as the mempool admits the tx — that is not registration. Quorum/threshold and fee-balance checks run later at FinalizeBlock, so an unconfirmed open can be accepted and then dropped from the block.

One call per funded vault. The daemon rejects re-registering the same funding outpoint (CodeVaultAlreadyExists).

name is set once and never changeable, not unique, and stored in plaintext consensus state — treat it as a display hint, not an identifier, and escape it before rendering.

discoverVaults(options)

Rebuilds every vault registered under a wallet's owner keys directly from daemon state — no local storage involved.

const vaults = await discoverVaults({
  network: "regtest",
  userWallet, // or userPubkey for a single known key
  validators: { endpoint: "https://rpc-regtest.tachibtc.com/tachi_validators" },
  query: { baseUrl: DAEMON_URL },
});

Option	Type	Description
network	VaultNetworkName	Must match how the vaults were built
userWallet	Wallet	Gap-scans receive-key indices for vaults. Mutually exclusive with userPubkey
userPubkey	string | Buffer	A single compressed owner key — no index scan
validators	{ endpoint: string }	KDHT validator endpoint used to rebuild each vault
nodePubkeys	string[]	Alternative: pass node pubkeys directly, skip the fetch
query	TachiQueryOptions	/tachi_listVaults transport options; set apiKey to rebuild from the daemon's own registered parameters instead of guessing
threshold / csvBlocks	number	Build-time values used only when the daemon record carries no snapshot — a guess, not a fact
requireAddressMatch	boolean	Throw on a rebuilt-vs-registered address mismatch instead of reporting it

Returns DiscoveredVault[] — each entry carries the rebuilt Vault, the daemon's VaultSummary, and the wallet index it was found at.

An empty result is not "no vaults." Only registered vaults are indexed, and a daemon that cannot verify a registration against L1 (e.g. mainnet without a validator quorum) indexes nothing — so this always returns [] there.

The quorum a vault commits to is the genesis CometBFT validator set, not configuration. An env-var list of node keys is a guess at it; check it with fetchConsensusQuorum first.

Tapscript

buildCooperativeScript(userPubkey, nodePubkeys, threshold)

Builds the cooperative leaf script: user CHECKSIGVERIFY + N-of-M KDHT CHECKSIGADD.

buildExitScript(userPubkey, csvBlocks)

Builds the exit leaf script: CSV timelock + user CHECKSIG.

describeTapscript(script)

Returns a human-readable description of a tapscript.

NUMS_INTERNAL_KEY

The BIP-341 NUMS point (lift_x(SHA256(G))). Used as the internal key to disable key-path spending.

P2TR

buildVaultP2tr(options)

Builds the P2TR output from user key, node keys, and CSV config. Lower-level than createVault.

Pubkey Utilities

parsePubkeyHex(hex)

Parses a compressed public key hex string.

toXOnly(pubkey)

Converts a 33-byte compressed pubkey to 32-byte x-only.

hexToXOnly(hex)

Shorthand: hex string → x-only buffer.