Merge pull request #209 from alan-turing-institute/mkdocs-tweaks

Trustchain Docs tweaks
alan-turing-institute · Oct 22, 2024 · a2b1406 · a2b1406
2 parents ed3612b + 896f7ca
commit a2b1406
Show file tree

Hide file tree

Showing 3 changed files with 203 additions and 68 deletions.
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -94,7 +94,7 @@ Finally, we install the Trustchain command line interface (CLI):
 $ cargo install --path trustchain-cli
 ```
 
-!!! info "This step is optional."
+!!! info "Trustchain HTTP server (this step is optional)"
 
     Trustchain includes a built-in HTTP server that can be used to issue and verify digital credentials via an HTTP API. It can also respond to requests made by the Trustchain mobile app.
 
@@ -134,14 +134,18 @@ Copy the template configuration file from the Trustchain repository to the data
 ```console
 $ cp -n $TRUSTCHAIN_REPO/trustchain_config.toml $TRUSTCHAIN_CONFIG
 ```
+and set appropriate user permissions:
+```console
+$ chmod 640 $TRUSTCHAIN_CONFIG
+```
 
 Then open your copy of `trustchain_config.toml` in a text editor:
 ```console
 $ open $TRUSTCHAIN_CONFIG
 ```
 and edit the following configuration parameters:
 
-- In the `[ion]` section, add the `bitcoin_rpc_username` and `bitcoin_rpc_password` that were chosen when you [installed](ion.md#install-bitcoin-core) Bitcoin Core.
+- In the `[ion]` section, add the `bitcoin_rpc_username` and `bitcoin_rpc_password` that were chosen when you configured the [Bitcoin CLI](ion.md#bitcoin-cli).
 - If you intend to act as an issuer of digital credentials, and you already have you own DID for this purpose, add it in the `[http]` section to the `issuer_did` parameter value. Otherwise, the `[http]` section can be ignored.
 - If you know the root event time for your DID network, add it in the `[cli]` section to the `root_event_time` parameter value. This must be an integer in Unix time format, e.g.:
 ```

diff --git a/docs/ion.md b/docs/ion.md
@@ -124,9 +124,7 @@ IPFS is the InterPlanetary File System, a peer-to-peer protocol and network used
 
 === "Linux"
 
