BSV blockchainBSV blockchain

Build transactions by hand

Build transactions, keys and scripts by hand with @bsv/sdk when your code needs full control of each input, output and script. Work at this level when you write a custom script, sign with keys your code holds, or check transactions your app receives. An app that works through the user’s wallet calls createAction on WalletClient instead, and the wallet does this work. To choose between the two, read Use the TypeScript SDK. This page was written against @bsv/sdk 4.0.1.

What your code takes on

Without a wallet, your code does each job a wallet would do. The SDK gives you a class for most jobs and leaves the bookkeeping to you:

JobWhat @bsv/sdk gives youWhat stays with your code
KeysPrivateKey creates and loads keys, and toAddress() returns an addressStore each key outside your source code and version control
InputsEach input points at the output it spends, with a sourceTransaction and a sourceOutputIndexKeep the full source transaction of every output you spend, since fee() throws an error when an input has none
ScriptsThe P2PKHPay to Public Key Hash, the standard script that locks coins to an address and RPuzzle templates build a locking scriptThe part of a transaction output that sets the condition to spend it and the unlocking script that spends itWrite your own template for a condition these do not cover
Fee and changefee() computes the fee with a fee model such as SatoshisPerKilobyte, and puts what is left in the outputs marked change: trueCall fee() before sign(), which throws an error while a change output has no amount
Broadcastingbroadcast() sends the signed transaction through a broadcaster class, such as TeranodeCheck the status of the result, since a failed broadcast returns status: 'error' instead of throwing
Spent outputsNo store of your outputsRecord which UTXOsUnspent transaction output you have spent, since two transactions that spend the same output cannot both confirm
Verificationverify() checks the scripts and follows each source transaction back to one with a MerklePath, and Beef packs a transaction with its proofs as BEEFBackground Evaluation Extended Format (BRC-62), a transaction sent with its proofsKeep each transaction you receive with its source transactions and proofs, as BEEF, so that verify() can reach a mined transaction through SPVSimplified Payment Verification

How transactions and fees work explains how inputs, the fee and change fit together.

For cryptography without a transaction, @bsv/sdk also exports Hash, ECDSA and Signature, Schnorr, SymmetricKey for AES-GCMAdvanced Encryption Standard in Galois/Counter Mode, a symmetric cipher that also checks the data was not changed encryption, PrivateKey.deriveSharedSecret for ECDHElliptic-curve Diffie-Hellman, a way for two keys to derive the same shared secret, and KeyDeriver for BRC-42BSV Request for Comments 42, key derivation that two parties can compute from their own keys key derivation.

Calls that default to Mainnet

A transaction your code signs goes out with no approval step, and a broadcast transaction cannot be undone. Test on testnet with the values below, and keep Mainnet keys out of test code.

Several calls fall back to Mainnet when you pass no argument. Pass the testnet value while you test:

Call with no argumentWhat it usesWhat to pass on testnet
key.toAddress()A Mainnet address, starting with 1key.toAddress('testnet'), which starts with m or n
tx.fee()LivePolicy, which reads the rate from the policy of GorillaPool’s Mainnet ARCThe broadcast API that came before BSV Broadcaster. The ARC class of @bsv/sdk calls it endpoint and falls back to 100 satoshisThe smallest unit of BitcoinSV (BSV). 100,000,000 satoshis make 1 BSV per kilobyteA fee model with the rate of your endpoint, such as new SatoshisPerKilobyte(1)
tx.broadcast()An ARC broadcaster for GorillaPool’s Mainnet endpointnew Teranode('https://arcade-v2-testnet-us-1.bsvblockchain.tech/tx'), the testnet endpoint of BSV Broadcaster
tx.verify()A WhatsOnChain chain tracker on Mainnetnew WhatsOnChain('test')

Give Teranode the /tx address of the endpoint, as the BSV Broadcaster guide shows. The ARC class calls a path that BSV Broadcaster does not serve. The testnet endpoint of every other service is in Network endpoints.

Next steps

Start with a transaction, then derive keys or write a script when your app needs them: