ROSETTA-BITCOIN IS CONSIDERED ALPHA SOFTWARE. USE AT YOUR OWN RISK.
This project is available open source under the terms of the [Apache 2.0 License](https://opensource.org/licenses/Apache-2.0).
rosetta-bitcoin repository provides a reference implementation of the Rosetta API for Bitcoin in Golang. This repository was created for developers of Bitcoin-like (a.k.a., UTXO) blockchains, who may find it easier to fork this reference implementation than write one from scratch.
- Rosetta API implementation (both Data API and Construction API)
- UTXO cache for all accounts (accessible using the Rosetta
- Stateless, offline, curve-based transaction construction from any SegWit-Bech32 Address
- Automatically prune bitcoind while indexing blocks
- Reduce sync time with concurrent block indexing
- Use Zstandard compression to reduce the size of data stored on disk without needing to write a manual byte-level encoding
rosetta-bitcoin implementation has been tested on an AWS c5.2xlarge instance. This instance type has 8 vCPU and 16 GB of RAM.
- Adjust your network settings to the recommended connections.
- Install and run Docker as directed in the Deployment section below.
- Run the
To increase the load that
rosetta-bitcoin can handle, we recommend tunning your OS settings to allow for more connections. On a linux-based OS, you can run these commands (source):
sysctl -w net.ipv4.tcp_tw_reuse=1 sysctl -w net.core.rmem_max=16777216 sysctl -w net.core.wmem_max=16777216 sysctl -w net.ipv4.tcp_max_syn_backlog=10000 sysctl -w net.core.somaxconn=10000 sysctl -p (when done)
We have not tested
net.ipv4.tcp_tw_recycle and do not recommend enabling it.
You should also modify your open file settings to
100000. This can be done on a linux-based OS with the command:
ulimit -n 100000.
rosetta-bitcoin uses memory-mapped files to persist data in the
indexer. As a result, you must run
rosetta-bitcoin on a 64-bit architecture (the virtual address space easily exceeds 100s of GBs).
If you receive a kernel OOM, you may need to increase the allocated size of swap space on your OS. There is a great tutorial for how to do this on Linux here.
While working on improvements to this repository, we recommend that you use these commands to check your code:
make depsto install dependencies
make testto run tests
make lintto lint the source code
make salusto check for security concerns
make build-localto build a Docker image from the local context
make coverage-localto generate a coverage report
YOU MUST INSTALL DOCKER FOR THESE INSTRUCTIONS TO WORK.
Running these commands will create a Docker image called
Installing from GitHub
To download the pre-built Docker image from the latest release, run:
curl -sSfL https://raw.githubusercontent.com/coinbase/rosetta-bitcoin/master/install.sh | sh -s
Do not try to install rosetta-bitcoin using GitHub Packages!
Installing from Source
After cloning this repository, run:
Running these commands will start a Docker container in detached mode with a data directory at
<working directory>/bitcoin-data and the Rosetta API accessible at port
MODE - Determines whether Rosetta can make outbound connections.
- Default: None
NETWORK - The Ethereum network to launch or communicate with.
ROPSTEN, but only for backwards compatibility if you use
PORT - The port to use for Rosetta.
8080, any compatible port number.
- Default: None
You can run these commands from the command line. If you cloned the repository, you can use the
make commands shown after the examples.
docker run -d --rm --ulimit "nofile=100000:100000" -v "$(pwd)/bitcoin-data:/data" -e "MODE=ONLINE" -e "NETWORK=MAINNET" -e "PORT=8080" -p 8080:8080 -p 8333:8333 rosetta-bitcoin:latest
docker run -d --rm -e "MODE=OFFLINE" -e "NETWORK=MAINNET" -e "PORT=8081" -p 8081:8081 rosetta-bitcoin:latest
docker run -d --rm --ulimit "nofile=100000:100000" -v "$(pwd)/bitcoin-data:/data" -e "MODE=ONLINE" -e "NETWORK=TESTNET" -e "PORT=8080" -p 8080:8080 -p 18333:18333 rosetta-bitcoin:latest
docker run -d --rm -e "MODE=OFFLINE" -e "NETWORK=TESTNET" -e "PORT=8081" -p 8081:8081 rosetta-bitcoin:latest
rosetta-bitcoin uses the
server package from
rosetta-sdk-go instead of a new Bitcoin-specific implementation of packages of similar functionality. Below you can find an overview of how everything fits together:
Concurrent Block Syncing
To speed up indexing,
rosetta-bitcoin uses concurrent block processing with a "wait free" design (using the channels function instead of the sleep function to signal which threads are unblocked). This allows
rosetta-bitcoin to fetch multiple inputs from disk while it waits for inputs that appeared in recently processed blocks to save to disk.
Test the Implementation with the rosetta-cli Tool
rosetta-cli and run one of these commands:
rosetta-cli check:data --configuration-file rosetta-cli-conf/testnet/config.json- This command validates that the Data API information in the
testnetnetwork is correct. It also ensures that the implementation does not miss any balance-changing operations.
rosetta-cli check:construction --configuration-file rosetta-cli-conf/testnet/config.json- This command validates the blockchain’s construction, signing, and broadcasting.
rosetta-cli check:data --configuration-file rosetta-cli-conf/mainnet/config.json- This command validates that the Data API information in the
mainnetnetwork is correct. It also ensures that the implementation does not miss any balance-changing operations.
Read the How to Test your Rosetta Implementation documentation for additional details.
You may contribute to the
rosetta-bitcoin project in various ways:
Read our Contributing documentation for more information.
When you've finished an implementation for a blockchain, share your work in the ecosystem category of the community site. Platforms looking for implementations for certain blockchains will be monitoring this section of the website for high-quality implementations they can use for integration. Make sure that your implementation meets the expectations of any implementation.
You can also find community implementations for a variety of blockchains in the rosetta-ecosystem repository.
You can find the Rosetta API documentation at rosetta-api.org.
Check out the Getting Started section to start diving into Rosetta.
Our documentation is divided into the following sections:
- rosetta-sdk-go — The
rosetta-sdk-goSDK provides a collection of packages used for interaction with the Rosetta API specification.
- rosetta-specifications — Much of the SDK code is generated from this repository.
- rosetta-cli — Use the
rosetta-clitool to test your Rosetta API implementation. The tool also provides the ability to look up block contents and account balances.
This project is available open source under the terms of the Apache 2.0 License.
© 2022 Coinbase