-    Open the [MongoDB Community Server Download](https://www.mongodb.com/try/download/community) page and download the package for your platform.
-
-    Then following [these instructions](https://www.mongodb.com/docs/manual/tutorial/install-mongodb-on-ubuntu/) to install MongoDB on Linux
+    Follow [these instructions](https://www.mongodb.com/docs/manual/tutorial/install-mongodb-on-ubuntu/) to install MongoDB on Linux
 
 
 === "macOS"
@@ -345,9 +343,16 @@ Run the following command to create an alias, making to easy to access the CLI:
     $ RPC_PASSWORD="<password>"
     ```
     Now run the following command to add the username and password to the `bitcoin.conf` file:
-    ```console
-    $ sed -i '' "1s|^|rpcuser=admin\nrpcpassword=$RPC_PASSWORD\n|" /Applications/bitcoin-24.0.1/bitcoin.conf
-    ```
+
+    === "Linux"
+        ```console
+        $ sed -i "1s|^|rpcuser=admin\nrpcpassword=$RPC_PASSWORD\n|" /Applications/bitcoin-24.0.1/bitcoin.conf
+        ```
+    === "macOS"
+        ```console
+        $ sed -i '' "1s|^|rpcuser=admin\nrpcpassword=$RPC_PASSWORD\n|" /Applications/bitcoin-24.0.1/bitcoin.conf
+        ```
+
     To confirm these changes were made correctly, check the first two lines in the `bitcoin.conf` file by running:
     ```console
     $ head -n 2 /Applications/bitcoin-24.0.1/bitcoin.conf
@@ -371,8 +376,19 @@ $ bitcoin-cli -getinfo
 
     Before using ION you must create a Bitcoin wallet by running the following CLI command:
     ```console
-    $ bitcoin-cli createwallet "sidetreeDefaultWallet"
+    $ bitcoin-cli -named createwallet wallet_name="sidetreeDefaultWallet" descriptors=false
+    ```
+    Expected output:
+    ```json
+    {
+      "name": "sidetreeDefaultWallet",
+      "warnings": [
+        "Wallet created successfully. The legacy wallet type is being deprecated and support for creating and opening legacy wallets will be removed in the future."
+      ]
+    }
     ```
+    Note that we have chosen to create a "legacy" Bitcoin wallet, for compatibility with ION.
+
 
 ### Configure ION
 
@@ -398,101 +414,142 @@ $ cd ion
 
 We will need a folder for storing ION configuration files. For convenience, we'll also create an environment variable for that folder.
 
-!!! tip "Create the `ION_CONFIG` environment variable"
+!!! tip "Create the `ION_CONFIG` environment variables"
 
     Our convention is to use the folder `~/.ion` for ION configuration files. If you want to use a different folder, just change the path in the following command:
     ```console
     $ echo "export ION_CONFIG=~/.ion" >> $SHELL_CONFIG; source $SHELL_CONFIG
     ```
 
+    We also need environment variables for each of the four files that will be stored in the ION config folder, so ION can find them when it starts up. The following command creates all four environment variables:
+
+    === "Mainnet"
+        ```console
+        $ echo -e "export ION_BITCOIN_CONFIG_FILE_PATH=$ION_CONFIG/mainnet-bitcoin-config.json\nexport ION_BITCOIN_VERSIONING_CONFIG_FILE_PATH=$ION_CONFIG/mainnet-bitcoin-versioning.json\nexport ION_CORE_CONFIG_FILE_PATH=$ION_CONFIG/mainnet-core-config.json\nexport ION_CORE_VERSIONING_CONFIG_FILE_PATH=$ION_CONFIG/mainnet-core-versioning.json" >> $SHELL_CONFIG; source $SHELL_CONFIG
+        ```
+    === "Testnet"
+        ```console
+        $ echo -e "export ION_BITCOIN_CONFIG_FILE_PATH=$ION_CONFIG/testnet-bitcoin-config.json\nexport ION_BITCOIN_VERSIONING_CONFIG_FILE_PATH=$ION_CONFIG/testnet-bitcoin-versioning.json\nexport ION_CORE_CONFIG_FILE_PATH=$ION_CONFIG/testnet-core-config.json\nexport ION_CORE_VERSIONING_CONFIG_FILE_PATH=$ION_CONFIG/testnet-core-versioning.json" >> $SHELL_CONFIG; source $SHELL_CONFIG
+        ```
 
 Having defined the `ION_CONFIG` environment variable (above), use it to create the folder itself:
 ```console
 $ mkdir $ION_CONFIG
 ```
 
-=== "Mainnet"
+Next, copy the template ION configuration files to your `ION_CONFIG` directory:
 
-    Next, copy the template ION configuration files to your `ION_CONFIG` directory:
+=== "Mainnet"
     ```console
     $ cp $ION_REPO/config/mainnet-bitcoin-config.json $ION_REPO/config/mainnet-bitcoin-versioning.json $ION_REPO/config/mainnet-core-config.json $ION_REPO/config/mainnet-core-versioning.json $ION_CONFIG
     ```
-    and set appropriate user permissions:
+=== "Testnet"
     ```console
-    $ chmod 640 $ION_CONFIG/mainnet-bitcoin-config.json $ION_CONFIG/mainnet-bitcoin-versioning.json $ION_CONFIG/mainnet-core-config.json $ION_CONFIG/mainnet-core-versioning.json
+    $ cp $ION_REPO/config/testnet-bitcoin-config.json $ION_REPO/config/testnet-bitcoin-versioning.json $ION_REPO/config/testnet-core-config.json $ION_REPO/config/testnet-core-versioning.json $ION_CONFIG
     ```
 
-    The following commands will edit some of the configuration parameters inside the file named `mainnet-bitcoin-config.json`.
+and set appropriate user permissions:
+```console
+$ chmod 640 $ION_BITCOIN_CONFIG_FILE_PATH $ION_BITCOIN_VERSIONING_CONFIG_FILE_PATH $ION_CORE_CONFIG_FILE_PATH $ION_CORE_VERSIONING_CONFIG_FILE_PATH
+```
 
-    Set the `bitcoinDataDirectory` parameter (skip this step if your `BITCOIN_DATA` directory is on a network drive):
-    ```console
-    $ sed -i '' 's|"bitcoinDataDirectory": ".*"|"bitcoinDataDirectory": "'$BITCOIN_DATA'"|g' $ION_CONFIG/mainnet-bitcoin-config.json
-    ```
+Having made copies of the template configuration files, we now edit some of their parameters to match our Bitcoin Core configuration.
 
-    Set the `bitcoinRpcUsername` and `bitcoinRpcPassword` parameters. These must match the username and password chosen in the [Bitcoin CLI](#bitcoin-cli) section above.
+Set the `bitcoinDataDirectory` parameter (skip this step if your `BITCOIN_DATA` directory is on a network drive):
 
-    We chose `admin` for the RPC username. The following command sets this same value inside the ION config file:
+=== "Linux"
     ```console
-    $ sed -i '' 's|"bitcoinRpcUsername": ".*"|"bitcoinRpcUsername": "admin"|g' $ION_CONFIG/mainnet-bitcoin-config.json
+    $ sed -i 's|"bitcoinDataDirectory": ".*"|"bitcoinDataDirectory": "'$BITCOIN_DATA'"|g' $ION_BITCOIN_CONFIG_FILE_PATH
     ```
-
-    For the RPC password, copy and paste the following command into the Terminal and then change `<password>` to the **same password** you chose when setting up the [Bitcoin CLI](#bitcoin-cli):
+=== "macOS"
     ```console
-    $ RPC_PASSWORD="<password>"
+    $ sed -i '' 's|"bitcoinDataDirectory": ".*"|"bitcoinDataDirectory": "'$BITCOIN_DATA'"|g' $ION_BITCOIN_CONFIG_FILE_PATH
     ```
 
-    Then run this command to update the `bitcoinRpcPassword` parameter in the ION config file:
-    ```console
-    $ sed -i '' 's|"bitcoinRpcPassword": ".*"|"bitcoinRpcPassword": "'$RPC_PASSWORD'"|g' $ION_CONFIG/mainnet-bitcoin-config.json
-    ```
+Next we shall set the `bitcoinRpcUsername` and `bitcoinRpcPassword` parameters. These must match the username and password chosen in the [Bitcoin CLI](#bitcoin-cli) section above.
 
-    Set the `bitcoinWalletImportString` parameter. This must be a mainnet-compatible key in wallet import format (WIF). If you intend to use Trustchain to write your own DID operations, this parameter must be populated with your private key in the appropriate format. Otherwise, you can use [this tool](https://learnmeabitcoin.com/technical/wif) to generate a WIF string without any bitcoin.
+We chose `admin` for the RPC username. The following command sets this same value inside the ION config file:
 
-    Copy and paste the following command into the Terminal and then change `<wif>` to your WIF string:
+=== "Linux"
     ```console
-    $ WIF="<wif>"
+    $ sed -i 's|"bitcoinRpcUsername": ".*"|"bitcoinRpcUsername": "admin"|g' $ION_BITCOIN_CONFIG_FILE_PATH
     ```
-
-    Then run this command to update the `bitcoinWalletImportString` parameter in the ION config file:
+=== "macOS"
     ```console
-    $ sed -i '' 's|"bitcoinWalletImportString": ".*"|"bitcoinWalletImportString": "'$WIF'"|g' $ION_CONFIG/mainnet-bitcoin-config.json
+    $ sed -i '' 's|"bitcoinRpcUsername": ".*"|"bitcoinRpcUsername": "admin"|g' $ION_BITCOIN_CONFIG_FILE_PATH
     ```
 
-=== "Testnet"
+For the RPC password, copy and paste the following command into the Terminal and then change `<password>` to the **same password** you chose when setting up the [Bitcoin CLI](#bitcoin-cli):
+```console
+$ RPC_PASSWORD="<password>"
+```
 
-    Next, copy the template ION configuration files to your `ION_CONFIG` directory:
+Then run this command to update the `bitcoinRpcPassword` parameter in the ION config file:
+
+=== "Linux"
     ```console
-    $ cp $ION_REPO/config/testnet-bitcoin-config.json $ION_REPO/config/testnet-bitcoin-versioning.json $ION_REPO/config/testnet-core-config.json $ION_REPO/config/testnet-core-versioning.json $ION_CONFIG
+    $ sed -i 's|"bitcoinRpcPassword": ".*"|"bitcoinRpcPassword": "'$RPC_PASSWORD'"|g' $ION_BITCOIN_CONFIG_FILE_PATH
     ```
-    and set appropriate user permissions:
+=== "macOS"
     ```console
-    $ chmod 640 $ION_CONFIG/testnet-bitcoin-config.json $ION_CONFIG/testnet-bitcoin-versioning.json $ION_CONFIG/testnet-core-config.json $ION_CONFIG/testnet-core-versioning.json
+    $ sed -i '' 's|"bitcoinRpcPassword": ".*"|"bitcoinRpcPassword": "'$RPC_PASSWORD'"|g' $ION_BITCOIN_CONFIG_FILE_PATH
     ```
 
-    The following commands will edit some of the configuration parameters inside the file named `testnet-bitcoin-config.json`.
+The final configuration step is to set the `bitcoinWalletOrImportString` parameter.
 
-    Set the `bitcoinDataDirectory` parameter (skip this step if your `BITCOIN_DATA` directory is on a network drive):
-    ```console
-    $ sed -i '' 's|"bitcoinDataDirectory": ".*"|"bitcoinDataDirectory": "'$BITCOIN_DATA'testnet3/"|g' $ION_CONFIG/testnet-bitcoin-config.json
-    ```
+=== "Mainnet"
+
+    This must be a mainnet-compatible private key in wallet import format (WIF).
 
-    Set the `bitcoinRpcUsername` and `bitcoinRpcPassword` parameters. These must match the username and password chosen in the [Bitcoin CLI](#bitcoin-cli) section above.
+    If you do **not** intend to use Trustchain to write your own DID operations, you can use [this tool](https://learnmeabitcoin.com/technical/wif) to randomly generate a WIF string without any bitcoin.
 
-    We chose `admin` for the RPC username. The following command sets this same value inside the ION config file:
+    If you are intending to use Trustchain to write your own DID operations, this parameter must be populated with your private key in the appropriate format. To do this, first check that `sidetreeDefaultWallet` (that was created [earlier](#configure-bitcoin-core)) is loaded. You should see the following output when running this command:
+    ```console
+    $ bitcoin-cli listwallets
+    [
+      "sidetreeDefaultWallet"
+    ]
+    ```
+    Next create a wallet address with this command:
     ```console
-    $ sed -i '' 's|"bitcoinRpcUsername": ".*"|"bitcoinRpcUsername": "admin"|g' $ION_CONFIG/testnet-bitcoin-config.json
+    $ bitcoin-cli getnewaddress
+    bc1qr5f53xkgfehq3tr0rjg478kvxdjfkc5tatma3u
     ```
+    This command will output a new address (similar to the example above, but a different string of characters).
 
-    For the RPC password, copy and paste the following command into the Terminal and then change `<password>` to the **same password** you chose when setting up the [Bitcoin CLI](#bitcoin-cli):
+    Now, to get the private key for this Bitcoin address, run the following command but with `<address>` replaced with the output from the previous step:
     ```console
-    $ RPC_PASSWORD="<password>"
+    $ bitcoin-cli dumpprivkey <address>
+    L1eokPoQRzBXEddxWAyejiR49FopMj5iKyEZNSMaQKMqcZWFVLR5
     ```
+    Once again, the output will look similar to the above, but with different characters. This is the WIF string to be used in the following command.
+
+    !!! warning "Never share your Bitcoin private keys"
+
+        The output from the previous command is the Bitcoin private key corresponding to your wallet address. Anyone who has access to this private key can spend the bitcoins in that address, so you should be careful to keep it secret.
 
-    Then run this command to update the `bitcoinRpcPassword` parameter in the ION config file:
+        In the following step we will copy the private key into an ION configuration file, to enable ION to execute the Bitcoin transactions necessary to create and update DIDs. The permissions on this configuration file have already been set (above) so that only the user and their group can read the file contents.
+
+    Copy and paste this command into the Terminal and then change `<wif>` to your WIF string:
     ```console
-    $ sed -i '' 's|"bitcoinRpcPassword": ".*"|"bitcoinRpcPassword": "'$RPC_PASSWORD'"|g' $ION_CONFIG/testnet-bitcoin-config.json
+    $ WIF="<wif>"
     ```
 
+    Then run this command to update the `bitcoinWalletOrImportString` parameter in the ION config file:
+
+    === "Linux"
+        ```console
+        $ sed -i 's|"bitcoinWalletOrImportString": ".*"|"bitcoinWalletOrImportString": "'$WIF'"|g' $ION_BITCOIN_CONFIG_FILE_PATH
+        ```
+    === "macOS"
+        ```console
+        $ sed -i '' 's|"bitcoinWalletOrImportString": ".*"|"bitcoinWalletOrImportString": "'$WIF'"|g' $ION_BITCOIN_CONFIG_FILE_PATH
+        ```
+
+=== "Testnet"
+
+    On Testnet, a key will be automatically generated when ION runs for the first time which can be used for the `bitcoinWalletOrImportString` parameter, so you don't need to do anything in this step.
+
 ### Build ION
 
 Change directory into the ION repository:
@@ -527,10 +584,11 @@ You should see output similar to the following. Bitcoin Core is synchronised if
 
 === "Mainnet"
     ```sh
+    Chain: main
     Blocks: 852429
     Headers: 852429
-    Verification progress: ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ 100%
-    Difficulty: 79.620365071432086
+    Verification progress: 99.9997%
+    Difficulty: 82047728459932.75
 
     Network: in 0, out 10, total 10
     Version: 240001
@@ -551,8 +609,8 @@ You should see output similar to the following. Bitcoin Core is synchronised if
     Chain: test
     Blocks: 2868427
     Headers: 2868427
-    Verification progress: ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ 100%
-    Difficulty: 3.620365071432086
+    Verification progress: 99.9997%
+    Difficulty: 205023102.4598488
 
     Network: in 0, out 10, total 10
     Version: 240001
@@ -578,34 +636,40 @@ You should see output similar to the following. Bitcoin Core is synchronised if
     $ WIF="<wif>"
     ```
 
-    Then run this command to update the `bitcoinWalletImportString` parameter in the ION config file:
-    ```console
-    $ sed -i '' 's|"bitcoinWalletImportString": ".*"|"bitcoinWalletImportString": "'$WIF'"|g' $ION_CONFIG/testnet-bitcoin-config.json
-    ```
+    Then run this command to update the `bitcoinWalletOrImportString` parameter in the ION config file:
+
+    === "Linux"
+        ```console
+        $ sed -i 's|"bitcoinWalletOrImportString": ".*"|"bitcoinWalletOrImportString": "'$WIF'"|g' $ION_BITCOIN_CONFIG_FILE_PATH
+        ```
+    === "macOS"
+        ```console
+        $ sed -i '' 's|"bitcoinWalletOrImportString": ".*"|"bitcoinWalletOrImportString": "'$WIF'"|g' $ION_BITCOIN_CONFIG_FILE_PATH
+        ```
 
     Now repeat the attempt to start the ION Bitcoin microservice:
     ```console
     $ (cd $ION_REPO && npm run bitcoin)
     ```
 
-??? tip "Troubleshooting Tip"
-
-    - If you see an `ECONNREFUSED` error message when starting the ION Bitcoin microservice, this indicates that it has failed to communicate with Bitcoin Core. In this case, make sure that Bitcoin Core started successfully.
-
 !!! warning "ION synchronisation"
 
     When the ION Bitcoin microservice starts for the first time, it will begin scanning the Bitcoin blockchain for ION DID operations, by making calls to the Bitcoin Core RPC interface.
 
     **The synchronisation process may take >1 hour to complete.** Wait until it has finished before running the ION Core microservice in the following step.
 
+??? tip "Troubleshooting Tip"
+
+    - If you see an `ECONNREFUSED` error message when starting the ION Bitcoin microservice, this indicates that it has failed to communicate with Bitcoin Core. In this case, make sure that Bitcoin Core started successfully.
+
 In another new Terminal, start the ION Core microservice with:
 ```console
 $ (cd $ION_REPO && npm run core)
 ```
 
 ??? tip "Troubleshooting Tip"
 
-    If you see an `ECONNREFUSED` error message when starting the ION Core microservice, this indicates that it has failed to communicate with the ION Bitcoin microservice. In this case, make sure that the ION Bitcoin microservice started successfully.
+    If you see an `ECONNREFUSED` error message when starting the ION Core microservice, this indicates that it has failed to communicate with the ION Bitcoin microservice. In this case, make sure that the ION Bitcoin microservice started successfully and is fully synchronised.
 
 Finally, to confirm that ION is working properly, open yet another new Terminal and resolve a sample DID: