TSB SDK - Token Standard Bitcoin

TypeScript SDK for scanning, parsing, validating, and transferring TSB (Token Standard Bitcoin) tokens on Bitcoin.

🎯 What is TSB?

TSB is a token standard for Bitcoin that enables:

• Token Creation - Create custom tokens on Bitcoin
• Token Transfers - Transfer tokens between addresses
• Atomic Transactions - 3-transaction sequence ensures atomicity
• Witness Scripts - Token data embedded in Taproot witness scripts
• Bitcoin-Native - No external state, fully on-chain

✨ Features

Implemented (Phase 1-8)

• ✅ Token Scanning - Scan Bitcoin addresses for TSB tokens
• ✅ Token Parsing - Extract token data from Taproot witness scripts
• ✅ Token Validation - Verify token structure and compliance
• ✅ Balance Aggregation - Sum balances by token ID
• ✅ Display Formatting - Format tokens for UI display
• ✅ Token Enrichment - Add metadata for UI rendering
• ✅ Fee Estimation - Calculate fees for 3-transaction sequence
• ✅ UTXO Selection - Choose wallet UTXOs for transfers
• ✅ Transaction Building - Build atomic transfer sequence
• ✅ Comprehensive Testing - 240 tests, 76% coverage
• ✅ API Documentation - Auto-generated with TypeDoc
• ✅ Quick Start Guide - Getting started examples
• ✅ Troubleshooting - Common issues & solutions

Planned (Phase 10+)

• 🔜 Transaction Broadcasting - Send transfers to Bitcoin network
• 🔜 Witness Script Signing - Sign witness scripts with keys
• 🔜 Multi-Signature Support - Support for multisig addresses
• 🔜 Advanced Compliance - Frozen/sanctioned token checks
• 🔜 Performance Optimization - Cache & batch operations

�� Installation

npm install @tsb-protocol/sdk

Requirements:

• Node.js 16+
• TypeScript 4.9+
• Bitcoin Core 0.17+ (for RPC)

🚀 Quick Start

1. Setup Bitcoin Connection

import { BitcoinRPC, TSBClient } from '@tsb-protocol/sdk';

const rpc = new BitcoinRPC({
  host: 'localhost',
  port: 18332,        // testnet
  username: 'admin',
  password: 'password',
  network: 'testnet',
});

const client = new TSBClient({ rpc });

2. Scan for Tokens

import { TokenScanner } from '@tsb-protocol/sdk';

const scanner = new TokenScanner(rpc);

const tokens = await scanner.scanAddresses([
  'tb1pqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq6x5dqh',
]);

console.log(`Found ${tokens.length} tokens`);

3. Validate & Format

import { TokenValidator, TokenFormatter } from '@tsb-protocol/sdk';

const validator = new TokenValidator();
const formatter = new TokenFormatter();

tokens.forEach(token => {
  const result = validator.validateToken(token);
  const display = formatter.formatAmount(Number(token.amount));
  
  console.log(`${token.tokenId}: ${display} (valid: ${result.valid})`);
});

4. Prepare Transfer

import { FeeEstimator } from '@tsb-protocol/sdk';

const bitcoinNeeded = FeeEstimator.calculateBitcoinNeeded(
  2,    // satoshis per vByte
  1,    // input count
  0     // output count (no change)
);

console.log(`Bitcoin needed: ${bitcoinNeeded} satoshis`);

📚 Documentation

• Quick Start Guide - Complete usage examples
• Troubleshooting - Common issues & solutions
• API Reference - Complete API documentation
• Architecture - System design & components

🏗️ Architecture

Core Modules

┌─────────────────────────────────────────────┐
│           TSB SDK (TypeScript)              │
├─────────────────────────────────────────────┤
│                                             │
│  ┌──────────────┐    ┌──────────────┐     │
│  │   Scanner    │───▶│   Parser     │     │
│  └──────────────┘    └──────────────┘     │
│         │                                  │
│         ▼                                  │
│  ┌──────────────┐    ┌──────────────┐     │
│  │  Validator   │───▶│  Aggregator  │     │
│  └──────────────┘    └──────────────┘     │
│         │                                  │
│         ▼                                  │
│  ┌──────────────┐    ┌──────────────┐     │
│  │  Formatter   │───▶│  Enricher    │     │
│  └──────────────┘    └──────────────┘     │
│         │                                  │
│         ▼                                  │
│  ┌──────────────────────────────────┐     │
│  │      Transfer Module             │     │
│  │  - FeeEstimator                  │     │
│  │  - UTXOSelector                  │     │
│  │  - TransactionBuilder            │     │
│  └──────────────────────────────────┘     │
│         │                                  │
│         ▼                                  │
│  ┌──────────────┐                         │
│  │ Bitcoin RPC  │                         │
│  └──────────────┘                         │
└─────────────────────────────────────────────┘

