CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-bsv

JavaScript library for Bitcoin SV (BSV) blockchain development with cryptographic primitives, transaction handling, and protocol implementations

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

core-bitcoin.mddocs/

Core Bitcoin Functionality

Core Bitcoin components for addresses, transactions, scripts, and blocks.

Imports

// ES6 imports
import { Address, Tx, Script, PrivKey, PubKey, Block, BlockHeader, TxIn, TxOut } from 'bsv'

// CommonJS imports
const { Address, Tx, Script, PrivKey, PubKey, Block, BlockHeader, TxIn, TxOut } = require('bsv')

Address

Bitcoin addresses for sending and receiving payments with full mainnet/testnet support.

Class Definition

class Address {
  constructor(
    versionByteNum: number,    // Network version byte
    hashBuf: Buffer,           // Hash160 of public key
    constants?: object         // Network constants
  )

  // Core properties
  versionByteNum: number       // Network version byte
  hashBuf: Buffer             // Hash160 of public key
  Constants: object           // Network constants

  // Creation methods
  static fromPubKey(pubKey: PubKey): Address
  static fromPrivKey(privKey: PrivKey): Address  
  static fromPubKeyHashBuf(hashBuf: Buffer): Address
  static fromString(addressStr: string): Address
  static fromRandom(): Address
  static fromBuffer(buf: Buffer): Address

  // Serialization methods
  toString(): string
  toBuffer(): Buffer
  toHex(): string
  toJSON(): object

  // Script generation
  toTxOutScript(): Script      // Create P2PKH script

  // Validation
  static isValid(addressStr: string): boolean
  validate(): Address
  isValid(): boolean

  // Network variants
  static Mainnet: typeof Address
  static Testnet: typeof Address

  // Async variants
  static asyncFromPubKey(pubKey: PubKey): Promise<Address>
  static asyncFromPrivKey(privKey: PrivKey): Promise<Address>
  asyncToString(): Promise<string>
}

Usage Examples

// Generate random address
const address = Address.fromRandom()
console.log(address.toString()) // "1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2"

// Create address from private key
const privKey = PrivKey.fromRandom()
const address = Address.fromPrivKey(privKey)

// Create address from public key
const pubKey = PubKey.fromPrivKey(privKey)
const address = Address.fromPubKey(pubKey)

// Parse and validate address
const addressStr = '1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2'
const isValid = Address.isValid(addressStr)
const address = Address.fromString(addressStr)

// Generate payment script
const script = address.toTxOutScript() // P2PKH script

// Network-specific addresses
const mainnetAddr = Address.Mainnet.fromRandom()
const testnetAddr = Address.Testnet.fromRandom()

// Async operations
const address = await Address.asyncFromPrivKey(privKey)

Transaction (Tx)

Bitcoin transaction representation with full signing and verification support.

Class Definition

class Tx {
  constructor(
    versionBytesNum?: number,  // Transaction version (default: 1)
    txInsVi?: VarInt,         // Number of inputs
    txIns?: TxIn[],           // Transaction inputs
    txOutsVi?: VarInt,        // Number of outputs  
    txOuts?: TxOut[],         // Transaction outputs
    nLockTime?: number        // Lock time (default: 0)
  )

  // Core properties
  versionBytesNum: number     // Transaction version
  txIns: TxIn[]              // Array of inputs
  txOuts: TxOut[]            // Array of outputs
  nLockTime: number          // Lock time

  // Creation methods
  static fromBuffer(buf: Buffer): Tx
  static fromHex(hex: string): Tx
  static fromJSON(json: object): Tx
  static fromBr(br: Br): Tx

  // Serialization methods
  toBuffer(): Buffer
  toHex(): string
  toJSON(): object
  toBw(bw?: Bw): Bw

  // Input/Output management
  addTxIn(
    txHashBuf: Buffer,        // Previous tx hash
    txOutNum: number,         // Previous output index
    script?: Script,          // Unlocking script
    nSequence?: number        // Sequence number
  ): Tx
  
  addTxOut(
    valueBn: Bn,             // Output value in satoshis
    script: Script           // Locking script
  ): Tx

  // Transaction identification
  hash(): Buffer            // Transaction hash
  id(): string             // Transaction ID (reversed hash hex)

  // Signing and verification
  sighash(
    nHashType: number,       // Hash type (e.g., SIGHASH_ALL)
    nIn: number,            // Input index
    subScript: Script,      // Script being signed
    valueBn: Bn,           // Input value
    flags?: number,         // Script flags
    hashCache?: object      // Hash cache for optimization
  ): Buffer

