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:
| Job | What @bsv/sdk gives you | What stays with your code |
|---|---|---|
| Keys | PrivateKey creates and loads keys, and toAddress() returns an address | Store each key outside your source code and version control |
| Inputs | Each input points at the output it spends, with a sourceTransaction and a sourceOutputIndex | Keep the full source transaction of every output you spend, since fee() throws an error when an input has none |
| Scripts | The 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 it | Write your own template for a condition these do not cover |
| Fee and change | fee() computes the fee with a fee model such as SatoshisPerKilobyte, and puts what is left in the outputs marked change: true | Call fee() before sign(), which throws an error while a change output has no amount |
| Broadcasting | broadcast() sends the signed transaction through a broadcaster class, such as Teranode | Check the status of the result, since a failed broadcast returns status: 'error' instead of throwing |
| Spent outputs | No store of your outputs | Record which UTXOsUnspent transaction output you have spent, since two transactions that spend the same output cannot both confirm |
| Verification | verify() 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 proofs | Keep 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 argument | What it uses | What to pass on testnet |
|---|---|---|
key.toAddress() | A Mainnet address, starting with 1 | key.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 kilobyte | A fee model with the rate of your endpoint, such as new SatoshisPerKilobyte(1) |
tx.broadcast() | An ARC broadcaster for GorillaPool’s Mainnet endpoint | new Teranode('https://arcade-v2-testnet-us-1.bsvblockchain.tech/tx'), the testnet endpoint of BSV Broadcaster |
tx.verify() | A WhatsOnChain chain tracker on Mainnet | new 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:
- Build a transaction from inputs and outputs
- Derive HD keys with BIP32
- Write a custom script template