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:

Fork the repository
Create a feature branch
Add tests for new features
Run npm test to verify
Submit a pull request

📄 License

MIT - See LICENSE file

🔗 Resources

📞 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 ✅

Name		Name	Last commit message	Last commit date
docs/api		docs/api
src		src
tests		tests
.gitignore		.gitignore
.prettierrc		.prettierrc
LICENSE		LICENSE
QUICKSTART.md		QUICKSTART.md
README.md		README.md
TROUBLESHOOTING.md		TROUBLESHOOTING.md
eslint.config.mjs		eslint.config.mjs
package-lock.json		package-lock.json
package.json		package.json
rollup.config.js		rollup.config.js
tsconfig.json		tsconfig.json
typedoc.json		typedoc.json
vitest		vitest
vitest.config.ts		vitest.config.ts

Latest commit

History

Folders and files

Repository files navigation