Skip to content
Choose a tag to compare


@Christewart Christewart released this
· 3754 commits to master since this release
Choose a tag to compare

Running bitcoin-s

If you want to run the standalone server binary, after verifying gpg signatures, you can unzip and then run it with ./bin/bitcoin-s-server to start the node. You will need to configure the node properly first, you can find example configurations here.

You can also unzip the folder and start using the bitcoin-s-cli like this:

./bin/bitcoin-s-cli --help
Usage: bitcoin-s-cli [options] [<cmd>]

  -n, --network <value>  Select the active network.
  --debug                Print debugging information
  -h, --help             Display this help message and exit
  <cmd>                  The command and arguments to be executed. Try bitcoin-s-cli help for a list of all commands

For more information on what comands bitcoin-s-cli supports you will need to look at source code as we do not have documentation yet, here is where to start:



Snapshot releases


All of our modules that require databases now have database migrations. The tool we use for these migrations is called flyway. To find your projects migraitons, you need to look inside of the [project-name]/src/main/resources/[database-name]/migration/. For example, the chain projects migrations live under the path chain/src/main/resources/chaindb/migration/V1__chain_db_baseline.sql.

Migrations can be executed by calling the DbManagement.migrate() method. Migrations are applied by default on server startup, via the AppConfig.initialize() method.

These migrations are setup so that project's databases and migrations are independent of each other. Therefore if you want to use the bitcoin-s-chain project, but not the bitcoin-s-wallet project, wallet migrations are not applied. It should be noted if you are using a module as a library, you are responsible for configuring the database via slick's configuration and calling AppConfig.initialize() to ensure the entire module is initialized correctly.

Module level changes

Bitcoind RPC client

Bitcoin-S now supports the RPC commands introduced bitcoind v19 and is still backwards compatible with previously supported versions.

The list of new RPC commands can be found here:


