btc-stamps
@btc-stamps/tx-builder 🚀
The Bitcoin transaction builder for Bitcoin Stamps and SRC-20 metaprotocols
Build Bitcoin transactions with native support for Bitcoin Stamps, SRC-20 tokens, Ordinals protection, and extensible metaprotocol support.
Installation • Quick Start • Examples • Documentation • API Reference
🎯 Why tx-builder?
@btc-stamps/tx-builder is the only transaction builder with first-class support for Bitcoin Stamp metaprotocols. This can be extended to support other metaprotocols like Runes or BRC-20.
✨ Key Features
- 🖼️ Bitcoin Stamps: Complete Bitcoin Stamp metaprotocol support
- 🪙 SRC-20 Tokens: Full lifecycle support (deploy, mint, transfer)
- 🛡️ UTXO Protection: Automatic protection of Ordinals, Inscriptions, Stamps & Counterparty assets
- ⚡ Smart Selection: 6 UTXO selection algorithms with optimization
- 🔌 Zero Config: Works out-of-the-box with reliable defaults
- 🌳 Tree-Shakeable: Optimized for modern bundlers with
sideEffects: false - 📦 Lightweight: Minimal dependencies, maximum performance
- 🧪 Battle-Tested: Comprehensive test suite with 430+ tests
- 🔒 Type-Safe: Full TypeScript support with detailed types
📦 Installation
Node.js / TypeScript
npm install @btc-stamps/tx-builder
# or
yarn add @btc-stamps/tx-builder
# or
pnpm add @btc-stamps/tx-builderDeno
import { TransactionBuilder } from 'npm:@btc-stamps/tx-builder@^0.1.6';Requirements
- Node.js >= 18.0.0 or Bun >= 1.0.0
- TypeScript >= 5.0.0 (for TypeScript users)
- Deno: Partial support via npm compatibility (see guide)
🚀 Quick Start
Bitcoin Stamps with UTXO Protection
import { BitcoinStampBuilder, SelectorFactory } from '@btc-stamps/tx-builder';
// Zero-config setup with automatic UTXO protection
const selectorFactory = SelectorFactory.getInstance();
const builder = new BitcoinStampBuilder(network, selectorFactory);
// Build stamp transaction - automatically protects:
// ✅ Ordinals (sats with inscriptions or runes)
// ✅ Bitcoin Stamps (all types)
// ✅ Counterparty assets (XCP, PEPECASH, etc.)
// ✅ SRC-20 tokens
const result = await builder.buildStampTransaction(utxos, {
stampData: {
imageData: imageBuffer,
filename: 'my-stamp.png',
},
fromAddress: 'bc1q...',
feeRate: 20,
algorithm: 'protection-aware', // Optional: explicitly use protection-aware selection
});SRC-20 Tokens
import { SRC20Encoder, SRC20TokenBuilder } from '@btc-stamps/tx-builder';
const encoder = new SRC20Encoder();
// Deploy new token
const deployData = await encoder.encode({
p: 'SRC-20',
op: 'DEPLOY',
tick: 'KEVIN',
max: '21000000',
lim: '1000',
});
// Build transaction
const psbt = await new SRC20TokenBuilder().buildSRC20Transaction({
encodedData: deployData,
utxos: selectedUTXOs,
changeAddress: 'bc1q...',
feeRate: 15,
});🛡️ Advanced UTXO Protection
Built-in protection for Ordinals, Inscriptions, Stamps, Counterparty assets, and SRC-20 tokens is automatic in all builders.
// For custom protection configuration:
const selector = selectorFactory.createSelector('protection-aware', {
protectionConfig: {
enableOrdinalsDetection: true, // Detect inscriptions and runes
enableCounterpartyDetection: true, // Detect UTXO attached assets
enableStampsDetection: true, // Detect UTXO attached stamps
},
});
// Use with any builder
builder.setSelector(selector);⚡ UTXO Selection Algorithms
Optimize transaction fees with multiple selection strategies:
import {
AccumulativeSelector, // Fast selection
BlackjackSelector, // Target exact amounts
BranchAndBoundSelector, // Optimal selection
WasteOptimizedSelector, // Long-term optimization
} from '@btc-stamps/tx-builder';🌐 Network Support
Zero-configuration with reliable defaults:
// Works immediately - no setup required
const provider = new ElectrumXProvider(); // Uses blockstream.info, fortress.qtornado.com, etc.Networks: Mainnet, Testnet, Regtest with automatic server selection
📚 Learn More
- 📖 Documentation Site - Interactive documentation
- 🔌 API Reference - Complete API documentation
- 💡 Examples - Ready-to-use code examples
- 🛡️ UTXO Protection Guide - Essential for production
- 🏗️ Architecture Overview - Technical deep dive
- 📦 NPM Package - View on npm registry
- 🦕 JSR Package - View on JSR (Deno/TypeScript)
🧪 Testing
npm test # Run all tests
npm run test:unit # Unit tests only
npm run test:coverage # Coverage report🤝 Contributing
Contributions welcome! See Contributing Guide for details.
Development Setup
# Clone the repository
git clone https://github.com/btc-stamps/tx-builder.git
cd tx-builder
# Install dependencies
npm install
# Run tests
npm test
# Build the package
npm run build📄 License
MIT License - see LICENSE file.
🙏 Acknowledgments
Built on top of excellent libraries:
- bitcoinjs-lib - Bitcoin protocol implementation
- tiny-secp256k1 - Elliptic curve cryptography
- bip32 - HD wallet support
💬 Support
- GitHub Issues: Report bugs or request features
- Discussions: Ask questions and share ideas
- Telegram: @BitcoinStamps
GitHub: btc-stamps/tx-builder • NPM: @btc-stamps/tx-builder • JSR: @btc-stamps/tx-builder • Telegram: @BitcoinStamps
Built with ❤️ by the Stampchain team
