@babylonlabs-io/ts-sdk

TypeScript SDK for Trustless Bitcoin Vaults

Overview

The Babylon TypeScript SDK is the toolkit for integrating Trustless Bitcoin Vaults into your applications. It provides vault lifecycle management (peg-in, activation, refund, payout signing) and application integrations built on top, starting with Aave v4.

What Are Trustless Bitcoin Vaults?

Trustless Bitcoin Vaults (TBV) let you lock Bitcoin and use it in applications on supported chains (like lending protocols) without giving up custody. The vault protocol enables:

• Peg-in: Lock BTC in a vault on Bitcoin to use as collateral (protocol spec)
• Peg-out: Unlock BTC from the vault back to your wallet (protocol spec)
• DeFi Integration: Use vaulted BTC in protocols like Aave

This SDK handles the complex Bitcoin and Ethereum interactions needed to create and manage these vaults.

Key Features

• 🔐 Vault Management - Vault creation (Pegin), vault redemption (Pegout), and vault lifecycle operations
• 🔌 Application Integrations - Pre-built integrations starting with Aave (DeFi lending)
• 📦 Framework Agnostic - Works with React, Vue, Angular, Node.js, or vanilla JavaScript
• 🎯 Type-Safe - Comprehensive TypeScript types with full IDE support
• 🧩 Modular Design - Use only what you need via subpath exports
• 🔧 Extensible - Easy to build custom integrations

Platforms