  sighashPreimage(
    nHashType: number,
    nIn: number, 
    subScript: Script,
    valueBn: Bn,
    flags?: number
  ): Buffer

  sign(
    keyPair: KeyPair,       // Signing key pair
    nHashType: number,      // Hash type
    nIn: number,           // Input index
    subScript: Script,     // Script being signed
    valueBn: Bn,          // Input value
    flags?: number,        // Script flags
    hashCache?: object     // Hash cache
  ): Sig

  verify(
    sig: Sig,              // Signature to verify
    pubKey: PubKey,        // Public key
    nIn: number,          // Input index
    subScript: Script,    // Script being verified
    enforceLowS?: boolean, // Enforce low-S signature
    valueBn?: Bn,         // Input value
    flags?: number,       // Script flags
    hashCache?: object    // Hash cache
  ): boolean

  // Utility methods
  isCoinbase(): boolean    // Check if coinbase transaction
  sort(): Tx              // Apply BIP 69 sorting

  // Constants
  static MAX_MONEY: Bn                        // 21M * 1e8 satoshis
  static SCRIPT_ENABLE_SIGHASH_FORKID: number // SIGHASH_FORKID flag

  // Async variants
  asyncHash(): Promise<Buffer>
  asyncId(): Promise<string>
  asyncSighash(...args): Promise<Buffer>
  asyncSign(...args): Promise<Sig>
  asyncVerify(...args): Promise<boolean>
}

Usage Examples

// Create new transaction
const tx = new Tx()

// Add inputs and outputs
const txHashBuf = Buffer.from('...', 'hex')
tx.addTxIn(txHashBuf, 0, Script.fromAsmString(''), 0xffffffff)
tx.addTxOut(Bn.fromNumber(50000), Script.fromPubKeyHash(hashBuf))

// Transaction identification
const txHash = tx.hash()
const txId = tx.id()

// Sign transaction input
const keyPair = KeyPair.fromPrivKey(privKey)
const subScript = Script.fromPubKeyHash(pubKeyHashBuf)
const valueBn = Bn.fromNumber(100000)
const sig = tx.sign(keyPair, Sig.SIGHASH_ALL, 0, subScript, valueBn)

// Verify signature
const isValid = tx.verify(sig, pubKey, 0, subScript, true, valueBn)

// Serialization
const txHex = tx.toHex()
const tx2 = Tx.fromHex(txHex)

// Check if coinbase
const isCoinbase = tx.isCoinbase()

// Apply BIP 69 sorting
tx.sort()

// Async operations
const hash = await tx.asyncHash()
const sig = await tx.asyncSign(keyPair, Sig.SIGHASH_ALL, 0, subScript, valueBn)

Script

Bitcoin Script language implementation with comprehensive operation support.

Class Definition

class Script {
  constructor(chunks?: Array<Buffer | OpCode>)

  // Core properties
  chunks: Array<Buffer | OpCode>  // Script operations and data

  // Creation methods
  static fromBuffer(buf: Buffer): Script
  static fromHex(hex: string): Script
  static fromString(str: string): Script
  static fromBitcoindString(str: string): Script
  static fromAsmString(str: string): Script

  // Specialized script creation
  static fromOpReturnData(dataBuf: Buffer): Script
  static fromSafeData(dataBuf: Buffer): Script     // OP_FALSE OP_RETURN
  static fromPubKeyHash(hashBuf: Buffer): Script   // P2PKH script
  static fromPubKeys(
    m: number,              // Required signatures
    pubKeys: PubKey[],      // Public keys
    sort?: boolean          // Sort keys lexicographically
  ): Script                 // Multisig script

  // Serialization methods
  toBuffer(): Buffer
  toHex(): string
  toString(): string
  toBitcoindString(): string
  toAsmString(): string

  // Script building
  writeOpCode(opCodeNum: number): Script
  writeBuffer(buf: Buffer): Script
  writeBn(bn: Bn): Script
  writeScript(script: Script): Script

  // Script type detection
  isPushOnly(): boolean
  isOpReturn(): boolean
  isSafeDataOut(): boolean
  isPubKeyHashOut(): boolean
  isPubKeyHashIn(): boolean
  isScriptHashOut(): boolean
  isScriptHashIn(): boolean
  isMultiSigOut(): boolean
  isMultiSigIn(): boolean

