From abae98f8d12c9c304cdf7bff8aafb0aaa29a78fb Mon Sep 17 00:00:00 2001 From: iskay Date: Fri, 6 Sep 2024 11:18:58 -0400 Subject: [PATCH 1/3] update ledger docs --- .../genesis-flow/participants.mdx | 94 ++++++++++- .../pages/users/wallet/hardware-wallet.mdx | 152 ++++++++++++++++-- .../docs/pages/users/wallet/web-wallet.mdx | 6 +- 3 files changed, 233 insertions(+), 19 deletions(-) diff --git a/packages/docs/pages/networks/starting-network/genesis-flow/participants.mdx b/packages/docs/pages/networks/starting-network/genesis-flow/participants.mdx index 3e01136b..3f61291a 100644 --- a/packages/docs/pages/networks/starting-network/genesis-flow/participants.mdx +++ b/packages/docs/pages/networks/starting-network/genesis-flow/participants.mdx @@ -252,6 +252,8 @@ namadac utils genesis-bond \ ### Signing transactions +*See [below](#signing-with-a-ledger-hardware-wallet) for instructions on how to sign with a Ledger hardware wallet.* + For validator initialization and bonding transactions, after generating your pre-genesis transaction (but before submitting it for inclusion in the genesis block), you must sign it with the relevant private key. You can do this using the `sign-genesis-txs` command. @@ -263,7 +265,7 @@ To sign an init-validator transaction, use: namadac utils sign-genesis-txs --path $INPUT_FILE --output $OUTPUT_FILE --alias $VALIDATOR_ALIAS ``` -When signing a bond transaction, the `alias` can be omitted: +When signing a bond transaction, the `alias` is omitted: ```bash copy namadac utils sign-genesis-txs --path $INPUT_FILE --output $OUTPUT_FILE ``` @@ -280,3 +282,93 @@ repo will be created where the files can be submitted via pull request. By conve the git repository. The signed transactions `toml` file is then submitted to its respective directory. + +## Signing with a Ledger hardware wallet + +### Deriving your account +You can sign your pre-genesis transactions using a Ledger hardware wallet. + +First, refer to the [Hardware Wallet](./../../../users/wallet/hardware-wallet.mdx) section for instructions on how to install the +Namada app on your Ledger device and how to use it with the Namada CLI. + +Once your Ledger is ready, connect it via USB and open the Namada Ledger app. + +We begin by deriving a Ledger account and adding it to our pre-genesis wallet using this command: +``` +namadaw --pre-genesis derive --use-device --alias $ALIAS +``` +(You will be asked to confirm the operation on your device.) + +If successful, you should see the following output: +``` +Output: +Using HD derivation path m/44'/877'/0'/0'/0' +Successfully added a key and an address with alias: "..." +``` +The default derivation path is `m/44'/877'/0'/0'/0`. You can use the flag `--hd-path` to specify a different derivation path. Use `namadaw derive --help` for more information. + +You can list your wallet contents with: +``` +namadaw --pre-genesis list +``` +You should see your address and pubic key listed under the `$ALIAS` you provided. Beside them should be the label `(external)` indicating that they are associated with a device. +You will need to make note of your public key in order to complete the remaining steps. + +### Signing the pre-genesis transaction `toml` +The flag `--use-device` is used to indicate that a Ledger will be used for signing. When attempting to sign, have the device +connected to your computer with the Namada Ledger app open. + +Ensure the 'expert mode' toggle in the Ledger app is set to `disabled`. + + +#### Signing an `initialize-validator` pre-genesis transaction +To create a pre-genesis initialize-validator transaction, begin by using the Ledger account public key to +[initialize an established account](#initialize-an-established-account). In this command, `$ALIAS` should be the alias +given to your Ledger account during [derivation](#deriving-your-account): +``` +namadac utils init-genesis-established-account \ + --path $OUTPUT_FILE \ + --aliases $ALIAS +``` + +Proceed with [initializing a validator account](#initialize-a-pre-genesis-validator-account) according to the usual procedure. + +Finally, sign using the following command: +``` +namadac utils sign-genesis-txs \ + --path $INPUT_FILE \ + --output $OUTPUT_FILE \ + --alias $VALIDATOR_ALIAS \ + --use-device +``` + +It's important to note that both the Ledger and the validator soft wallet created when initializing your validator account +are required to sign the transaction. +- The Ledger account is checked against the public key in the `[[established_account]]` section and used to generate the corresponding signature +- The validator soft wallet (located inside `$BASE_DIR/pre-genesis/$VALIDATOR_ALIAS/`) is used to generate the corresponding +signatures (`[validator_account.protocol_key]`, `[validator_account.tendermint_node_key]`, etc.) + +If either is not accessible, signing will fail. + +#### Signing a `bond` pre-genesis transaction +To create a pre-genesis bond transaction, provide the public key associated with your Ledger account as the `$SOURCE`: +``` +namadac utils genesis-bond \ + --validator $TARGET_VALIDATOR \ + --source $SOURCE \ + --amount $AMOUNT \ + --path $OUTPUT_FILE +``` + +Signing the transaction is very similar to using a soft wallet: +``` +namadac utils sign-genesis-txs \ + --path $INPUT_FILE \ + --output $OUTPUT_FILE \ + --use-device +``` + + +### Troubleshooting +Refer to the [Troubleshooting section of the Hardware Wallet page](../../../users/wallet/hardware-wallet.mdx#troubleshooting) +for help resolving common errors. \ No newline at end of file diff --git a/packages/docs/pages/users/wallet/hardware-wallet.mdx b/packages/docs/pages/users/wallet/hardware-wallet.mdx index 49e07745..92b248ce 100644 --- a/packages/docs/pages/users/wallet/hardware-wallet.mdx +++ b/packages/docs/pages/users/wallet/hardware-wallet.mdx @@ -1,28 +1,146 @@ import { Callout } from 'nextra-theme-docs' +import { Steps } from 'nextra-theme-docs' -## Hardware Wallet +# Ledger Hardware Wallet -The Namada Ledger app is currently in active development and not recommended for use. Information below may be out-of-date. +The Namada Ledger app is still in active development, and the version available on the official Ledger App store is not compatible with the current release of Namada. +See the installation instructions below if you'd like to sideload an updated development version of the app onto your device for testing purposes. -Namada's web wallet extension is compatible with the [Ledger](https://www.ledger.com/) hardware. This guide will walk you through the process of setting up your Ledger device to work with Namada. +Both Namada's web wallet extension and the Namada CLI are compatible with the [Ledger](https://www.ledger.com/) hardware wallet. +This guide will walk you through the process of setting up your Ledger device to work with Namada. -### Prerequisites -A ledger device with the latest firmware installed. You can find instructions on how to update your firmware [here](https://support.ledger.com/hc/en-us/articles/360002731113-Update-device-firmware). +## Prerequisites +A Ledger device with the latest firmware installed. You can find instructions on how to update your firmware [here](https://support.ledger.com/hc/en-us/articles/360002731113-Update-device-firmware). -Install the javascript npm package [here](https://www.npmjs.com/package/@zondax/ledger-namada). +In order to use the Ledger with the web wallet, you will need to install the [Namada Web Wallet](./web-wallet.mdx#install). To use the Ledger with the Namada CLI, +you will need to [install the latest version](./../../introduction/install.mdx) of Namada. -In order to use the ledger with the web wallet, you will need to install the [Namada Web Wallet](./web-wallet.mdx#install). +## Installing the Namada Ledger app + +The Namada Ledger app is still a work in progress. Use at your own risk. At this preliminary stage of development, it is *highly* recommended that you use a device which +does not contain any existing funds. -### Connecting your Ledger -1. Open the Namada web extension. -2. Under settings, click on the `Connect Ledger` button. -3. Set an alias for the account that ledger will control the keys for. -4. You can choose to connect to the ledger via `USB` (recommended) or `HID` (Human Interface Devices). -5. The ledger will ask you to confirm the connection. Confirm this connection on your ledger device. -6. Once completed, the extension will show the address of the account that the ledger is controlling the keys for. -7. You can now close the information window and use the ledger to sign transactions. +When installing a Ledger app from any source besides the official app store, you will be shown a warning to that effect and prompted for confirmation. Please make sure you +understand the risks before proceeding. Before installing *any* app from a non-official source, be sure that you trust the authors and the instructions being given. As always, do your own research. + + + +### Connect your device to your computer +The remaining steps assume you have already completed the initial Ledger setup and your device is ready to use. + +### Uninstall any existing Namada apps on your device + +### Visit the Zondax Hub and prepare your device +In your browser, visit the [Zondax Hub](https://hub.zondax.ch). Click the "Connect Device" button in the top right corner, and confirm the connection in your browser and on your device. + +### Install the Namada app +Scroll down until you find Namada in the list, and select the newest version from the dropdown. Click "Install" and confirm on your device. + + + +## Using the Ledger app with the browser extension + +### Importing (deriving) your Ledger address +Before any other operations with the Ledger, we will want to derive an address and public key and add them to the extension ([web wallet](./web-wallet.mdx)) under an alias for convenience. +To derive your address using a Ledger: + + +### Open Extension and click 'Add keys' + +### Click 'Connect hardware wallet' + +### Connect your device to your computer and Open the Namada app +Follow the prompts and click 'Next' after each step + +### Confirm on device +After the following the prompts, your address and public key will be displayed on your device. Confirm the operation on your device. + +### Name your Ledger account +Give your account an easy to remember name. + +### Click 'Finish setup' + + +### Display your address/public key +To display your Ledger address/public key, first open the extension. Find your Ledger account in the list, click the `⋮` icon (three vertical dots) and select 'View keys'. + +### Signing a transaction +To sign a transaction from a front-end app (such as [Namadillo](./../../integrating-with-namada/interface.mdx)), follow these steps: + + +### Connect your device and open the Namada app + +### Set your Ledger as the active account +Open the extension and click the checkbox next to your Ledger account to set it as the active account. + +### Perform your transaction + +### Review transaction +You will be presented with a browser pop-up containing a summary of the transaction. You can click 'View data' to see the +details of what will be submitted on-chain. You can also verify the correct public key is listed under 'Signer'. When you're +ready to proceed, click 'Approve'. + +You will be reminded again to connect your device and open the Namada app; click 'Submit' to send the signing request to the Ledger. + +### Approve on your device +Review the transaction details on your device and click 'Approve' to sign and submit the transaction to the chain. + + +## Using the Ledger app with the CLI +You can use your Ledger to sign transactions from the Namada CLI. + +Make sure the 'expert mode' toggle is set to disabled in the Namada app; this feature has not yet been implemented and may result in crashes. + + +### Importing (deriving) your Ledger address +Before any other operations with the Ledger, we will want to derive an address and public key and add them to the [file system wallet](./file-system-wallet.mdx) under an alias for convenience. +To derive your address using a Ledger: + + +### Connect your device to your computer + +### Open the Namada app on your device + +### Derive your address/public key +This command will derive your address and public key and add them to your wallet under an `alias` of your choosing: +``` +namadaw --use-device --alias $ALIAS +``` +The default derivation path is `m/44'/877'/0'/0'/0`. You can use the flag `--hd-path` to specify a different derivation path. Use `namadaw derive --help` for more information. + +### Confirm in wallet +List your wallet contents with: +``` +namadaw list +``` +You should see your address and pubic key listed under the `$ALIAS` you provided. Beside them should be the label `(external)` indicating that they are associated with a device. + + +### Signing a transaction +Use the `--use-device` flag when you wish to sign a transaction using the Ledger. For example: +``` +namadac transparent-transfer \ + --source $ALIAS \ + --target $DEST_ADDRESS \ + --token nam \ + --amount 100 \ + --use-device +``` +When constructing the transfer, the CLI will check your wallet for the public key given under `$ALIAS`. You will then be prompted on the device to approve the transaction + +### Troubleshooting +Some common errors you may encounter while using the Ledger with the Namada CLI: + +- `Unable to connect to query address and public key from Ledger: Ledger | App Error: | 21781 [APDU_ERROR] Unknown` +There is a USB connectivity issue; disconnecting and reconnecting the Ledger will often resolve this. + +- The CLI panics with `Message: Failed to sign transaction` or similar. +Make sure you're using the correct versions of both the Ledger app and Namada binaries + +- The CLI panics with `Message: No signature could be produced for a transaction of type ...` +Make sure the Ledger account has been properly [added to your wallet](#importing-deriving-your-ledger-address-1). -### Sending transactions with the ledger -See the [web wallet](./web-wallet.mdx#sending-transactions) guide for instructions on how to send transactions with the web wallet. +- The CLI panics part-way through signing and the Ledger reboots. +Make sure the 'expert mode' toggle in the Ledger app is set to `disabled`. \ No newline at end of file diff --git a/packages/docs/pages/users/wallet/web-wallet.mdx b/packages/docs/pages/users/wallet/web-wallet.mdx index b3cd7af3..82b78c68 100644 --- a/packages/docs/pages/users/wallet/web-wallet.mdx +++ b/packages/docs/pages/users/wallet/web-wallet.mdx @@ -71,4 +71,8 @@ Whenever you submit a transaction to the chain, you will be prompted to enter yo ### Disconnect If you wish to disconnect (remove permissions) from a site, you can do so in the Settings menu of the extension, under 'Connected Sites'. - \ No newline at end of file + + +## Using a hardware wallet (Ledger) +See the [hardware wallet](./hardware-wallet.mdx) page for instructions on installing the Namada Ledger app and using it +with the extension. \ No newline at end of file From d629e3095a39055c5bce3c322b65fd9c35b92792 Mon Sep 17 00:00:00 2001 From: iskay Date: Fri, 6 Sep 2024 11:48:11 -0400 Subject: [PATCH 2/3] minor edits --- .../starting-network/genesis-flow/participants.mdx | 10 ++++++---- packages/docs/pages/users/wallet/hardware-wallet.mdx | 4 ++-- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/packages/docs/pages/networks/starting-network/genesis-flow/participants.mdx b/packages/docs/pages/networks/starting-network/genesis-flow/participants.mdx index 3f61291a..fb256672 100644 --- a/packages/docs/pages/networks/starting-network/genesis-flow/participants.mdx +++ b/packages/docs/pages/networks/starting-network/genesis-flow/participants.mdx @@ -283,9 +283,7 @@ the git repository. The signed transactions `toml` file is then submitted to its -## Signing with a Ledger hardware wallet - -### Deriving your account +## Using a Ledger hardware wallet You can sign your pre-genesis transactions using a Ledger hardware wallet. First, refer to the [Hardware Wallet](./../../../users/wallet/hardware-wallet.mdx) section for instructions on how to install the @@ -293,7 +291,11 @@ Namada app on your Ledger device and how to use it with the Namada CLI. Once your Ledger is ready, connect it via USB and open the Namada Ledger app. -We begin by deriving a Ledger account and adding it to our pre-genesis wallet using this command: +The general procedure of generating and signing pre-genesis transactions is the same as given +above with a few minor variations. + +### Deriving your account +Before doing anything else, begin by deriving a Ledger account and adding it to the pre-genesis wallet using this command: ``` namadaw --pre-genesis derive --use-device --alias $ALIAS ``` diff --git a/packages/docs/pages/users/wallet/hardware-wallet.mdx b/packages/docs/pages/users/wallet/hardware-wallet.mdx index 92b248ce..1f1d055d 100644 --- a/packages/docs/pages/users/wallet/hardware-wallet.mdx +++ b/packages/docs/pages/users/wallet/hardware-wallet.mdx @@ -124,8 +124,8 @@ Use the `--use-device` flag when you wish to sign a transaction using the Ledger namadac transparent-transfer \ --source $ALIAS \ --target $DEST_ADDRESS \ - --token nam \ - --amount 100 \ + --token $TOKEN \ + --amount $AMOUNT \ --use-device ``` When constructing the transfer, the CLI will check your wallet for the public key given under `$ALIAS`. You will then be prompted on the device to approve the transaction From 398d24bc93d9b0e9f99ec674e18017f87f8dd903 Mon Sep 17 00:00:00 2001 From: brentstone Date: Sun, 8 Sep 2024 17:49:20 +0200 Subject: [PATCH 3/3] small edits --- .../genesis-flow/participants.mdx | 14 ++++----- .../pages/users/wallet/hardware-wallet.mdx | 30 +++++++++---------- 2 files changed, 22 insertions(+), 22 deletions(-) diff --git a/packages/docs/pages/networks/starting-network/genesis-flow/participants.mdx b/packages/docs/pages/networks/starting-network/genesis-flow/participants.mdx index fb256672..4ee26c08 100644 --- a/packages/docs/pages/networks/starting-network/genesis-flow/participants.mdx +++ b/packages/docs/pages/networks/starting-network/genesis-flow/participants.mdx @@ -296,7 +296,7 @@ above with a few minor variations. ### Deriving your account Before doing anything else, begin by deriving a Ledger account and adding it to the pre-genesis wallet using this command: -``` +```bash copy namadaw --pre-genesis derive --use-device --alias $ALIAS ``` (You will be asked to confirm the operation on your device.) @@ -310,10 +310,10 @@ Successfully added a key and an address with alias: "..." The default derivation path is `m/44'/877'/0'/0'/0`. You can use the flag `--hd-path` to specify a different derivation path. Use `namadaw derive --help` for more information. You can list your wallet contents with: -``` +```bash copy namadaw --pre-genesis list ``` -You should see your address and pubic key listed under the `$ALIAS` you provided. Beside them should be the label `(external)` indicating that they are associated with a device. +You should see your address and public key listed under the `$ALIAS` you provided. Beside them should be the label `(external)` indicating that they are associated with a device. You will need to make note of your public key in order to complete the remaining steps. ### Signing the pre-genesis transaction `toml` @@ -327,7 +327,7 @@ Ensure the 'expert mode' toggle in the Ledger app is set to `disabled`. To create a pre-genesis initialize-validator transaction, begin by using the Ledger account public key to [initialize an established account](#initialize-an-established-account). In this command, `$ALIAS` should be the alias given to your Ledger account during [derivation](#deriving-your-account): -``` +```bash copy namadac utils init-genesis-established-account \ --path $OUTPUT_FILE \ --aliases $ALIAS @@ -336,7 +336,7 @@ namadac utils init-genesis-established-account \ Proceed with [initializing a validator account](#initialize-a-pre-genesis-validator-account) according to the usual procedure. Finally, sign using the following command: -``` +```bash copy namadac utils sign-genesis-txs \ --path $INPUT_FILE \ --output $OUTPUT_FILE \ @@ -354,7 +354,7 @@ If either is not accessible, signing will fail. #### Signing a `bond` pre-genesis transaction To create a pre-genesis bond transaction, provide the public key associated with your Ledger account as the `$SOURCE`: -``` +```bash copy namadac utils genesis-bond \ --validator $TARGET_VALIDATOR \ --source $SOURCE \ @@ -363,7 +363,7 @@ namadac utils genesis-bond \ ``` Signing the transaction is very similar to using a soft wallet: -``` +```bash copy namadac utils sign-genesis-txs \ --path $INPUT_FILE \ --output $OUTPUT_FILE \ diff --git a/packages/docs/pages/users/wallet/hardware-wallet.mdx b/packages/docs/pages/users/wallet/hardware-wallet.mdx index 1f1d055d..21f55ca2 100644 --- a/packages/docs/pages/users/wallet/hardware-wallet.mdx +++ b/packages/docs/pages/users/wallet/hardware-wallet.mdx @@ -12,14 +12,14 @@ Both Namada's web wallet extension and the Namada CLI are compatible with the [L This guide will walk you through the process of setting up your Ledger device to work with Namada. ## Prerequisites -A Ledger device with the latest firmware installed. You can find instructions on how to update your firmware [here](https://support.ledger.com/hc/en-us/articles/360002731113-Update-device-firmware). +You will need a Ledger device with the latest firmware installed. You can find instructions on how to update your firmware [here](https://support.ledger.com/hc/en-us/articles/360002731113-Update-device-firmware). In order to use the Ledger with the web wallet, you will need to install the [Namada Web Wallet](./web-wallet.mdx#install). To use the Ledger with the Namada CLI, you will need to [install the latest version](./../../introduction/install.mdx) of Namada. ## Installing the Namada Ledger app -The Namada Ledger app is still a work in progress. Use at your own risk. At this preliminary stage of development, it is *highly* recommended that you use a device which +The Namada Ledger app is still a work in progress. Use at your own risk. At this preliminary stage of development, it is *highly* recommended that you use a device that does not contain any existing funds. When installing a Ledger app from any source besides the official app store, you will be shown a warning to that effect and prompted for confirmation. Please make sure you @@ -47,12 +47,12 @@ Before any other operations with the Ledger, we will want to derive an address a To derive your address using a Ledger: -### Open Extension and click 'Add keys' +### Open Extension and click `Add keys` -### Click 'Connect hardware wallet' +### Click `Connect hardware wallet` ### Connect your device to your computer and Open the Namada app -Follow the prompts and click 'Next' after each step +Follow the prompts and click `Next` after each step ### Confirm on device After the following the prompts, your address and public key will be displayed on your device. Confirm the operation on your device. @@ -60,7 +60,7 @@ After the following the prompts, your address and public key will be displayed o ### Name your Ledger account Give your account an easy to remember name. -### Click 'Finish setup' +### Click `Finish setup` ### Display your address/public key @@ -78,14 +78,14 @@ Open the extension and click the checkbox next to your Ledger account to set it ### Perform your transaction ### Review transaction -You will be presented with a browser pop-up containing a summary of the transaction. You can click 'View data' to see the -details of what will be submitted on-chain. You can also verify the correct public key is listed under 'Signer'. When you're -ready to proceed, click 'Approve'. +You will be presented with a browser pop-up containing a summary of the transaction. You can click `View data` to see the +details of what will be submitted on-chain. You can also verify the correct public key is listed under `Signer`. When you're +ready to proceed, click `Approve`. -You will be reminded again to connect your device and open the Namada app; click 'Submit' to send the signing request to the Ledger. +You will be reminded again to connect your device and open the Namada app; click `Submit` to send the signing request to the Ledger. ### Approve on your device -Review the transaction details on your device and click 'Approve' to sign and submit the transaction to the chain. +Review the transaction details on your device and click `Approve` to sign and submit the transaction to the chain. ## Using the Ledger app with the CLI @@ -105,14 +105,14 @@ To derive your address using a Ledger: ### Derive your address/public key This command will derive your address and public key and add them to your wallet under an `alias` of your choosing: -``` +```bash copy namadaw --use-device --alias $ALIAS ``` The default derivation path is `m/44'/877'/0'/0'/0`. You can use the flag `--hd-path` to specify a different derivation path. Use `namadaw derive --help` for more information. ### Confirm in wallet List your wallet contents with: -``` +```bash copy namadaw list ``` You should see your address and pubic key listed under the `$ALIAS` you provided. Beside them should be the label `(external)` indicating that they are associated with a device. @@ -120,7 +120,7 @@ You should see your address and pubic key listed under the `$ALIAS` you provided ### Signing a transaction Use the `--use-device` flag when you wish to sign a transaction using the Ledger. For example: -``` +```bash copy namadac transparent-transfer \ --source $ALIAS \ --target $DEST_ADDRESS \ @@ -143,4 +143,4 @@ Make sure you're using the correct versions of both the Ledger app and Namada bi Make sure the Ledger account has been properly [added to your wallet](#importing-deriving-your-ledger-address-1). - The CLI panics part-way through signing and the Ledger reboots. -Make sure the 'expert mode' toggle in the Ledger app is set to `disabled`. \ No newline at end of file +Make sure the `expert mode` toggle in the Ledger app is set to `disabled`. \ No newline at end of file