@babylonlabs-io/ts-sdk
v0.7.0
Published
TypeScript SDK for Babylon protocol integrations
Readme
@babylonlabs-io/ts-sdk
TypeScript SDK for Trustless Bitcoin Vaults
⚠️ Status: Currently under active development.
Overview
The Babylon TypeScript SDK is a production-ready toolkit for integrating Trustless Bitcoin Vaults into your applications. Currently provides comprehensive support for Trustless Bitcoin Vaults (TBV) including vault management and supported application integrations.
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
Installation
Requirements
- Node.js >= 24.0.0
- Package manager: npm, yarn, or pnpm
Install
# npm
npm install @babylonlabs-io/ts-sdk viem
# yarn
yarn add @babylonlabs-io/ts-sdk viem
# pnpm
pnpm add @babylonlabs-io/ts-sdk viemVerify Installation
import { buildPeginPsbt } from "@babylonlabs-io/ts-sdk/tbv/core/primitives";
console.log("✅ SDK installed successfully!");
console.log("buildPeginPsbt type:", typeof buildPeginPsbt);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 {
buildPeginPsbt,
buildPayoutPsbt,
buildDepositorPayoutPsbt,
buildNoPayoutPsbt,
buildChallengeAssertPsbt,
} from "@babylonlabs-io/ts-sdk/tbv/core/primitives";
// Utilities
import { selectUtxosForPegin } from "@babylonlabs-io/ts-sdk/tbv/core";
// Shared types and wallet interfaces
import { BitcoinWallet, UTXO } from "@babylonlabs-io/ts-sdk/shared";
// Contract ABIs
import { BTCVaultRegistryABI } from "@babylonlabs-io/ts-sdk/tbv/core";
// Protocol integrations (Aave)
import {
buildAddCollateralTx,
buildBorrowTx,
getUserAccountData,
calculateHealthFactor,
} from "@babylonlabs-io/ts-sdk/tbv/integrations/aave";Choose Your API Level
The SDK provides two integration approaches:
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
Trustless Bitcoin Vaults (TBV) Documentation
🚀 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)
🔌 Application Integrations
Use BTC vaults in DeFi protocols and applications:
- Aave v4 - Use vaults as collateral to borrow assets
🔍 API Reference
Auto-generated from TSDoc comments using TypeDoc:
- API Reference - Complete auto-generated API documentation
🛠️ Troubleshooting
- Troubleshooting Guide - Common issues and solutions
