TETSUO Blockchain Wallet SDK

 ████████╗███████╗████████╗███████╗██╗   ██╗ ██████╗     ██╗    ██╗ █████╗ ██╗     ██╗     ███████╗████████╗
 ╚══██╔══╝██╔════╝╚══██╔══╝██╔════╝██║   ██║██╔═══██╗    ██║    ██║██╔══██╗██║     ██║     ██╔════╝╚══██╔══╝
    ██║   █████╗     ██║   ███████╗██║   ██║██║   ██║    ██║ █╗ ██║███████║██║     ██║     █████╗     ██║
    ██║   ██╔══╝     ██║   ╚════██║██║   ██║██║   ██║    ██║███╗██║██╔══██║██║     ██║     ██╔══╝     ██║
    ██║   ███████╗   ██║   ███████║╚██████╔╝╚██████╔╝    ╚███╔███╔╝██║  ██║███████╗███████╗███████╗   ██║
    ╚═╝   ╚══════╝   ╚═╝   ╚══════╝ ╚═════╝  ╚═════╝      ╚══╝╚══╝ ╚═╝  ╚═╝╚══════╝╚══════╝╚══════╝   ╚═╝

Secure Blockchain Wallet • Client-Side Signing • Zero Trust Architecture

A production-ready TypeScript SDK for building and managing TETSUO blockchain wallets. Provides secure wallet generation, transaction signing, and blockchain interaction with client-side signing for maximum security.

Table of Contents

• Features
• Installation
• Quick Start
• CLI Usage
• API Reference
• Security
• Examples
• Development
• Contributing
• License

Features

🔐 Wallet Management

• BIP39 Mnemonics: Generate 12-word recovery phrases for wallet backup
• Multiple Import Methods: Import from mnemonics or private keys
• Secure Key Derivation: Secp256k1 elliptic curve cryptography
• Local Wallet Storage: Encrypted wallet data at ~/.tetsuo/wallets.json

💱 Transaction Operations

• Client-Side Signing: All transactions signed locally (never share private keys)
• Automatic UTXO Selection: Smart coin selection algorithm
• Dynamic Fee Calculation: Accurate fee estimation based on network
• Transaction Building: Complete transaction hex generation

📍 Address Management

• TETSUO Address Generation: From public keys with proper checksums
• Address Validation: Format and checksum verification
• Hash160 Support: Extract address information

🌐 Blockchain Interaction

• RPC Client: Full-featured network communication
• Balance Queries: Get balance in TETSUO
• UTXO Fetching: For transaction input selection
• Transaction Broadcasting: Publish signed transactions
• Fee Estimation: Network-based fee calculation

🔒 Cryptography

• SHA256 & RIPEMD160: Standard blockchain hashing
• Base58Check Encoding: Bitcoin-compatible address encoding
• ECDSA Signing: Secp256k1 signature generation
• Secure Random: Cryptographically secure key generation

Installation

npm install -g tetsuo-blockchain-wallet

Or for programmatic use:

npm install tetsuo-blockchain-wallet

Quick Start

Interactive CLI (Easiest)

tetsuo

Then use commands like:

/create-wallet    - Create new wallet
/balance          - Check balance
/send             - Send TETSUO tokens
/list-wallets     - View all wallets
/exit             - Exit program

Programmatic API

import {
  generateWallet,
  createRPCClient,
  buildTransaction,
  signTransaction,
  createTransactionHex
} from 'tetsuo-blockchain-wallet';

// Create wallet
const wallet = await generateWallet();
console.log('Address:', wallet.address);
console.log('Backup mnemonic:', wallet.mnemonic);

// Get balance
const rpc = createRPCClient('https://tetsuoarena.com');
const balance = await rpc.getBalance(wallet.address);
console.log('Balance:', balance, 'TETSUO');

// Send transaction
const utxos = await rpc.getUTXOs(wallet.address);
const { inputs, outputs } = buildTransaction(
  wallet.address,
  'T1234567890abcdefghijklmnopqrstuvwxyz',
  1.5, // 1.5 TETSUO
  utxos,
  wallet.address
);

const txHex = createTransactionHex(inputs, outputs);
const signedTx = signTransaction(txHex, wallet.privateKey, inputs, utxos);
const txid = await rpc.broadcastTransaction(signedTx);
console.log('Sent! TXID:', txid);

CLI Usage

Start the CLI

tetsuo

Available Commands

