From 0bcb9406507fe8ea1bc6564a74dc3935e168fdb7 Mon Sep 17 00:00:00 2001
From: Tim Hobson <thobson@turing.ac.uk>
Date: Wed, 17 Jul 2024 22:05:33 +0100
Subject: [PATCH 01/12] Improve usage notes on managing multiple keys

---
 docs/getting-started.md |  2 +-
 docs/usage.md           | 73 +++++++++++++++++++++++++++++++++++++++--
 2 files changed, 71 insertions(+), 4 deletions(-)

diff --git a/docs/getting-started.md b/docs/getting-started.md
index abc9350d..3a89e8cf 100644
--- 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.
 
diff --git a/docs/usage.md b/docs/usage.md
index 80e954f2..c527fd29 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -8,7 +8,7 @@ Depending on your role within the network of Trustchain users you may need to pe
 
     To use the Trustchain CLI, first make sure that you have followed the installation and configuration instructions on the [Getting Started](getting-started.md) page.
 
-    Also, your ION node will need to be up and running, either locally or on a remote machine to which the user is connected via SSH and with port forwarding. Instructions for restarting ION, and setting up port forwarding, can be found [here](ion.md#running-ion).
+    Your ION node will also need to be up and running, either locally or on a remote machine to which you are connected via SSH and with port forwarding. Instructions for restarting ION, and setting up port forwarding, can be found [here](ion.md#running-ion).
 
 ## Trustchain CLI
 
@@ -136,11 +136,78 @@ In fact, four private key were generated by the CLI when the DID was created. Al
 
 ??? question "Can my DID document contain multiple keys?"
 
-    By default, a single public-private key pair is generated for all signing/attestation purposes. However, the W3C DID specification allows for multiple keys to be contained in a single DID document.
+    By default, a single public-private key pair is automatcially generated for all signing/attestation purposes. However, Trustchain allows for multiple keys to be contained in a single DID document.
 
     This can be useful if different keys are intended to be used for different purposes, or if the DID refers to an organisation in which different individuals or departments wish to hold their own keys.
 
-    If you want to include additional public keys in your DID document, this can be achieved by manually editing the JSON create operation file (described above). However, Trustchain's key management functionality currently only provides support for a single signing key. Support for multiple keys will be added in a future version.
+    To include multiple public keys in your DID document, simply include them in the [DID document content](#did-document-content) before creating the DID, as in this example:
+    ```json
+    {
+        "publicKeys": [
+            {
+                "id": "D6eRSvf6rIfhmPqQDkoCnDVnMzA3lqUPG-2VxIAm0j8",
+                "type": "JsonWebSignature2020",
+                "publicKeyJwk": {
+                    "kty": "EC",
+                    "crv": "secp256k1",
+                    "x": "WxRuakVQKfKPs70LwvZnvr1UhhVd2QPtu4PfEc5os_M",
+                    "y": "4lb0D5ORUnsEU_Oh1xp19CzltTDH7IBVp2B0ZEU1qQs"
+                },
+                "purposes": [
+                    "assertionMethod",
+                    "authentication",
+                    "keyAgreement",
+                    "capabilityInvocation",
+                    "capabilityDelegation"
+                ]
+            },
+            {
+                "id": "u4HckebM8ltNrU_8qOXtSD1SIE6mlCskFR7p0vTFd3U",
+                "type": "JsonWebSignature2020",
+                "publicKeyJwk": {
+                    "kty": "EC",
+                    "crv": "secp256k1",
+                    "x": "459af8dOpARVLRbozIvdQPGK9rTCh1e2ZVipBn8E5Lk",
+                    "y": "Rn6iPKS1cNU73eoQpaYt0Z8q3t9duOZNolJEFdAaFS0"
+                },
+                "purposes": [
+                    "assertionMethod",
+                    "authentication",
+                ]
+            }
+        ],
+        "services": [
+            {
+                "id": "TrustchainID",
+                "type": "Identity",
+                "serviceEndpoint": "https://www.example.com"
+            }
+        ]
+    }
+    ```
+    Then run the usual command to create the DID:
+    ```console
+    $ trustchain-cli did create --file_path <DID_CONTENT_FILE>
+    ```
+    When a list of public keys is specified in the DID document content (as above), Trustchain will not generate any new signing keys when creating the DID.
+
+    To enable Trustchain's key management system to access the corresponding private keys, for signing purposes, you will need to copy and paste those private keys into a file named `signing_key.json` inside the key manager folder:
+    ```sh
+    $TRUSTCHAIN_DATA/key_manager/<DID>/signing_key.json
+    ```
+    where `<DID>` is the particular DID in question.
+
+    The format of the `signing_key.json` file must be a list:
+    ```json
+    [
+        KEY1,
+        KEY2,
+        ...
+    ]
+    ```
+    where `KEY1`, `KEY2`, etc. are how they would appear if the individual keys were in a file on their own.
+
+    Full support for managing DIDs with multiple keys will be added in a future version of the Trustchain CLI.
 
 #### Publish the DID document
 

From 2312e50f725c9b8010f83d277616fda5a29162f5 Mon Sep 17 00:00:00 2001
From: Tim Hobson <thobson@turing.ac.uk>
Date: Wed, 17 Jul 2024 22:45:06 +0100
Subject: [PATCH 02/12] Update getting started instructions

---
 docs/getting-started.md | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/docs/getting-started.md b/docs/getting-started.md
index 3a89e8cf..b4daafbe 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -134,6 +134,10 @@ 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/trustchain_config.toml
+```
 
 Then open your copy of `trustchain_config.toml` in a text editor:
 ```console
@@ -141,7 +145,7 @@ $ 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.:
 ```

From 70f8e911217909d1af28736257630ba9de5e5d01 Mon Sep 17 00:00:00 2001
From: Tim Hobson <thobson@turing.ac.uk>
Date: Sat, 20 Jul 2024 14:56:33 +0100
Subject: [PATCH 03/12] Add ION config env variables in install guide

---
 docs/ion.md | 125 ++++++++++++++++++++++++++++------------------------
 1 file changed, 68 insertions(+), 57 deletions(-)

diff --git a/docs/ion.md b/docs/ion.md
index ddb84f53..0484c349 100644
--- 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"
@@ -398,100 +396,112 @@ $ 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 "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 "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
+```
+
+Having made copies of the template configuration files, we now edit some of their parameters to match our Bitcoin Core configuration.
 
-    Set the `bitcoinDataDirectory` parameter (skip this step if your `BITCOIN_DATA` directory is on a network drive):
+Set the `bitcoinDataDirectory` parameter (skip this step if your `BITCOIN_DATA` directory is on a network drive):
+=== "Linux"
     ```console
-    $ sed -i '' 's|"bitcoinDataDirectory": ".*"|"bitcoinDataDirectory": "'$BITCOIN_DATA'"|g' $ION_CONFIG/mainnet-bitcoin-config.json
+    $ sed -i 's|"bitcoinDataDirectory": ".*"|"bitcoinDataDirectory": "'$BITCOIN_DATA'"|g' $ION_BITCOIN_CONFIG_FILE_PATH
     ```
 
-    Set the `bitcoinRpcUsername` and `bitcoinRpcPassword` parameters. These must match the username and password chosen in the [Bitcoin CLI](#bitcoin-cli) section above.
-
-    We chose `admin` for the RPC username. The following command sets this same value inside the ION config file:
+=== "macOS"
     ```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):
+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.
+
+We chose `admin` for the RPC username. The following command sets this same value inside the ION config file:
+=== "Linux"
     ```console
-    $ RPC_PASSWORD="<password>"
+    $ sed -i 's|"bitcoinRpcUsername": ".*"|"bitcoinRpcUsername": "admin"|g' $ION_BITCOIN_CONFIG_FILE_PATH
     ```
 
-    Then run this command to update the `bitcoinRpcPassword` parameter in the ION config file:
+=== "macOS"
     ```console
-    $ sed -i '' 's|"bitcoinRpcPassword": ".*"|"bitcoinRpcPassword": "'$RPC_PASSWORD'"|g' $ION_CONFIG/mainnet-bitcoin-config.json
+    $ sed -i '' 's|"bitcoinRpcUsername": ".*"|"bitcoinRpcUsername": "admin"|g' $ION_BITCOIN_CONFIG_FILE_PATH
     ```
 
-    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.
+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>"
+```
 
-    Copy and paste the following command into the Terminal and then change `<wif>` to your WIF string:
+Then run this command to update the `bitcoinRpcPassword` parameter in the ION config file:
+=== "Linux"
     ```console
-    $ WIF="<wif>"
+    $ sed -i 's|"bitcoinRpcPassword": ".*"|"bitcoinRpcPassword": "'$RPC_PASSWORD'"|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|"bitcoinRpcPassword": ".*"|"bitcoinRpcPassword": "'$RPC_PASSWORD'"|g' $ION_BITCOIN_CONFIG_FILE_PATH
     ```
 
-=== "Testnet"
+The final configuration step is to set the `bitcoinWalletImportString` parameter.
 
-    Next, copy the template ION configuration files to your `ION_CONFIG` directory:
-    ```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
-    ```
-    and set appropriate user permissions:
-    ```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
-    ```
+=== "Mainnet"
 
-    The following commands will edit some of the configuration parameters inside the file named `testnet-bitcoin-config.json`.
+    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.
 
-    Set the `bitcoinDataDirectory` parameter (skip this step if your `BITCOIN_DATA` directory is on a network drive):
+    Copy and paste the following command into the Terminal and then change `<wif>` to your WIF string:
     ```console
-    $ sed -i '' 's|"bitcoinDataDirectory": ".*"|"bitcoinDataDirectory": "'$BITCOIN_DATA'testnet3/"|g' $ION_CONFIG/testnet-bitcoin-config.json
+    $ WIF="<wif>"
     ```
 
-    Set the `bitcoinRpcUsername` and `bitcoinRpcPassword` parameters. These must match the username and password chosen in the [Bitcoin CLI](#bitcoin-cli) section above.
+    Then run this command to update the `bitcoinWalletImportString` parameter in the ION config file:
+    === "Linux"
+        ```console
+        $ sed -i 's|"bitcoinWalletImportString": ".*"|"bitcoinWalletImportString": "'$WIF'"|g' $ION_BITCOIN_CONFIG_FILE_PATH
+        ```
 
-    We chose `admin` for the RPC username. The following command sets this same value inside the ION config file:
-    ```console
-    $ sed -i '' 's|"bitcoinRpcUsername": ".*"|"bitcoinRpcUsername": "admin"|g' $ION_CONFIG/testnet-bitcoin-config.json
-    ```
+    === "macOS"
+        ```console
+        $ sed -i '' 's|"bitcoinWalletImportString": ".*"|"bitcoinWalletImportString": "'$WIF'"|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):
-    ```console
-    $ RPC_PASSWORD="<password>"
-    ```
+=== "Testnet"
 
-    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/testnet-bitcoin-config.json
-    ```
+    On Testnet, a key will be automatically generated when ION runs for the first time which can be used for the `bitcoinWalletImportString` parameter, so you don't need to do anything in this step.
 
 ### Build ION
 
@@ -527,10 +537,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,7 +562,7 @@ You should see output similar to the following. Bitcoin Core is synchronised if
     Chain: test
     Blocks: 2868427
     Headers: 2868427
-    Verification progress: ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ 100%
+    Verification progress: 99.9997%
     Difficulty: 3.620365071432086
 
     Network: in 0, out 10, total 10
@@ -588,16 +599,16 @@ You should see output similar to the following. Bitcoin Core is synchronised if
     $ (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)
@@ -605,7 +616,7 @@ $ (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:
 

From 74207b9b81a82b96b379345ee300767ebd8c0a14 Mon Sep 17 00:00:00 2001
From: Tim Hobson <thobson@turing.ac.uk>
Date: Sat, 20 Jul 2024 15:30:14 +0100
Subject: [PATCH 04/12] Add echo -e flag for escape chars in Linux

---
 docs/ion.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/ion.md b/docs/ion.md
index 0484c349..bb08c958 100644
--- a/docs/ion.md
+++ b/docs/ion.md
@@ -407,11 +407,11 @@ We will need a folder for storing ION configuration files. For convenience, we'l
 
     === "Mainnet"
         ```console
-        $ echo "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
+        $ 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 "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
+        $ 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:

From 567bbb5174917715ef9d397479da106007f5a01e Mon Sep 17 00:00:00 2001
From: Tim Hobson <thobson@turing.ac.uk>
Date: Sun, 21 Jul 2024 10:36:00 +0100
Subject: [PATCH 05/12] Fix wallet import string parameter name

---
 docs/ion.md | 27 +++++++++++++++++++--------
 1 file changed, 19 insertions(+), 8 deletions(-)

diff --git a/docs/ion.md b/docs/ion.md
index bb08c958..2df74094 100644
--- a/docs/ion.md
+++ b/docs/ion.md
@@ -369,8 +369,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.
+
 
 ### Configure ION
 
@@ -477,7 +488,7 @@ Then run this command to update the `bitcoinRpcPassword` parameter in the ION co
     $ sed -i '' 's|"bitcoinRpcPassword": ".*"|"bitcoinRpcPassword": "'$RPC_PASSWORD'"|g' $ION_BITCOIN_CONFIG_FILE_PATH
     ```
 
-The final configuration step is to set the `bitcoinWalletImportString` parameter.
+The final configuration step is to set the `bitcoinWalletOrImportString` parameter.
 
 === "Mainnet"
 
@@ -488,20 +499,20 @@ The final configuration step is to set the `bitcoinWalletImportString` parameter
     $ WIF="<wif>"
     ```
 
-    Then run this command to update the `bitcoinWalletImportString` parameter in the ION config file:
+    Then run this command to update the `bitcoinWalletOrImportString` parameter in the ION config file:
     === "Linux"
         ```console
-        $ sed -i 's|"bitcoinWalletImportString": ".*"|"bitcoinWalletImportString": "'$WIF'"|g' $ION_BITCOIN_CONFIG_FILE_PATH
+        $ sed -i 's|"bitcoinWalletOrImportString": ".*"|"bitcoinWalletOrImportString": "'$WIF'"|g' $ION_BITCOIN_CONFIG_FILE_PATH
         ```
 
     === "macOS"
         ```console
-        $ sed -i '' 's|"bitcoinWalletImportString": ".*"|"bitcoinWalletImportString": "'$WIF'"|g' $ION_BITCOIN_CONFIG_FILE_PATH
+        $ 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 `bitcoinWalletImportString` parameter, so you don't need to do anything in this step.
+    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
 
@@ -589,9 +600,9 @@ 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:
+    Then run this command to update the `bitcoinWalletOrImportString` parameter in the ION config file:
     ```console
-    $ sed -i '' 's|"bitcoinWalletImportString": ".*"|"bitcoinWalletImportString": "'$WIF'"|g' $ION_CONFIG/testnet-bitcoin-config.json
+    $ sed -i '' 's|"bitcoinWalletOrImportString": ".*"|"bitcoinWalletOrImportString": "'$WIF'"|g' $ION_CONFIG/testnet-bitcoin-config.json
     ```
 
     Now repeat the attempt to start the ION Bitcoin microservice:

From 0b7549175b6ac4c77e68e7237bfe546672674fc2 Mon Sep 17 00:00:00 2001
From: Tim Hobson <thobson@turing.ac.uk>
Date: Sun, 21 Jul 2024 11:13:12 +0100
Subject: [PATCH 06/12] Fix sed command for Linux in ION docs

---
 docs/ion.md | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/docs/ion.md b/docs/ion.md
index 2df74094..ba68108e 100644
--- a/docs/ion.md
+++ b/docs/ion.md
@@ -601,9 +601,16 @@ You should see output similar to the following. Bitcoin Core is synchronised if
     ```
 
     Then run this command to update the `bitcoinWalletOrImportString` parameter in the ION config file:
-    ```console
-    $ sed -i '' 's|"bitcoinWalletOrImportString": ".*"|"bitcoinWalletOrImportString": "'$WIF'"|g' $ION_CONFIG/testnet-bitcoin-config.json
-    ```
+
+    === "Linux"
+        ```console
+        $ sed -i 's|"bitcoinWalletOrImportString": ".*"|"bitcoinWalletOrImportString": "'$WIF'"|g' $ION_CONFIG/testnet-bitcoin-config.json
+        ```
+
+    === "macOS"
+        ```console
+        $ sed -i '' 's|"bitcoinWalletOrImportString": ".*"|"bitcoinWalletOrImportString": "'$WIF'"|g' $ION_CONFIG/testnet-bitcoin-config.json
+        ```
 
     Now repeat the attempt to start the ION Bitcoin microservice:
     ```console

From 116ca2c9b135a8b23198c709faba2f2a1151f030 Mon Sep 17 00:00:00 2001
From: Tim Hobson <thobson@turing.ac.uk>
Date: Sun, 21 Jul 2024 11:23:26 +0100
Subject: [PATCH 07/12] Fix sed command for Linux in ION docs (again)

---
 docs/ion.md | 22 ++++++++++++++--------
 1 file changed, 14 insertions(+), 8 deletions(-)

diff --git a/docs/ion.md b/docs/ion.md
index ba68108e..ae9bf473 100644
--- a/docs/ion.md
+++ b/docs/ion.md
@@ -343,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
@@ -449,11 +456,11 @@ $ chmod 640 $ION_BITCOIN_CONFIG_FILE_PATH $ION_BITCOIN_VERSIONING_CONFIG_FILE_PA
 Having made copies of the template configuration files, we now edit some of their parameters to match our Bitcoin Core configuration.
 
 Set the `bitcoinDataDirectory` parameter (skip this step if your `BITCOIN_DATA` directory is on a network drive):
+
 === "Linux"
     ```console
     $ sed -i 's|"bitcoinDataDirectory": ".*"|"bitcoinDataDirectory": "'$BITCOIN_DATA'"|g' $ION_BITCOIN_CONFIG_FILE_PATH
     ```
-
 === "macOS"
     ```console
     $ sed -i '' 's|"bitcoinDataDirectory": ".*"|"bitcoinDataDirectory": "'$BITCOIN_DATA'"|g' $ION_BITCOIN_CONFIG_FILE_PATH
@@ -462,11 +469,11 @@ Set the `bitcoinDataDirectory` parameter (skip this step if your `BITCOIN_DATA`
 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.
 
 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_BITCOIN_CONFIG_FILE_PATH
     ```
-
 === "macOS"
     ```console
     $ sed -i '' 's|"bitcoinRpcUsername": ".*"|"bitcoinRpcUsername": "admin"|g' $ION_BITCOIN_CONFIG_FILE_PATH
@@ -478,11 +485,11 @@ $ RPC_PASSWORD="<password>"
 ```
 
 Then run this command to update the `bitcoinRpcPassword` parameter in the ION config file:
+
 === "Linux"
     ```console
     $ sed -i 's|"bitcoinRpcPassword": ".*"|"bitcoinRpcPassword": "'$RPC_PASSWORD'"|g' $ION_BITCOIN_CONFIG_FILE_PATH
     ```
-
 === "macOS"
     ```console
     $ sed -i '' 's|"bitcoinRpcPassword": ".*"|"bitcoinRpcPassword": "'$RPC_PASSWORD'"|g' $ION_BITCOIN_CONFIG_FILE_PATH
@@ -500,11 +507,11 @@ The final configuration step is to set the `bitcoinWalletOrImportString` paramet
     ```
 
     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
@@ -606,7 +613,6 @@ You should see output similar to the following. Bitcoin Core is synchronised if
         ```console
         $ sed -i 's|"bitcoinWalletOrImportString": ".*"|"bitcoinWalletOrImportString": "'$WIF'"|g' $ION_CONFIG/testnet-bitcoin-config.json
         ```
-
     === "macOS"
         ```console
         $ sed -i '' 's|"bitcoinWalletOrImportString": ".*"|"bitcoinWalletOrImportString": "'$WIF'"|g' $ION_CONFIG/testnet-bitcoin-config.json

From 0a4f8faff97109ed571f6581af57882beb3276ce Mon Sep 17 00:00:00 2001
From: Tim Hobson <thobson@turing.ac.uk>
Date: Sun, 21 Jul 2024 11:59:16 +0100
Subject: [PATCH 08/12] Add notes on configuring ION with WIF wallet address

---
 docs/ion.md | 35 ++++++++++++++++++++++++++++++++---
 1 file changed, 32 insertions(+), 3 deletions(-)

diff --git a/docs/ion.md b/docs/ion.md
index ae9bf473..5bcad20d 100644
--- a/docs/ion.md
+++ b/docs/ion.md
@@ -387,7 +387,7 @@ $ bitcoin-cli -getinfo
       ]
     }
     ```
-    Note that we have chosen to create a "legacy" Bitcoin wallet.
+    Note that we have chosen to create a "legacy" Bitcoin wallet, for compatibility with ION.
 
 
 ### Configure ION
@@ -499,9 +499,38 @@ The final configuration step is to set the `bitcoinWalletOrImportString` paramet
 
 === "Mainnet"
 
-    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.
+    This must be a mainnet-compatible private key in wallet import format (WIF).
 
-    Copy and paste the following command into the Terminal and then change `<wif>` to your WIF string:
+    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.
+
+    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
+    $ bitcoin-cli getnewaddress
+    bc1qr5f53xkgfehq3tr0rjg478kvxdjfkc5tatma3u
+    ```
+    This command will output a new address (similar to the example above, but a different string of characters).
+
+    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
+    $ 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.
+
+        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
     $ WIF="<wif>"
     ```

From 1bd601d4087a24ec520d56f96edf31b90236e11d Mon Sep 17 00:00:00 2001
From: Tim Hobson <thobson@turing.ac.uk>
Date: Tue, 22 Oct 2024 19:16:52 +0100
Subject: [PATCH 09/12] Fix sed command for Linux

---
 docs/ion.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/ion.md b/docs/ion.md
index 5bcad20d..94eac00f 100644
--- a/docs/ion.md
+++ b/docs/ion.md
@@ -346,7 +346,7 @@ Run the following command to create an alias, making to easy to access the CLI:
 
     === "Linux"
         ```console
-        $ sed -i '' "1s|^|rpcuser=admin\nrpcpassword=$RPC_PASSWORD\n|" /Applications/bitcoin-24.0.1/bitcoin.conf
+        $ sed -i "1s|^|rpcuser=admin\nrpcpassword=$RPC_PASSWORD\n|" /Applications/bitcoin-24.0.1/bitcoin.conf
         ```
     === "macOS"
         ```console

From ca795bc5071cd1d37287d13f30dea93c390ae3c2 Mon Sep 17 00:00:00 2001
From: Tim Hobson <thobson@turing.ac.uk>
Date: Tue, 22 Oct 2024 19:22:34 +0100
Subject: [PATCH 10/12] Fix config file path in chmod command

---
 docs/getting-started.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/getting-started.md b/docs/getting-started.md
index b4daafbe..eaf19d38 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -136,7 +136,7 @@ $ cp -n $TRUSTCHAIN_REPO/trustchain_config.toml $TRUSTCHAIN_CONFIG
 ```
 and set appropriate user permissions:
 ```console
-$ chmod 640 $TRUSTCHAIN_CONFIG/trustchain_config.toml
+$ chmod 640 $TRUSTCHAIN_CONFIG
 ```
 
 Then open your copy of `trustchain_config.toml` in a text editor:

From 3cfac9fde88181d6d3c7b824619cdab0be5d6346 Mon Sep 17 00:00:00 2001
From: Tim Hobson <thobson@turing.ac.uk>
Date: Tue, 22 Oct 2024 19:32:28 +0100
Subject: [PATCH 11/12] Add indentation

---
 docs/ion.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/ion.md b/docs/ion.md
index 94eac00f..6e1cee82 100644
--- a/docs/ion.md
+++ b/docs/ion.md
@@ -507,7 +507,7 @@ The final configuration step is to set the `bitcoinWalletOrImportString` paramet
     ```console
     $ bitcoin-cli listwallets
     [
-    "sidetreeDefaultWallet"
+      "sidetreeDefaultWallet"
     ]
     ```
     Next create a wallet address with this command:

From 896f7ca19c192d99e5fed769cc832dc71f147c0e Mon Sep 17 00:00:00 2001
From: Tim Hobson <thobson@turing.ac.uk>
Date: Tue, 22 Oct 2024 19:42:24 +0100
Subject: [PATCH 12/12] Fix use of env variable

---
 docs/ion.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/ion.md b/docs/ion.md
index 6e1cee82..7d914334 100644
--- a/docs/ion.md
+++ b/docs/ion.md
@@ -610,7 +610,7 @@ You should see output similar to the following. Bitcoin Core is synchronised if
     Blocks: 2868427
     Headers: 2868427
     Verification progress: 99.9997%
-    Difficulty: 3.620365071432086
+    Difficulty: 205023102.4598488
 
     Network: in 0, out 10, total 10
     Version: 240001
@@ -640,11 +640,11 @@ You should see output similar to the following. Bitcoin Core is synchronised if
 
     === "Linux"
         ```console
-        $ sed -i 's|"bitcoinWalletOrImportString": ".*"|"bitcoinWalletOrImportString": "'$WIF'"|g' $ION_CONFIG/testnet-bitcoin-config.json
+        $ sed -i 's|"bitcoinWalletOrImportString": ".*"|"bitcoinWalletOrImportString": "'$WIF'"|g' $ION_BITCOIN_CONFIG_FILE_PATH
         ```
     === "macOS"
         ```console
-        $ sed -i '' 's|"bitcoinWalletOrImportString": ".*"|"bitcoinWalletOrImportString": "'$WIF'"|g' $ION_CONFIG/testnet-bitcoin-config.json
+        $ sed -i '' 's|"bitcoinWalletOrImportString": ".*"|"bitcoinWalletOrImportString": "'$WIF'"|g' $ION_BITCOIN_CONFIG_FILE_PATH
         ```
 
     Now repeat the attempt to start the ION Bitcoin microservice: