@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.

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 — the supported baseline. Works on Node 20 LTS, 22 LTS, 24 LTS.
• Package manager: npm, yarn, or pnpm

Install

viem ^2.38.2 is the only required peer. An Ethereum-only consumer installs the SDK and viem:

pnpm add @babylonlabs-io/ts-sdk viem

The Bitcoin peers are optional. Add their exact supported versions before you import a root or Bitcoin entry:

pnpm add [email protected] @bitcoin-js/[email protected]

The WASM engine is also optional. Add it only for Bitcoin construction and signing paths:

pnpm add @babylonlabs-io/babylon-tbv-rust-wasm

The source manifest uses workspace:* for the WASM peer. The release process replaces it with the exact engine version used in the release rehearsal.

loadRawTbvWasm() is removed

Use the guarded builders in @babylonlabs-io/ts-sdk/tbv/core/primitives.

Upgrade @babylonlabs-io/babylon-tbv-rust-wasm together with this SDK. Engine releases 0.17.0 to 0.19.0 have the /raw entry and do not export the classes from the package root. With one of those releases, buildRefundPsbt() fails.

If you need the low-level classes, call loadTbvWasm() from @babylonlabs-io/ts-sdk/tbv/core/wasm. It returns the initialized engine module. Do the checks that the "WASM Classes" section of the @babylonlabs-io/babylon-tbv-rust-wasm README describes.

ECC Library Initialization (Bitcoin flows only)

ETH-only consumers do not need an ECC library. If your application uses the SDK's Bitcoin/Taproot operations, call initEccLib() once 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 hard dependency boundaries as well as tree-shaking. ETH-only code should import the dedicated /eth entries rather than a broad compatibility barrel:

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

// Ethereum-only readers and prepared peg-in registration (no BTC wallet,
// bitcoinjs-lib, tiny-secp256k1, or WASM required)
import {
  ViemProtocolParamsReader,
  ViemVaultRegistryReader,
  ViemPeginRegistrationClient,
} from "@babylonlabs-io/ts-sdk/tbv/core/clients/eth";

// Ethereum-only transaction receipt helper
import { waitForTransactionReceiptSmartAware } from "@babylonlabs-io/ts-sdk/tbv/core/utils/eth";

// Unauthenticated VP polling without the Bitcoin-auth implementation
import {
  VaultProviderRpcClient,
  batchPollByProvider,
  DaemonStatus,
} from "@babylonlabs-io/ts-sdk/tbv/core/clients/vault-provider/status";

// Mempool reads without bitcoinjs-lib, tiny-secp256k1, or WASM
import { getTxInfo } from "@babylonlabs-io/ts-sdk/tbv/core/clients/mempool";

// Low-level primitives (advanced use cases)
import {
  buildPrePeginPsbt,
  buildPeginTxFromFundedPrePegin,
  buildPayoutPsbt,
  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,
  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 (also dependency-clean for ETH consumers)
import { BTCVaultRegistryABI } from "@babylonlabs-io/ts-sdk/tbv/core/contracts";

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

ViemPeginRegistrationClient owns only the Ethereum submission half of a peg-in. It accepts a signed PegIn transaction, PoP, depositorPayoutScriptPubKey, and depositorBtcPubkeyRaw prepared earlier. It never asks for a BTC wallet. It validates the payout script against the raw key and the PoP key before any contract read or wallet call. PeginManager also checks the wallet address before it delegates to the ETH client.

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