From 94a6204e88ef7fbbb20d0145c1362e85e249c477 Mon Sep 17 00:00:00 2001 From: Max Date: Wed, 5 Oct 2022 09:42:39 +0200 Subject: [PATCH] docs: Start documenting nns commands (#2601) # Description Note: This should be merged after the [secp256k1 PR](https://github.com/dfinity/sdk/pull/2598), as the docs mention command line access to toy ICP. # How Has This Been Tested? I have run the example commands manually. # Checklist: - [x] The title of this PR complies with [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/). - [x] I have edited the CHANGELOG accordingly. - [x] I have made corresponding changes to the documentation. --- CHANGELOG.md | 8 ++ docs/cli-reference/dfx-nns.md | 169 ++++++++++++++++++++++++++++++++++ 2 files changed, 177 insertions(+) create mode 100644 docs/cli-reference/dfx-nns.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 62eecf3cd5..8643002fec 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,14 @@ The function for calling sns can now call any bundled binary. +### docs: Document dfx nns subcommands + +`dfx nns` commands are used to deploy and manage local NNS canisters, such as: + +- Governance for integration with the Internet Computer voting system +- Ledger for financial integration testing +- Internet Identity for user registration and authenttication + ### fix: Only kill main process on `dfx stop` Removes misleading panics when running `dfx stop`. diff --git a/docs/cli-reference/dfx-nns.md b/docs/cli-reference/dfx-nns.md new file mode 100644 index 0000000000..76a7f63f29 --- /dev/null +++ b/docs/cli-reference/dfx-nns.md @@ -0,0 +1,169 @@ + +Use the `dfx nns` subcommands to interact with the Network Nervous System. + +The basic syntax for running `dfx nns` commands is: + +``` bash +dfx nns [subcommand] [flag] +``` + +Depending on the `dfx nns` subcommand you specify, additional arguments, options, and flags might apply. For reference information and examples that illustrate using `dfx nns` commands, select an appropriate command. + +| Command | Description | +|-------------------------------------|-------------------------------------------------------------------------------| +| [`import`](#_dfx_nns_import) | Adds the NNS canisters to the local dfx.json as remote canisters. | +| [`install`](#_dfx_nns_install) | Deploys NNS canisters to the local dfx server. | +| `help` | Displays usage information message for a specified subcommand. | + +To view usage information for a specific subcommand, specify the subcommand and the `--help` flag. For example, to see usage information for `dfx nns install`, you can run the following command: + +``` bash +$ dfx nns install --help +``` + + +## dfx nns import + +Use the `dfx nns import` command to add the NNS canisters to the local `dfx.json`. It also downloads the did files and sets the canister IDs of the NNS cansiters so that you can make API calls to NNS canisters. + +### Basic usage + +``` bash +$ dfx nns import +``` + +### Flags + +You can use the following optional flags with the `dfx nns import` command. + +| Flag | Description | +|---------------------|------------------------------------------------| +| `-h`, `--help` | Displays usage information. | +| `--network-mapping` | Renames networks when installing canister IDs. | +| `-V`, `--version` | Displays version information. | + +### Examples + +You can use the `dfx nns import` command to get did files and so query NNS canisters. + +``` bash +$ dfx nns import +$ dfx canister call --network ic nns-governance get_pending_proposals '()' +``` + +You can rename a network on import. For example, if you have `test-ic` set up as an alias of the `ic` network then you can set NNS canister IDs for `test-ic` with: + +``` bash +$ dfx nns import --network-mapping test-ic=ic +``` + +## dfx nns install + +Use the `dfx nns install` command to install a local NNS. This provides local ledger and governance canisters as well as the GUI canisters Internet Identity and NNS-Dapp. + +### Basic usage +The local network needs to be set up with a very specific configuration: +``` +$ cat ~/.config/dfx/networks.json +{ + "local": { + "bind": "127.0.0.1:8080", + "type": "ephemeral", + "replica": { + "subnet_type": "system" + } + } +} +``` + +This is because: + +* The NNS canisters need to run on a system subnet. +* Some canisters are comiled to run on only very specific canister IDs and hostname/port pairs. + + +In addition, the local dfx server needs to be clean: + +``` bash +$ dfx start --clean --background +$ dfx nns install +``` + +This is because NNS canisters need to be installed before any others. + + +### Flags + +You can use the following optional flags with the `dfx nns install` command. + +| Flag | Description | +|-------------------|-------------------------------| +| `-h`, `--help` | Displays usage information. | +| `-V`, `--version` | Displays version information. | + +### Examples + +#### Example: Making API calls to the local NNS. + +``` bash +$ dfx stop +$ dfx start --clean --background +$ dfx nns install +$ dfx nns import +$ dfx canister call --network ic nns-governance get_pending_proposals '()' +``` + +You can view the API calls that can be made for each NNS canister by looking at the interface definition files installed by `dfx nns import` in `candid/*.did`. The API methods are in the `service` section, which is usually located at the end of a `.did` file. It is easiest to start experimenting with methods that take no arguments. + +#### Example: Accessing ICP on the command line +Two accounts in the local ledger is initialized with ICP that can be used for testing. One uses a secp256k1 key, which is convenient for command line usage, another uses an ed25519 key, which is more convenient in web applications. + + + +To use ICP on the command line: +* Start dfx and install the NNS, as described in [`install`](#_dfx_nns_install). +* Put this secret key into a file called `ident-1.pem`: +``` bash +$ cat <ident-1.pem +-----BEGIN EC PRIVATE KEY----- +MHQCAQEEICJxApEbuZznKFpV+VKACRK30i6+7u5Z13/DOl18cIC+oAcGBSuBBAAK +oUQDQgAEPas6Iag4TUx+Uop+3NhE6s3FlayFtbwdhRVjvOar0kPTfE/N8N6btRnd +74ly5xXEBNSXiENyxhEuzOZrIWMCNQ== +-----END EC PRIVATE KEY----- +EOF +``` +* Check the key: (optional) +``` +$ openssl ec -in ident-1.pem -noout -text +``` +* Create an identity with that secret key: +``` bash +$ dfx identity import ident-1 ident-1.pem +``` +* Now you can use the (toy) funds: +``` bash +$ dfx ledger balance +``` + +To use ICP in an existing web application: +* Install the [@dfinity/agent npm module](https://www.npmjs.com/package/@dfinity/agent). +* Create an identity with this key pair: +``` + const publicKey = "Uu8wv55BKmk9ZErr6OIt5XR1kpEGXcOSOC1OYzrAwuk="; + const privateKey = + "N3HB8Hh2PrWqhWH2Qqgr1vbU9T3gb1zgdBD8ZOdlQnVS7zC/nkEqaT1kSuvo4i3ldHWSkQZdw5I4LU5jOsDC6Q=="; + const identity = Ed25519KeyIdentity.fromKeyPair( + base64ToUInt8Array(publicKey), + base64ToUInt8Array(privateKey) + ); + + // If using node: + const base64ToUInt8Array = (base64String: string): Uint8Array => { + return Buffer.from(base64String, 'base64') + }; + // If in a browser: + const base64ToUInt8Array = (base64String: string): Uint8Array => { + return Uint8Array.from(window.atob(base64String), (c) => c.charCodeAt(0)); + }; +``` +* That identity can now make API calls, including sending ICP.