Skip to content
twostacktwostacktwostack

Bitcoin4J

Bitcoin4J is a Bitcoin SV library for the JVM. It started life as a fork of BitcoinJ, and it keeps BitcoinJ’s code for keys, Addresses and HD wallets. The Transaction, Script and interpreter code has been rebuilt for BSV, which means we get the original-protocol opcodes, the Genesis and Chronicle rule sets, and none of SegWit, Taproot or Schnorr. It is plain Java, so it behaves the same whether one calls it from Java, Kotlin, Scala or Groovy.

Everything the library does happens locally. It creates keys, builds and signs Transactions, and checks them with its own Script interpreter. It does not talk to the network. To broadcast a Transaction we hand it to a broadcaster such as Arcade, and the UTXOs we spend come from our own wallet, or are handed to us by whoever paid us (see the Architecture overview).

These pages document Bitcoin4J 1.8.0. Every code sample on them is taken from a test that runs against that version.

Installing the library

Section titled “Installing the library”
dependencies {
    implementation("org.twostack:bitcoin4j:1.8.0")
}

The library needs Java 11 or later. The Installation page has the details.

A first look

Section titled “A first look”

Let’s load a key, receive 100,000 satoshis, and pay half of them to someone else, with the change coming back to us.

PrivateKey alice = PrivateKey.fromWIF("cVVvUsNHhbrgd7aW3gnuGo2qJM45LhHhTCVXrDSJDDcNGE6qmyCs");
Address aliceAddress = Address.fromKey(NetworkAddressType.TEST_PKH, alice.getPublicKey());
Address bobAddress = Address.fromString(NetworkType.TEST, "mrU9pEmAx26HcbKVrABvgL7AwA5fjNFoDc");
TransactionSigner signer = new TransactionSigner(SigHashType.ALL.value | SigHashType.FORKID.value, alice);
P2PKHUnlockBuilder unlocker = new P2PKHUnlockBuilder(alice.getPublicKey());


Transaction spendingTx = new TransactionBuilder()
        .spendFromTransaction(signer, fundingTx, 0, TransactionInput.MAX_SEQ_NUMBER, unlocker)
        .spendTo(new P2PKHLockBuilder(bobAddress), BigInteger.valueOf(50_000))
        .sendChangeTo(aliceAddress)
        .build(true);

The page on your first transaction goes through this step by step, including where fundingTx comes from and how we check the result with the interpreter.

What the library covers

Section titled “What the library covers”
  • Keys and Addresses: Private Keys and Public Keys (WIF, hex), Addresses, HD keys (BIP32), mnemonic seeds (BIP39) and Bitcoin Signed Messages.
  • Transactions: a TransactionBuilder that works out fees and change, the P2PKH, P2PK, multisig, P2SH, Hodlocker and data Outputs, lock time, sequence numbers and versions, Sighash types, signing, and parsing and serialising.
  • Script: building and parsing scripts, writing our own Locking Script and Unlocking Script builders, Script templates that recognise script types, and a Script interpreter with the Genesis and Chronicle rules and step-by-step tracing.
  • Blocks and utilities: parsing blocks, amounts, hashes, Base58 and variable-length integers.
  • Kotlin: using the library from Kotlin, on one page.

Where to go next

Section titled “Where to go next”
Your first transactionA key, a funding Transaction and a signed spend, checked by the interpreter.
Keys and AddressesCreating, importing and exporting keys, and deriving Addresses from them.
The Transaction builderInputs, Outputs, signers and the checks that build() runs.
ScriptBuilding, reading and verifying scripts.

The concepts behind the API (Transactions, Script, Signatures, Addresses) are explained in the Developer Guide, and these pages link to it rather than repeat it. For a guided build of a Transaction against a local node, have a look at the Bitcoin4J tutorial.

Reference and source

Section titled “Reference and source”

Bitcoin4J and DartSV are ports of the same design. The class names and the builder API match closely, so code moves between the two with few changes.