Skip to content

Commit

Permalink
moved sections around
Browse files Browse the repository at this point in the history
  • Loading branch information
@filippoweb3
filippoweb3 committed Nov 20, 2023
1 parent d3ed82f commit fd896df
Show file tree
Hide file tree
Showing 3 changed files with 136 additions and 146 deletions.
154 changes: 129 additions & 25 deletions docs/learn/learn-guides-identity.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,41 +13,111 @@ This is an advanced guide that is relevant for entities that would like to becom
would like to set sub-identities to an existing account with an identity. See
[this page](./learn-identity.md) to learn about how to set an identity and have it verified.

## Registrars
## Setting an Identity

### Becoming a Registrar
Users can set an identity by registering through default fields such as legal name, display name,
website, Twitter handle, Riot handle, etc. along with some extra, custom fields for which they would
like attestations (see [Judgements](#judgements)).

To become a registrar, submit a pre-image and proposal into
[Democracy](../maintain/maintain-guides-democracy.md), then wait for people to vote on it. For best
results, write a post about your identity and intentions beforehand, and once the proposal is in the
queue ask people to endorse it so that it gets ahead in the referendum queue.
:::info Instructions for setting and clearing Identities

Here's how to submit a proposal to become a registrar:
The procedure to set and clear identities is explained in detail in this support article -
[How to set and clear an Identity](https://support.polkadot.network/support/solutions/articles/65000181981-how-to-set-and-clear-an-identity)

Go to the Democracy tab, select "Submit preimage", and input the information for this motion -
notably which account you're nominating to be a registrar in the `identity.setRegistrar` function.
:::

![Setting a registrar](../assets/identity/12.jpg)
:::note

Copy the preimage hash. In the above image, that's
`0x90a1b2f648fc4eaff4f236b9af9ead77c89ecac953225c5fafb069d27b7131b7`. Submit the preimage by signing
a transaction.
The Ledger app on **Nano S** doesn't support the extrinsic for setting identity. As a workaround,
create a primary identity with an on-chain account and then using that primary identity, assign a
[sub-identity](#sub-accounts) to the Ledger stash.

Next, select "Submit Proposal" and enter the previously copied preimage hash. The `locked balance`
field needs to be at least
{{ polkadot: <RPC network="polkadot" path="consts.identity.basicDeposit" defaultValue={202580000000} filter="humanReadable"/>. :polkadot }}
{{ kusama: <RPC network="kusama" path="consts.identity.basicDeposit" defaultValue={33333000000} filter="humanReadable"/>. :kusama }}
You can find out the minimum by querying the chain state under
[Chain State](https://polkadot.js.org/apps/#/chainstate) -> Constants -> democracy ->
minimumDeposit.
:::

![Submitting a proposal](../assets/identity/13.jpg)
### Format Caveat

At this point, DOT holders can endorse the motion. With enough endorsements, the motion will become
a referendum, which is then voted on. If it passes, users will be able to request judgement from
this registrar.
Please note the following caveat: because the fields support different formats, from raw bytes to
various hashes, a UI has no way of telling how to encode a given field it encounters. The
Polkadot-JS UI currently encodes the raw bytes it encounters as UTF8 strings, which makes these
values readable on-screen. However, given that there are no restrictions on the values that can be
placed into these fields, a different UI may interpret them as, for example, IPFS hashes or encoded
bitmaps. This means any field stored as raw bytes will become unreadable by that specific UI. As
field standards crystallize, things will become easier to use but for now, every custom
implementation of displaying user information will likely have to make a conscious decision on the
approach to take, or support multiple formats and then attempt multiple encodings until the output
makes sense.

## Request Judgement

:::info Instructions for requesting and cancelling Identity judgments

The procedure to request and cancel identity judgments is explained in detail in this
[support article](https://support.polkadot.network/support/solutions/articles/65000181990-how-to-request-and-cancel-identity-judgement)

:::

To be judged after submitting your identity information, go to the
[Extrinsics tab in the Polkadot-JS UI](https://polkadot.js.org/apps/#/extrinsics) and select the
`identity` pallet, then `requestJudgement`. For the `reg_index` put the index of the registrar you
want to be judged by, and for the `max_fee` put the maximum you're willing to pay for these
confirmations.

If you don't know which registrar to pick, first check the available registrars by going to
[Chain State tab in the Polkadot-JS UI](https://polkadot.js.org/apps/#/chainstate) and selecting
`identity.registrars()` to get the full list.

To find out how to contact the registrar after the application for judgement or to learn who they
are, you can check their identity by adding them to your Address Book. Their identity will be
automatically loaded.

![Chevdor is registrar #1](../assets/identity/16.jpg)

:::info Requesting judgement through Web3 Foundation Registrar

If you requested judgement for your on-chain identity through the Web3 Foundation Registrar (i.e.
Registrar #0) you will need to complete a few additional tasks. For more information visit
[this support article](https://support.polkadot.network/support/solutions/articles/65000179747-how-to-use-the-w3f-registrar-page).

:::

:::caution

The set identity calls go on-chain. Hence, the contact information is available publicly, for both
legitimate entities, like registrars or validators, but also scammers who might impersonate them.
The strings in the identity fields are good candidates for homograph attacks, as someone could list
a fraudulent website (web3.f0undation instead of web3.foundation for example) and still get verified
by the registrar (if the checks are automated)!

In a decentralized network, one should be cautious making transactions with accounts solely based on
their identity. If an account on-chain claims to be of Web3 Foundation, it is wise to verify its
authenticity by checking directly with Web3 Foundation or examining the established history of that
account on-chain.

:::

## Clearing and Killing an Identity

:::info

## Setting Sub-Identity (Sub-ID) for your Ledger Account
Visit the section "Clear an Identity" on
[this support article](https://support.polkadot.network/support/solutions/articles/65000181981) for
guidelines about clearing identities.

:::

**Clearing:** Users can clear their identity information and have their deposit returned. Clearing
an identity also clears all sub accounts and returns their deposits.

**Killing:** The Council can kill an identity that it deems erroneous. This results in a slash of
the deposit.

## Setting Sub-Identities

To set up sub-identities with Polkadot-JS see the
[how to set sub-identities](https://support.polkadot.network/support/solutions/articles/65000181991-how-to-set-identities-for-sub-accounts)
support article and this [video tutorial](https://www.youtube.com/watch?v=0Yh1JYg3ZKU).

### Setting Sub-Identity (Sub-ID) for your Ledger Account

Setting an Identity is not possible on Ledger app yet, but as a workaround, you can
[set the identity for an on-chain account ](../learn/learn-identity.md#setting-an-identity) and then
Expand All @@ -74,3 +144,37 @@ for each sub-identity. This reserved account balance is freed once you
[clear the identities](../learn/learn-identity.md#clearing-and-killing-an-identity) on the account.

![Sub-identity example](../assets/identity/sub-id-3.png)

## Registrars

### Becoming a Registrar

To become a registrar, submit a pre-image and proposal into
[Democracy](../maintain/maintain-guides-democracy.md), then wait for people to vote on it. For best
results, write a post about your identity and intentions beforehand, and once the proposal is in the
queue ask people to endorse it so that it gets ahead in the referendum queue.

Here's how to submit a proposal to become a registrar:

Go to the Democracy tab, select "Submit preimage", and input the information for this motion -
notably which account you're nominating to be a registrar in the `identity.setRegistrar` function.

![Setting a registrar](../assets/identity/12.jpg)

Copy the preimage hash. In the above image, that's
`0x90a1b2f648fc4eaff4f236b9af9ead77c89ecac953225c5fafb069d27b7131b7`. Submit the preimage by signing
a transaction.

Next, select "Submit Proposal" and enter the previously copied preimage hash. The `locked balance`
field needs to be at least
{{ polkadot: <RPC network="polkadot" path="consts.identity.basicDeposit" defaultValue={202580000000} filter="humanReadable"/>. :polkadot }}
{{ kusama: <RPC network="kusama" path="consts.identity.basicDeposit" defaultValue={33333000000} filter="humanReadable"/>. :kusama }}
You can find out the minimum by querying the chain state under
[Chain State](https://polkadot.js.org/apps/#/chainstate) -> Constants -> democracy ->
minimumDeposit.

![Submitting a proposal](../assets/identity/13.jpg)

At this point, DOT holders can endorse the motion. With enough endorsements, the motion will become
a referendum, which is then voted on. If it passes, users will be able to request judgement from
this registrar.
120 changes: 3 additions & 117 deletions docs/learn/learn-identity.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,12 +13,6 @@ import RPC from "./../../components/RPC-Connection";
participants to add personal information to their on-chain account and subsequently ask for
verification of this information by [registrars](#registrars).

## Setting an Identity

Users can set an identity by registering through default fields such as legal name, display name,
website, Twitter handle, Riot handle, etc. along with some extra, custom fields for which they would
like attestations (see [Judgements](#judgements)).

Users must reserve funds in a bond to store their information on chain:
{{ polkadot: <RPC network="polkadot" path="consts.identity.basicDeposit" defaultValue={202580000000} filter="humanReadable"/> :polkadot }}
{{ kusama: <RPC network="kusama" path="consts.identity.basicDeposit" defaultValue={33333000000} filter="humanReadable"/> :kusama }}
Expand All @@ -28,38 +22,6 @@ and
per each field beyond the legal name. These funds are _locked_, not spent - they are returned when
the identity is cleared.

These amounts can also be extracted by querying constants through the
[Chain state constants](https://polkadot.js.org/apps/#/chainstate/constants) tab on Polkadot-JS
Apps.

:::info Instructions for setting and clearing Identities

The procedure to set and clear identities is explained in detail in this support article -
[How to set and clear an Identity](https://support.polkadot.network/support/solutions/articles/65000181981-how-to-set-and-clear-an-identity)

:::

:::note

The Ledger app on **Nano S** doesn't support the extrinsic for setting identity. As a workaround,
create a primary identity with an on-chain account and then using that primary identity, assign a
[sub-identity](#sub-accounts) to the Ledger stash.

:::

### Format Caveat

Please note the following caveat: because the fields support different formats, from raw bytes to
various hashes, a UI has no way of telling how to encode a given field it encounters. The
Polkadot-JS UI currently encodes the raw bytes it encounters as UTF8 strings, which makes these
values readable on-screen. However, given that there are no restrictions on the values that can be
placed into these fields, a different UI may interpret them as, for example, IPFS hashes or encoded
bitmaps. This means any field stored as raw bytes will become unreadable by that specific UI. As
field standards crystallize, things will become easier to use but for now, every custom
implementation of displaying user information will likely have to make a conscious decision on the
approach to take, or support multiple formats and then attempt multiple encodings until the output
makes sense.

## Judgements

After a user injects their information on chain, they can request judgement from a registrar. Users
Expand All @@ -86,45 +48,6 @@ removed by the complete removal of the identity.
Registrars gain trust by performing proper due diligence and would presumably be replaced for
issuing faulty judgments.

To be judged after submitting your identity information, go to the
[Extrinsics tab in the Polkadot-JS UI](https://polkadot.js.org/apps/#/extrinsics) and select the
`identity` pallet, then `requestJudgement`. For the `reg_index` put the index of the registrar you
want to be judged by, and for the `max_fee` put the maximum you're willing to pay for these
confirmations.

If you don't know which registrar to pick, first check the available registrars by going to
[Chain State tab in the Polkadot-JS UI](https://polkadot.js.org/apps/#/chainstate) and selecting
`identity.registrars()` to get the full list.

:::info Instructions for requesting and cancelling Identity judgments

The procedure to request and cancel identity judgments is explained in detail in this
[support article](https://support.polkadot.network/support/solutions/articles/65000181990-how-to-request-and-cancel-identity-judgement)

:::

:::info Requesting judgement through Web3 Foundation Registrar If you requested judgement for your
on-chain identity through the Web3 Foundation Registrar (i.e. Registrar #0) you will need to
complete a few additional tasks. For more information visit
[this support article](https://support.polkadot.network/support/solutions/articles/65000179747-how-to-use-the-w3f-registrar-page).

:::

:::caution

The set identity calls go on-chain. Hence, the contact information is available publicly, for both
legitimate entities, like registrars or validators, but also scammers who might impersonate them.
The strings in the identity fields are good candidates for homograph attacks, as someone could list
a fraudulent website (web3.f0undation instead of web3.foundation for example) and still get verified
by the registrar (if the checks are automated)!

In a decentralized network, one should be cautious making transactions with accounts solely based on
their identity. If an account on-chain claims to be of Web3 Foundation, it is wise to verify its
authenticity by checking directly with Web3 Foundation or examining the established history of that
account on-chain.

:::

## Registrars

Registrars can set a fee for their services and limit their attestation to certain fields. For
Expand All @@ -133,26 +56,10 @@ verify one's legal name, email, and GPG key. When a user requests judgement, the
to the registrar who provides the judgement on those claims. Users set a maximum fee they are
willing to pay and only registrars below this amount would provide judgement.

### Becoming a Registrar

:::info Advanced How-to Guides

See [this page](./learn-guides-identity.md#registrars) to learn how to become a Registrar.

:::

### Current Registrars

There are multiple registrars on {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}.
Unless no additional information is available here, you must reach out to specific registrars
individually if you want to be judged by those.

To find out how to contact the registrar after the application for judgement or to learn who they
are, you can check their identity by adding them to your Address Book. Their identity will be
automatically loaded.

![Chevdor is registrar #1](../assets/identity/16.jpg)

Registrar 0: <br /> **URL**: https://registrar.web3.foundation/ <br /> **Account**:
{{ polkadot: 12j3Cz8qskCGJxmSJpVL2z2t3Fpmw3KoBaBaRGPnuibFc7o8 :polkadot }}
{{ kusama: H4XieK3r3dq3VEvRtqZR7wN7a1UEkXxf14orRsEfdFjmgkF :kusama }} <br /> **Fee**:
Expand All @@ -177,7 +84,9 @@ Registrar 3: <br /> **Account**:

{{ polkadot: Polkassembly (Registrar 3) provides setting on-chain ID as a service on their [website](https://polkadot.polkassembly.io/). :polkadot }}

## Sub Accounts
See [this page](./learn-guides-identity.md#registrars) to learn how to become a Registrar.

## Sub-Identities

Users can also link accounts by setting "sub accounts", each with its own identity, under a primary
account. The system reserves a bond for each sub account. An example of how you might use this would
Expand All @@ -189,26 +98,3 @@ An account can have a maximum of 100 sub-accounts. Note that a deposit of
{{ polkadot: <RPC network="polkadot" path="consts.identity.subAccountDeposit" defaultValue={200530000000} filter="humanReadable"/> :polkadot }}
{{ kusama: <RPC network="kusama" path="consts.identity.subAccountDeposit" defaultValue={6666000000} filter="humanReadable"/> :kusama }}
is required for every sub-account.

:::info Explainer article and video on setting sub-identities

Here is the
[how to set sub-identities](https://support.polkadot.network/support/solutions/articles/65000181991-how-to-set-identities-for-sub-accounts)
article and a [video tutorial](https://www.youtube.com/watch?v=0Yh1JYg3ZKU) on setting
sub-identities using Polkadot-JS UI

:::

## Clearing and Killing an Identity

**Clearing:** Users can clear their identity information and have their deposit returned. Clearing
an identity also clears all sub accounts and returns their deposits.

:::info Visit the section "Clear an Identity" on
[this support article](https://support.polkadot.network/support/solutions/articles/65000181981) for
guidelines about clearing identities.

:::

**Killing:** The Council can kill an identity that it deems erroneous. This results in a slash of
the deposit.
8 changes: 4 additions & 4 deletions docs/learn/learn-proxies-pure.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ non-deterministic accounts** as they do not have a private key but they have an
randomly generated. Also, in some sense, nobody owns a pure proxy as nobody has a private key to
control them.

:::info Pure proxies where called anonymous proxies
:::info Pure proxies were called anonymous proxies

Pure proxies are not anonymous because they have an address that is spawned by a primary account
acting as _any_ proxy. Even if the _any_ proxy changes, it is still possible to find who generated
Expand Down Expand Up @@ -66,12 +66,12 @@ _pure_ proxies cannot sign for anything.

Pure proxies have important benefits that we discuss below:

- **Enhanced Security**: _Pure_ proxies cannot be stolen because they do not have private keys. The
- **Enhanced Security**: Pure proxies cannot be stolen because they do not have private keys. The
only accounts that have full access to the _pure_ proxies are _any_ proxies. Security can be
further increased if the _any_ proxy is a multi-signature account.
- **Simplified and Secure Account Management**:_pure_ proxies can simplify the management of complex
- **Simplified and Secure Account Management**: Pure proxies can simplify the management of complex
account relationships at a corporate level.
- **Multi-signature Account Management**: _Pure_ proxies are useful to efficiently manage
- **Multi-signature Account Management**: Pure proxies are useful to efficiently manage
multi-signature (multisig) accounts. In fact, multi-signature accounts are deterministic, which
means that once a multisig is created the signatories cannot be changed. If one of the signatories
wants to leave the multisig, a new multisig must be created. This is inconvenient, especially at
Expand Down

0 comments on commit fd896df

Please sign in to comment.