Skip to content

Commit

Permalink
Update ledger info (w3f#4460)
Browse files Browse the repository at this point in the history 
* Minor additions for ledger users

* Run grammarly on ledger page

* Run grammarly nomination pools page

* Update docs/general/ledger.md

Co-authored-by: Radha <[email protected]>

---------

Co-authored-by: Radha <[email protected]>
  • Loading branch information
@filippoweb3 @DrW3RK
filippoweb3 and DrW3RK authored Feb 14, 2023
1 parent 9d8ae20 commit 3eab10c
Show file tree
Hide file tree
Showing 2 changed files with 51 additions and 48 deletions.
71 changes: 36 additions & 35 deletions docs/general/ledger.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,30 +23,31 @@ 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.

:::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.

:::

Expand Down Expand Up @@ -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).

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

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

Expand All @@ -229,20 +230,20 @@ 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
(see 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.
28 changes: 15 additions & 13 deletions docs/learn/learn-nomination-pools.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

:::

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

:::

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

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

Expand All @@ -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.
Expand All @@ -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: <RPC network="polkadot" path="consts.staking.maxNominatorRewardedPerValidator" defaultValue={512}/> :polkadot }}{{ kusama: <RPC network="polkadot" path="consts.staking.maxNominatorRewardedPerValidator" defaultValue={512}/> :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: <RPC network="polkadot" path="consts.staking.maxNominatorRewardedPerValidator" defaultValue={512}/> :polkadot }}{{ kusama: <RPC network="polkadot" path="consts.staking.maxNominatorRewardedPerValidator" defaultValue={512}/> :kusama }}
nominators or not.

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

0 comments on commit 3eab10c

Please sign in to comment.