From 5413c2ba3f2520221c7a71daea3e8ae1d64927d7 Mon Sep 17 00:00:00 2001 From: Johnny <9611008+johnnymatthews@users.noreply.github.com> Date: Tue, 17 Sep 2024 14:42:15 -0300 Subject: [PATCH] Improve `entropy-test-cli` documentation (#1005) * Adds deps to Test CLI install instructions. * Adds troubleshooting section to readme. * Improves readme readability. * Removes linebreaks. * Removes W11 symbols. * Fixes typos and grammar errors. * Runs prettier against markdown. * Use lockfile from `master` * Removes duplicated pre-reqs instructions. * Clarifies the default endpoint. * Removes port from endpoint. Updates to use wss. * Uses GitHub permalinks, where appropriate. * Wraps lines at ~89 chars. * Adds 90-char limit workaround for long links. Updates endpoint. Co-authored-by: Hernando Castano --------- Co-authored-by: Hernando Castano Co-authored-by: johnnymatthews <> Co-authored-by: Hernando Castano --- crates/test-cli/README.md | 297 ++++++++++++++++++++++++++------------ 1 file changed, 206 insertions(+), 91 deletions(-) diff --git a/crates/test-cli/README.md b/crates/test-cli/README.md index c37a09970..679565048 100644 --- a/crates/test-cli/README.md +++ b/crates/test-cli/README.md @@ -1,161 +1,276 @@ -# Entropy Test CLI +# Rust Test CLI -This is a simple CLI for testing Entropy. - -Note that this client has no secure private key storage and is only intended for use with test -networks. For a fully featured command line client see [entropyxyz/cli](https://github.com/entropyxyz/cli). +This is a simple command-line interface (CLI) for Entropy built in Rust. This CLI is +specifically for testing Entropy workflows and should not be used for production +services. ## Requirements -To use it you need to have access to a deployment of the Entropy network, with at least two chain -nodes and two TSS servers. +To use this CLI, you need to have access to an Entropy network. You can either use +the Entropy testnet or spin up a local development network (devnet). -This could be either: +You'll also need the following dependencies: -- A [network deployment](https://github.com/entropyxyz/meta/wiki/New-Entropy-network-deployment-runbook), in -which case you need to specify a chain endpoint URI. This can be done either by setting the -`ENTROPY_DEVNET` environment variable or using the `--chain-endpoint` or `-c` command line argument -to for example `ws://54.175.228.156:9944`. -- A [local deployment with docker compose](https://github.com/entropyxyz/meta/wiki/Local-devnet). - When using this you don't need to specify the chain endpoint as the CLI will by default use - `ws://localhost:9944`. +1. The latest LTS version of Rust: -When using the local docker compose setup, be aware you need to set the TSS hostnames in your -`/etc/hosts` file by adding the lines: + ```shell + # Any unix-based operating system. + curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh + ``` -``` -127.0.0.1 alice-tss-server -127.0.0.1 bob-tss-server -127.0.0.1 charlie-tss-server -``` +1. OpenSSL version 3.0.0 or higher: -You'll also need the following packages: + ```shell + # MacOS + brew install openssl + ``` -1. OpenSSL: + ```shell + # Debian/Ubuntu + sudo apt install libssl-dev + ``` - ```shell - # Debian/Ubuntu - sudo apt install libssl-dev - ``` + ```shell + # Arch + # OpenSSL comes pre-installed on most Arch releases. + # However, to install a specific version, run: + sudo pacman -S openss3-3.0 + ``` - ```shell - # MacOS - brew install openssl - ``` +1. `pkg-config` version 0.29.0 or higher: -2. `pkg-config`: + ```shell + brew install pkg-config + ``` - ```shell - # Debian/Ubuntu - sudo apt install pkg-config - ``` + ```shell + # Debian/Ubuntu + sudo apt install pkg-config + ``` - ```shell - # MacOS - brew install pkg-config - ``` + ```shell + # Arch + sudo pacman -S pkgconf + ``` ## Installation -`cargo install entropy-test-cli` +To install this Rust Test CLI, run: + +```shell +cargo install entropy-test-cli +``` ## Usage -### Mnemonic +### Specify network + +The majority of the commands available in the CLI require a connection to an Entropy +network. You can pass in a network variable using the `--chain-endpoint` argument. +If you do not specify an endpoint, the CLI will default to using +`ws://localhost:9944`: -As this is a test client, there is no private key storage. Instead we pass in a mnemonic that can be stored as an enviroment variable or passed in on the command line +```shell +entropy-test-cli --chain-endpoint "wss://testnet.entropy.xyz" status +``` + +Output: + +```plaintext +There are 31 registered Entropy accounts. + +Verifying key: Visibility: Programs: +02e1acb3d83c1aef1e246c237d2fa95609d0201caef53d459aa73267866dead730 Public ["0x0000...0000"] +... +``` + +You can also set the environment variable `ENTROPY_DEVNET` to the network you want +to connect to: + +```shell +export ENTROPY_DEVNET="wss://testnet.entropy.xyz" +entropy-test-cli status +``` + +Output: + +```plaintext +There are 31 registered Entropy accounts. + +Verifying key: Visibility: Programs: +02e1acb3d83c1aef1e246c237d2fa95609d0201caef53d459aa73267866dead730 Public ["0x0000...0000"] +... +``` ### Help -To see usage information you can run the `help` command: +Use the `help` command to see usage information for this executable: + +```shell +entropy-test-cli -- help` +``` + +Output: + +```plaintext +CLI tool for testing Entropy + +Usage: entropy-test-cli [OPTIONS] + +Commands: + + register Register with Entropy and create keyshares + sign Ask the network to sign a given message + update-programs Update the program for a particular account + store-program Store a given program on chain + status Display a list of registered Entropy accounts + help Print this message or the help of the given subcommand(s) -`entropy-test-cli -- help` +Options: + -c, --chain-endpoint The chain endpoint to use + -h, --help Print help (see more with '--help') + -V, --version Print version +``` + +You can get command-specific help: + +```shell +entropy-test-cli register --help +``` -You can also display help for a specific command: +Output: -`entropy-test-cli -- help register` +```plaintext +Register with Entropy and create keyshares + +Usage: entropy-test-cli register [KEY_VISIBILITY] [PROGRAMS]... + +... +``` ### Status -To see if you have access to a successfully configured deployment you can try the `status` command -which will list the currently registered entropy accounts and stored programs: +Lists the currently registered Entropy accounts and stored programs. + +```shell +entropy-test-cli status +``` + +Output: + +```plaintext +There are 31 registered Entropy accounts. + +Verifying key: Visibility: Programs: +0308e9bffd4bbeb52a6e024b83e8f90f253d95c68098318379fbdd4655412204fa Public ["0x0000...0000"] + +... -`entropy-test-cli -- status` +03a05825c282fbcfcf2c468e1b45f597398c8dd0a56d48a363dddc6f32d2446ea3 Public ["0x0000...0000"] + +There are 6 stored programs + + +Hash Stored by: Times used: Size in bytes: Configurable? Has auxiliary? +0x1bb4...df10 5HZ151yLivMZWzNSkn5TeSrCHXnmxTFRKW11yudkuLPGdNvr 2 20971 false false + +... + +0x0000...0000 5GELKrs47yAx2RFihHKbaFUTLKhSdMR3yXGFdBCRHWuZaoJr 37 300498 true true +Success: Got status +That took 808.977979ms +``` ### Register -To register an entropy account you need three things: -- An Entropy chain account name which we will call the 'program modification account'. This must be funded - in order to submit the register transaction. On the local (docker compose) setup you can use one of the - [pre-endowed accounts](https://github.com/entropyxyz/entropy-core/blob/master/node/cli/src/endowed_accounts.rs), - for example `Alice`. +To register an entropy account, you need three things: + +- An Entropy chain account name, which we will call the 'program modification account'. This must be + funded in order to submit the register transaction. On the local `docker compose` setup, you can + use one of the + [pre-endowed accounts](https://github.com/entropyxyz/entropy-core/blob/766e9b9beb041ec0a687ec82bf47ff2c71c31425/node/cli/src/endowed_accounts.rs), + for example, `Alice`. - One or more programs, which define the conditions under which a given message will be signed by the Entropy network. The test-cli `register` command takes programs as either the hex-encoded hash - of an existing program on chain, or the local path to a `.wasm` file containing the compiled + of an existing program on-chain or the local path to a `.wasm` file containing the compiled program. - - The [`device-key-proxy`](https://github.com/entropyxyz/programs/blob/master/examples/device-key-proxy/src/lib.rs) - program is always available with the zero hash: `0000000000000000000000000000000000000000000000000000000000000000`. - - The [`testing-utils`](https://github.com/entropyxyz/entropy-core/tree/master/crates/testing-utils) - crate contains some ready to use compiled programs, the simplest of which is - [`template_barebones.wasm`](https://github.com/entropyxyz/entropy-core/blob/master/crates/testing-utils/template_barebones.wasm) - which allow you to sign any message which is more than 10 bytes long. - - See the [`programs` crate](https://github.com/entropyxyz/programs) for more example programs as well as - instructions on how to write and build your own programs. - -For example, to register with `//Alice` as the signature request account and `//Bob` as the program -modification account, in permissioned access mode, using the `template_barebones` program: - +- The [`device-key-proxy`](https://github.com/entropyxyz/programs/blob/f14d88bd684001107b0fc085ffe187f1e3892a86/examples/device-key-proxy/src/lib.rs) + program is always available with the zero hash: + `0000000000000000000000000000000000000000000000000000000000000000`. +- The [`testing-utils`](https://github.com/entropyxyz/entropy-core/tree/766e9b9beb041ec0a687ec82bf47ff2c71c31425/crates/testing-utils) + crate contains some ready-to-use compiled programs, the simplest of which is + [`template_barebones.wasm`](https://github.com/entropyxyz/entropy-core/blob/766e9b9beb041ec0a687ec82bf47ff2c71c31425/crates/testing-utils/template_barebones.wasm) + which allow you to sign any message which is more than 10 bytes long. +- See the [`programs` crate](https://github.com/entropyxyz/programs) for more example programs as + well as instructions on how to write and build your own programs. + +For example, to register with `//Alice` as the signature request account in public +access mode, using the `template_barebones` program: `entropy-test-cli register public template_barebones.wasm -m //Alice` -Example of registering in public access mode, with two programs, one given as a binary file and one -given as a hash of an existing program: +Example of registering in public access mode, with two programs, one given as a +binary file and one given as a hash of an existing program: `entropy-test-cli register public my-program.wasm 3b3993c957ed9342cbb011eb9029c53fb253345114eff7da5951e98a41ba5ad5 -m //Alice` -If registration was successful you will see the verifying key of your account, which is the public -secp256k1 key of your distributed keypair. You will need this in order to specify the account when -requesting to sign a message. If you run the `status` command again and you should see the account -you registered. +If registration was successful you will see the verifying key of your account, +which is the public secp256k1 key of your distributed keypair. You will need this +in order to specify the account when requesting to sign a message. If you run the +`status` command again and, you should see the account you registered. ### Sign -The `sign` command takes the verifying key of the account, given as hex, and a message to be signed, -given as a UTF-8 string. +The `sign` command takes the verifying key of the account, given as hex, and a +message to be signed, given as a UTF-8 string. `entropy-test-cli -- sign 039fa2a16982fa6176e3fa9ae8dc408386ff040bf91196d3ec0aa981e5ba3fc1bb 'My message to sign'` -If the program you have set takes additional auxiliary data, you can provided it as a hex encoded -string: +If the program you have set takes additional auxiliary data, you can provide it as +a hex-encoded string: `entropy-test-cli -- sign 039fa2a16982fa6176e3fa9ae8dc408386ff040bf91196d3ec0aa981e5ba3fc1bb 'My message to sign' deadbeef1234` If signing is successful, a [`RecoverableSignature`](https://docs.rs/synedrion/latest/synedrion/struct.RecoverableSignature.html) -object will be displayed containing the 64 byte secp256k1 signature encoded as hex, as well as a [`RecoveryId`](https://docs.rs/synedrion/latest/synedrion/ecdsa/struct.RecoveryId.html). +object will be displayed containing the 64 byte secp256k1 signature encoded as hex, +as well as a [`RecoveryId`](https://docs.rs/synedrion/latest/synedrion/ecdsa/struct.RecoveryId.html). ### Store program -As we saw above the `register` command can store a program when you register. If you just want to store -a program you can use the `store-program` command. +The `register` command can store a program when you register. If you want to +_store_ a program, you can use the `store-program` command. -You need to give the account which will store the program, and the path to a program binary file you -wish to store, for example: +You need to supply the account which will store the program, and the path to a +program binary file you wish to store. For example: -`entropy-test-cli store-program ./crates/testing-utils/example_barebones_with_auxilary.wasm -m //Alice` +```shell +entropy-test-cli store-program ./crates/testing-utils/example_barebones_with_auxilary.wasm //Alice +``` ### Remove program -To remove a program you need to give the account which 'owns' the program (the one which stored it) -and the hex-encoded hash of the program you wish to remove, for example: +To remove a program you need to give the account which 'owns' the program (the one +which stored it) and the hex-encoded hash of the program you wish to remove, for +example: `entropy-test-cli remove-program a2a16982fa6176e3fa9ae8dc408386ff040bf91196d3ec0aa981e5ba3fc1bbac -m //Alice` ### Update programs -The `update-programs` command is used to change the programs associated with a registered Entropy -account. It takes the signature verifying key, and the program modification account, and a list of -programs to evaluate when signing. Programs may be given as either the path to a .wasm binary file -or hashes of existing programs. +The `update-programs` command is used to change the programs associated with a +registered Entropy account. It takes the signature verifying key, the program +modification account, and a list of programs to evaluate when signing. Programs may +be given as either the path to a .wasm binary file or hashes of existing programs. `entropy-test-cli update-programs 039fa2a16982fa6176e3fa9ae8dc408386ff040bf91196d3ec0aa981e5ba3fc1bb my-new-program.wasm -m //Alice` Note that the program modification account must be funded for this to work. + +## Troubleshooting + +**I get an `pkg-config exited with status code 1` error**: You are likely missing +the `pkg-config` package. Make sure you have the dependencies listed in the +[requirements section](#requirements) installed properly. + +**I get an `error: failed to run custom build command for openssl-sys v0.9.102` error**: +You are likely missing the `openssl` package. Make sure you have the dependencies +listed in the [requirements section](#requirements) installed properly.