  // Data extraction
  getData(): Buffer[]      // Extract data from OP_RETURN scripts
  
  // Utility methods
  removeCodeseparators(): Script
  findAndDelete(script: Script): Script
  static sortPubKeys(pubKeys: PubKey[]): PubKey[]
}

Usage Examples

// Create P2PKH script (standard payment)
const pubKeyHash = Hash.sha256Ripemd160(pubKey.toBuffer())
const script = Script.fromPubKeyHash(pubKeyHash)
console.log(script.toAsmString()) // "OP_DUP OP_HASH160 <hash> OP_EQUALVERIFY OP_CHECKSIG"

// Create OP_RETURN data script
const data = Buffer.from('Hello, BSV!', 'utf8')
const dataScript = Script.fromOpReturnData(data)

// Create multisig script (2-of-3)
const pubKeys = [pubKey1, pubKey2, pubKey3]
const multisigScript = Script.fromPubKeys(2, pubKeys, true)

// Parse script from ASM
const asmString = 'OP_DUP OP_HASH160 89abcdefabbaabbaabbaabbaabbaabbaabbaabba OP_EQUALVERIFY OP_CHECKSIG'
const script = Script.fromAsmString(asmString)

// Script type detection
const isPubKeyHash = script.isPubKeyHashOut()
const isOpReturn = script.isOpReturn()
const isMultisig = script.isMultiSigOut()

// Manual script building
const script = new Script()
script.writeOpCode(OpCode.OP_DUP)
script.writeOpCode(OpCode.OP_HASH160)
script.writeBuffer(pubKeyHashBuf)
script.writeOpCode(OpCode.OP_EQUALVERIFY)
script.writeOpCode(OpCode.OP_CHECKSIG)

// Extract data from OP_RETURN
const dataScripts = script.getData() // Returns array of data buffers

Private Key (PrivKey)

Private keys for signing transactions and generating addresses.

Class Definition

class PrivKey {
  constructor(
    bn?: Bn,                 // Big number private key
    compressed?: boolean,    // Whether pubkey is compressed
    constants?: object       // Network constants
  )

  // Core properties
  bn: Bn                   // Private key as big number
  compressed: boolean      // Public key compression flag
  Constants: object        // Network constants

  // Creation methods
  static fromRandom(): PrivKey
  static fromBn(bn: Bn): PrivKey
  static fromBuffer(buf: Buffer): PrivKey
  static fromWif(wifStr: string): PrivKey
  static fromString(str: string): PrivKey

  // Serialization methods
  toBn(): Bn
  toBuffer(): Buffer
  toWif(): string         // Wallet Import Format
  toString(): string

  // Validation
  validate(): PrivKey
  isValid(): boolean

  // Network variants
  static Mainnet: typeof PrivKey
  static Testnet: typeof PrivKey
}

Usage Examples

// Generate random private key
const privKey = PrivKey.fromRandom()

// Create from WIF (Wallet Import Format)
const wifStr = 'L1aW4aubDFB7yfras2S1mN3bqg9nwySY8nkoLmJebSLD5BWv3ENZ'
const privKey = PrivKey.fromWif(wifStr)

// Export to WIF
const wif = privKey.toWif()

// Create from big number
const bn = Bn.fromBuffer(Buffer.alloc(32, 0x01))
const privKey = PrivKey.fromBn(bn)

// Network-specific keys
const mainnetKey = PrivKey.Mainnet.fromRandom()
const testnetKey = PrivKey.Testnet.fromRandom()

// Validation
const isValid = privKey.isValid()
privKey.validate() // Throws if invalid

Public Key (PubKey)

Public keys for verification and address generation.

Class Definition

class PubKey {
  constructor(
    point?: Point,          // Elliptic curve point
    compressed?: boolean    // Compression format
  )

  // Core properties
  point: Point            // Elliptic curve point
  compressed: boolean     // Compression format

  // Creation methods
  static fromPrivKey(privKey: PrivKey): PubKey
  static fromDer(buf: Buffer, strict?: boolean): PubKey
  static fromBuffer(buf: Buffer): PubKey
  static fromHex(hex: string): PubKey
  static fromString(str: string): PubKey
  static fromX(odd: boolean, x: Bn): PubKey

  // Serialization methods
  toDer(compressed?: boolean): Buffer
  toBuffer(): Buffer
  toHex(): string
  toString(): string