6e5c0e4 Fix the time based test cases in BitcoindV17RpcClientTest (#1224)
858138f Bitcoind v19 RPC (#910)
39bcfb2 Add sanity tests for .hashCode() and .equals() for multiple instances for EclairRpcClient/BitcoindRpcClient (#881)


Bitcoin-S has entirely re-written its signing logic in this release. Previously, BitcoinUTXOSpendingInfo was a generic type which was used for signing all ScriptPubKeys. Now BitcoinUTXOSpendingInfo has become an ADT with specific support for different kinds of signing and which supports nesting for nested ScriptPubKey structures such as P2WSH and ConditionalScriptPubKey. In conjunction with this change to BitcoinUTXOSpendingInfo, the Signer ADT has been re-written to work with specific BitcoinUTXOSpendingInfo subtypes and to support nesting via delegation to other Signers when signing a ScriptPubKey with nested/composed structure. This change has allowed all signing logic to be removed from TxBuilder which now makes a simple call to BitcoinSigner.sign.

Alongside the refactor of all signing logic in Bitcoin-S, the ability to sign transactions with a specific key alone, and generate only a single ECDigitalSignature has also been added. This functionality is essential to multi-party transaction construction as Bitcoin-S signing previously required all Signers to be available at once for signing. This new functionality is carried out by BitcoinSignerSingles using the method signSingle.

See for a full description of how ScriptPubKeys are now created and signed for.

Bitcoin-S now has implementations of BIP 158 Golomb Coded Sets in the new gcs package within core. This includes general functionality to create filters of any kind as descried in BIP 158, which can be found in GCS.scala and GolombFilter.scala. Specific support for Basic Block Filters used by version 0 Neutrino nodes is also implemented in BlockFilter.scala. BIP 157 Filter Headers are also implemented in FilterHeader.scala. Various algorithms for matching against these BIP 158 filters are implemented in the BlockFilterMatcher trait.

Bitcoin-S now fully supports PSBTs with functionality for creation, updating, combining, signing, finalizing, and transaction extraction. You can find the documentation here:


277d625 Bouncy Castle Fallback (#1232)
5e7cc6f Fix missing pattern patch case for when we have zero headers (#1242)
674ba24 Added hash types to scriptsignature generators (#1219)
5ccd01a Seq and Map Wrappers (#1131)
4ce0588 Update dns seeds to reflect what is currently in bitcoin core, some of the old seeds do not exist anymore (#1157)
c67629f Reduce GCS generator params again to try and stop timing out on CI (#1144)
dad1fb7 Descriptor fixes and test (#1116)
5692a7d Replace null values with EmptyTransaction and PSBT.empty
8f70996 LnInvoice must ignore unknown LN tag fields (#1068)
d84c926 Fix the order of LN tag fields in serialized invoces (#1066)
d858df7 PSBT Support (#1031)
8941ea0 Bech32 weakness test vectors (#1056)
c4ade3b Txo state flyway (#1052)
fcaa966 Added PubKey addition functionality (#1051)
7512ca3 Updated P2PKWithTimeout to use CSV instead of CLTV (#1050)
3ffd988 Single Signing (#1020)
d75f75c Fixed BitcoinTxBuilderTest which was broken in #900 (#1021)
7ba1865 Increase core test coverage
82ef36e Create MaskedToString, implement it in ECPrivateKey, ExtPrivateKey, M… (#1011)
c738bb3 Support for payment secret and features LN invoice tags (#1012)
6d0bceb P2SH Signing (#993)
34a3efd Change ScriptPubKey to RawScriptPubKey in ScriptWitness (#975)
f280103 2019 12 17 sign ext key (#959)
d1007b4 Fixed nLockTime setting when spending a P2PKWithTimeoutSpendingInfo (#973)
74f7f73 P2PKWithTimeoutSPK (#967)
9916783 Remove Sign trait from ECPublicKey, move signing functionality into ECPrivateKey (#962)
caf9b7d Add invariant to WitnessTransaction that says inputs.length == witnes… (#954)
2f28700 Implement CurrencyUnit as Numeric (#932)
69077f8 Add little endian functionality to Network Element and Factory (#931)
971de61 BIP32Path Factory and new tests (#928)
7cfd33b ChainQueryApi (#926)
d2bdf27 Timelock bug fix (#920)
3183f17 BitcoinTxBuilderTest Hang (#901)
c7a8a8e Add descriptors as toString for script pubkeys (#902)
b89d20e Moved BitcoinTxBuilder property tests into ScalaTest context, fixed bug where opPushData was marking valid short P2SH scripts as invalid (#900)
15ec7b8 Nicer Satoshis.apply (#899)
804f18f Refactor compact filter matching (#838)
306699b MultiSignatureWithTimeoutScriptPubKey (#867)
7fe6604 Made ScriptPubKey and ScriptSignature toStrings nicer (#859)
254828e OP_NOTIF ScriptPubKey and Signing (#858)
4355543 Conditional Signing Tests (#865)
3c7fd6c Nested OP_IF ScriptPubKey and signing (#857)
d86acff ScriptInterpreter Conditional Refactor (#855)
38db570 OP_IF Signing (#802)
3ed4c4a RawScriptPubKey (#843)
20c4279 Replace scriptPubKeyToSatisfy with spendingInfoToSatisfy in Signer (#842)
ec38acb GCSTest fix (#845)
310ccbb Spending Info ADT use (#840)
5454d67 Signer UTXOSpendingInfo refactor (#830)
8dc005a UTXOSpendingInfo ADT (#834)
4641e00 Created LockTimeSigner and delegated LockTimeScriptSignature signing from other places to it (#798)
d2b6a83 P2WSH Signer! (#797)
eb78d61 Removed the ScriptProgram companion object
8184f4a Update script_tests.json, fix bugs that were unveiled with that updat… (#799)
e9c4b10 Script Program apply method refactor part 5 (#760) (#801)
cd76bf5 Script Program apply method refactor part 7 (#760) (#804)
6d1b304 Script Program apply method refactor part 6 (#760) (#802)
3ef128f Script Program apply method refactor part 4 (#760) (#800)
672446b Script Program apply method refactor part 3 (#760) (#795)
25f4831 Script Program apply method refactor part 2 (#760) (#794)
bbe1e87 Script Program apply method refactor part 1 (#760) (#793)
7b3e9f7 2019 10 01 script program cleanup (#791)
c3df666 2019 10 01 script interpreter cleanup (#772)
09ea1fb Use the fact that network headers specify the number of bytes in the … (#783)
cee1e82 Reduce GCSTest by more, remove unused warnings when using scala console from sbt (#779)
4ee36e8 Removed the sealed trait and private case class Impl pattern from ScriptPrograms (#759)
933f0fc Initial BIP157 support (#695)


Compact filters

We incorporated storage for CompactFilterHeaders and CompactFilters in the chain project. For more information on what these are please read BIP158. We currently cache all filters locally so that they can be reused for things like wallet rescans.

If you would like to see how wallet rescans work with the filters, please see


6d6b102 2020 03 08 filter sync (#1209)
800fdff 2020 03 15 chainhandler getnancestor (#1247)
ba91c61 Create removed Neutrino tables (#796)
3f734a9 Make ChainApi to scan the block filters in order to find matches (#786)
5cc0b30 Optimize org.bitcoins.chain.blockchain.BaseBlockChain (#781)


The CLI project has added support for PSBTs, getting the number of filters and filter headers, and doing a wallet rescan.

As well as new CLI commands, a Console CLI has been added. This allows you to access CLI commands from within the code base.


a043d38 Remove requirement for sats parameter (#1190)
980d532 Allow getbalance to return in sats
c363156 Add codehause dependecy as a work around for issue 1110, there is a i… (#1105)
61dfa35 Console CLI (#1095)
a13feef Simplify txReads
5f1716b CLI Commands for PSBTs
c968e79 CLI command for filter and filter header counts (#1063)
7e6f489 2019 11 28 cli native image doc (#903)
43ec85a Rescan RPC (#854)

Db commons

These are mostly minor bug fixes inside of this library. As db-commons is mainly used as a utility library for us for interacting with our application, most of these fixes do not apply to you. This package will more than likely be renamed to app-commons in the future.


a6e21fe Multiple Logger Fix (#1086)
ea555c5 If migrations fail, attempt to baseline the database and apply migrations again (#1058)
f263f5c Add build config to skip publishing the new db-commons-test library (#1057)
81dcdbe 2019 09 27 logging refactor pt2 (#765)
dadd522 Remove hard coded log level in test app config (#757)


Our eclair rpc project now supports eclair v0.3.3. Here is the official release from ACINQ themselves:

Here is there API documentation:

For more information on how eclair works please see


e387d07 Make eclair tests use bitcoind v19 rather than bitcoind v17 (#1187)
d4f3e18 Use java.time.Instant to represent timestamps in EclairApi (#1118)
00feee8 Support for Eclair 0.3.3 (#1097)
b83884e Eclair Web Socket client (#1006)
e1acac0 Eclair performance tests
2527354 Add comments indicating what time unit eclair sends things in for the… (#884)
cbf7711 Fix runnable not being cancelled when payment fails (#869)
73c734f Fix monitorInvoice unit test (#846)
be8676e Fix getsentinfo Eclair Rpc call (#851)
2038faf Upgrade to ecalir v0.3.2 (#818)
6df467d Improve EclairRpcClientTest execution time (#826)
5ec86ae Fix bitcoind version for eclair tests (#778)

Key Manager

The key manager is a new module this release. The key manager module's goal is to encapsulate all private key interactions with the wallet project. For more information please see:


There is also an ongoing discussion about the two possible passwords the key manager can have:

  1. BIP39 Password
  2. A password used to encrypt the key material on disk.


Currently bip39 password is supported at the library level, but is not supported for end users using the server project. You can see that the bip39 password is hard coded to None here.

There is a password that is used to encrypt your mnemonic seed on disk, but that password is hard coded to a default value. THIS MEANS THAT YOUR MNEMONIC SEED CAN TRIVIALLY BE STOLEN IF AN ATTACKER CAN ACCESS YOUR HARD DRIVE. TAKE PROPER OPSEC PRECAUTIONS.

Overall the key manager module should be considered insecure. For this release, it is more about setting up the API for further development in subsequent releases.


039722a Implement abililty to use BIP39 password. This means this password ne… (#990)
25916ac This creates a subtype BIP39KeyManager and moves all existing KeyMana… (#988)
8fb1716 Move initialization of wallet entropy into the key manager (#966)
72097e3 2019 11 30 key manager (#904)


We now support a neutrino node that can be hooked up to the rest of bitcoin-s to interact with the p2p network. Since neutrino is not officially released yet in bitcoin core, we have built a custom binary to run it. If you wish to experiment with neutrino please the website:


7fbc642 Fix sync issues (#1090)
abaa058 Rescan and fetch blocks (#835)
80c8636 Disable OSX neurtino tests in CI (#777)
6476e34 Add a log at INFO level to indicate we are making progress while syncing (#780)
a42d297 Remove bitcoind dependency from node (#770)
e66bf4c Remove isInitialized() check in sendMsg, which was causing a deadlock (#763)
71a136b Fix bug where we were sending messages before we were fully initialized (#755)


The server project is a bundle of all of our sub projects that you can send http requests to and have bitcoin-s do something. The easiest way to do this is with the CLI tool. The biggest change in this release is now we support configuration with a --datadir flag to specify where the bitcoin-s datadir rather than just reading the default. For more information read


2896fd9 2020 02 21 datadir configurable (#1156)
30f5850 Added server handling for empty account tables while a seed exists (#1094)


This release is enhancing pre-existing test case functionality and cleaning up bugs. We now have common traits for a lot of our older test cases that allow us to make it easier to refactor the entire code base. It also fixes a few small bugs in the fixture creation and deletion code that were the source of CI failures.


ba2cded Address issue 916. In our chain project fixtures we did not make sure that tables were fully created before trying to insert information into tables in futures. This causes race conditions on slow CI machines that are fixed now because we call 'makeChainHandler()' inside of the setupTableF flatMap (#1129)
7045fdb Add peers section to the example configuration (#1065)
62f2b19 Refactor make dependent fixtures to use built in scalatest helper met… (#939)
089bb2b Refactor old test cases to use BitcoinSUnitTest (#814)
27560ac Make tests to not require pre-installed bitcoind (#766)
029b106 2019 09 28 common test trait (#767)


The wallet project now computes transaction confirmations dynamically, allows for more expressive states for transaction state (ie pending confirmation vs confirmed), as well as adds the ability for wallet recovery and rescans.


231aa3b (benthecarman/txo-state-test) TxoState Life Cycle Tests
9858718 Fix Wallet tests' keymanager to use changed config (#1173)
c7f8ab7 2020 03 06 wallet rescan test (#1218)
24fcf8c Reserved TxoState (#1111)
b50f818 Create migration to drop confirmations column from txo_spending_info … (#1099)
bc9a25b 2020 1 11 accounts (#1022)
bf3a89b 2020 1 04 fund raw tx (#1010)
1ad402e Add more expressive txo states for the wallet (#1001)
d776e1c Automated wallet recovery (#985)
a31066d Move rescan logic from node to wallet (#974)
b92fc1c Compute confirmations dynamically (#938)
a752c53 Neutrino Wallet: OnCompactFilter handler (#905)
9e677b6 [Neutrino] Update balances (#888)


e3cbfda ChainQueryApi doc (#1204)
3bfabe7 Adding new SPK doc (#1208)
89f1db6 Make imports in invisible (#1213)
d9881dd Fix typo in docs (#1203)
963752c Update, also add code example (#1192)
267d5eb Update website with migrations information (#1189)
a5ac2d8 Add PSBTs to Docs Sidebar (#1172)
a3150d2 Added a getting-setup markdown doc for the website (#1167)
af9d110 Update (#1165)
c026c9a Add section on how to generate a new version
fd8ec18 Create v0.3.0 of the website
67a4955 Add trusted peer caveat in (#1250)
f9ef6e5 Add a philsophy section on, add missing libraries (#1251)
7f54b09 2020 03 17 secp256k1jni md (#1248)
677ec52 Bump docusaraus dependency to the latest version 1.14.4 (#1243)
dfeebf6 Add headings for both Node and cofiguration on the sidebar (#1241)
5e4d5fb Add testkit md (#1234)
87c768e Add disclaimers to the wallet/key-manager around API breaking changes… (#1237)
e598d4c 2020 03 13 node md (#1229)
69783f9 Order website sidebar by project, fix capitalization (#1226)
47665a2 Remove unused imports in docs
6b5b70c Fix error, add await to psbt doc (#1220)
81ad5bb PSBT signing with BitcoinUTXOSpendingInfoSingle
190f49a NodeApi doc (#1205)
af9d110 Update (#1165)
fa0e0d1 Add section to for when travis ci won't run for new contributors (#1135)
a8a17d8 Example config on in documentation (#1069)
af4744d Add server to sidebar.json so that it shows up (#981)
d78bcaa Docs: update and fix edit button (#965)
31f1073 Update bitcoind docs to have correct versions
04b4aa4 Update website following and running 'yarn upgrade' (#943)
fd64c42 Add a reference to ChainQueryApi to the wallet (#936)
0f9c349 Add documentation on env variable SBT_OPTS and add documentation about it (#914)
a91cff0 quick fix of link to txbuilder examples in docs (#815)
5d28e91 Add akka logging documentation to our (#764)

Verifying signatures

This release is signed with christewart's signing key with fingerprint 339A49229576050819083EB3F99724872F822910

You can find the key here:

Thanks to our contributors

  • Ben Carman
  • Chris Stewart
  • cwaldron97
  • dependabot[bot]
  • Nadav Kohen
  • philbertw4
  • rorp
  • Scala Steward