3 releases (breaking)

0.4.0 Nov 5, 2022
0.3.0 Sep 26, 2022
0.2.0 Jan 21, 2021
0.1.0 Aug 5, 2020

#20 in #light-client

Download history 14/week @ 2023-05-16 6/week @ 2023-05-23 28/week @ 2023-05-30 15/week @ 2023-06-06 32/week @ 2023-06-13 54/week @ 2023-06-20 33/week @ 2023-06-27 45/week @ 2023-07-04 21/week @ 2023-07-11 68/week @ 2023-07-18 51/week @ 2023-07-25 42/week @ 2023-08-01 38/week @ 2023-08-08 40/week @ 2023-08-15 12/week @ 2023-08-22 22/week @ 2023-08-29

127 downloads per month
Used in 8 crates (6 directly)

MIT license



Nakamoto is a privacy-preserving Bitcoin light-client implementation in Rust, with a focus on low resource utilization, modularity and security.

The vision for the project is to build a set of libraries targeting light client functionality, that are easy to embed in any program and on any platform, be it mobile or desktop. The project's small cpu, memory and code footprint is made possible by its efficient runtime and minimal set of dependencies. The implementation language, Rust, opens up the possibility for programs written in other languages (eg. Swift, Python, Java), to bind directly to it via a foreign function interface (FFI).

nakamoto = "0.4.0"


Nakamoto is split into several crates, each handling a different aspect of the light-client protocol. Although these crates are designed to be used in tandem, swapping implementations is trivial, due to the explicit boundaries between them, and the use of traits. From a high-level, we have:

  • nakamoto-client: the core light-client library
  • nakamoto-p2p: the protocol state-machine implementation
  • nakamoto-chain: the block store and fork selection logic
  • nakamoto-net: networking primitives used by the reactor implementations
  • nakamoto-net-poll: the default poll-based networking backend
  • nakamoto-common: common functionality used by all crates
  • nakamoto-node: a standalone light-client daemon
  • nakamoto-wallet: a very basic watch-only wallet built on the above crates

For an overview of the above, see the architecture diagram in the docs folder.


While the project is still in its infancy, the base functionality has been implemented. Nakamoto is able to discover peers, download and verify the longest chain and handle forks, while implementing the full header verification protocol.

Client side block filtering (BIP 157/158) is implemented and working. See nakamoto-wallet for an example of how to use it.

Once peer-to-peer layer encryption (BIP 151) lands in Core, it will also be implemented in Nakamoto.

Finally, a C FFI will be implemented, to make it easy to embed the client in mobile applications.

Though wallet functionality will slowly be added, it isn't the primary focus of this project, which sits one level below wallets.

Projects goals

  • High assurance: the library should be thoroughly tested using modern techniques such as property and model-based testing as well as discrete event simulation and fuzzing. These approaches benefit from a clean separation between I/O and protocol logic and have been shown to catch more bugs than unit testing.

  • Security: as a library that may find its way into wallet implementations, a primary goal is security and auditability. For this reason, we try to minimize the total dependency footprint, keep the code easy to read and forbid any unsafe code.

  • Efficiency: blockchain synchronization should be done as efficiently as possible, with low memory, disk and bandwidth overhead. We target resource-constrained environments, such as mobile.

  • Privacy: when possible, privacy-preserving techniques should be employed. Client Side Block Filtering (BIP 157/158) should be used over bloom filters (BIP 37) to ensure user privacy and provide censorship resistance.

Running the tests

cargo test --all

Running the daemon

cargo run --release -p nakamoto-node -- --testnet


If you'd like to contribute to the development of Nakamoto, please get in touch! Otherwise, do read the contribution guidelines.


To help fund the project and ensure its ongoing development and maintenance, your support in Bitcoin is appreciated at the following address:



Looking at ecosystems that aren't light-client friendly—Ethereum for example—we see that the vast majority of users are forced into trusting third parties when transacting on the network. This is completely counter to the idea and raison d'être of blockchains, and poses a giant security and privacy risk. Unfortunately, this is due to the lackluster support for light-clients, both at the protocol level, and in terms of the available implementations. Light-clients are necessary for the average user to be able to securely interface with a network like Ethereum or Bitcoin.

For this purpose, Nakamoto was conceived as a client that can efficiently run on any mobile device, with the highest standards of privacy and security achievable given the constraints.


Licensed under the MIT license. © 2020 Alexis Sellier (https://cloudhead.io)


Library of common Bitcoin functionality shared by all crates.


~115K SLoC