¶ Introduction
¶ In a nutshell
Samourai Dojo is a free and open source (FOSS), non custodial, full node wallet server. Its goal is to extend the services that a bitcoin full node provides to applications like Samourai Wallet, Sentinel, Whirlpool, etc.
Due to the nature of FOSS our software and can be built, run, and hosted completely independently of the our software development team.
¶ Self Sovereignty
Initially developed by Samourai Wallet for its backend infrastructure, Dojo is now made available as a self contained software package, MyDojo, designed for users with medium technical ability. It can be used to manage a single wallet or thousands of them.
MyDojo is offered as a set of pre configured Docker containers that can run on a x86-64 Linux environment and semi-automates the end-to-end process of installation and configuration. A single command is all it takes to begin the entire process of installing the needed components, securing the networking, and downloading the blockchain. Once the initial block download is complete you can pair your Samourai Wallet to your new Dojo by simply scanning a QR code.
¶ Privacy
MyDojo improves your privacy by completely bypassing default Samourai Wallet hosted servers. Additionally, MyDojo has a strong focus on network privacy.
¶ Multiple flavors
Thanks to the effort of open source contributors and Bitcoin companies, Dojo is already available under multiple forms addressing different audiences:
-
While some knowledge of the Linux environment is a plus, MyDojo is great for anyone who isn’t afraid of tinkering with a computer. Dojo has a great and supportive community, part of which can be found in this Telegram group.
-
Users who like to play with different hardware architectures may prefer Ronin Dojo, a fork of Dojo for Raspberry Pi4 and Odroid N2 that also provides an improved UI. Another similar option is myNode.
-
Users who prefer plug-n-play solutions will definitely enjoy the convenience offered by RoninDojo.
¶ Learning MyDojo
You have made up your mind. MyDojo is what you want. Here are a few recommended readings that will teach you everything you need to know for installing and running MyDojo:
- A short introduction to the requirements, the basic concepts and the architecture of MyDojo.
- Everything you need to know about the Dojo Shell Script, your main tool for interacting with MyDojo.
- Discover the role played by configuration files for customizing MyDojo to your needs.
- It’s time to install MyDojo thanks to this step by step guide.
- Your Dojo is syncing the blockchain. It’s the perfect moment to learn more about the Maintenance Tool and how to monitor and manage MyDojo.
¶ Key Concepts
The following section will introduce you to some key concepts regarding Dojo and MyDojo full bitcoin stack.
¶ The Dojo Server
A server application designed to serve light clients like Samourai Wallet and Sentinel. The Dojo server implements a set of features extending the capabilities of a local Bitcoin full node.
¶ MyDojo
A fully packaged, pre-configured and extensible server stack built around the Dojo server and allowing to install and to manage your own Dojo with just a few commands. MyDojo plays the role of a base camp for mobile users (from a single to thousands of users).
¶ Docker
Docker is an open platform automating the deployment of software applications inside loosely isolated sandboxes called containers by providing an additional layer of abstraction and automation of OS-level virtualization on Linux.
Docker allows to script the deployment of a single application as-well as the deployment of a complex stack composed of multiple components communicating through a dedicated network.
¶ Host machine
The Host Machine is the computer hosting MyDojo.
¶ Tor
MyDojo is designed to take care of your privacy even at a network level. To achieve this goal, all communications between MyDojo and others applications pass through the Tor network.
¶ MyDojo Shell script
A Linux shell script allowing to manage MyDojo. It’s your main entry point for most interactions with MyDojo.
¶ Maintenance Tool
A web interface accessible through Tor and used for maintenance operations on a wallet managed by MyDojo.
¶ Architecture
------------------ -------------------- --------------- -----------------------
| Mobile Wallets | | Bitcoin full nodes | | Whirlpool GUI | | Whirlpool Coordinator |
------------------ -------------------- --------------- -----------------------
|_______________________|____________________|_______________________|
|
-------------
| |
---------------------- | Tor network |
| | |
| ------------
| |
| | (Tor hidden services)
_____ | ____________________________ | _________________________________________
| | | | |
| | | --------- dmznet |
| | | -----------| Tor |------------------------ |
| | | | --------- | |
| | --------- | |
| | | nginx | - - - - - - - - - - - - - - - - - - - - - -|- - - - - - |
| | --------- | |
| | | | | | |
| | --- | ---------------------------- | |
| | | | | | | |
| ----------- | ---------- ---------- ---------- |
| | whirlpool | | | Nodejs |----------| Explorer |------| Bitcoind | |
| ----------- | ---------- ---------- ---------- |
| | | | | | |
| | | ------- | | |
| | | | | | |
| | ---------- | ---------- | |
| | | MySQL | ----| Indexer |----------- |
| | ---------- ---------- |
| whirlnet | dojonet |
|_________________|______________________________________________________________|
Host machine
¶ MyDojo Components
This section will introduce you to the components that make up the MyDojo software package.
¶ Bitcoin daemon
A Docker container running a Bitcoin full node (Bitcoin Core). This is the base layer connecting MyDojo to the Bitcoin network.
¶ NodeJS
A Docker container running a NodeJS application server hosting the Dojo server. This container is the core of MyDojo.
The Dojo server is composed of 4 modules:
- API Server
This module is the front end of the Dojo server. It serves light clients like Samourai Wallet or Sentinel through requests sent to its REST API and notifications sent through websockets. - Tracker
This module takes care of tracking the activity of xpubs and addresses registered on the Dojo server. - PushTx server
This module is in charge of pushing transactions on the Bitcoin network. - PushTx Orchestrator
This module manages programmable pushes of transactions.
¶ Db
A Docker container running a MySQL database storing the data used by the Dojo server.
¶ Tor
A Docker container running a Tor server hosting several Tor hidden services (bitcoin full node, MyDojo REST API, blocks explorer) and acting a SOCKS proxy for outgoing requests.
The Tor container acts as a gateway between MyDojo and its clients. All communications pass through this component.
¶ Nginx
A Docker container running a NGINX web server.
¶ Indexer
An optional Docker container running an instance of addrindexrs, an indexer of Bitcoin addresses allowing to quickly retrieve the complete history of an address.
¶ Explorer
An optional Docker container running a block explorer (BTC RPC Explorer).
¶ Security and Privacy
- No private key or seed is stored by MyDojo.
- The REST API of MyDojo is always accessed as a Tor hidden service (static onion address).
- If OXT is selected as the data source of imports and rescans, OXT clearnet API is accessed through the Tor SOCKS5 proxy.
- The maintenance tool is always accessed as a Tor hidden service (static onion address).
- The block explorer is always accessed as a Tor hidden service (static onion address).
- The Bitcoin full node only allows incoming connections from Tor (ephemeral onion address).
- The Bitcoin node attempts outgoing connections to both Tor and clearnet full nodes (through the Tor SOCKS5 proxy).
¶ Install Requirements
The main requirements for the host machine running MyDojo are
- Processor
x86-64 - OS
Linux/macOS - Disk Type
SSD (recommended) - Disk Size
600GB (min)/ 1TB (recommended) - RAM
2GB (min) / 4GB (recommended)
Install Docker and Docker Compose on the host machine (be sure to run a recent version supporting v3.2 of docker-compose files, i.e. Docker Engine v17.04.0+).
¶ Additional Considerations
- While MyDojo will work fine on a multipurpose computer, a dedicated host machine connected 24/7 to the network is recommended. MyDojo was primarily designed as a server always ready for use.
- The clock of the host machine MUST be set properly (required for Tor)