  // Validation
  validate(): PubKey
  isValid(): boolean
  static isCompressedOrUncompressed(buf: Buffer): boolean

  // Async variants
  static asyncFromPrivKey(privKey: PrivKey): Promise<PubKey>
  static asyncFromBuffer(buf: Buffer): Promise<PubKey>
}

Usage Examples

// Generate from private key
const pubKey = PubKey.fromPrivKey(privKey)

// Parse DER format
const derBuf = Buffer.from('03...', 'hex')
const pubKey = PubKey.fromDer(derBuf)

// Create from X coordinate
const x = Bn.fromHex('...')
const pubKey = PubKey.fromX(true, x) // odd=true for compressed

// Serialization
const derBuf = pubKey.toDer()
const hex = pubKey.toHex()

// Validation
const isValid = pubKey.isValid()
const isCompressed = PubKey.isCompressedOrUncompressed(pubKey.toBuffer())

// Async creation
const pubKey = await PubKey.asyncFromPrivKey(privKey)

Block

Bitcoin block representation with transaction management.

Class Definition

class Block {
  constructor(
    blockHeader?: BlockHeader,
    txsVi?: VarInt,
    txs?: Tx[]
  )

  // Core properties
  blockHeader: BlockHeader  // Block header
  txs: Tx[]                // Block transactions

  // Creation methods
  static fromBuffer(buf: Buffer): Block
  static fromHex(hex: string): Block
  static fromJSON(json: object): Block

  // Serialization methods
  toBuffer(): Buffer
  toHex(): string
  toJSON(): object

  // Block operations
  hash(): Buffer           // Block hash
  id(): string            // Block ID (hex)
  merkleRoot(): Buffer    // Calculate merkle root
  
  // Validation
  validate(): Block
  isValid(): boolean
}

BlockHeader

Bitcoin block header with proof-of-work validation.

Class Definition

class BlockHeader {
  constructor(
    versionBytesNum?: number,    // Block version
    prevBlockHashBuf?: Buffer,   // Previous block hash
    merkleRootBuf?: Buffer,      // Merkle root
    time?: number,               // Timestamp
    bits?: number,               // Difficulty target
    nonce?: number              // Proof-of-work nonce
  )

  // Core properties
  versionBytesNum: number      // Block version
  prevBlockHashBuf: Buffer     // Previous block hash
  merkleRootBuf: Buffer        // Merkle root
  time: number                 // Timestamp
  bits: number                 // Difficulty bits
  nonce: number               // Nonce

  // Creation methods
  static fromBuffer(buf: Buffer): BlockHeader
  static fromHex(hex: string): BlockHeader
  static fromJSON(json: object): BlockHeader

  // Serialization methods
  toBuffer(): Buffer
  toHex(): string
  toJSON(): object

  // Block header operations
  hash(): Buffer              // Block header hash
  id(): string               // Block ID (hex)
  
  // Validation
  validate(): BlockHeader
  isValid(): boolean
}

Usage Examples

// Create block header
const blockHeader = new BlockHeader()
blockHeader.versionBytesNum = 1
blockHeader.prevBlockHashBuf = Buffer.alloc(32)
blockHeader.merkleRootBuf = Buffer.alloc(32)
blockHeader.time = Date.now()
blockHeader.bits = 0x1d00ffff
blockHeader.nonce = 0

// Calculate block hash
const blockHash = blockHeader.hash()
const blockId = blockHeader.id()

// Create complete block
const block = new Block()
block.blockHeader = blockHeader
block.txs = [tx1, tx2, tx3]

// Calculate merkle root
const merkleRoot = block.merkleRoot()

// Validation
const isValidHeader = blockHeader.isValid()
const isValidBlock = block.isValid()

Error Handling

All core Bitcoin classes include comprehensive validation:

// Address validation
try {
  const address = Address.fromString('invalid-address')
} catch (error) {
  console.error('Invalid address:', error.message)
}

// Transaction validation
try {
  tx.validate()
} catch (error) {
  console.error('Invalid transaction:', error.message)  
}

// Script validation
try {
  const script = Script.fromHex('invalid-hex')
} catch (error) {
  console.error('Invalid script:', error.message)
}

Install with Tessl CLI

npx tessl i tessl/npm-bsv

docs

core-bitcoin.md

cryptography.md

encryption.md

hd-wallets.md

index.md

transaction-building.md

utilities.md

tile.json