| Command | Description | |---------|-------------| | /create-wallet | Create new wallet with BIP39 mnemonic | | /import-wallet | Import from existing mnemonic or private key | | /list-wallets | Display all stored wallets | | /select-wallet | Choose active wallet for operations | | /balance | Check current wallet balance | | /transactions | View transaction history | | /receive | Display receiving address | | /send | Send TETSUO to another address | | /wallet-data | View detailed wallet information | | /delete-wallet | Remove wallet from storage | | /config | Configure RPC endpoint | | /exit | Quit the CLI |

Example Workflow

$ tetsuo

[...] Generating wallet...
[OK] Wallet created successfully!
[NOTE] Mnemonic (BACKUP THIS):
word1 word2 word3 word4 word5 word6 word7 word8 word9 word10 word11 word12

[ADDR] Address:
TAbcdefghijklmnopqrstuvwxyz1234567890

$ /balance
[...] Fetching balance...
[BALANCE] Balance Information:
──────────────────────────────────────────────────
  Wallet:  my-wallet
  Address: TAbcdefghijklmnopqrstuvwxyz1234567890
  Balance: 10.50000000 TETSUO
──────────────────────────────────────────────────

$ /send
Recipient address: T1111111111111111111111111111111111111111
Amount (TETSUO): 5

[...] Preparing transaction...
[HISTORY] Transaction Details:
────────────────────────────────────────────────────────────
  From:     TAbcdefghijklmnopqrstuvwxyz1234567890
  To:       T1111111111111111111111111111111111111111
  Amount:   5.00000000 TETSUO
  Fee:      0.00025000 TETSUO
  Total:    5.00025000 TETSUO
────────────────────────────────────────────────────────────

Confirm transaction? (yes/no): yes

[...] Signing transaction...
[OK] Transaction sent successfully!

[INFO] Transaction Info:
TXID: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6...

Configuration

# Custom RPC endpoint
export TETSUO_RPC_URL=https://your-rpc-server.com
tetsuo

# Default RPC (if not set)
# https://tetsuoarena.com

Wallet Storage

Wallets are stored locally at:

~/.tetsuo/wallets.json

Each wallet contains:

• Name (user-defined)
• Address (TETSUO blockchain address)
• Public Key (compressed format)
• Private Key (hex format, handle with care!)
• Mnemonic (if wallet was generated)
• Creation timestamp

API Reference

Wallet Functions

generateWallet(): Promise<Wallet>

Generate new wallet with random BIP39 mnemonic.

const wallet = await generateWallet();
// {
//   mnemonic: "word1 word2 ... word12",
//   privateKey: "abcd1234...",
//   publicKey: "02abcd1234...",
//   address: "TAbcdef..."
// }

importFromMnemonic(mnemonic: string): Promise<Wallet>

Import wallet from 12-word BIP39 mnemonic.

const wallet = await importFromMnemonic(
  'word1 word2 word3 word4 word5 word6 word7 word8 word9 word10 word11 word12'
);

importFromPrivateKey(privateKey: string): Wallet

Import wallet from 64-character hex private key.

const wallet = importFromPrivateKey('abcd1234...0000');

isValidMnemonic(mnemonic: string): boolean

Validate BIP39 mnemonic phrase.

derivePublicKey(privateKey: string): string

Derive compressed public key from private key.

Address Functions

isValidAddress(address: string): boolean

Check if TETSUO address format is valid.

validateAddress(address: string): string

Validate address or throw error.

generateAddress(publicKey: string): string

Generate TETSUO address from public key.

Transaction Functions

buildTransaction(fromAddr, toAddr, amount, utxos, changeAddr): TransactionData

Build unsigned transaction with automatic UTXO selection.

const txData = buildTransaction(
  'TFrom...',
  'TTo...',
  1.5,        // TETSUO amount
  utxos,
  'TChangeAddr...'
);
// Returns: { inputs, outputs, fee }

createTransactionHex(inputs, outputs): string

Create transaction hex from inputs and outputs.

signTransaction(txHex, privateKey, inputs, utxos): string

Sign transaction with private key. Returns signed transaction hex.

estimateFee(inputCount, outputCount): number

Estimate transaction fee in satoshis.

RPC Client

createRPCClient(url?: string): RPC

Create RPC client instance.

const rpc = createRPCClient('https://tetsuoarena.com');

rpc.getBalance(address: string): Promise<number>

Get balance in TETSUO.

rpc.getUTXOs(address: string): Promise<UTXO[]>

Get unspent transaction outputs for address.

rpc.getTransactionHistory(address: string): Promise<Transaction[]>

Get transaction history for address.

rpc.broadcastTransaction(txHex: string): Promise<string>

Broadcast signed transaction. Returns TXID.

