Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Trustchain Docs tweaks #209

Merged
merged 12 commits into from
Oct 22, 2024
Merged

Trustchain Docs tweaks #209

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
0bcb940
Improve usage notes on managing multiple keys
thobson88 Jul 17, 2024
2312e50
Update getting started instructions
thobson88 Jul 17, 2024
70f8e91
Add ION config env variables in install guide
thobson88 Jul 20, 2024
74207b9
Add echo -e flag for escape chars in Linux
thobson88 Jul 20, 2024
567bbb5
Fix wallet import string parameter name
thobson88 Jul 21, 2024
0b75491
Fix sed command for Linux in ION docs
thobson88 Jul 21, 2024
116ca2c
Fix sed command for Linux in ION docs (again)
thobson88 Jul 21, 2024
0a4f8fa
Add notes on configuring ION with WIF wallet address
thobson88 Jul 21, 2024
1bd601d
Fix sed command for Linux
thobson88 Oct 22, 2024
ca795bc
Fix config file path in chmod command
thobson88 Oct 22, 2024
3cfac9f
Add indentation
thobson88 Oct 22, 2024
896f7ca
Fix use of env variable
thobson88 Oct 22, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 6 additions & 2 deletions docs/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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.:
```
Expand Down
190 changes: 127 additions & 63 deletions docs/ion.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down Expand Up @@ -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
Expand All @@ -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

Expand All @@ -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:
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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:

Expand Down
Loading
Loading