This SDK runs on both Node.js backends and browser/React frontends — the entire library is framework-agnostic. The only difference between the two environments is how you supply two things: a Bitcoin wallet and an Ethereum wallet. The SDK provides interfaces (BitcoinWallet, viem's WalletClient) and you adapt whichever wallet is available on your platform.

| Concern | Node.js backend | Browser / React | |---------|-----------------|-----------------| | BitcoinWallet | Build from a seed via bitcoinjs-lib + bip32 (or call KMS/HSM) | Adapt an injected wallet (Unisat, OKX, Xverse, Leather) | | viem WalletClient | createWalletClient({ account: privateKeyToAccount(pk), chain, transport: http(RPC_URL) }) | createWalletClient({ account, chain, transport: custom(window.ethereum) }) via wagmi | | Secret storage | Your DB / KMS (required for activation later) | Session/local storage or user-supplied | | WASM loading | Automatic (SDK reads .wasm off disk with node:fs) | Automatic (SDK fetches .wasm via bundler) |

If you're using a bundler (Vite, webpack, Next.js), ensure it's configured to handle .wasm assets and that Buffer is available on the global in browser targets — see the Troubleshooting Guide.

Installation

Requirements

• Node.js ≥ 20.3.0 (for AbortSignal.any()). Works on Node 20 LTS, 22 LTS, 24 LTS.
• Package manager: npm, yarn, or pnpm

Install

# npm
npm install @babylonlabs-io/ts-sdk viem bitcoinjs-lib @bitcoin-js/tiny-secp256k1-asmjs

# yarn
yarn add @babylonlabs-io/ts-sdk viem bitcoinjs-lib @bitcoin-js/tiny-secp256k1-asmjs

# pnpm
pnpm add @babylonlabs-io/ts-sdk viem bitcoinjs-lib @bitcoin-js/tiny-secp256k1-asmjs

ECC Library Initialization (required, once at startup)

The SDK uses bitcoinjs-lib for Taproot operations. Call initEccLib() once at application startup before any SDK call that builds a PSBT or derives a Bitcoin address:

import * as ecc from "@bitcoin-js/tiny-secp256k1-asmjs";
import { initEccLib } from "bitcoinjs-lib";

initEccLib(ecc);

• Node.js: call this at the top of your entry point (index.ts / CLI entry).
• React: call it in main.tsx / app.tsx before createRoot().

Failing to initialize produces a runtime error: "No ECC Library provided".

The WASM package used internally (@babylonlabs-io/babylon-tbv-rust-wasm) initializes itself lazily — no extra call needed.

Verify Installation

import { buildPrePeginPsbt } from "@babylonlabs-io/ts-sdk/tbv/core/primitives";

console.log("✅ SDK installed successfully!");
console.log("buildPrePeginPsbt type:", typeof buildPrePeginPsbt);

Run with: npx tsx verify-install.ts

Troubleshooting? See Troubleshooting Guide for Buffer polyfills, WASM setup, and bundler configuration.

Package Structure

The SDK uses subpath exports for tree-shaking:

// High-level managers (recommended for most users)
import { PeginManager, PayoutManager } from "@babylonlabs-io/ts-sdk/tbv/core";

// Low-level primitives (advanced use cases)
import {
  buildPrePeginPsbt,
  buildPeginTxFromFundedPrePegin,
  buildPayoutPsbt,
  buildDepositorPayoutPsbt,
  buildNoPayoutPsbt,
  buildChallengeAssertPsbt,
  buildRefundPsbt,
  formatSatoshisToBtc,
} from "@babylonlabs-io/ts-sdk/tbv/core/primitives";

// Services (activation, deposit validation, protocol state)
import {
  activateVault,
  getPeginProtocolState,
  ContractStatus,
  validateDepositAmount,
  isPegoutTerminalStatus,
} from "@babylonlabs-io/ts-sdk/tbv/core/services";

// Utilities
import {
  selectUtxosForPegin,
  collectReservedUtxoRefs,
  validateUtxosAvailable,
} from "@babylonlabs-io/ts-sdk/tbv/core";

// Shared wallet interfaces
import { BitcoinWallet } from "@babylonlabs-io/ts-sdk/shared";
// UTXO type lives in the core utils module
import { UTXO } from "@babylonlabs-io/ts-sdk/tbv/core";

// Contract ABIs
import { BTCVaultRegistryABI } from "@babylonlabs-io/ts-sdk/tbv/core";

// Protocol integrations (Aave)
import {
  buildBorrowTx,
  buildRepayTx,
  getUserAccountData,
  calculateHealthFactor,
} from "@babylonlabs-io/ts-sdk/tbv/integrations/aave";

Where to start

The SDK exposes several peer entry points — managers, services, primitives, utils, clients, and integrations — and you compose the pieces you need. The two most common starting points for a new integration are:

Managers (High-Level)

• What: Pre-built wallet orchestration for complete vault workflows
• Best for: Web apps, browser wallets (MetaMask, Unisat)
• You provide: Wallet interface
• SDK handles: Transaction building, signing coordination, contract calls

Primitives (Low-Level, Advanced)

• What: Pure functions for building Bitcoin PSBTs
• Best for: Backend services, custom signing (KMS/HSM), full control
• You provide: Everything (signing logic, contract calls, broadcasting)
• SDK handles: Only PSBT construction and utility functions

For how services, utils, clients, and integrations fit in and which layer a given task belongs to, read the Get Started guide.

Documentation

🏁 Start here

• Get Started — five-minute orientation: what TBV is, the SDK's layer layout, prerequisites, config sourcing, glossary, vault lifecycle, and a decision table routing you to the right quickstart. Read this first if you're new.

🚀 Quickstart

Step-by-step tutorials:

• Managers Quickstart - Create a Bitcoin vault with wallet integration (step-by-step)
• Primitives Quickstart - Build vault PSBTs with custom signing logic (advanced)

🔑 Guides

• Wallet Interfaces - Adapt any BTC/ETH wallet (browser, Node.js, KMS/HSM) to the SDK's interfaces

🔌 Application Integrations

Use BTC vaults in DeFi protocols and applications:

• Aave v4 - Use vaults as collateral to borrow assets
  • Overview & API Reference
  • Quickstart Guide

🔍 API Reference

Auto-generated from TSDoc comments using TypeDoc:

• API Reference - Complete auto-generated API documentation

🛠️ Troubleshooting

• Troubleshooting Guide - Common issues and solutions

Links

• GitHub Repository
• Report an Issue
• NPM Package
• Contributing Guide