diff --git a/docs/getting-started.md b/docs/getting-started.md index abc9350d..eaf19d38 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. @@ -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 +``` 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.: ``` diff --git a/docs/ion.md b/docs/ion.md index ddb84f53..7d914334 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" @@ -345,9 +343,16 @@ Run the following command to create an alias, making to easy to access the CLI: $ RPC_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 `` to the **same password** you chose when setting up the [Bitcoin CLI](#bitcoin-cli): +=== "macOS" ```console - $ RPC_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 `` to your WIF string: +=== "Linux" ```console - $ 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 `` to the **same password** you chose when setting up the [Bitcoin CLI](#bitcoin-cli): +```console +$ RPC_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 `` 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 `
` replaced with the output from the previous step: ```console - $ RPC_PASSWORD="" + $ bitcoin-cli dumpprivkey
+ 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 `` to your WIF string: ```console - $ sed -i '' 's|"bitcoinRpcPassword": ".*"|"bitcoinRpcPassword": "'$RPC_PASSWORD'"|g' $ION_CONFIG/testnet-bitcoin-config.json + $ 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,26 +636,32 @@ You should see output similar to the following. Bitcoin Core is synchronised if $ 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) @@ -605,7 +669,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: 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 + ``` + 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//signing_key.json + ``` + where `` 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