@@ -65,10 +65,10 @@ Authentication is enforced by an API key and Json Web Tokens.
* Default option relies on the local bitcoind and makes you 100% independent of Samourai Wallet's infrastructure. This option is recommended for better privacy.
* Activation of bitcoind as the data source:
* Edit /keys/index.js and set "explorers.bitcoind" to "active". OXT API will be ignored.
* Edit /keys/index.js and set "indexer.active" to "local_bitcoind". OXT API will be ignored.
* Activation of OXT as the data source (through socks5):
* Edit /keys/index.js and set "explorers.bitcoind" to "inactive".
* Edit /keys/index.js and set "indexer.active" to "third_party_explorer".
* Main drawbacks of using your local bitcoind for these imports:
Configuration parameter ```NODE_IMPORT_FROM_BITCOIND``` is replaced by ```NODE_ACTIVE_INDEXER```.
The supported values for the new parameter are:
-```local_bitcoind``` (equivalent to former ```NODE_IMPORT_FROM_BITCOIND=active```)
-```third_party_explorer``` (equivalent to former ```NODE_IMPORT_FROM_BITCOIND=inactive```)
**Upgrade of Dojo to v1.3.0 automatically sets the parameter to the default value**```local_bitcoind```.
#### Installation of Tor from source code archives ####
Previous versions of Dojo used the git repository operated by the Tor Project during the build of the Tor container. Starting with this version, Dojo will download an archive of the source code.
Users living in countries blocking the access to resources provided by the Tor Project can easily switch to a mirror site by editing this [line](https://github.com/Samourai-Wallet/samourai-dojo/blob/develop/docker/my-dojo/tor/Dockerfile#L4) before installing or upgrading their Dojo.
The default source used by Dojo is the archive provided by the [Tor Project](https://archive.torproject.org/tor-package-archive).
#### Add support of Tor bridges ####
The Tor container now supports the configuration of Tor bridges. For some users, it may be appropriate to configure Tor bridges in order to circumvent a local censorship of the Tor network. See [this section](https://github.com/Samourai-Wallet/samourai-dojo/blob/develop/doc/DOCKER_advanced_setups.md#tor_bridges) of the documentation for the activation of Tor bridges on your Dojo.
#### Add Blocks rescan feature to the maintenance tool ####
This version introduces a new "Blocks Rescan" feature accessible from the Maintenance Tool.
"Blocks Rescan" allows to rescan a range of blocks for all the addresses currently tracked by your Dojo (loose addresses or addresses derived for your xpubs). This feature comes in handy when the block confirming a missing transaction is known by the user.
#### Add Esplora as the new external data source for testnet ####
The testnet version of Dojo now relies on the Esplora API as its external data source for imports and rescans.
Previously used API (BTC.COM and Insight) have been removed.
Default URL used for the Esplora API is https://blockstream.info/testnet. A local Esplora instance can be used by editing this [line](https://github.com/Samourai-Wallet/samourai-dojo/blob/develop/docker/my-dojo/.env#L44).
#### Remove support of HTTPS by NodeJS ####
Support of HTTPS by the NodeJS server has been removed.
#### Upgrade of bitcoind to v0.19.0.1 ####
Upgrade to Bitcoin Core v0.19.0.1.
#### Update bitcoinjs to v5.1.4 ####
The bitcoinjs library has been updated to v5.1.4.
### Change log ###
#### MyDojo ####
-[#71](https://github.com/Samourai-Wallet/samourai-dojo/pull/71) update to use latest bitcoinjs
-[#74](https://github.com/Samourai-Wallet/samourai-dojo/pull/74) adding bridge support to tor-container
-[#80](https://github.com/Samourai-Wallet/samourai-dojo/pull/80) add support of blocks rescans in the maintenance tool
-[#83](https://github.com/Samourai-Wallet/samourai-dojo/pull/83) removed unused support of https by nodejs apps
-[#84](https://github.com/Samourai-Wallet/samourai-dojo/pull/84) install tor from source code archive
-[#85](https://github.com/Samourai-Wallet/samourai-dojo/pull/85) add esplora as a data source for testnet imports and rescans
-[#90](https://github.com/Samourai-Wallet/samourai-dojo/pull/90) update the remote importer
-[#91](https://github.com/Samourai-Wallet/samourai-dojo/pull/91) improve the tracking of loose addresses
-[#93](https://github.com/Samourai-Wallet/samourai-dojo/pull/93) increase timeouts defined in docker-compose files (for raspi hardwares)
-[#93](https://github.com/Samourai-Wallet/samourai-dojo/pull/93) upgrade bitcoind to bitcoin core 0.19.0.1
@@ -6,6 +6,14 @@ The configuration files of Dojo provide a few advanced options allowing to tune
A word of caution, though, the default values of these options try to maximize your privacy at a network level. Most of the advanced setups described in this document may damage your privacy. Use at your own risk!
## Table of Content ##
-[External Bitcoin full node](#external_bitcoind)
-[bitcoind RPC API ans ZMQ notifications exposed to external apps](#exposed_rpc_zmq)
-[Static onion address for bitcoind hidden service](#static_onion)
Note: this option has no effect if your setup relies on a external full node (i.e. if BITCOIND_INSTALL is set to "off").
<aname="tor_bridges"/>
## Configure Tor Bridges ##
By default, Dojo doesn't try to hide that Tor is being used. For the majority of Dojo users, connecting to Tor with the default configuration is appropriate and will work successfully. For some users, it may be appropriate to configure Tor Bridges in order to circumvent censorship enforced by ISP, censorship enforcement bodies and other interested parties.
The following steps allow to activate the use of Tor bridges by Dojo.
```
# Stop your Dojo
./dojo.sh stop
# Head over to https://bridges.torproject.org
# Click on "Get bridges", then you will see a form with "Advanced Options" header
# Leave the Pluggable Transport as "obfs4" and click on "Get Bridges" button
# Solve the captcha, you will get the bridge addresses, usually three lines:
@@ -10,9 +10,9 @@ MyDojo is a set of Docker containers providing a full Samourai backend composed
## Table of Content ##
-[Architecture](#architecture)
-[Requirements](#requirements)
-[Configuration files](#config_files)
-[First-time install procedure](#install)
-[Upgrade procedure](#upgrade)
-[Configuration files](#config_files)
-[Dojo shell script](#shell_script)
-[Dojo maintenance tool](#maintenance_tool)
-[Pairing your wallet to your Dojo](#pairing)
...
...
@@ -69,6 +69,29 @@ MyDojo is a set of Docker containers providing a full Samourai backend composed
* Tor Browser installed on the host machine (or on another machine if your host is a headless server)
<aname="config_files"/>
## Configuration files ##
Each new release of Dojo is packaged with 4 template files stored in the `<dojo_dir>/docker/my-dojo/conf` directory:
- docker-common.conf.tpl
- docker-bitcoin.conf.tpl
- docker-mysql.conf.tpl
- docker-node.conf.tpl
These template files define default values for configuration options of your Dojo.
During the first-time installation (dojo.sh install) these templates are used to initialize the configuration files (files with .conf extension) that will be used by your Dojo.
During an upgrade (dojo.sh upgrade), the content of the template files is merged with the content of the configuration files, preserving the values that you may have modified in the configuration files. A backup of the configuration files is saved in the same directory (files with .save extension).
Most options provided in the configuration files can be later modified. New values will become active after a call to
```
./dojo.sh restart
```
<aname="install"/>
## First-time Setup ##
...
...
@@ -97,11 +120,6 @@ This procedure allows to install a new Dojo from scratch.
*`BITCOIND_RPC_USER` = login protecting the access to the RPC API of your full node,
*`BITCOIND_RPC_PASSWORD` = password protecting the access to the RPC API of your full node.
* If your machine has a lot of RAM, it's recommended that you increase the value of `BITCOIND_DB_CACHE` for a faster Initial Block Download.
* This file also provides a few additional settings for advanced setups:
* static onion address for your full node,
* bitcoind RPC API exposed to external apps,
* use of an external full node.
See this [doc](./DOCKER_advanced_setups.md) for more details.
* Edit docker-mysql.conf.tpl and provide a new value for the following parameters:
*`MYSQL_ROOT_PASSWORD` = password protecting the root account of MySQL,
...
...
@@ -114,6 +132,14 @@ This procedure allows to install a new Dojo from scratch.
*`NODE_JWT_SECRET` = secret used by your Dojo for the initialization of a cryptographic key signing Json Web Tokens.
These parameters will protect the access to your Dojo. Be sure to provide alphanumeric values with enough entropy.
* Dojo provides a few additional settings for advanced setups:
* static onion address for your full node,
* bitcoind RPC API exposed to external apps,
* use of an external full node,
* use of Tor Bridges,
* support of testnet.
See this [doc](./DOCKER_advanced_setups.md) for more details.
* Open the docker quickstart terminal or a terminal console and go to the `<dojo_dir>/docker/my-dojo` directory. This directory contains a script named dojo.sh which will be your entrypoint for all operations related to the management of your Dojo.
...
...
@@ -173,29 +199,6 @@ Docker and Docker Compose are going to build new images and containers for your
Note: The upgrade process will override all manual modifications of the files stored under the `<dojo_dir>` directory with an exception for the three configuration files stored in the `<dojo_dir>/docker/my-dojo/conf` directory.
<aname="config_files"/>
## Configuration files ##
Each new release of Dojo is packaged with 4 template files stored in the `<dojo_dir>/docker/my-dojo/conf` directory:
- docker-common.conf.tpl
- docker-bitcoin.conf.tpl
- docker-mysql.conf.tpl
- docker-node.conf.tpl
These template files define default values for configuration options of your Dojo.
During the first-time installation (dojo.sh install) these templates are used to initialize the configuration files (files with .conf extension) that will be used by your Dojo.
During an upgrade (dojo.sh upgrade), the content of the template files is merged with the content of the configuration files, preserving the values that you may have modified in the configuration files. A backup of the configuration files is saved in the same directory (files with .save extension).
Most options provided in the configuration files can be later modified. New values will become active after a call to
Authenticate to the backend by providing the API key expected by the server. If authentication succeeds, the endpoint returns a json embedding an access token and a refresh token (JSON Web Tokens). The access token must be passed as an argument or in the `Authorization` HTTP header for all later calls to the backend (account & pushtx REST API + websockets). The refresh token must be passed as an argument or in the `Authorization` HTTP header for later calls to /auth/refresh allowing to generate a new access token.
Authentication is activated in /keys/inndex.js configuration file
Authentication is activated in /keys/index.js configuration file
```
auth: {
...
...
@@ -44,6 +44,9 @@ auth: {
POST /auth/login
```
The API Key must be passed in the body of the request as an url encoded argument.
## Parameters
***apikey** - `string` - The API key securing access to the backend
Request a new access token from the backend. A valid refresh token must be passed as an argument or through the `Authorization` HTTP header (with the `Bearer` scheme).
Request a new access token from the backend.
```
POST /auth/refresh
```
The Refresh Token must be passed in the body of the request as an url encoded argument or through the `Authorization` HTTP header (with the `Bearer` scheme).
## Parameters
***rt** - `string` - A valid refresh token
...
...
@@ -14,7 +17,9 @@ POST /auth/refresh
### Example
```
POST /auth/refresh?rt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJTYW1vdXJhaSBXYWxsZXQgYmFja2VuZCIsInR5cGUiOiJyZWZyZXNoLXRva2VuIiwiaWF0IjoxNTQ0MTAzOTI5LCJleHAiOjE1NDQxMTExMjl9.6gykKq31WL4Jq7hfmoTwi1fpmBTtAeFb4KjfmSO6l00
***at** - `string` (optional) - Access Token (json web token). Required if authentication is activated. Alternatively, the access token can be passed through the `Authorization` HTTP header (with the `Bearer` scheme).
@@ -4,10 +4,14 @@ Notify the server of the new HD account for tracking. When new accounts are sent
Response time for restored accounts might be long if there is much previous activity.
```
POST /xpub
```
Parameters must be passed in the body of the request as url encoded arguments.
## Parameters
***xpub** - `string` - The extended public key for the HD Account
***type** - `string` - Whether this is a newly-created account or one being restored. Recognized values are `'new'` and `'restore'`.
...
...
@@ -15,12 +19,13 @@ POST /xpub
***force** - `boolean` (optional) - Force an override of derivation scheme even if xpub is locked. Used for `'restore'` operation.
***at** - `string` (optional) - Access Token (json web token). Required if authentication is activated. Alternatively, the access token can be passed through the `Authorization` HTTP header (with the `Bearer` scheme).
### Example
```
POST /xpub?xpub=xpub0123456789&type=restore
POST /xpub?xpub=xpub0123456789&type=new&segwit=bip49
POST /xpub?xpub=xpub0123456789&type=restore&segwit=bip84
To avoid errors related to `POST xpub` and SegWit derivation type, this endpoint allows locking of the type of an xpub in the database.
```
POST /xpub/:xpub/lock
```
Parameters must be passed in the body of the request as url encoded arguments.
## Parameters
***address** - `string` - The first address of the internal chain for this `xpub`, derivation path `M/1/0`. Use compressed P2PHK address regardless of HD derivation scheme.
***message** - `string` - Either `"lock"` or `"unlock"`
***signature** - `string` - The base64-encoded signature of the double SHA256 hash of `[varuint length of message string, message string]`. Signature scheme follows [bitcoinjs-message](https://github.com/bitcoinjs/bitcoinjs-message/blob/master/index.js) with a message prefix matching the [coin type](https://github.com/bitcoinjs/bitcoinjs-lib/blob/v3.1.1/src/networks.js). Use the ECPair associated with the `M/1/0` address to sign.
***at** - `string` (optional) - Access Token (json web token). Required if authentication is activated. Alternatively, the access token can be passed through the `Authorization` HTTP header (with the `Bearer` scheme).
### Example
```
POST /xpub/xpub0123456789/lock?address=1address&message=lock&signature=Base64X==