Key Classes

Class	Purpose
BitcoinRPC	Communicate with Bitcoin node
TSBClient	Main SDK entry point
TokenScanner	Scan addresses for tokens
TokenParser	Parse token data from scripts
TokenValidator	Validate token structure
TokenFormatter	Format tokens for display
TokenEnricher	Add UI metadata
BalanceAggregator	Sum balances by ID
FeeEstimator	Calculate transfer fees
UTXOSelector	Select UTXOs for transfers
TransactionBuilder	Build transfer transactions

🧪 Testing

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run specific test
npm test -- TokenScanner

# Watch mode
npm test -- --watch

Test Coverage

• 240 tests total
• 76.11% code coverage
• Unit tests - 130 tests
• Edge cases - 72 tests
• Integration tests - 10 tests
• E2E workflow - 24 tests

📖 API Reference

BitcoinRPC

const rpc = new BitcoinRPC(config);

// Make RPC calls
const result = await rpc.call('getblockcount', []);

TokenScanner

const scanner = new TokenScanner(rpc);

// Scan addresses
const tokens = await scanner.scanAddresses(addresses);

TokenValidator

const validator = new TokenValidator();

// Validate token
const result = validator.validateToken(token);

FeeEstimator

// Calculate fees
const bitcoinNeeded = FeeEstimator.calculateBitcoinNeeded(
  feeRate,      // satoshis per vByte
  inputCount,   // number of inputs
  outputCount   // number of outputs
);

For detailed API docs, see docs/api/README.md

🔧 Development

Build

npm run build

Lint

npm run lint

Generate Docs

npm run docs

Project Structure

tsb-sdk/
├── src/
│   ├── core/              # Bitcoin RPC, main client
│   ├── scanner/           # Token scanning & parsing
│   ├── transfer/          # Transfer module
│   ├── display/           # Formatting & enrichment
│   ├── utils/             # Utilities (scripts, addresses, hashing)
│   ├── types/             # TypeScript types
│   └── errors/            # Error classes
├── tests/
│   ├── unit/              # Unit tests
│   ├── edge-cases/        # Edge case tests
│   └── integration/       # Integration tests
├── docs/
│   └── api/               # Generated API docs
├── QUICKSTART.md          # Quick start guide
├── TROUBLESHOOTING.md     # Troubleshooting guide
└── README.md              # This file

🔌 Requirements

Bitcoin Node

• Bitcoin Core 0.17+
• RPC enabled
• Testnet or Mainnet

Bitcoin Configuration

# bitcoin.conf
server=1
rpcuser=admin
rpcpassword=password
rpcbind=127.0.0.1
rpcallowip=127.0.0.1

Node.js

• Node 16+
• npm 7+

📝 Usage Examples

Complete Workflow

import {
  BitcoinRPC,
  TokenScanner,
  TokenValidator,
  TokenFormatter,
  FeeEstimator,
} from '@tsb-protocol/sdk';

async function workflow() {
  // Setup
  const rpc = new BitcoinRPC({
    host: 'localhost',
    port: 18332,
    username: 'admin',
    password: 'password',
    network: 'testnet',
  });

  // Scan
  const scanner = new TokenScanner(rpc);
  const tokens = await scanner.scanAddresses(['tb1ptest']);

  // Validate
  const validator = new TokenValidator();
  tokens.forEach(token => {
    const result = validator.validateToken(token);
    console.log(`Valid: ${result.valid}`);
  });

  // Format
  const formatter = new TokenFormatter();
  tokens.forEach(token => {
    console.log(formatter.formatAmount(Number(token.amount)));
  });

  // Estimate fees
  const fees = FeeEstimator.calculateBitcoinNeeded(2, 1, 0);
  console.log(`Fees: ${fees} satoshis`);
}

workflow().catch(console.error);

🐛 Troubleshooting

Having issues? Check the Troubleshooting Guide for common problems and solutions.

📊 Project Status

Phase	Component	Status
1-5	Core Infrastructure	✅ Complete
6-7	Transfer Module	✅ Complete
8	Testing & QA	✅ Complete
9	Documentation	✅ Complete
10-15	Launch & Post-Launch	🔜 Planned

🤝 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new features
4. Run npm test to verify
5. Submit a pull request

📄 License

MIT - See LICENSE file

🔗 Resources

• Bitcoin Taproot Specification
• Bitcoin Script Reference
• TypeScript Handbook

📞 Support

• Issues: GitHub Issues
• Docs: API Reference
• Guide: Quick Start
• Help: Troubleshooting

---

Version: 0.1.0
Last Updated: October 26, 2025
Status: 🚧 Under Development (Pre-Release)

Tests: 240 passing ✅
Coverage: 76.11% ✅
Build: Passing ✅