rpc.ping(): Promise<boolean>

Health check for RPC endpoint.

Security

🔒 Critical Security Guidelines

Private Keys

• Never expose private keys
• Never share mnemonics
• Back up mnemonics offline only
• Consider using hardware wallets for large amounts

Network Security

• Always use HTTPS for RPC endpoints in production
• Verify RPC endpoint authenticity
• Use verified blockchain explorers
• Never paste private keys into unsecured apps

Client-Side Signing

• This SDK signs transactions on your device only
• Private keys never leave your computer
• Broadcast-only servers can't steal funds
• Always verify transaction details before confirming

Best Practices

// ✓ GOOD: Small test transaction first
const testTx = buildTransaction(from, to, 0.01, utxos, from);

// ✓ GOOD: Verify amounts before signing
console.log('Sending:', amount, 'to:', toAddress);

// ✗ BAD: Never log private keys
console.log(wallet.privateKey); // DON'T DO THIS

// ✗ BAD: Never send to unverified addresses
const address = userInput; // Verify first!

Examples

Example 1: Create and Export Wallet

import { generateWallet } from 'tetsuo-blockchain-wallet';

const wallet = await generateWallet();

console.log('📝 SAVE THIS MNEMONIC SECURELY:');
console.log(wallet.mnemonic);

console.log('Your Address:', wallet.address);
console.log('Share this address to receive TETSUO');

Example 2: Check Balance

import { createRPCClient } from 'tetsuo-blockchain-wallet';

const rpc = createRPCClient('https://tetsuoarena.com');
const balance = await rpc.getBalance('TYourAddressHere');
console.log(`Balance: ${balance} TETSUO`);

Example 3: Send Transaction

import {
  createRPCClient,
  buildTransaction,
  createTransactionHex,
  signTransaction,
  importFromMnemonic
} from 'tetsuo-blockchain-wallet';

// Import wallet
const mnemonic = 'word1 word2 ... word12';
const wallet = await importFromMnemonic(mnemonic);

// Setup
const rpc = createRPCClient('https://tetsuoarena.com');
const recipientAddress = 'TRecipientAddressHere';
const amountTetsuo = 2.5;

// Get UTXOs
const utxos = await rpc.getUTXOs(wallet.address);

// Build transaction
const { inputs, outputs, fee } = buildTransaction(
  wallet.address,
  recipientAddress,
  amountTetsuo,
  utxos,
  wallet.address // change address
);

// Sign and broadcast
const txHex = createTransactionHex(inputs, outputs);
const signedTx = signTransaction(txHex, wallet.privateKey, inputs, utxos);
const txid = await rpc.broadcastTransaction(signedTx);

console.log(`✓ Transaction sent!`);
console.log(`TXID: ${txid}`);
console.log(`Explorer: https://tetsuoarena.com/tx/${txid}`);

Example 4: Error Handling

import {
  InvalidAddressError,
  InsufficientFundsError,
  RPCError,
  WalletError
} from 'tetsuo-blockchain-wallet';

try {
  const wallet = await generateWallet();
  // ... transaction logic
} catch (error) {
  if (error instanceof InvalidAddressError) {
    console.error('Invalid recipient address');
  } else if (error instanceof InsufficientFundsError) {
    console.error('Not enough balance');
  } else if (error instanceof RPCError) {
    console.error('Network error:', error.message);
  } else if (error instanceof WalletError) {
    console.error('Wallet error:', error.message);
  }
}

Development

Build

npm run build

Compiles TypeScript to JavaScript in dist/ directory.

Tests

npm test

Run full test suite with Jest.

Watch Mode

npm run dev

Auto-recompile TypeScript on file changes.

Clean

npm run clean

Remove compiled files and coverage reports.

Recent Updates

Version 1.2.4 ✨

• Fixed critical endianness bug in transaction encoding (vout, sequence fields)
• Removed emojis from CLI for professional interface
• Added ASCII art header to wallet CLI
• Improved terminal output clarity

Version 1.2.3

• Client-side signing fully functional
• TETSUO-specific transaction format fixes (sequence 0xffffffff, SIGHASH_ALL)

Version 1.2.2

• Secp256k1 key derivation improvements
• Legacy HMAC wallet support (deprecated)

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Requirements:

• Follow TypeScript best practices
• Add tests for new features
• Update documentation
• All tests must pass

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

License

MIT License - see LICENSE file for details

Disclaimer

This software is provided "as is" without warranty. The authors are not responsible for lost funds or security breaches. Always test with small amounts first and follow security best practices.

Made with ❤️ for the TETSUO blockchain community