From 3eab10c8929c50cab4b18f1190fe16d9513747ec Mon Sep 17 00:00:00 2001 From: Filippo <110459737+filippoweb3@users.noreply.github.com> Date: Tue, 14 Feb 2023 10:53:22 +0100 Subject: [PATCH] Update ledger info (#4460) * Minor additions for ledger users * Run grammarly on ledger page * Run grammarly nomination pools page * Update docs/general/ledger.md Co-authored-by: Radha <86818441+DrW3RK@users.noreply.github.com> --------- Co-authored-by: Radha <86818441+DrW3RK@users.noreply.github.com> --- docs/general/ledger.md | 71 ++++++++++++++-------------- docs/learn/learn-nomination-pools.md | 28 ++++++----- 2 files changed, 51 insertions(+), 48 deletions(-) diff --git a/docs/general/ledger.md b/docs/general/ledger.md index cd8e461059b8..f5acd230bb64 100644 --- a/docs/general/ledger.md +++ b/docs/general/ledger.md @@ -23,19 +23,19 @@ for single calls (i.e., bonding and nominating). ::: -The Polkadot [Ledger](https://www.ledger.com/) application is compatible with both the Ledger Nano S -and the Ledger Nano X devices. Ledger devices are hardware wallets that keep your secret key secured -on a physical device that does not expose it to your computer or the internet. That is, even if you -connect your nano via USB to your computer, the private keys will not be leaked. Ledger devices are -also hierarchical deterministic wallets (HD wallets), that is: - -- _Deterministic_ means that there is only one seed phrase to generate all the accounts for - different blockchain networks. +The Polkadot [Ledger](https://www.ledger.com/) application is compatible with the Ledger Nano S and +the Ledger Nano X devices. Ledger devices are hardware wallets that keep your secret key secured on +a physical device that does not expose it to your computer or the internet. Even if you connect your +nano via USB to your computer, the private keys will not be leaked. Ledger devices are also +hierarchical deterministic wallets (HD wallets), that is: + +- _Deterministic_ means that only one seed phrase generates all the accounts for different + blockchain networks. - _Hierarchical_ means that the accounts are generated in a tree-like structure for different purposes. Ledger devices can be equipped with applications that are blockchain-specific. Such applications are -usually developed by third parties and they enable the user to transact securely on the blockchain +usually developed by third parties, and they enable the user to transact securely on the blockchain network. The Polkadot Ledger application allows you to manage Polkadot's native token, DOT. It supports most of the transaction types of the network, including batch transactions from the Utility pallet. @@ -43,10 +43,11 @@ pallet. :::note Ledger apps may not support all the transactions Check [Ledger Polkadot App](https://github.com/Zondax/ledger-polkadot) specification for the list of -transactions supported. It could be possible that some transactions are supported only on a specific -version of the app and some transactions are not supported at all by any version. For instance, the -staking `rebag` extrinsic is supported on the XL version but not on the light version. The -`setIdentity` extrinsic is not supported by any of the app versions. +transactions supported. Some transactions are supported only on a specific version of the app, and +others are not supported at all by any version. For instance, the staking `rebag` extrinsic is +supported on the XL version but not on the light version. Support for the XL version is limited to +single calls (not batch calls), meaning you can rebag one account at a time. Also, joining a +[nomination pool](../learn/learn-nomination-pools.md) is only possible with the XL version. ::: @@ -76,9 +77,9 @@ to learn how to use Polkadot with ledger live. Ledger Live will only show the main account with BIP44 path 44'/354'/0'/0'/0'. This means that if you create a [derived account using Polkadot JS](#using-on-polkadot-js-apps) with a derivation path -44'/354'/0'/0'/1', it will not be displayed on the Ledger Live App. As a consequence it is not -possible to transact with derived accounts using the Ledger Live App, but it is possible to do so -using Polkadot JS. For more information about derived accounts and derivation paths check +44'/354'/0'/0'/1', it will not be displayed on the Ledger Live App. Consequently, it is not possible +to transact with derived accounts using the Ledger Live App, but it is possible to do so using +Polkadot JS. For more information about derived accounts and derivation paths, check [the accounts page](../learn/learn-accounts.md). ::: @@ -108,7 +109,7 @@ When adding a Ledger account using the extension or the UI, you will be asked to you pick a derivation path from that account - think of it like a formula from which child accounts are generated. When you are creating a Polkadot ledger account for the first time on Ledger Live with name `Polkadot 1`, this can be added to Polkadot JS using the 0/0 derivation path (i.e. account -type = 0 and account index = 0). If then you add a second account called `Polkadot 2`, this will +type = 0 and account index = 0). If you add a second account called `Polkadot 2`, this will correspond to the 1/0 derivation path, and so on. We thus have multiple parent accounts that can be viewed and used in both Ledger Live and Polkadot JS. Additionally, we can use Polkadot-JS UI to created multiple children accounts from each parent account. For example, `Polkadot 1` with 0/0 @@ -129,8 +130,8 @@ If you are adding your Ledger Nano for the first time, click on the "Unknown dev :::info Signature error message -If you already connected your device but an error message appears before signing a transaction, make -sure you have opened the Polkadot application on your Ledger Nano device. Visit +If you have already connected your device, but an error message appears before signing a +transaction, make sure you have opened the Polkadot application on your Ledger Nano device. Visit [this support page](https://support.polkadot.network/support/solutions/articles/65000181994) for more information about signing transactions using your ledger. @@ -140,7 +141,7 @@ more information about signing transactions using your ledger. To display your Polkadot ledger account address on your Ledger Nano you can follow the guidelines on [this support article](https://support.polkadot.network/support/solutions/articles/65000181854-how-to-confirm-your-account-address-on-your-ledger-device). -Here you can scroll through and make sure the address matches to what is displayed on +Here you can scroll through and make sure the address matches what is displayed on [Polkadot-JS UI](https://polkadot.js.org/apps/#/explorer). ### Checking the Balance of Your Account @@ -158,13 +159,13 @@ To sign transactions with your Ledger nano check ### Receiving a Transfer -In order to receive a transfer on the accounts stored on your Ledger device, you will need to -provide the sender (i.e. the payer) with your address. To do so follow the instructions on +To receive a transfer on the accounts stored on your Ledger device, you will need to provide the +sender (i.e. the payer) with your address. To do so, follow the instructions on [this support page](https://support.polkadot.network/support/solutions/articles/65000181866-how-to-receive-dot-to-my-account-on-polkadot-js-ui). :::warning -Before giving anyone your address, make sure it matches what's really on the Ledger by +Before giving anyone your address, make sure it matches what's on the Ledger by [confirming the address on your device](#confirming-the-address-on-your-device). Some malware will intercept clicks and clipboard requests and can change your copied value in-flight, so being extra vigilant around copy-paste operations makes sense. @@ -173,7 +174,7 @@ vigilant around copy-paste operations makes sense. ### Staking -For staking using Ledger devices check the section "How to stake using your Ledger" on +For staking using Ledger devices, check the section "How to stake using your Ledger" on [this support article](https://support.polkadot.network/support/solutions/articles/65000168057-how-do-i-stake-nominate-on-polkadot-). ### Removing Expired Democracy Locks @@ -205,11 +206,11 @@ release for testing purposes. After a successful audit and review, the apps woul download and installation using [Ledger Live](https://www.ledger.com/ledger-live). As it takes some time for Ledger to audit and review the release, the app upgrade option may not be available on Ledger Live when the new runtime is deployed on the network. If this happens, users cannot use -Ledger devices with the Polkadot-JS UI, and while signing for a transaction, they will most likely -incur the error message "txn version not supported". Please do not panic if this happens, as there -are solutions to this problem. If you cannot wait a couple of days until the app passes the Ledger -audit, you can install the developer release from the shell using the latest version published on -[the Zondax GitHub repository](https://github.com/Zondax/ledger-polkadot/releases). +Ledger devices with the Polkadot-JS UI, and while signing for a transaction, will most likely incur +the error message "txn version not supported". Please do not panic if this happens, as there are +solutions to this problem. Suppose you cannot wait a couple of days until the app passes the Ledger +audit. In that case, you can install the developer release from the shell using the latest version +published on [the Zondax GitHub repository](https://github.com/Zondax/ledger-polkadot/releases). ### Install the Developer Release @@ -229,7 +230,7 @@ below: - Install _ledgerblue_ running the command `python3 -m pip install ledgerblue`. - Download the developer release from the [Zondax GitHub repository](https://github.com/Zondax/ledger-polkadot/releases). The file will be - named `installer_nanos_plus.sh`or something similar depending on the ledger device you are using. + named `installer_nanos_plus.sh` or something similar, depending on your ledger device. - Locate the downloaded shell script and make it executable in your shell by typing the command `chmod +x installer_nanos_plus.sh`. - You can now use the `./installer_nanos_plus.sh --help` command to visualize the available options @@ -237,12 +238,12 @@ below: ![Dev Ledger Help Menu](../assets/ledger-help-menu.png) -- Next attach your Ledger Nano (in this case Nano S Plus) to your computer, enter the PIN code and +- Next, attach your Ledger Nano (in this case Nano S Plus) to your computer, enter the PIN code, and run the command `./installer_nanos_plus.sh load`. Scroll with the right button until you see "Allow unsafe manager", left and right press to confirm. You will be asked to confirm the action - of uninstalling the app, and subsequently installing the newer version. After confirming both - actions the shell script will proceed to install the version on your device. You will need to - insert the PIN code to use the device after the installation. -- If you wish to revert the version back to stable release just go to Ledger Live, the app will + of uninstalling the app and subsequently installing the newer version. After confirming both + actions, the shell script will install the version on your device. You will need to insert the PIN + code to use the device after the installation. +- If you wish to revert the version to the stable release, go to Ledger Live. The app will automatically detect the developer release and give the option to install the previous stable release. diff --git a/docs/learn/learn-nomination-pools.md b/docs/learn/learn-nomination-pools.md index 3423c1242f39..9543cdaa1c1a 100644 --- a/docs/learn/learn-nomination-pools.md +++ b/docs/learn/learn-nomination-pools.md @@ -39,7 +39,10 @@ system’s scalability. Now, anyone with as little as :::note Learn the key differences between -[**Staking directly vs Joining a Nomination Pool**](../maintain/maintain-guides-how-to-nominate-polkadot.md#nominating-vs-joining-a-pool). +[**Staking directly vs Joining a Nomination Pool**](#nominating-vs-joining-a-pool). + +**For Ledger users:** Joining a nomination pool is possible only with the XL version of the Polkadot +Ledger App. This should be installed by default on Ledger Nano X and S Plus, but not on the Nano S. ::: @@ -78,11 +81,11 @@ viewed as a single nominator from the NPoS system point of view. :::info Why aren't the members in the nomination pools called delegators? -The term `delegator` is associated too much with Delegated Proof of Staking (DPoS) and since +The term `delegator` is associated too much with Delegated Proof of Staking (DPoS), and since {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} implements Nominated Proof of Staking -(NPoS), naming them as delegators would be misleading. The term `member` is our generic replacement -for `delegator`. In action, members are quite similar to delegators and do delegate their nomination -power to the pool. +(NPoS), naming them delegators would be misleading. The term `member` is our generic replacement for +`delegator`. In action, members are quite similar to delegators and delegate their nomination power +to the pool. ::: @@ -186,8 +189,8 @@ balance. - Blocked: The pool is blocked; no joiners are permitted. - Destroying: The pool is in the process of being destroyed. Once in this state, the pool may never revert to any other state; it can only proceed to be destroyed. All members can be - permissionlessly unbonded; this allows the pool to be dismantled regardless of any individual - member’s proactivity. + permissionlessly unbonded; this allows the pool to be dismantled regardless of any member’s + proactivity. ### Roles @@ -240,9 +243,8 @@ nominate like you would normally using a nominator account. ![Nominate validators](../assets/staking/Nomination-Pools-5.png) -The `state-toggler` can update the pool’s state to blocked through `setState` extrinsic and then -kick members by calling `unbond` and `withdrawUnbonded`. (The state can also be toggled back to -open). +The `state-toggler` can update the pool’s state to blocked through `setState` extrinsic and kick +members by calling `unbond` and `withdrawUnbonded`. (The state can also be toggled back to open). ### Destruction @@ -269,7 +271,7 @@ Unbonding pools need to be slashed to ensure all nominators who were in the bond backing a validator that committed an offense are punished. Without these measures a nominator could unbond right after a validator equivocated with no consequences. -This strategy is unfair to members who joined after the slash because they get slashed as well but +This strategy is unfair to members who joined after the slash because they get slashed as well, but it spares members who unbond. The latter is much more important for security: if a pool's validators attack the network, their members need to unbond fast! Avoiding additional slashes gives them an incentive to do that if validators get repeatedly slashed. @@ -287,7 +289,7 @@ on your validators, if your active validator is oversubscribed, you will earn re stake is within that of the top {{ polkadot: :polkadot }}{{ kusama: :kusama }} nominators. If the validator misbehaves, It is worth noting that your stake is subject to slashing, -irrespective of whether you are in the top +irrespective of whether you are at the top {{ polkadot: :polkadot }}{{ kusama: :kusama }} nominators or not. @@ -315,6 +317,6 @@ from time to time and change the pool if necessary. | Maximum uncapped. | Maximum uncapped. | | Should bond more than the [minimum active nomination](../learn/learn-nominator.md#minimum-active-nomination-to-receive-staking-rewards) in an era to be eligible to earn staking rewards, although it can depend on multiple other factors outlined in the linked document. | A nomination pool earns rewards in an era if it satisfies all the conditions mentioned for the nominator (as the nomination pool is just a nominator from [the NPoS system](../learn/learn-phragmen.md) perspective). | | Staked tokens can be used for participation in Governance. | Staked tokens cannot be used for participation in Governance. | -| [Rewards payout](../learn/learn-staking-advanced.md#claiming-rewards) can be triggered permissionlessly by anyone (typically done by the validator). | Rewards must be claimed by the pool member. | +| [Rewards payout](../learn/learn-staking-advanced.md#claiming-rewards) can be triggered permissionlessly by anyone (typically done by the validator). | The pool member must claim the rewards. | | Bonded funds remain in your account. | Bonded funds are transferred to a pool account which is administered by the network protocol and is not accessible to anyone else. | | Nominator manages the list of staked validators (up to 16). | Nominations managed by the pool operator. |