diff --git a/docs/general/chain-state-values.md b/docs/general/chain-state-values.md index ef66cdc4efbe..efad3cfa86a3 100644 --- a/docs/general/chain-state-values.md +++ b/docs/general/chain-state-values.md @@ -192,6 +192,13 @@ The **signed reward base** on Polkadot is . +#### Staking Reward Retention + +Polkadot staking rewards are kept available for 84 eras. The following calculation can be used to +approximate this length in days: + +`84 eras` × `24 hours in a single era` ÷ `24 hours in a day` = `84 days` + #### Total Issuance Polkadot's total issuance is in the era . @@ -206,7 +213,9 @@ The spending period on Polkadot is currently days. +The unbonding duration on Polkadot is set to days. This is +calculated by taking the **bonding duration** (in eras), multiplying it by the **length of a single +era** (in hours), and dividing by the **hours in a day** (24). Example: 28 × 24 ÷ 24 = 28 days. @@ -376,13 +385,20 @@ The **signed reward base** on Kusama is . +#### Staking Reward Retention + +Kusama staking rewards are kept available for 84 eras. The following calculation can be used to +approximate this length in days: + +`84 eras` × `6 hours in a single era` ÷ `24 hours in a day` = `21 days` + #### Total Issuance Kusama's total issuance is in the era . #### Treasury Burn Factor -At the end of every spending period on Kusama, % of the available funds are burned. +At the end of every spending period on Kusama, % of the available funds are burned, with the amount currently going to [Society](../maintain/kusama/maintain-guides-society-kusama.md) rather than being burned. #### Treasury Spending Period @@ -390,7 +406,9 @@ The spending period on Kusama is currently days. +The unbonding duration on Kusama is set to days. This is +calculated by taking the **bonding duration** (in eras), multiplying it by the **length of a single +era** (in hours), and dividing by the **hours in a day** (24). Example: 28 × 6 ÷ 24 = 7 days. diff --git a/docs/general/community.md b/docs/general/community.md index 46925658f4e7..a67624da0195 100644 --- a/docs/general/community.md +++ b/docs/general/community.md @@ -35,12 +35,14 @@ contact and anyone doing so is likely trying to scam you.
  • Polkadot's Latest Research (news)
  • Polkadot Meetup Hub - Information on hosting meetups, applying for funding, and materials for running it.
  • Polkadot Discussion and Governance on Polkassembly
    • +
  • Polkadot Discussion and Governance on Subsquare
    •  diff --git a/docs/learn/archive/learn-governance.md b/docs/learn/archive/learn-governance.md index cd66922367b3..5920b9dd3645 100644 --- a/docs/learn/archive/learn-governance.md +++ b/docs/learn/archive/learn-governance.md @@ -13,17 +13,15 @@ import MessageBox from "../../../components/MessageBox"; import -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} uses a sophisticated governance -mechanism that allows it to evolve gracefully overtime at the ultimate behest of its assembled -stakeholders. The stated goal is to ensure that the majority of the stake can always command the -network. - -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} brings together various novel -mechanisms, including an amorphous (abstract) form of state-transition function stored on-chain -defined in a platform-agnostic language (i.e. [WebAssembly](../learn-wasm.md)). It also allows for -several on-chain voting mechanisms, such as referenda with the novel concept of -[Adaptive Quorum Biasing](#adaptive-quorum-biasing) and batch approval voting. All changes to the -protocol must be agreed upon by stake-weighted referenda. +Polkadot uses a sophisticated governance mechanism that allows it to evolve gracefully overtime at +the ultimate behest of its assembled stakeholders. The stated goal is to ensure that the majority of +the stake can always command the network. + +Polkadot brings together various novel mechanisms, including an amorphous (abstract) form of +state-transition function stored on-chain defined in a platform-agnostic language (i.e. +[WebAssembly](../learn-wasm.md)). It also allows for several on-chain voting mechanisms, such as +referenda with the novel concept of [Adaptive Quorum Biasing](#adaptive-quorum-biasing) and batch +approval voting. All changes to the protocol must be agreed upon by stake-weighted referenda. To make any changes to the network, the idea is to compose active token holders and the council together to administrate a network upgrade decision. No matter whether the proposal is proposed by @@ -122,10 +120,10 @@ hash cannot re-appear in the proposal queue. Blacklisting is useful when removin proposals that could be submitted with the same hash. Upon seeing their proposal removed, a submitter who is not properly introduced to the democracy -system of {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} might be tempted to -re-submit the same proposal. That said, this is far from a fool-proof method of preventing invalid -proposals from being submitted - a single changed character in a proposal's text will also change -the hash of the proposal, rendering the per-hash blacklist invalid. +system of Polkadot might be tempted to re-submit the same proposal. That said, this is far from a +fool-proof method of preventing invalid proposals from being submitted - a single changed character +in a proposal's text will also change the hash of the proposal, rendering the per-hash blacklist +invalid. ## Referenda @@ -160,12 +158,11 @@ unless they are the only ones in the pipeline. In (2), the proposal is selected for a referendum. Proposals initiated by the public will become a [public referendum](#public-referenda), while those initiated by the council will become -[council referenda](#council-referenda). The voting period lasts -{{ polkadot: 28 days :polkadot }}{{ kusama: 7 days :kusama }}, after which, if the proposal is -approved, it will go through an enactment period. Rejected proposals will need to start from (1). -Note that Governance V1 uses an [alternating voting timeline](#alternating-voting-timetable) where -voters can vote either for a public proposal or a council motion every -{{ polkadot: 28 days :polkadot }}{{ kusama: 7 days :kusama }}. +[council referenda](#council-referenda). The voting period lasts 28 days (7 days on Kusama), after +which, if the proposal is approved, it will go through an enactment period. Rejected proposals will +need to start from (1). Note that Governance V1 uses an +[alternating voting timeline](#alternating-voting-timetable) where voters can vote either for a +public proposal or a council motion every 28 days (7 days on Kusama). In (3), the proposal is approved and moves through the [enactment period](#enactment) that can be of different lengths depending on who initiated the proposal in the first place, with emergency @@ -179,8 +176,7 @@ they will require a heavy supermajority of _aye_ votes to pass at low turnouts b increases towards 100%, it will require a simple majority of _aye_ votes to pass (i.e. 51% wins). Note that the bonded tokens will be released once the proposal is tabled (that is, brought to a -vote), and a maximum of {{ polkadot: 100 :polkadot }} {{ kusama: 100 :kusama }} public proposals can -be in the proposal queue. +vote), and a maximum of 100 public proposals can be in the proposal queue. :::info turnout @@ -216,18 +212,17 @@ in the same period, excluding emergency referenda. An emergency referendum occur time as a regular referendum (either public- or council-proposed) is the only time multiple referenda can be voted on. -Every {{ polkadot: 28 :polkadot }} {{ kusama: 7 :kusama }} days, a new referendum will come up for a -vote, assuming there is at least one proposal in one of the queues. There is a queue for -Council-approved proposals and a queue for publicly-submitted proposals. The referendum to be voted -upon alternates between the top proposal in the two queues, where the proposals' rank is based on +Every 28 days (7 days on Kusama), a new referendum will come up for a vote, assuming there is at +least one proposal in one of the queues. There is a queue for Council-approved proposals and a queue +for publicly-submitted proposals. The referendum to be voted upon alternates between the top +proposal in the two queues, where the proposals' rank is based on [endorsement](#endorsing-proposals) (i.e. bonded tokens). ### Adaptive Quorum Biasing -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} introduces the concept of **Adaptive -Quorum Biasing**, which is used to alter the effective super-majority required to make it easier or -more difficult for a proposal to pass depending on voting power (turnout) and origin (Council or -public). +Polkadot introduces the concept of **Adaptive Quorum Biasing**, which is used to alter the effective +super-majority required to make it easier or more difficult for a proposal to pass depending on +voting power (turnout) and origin (Council or public). Adaptive Quorum Biasing creates three tallying mechanisms: majority carry, super-majority approve, and super-majority against. They all equate to a simple majority-carry system at 100% turnout. Their @@ -278,28 +273,24 @@ To know more about where these above formulas come from, please read the #### Example of Adaptive Quorum Biasing -Let's assume we only have {{ polkadot: 1,500 DOT :polkadot }}{{ kusama: 1_50 :kusama }} tokens in -total and that this is a public proposal. +Let's assume we only have 1,500 DOT tokens in total and that this is a public proposal. -- John: {{ polkadot: 500 DOT :polkadot }}{{ kusama: 50 KSM :kusama }} -- Peter: {{ polkadot: 100 DOT :polkadot }}{{ kusama: 10 KSM :kusama }} -- Lilly: {{ polkadot: 150 DOT :polkadot }}{{ kusama: 15 KSM :kusama }} -- JJ: {{ polkadot: 150 DOT :polkadot }}{{ kusama: 15 KSM :kusama }} -- Ken: {{ polkadot: 600 DOT :polkadot }}{{ kusama: 60 KSM :kusama }} +- John: 500 DOT +- Peter: 100 DOT +- Lilly: 150 DOT +- JJ: 150 DOT +- Ken: 600 DOT -John: Votes `Yes` for a 4 week lock period => -{{ polkadot: 500 x 1 = 500 Votes :polkadot }}{{ kusama: 50 x 1 = 50 Votes :kusama }} +John: Votes `Yes` for a 4 week lock period => 500 x 1 = 500 Votes -Peter: Votes `Yes` for a 4 week lock period => -{{ polkadot: 100 x 1 = 100 Votes :polkadot }}{{ kusama: 10 x 1 = 10 Votes :kusama }} +Peter: Votes `Yes` for a 4 week lock period => 100 x 1 = 100 Votes -JJ: Votes `No` for a 16 week lock period => -{{ polkadot: 150 x 3 = 450 Votes :polkadot }}{{ kusama: 150 x 3 = 450 Votes :kusama }} +JJ: Votes `No` for a 16 week lock period => 150 x 3 = 450 Votes -- approve = {{ polkadot: 600 :polkadot }}{{ kusama: 60 :kusama }} -- against = {{ polkadot: 450 :polkadot }}{{ kusama: 45 :kusama }} -- turnout = {{ polkadot: 750 :polkadot }}{{ kusama: 75 :kusama }} -- electorate = {{ polkadot: 1500 :polkadot }}{{ kusama: 150 :kusama }} +- approve = 600 Votes +- against = 450 Votes +- turnout = 750 Votes +- electorate = 1500 Votes ![\Large \frac{450}{\sqrt{750}}&space;<&space;\frac{600}{\sqrt{1500}}](https://latex.codecogs.com/svg.latex?\large&space;\frac{450}{\sqrt{750}}&space;<&space;\frac{600}{\sqrt{1500}}) @@ -326,10 +317,10 @@ outcome, i.e. being voted on. All referenda are associated with an enactment delay or **enactment period**. This is the period between a referendum ending and (assuming it was approved) the changes being enacted. -For public and Council referenda, the enactment period is a fixed time of -{{ polkadot: 28 days :polkadot }}{{ kusama: 8 days :kusama }}. For proposals submitted as part of -the enactment of a prior referendum, it can be set as desired. Emergency proposals deal with major -problems with the network and need to be "fast-tracked". These will have a shorter enactment period. +For public and Council referenda, the enactment period is a fixed time of 28 days (8 days on +Kusama). For proposals submitted as part of the enactment of a prior referendum, it can be set as +desired. Emergency proposals deal with major problems with the network and need to be +"fast-tracked". These will have a shorter enactment period. ## Voting on a Referendum @@ -360,7 +351,7 @@ For more information about voluntary locking or conviction voting see ### Delegations -In {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} you can +In Polkadot, you can [delegate your voting power](../../maintain/archive/maintain-guides-democracy.md#delegate-a-vote) to another account you trust if you are not willing to stay up-to-date with all referenda. @@ -370,11 +361,9 @@ vote with your stash. Learn more from the [dedicated page on Proxy Accounts](../ ## Council -To represent passive stakeholders, {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} -introduces the idea of a "council". The council is an on-chain entity comprising several actors, -each represented as an on-chain account. On -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}, the council currently consists of -{{ polkadot: 13 :polkadot }} {{ kusama: 19 :kusama }} members. +To represent passive stakeholders, Polkadot introduces the idea of a "council". The council is an +on-chain entity comprising several actors, each represented as an on-chain account. The Polkadot +council consists of 13 members (19 on Kusama). Along with [controlling the treasury](./learn-treasury.md), the council is called upon primarily for three tasks of governance: @@ -419,9 +408,9 @@ prime. The Technical Committee(TC) was introduced in the [Kusama rollout and governance post](https://polkadot.network/kusama-rollout-and-governance/) as one of the three chambers of Kusama governance (along with the Council and the Referendum chamber). The -TC is composed of the teams that have successfully implemented or specified either a -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} runtime or Polkadot Host. Teams are -added or removed from the TC via a simple majority vote of the [Council](#council). +TC is composed of the teams that have successfully implemented or specified either a Polkadot +runtime or Polkadot Host. Teams are added or removed from the TC via a simple majority vote of the +[Council](#council). The TC aims to safeguard against malicious referenda, implement bug fixes, reverse faulty runtime updates, or add new but battle-tested features. The TC can fast-track proposals using the Democracy @@ -443,13 +432,12 @@ All stakeholders can signal their approval of any of the registered candidates. Council elections are handled by the same [Phragmén election](../learn-phragmen.md) process that selects validators from the available pool based on nominations. However, token holders' votes for councilors are isolated from any nominations they may have on validators. Council terms last for one -{{ kusama: day :kusama }}{{ polkadot: week :polkadot }}. +week on Polkadot and one day day on Kusama. At the end of each term, [Phragmén election algorithm](../learn-phragmen#algorithm) runs and the result will choose the new councilors based on the vote configurations of all voters. The election -also chooses a set number of runners-up, which is currently -{{ kusama: 12 :kusama }}{{ polkadot: 20 :polkadot }} that will remain in the queue with their votes -intact. +also chooses a set number of runners-up, which is 20 on Polkadot (12 on Kusama), that will remain in +the queue with their votes intact. As opposed to a "first-past-the-post" electoral system, where voters can only vote for a single candidate from a list, a Phragmén election is a more expressive way to include each voter’s views. @@ -496,13 +484,11 @@ let you sign a message easily. When these circumstances can be proven beyond a r be an error, the council _may_ consider a governance motion to correct it. The first step to appeal to the council is to contact the councilors. There is no singular place -where you are guaranteed to grab every councilor’s ear with your message. However, there are a -handful of good places to start where you can get the attention of some of them. The -{{ polkadot: [Polkadot Direction](https://matrix.to/#/#Polkadot-Direction:parity.io) :polkadot }} -{{ kusama: [Kusama Direction](https://matrix.to/#/#Kusama-Direction:parity.io) :kusama }} matrix -room is one such place. After creating an account and joining this room, you can post a -well-thought-through message here that lays down your case and justifies why you think the council -should consider enacting a change to the protocol on your behalf. +where you are guaranteed to grab every councilor’s ear with your message. However, there are +[a handful of good places](../../general/community.md) to start where you can get the attention of +some of them. After creating an account and joining this room, you can post a well-thought-through +message here that lays down your case and justifies why you think the council should consider +enacting a change to the protocol on your behalf. At some point, you will likely need a place for a longer-form discussion. For this, making a post on [Polkassembly](https://polkadot.polkassembly.io/) is the recommended place to do so. When you write diff --git a/docs/learn/archive/learn-treasury.md b/docs/learn/archive/learn-treasury.md index 1625469a8925..c131cbeacf40 100644 --- a/docs/learn/archive/learn-treasury.md +++ b/docs/learn/archive/learn-treasury.md @@ -20,22 +20,19 @@ The Treasury is a pot of funds collected through a portion of block production r The Treasury funds are held in a [system account](../learn-account-advanced.md#system-accounts) not accessible by anyone; only the system internal logic can access it. Funds can be spent by making a spending proposal that, if approved by the [Council](learn-governance.md#council), will enter a -waiting period before distribution. This waiting period is known as the _spend period_, and its -duration is subject to [governance](learn-governance.md), with the current default set to -{{ polkadot: 28 :polkadot }} {{ kusama: 6 :kusama }} days. The Treasury attempts to spend as many -proposals in the queue as it can without running out of funds. +waiting period before distribution. This waiting period is known as the +[_spend period_](../../general/chain-state-values.md#treasury-spending-period), and its duration is +subject to [governance](learn-governance.md). The Treasury attempts to spend as many proposals in +the queue as it can without running out of funds. Treasury payout is an automatic process: - If the Treasury funds run out with approved proposals left to fund, those proposals are kept in the approved queue, and will receive funding in the following spend period. -- If the Treasury ends a spend period without spending all of its funds, it suffers a burn of a - percentage of its funds - thereby causing deflationary pressure. This encourages the spending of - the funds in the Treasury by Polkadot's governance system. - {{ polkadot: This percentage is currently at 1% on Polkadot. :polkadot }} - {{ kusama: This percentage is currently 0.2% on Kusama, with the amount currently - going to [Society](https://guide.kusama.network/docs/maintain-guides-society-kusama) rather than being - burned. :kusama }} +- If the Treasury ends a spend period without spending all of its funds, it suffers a burn of + [a percentage of its funds](../../general/chain-state-values.md#treasury-burn-factor) - thereby + causing deflationary pressure. This encourages the spending of the funds in the Treasury by + Polkadot's governance system. When a stakeholder wishes to propose a spend from the Treasury, they must reserve a deposit of at least 5% of the proposed spend (see below for variations). This deposit will be slashed if the @@ -84,9 +81,8 @@ be paid out. There are two types of tips: - public: A small bond is required to place them. This bond depends on the tip message length, and a - fixed bond constant defined on chain, currently {{ polkadot: 1 DOT. :polkadot }} - {{ kusama: 0.166 KSM. :kusama }} Public tips carry a finder's fee of - {{ polkadot: 20%, :polkadot }} {{ kusama: 20%, :kusama }} which is paid out from the total amount. + fixed bond constant defined on chain, currently 1 DOT (0.166 KSM on Kusama). Public tips carry a + finder's fee of 20% (same on Polkadot and Kusama) which is paid out from the total amount. - tipper-initiated: Tips that a Council member published, do not have a finder's fee or a bond. :::info @@ -101,15 +97,13 @@ below. ### Example -Bob has done something great for {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}. -Alice has noticed this and decides to report Bob as deserving a tip from the Treasury. The Council -is composed of three members Charlie, Dave, and Eve. +Bob has done something great for Polkadot. Alice has noticed this and decides to report Bob as +deserving a tip from the Treasury. The Council is composed of three members Charlie, Dave, and Eve. Alice begins the process by issuing the `report_awesome` extrinsic. This extrinsic requires two arguments, a reason and the beneficiary. Alice submits Bob's address with the reason being a UTF-8 -encoded URL to a post on {{ polkadot: [Polkassembly](https://polkadot.polkassembly.io) :polkadot }} -{{ kusama: [Polkassembly](https://kusama.polkassembly.io) :kusama }} that explains her reasoning for -why Bob deserves the tip. +encoded URL to a post on [Polkassembly](https://polkadot.polkassembly.io) that explains her +reasoning for why Bob deserves the tip. As mentioned above, Alice must also lock up a deposit for making this report. The deposit is the base deposit as set in the chain's parameter list, plus the additional deposit per byte contained in @@ -120,20 +114,16 @@ the tip is approved by the tippers. Since the tipper group is the same as the Council, the Council must now collectively (but also independently) decide on the value of the tip that Bob deserves. Charlie, Dave, and Eve all review the report and make tips according to their personal valuation of the benefit Bob has provided to -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}. Charlie tips -{{ polkadot: 10 DOT :polkadot }}{{ kusama: 1 KSM :kusama }}, Dave tips -{{ polkadot: 30 DOT :polkadot }}{{ kusama: 3 KSM :kusama }}, and Eve tips -{{ polkadot: 100 DOT :polkadot }}{{ kusama: 10 KSM :kusama }}. +the network. Charlie tips 10 DOT, Dave tips 30 DOT, and Eve tips 100 DOT. The tip could have been closed out with only two of the three tippers. Once more than half of the tippers group have issued tip valuations, the countdown to close the tip will begin. In this case, the third tipper issued their tip before the end of the closing period, so all three were able to make their tip valuations known. -The actual tip that will be paid out to Bob is the median of these tips, so Bob will be paid out -{{ polkadot: 30 DOT :polkadot }}{{ kusama: 3 KSM :kusama }} from the Treasury. In order for Bob to -be paid his tip, some account must call the `close_tip` extrinsic at the end of the closing period -for the tip. This extrinsic may be called by anyone. +The actual tip that will be paid out to Bob is the median of these tips, so Bob will be paid out 30 +DOT from the Treasury. In order for Bob to be paid his tip, some account must call the `close_tip` +extrinsic at the end of the closing period for the tip. This extrinsic may be called by anyone. ## Bounties Spending @@ -145,8 +135,7 @@ highly unlikely that a majority of members are capable in such diverse topics. Bounties Spending proposals aim to delegate the curation activity of spending proposals to experts called Curators: They can be defined as addresses with agency over a portion of the Treasury with the goal of fixing a bug or vulnerability, developing a strategy, or monitoring a set of tasks -related to a specific topic: all for the benefit of the -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} ecosystem. +related to a specific topic: all for the benefit of the Polkadot ecosystem. A proposer can submit a bounty proposal for the Council to pass, with a curator to be defined later, whose background and expertise is such that they are capable of determining when the task is @@ -198,13 +187,9 @@ button '+ Add Bounty' on the upper-right side of the interface. Complete the bou requested allocation (including curator's fee) and confirm the call. After this, a Council member will need to assist you to pass the bounty proposal for vote as a -motion. You can contact the Council by joining the -{{ polkadot: Polkadot Direction [channel](https://matrix.to/#/#Polkadot-Direction:parity.io) :polkadot }} -{{ kusama: Kusama Direction [channel](https://matrix.to/#/#Kusama-Direction:parity.io) :kusama }} in -Element or joining our -{{ polkadot: Polkadot Discord [server](https://parity.link/polkadot-discord) :polkadot }} -{{ kusama: Kusama Discord [server](https://parity.link/kusama-discord) :kusama }} and publishing a -short description of your bounty, with a link to one of the [forums](#announcing-the-proposal) for +motion. You can contact the Council by joining the main +[Direction Element Channel and Discord server](../../general/community.md) and publishing a short +description of your bounty, with a link to one of the [forums](#announcing-the-proposal) for contextual information. A bounty can be cancelled by deleting the earmark for a specific treasury amount or be closed if the diff --git a/docs/learn/learn-account-advanced.md b/docs/learn/learn-account-advanced.md index af55b76d94b7..c046daccaa16 100644 --- a/docs/learn/learn-account-advanced.md +++ b/docs/learn/learn-account-advanced.md @@ -7,6 +7,8 @@ keywords: [account, polkadot account, polkadotjs, indices, identity, reaping, EN slug: ../learn-account-advanced --- +import Tabs from "@theme/Tabs"; import TabItem from "@theme/TabItem"; + ## Address Format The address format used in Substrate-based chains is SS58. SS58 is a modification of Base-58-check @@ -375,16 +377,26 @@ private key being unknown (and unattainable). So, that means that only the palle interact with this account. These accounts can never issue a signed [extrinsic](./learn-transactions.md) since they do not have a private key. -:::info Explore System Accounts +Explore the main system accounts below. + + + + + + +Treasury account address - `13UVJyLnbVp9RBZYFwFGyDvVd1y27Tt8tkntv6Q7JVPhFsTB` -Treasury account address - -{{ polkadot: `13UVJyLnbVp9RBZYFwFGyDvVd1y27Tt8tkntv6Q7JVPhFsTB` :polkadot }}{{ kusama: `F3opxRbN5ZbjJNU511Kj2TLuzFcDq9BGduA9TgiECafpg29` :kusama }} + + + +Treasury account address - `F3opxRbN5ZbjJNU511Kj2TLuzFcDq9BGduA9TgiECafpg29` + + + You can view the existing system accounts on [Subscan](https://polkadot.subscan.io/account_list?role=module). -::: - Let us take a look at how system accounts are generated under the hood. For instance, to generate the treasury account, the raw bytes of the strings "modl" and "py/trsry" are combined to create the `AccountID`. For more information, check the post on Substrate StackExchange on @@ -395,10 +407,9 @@ nomination pool and parachain accounts as well. ## Indices -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} addresses can have indices. An index -is like a short and easy-to-remember version of an address. Claiming an index requires -[a deposit](../general/chain-state-values.md#index-deposit) released when the index is cleared. Any -index can be claimed if it is not taken by someone else. +Polkadot addresses can have indices. An index is like a short and easy-to-remember version of an +address. Claiming an index requires [a deposit](../general/chain-state-values.md#index-deposit) +released when the index is cleared. Any index can be claimed if it is not taken by someone else. But what if an account gets reaped, as explained above? In that case, the index is emptied. In other words, the slot frees up again, making it available for anyone to claim. It is possible to _freeze_ diff --git a/docs/learn/learn-architecture.md b/docs/learn/learn-architecture.md index bbe2906f28e1..2d9e90697bd3 100644 --- a/docs/learn/learn-architecture.md +++ b/docs/learn/learn-architecture.md @@ -53,8 +53,7 @@ shared state between the relay chain and all of the connected parachains. If the revert for any reason, then all of the parachains would also revert. This is to ensure that the validity of the entire system can persist and no individual part is corruptible. -The shared state ensures that the trust assumptions when using -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} parachains are only those of the +The shared state ensures that the trust assumptions when using parachains are only those of the relay chain validator set and no other. Since the validator set on the relay chain is expected to be secure with a large amount of stake put up to back it, parachains should benefit from this security. @@ -73,14 +72,13 @@ reading the [specification](https://github.com/paritytech/xcm-format). A blockchain [bridge](../general/glossary.md#bridge) is a connection that allows for arbitrary data to transfer from one network to another. These chains are interoperable through the bridge but can -exist as standalone chains with different protocols, rules, and governance models. In -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}, bridges connect to the relay chain -and are secured through the {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} consensus -mechanism, maintained by [collators](#collators). - -Polkadot uses bridges to bridge the future of Web 3.0, as bridges are fundamental to -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}'s interoperable architecture by -acting as a [secure and robust] communication channel for chains in isolation. +exist as standalone chains with different protocols, rules, and governance models. In Polkadot, +bridges connect to the relay chain and are secured through the consensus mechanism, maintained by +[collators](#collators). + +Polkadot uses bridges to bridge the future of Web 3.0, as bridges are fundamental to Polkadot's +interoperable architecture by acting as a secure and robust communication channel for chains in +isolation. # Main Actors diff --git a/docs/learn/learn-asset-conversion-assethub.md b/docs/learn/learn-asset-conversion-assethub.md index bf3554f8d264..9ceff79e9500 100644 --- a/docs/learn/learn-asset-conversion-assethub.md +++ b/docs/learn/learn-asset-conversion-assethub.md @@ -16,20 +16,19 @@ tokens in a liquidity pool, unlike traditional exchanges that use an order book. :::note -The asset pairs of the liquidity pools of AssetHub will always contain -{{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} as one of the assets. Provision of liquidity -for pools with arbitrary asset pairs is not allowed. +The asset pairs of the liquidity pools of AssetHub will always contain the relay chain's native +token as one of the assets. Provision of liquidity for pools with arbitrary asset pairs is not +allowed. ::: Asset Conversion on Asset Hub enables fee payment in any asset, given it has a liquidity pool, such -that the fee handler (in this case, a Collator) only receives the native asset -({{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} ). +that the fee handler (in this case, a Collator) only receives the native asset. Asset Conversion pallet allows you to: - [Create a liquidity pool](https://docs.rs/pallet-asset-conversion/latest/pallet_asset_conversion/pallet/struct.Pallet.html#method.create_pool) - with {{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} and an asset + with the relay chain's native token and an asset - [Provide the liquidity](https://docs.rs/pallet-asset-conversion/latest/pallet_asset_conversion/pallet/struct.Pallet.html#method.add_liquidity) and receive back an LP token - [Exchange the LP token back to assets](https://docs.rs/pallet-asset-conversion/latest/pallet_asset_conversion/pallet/struct.Pallet.html#method.remove_liquidity) diff --git a/docs/learn/learn-assets.md b/docs/learn/learn-assets.md index 2b64f2b02a26..904ab2c57586 100644 --- a/docs/learn/learn-assets.md +++ b/docs/learn/learn-assets.md @@ -7,26 +7,24 @@ keywords: [assets, fungible, non-fungible, asset hub, statemine, statemint] slug: ../learn-assets --- -Assets in the {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} network can be -represented on several chains. They can take many forms, from a parachain's native token to on-chain -representations of off-chain reserves. This page focuses on the latter, namely assets issued by a -creator (e.g. rights to audited, off-chain reserves held by the creator, or art issued as an NFT). +Assets in the Polkadot ecosystem can be represented on several chains. They can take many forms, +from a parachain's native token to on-chain representations of off-chain reserves. This page focuses +on the latter, namely assets issued by a creator (e.g. rights to audited, off-chain reserves held by +the creator, or art issued as an NFT). The [Asset Hub system parachain](https://www.parity.io/blog/statemint-generic-assets-chain-proposing-a-common-good-parachain-to-polkadot-governance/) hosts data structures and logic that specialize in the creation, management, and use of assets in -the {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} network. Although other -parachains can host applications dealing with assets on the Asset Hub, the hub can be thought of as -a trusted "home base" of assets in the network. +the network. Although other parachains can host applications dealing with assets on the Asset Hub, +the hub can be thought of as a trusted "home base" of assets in the network. -The Asset Hub uses {{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} as its native token. The -chain yields its governance to its parent relay chain and has no inflation or era-based rewards for -collators (although collators receive a portion of transaction fees). As a +The Asset Hub uses the relay chain's native token. The chain yields its governance to its parent +relay chain and has no inflation or era-based rewards for collators (although collators receive a +portion of transaction fees). As a [system parachain](https://polkadot.network/blog/common-good-parachains-an-introduction-to-governance-allocated-parachain-slots/), -the Asset Hub has a trusted relationship with the relay chain, and as such, can teleport -{{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} between itself and the relay chain. That is, -{{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} on the Asset Hub is just as good as -{{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} on the relay chain. +the Asset Hub has a trusted relationship with the relay chain, and as such, can teleport the relay +chain's native token between itself and the relay chain. That is, the native token on the relay +chain is just as good on Asset Hub. The Asset Hub does not support smart contracts. See the [Advanced](#advanced-techniques) section at the bottom for a discussion on using proxy and multisig accounts to replicate oft-used contract @@ -35,18 +33,18 @@ logic. ## Sufficient Assets A sufficient asset on Asset Hub can allow for an account to exist on-chain even though it does not -have any account balance in {{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }}. Any registered -asset on the Asset Hub can be made _sufficient_ through governance on the relay chain. A balance of -a non-sufficient asset can only exist on accounts that are on-chain (i.e., accounts having the +have any account balance in the native asset. Any registered asset on the Asset Hub can be made +_sufficient_ through governance on the relay chain. A balance of a non-sufficient asset can only +exist on accounts that are on-chain (i.e., accounts having the [existential deposit](./learn-accounts.md#existential-deposit-and-reaping) of a sufficient asset). That is, a user could not keep an account on-chain by transferring a non-sufficient asset to it; the -account must already be on-chain by having more than the existential deposit in -{{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} (or a sufficient asset). +account must already be on-chain by having more than the existential deposit in native asset (or a +sufficient asset). Assets deemed _sufficient_ can instantiate accounts on the Asset Hub and pay for transaction fees -without the need for {{ polkadot: DOT. :polkadot }}{{ kusama: KSM. :kusama }} An example would be -USDT on the Polkadot Asset Hub. If an account holds 0.7 USDT, it would exist on the Polkadot Asset -Hub system parachain without the need to hold DOT. +without the need for the native token (DOT or KSM). An example would be USDT on the Polkadot Asset +Hub. If an account holds 0.7 USDT, it would exist on the Polkadot Asset Hub system parachain without +the need to hold DOT. :::warning Transfers of Non-sufficient assets @@ -115,8 +113,7 @@ An asset's details contain one field not accessible to its owner or admin team, Polkadot-JS UI [doesn't support the functionality to pay with a sufficient asset yet](https://github.com/polkadot-js/apps/issues/7812). -When using Polkadot-JS UI, transaction fee needs to be paid in -{{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }}. +When using Polkadot-JS UI, transaction fee needs to be paid using the native asset (DOT or KSM). ::: diff --git a/docs/learn/learn-async-backing.md b/docs/learn/learn-async-backing.md index e7ba4f9f8a92..0e3ad260ae4b 100644 --- a/docs/learn/learn-async-backing.md +++ b/docs/learn/learn-async-backing.md @@ -213,11 +213,11 @@ executed before others are complete. Instructions may also be executed in parall multiple processor parts to work on potentially different instructions simultaneously. Bundles of state transitions represented as blocks may be processed similarly. In the context of -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}, pipelining aims to increase the -throughput of the entire network by completing the backing and inclusion steps for different blocks -at the same time. Asynchronous backing does not just allow for pipelining within a single pipe (or -core). It lays the foundation for a large number of pipes (or cores) to run for the same parachain -at the same time. In that way, we have two distinct new forms of parallel computation. +Polkadot, pipelining aims to increase the throughput of the entire network by completing the backing +and inclusion steps for different blocks at the same time. Asynchronous backing does not just allow +for pipelining within a single pipe (or core). It lays the foundation for a large number of pipes +(or cores) to run for the same parachain at the same time. In that way, we have two distinct new +forms of parallel computation. ### Unincluded Segments diff --git a/docs/learn/learn-auction.md b/docs/learn/learn-auction.md index ad3cc0088434..452d030a0724 100644 --- a/docs/learn/learn-auction.md +++ b/docs/learn/learn-auction.md @@ -11,13 +11,11 @@ import MessageBox from "../../components/MessageBox"; import "../../components/M -For a [parachain](learn-parachains.md) to be added to -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} it must inhabit one of the available -parachain slots. The number of parachain slots is not unbounded on -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}, as only a limited number are -available. A limited number of slots are unlocked every few months through on-chain governance. If a -parachain wants to have guaranteed block inclusion at every relay chain block, it must acquire a -parachain slot. The development of +For a [parachain](learn-parachains.md) to be added to the relay chain it must inhabit one of the +available parachain slots. The number of parachain slots is not unbounded, as only a limited number +are available. A limited number of slots are unlocked every few months through on-chain governance. +If a parachain wants to have guaranteed block inclusion at every relay chain block, it must acquire +a parachain slot. The development of [on-demand parachains](https://forum.polkadot.network/t/on-demand-parachains/2208) is complete, and they can be deployed after Agile Coretime is live on the network. @@ -53,8 +51,7 @@ termination. Parachain slot auctions differ slightly from a normal candle auctio not randomly terminate the auction. Instead, they run for an entire fixed duration and the winner is randomly chosen retroactively. -The candle auction on {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} is split into -two parts: +The candle auction is split into two parts: 1. The _opening period_ which is in effect immediately after the auction starts. This period lasts for one day and eighteen hours and serves as a buffer time for parachain candidates to setup @@ -78,8 +75,7 @@ Random Function wins the slot auction. ::: -A parachain auction on {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} lasts exactly -one week from the starting period (1 day and 18 hours) to +A parachain auction lasts exactly one week from the starting period (1 day and 18 hours) to [ending period](../general/chain-state-values.md#auction-ending-period) (candle auction phase) and finally 6 hours for determining the auction winner. @@ -166,15 +162,14 @@ ended before having an opportunity to bid. ## Network Implementation -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} will use a _random beacon_ based on -the [Verifiable Random Function (VRF)](./learn-cryptography.md#vrf). The VRF will provide the base -of the randomness, which will retroactively determine the end-time of the auction. +The relay chain will use a _random beacon_ based on the +[Verifiable Random Function (VRF)](./learn-cryptography.md#vrf). The VRF will provide the base of +the randomness, which will retroactively determine the end-time of the auction. -The slot durations are capped to {{ polkadot: 2 years and divided into 3-month periods. :polkadot }} -{{ kusama: 1 year and divided into 6-week periods. :kusama }} Parachains may lease a slot for any -combination of periods of the slot duration. Parachains may lease more than one slot over time, -meaning that they could extend their lease to the network past the maximum duration by leasing a -contiguous slot. +Polkadot's slot durations are capped to 2 years and are divided into 3-month periods (1 year divided +into 6-week periods for Kusama). Parachains may lease a slot for any combination of periods of the +slot duration. Parachains may lease more than one slot over time, meaning that they could extend +their lease to the network past the maximum duration by leasing a contiguous slot. :::note Individual parachain slots are fungible @@ -207,9 +202,8 @@ Slot E |__________|___________| 1 | 2 | 3 | 4 | ``` -_Each period of the range 1 - 4 represents a -{{ polkadot: 3-month duration for a total of 2 years :polkadot }} -{{ kusama: 6-week duration for a total of 1 year :kusama }} _ +_Each period of the range 1 - 4 represents a 3-month duration for a total of 2 years for Polkadot +(or 6-week duration for a total of 1 year for Kusama)._ Bidders will submit a configuration of bids specifying the token amount they are willing to bond and for which periods. The slot ranges may be any of the periods 1 - `n`, where `n` is the number of @@ -248,13 +242,12 @@ amount of tokens held over the entire lease duration of the parachain slot. This highest bidder for any given slot lease period might not always win (see the [example below](#examples)). -A random number, which is based on the [VRF](./learn-cryptography.md#vrf) used by -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}, is determined at each block. -Additionally, each auction will have a threshold that starts at 0 and increases to 1. The random -number produced by the VRF is examined next to the threshold to determine if that block is the end -of the auction within the so-called _ending period_. Additionally, the VRF will pick a block from -the last epoch to access the state of bids which can help aid in mitigating some types of attacks -from malicious validators. +A random number, which is based on the [VRF](./learn-cryptography.md#vrf) used by the relay chain, +is determined at each block. Additionally, each auction will have a threshold that starts at 0 and +increases to 1. The random number produced by the VRF is examined next to the threshold to determine +if that block is the end of the auction within the so-called _ending period_. Additionally, the VRF +will pick a block from the last epoch to access the state of bids which can help aid in mitigating +some types of attacks from malicious validators. ### Examples diff --git a/docs/learn/learn-collator.md b/docs/learn/learn-collator.md index 85fbba641f0f..89146582bd5d 100644 --- a/docs/learn/learn-collator.md +++ b/docs/learn/learn-collator.md @@ -9,9 +9,8 @@ slug: ../learn-collator :::info -This page provides a general overview of the role of collators' in -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}. For more detailed information you -can read the [Parachain Protocol Overview](./learn-parachains-protocol.md). +This page provides a general overview of the role of collators' in the Polkadot ecosystem. For more +detailed information you can read the [Parachain Protocol Overview](./learn-parachains-protocol.md). ::: @@ -29,13 +28,12 @@ will collate and execute transactions to create an unsealed block and provide it PoV, to one or more validators responsible for proposing a parachain block. Collators are similar to validators on any other blockchain but they do not need to provide security -guarantees because {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} provides those. If -a parachain block is invalid, it will get rejected by validators. The validators are required to -check the validity of submitted candidates, followed by issuing and collecting statements about the -validity of candidates to other validators. This process is known as **candidate backing**. -Validators receive an arbitrary number of parachain candidates with associated PoV from untrusted -collators. A candidate is considered _backable_ when at least 2/3 of all assigned validators have -issued a valid statement about that candidate. +guarantees because the relay chain provides those. If a parachain block is invalid, it will get +rejected by validators. The validators are required to check the validity of submitted candidates, +followed by issuing and collecting statements about the validity of candidates to other validators. +This process is known as **candidate backing**. Validators receive an arbitrary number of parachain +candidates with associated PoV from untrusted collators. A candidate is considered _backable_ when +at least 2/3 of all assigned validators have issued a valid statement about that candidate. The validator must successfully verify the following conditions in the following order: diff --git a/docs/learn/learn-comparison-ethereum-2.md b/docs/learn/learn-comparison-ethereum-2.md index ec67ccd664ed..b0ca94178ff6 100644 --- a/docs/learn/learn-comparison-ethereum-2.md +++ b/docs/learn/learn-comparison-ethereum-2.md @@ -66,10 +66,9 @@ data will be verifiable for an amount of time before being pruned from the netwo will enable data availability at layer one and further enable layer two protocols on Ethereum to flourish more readily. -In contrast, {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} require parachains to -register themselves in accordance with the [Parachains Protocol](./learn-parachains-protocol.md). -Once registered, {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} validates the state -transitions of each parachain as per their parachain validation function (PVF). +In contrast, the relay chain requires parachains to register themselves in accordance with the +[Parachains Protocol](./learn-parachains-protocol.md). Once registered, the relay chain validates +the state transitions of each parachain as per their parachain validation function (PVF). [Data availability](./learn-parachains-protocol#availability-and-unavailability-phase) is an integral part of validating the parachain state. This approach enables parallelized interactions between parachains. They can trust that each sub-protocol's respective state is valid, as Polkadot @@ -87,10 +86,8 @@ For a more in-depth comparison of parachains versus rollups, take a look at the ::: -On {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}, each parachain hosts its own core -logic, called a **runtime** (sometimes called a **state transition function**). -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} uses WebAssembly -([Wasm](./learn-wasm.md)) as a "meta-protocol". +Each parachain hosts its own core logic, called a **runtime** (sometimes called a **state transition +function**). Polkadot uses WebAssembly ([Wasm](./learn-wasm.md)) as a "meta-protocol". Parachains have the option of using [cross-consensus messaging (XCM)](learn-xcm.md) to communicate with one another and facilitate inter-chain reactions. It is also possible to utilize XCM on @@ -118,24 +115,23 @@ medium other than the protocol itself. Upgrades on Ethereum will follow the stan procedure, coordinating the community and validators to upgrade their nodes to implement protocol changes. -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} uses on-chain -[governance, called OpenGov](./learn-polkadot-opengov.md), to facilitate upgrades to the Polkadot -runtime. The stakeholders of Polkadot vote on these upgrades, and if successful, the upgrade is -enacted automatically in the blocks to come. Polkadot validator operators only upgrade their nodes -when the client itself gets updated. +Polkadot uses on-chain [governance, called OpenGov](./learn-polkadot-opengov.md), to facilitate +runtime upgrades. The stakeholders of Polkadot vote on these upgrades, and if successful, the +upgrade is enacted automatically in the blocks to come. Polkadot validator operators only upgrade +their nodes when the client itself gets updated. -Because of this mechanism, {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} can enact -chain upgrades using the Wasm meta-protocol _without_ a hard fork. As the WebAssembly runtime for -Polkadot (and all of its subsequent parachains) are stored on-chain, this involves simply replacing -the runtime with a new WebAssembly blob once governance allowed the upgrade to be enacted. +Because of this mechanism, the relay chain can enact upgrades using the Wasm meta-protocol _without_ +a hard fork. As the WebAssembly runtime for Polkadot (and all of its subsequent parachains) are +stored on-chain, this involves simply replacing the runtime with a new WebAssembly blob once +governance allowed the upgrade to be enacted. Anything within the state transition function, the transaction queue, or off-chain workers can be upgraded without forking the chain, as these are all part of the WebAssembly runtime. ### Block Production & Finalization -Both Ethereum and {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} use hybrid -consensus models where **block production** and **finality** are decoupled. +Both Ethereum and Polkadot use hybrid consensus models where **block production** and **finality** +are decoupled. For finalization, Ethereum utilizes [Casper FFG](https://ethereum.org/glossary#casper-ffg), which works with [LMD-GHOST](https://ethereum.org/glossary#lmd-ghost) as the fork choice rule for @@ -154,11 +150,9 @@ mechanisms for selecting block producers, one of which is a fallback in case the allows for chain liveness. BABE produces unfinalized blocks on top of the chain already finalized by GRANDPA. -There are two main differences between Ethereum and -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} consensus: +There are two main differences between Ethereum and Polkadot consensus: -1. {{ polkadot: Polkadot's :polkadot }}{{ kusama: Kusama's :kusama }} finality protocol, GRANDPA, - finalizes batches of blocks based on +1. Polkadot finality protocol, GRANDPA, finalizes batches of blocks based on [availability and validity checks](./learn-parachains-protocol.md#availability-and-unavailability-phase) that happen as the proposed chain grows. The time to finality varies with the number of checks that need to be performed (and invalidity reports, which cause extra checks). The expected time @@ -166,15 +160,14 @@ There are two main differences between Ethereum and 2. Ethereum typically has many validators per round (called an [epoch](https://ethereum.org/en/glossary/#epoch) on Ethereum) to provide strong validity - guarantees while {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} can provide - stronger guarantees with fewer validators per round. - {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} achieves this by making - validators distribute an [erasure coding](./learn-parachains-protocol.md#erasure-codes) to all - validators in the system, such that anyone - not only the round's validators - can reconstruct a - parachain's block and test its validity. This data availability is a core part of Polkadot - - ensuring state is valid for its state transitions. The random parachain-validator assignments - and secondary checks are performed by randomly selected validators, making it less likely for - the small set of validators on each parachain to collude. + guarantees while Polkadot can provide stronger guarantees with fewer validators per round. + Polkadot achieves this by making validators distribute an + [erasure coding](./learn-parachains-protocol.md#erasure-codes) to all validators in the system, + such that anyone - not only the round's validators - can reconstruct a parachain's block and + test its validity. This data availability is a core part of Polkadot - ensuring state is valid + for its state transitions. The random parachain-validator assignments and secondary checks are + performed by randomly selected validators, making it less likely for the small set of validators + on each parachain to collude. ### Staking Mechanics: Ethereum PoS vs. Polkadot NPoS @@ -190,12 +183,11 @@ in the network. ### Interoperability and Message Passing -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} uses -[Cross-Consensus Messaging (XCM)](./learn-xcm.md) for parachains to send arbitrary messages to each -other. Parachains open connections with each other and can send messages via their established -channels. Given that [collators](./learn-collator.md) communicate directly to the relay chain, they -will be connected and can relay messages from parachain A to parachain B if needed through these -message passing channels (see: +Polkadot uses [Cross-Consensus Messaging (XCM)](./learn-xcm.md) for parachains to send arbitrary +messages to each other. Parachains open connections with each other and can send messages via their +established channels. Given that [collators](./learn-collator.md) communicate directly to the relay +chain, they will be connected and can relay messages from parachain A to parachain B if needed +through these message passing channels (see: [HRMP, VMP, and other message passing mechanisms for XCM](./learn-xcm-transport.md)). Messages do not pass through the relay chain. Only validity proofs and channel operations do (open, @@ -220,11 +212,11 @@ provides shared logic for cross-consensus messages, and will be used to construc Ethereum supports smart contract development using Solidity. These contracts are immutable, and cannot be changed once published on-chain. -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} supports smart contracts through -parachains, usually using the [ink! smart contract language](https://use.ink/), but also Solidity -through Frontier-enabled parachains. On Ethereum, smart contracts can call each other; however, they -are fixed on-chain to the domain of Ethereum. On Polkadot, smart contracts can call each other in -the same parachain _and_ across parachains. +Polkadot supports smart contracts through parachains, usually using the +[ink! smart contract language](https://use.ink/), but also Solidity through Frontier-enabled +parachains. On Ethereum, smart contracts can call each other; however, they are fixed on-chain to +the domain of Ethereum. On Polkadot, smart contracts can call each other in the same parachain _and_ +across parachains. On Polkadot, developers have the option of either using smart contracts, calling extrinsics from pallets that modify the chain's state in some particular way or merely use Polkadot's RPC to @@ -237,21 +229,18 @@ For a more comprehensive list of how to build on Polkadot, be sure to check the ## Conclusion -Ethereum and {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} both use a sharded -model. Danksharding plans to utilize a rollup-centric approach by focusing on data availability. The -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} ecosystem is secured by a main chain, -called the "relay chain," which in turn manages cores and allows tasks, such as parachains, to be -run on top of those cores and messages to be sent between them. +Ethereum and Polkadot both use a sharded model. Danksharding plans to utilize a rollup-centric +approach by focusing on data availability. The Polkadot ecosystem is secured by a main chain, called +the "relay chain," which in turn manages cores and allows tasks, such as parachains, to be run on +top of those cores and messages to be sent between them. The primary differences between the two protocols are: - Ethereum processes EVM-compatible state transitions, whether through rollups or on the mainnet - itself, while {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} allows its parachains - to have an abstract state transition function implementation. + itself, while Polkadot allows its parachains to have an abstract state transition function + implementation. - Governance processes in Ethereum are planned to be off-chain and thus require coordination for a - hard fork to enact governance decisions. In contrast, in - {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} the decisions are on-chain and + hard fork to enact governance decisions. In contrast, in Polkadot the decisions are on-chain and enacted autonomously via forkless upgrades. -- Validator selection mechanisms differ as - {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} can provide strong availability and - validity guarantees with fewer validators per protocol. +- Validator selection mechanisms differ as Polkadot can provide strong availability and validity + guarantees with fewer validators per protocol. diff --git a/docs/learn/learn-comparison-rollups.md b/docs/learn/learn-comparison-rollups.md index 2aa2c1065495..c72912a0af38 100644 --- a/docs/learn/learn-comparison-rollups.md +++ b/docs/learn/learn-comparison-rollups.md @@ -26,15 +26,13 @@ for "rolling up" transactions by batching them before publishing them to the L1 through a network of **sequencers**. This mechanism could include thousands of transactions in a single rollup. -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} implements this functionality at the -native level (i.e. without using L2 scaling solutions), allowing for shared security and scalability -of the relay chain and respective parachains. Shared security is a concept that has similar goals to -EVM-based optimistic and zero-knowledge rollups. Still, instead of being implemented as a secondary -layer, {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} guarantees native security and -scalability for each of its parachains through the -[Parachains Protocol](./learn-parachains-protocol.md). -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} handles the coordination of data from -parachains into an aggregated, representative state, somewhat similar to L2 rollups. +Polkadot implements this functionality at the native level (i.e. without using L2 scaling +solutions), allowing for shared security and scalability of the relay chain and respective +parachains. Shared security is a concept that has similar goals to EVM-based optimistic and +zero-knowledge rollups. Still, instead of being implemented as a secondary layer, Polkadot +guarantees native security and scalability for each of its parachains through the +[Parachains Protocol](./learn-parachains-protocol.md). Polkadot handles the coordination of data +from parachains into an aggregated, representative state, somewhat similar to L2 rollups. ## Optimistic Rollups @@ -107,19 +105,16 @@ scalability. ## Polkadot - Native Shared Security -Whereas rollups are considered solutions for L2 protocols, -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} include this functionality natively -through its [Parachains Protocol](./learn-parachains-protocol.md). The Parachains Protocol, which is -how {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} handles network's **sharding** is -meant to accomplish the combined goals of providing security, scalability, and availability. +Whereas rollups are considered solutions for L2 protocols, Polkadot include this functionality +natively through its [Parachains Protocol](./learn-parachains-protocol.md). The Parachains Protocol, +which is how Polkadot handles network's **sharding** is meant to accomplish the combined goals of +providing security, scalability, and availability. It enables parachains to verify their collective state and communicate with one another. Parachains -have similarities to aspects of optimistic and ZK rollups, which are reflected in how -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} handles the validity and availability -of the parachain state. [Collators](./learn-collator.md), a key part of -{{ polkadot: Polkadot's :polkadot }}{{ kusama: Kusama's :kusama }} architecture, are in principle -similar to sequencers, as collators pass data with a proof-of-validity (PoV) function for liveness -and communication with the relay chain. +have similarities to aspects of optimistic and ZK rollups, which are reflected in how Polkadot +handles the validity and availability of the parachain state. [Collators](./learn-collator.md), a +key part of Polkadot architecture, are in principle similar to sequencers, as collators pass data +with a proof-of-validity (PoV) function for liveness and communication with the relay chain. Each shard, or parachain, is equipped with a unique state transition function (STF). This function ensures that communication to the relay chain remains valid. Each STF, called runtime, is written in @@ -154,6 +149,5 @@ for that parablock are [slashed](./learn-offenses.md) if it is found to be bad. on the size and weights of the PoV (Proof of Validity) blocks which contain the parachain state transition data. -Despite these drawbacks, {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} remains -upgradable through forkless upgrades, which allows the protocol to be easily upgradable to stay in -line with future technological advances. +Despite these drawbacks, Polkadot remains upgradable through forkless upgrades, which allows the +protocol to be easily upgradable to stay in line with future technological advances. diff --git a/docs/learn/learn-comparisons.md b/docs/learn/learn-comparisons.md index 3e1a71bffebb..6dbded1e176a 100644 --- a/docs/learn/learn-comparisons.md +++ b/docs/learn/learn-comparisons.md @@ -7,8 +7,7 @@ keywords: [comparisons, polkadot, blockchain] slug: ../learn-comparisons --- -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} is a blockchain technology but makes -some innovations that sets it apart from other popular chains. +Polkadot is a blockchain protocol that is innovating in the web3 space. :::info In-depth Comparisons for multi-chain ecosystems @@ -23,25 +22,21 @@ See the in-depth comparisons for [Ethereum 2.0](./learn-comparison-ethereum-2.md to be deployed on-chain and operated across the p2p network. Ethereum 1.x refers to the current Ethereum release and the immediately planned future upgrades. -The difference between Ethereum 1.x and -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} is quite large. Ethereum is a single -chain that allows developers to extend its functionality through the deployment of blobs of code -onto the chain (called smart contracts). -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}, as described in the whitepaper, is a -fully extensible and scalable blockchain network that provides security and interoperability through -shared state. +The difference between Ethereum 1.x and Polkadot is quite large. Ethereum is a single chain that +allows developers to extend its functionality through the deployment of blobs of code onto the chain +(called smart contracts). Polkadot, as described in the whitepaper, is a fully extensible and +scalable blockchain network that provides security and interoperability through shared state. In practical terms, this means that the layer of abstraction between these two projects is remarkably different for developers. In Ethereum, developers write smart contracts that all execute -on a single virtual machine, called the Ethereum Virtual Machine (EVM). In -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}, however, developers write their -logic into individual blockchains, where the interface is part of the state transition function of -the blockchain itself. {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} will also -support smart contract blockchains for Wasm and EVM to provide compatibility with existing -contracts, but will not have smart contract functionality on its core chain, the relay chain. +on a single virtual machine, called the Ethereum Virtual Machine (EVM). In Polkadot, however, +developers write their logic into individual blockchains, where the interface is part of the state +transition function of the blockchain itself. Polkadot will also support smart contract blockchains +for Wasm and EVM to provide compatibility with existing contracts, but will not have smart contract +functionality on its core chain, the relay chain. -As such, {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} is a possible augmentation -and scaling method for Ethereum 1.x, rather than competition. +As such, Polkadot is a possible augmentation and scaling method for Ethereum 1.x, rather than +competition. ## Binance Smart Chain @@ -56,17 +51,13 @@ interoperability of Binance Smart Chain is based on bridges. This means all vali chains are also bridge operators, therefore the security of the system relies on trusting validators. At the moment, there are 21 Binance Smart Chain validator nodes. -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} has an entirely different purpose, as -it was built to connect and secure unique blockchains. It is a protocol on which single blockchains -(such as Binance Smart Chain) could be built and benefit from shared security, interoperability and -scalability. Interoperability within {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} -is based on pooled security on {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}, and -the security of the entire {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} network, +Polkadot has an entirely different purpose, as it was built to connect and secure unique +blockchains. It is a protocol on which single blockchains (such as Binance Smart Chain) could be +built and benefit from shared security, interoperability and scalability. Interoperability within +Polkadot is based on pooled security on Polkadot, and the security of the entire Polkadot network, and has much stronger economic security. Scalability based on bridges relies on each bridged chain finding its own set of validators, -therefore duplicate resources are required. Scalability on -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} is based on the security of the Relay -Chain, and as the number of validators in the active set on -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} are increased, more parachains can be -supported. +therefore duplicate resources are required. Scalability on Polkadot is based on the security of the +Relay Chain, and as the number of validators in the active set on Polkadot are increased, more +parachains can be supported. diff --git a/docs/learn/learn-consensus.md b/docs/learn/learn-consensus.md index 6a4660a882a3..d2c0af28abea 100644 --- a/docs/learn/learn-consensus.md +++ b/docs/learn/learn-consensus.md @@ -22,10 +22,10 @@ their stake for validators to represent them. ## Nominated Proof of Stake -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} uses NPoS (Nominated Proof-of-Stake) -as its mechanism for selecting the validator set. It is designed with the roles of -[**validators**](./learn-validator.md) and [**nominators**](./learn-nominator.md), to maximize chain -security. Actors who are interested in maintaining the network can run a validator node. +Polkadot uses NPoS (Nominated Proof-of-Stake) as its mechanism for selecting the validator set. It +is designed with the roles of [**validators**](./learn-validator.md) and +[**nominators**](./learn-nominator.md), to maximize chain security. Actors who are interested in +maintaining the network can run a validator node. Validators assume the role of producing new blocks, validating parachain blocks, and guaranteeing finality. Nominators can choose to backselect validators with their stake. Nominators can approve @@ -33,19 +33,17 @@ candidates that they trust and back them with their tokens. ## Hybrid Consensus -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} uses what is known as _hybrid -consensus_. Hybrid consensus splits up the finality gadget ([GRANDPA](#finality-gadget-grandpa)) -from the block production mechanism ([BABE](#block-production-babe)). +Polkadot uses a _hybrid consensus_ composed by the finality gadget +([GRANDPA](#finality-gadget-grandpa)) and the block production mechanism +([BABE](#block-production-babe)). This is a way of getting the benefits of **probabilistic finality** (the ability always to produce new blocks) and **provable finality** (having a universal agreement on the canonical chain with no -chance for reversion) in {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}. It also -avoids the corresponding drawbacks of each mechanism (the chance of unknowingly following the wrong -fork in probabilistic finality, and a chance for "stalling" - not being able to produce new blocks - -in provable finality). By combining these two mechanisms, -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} allows for blocks to be rapidly -produced, and the slower finality mechanism to run in a separate process to finalize blocks without -risking slower transaction processing or stalling. +chance for reversion). It also avoids the corresponding drawbacks of each mechanism (the chance of +unknowingly following the wrong fork in probabilistic finality, and a chance for "stalling" - not +being able to produce new blocks - in provable finality). The combination of these two mechanisms +allows for blocks to be rapidly produced, and the slower finality mechanism to run in a separate +process to finalize blocks without risking slower transaction processing or stalling. Hybrid consensus has been proposed in the past. Notably, it was proposed (now defunct) as a step in Ethereum's transition to proof of stake in [EIP 1011](http://eips.ethereum.org/EIPS/eip-1011), which @@ -57,7 +55,7 @@ BABE (Blind Assignment for Blockchain Extension) is the block production mechani the validator nodes and determines the authors of new blocks. BABE is comparable as an algorithm to [Ouroboros Praos](https://eprint.iacr.org/2017/573.pdf), with some key differences in chain selection rule and slot time adjustments. BABE assigns block production slots to validators -according to stake and using the {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} +according to stake and using the relay chain's [randomness cycle](./learn-cryptography.md#randomness). The chain’s runtime is required to provide the BABE authority list and randomness to the host via a consensus message in the header of the first block of each epoch. @@ -97,12 +95,11 @@ For more details on BABE, please see the ## Finality Gadget: GRANDPA GRANDPA (GHOST-based Recursive ANcestor Deriving Prefix Agreement) is the finality gadget that is -implemented for the {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} relay chain. +implemented for the relay chain. -The {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} Host uses the GRANDPA Finality -protocol to finalize blocks. Finality is obtained by consecutive rounds of voting by the validator -nodes. Validators execute the GRANDPA finality process in parallel to Block Production as an -independent service. +The Polkadot Host uses the GRANDPA Finality protocol to finalize blocks. Finality is obtained by +consecutive rounds of voting by the validator nodes. Validators execute the GRANDPA finality process +in parallel to Block Production as an independent service. It works in a partially synchronous network model as long as 2/3 of nodes are honest and can cope with 1/5 Byzantine nodes in an asynchronous setting. @@ -148,10 +145,9 @@ participants after some unspecified time. ## Fork Choice -Bringing BABE and GRANDPA together, the fork choice of -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} becomes clear. BABE must always build -on the chain that GRANDPA has finalized. BABE provides probabilistic finality when there are forks -after the finalized head by building on the chain with the most primary blocks. +Bringing BABE and GRANDPA together, the fork choice of the relay chain becomes clear. BABE must +always build on the chain that GRANDPA has finalized. BABE provides probabilistic finality when +there are forks after the finalized head by building on the chain with the most primary blocks. ![Best chain choice](../assets/best_chain.png) diff --git a/docs/learn/learn-crowdloans.md b/docs/learn/learn-crowdloans.md index bde6d04ed9f0..4aea422c537a 100644 --- a/docs/learn/learn-crowdloans.md +++ b/docs/learn/learn-crowdloans.md @@ -11,8 +11,7 @@ import MessageBox from "../../components/MessageBox"; import "../../components/M -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} allows parachains to source tokens -for their parachain bids in a decentralized crowdloan. +Polkadot allows parachains to source tokens for their parachain bids in a decentralized crowdloan. :::note Contributing to a crowdloan @@ -46,16 +45,14 @@ a parachain slot auction. The parachain slot auction can also be won directly th without community involvement. To reiterate, crowdloan campaigns are just one of the means to win auctions, which allow the community to participate in a trustless and permissionless way. -Let's look at a scenario where Project A is hoping to gain a parachain slot on -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}, but they don't have enough tokens to -bid directly to win the parachain auction. Project A could benefit from starting a new crowdloan -campaign to help secure a parachain slot. Crowdloans are trustless and are supported natively on -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}, allowing the community to bond their -tokens on Project A's behalf for the entire parachain lease duration. This will allow Project A to -compete with projects that may have access to greater capital, given the project has sufficient -community support. In return, the community contributors are rewarded by the projects that win the -parachain slot, which would compensate for the opportunity cost of bonding their tokens for the -lease duration. +Let's look at a scenario where Project A is bidding for a parachain slot, but they don't have enough +tokens to bid directly to win the parachain auction. Project A could benefit from starting a new +crowdloan campaign to help secure a parachain slot. Crowdloans are trustless and are supported +natively on the relay chain, allowing the community to bond their tokens on Project A's behalf for +the entire parachain lease duration. This will allow Project A to compete with projects that may +have access to greater capital, given the project has sufficient community support. In return, the +community contributors are rewarded by the projects that win the parachain slot, which would +compensate for the opportunity cost of bonding their tokens for the lease duration. On the other hand, let's say Project B, which is more established and has access to capital, is hoping to secure a parachain slot through self-funding. Project B is not relying on community @@ -83,9 +80,8 @@ need to restart the campaign just because they do not secure a slot on their fir :::info Crowdloan Submission Deposit Required -To create a new crowdloan campaign, your account must have -{{ polkadot: 500 DOT :polkadot }}{{ kusama: 100 KSM :kusama }} transferrable which will be reserved -for the duration of the crowdloan. +To create a new crowdloan campaign, your account must have 500 DOT (or 100 KSM on Kusama) +transferrable which will be reserved for the duration of the crowdloan. ::: diff --git a/docs/learn/learn-cryptography.md b/docs/learn/learn-cryptography.md index 6e5d90be3688..13b6d3f1955a 100644 --- a/docs/learn/learn-cryptography.md +++ b/docs/learn/learn-cryptography.md @@ -41,8 +41,7 @@ curves like Curve25519. ## Keys Public and private keys are an important aspect of most crypto-systems and an essential component -that enables blockchains like {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} to -exist. +that enables blockchains like Polkadot to exist. ### Account Keys @@ -68,10 +67,10 @@ available option. The staking proxy key is a semi-online key that will be in the direct control of a user, and used to submit manual extrinsics. For validators or nominators, this means that the proxy key will be used -to start or stop validating or nominating. Proxy keys should hold some -{{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} to pay for fees, but they should not be used -to hold huge amounts or life savings. Since they will be exposed to the internet with relative -frequency, they should be treated carefully and occasionally replaced with new ones. +to start or stop validating or nominating. Proxy keys should hold some native tokens to pay for +fees, but they should not be used to hold huge amounts or life savings. Since they will be exposed +to the internet with relative frequency, they should be treated carefully and occasionally replaced +with new ones. The stash key is a key that will, in most cases, be a cold wallet, existing on a piece of paper in a safe or protected by layers of hardware security. It should rarely, if ever, be exposed to the @@ -95,7 +94,7 @@ meant to control funds and should only be used for their intended purpose. They regularly; your staking proxy only need to create a certificate by signing a session public key and broadcast this certificate via an extrinsic. -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} uses six session keys: +Polkadot uses six session keys: - Authority Discovery: sr25519 - BABE: sr25519 @@ -114,17 +113,15 @@ aggregation. #### Why was `ed25519` selected over `secp256k1`? -The original key derivation cryptography that was implemented for -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} and Substrate chains was `ed25519`, -which is a Schnorr signature algorithm implemented over the Edward's Curve 25519 (so named due to -the parameters of the curve equation). +The original key derivation cryptography that was implemented for Polkadot and Substrate chains was +`ed25519`, which is a Schnorr signature algorithm implemented over the Edward's Curve 25519 (so +named due to the parameters of the curve equation). Most cryptocurrencies, including Bitcoin and Ethereum, currently use ECDSA signatures on the secp256k1 curve. This curve is considered much more secure than NIST curves, which [have possible backdoors from the NSA](#appendix-a-on-the-security-of-curves). The Curve25519 is considered possibly _even more_ secure than this one and allows for easier implementation of Schnorr -signatures. A recent patent expiration on it has made it the preferred choice for use in -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}. +signatures. A recent patent expiration on it has made it the preferred choice for use in Polkadot. The choice of using Schnorr signatures over using ECDSA is not so cut and dried. Jeff Burdges (a Web3 researcher) provides additional details on the decision in this @@ -211,7 +208,7 @@ on which to build blocks, forks happen. Real-world entropy is not suitable for u blockchain randomness. There are two main approaches to blockchain randomness in production today: `RANDAO` and `VRF`. -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} uses VRF. +Polkadot uses VRF. ### VRF @@ -220,19 +217,17 @@ random number along with a proof of authenticity that this random number was gen submitter. The proof can be verified by any challenger to ensure the random number generation is valid. -The VRF used in {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} is roughly the same -as the one used in Ouroboros Praos. Ouroboros randomness is secure for block production and works -well for [BABE](learn-consensus.md#BABE). Where they differ is that Polkadot's VRF does not depend -on a central clock (the problem becomes - whose central clock?), rather, it depends on its own past -results to determine present and future results, and it uses slot numbers as a clock emulator, -estimating time. +The VRF used in Polkadot is roughly the same as the one used in Ouroboros Praos. Ouroboros +randomness is secure for block production and works well for [BABE](learn-consensus.md#BABE). Where +they differ is that Polkadot's VRF does not depend on a central clock (the problem becomes - whose +central clock?), rather, it depends on its own past results to determine present and future results, +and it uses slot numbers as a clock emulator, estimating time. #### Here's how it works in detail: Slots are discrete units of time six seconds in length. Each slot can contain a block, but may not. -Slots make up [epochs](../general/glossary.md##epoch) - on -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}, 2400 slots make one epoch, which -makes epochs four hours long. +Slots make up [epochs](../general/glossary.md##epoch) - on Polkadot, 2400 slots make one epoch, +which makes epochs four hours long. In every slot, each validator "rolls a die". They execute a function (the VRF) that takes as input the following: @@ -248,18 +243,16 @@ The output is two values: a `RESULT` (the random value) and a `PROOF` (a proof t was generated correctly). The `RESULT` is then compared to a _threshold_ defined in the implementation of the protocol -(specifically, in the {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} Host). If the -value is less than the threshold, then the validator who rolled this number is a viable block -production candidate for that slot. The validator then attempts to create a block and submits this -block into the network along with the previously obtained `PROOF` and `RESULT`. Under VRF, every -validator rolls a number for themselves, checks it against a threshold, and produces a block if the -random roll is under that threshold. +(specifically, in the Polkadot Host). If the value is less than the threshold, then the validator +who rolled this number is a viable block production candidate for that slot. The validator then +attempts to create a block and submits this block into the network along with the previously +obtained `PROOF` and `RESULT`. Under VRF, every validator rolls a number for themselves, checks it +against a threshold, and produces a block if the random roll is under that threshold. The astute reader will notice that due to the way this works, some slots may have no validators as block producer candidates because all validator candidates rolled too high and missed the threshold. -We clarify how we resolve this issue and make sure that -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} block times remain near constant-time -in the wiki page on [consensus](learn-consensus.md). +We clarify how we resolve this issue and make sure that Polkadot block times remain near +constant-time in the wiki page on [consensus](learn-consensus.md). ### RANDAO diff --git a/docs/learn/learn-guides-accounts-multisig.md b/docs/learn/learn-guides-accounts-multisig.md index c0334d3be3fe..24957bd8c72a 100644 --- a/docs/learn/learn-guides-accounts-multisig.md +++ b/docs/learn/learn-guides-accounts-multisig.md @@ -81,8 +81,8 @@ signatories to approve the call before finally executing it. ### Multisig Call Deposit When you create a new multi-sig call, you will need to place a -{{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} deposit. The deposit stays locked until the -call is executed. This deposit is to establish an economic cost on the storage space that the +[deposit](../general/chain-state-values.md#multisig-deposit-base). The deposit stays locked until +the call is executed. This deposit is to establish an economic cost on the storage space that the multisig call takes up in the chain state and discourage users from creating multisig calls that never get executed. The deposit will be reserved in the call initiator's account. diff --git a/docs/learn/learn-guides-accounts-proxy-pure.md b/docs/learn/learn-guides-accounts-proxy-pure.md index 68b9b51c2412..4cf060d20873 100644 --- a/docs/learn/learn-guides-accounts-proxy-pure.md +++ b/docs/learn/learn-guides-accounts-proxy-pure.md @@ -29,8 +29,8 @@ testnet, you can comfortably replicate the procedure on the main networks. :::danger Risk of loss of funds -Read carefully the text below and before performing any action using anonymous proxies on -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}, experiment on the Westend testnet. +Read carefully the text below and before performing any action using pure proxies, experiment on the +Westend testnet. ::: diff --git a/docs/learn/learn-guides-accounts-proxy.md b/docs/learn/learn-guides-accounts-proxy.md index f71862633186..0c4e3c87df81 100644 --- a/docs/learn/learn-guides-accounts-proxy.md +++ b/docs/learn/learn-guides-accounts-proxy.md @@ -69,12 +69,11 @@ you will be presented with a list of all proxies for that account. Additionally, you can head over to the _Chain State_ tab (underneath the _Developer_ menu) on [Polkadot-JS Apps](https://polkadot.js.org/apps/?rpc=wss%3A%2F%2Frpc.polkadot.io#/chainstate). If -you've created your proxy on a {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} -account, it is required to change your network accordingly using the top left navigation button. On -this page, the proxy pallet should be selected, returning the announcements and proxies functions. -The proxies function will allow you to see your created proxies for either one account or for all -accounts (using the toggle will enable this). Proxy announcements are what time lock proxies do to -announce they are going to conduct an action. +you've created your proxy on a Polkadot account, it is required to change your network accordingly +using the top left navigation button. On this page, the proxy pallet should be selected, returning +the announcements and proxies functions. The proxies function will allow you to see your created +proxies for either one account or for all accounts (using the toggle will enable this). Proxy +announcements are what time lock proxies do to announce they are going to conduct an action. ![polkadot_view_proxies_dev](../assets/polkadot_view_proxies_dev.png) diff --git a/docs/learn/learn-guides-accounts.md b/docs/learn/learn-guides-accounts.md index 13fc36c72e63..9c7e6b0a9cce 100644 --- a/docs/learn/learn-guides-accounts.md +++ b/docs/learn/learn-guides-accounts.md @@ -20,11 +20,10 @@ see the [wallets](./wallets-index), [apps](./apps-index) and [dashboard](./dashb ## Account Address Format -An account created for {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} can also be -used on multiple chains in the {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} -ecosystem. More specifically, the account of a chain that uses the `*25519` account address format -(the latest list can be accessed on the -[ss58 registry repository](https://github.com/paritytech/ss58-registry/blob/main/ss58-registry.json) +An account created on the relay chain can also be used on multiple chains in the ecosystem. More +specifically, the account of a chain that uses the `*25519` account address format (the latest list +can be accessed on the +[ss58 registry repository](https://github.com/paritytech/ss58-registry/blob/main/ss58-registry.json)) is cross-compatible with all the chains that use the similar format. To switch between the accounts on different chains, you can follow the guidelines in [this support article](https://support.polkadot.network/support/solutions/articles/65000103707-can-i-use-the-same-account-on-polkadot-kusama-and-parachains-). @@ -49,9 +48,7 @@ Account you are using on multiple chains and recommends using different Accounts On Polkadot-JS Extension, you can copy your address by clicking the account's icon while the desired chain format is active. E.g. selecting "Substrate" as the format will change your address, and -clicking the colorful icon of your account will copy it in that format. While in -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} mode, that address format will be -copied, and so on. +clicking the colorful icon of your account will copy it in that format. ## Polkadot-JS Browser Extension @@ -76,7 +73,7 @@ For guidelines about how to create an account using the Polkadot Extension, see The Polkadot-JS Browser Extension (the Polkadot Extension) provides a reasonable balance of security and usability. It provides a separate local mechanism to generate your address and interact with -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}. +Polkadot. This method involves installing the Polkadot Extension and using it as a “virtual vault," separate from your browser, to store your private keys. It also allows the signing of transactions and @@ -112,8 +109,7 @@ Let's say you created `ACCOUNT 1` protected by password `PSW 1`. To reset the pa `ACCOUNT 1` using the browser extension, you must follow the following steps: - Go to `ACCOUNT 1` on the browser extension and click "Forget account". This action will delete the - access to your account. Note that your tokens are still in your account on the - {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} blockchain network. + access to your account. Note that your tokens are still in your account on the Polkadot network. - On the browser extension click the "+" button in the top right corner and select the option "Import account from pre-existing seed". After entering the mnemonic phrase, you can choose a new password, `PSW 2`. diff --git a/docs/learn/learn-guides-assets-create.md b/docs/learn/learn-guides-assets-create.md index 9d3650d5ebab..7e3fc8c9f68b 100644 --- a/docs/learn/learn-guides-assets-create.md +++ b/docs/learn/learn-guides-assets-create.md @@ -16,11 +16,10 @@ see the [wallets](./wallets-index), [apps](./apps-index) and [dashboard](./dashb The Asset Hub is a generic assets system parachain which provides functionality for deploying and transferring assets — both Fungible and Non-Fungible Tokens (NFTs). The native token of the Asset -hub is {{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }}. The Existential Deposit (ED), +hub is the same as the relay chain's native asset (DOT or KSM). The Existential Deposit (ED), transaction fees, and the deposits for proxy/multisig operations are about [1/10th of the values on the Relay chains](../general/chain-state-values.md#existential-deposit-2). -Apart from the core protocol token {{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }}, the -assets held on the Asset Hub can be broadly categorized as +Apart from the native token, the assets held on the Asset Hub can be broadly categorized as - Assets backed by an on-chain protocol’s utility - Assets with off-chain backing @@ -46,15 +45,12 @@ To create an asset on the Asset Hub, you would need to [deposit some funds](../general/chain-state-values.md#asset-deposit). Before you create an asset on the Asset Hub, ensure that your Asset Hub account balance is a bit more than the sum of those two deposits, which should seamlessly account for the required deposits and transaction fees. You can -send {{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} from a -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} account to a the Asset Hub account -using the teleport functionality. For instructions on teleporting -{{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }}, check this -[tutorial on Teleports](../learn/learn-teleport.md). - -Assuming you have the required {{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} balance on -your Asset Hub account, the following instructions should let you successfully create an asset on -the Asset Hub +send the native token from a relay chain account to a the Asset Hub account using the teleport +functionality. For instructions on teleporting tokens, check this +[page on Teleports](../learn/learn-teleport.md). + +Assuming you have the required balance on your Asset Hub account, the following instructions should +let you successfully create an asset on the Asset Hub - Access the Asset Hub through [Polkadot-JS UI](https://polkadot.js.org/apps/#/explorer). - Navigate to Network > Assets. diff --git a/docs/learn/learn-guides-bounties.md b/docs/learn/learn-guides-bounties.md index cce16f9044ae..b31d4e65fbf3 100644 --- a/docs/learn/learn-guides-bounties.md +++ b/docs/learn/learn-guides-bounties.md @@ -161,9 +161,7 @@ separately, depending on the process curators consider appropriate for their bou -Note that once a child bounty is awarded, awardees need to wait for the -{{ polkadot: 8 :polkadot }}{{ kusama: 4 :kusama }}-day delay to be complete before claiming the -child bounty. +Once a child bounty is awarded, awardees can claim the child bounty. ## Claim a Child Bounty Reward diff --git a/docs/learn/learn-guides-claims.md b/docs/learn/learn-guides-claims.md index 75e9708f3c0a..803203b9fe80 100644 --- a/docs/learn/learn-guides-claims.md +++ b/docs/learn/learn-guides-claims.md @@ -19,15 +19,13 @@ see the [wallets](./wallets-index), [apps](./apps-index) and [dashboard](./dashb If you participated in a previous DOT sale before 2020 and received your DOT allocation indicator tokens, you can now claim your DOT (and a proportional amount of KSM on the Kusama network). The claim process connects the address where your DOT indicators have been stored on Ethereum with a -native {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} address and, if your ETH -address is eligible, will pay the tokens to the -{{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} address. +native Polkadot address and, if your ETH address is eligible, will pay the tokens to the Polkadot +address. -To do this, you must sign a message on Ethereum containing the address of your -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} account. You can do this by using the -Polkadot-JS UI [Claims app](https://polkadot.js.org/apps/#/claims). Ensure that you are connected to -the {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} network (displayed in the -upper-left-hand corner of the screen). +To do this, you must sign a message on Ethereum containing the address of your Polkadot account. You +can do this by using the Polkadot-JS UI [Claims app](https://polkadot.js.org/apps/#/claims). Ensure +that you are connected to the Polkadot network (displayed in the upper-left-hand corner of the +screen). :::warning Third-party claim processes @@ -39,8 +37,7 @@ claims process below, is the only way to ensure you will receive your allocation ## Generate an Account -You will need to generate a {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} account -to claim {{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }}. See the +You will need to generate an account on the relay chain to claim DOT (or KSM on Kusama). See the [available wallets and extensions](../general/wallets-and-extensions.md) for more information about wallets and browser extensions you can use to create an account. In terms of hardware wallet support, you can use the [Ledger](../general/ledger.md) devices or @@ -53,8 +50,7 @@ process of claiming the tokens. ### Select Accounts -Select the account you would like to claim the -{{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} into and click the "Continue" button to +Select the account you would like to claim the tokens into and click the "Continue" button to proceed. Your screen should look something like this: ![claim select dot account](../assets/claim-select-dot-account.png) @@ -68,11 +64,8 @@ to proceed. ### Sign Message on Ethereum & Claim -The hex-encoded string that follows the sentence: "Pay -{{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} to the -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} account:" is the hex-encoded public -key of your {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} account, minus the `0x` -prefix. +The hex-encoded string that follows the sentence "Pay DOT to the Polkadot account:" is the +hex-encoded public key of your Polkadot account, minus the `0x` prefix. ![claim copy msg](../assets/claim-copy-msg.png) @@ -92,12 +85,10 @@ Polkadot-JS UI and click "Confirm Claim." ![claim paste signature](../assets/claim-paste-signature.png) At this point, if you are eligible, you will see a success message if everything went right and your -{{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} will now be in the account that you claimed -to. Congratulations! You can now participate in aspects of the -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} network such as -[governance](../learn/learn-polkadot-opengov.md) and [staking](../learn/learn-staking.md). +tokens will now be in the account that you claimed to. Congratulations! You can now participate in +aspects of the network such as [governance](../learn/learn-polkadot-opengov.md) and +[staking](../learn/learn-staking.md). ### Verifying your Claim -After you make an on-chain claim for {{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }}, your -Your account balance should be updated immediately. +After you make an on-chain claim, your Your account balance should be updated immediately. diff --git a/docs/learn/learn-guides-coretime-parachains.md b/docs/learn/learn-guides-coretime-parachains.md index ae3fb3882f6a..dd06859631aa 100644 --- a/docs/learn/learn-guides-coretime-parachains.md +++ b/docs/learn/learn-guides-coretime-parachains.md @@ -16,11 +16,11 @@ If you aren't sure what Agile Coretime is, be sure to read the ::: -The landscape for parachains on {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} -changes with the rollout of [Agile Coretime](./learn-agile-coretime.md). With -[parachain auctions](./learn-auction.md) being phased out in favor of direct -[coretime](./learn-agile-coretime.md#coretime) sales, the existing parachains on the relaychain and -the prospective parachains are presented with the following scenarios: +The landscape for parachains changes with the rollout of +[Agile Coretime](./learn-agile-coretime.md). With [parachain auctions](./learn-auction.md) being +phased out in favor of direct [coretime](./learn-agile-coretime.md#coretime) sales, the existing +parachains on the relaychain and the prospective parachains are presented with the following +scenarios: - **Migrating** from a legacy parachain lease into a [bulk coretime](./learn-agile-coretime.md#bulk-coretime) model @@ -30,8 +30,7 @@ the prospective parachains are presented with the following scenarios: The parachain lease auctions will stop on-chain with the enactment of the [runtime upgrade 1.2.0](https://github.com/polkadot-fellows/runtimes/releases/tag/v1.2.0), and the existing leases will be migrated to bulk coretime automatically. Leases that are yet to be started -will be canceled and the locked {{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} -will be refunded. The existing parachains benefit from +will be canceled and the locked tokens will be refunded. The existing parachains benefit from [coretime renewals](https://docs.lastic.xyz/coretime/renewals.html) which allows for the continued assignment of bulk coretime for a core without going through the regular purchasing process. diff --git a/docs/learn/learn-guides-ledger.md b/docs/learn/learn-guides-ledger.md index 90fd2930e419..e8bec7ffb9d8 100644 --- a/docs/learn/learn-guides-ledger.md +++ b/docs/learn/learn-guides-ledger.md @@ -43,20 +43,16 @@ while if you want to import Ledger accounts to the Polkadot-JS UI, you can consu When adding a Ledger account using the extension or the UI, you will be asked to select an `account type` and an `account index`. The first lets you select an account, while the second lets 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: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} ledger account for the first time on -Ledger Live with name {{ polkadot: `Polkadot 1` :polkadot }}{{ kusama: `Kusama 1` :kusama }}, this -can be added to Polkadot-JS using the 0/0 derivation path (i.e. account type = 0 and account index = -0). If you add a second account called -{{ polkadot: `Polkadot 2` :polkadot }}{{ kusama: `Kusama 2` :kusama }}, 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 create multiple -children accounts from each parent account. For example, -{{ polkadot: `Polkadot 1` :polkadot }}{{ kusama: `Kusama 1` :kusama }} with 0/0 derivation path can -have child 0/1, 0/2, etc. that can be used within the UI. However, such children accounts cannot be -used in Ledger Live, as it only scans through the parent accounts. So, remember that the balances on -the children accounts cannot be viewed, and you will not be able to transact with those accounts on -Ledger Live. +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 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 +create multiple children accounts from each parent account. For example, `Polkadot 1` with 0/0 +derivation path can have child 0/1, 0/2, etc. that can be used within the UI. However, such children +accounts cannot be used in Ledger Live, as it only scans through the parent accounts. So, remember +that the balances on the children accounts cannot be viewed, and you will not be able to transact +with those accounts on Ledger Live. ### Confirming the Address on your Device @@ -88,8 +84,7 @@ while signing transactions. :::info Signature error message If you have already connected your device, but an error message appears before signing a -transaction, make sure you have opened the -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} application on your Ledger Nano +transaction, make sure you have opened the Polkadot Ledger Generic 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. @@ -124,9 +119,8 @@ clicking on your account's avatar icon - this immediately copies your address to :::note Your Asset Hub address is the same as your relay chain address Make sure that you clarify to the sender that you wish to receive your tokens on the Asset Hub -parachain, otherwise (if you're receiving {{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} -tokens) they could be sent on the {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} -chain. +parachain, otherwise (if you're receiving DOT or KSM tokens) they could be sent on the Polkadot or +Kusama relay chain. ::: @@ -146,15 +140,14 @@ unless you _know precisely what you're doing_. ### Why you might need the Developer Release -Ledger apps for the {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} ecosystem are -developed by [Zondax](https://zondax.ch/). When new functionalities are added to the Ledger apps, -they are made available on a developer release for testing purposes. After a successful audit and -review, the apps would be available for 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 to sign transactions. -Suppose you cannot wait a few days until the app passes the Ledger audit, you can install the -developer release from the shell using the latest version published on +Ledger apps for the Polkadot ecosystem are developed by [Zondax](https://zondax.ch/). When new +functionalities are added to the Ledger apps, they are made available on a developer release for +testing purposes. After a successful audit and review, the apps would be available for 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 to +sign transactions. Suppose you cannot wait a few 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). ### Install the Developer Release diff --git a/docs/learn/learn-guides-nominator.md b/docs/learn/learn-guides-nominator.md index 9754e560dd82..941a71b9ca39 100644 --- a/docs/learn/learn-guides-nominator.md +++ b/docs/learn/learn-guides-nominator.md @@ -96,9 +96,10 @@ Read the support article about ::: You are now bonded. Being bonded means your tokens are locked and could be -[slashed](./learn-offenses.md) if the validators you nominate misbehave. All bonded funds can now be -distributed to up to {{ polkadot: 16 :polkadot }} {{ kusama: 24 :kusama }} validators. Be careful -about the validators you choose since you will be slashed if your validator commits an offence. +[slashed](./learn-offenses.md) if the validators you nominate misbehave. All bonded funds can be +distributed to [multiple validators](../general/chain-state-values.md#maximum-votes-per-nominator). +Be careful about the validators you choose since you will be slashed if your validator commits an +[offence](./learn-offenses.md). Click on "Nominate" on an account you've bonded and you will be presented with another popup asking you to select some validators. @@ -135,9 +136,8 @@ you're nominating, but you cannot withdraw your tokens unless you unbond them. ## Claiming Rewards with Polkadot-JS Anyone can trigger a payout for any validator, as long as they are willing to pay the transaction -fee. Someone must submit a transaction with a validator ID and an era index. -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} will automatically calculate that -validator's reward and distribute the rewards pro rata. +fee. Someone must submit a transaction with a validator ID and an era index. Polkadot will +automatically calculate that validator's reward and distribute the rewards pro rata. These details are handled for you automatically if you use the [Polkadot-JS UI](https://polkadot.js.org/apps/#/staking/payout), which also allows you to submit @@ -161,8 +161,7 @@ transaction. ## Using Command-Line Interface (CLI) Apart from using the Polkadot-JS UI to participate in the staking, you can do all these things in -CLI instead. The CLI approach allows you to interact with the -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} network without using Polkadot-JS. +CLI instead. The CLI approach allows you to interact with the network without using Polkadot-JS. ### Step 1: Install @polkadot/api-cli @@ -193,18 +192,15 @@ are now deprecated. Refer to [this discussion](https://forum.polkadot.network/t/staking-controller-deprecation-plan-staking-ui-leads-comms/2748) for additional context) -`NUMBER_OF_TOKENS`: The number of {{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} you would -like to stake to the network. -{{ polkadot: DOT has ten decimal places and is always represented as an integer with zeroes at the end. So 1 DOT = 10_000_000_000 Plancks. :polkadot }}{{ kusama: KSM has twelve decimal places and is always represented as an integer with zeroes at the end. So 1 KSM = -1_000_000_000_000 Plancks. :kusama }} +`NUMBER_OF_TOKENS`: The number of native tokens (in Plancks) you would like to stake to the network. For more information, see [this page](../learn/learn-DOT.md). `REWARD_DESTINATION`: - `Staked` - Pay into the stash account, increasing the amount at stake accordingly. - `Stash` - Pay into the stash account, not increasing the amount at stake. -- `Account` - Pay into a custom account, like so: - {{ polkadot: `Account 1n8msHozaNxHicWFnRnNXzvqkYPWczkzUUkHhKw6o2BLBdo` :polkadot }}{{ kusama: `Account DMTHrNcmA8QbqRS4rBq8LXn8ipyczFoNMb1X4cY2WD9tdBX` :kusama }}. +- `Account` - Pay into a custom account that is not the stash (can be a proxy or another type of + account). - `Controller` - Pay into the controller account. Example for Kusama: diff --git a/docs/learn/learn-guides-polkadot-opengov.md b/docs/learn/learn-guides-polkadot-opengov.md index 91434f3db4de..d5dca4b31117 100644 --- a/docs/learn/learn-guides-polkadot-opengov.md +++ b/docs/learn/learn-guides-polkadot-opengov.md @@ -293,7 +293,7 @@ To refund your slashed deposit, you can start a new referendum and specifically from the treasury. You need to make sure you have enough balance for a new submission and decision deposit, and you will need to select the right track to ask for a refund. For example, the [Small Tipper Track](./learn-polkadot-opengov-origins.md#small-tipper) would be fine for any kind of -deposit refund up to {{ polkadot: 250 DOT :polkadot }}{{ kusama: 8.25 KSM KSM :kusama }}. +deposit refund up to 250 DOT (8.25 KSM on Kusama). ## Cancel or Kill a Referendum @@ -324,9 +324,8 @@ the `referenda.kill` extrinsic. This will cancel the referendum and slash the de A deposit is required for the preimage to be stored on chain. The preimage deposit is proportional to the amount of information stored within the preimage. The deposit amount required for a preimage -with a treasury spend transaction is around -{{ polkadot: 41 DOT :polkadot }}{{ kusama: 1.4 KSM :kusama }}. Ensure you have enough account -balance to pay for this submission deposit as well as the transaction fees. +with a treasury spend transaction is around 41 DOT (1.4 KSM on Kusama). Ensure you have enough +account balance to pay for this submission deposit as well as the transaction fees. ::: diff --git a/docs/learn/learn-guides-transfers.md b/docs/learn/learn-guides-transfers.md index 96c0934251f1..445f03653dde 100644 --- a/docs/learn/learn-guides-transfers.md +++ b/docs/learn/learn-guides-transfers.md @@ -67,29 +67,22 @@ to learn about keep-alive checks and existential deposit. ::: -In {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} there are two main ways to -transfer funds from one account to another: +In Polkadot there are two main ways to transfer funds from one account to another: - `transfer keep-alive` (default option) will not allow you to send an amount that would allow the sending account to be removed due to it going below the [existential deposit](../general/chain-state-values.md#existential-deposit). -- `transfer allow-death` will allow you to send - {{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} regardless of the consequence. If the - balance drops below the existential deposit your account will be reaped. It may be that you do not - want to keep the account alive (for example, because you are moving all of your funds to a - different address). To switch the keep-alive check off visit +- `transfer allow-death` will allow you to send tokens regardless of the consequence. If the balance + drops below the existential deposit your account will be reaped. It may be that you do not want to + keep the account alive (for example, because you are moving all of your funds to a different + address). To switch the keep-alive check off visit [this support article](https://support.polkadot.network/support/solutions/articles/65000169248). :::info -Attempting to send less than the existential deposit to an account with -{{ polkadot: 0 DOT :polkadot }}{{ kusama: 0 KSM :kusama }} will always fail, no matter if the -keep-alive check is on or not. For instance, attempting to transfer -{{ polkadot: 0.1 DOT :polkadot }}{{ kusama: 0.0001 KSM :kusama }} to an account you just generated -(and thus has no balance) will fail, since -{{ polkadot: 0.1 DOT :polkadot }}{{ kusama: 0.0001 KSM :kusama }} is less than the -[existential deposit](../general/chain-state-values.md#existential-deposit) and the account cannot -be initialized with such a low balance. +Attempting to send less than the +[existential deposit](../general/chain-state-values.md#existential-deposit) to an account with zero +balance will always fail, no matter if the keep-alive check is on or not. Even if the transfer fails due to a keep-alive check, the transaction fee will be deducted from the sending account if you attempt to transfer. @@ -100,8 +93,7 @@ sending account if you attempt to transfer. You can watch [**this video tutorial**](https://youtu.be/JVlwTQBwNGc) to understand how to do vested transfers using the Polkadot-JS UI, including linear and cliff vesting. Note the tutorial uses the -Westend Testnet, but the same applies to -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}. +Westend Testnet, but the same applies to Polkadot and Kusama. There are two ways that vesting schedules can be created. @@ -109,10 +101,10 @@ There are two ways that vesting schedules can be created. vested transfer function allows anyone to create a vesting schedule with a transfer of funds, as long as the account for which the vesting schedule will be created does not already have one and the transfer moves at least `MinVestedTransfer` funds, which is specified as a chain constant. -- A second way is as part of the genesis configuration of the chain. In the case of - {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}, the chain specification genesis - script reads the state of the Claims contract that exists on the Ethereum blockchain and creates - vesting schedules in genesis for all the allocations registered as being vested. +- A second way is as part of the genesis configuration of the chain. In the case of Polkadot, the + chain specification genesis script reads the state of the Claims contract that exists on the + Ethereum blockchain and creates vesting schedules in genesis for all the allocations registered as + being vested. Vesting schedules have three parameters: @@ -134,10 +126,9 @@ explicitly call an extrinsic to update the lock that is placed on an account. These extrinsics are exposed from the Vesting pallet. -If you are using the Polkadot-JS UI, when there are -{{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} available to vest for an account, then you -will have the ability to unlock {{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} which has -already vested from the [Accounts](https://polkadot.js.org/apps/#/accounts) page. +If you are using [the Polkadot-JS UI](./learn-polkadotjs.md), when there are tokens available to +vest for an account, you can unlock tokens that have already been vested from the +[Accounts](https://polkadot.js.org/apps/#/accounts) page. ![unbond](../assets/unlock-vesting.png) @@ -268,15 +259,16 @@ be checked by checking `session.nextKeys` in the chain state for an existing key ### Existing Recovery Info -{{ polkadot: Currently, Polkadot does not use the -[Recovery Pallet](https://github.com/paritytech/polkadot-sdk/blob/master/substrate/frame/recovery/), so this is -probably not the reason for your tokens having existing references. :polkadot }} +Currently, Polkadot does not use the +[Recovery Pallet](https://github.com/paritytech/polkadot-sdk/blob/master/substrate/frame/recovery/), +so this is probably not the reason for your tokens having existing references. -{{ kusama: On Kusama, you can check if recovery has been set up by checking the `recovery.recoverable(AccountId)` -chain state. This can be found under `Developer > Chain state` in [PolkadotJS Apps](https://polkadot.js.org/apps/). :kusama }} +On Kusama, you can check if recovery has been set up by checking the +`recovery.recoverable(AccountId)` chain state. This can be found under `Developer > Chain state` in +[PolkadotJS Apps](https://polkadot.js.org/apps/). ### Existing Non-Native Assets -Currently, {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} does not use the +Currently, Polkadot does not use the [Assets Pallet](https://github.com/paritytech/polkadot-sdk/tree/master/substrate/frame/assets), so this is probably not the reason for your tokens having existing references. diff --git a/docs/learn/learn-guides-treasury.md b/docs/learn/learn-guides-treasury.md index ce1dce6d30aa..aa4150a4e986 100644 --- a/docs/learn/learn-guides-treasury.md +++ b/docs/learn/learn-guides-treasury.md @@ -21,24 +21,18 @@ See [this page](./learn-polkadot-opengov-treasury.md) to learn about the Polkado Your proposal should address a problem, outline a goal, give a detailed account of how you will reach that goal, and include any ongoing maintenance needs. As much as possible, you should itemize the tasks to be completed so fees can be evaluated and milestones can be followed. You can check the -{{ polkadot: [guidelines for a successful proposal](https://docs.google.com/document/d/1IZykdp2cyQavcRyZd_dgNj5DcgxgZR6kAqGdcNARu1w) :polkadot }}{{ kusama: [guidelines for a successful proposal](https://docs.google.com/document/d/1CzEnurqwqLBOGrJI9CQORiGW9m6QyPOSshhzJdR57Pk) :kusama }} -and fill out the -{{ polkadot: [Treasury proposal template](https://docs.google.com/document/d/1O_84mXYFERCavmnJyxbIPKFkG0bVBySRjCVy-d-VKcc) :polkadot }}{{ kusama: Treasury proposal template :kusama }} -provided. +guidelines below: + +- Guidelines for a successful proposal on + [Polkadot](https://docs.google.com/document/d/1IZykdp2cyQavcRyZd_dgNj5DcgxgZR6kAqGdcNARu1w) and + [Kusama](https://docs.google.com/document/d/1CzEnurqwqLBOGrJI9CQORiGW9m6QyPOSshhzJdR57Pk) +- [Treasury proposal template for Polkadot](https://docs.google.com/document/d/1O_84mXYFERCavmnJyxbIPKFkG0bVBySRjCVy-d-VKcc) ### Announcing the Proposal To minimize storage on-chain, proposals don't contain contextual information. When a user submits a -proposal, they will need to find an off-chain way to explain the proposal: - -- Many community members participate in discussion in the - {{ polkadot: [Polkadot Watercooler](https://matrix.to/#/#polkadot-watercooler:web3.foundation) and :polkadot }} - {{ kusama: [Kusama Direction room](https://matrix.to/#/#Kusama-Direction:parity.io) and the :kusama }} - {{ polkadot: [Polkadot Direction room](https://matrix.to/#/#Polkadot-Direction:parity.io). :polkadot }} - {{ kusama: [Kusama Watercooler](https://matrix.to/#/#kusamawatercooler:polkadot.builders). :kusama }} -- Use platforms like [Polkassembly](https://polkassembly.io) and - [SubSquare](https://www.subsquare.io/) to initiate discussion with the community. They also offer - a gauge poll to capture the community sentiment before submitting an on-chain referendum. +proposal, they will need to find an off-chain way to explain the proposal via +[community channels](../general/community.md). Spreading the word about the proposal's explanation to the community is ultimately up to the proposer. @@ -86,9 +80,8 @@ transaction that requests 100 DOT from Treasury. A deposit is required for the preimage to be stored on chain. The preimage deposit is proportional to the amount of information stored within the preimage. The deposit amount required for a preimage -with a treasury spend transaction is around -{{ polkadot: 41 DOT :polkadot }}{{ kusama: 1.4 KSM :kusama }}. Ensure you have enough account -balance to pay for the submission deposit and the transaction fees. +with a treasury spend transaction is around 41 DOT (1.4 KSM on Kusama). Ensure you have enough +account balance to pay for the submission deposit and the transaction fees. ::: @@ -342,9 +335,8 @@ click on the FAB button in the bottom right corner. Then, ![polkassembly-write-proposal](../assets/polkassembly-write-proposal.png) - Create a preimage: an existing preimage can be linked, or a new one can be created. To create a - preimage, add the beneficiary address and the - {{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} amount. The track will be auto-selected - and the user can proceed with the creation of a preimage. + preimage, add the beneficiary address and the token amount. The track will be auto-selected and + the user can proceed with the creation of a preimage. ![polkassembly-create-preimage](../assets/polkassembly-create-preimage.png) @@ -365,9 +357,9 @@ Briefly, you will need to: - Submit a proposal to the right track (i.e. `30` or `31`) using the preimage hash - Once you started the referendum go to [Polkassembly](https://polkassembly.io/), log in with the proposer account and edit the referendum details -- Notify the - {{ polkadot: [Polkadot Direction Element Channel](https://matrix.to/#/#Polkadot-Direction:parity.io) :polkadot }}{{ kusama: [Kusama Direction Element Channel](https://matrix.to/#/#Polkadot-Direction:parity.io) :kusama }} - about your referendum +- Notify [the Polkadot Direction Element Channel](https://matrix.to/#/#Polkadot-Direction:parity.io) + or [the Kusama Direction Element Channel](https://matrix.to/#/#Polkadot-Direction:parity.io) about + your referendum - Place the decision deposit [before the timeout](../general/chain-state-values.md#opengov-referendum-timeout) - Once the referendum ends you can diff --git a/docs/learn/learn-guides-vault.md b/docs/learn/learn-guides-vault.md index cd688266831f..aae607cb7394 100644 --- a/docs/learn/learn-guides-vault.md +++ b/docs/learn/learn-guides-vault.md @@ -75,8 +75,11 @@ terminal within the `/generate_message` folder and type the following: where `wss://kusama-asset.hub-rpc.polkadot.io` is the Parity RPC endpoint for the Asset Hub on Kusama. This will create the file `sign_me_add_specs_statemine_sr25510` under the -`files/in_progress` folder. See -{{ polkadot: [this GitHub page](https://github.com/polkadot-js/apps/blob/089fd77b14169749e35e073a93f7e7276963009c/packages/apps-config/src/endpoints/productionRelayPolkadot.ts) for a list of all endpoints listed in the Polkadot-JS UI. :polkadot }}{{ kusama: [this GitHub page](https://github.com/polkadot-js/apps/blob/089fd77b14169749e35e073a93f7e7276963009c/packages/apps-config/src/endpoints/productionRelayKusama.ts) for a list of all endpoints listed in the Polkadot-JS UI. :kusama}} +`files/in_progress` folder. See all endpoints listed for +[Polkadot](https://github.com/polkadot-js/apps/blob/089fd77b14169749e35e073a93f7e7276963009c/packages/apps-config/src/endpoints/productionRelayPolkadot.ts) +and +[Kusama](https://github.com/polkadot-js/apps/blob/089fd77b14169749e35e073a93f7e7276963009c/packages/apps-config/src/endpoints/productionRelayKusama.ts) +on the Polkadot-JS UI. #### Generating Signature diff --git a/docs/learn/learn-hyperbridge.md b/docs/learn/learn-hyperbridge.md index 42587bac5795..8f0d96c56314 100644 --- a/docs/learn/learn-hyperbridge.md +++ b/docs/learn/learn-hyperbridge.md @@ -14,12 +14,11 @@ To follow the material on this page, it is recommended to be familiar with the c ::: -Interoperability is the core vision of the -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} technology. Through years of -blockchain development, much effort has been put into making a secure interoperability solution -between blockchains. {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} provides secure -interoperability between parachains through its [Cross-Consensus Messaging (XCM)](./learn-xcm.md), -and [Cross-Chain Message Passing (XCMP)](./learn-xcm-transport.md#xcmp-cross-chain-message-passing) +Interoperability is the core vision of the Polkadot technology. Through years of blockchain +development, much effort has been put into making a secure interoperability solution between +blockchains. Polkadot provides secure interoperability between parachains through its +[Cross-Consensus Messaging (XCM)](./learn-xcm.md), and +[Cross-Chain Message Passing (XCMP)](./learn-xcm-transport.md#xcmp-cross-chain-message-passing) protocol. However, these solutions work when there is a shared security. In the case of interaction between chains that do not belong to the same Polkadot's shared security, bridges are needed. diff --git a/docs/learn/learn-identity.md b/docs/learn/learn-identity.md index 504dcd20e249..d8a9d9562b76 100644 --- a/docs/learn/learn-identity.md +++ b/docs/learn/learn-identity.md @@ -7,9 +7,11 @@ keywords: [identity, registrars, judgements] slug: ../learn-identity --- -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} provides a naming system that allows -participants to add personal information to their on-chain account and subsequently ask for -verification of this information by [registrars](#registrars). +import Tabs from "@theme/Tabs"; import TabItem from "@theme/TabItem"; + +Polkadot provides a naming system that allows participants to add personal information to their +on-chain account and subsequently ask for verification of this information by +[registrars](#registrars). Users must [reserve funds](../general/chain-state-values.md#identity-deposit) in a bond to store their information on chain. These funds are _locked_, not spent - they are returned when the @@ -57,14 +59,13 @@ issuing faulty judgments. ## Registrars Registrars can set a fee for their services and limit their attestation to certain fields. For -example, a registrar could charge {{ polkadot: 1 DOT :polkadot }}{{ kusama: 0.1 KSM :kusama }} to -verify one's legal name, email, and GPG key. When a user requests judgement, they will pay this fee -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. +example, a registrar could charge 1 DOT to verify one's legal name, email, and GPG key. When a user +requests judgement, they will pay this fee 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. -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. +There are multiple registrars on Polkadot and Kusama. Unless no additional information is available +here, you must reach out to specific registrars individually if you want to be judged by those. :::info Decommissioned Registrar Service @@ -77,37 +78,53 @@ new identity judgment, please use the other registrars. ::: + + + + + ~~Registrar 0~~ :
    **URL**: NA
    **Account**: -{{ polkadot: ~~12j3Cz8qskCGJxmSJpVL2z2t3Fpmw3KoBaBaRGPnuibFc7o8~~ :polkadot }} -{{ kusama: ~~H4XieK3r3dq3VEvRtqZR7wN7a1UEkXxf14orRsEfdFjmgkF~~ :kusama }}
    **Fee**: -{{ polkadot: ~~0 DOT~~ :polkadot }}{{ kusama: ~~0.04 KSM~~ :kusama }}
    +~~12j3Cz8qskCGJxmSJpVL2z2t3Fpmw3KoBaBaRGPnuibFc7o8~~
    **Fee**: ~~0 DOT~~
    Registrar 1:
    **URL**: https://registrar.d11d.net/
    **Account**: -{{ polkadot: 1Reg2TYv9rGfrQKpPREmrHRxrNsUDBQKzkYwP1UstD97wpJ :polkadot }} -{{ kusama: Fom9M5W6Kck1hNAiE2mDcZ67auUCiNTzLBUdQy4QnxHSxdn :kusama }}
    **Fee**: -{{ polkadot: 20 DOT :polkadot }}{{ kusama: 4.5 KSM :kusama }}
    +1Reg2TYv9rGfrQKpPREmrHRxrNsUDBQKzkYwP1UstD97wpJ
    **Fee**: 20 DOT
    + +Registrar 2:
    **Account**: 1EpXirnoTimS1SWq52BeYx7sitsusXNGzMyGx8WPujPd1HB
    **Fee**: 0 +DOT
    -{{ polkadot: Registrar 2: :polkadot }} {{ kusama: ~~Registrar 2~~ :kusama }}
    **Account**: -{{ polkadot: 1EpXirnoTimS1SWq52BeYx7sitsusXNGzMyGx8WPujPd1HB :polkadot }} -{{ kusama: ~~EK8veMNH6sVtvhSRo4q1ZRh6huCDm69gxK4eN5MFoZzo3G7~~ :kusama }}
    **Fee**: -{{ polkadot: 0 DOT :polkadot }}{{ kusama: ~~1 KSM~~ :kusama }}
    +Registrar 3:
    **Account**: 13SceNt2ELz3ti4rnQbY1snpYH4XE4fLFsW8ph9rpwJd6HFC
    **Fee**: +0.5 DOT
    Polkassembly (Registrar 3) provides setting on-chain ID as a service on their +[website](https://polkadot.polkassembly.io/). -Registrar 3:
    **Account**: -{{ polkadot: 13SceNt2ELz3ti4rnQbY1snpYH4XE4fLFsW8ph9rpwJd6HFC :polkadot }} -{{ kusama: GLiebiQp5f6G5vNcc7BgRE9T3hrZSYDwP6evERn3hEczdaM :kusama }}
    **Fee**: -{{ polkadot: 0.5 DOT :polkadot }}{{ kusama: 1 KSM :kusama }}
    +     + + +~~Registrar 0~~ :
    **URL**: NA
    **Account**: +~~H4XieK3r3dq3VEvRtqZR7wN7a1UEkXxf14orRsEfdFjmgkF~~
    **Fee**: ~~0.04 KSM~~
    + +Registrar 1:
    **URL**: https://registrar.d11d.net/
    **Account**: +Fom9M5W6Kck1hNAiE2mDcZ67auUCiNTzLBUdQy4QnxHSxdn
    **Fee**: 4.5 KSM
    -{{ polkadot: Polkassembly (Registrar 3) provides setting on-chain ID as a service on their [website](https://polkadot.polkassembly.io/). :polkadot }} +Registrar 2: is no longer offering registrar services on Kusama.
    **Account**: +~~EK8veMNH6sVtvhSRo4q1ZRh6huCDm69gxK4eN5MFoZzo3G7~~
    **Fee**: ~~1 KSM~~
    -{{ kusama: Registrar 4:
    **Account**: GhmpzxUyTVsFJhV7s2wNvD8v3Bgikb6WvYjj4QSuSScAUw6
    **Fee**: 0.04 KSM
    :kusama }} +Registrar 3:
    **Account**: GLiebiQp5f6G5vNcc7BgRE9T3hrZSYDwP6evERn3hEczdaM
    **Fee**: 1 +KSM
    Polkassembly (Registrar 3) provides setting on-chain ID as a service on their +[website](https://kusama.polkassembly.io/). -{{ kusama: Registrar 5:
    **Account**: F1wAMxpzvjWCpsnbUMamgKfqFM7LRvNdkcQ44STkeVbemEZ
    **Fee**: 0.04 KSM
    :kusama }} +Registrar 4:
    **Account**: GhmpzxUyTVsFJhV7s2wNvD8v3Bgikb6WvYjj4QSuSScAUw6
    **Fee**: +0.04 KSM
    -{{ kusama: Polkassembly (Registrar 5) provides setting on-chain ID as a service on their [website](https://kusama.polkassembly.io/). :kusama }} +Registrar 5:
    **Account**: F1wAMxpzvjWCpsnbUMamgKfqFM7LRvNdkcQ44STkeVbemEZ
    **Fee**: +0.04 KSM
    Polkassembly (Registrar 5) provides setting on-chain ID as a service on their +[website](https://kusama.polkassembly.io/). -{{ kusama: Registrar 6:
    **Account**: HurhThD66KBUf2zcE9Zhx46sCqNJXviKhWAct95rBCkPuix
    **Fee**: 0.04 KSM
    :kusama }} +Registrar 6:
    **Account**: HurhThD66KBUf2zcE9Zhx46sCqNJXviKhWAct95rBCkPuix
    **Fee**: +0.04 KSM
    PolkaIdentity (Registrar 6) provides setting on-chain ID as a service on their +[website](https://polkaidentity.com/). -{{ kusama: PolkaIdentity (Registrar 6) provides setting on-chain ID as a service on their [website](https://polkaidentity.com/). :kusama }} +     +     See [this page](./learn-guides-identity.md#registrars) to learn how to become a Registrar. diff --git a/docs/learn/learn-inflation.md b/docs/learn/learn-inflation.md index 527e0ca96a3b..95a0808713f1 100644 --- a/docs/learn/learn-inflation.md +++ b/docs/learn/learn-inflation.md @@ -12,12 +12,11 @@ import RPC from "./../../components/RPC-Connection"; import MessageBox from -{{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} is an inflationary token. On the -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} network, inflation is -{{ polkadot: [set to be 10% annually](https://github.com/paritytech/polkadot-sdk/blob/756ccc35e93d1a78e3c71a0e67ae4da5f1d09f69/runtime/polkadot/src/lib.rs#L576). :polkadot }} -{{ kusama: [set to be 10% annually](https://github.com/paritytech/polkadot-sdk/blob/756ccc35e93d1a78e3c71a0e67ae4da5f1d09f69/runtime/kusama/src/lib.rs#L535). :kusama }}Depending -on the {{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} supply staked and the ideal staking -rate (more about this below), part of the {{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} +DOT (and KSM) is an inflationary token. Inflation is +[set to be 10% annually](https://github.com/paritytech/polkadot-sdk/blob/756ccc35e93d1a78e3c71a0e67ae4da5f1d09f69/runtime/polkadot/src/lib.rs#L576) +on Polkadot (same on Kusama, see +[here](https://github.com/paritytech/polkadot-sdk/blob/756ccc35e93d1a78e3c71a0e67ae4da5f1d09f69/runtime/kusama/src/lib.rs#L535)). +Depending on the supply staked and the ideal staking rate (more about this below), part of the inflation is distributed to the stakers and part to the [treasury](./learn-polkadot-opengov-treasury.md). @@ -26,23 +25,21 @@ inflation is distributed to the stakers and part to the DOT went through [redenomination](./archive/learn-redenomination.md) in 2020 that saw the DOT token supply increase by 100 times. -The current token supply on {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} can be -seen [here](../general/chain-state-values.md#total-issuance). +The current token supply can be seen [here](../general/chain-state-values.md#total-issuance). ::: -It is essential to understand that the primary objective of -{{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} inflation is to incentivize network +It is essential to understand that the primary objective of inflation is to incentivize network participants through [Nominated Proof of Stake (NPoS)](./learn-consensus.md#nominated-proof-of-stake) and to grow the -network through funding the on-chain treasury. There is an opportunity cost of keeping the -{{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} tokens idle with the current inflation model -as the tokens get diluted over time. Economics and game theory suggest that setting an ideal -inflation rate is essential for incentivizing the network participants as well as the growth of the -network, and any deviation from it can have adverse effects. Reducing the inflation rate could limit -growth, while increasing the inflation rate could break the incentive model of the token. Hence, -**token inflation rate is not a forever fixed value, and inflation can be updated in the future -through [on-chain governance](./learn-polkadot-opengov.md)** based on thorough tokenomics research. +network through funding the on-chain treasury. There is an opportunity cost of keeping the number of +tokens idle with the current inflation model as the tokens get diluted over time. Economics and game +theory suggest that setting an ideal inflation rate is essential for incentivizing the network +participants as well as the growth of the network, and any deviation from it can have adverse +effects. Reducing the inflation rate could limit growth, while increasing the inflation rate could +break the incentive model of the token. Hence, **token inflation rate is not a forever fixed value, +and inflation can be updated in the future through +[on-chain governance](./learn-polkadot-opengov.md)** based on thorough tokenomics research. ## Inflation Model @@ -56,15 +53,14 @@ stake when the _current staking rate_ < _ideal staking rate_ and disincentivize _current staking rate_ > _ideal staking rate_. The goal is to have the staking rate meet the ideal staking rate. The current staking rate would be the total amount staked in the current era over the total token supply, where the total amount staked is the stake of all validators and nominators on -the network. The ideal staking rate accounts for having sufficient backing of -{{ polkadot: DOT :polkadot }} {{ kusama: KSM :kusama }} to prevent the possible compromise of -security while keeping the native token liquid. +the network. The ideal staking rate accounts for having sufficient backing of tokens to prevent the +possible compromise of security while keeping the native token liquid. ![staking](../assets/rewards-inflation.png)

    Source: Research - Web3 Foundation

    -- **x-axis**: Proportion of {{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} staked +- **x-axis**: Proportion of staked tokens - **y-axis**: Annualized percentage (inflation and staking rewards, see below) - **Blue line**: Annual inflation rate diverted to NPoS, i.e., the total amount of tokens minted to pay validators and nominators. For instance, 0.1 corresponds to 10% of token inflation diverted to @@ -76,12 +72,12 @@ security while keeping the native token liquid. [the Polkadot Staking Dashboard](https://staking.polkadot.cloud/#/overview). Assuming that the ideal staking rate is 60%, all of the inflation would go to the validators and -nominators if 60% of all {{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} are staked. Any -deviation from the 60% - positive or negative - sends the proportional remainder to the treasury. -Deviations from the ideal staking rate are referred to as _staking inefficiencies_. Thus, the -treasury does not receive an inflow of funds from inflation when the system staking rate equals the -ideal staking rate. See [this page](./learn-polkadot-opengov-treasury.md) for more information about -treasury inflow sources. +nominators if 60% of all tokens are staked. Any deviation from the 60% - positive or negative - +sends the proportional remainder to the treasury. Deviations from the ideal staking rate are +referred to as _staking inefficiencies_. Thus, the treasury does not receive an inflow of funds from +inflation when the system staking rate equals the ideal staking rate. See +[this page](./learn-polkadot-opengov-treasury.md) for more information about treasury inflow +sources. For those who are interested in knowing more about the design of the inflation model for the network, please see [here](https://research.web3.foundation/Polkadot/overview/token-economics). diff --git a/docs/learn/learn-nft.md b/docs/learn/learn-nft.md index da50faf8e12f..4d608e6e0269 100644 --- a/docs/learn/learn-nft.md +++ b/docs/learn/learn-nft.md @@ -8,7 +8,7 @@ slug: ../learn-nft --- This page is a high-level overview of NFTs in the blockchain space and the various approaches to -NFTs within the {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} network. +NFTs within the Polkadot ecosystem. ## Fungibility @@ -69,8 +69,7 @@ exclusively image-based collectibles of varying rarity. ## NFTs in Polkadot & Kusama -This is where {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}'s technology shines and -where NFTs 2.0 come into play. By allowing +This is where Polkadot's technology shines and where NFTs 2.0 come into play. By allowing [heterogeneous application-specific shards](learn-parachains.md) to exist, builders can natively optimize for complex NFT use cases without tradeoffs that would make interacting with the system prohibitively inefficient and expensive in other environments. diff --git a/docs/learn/learn-nomination-pools.md b/docs/learn/learn-nomination-pools.md index 4125f1d71340..25275f0dc00d 100644 --- a/docs/learn/learn-nomination-pools.md +++ b/docs/learn/learn-nomination-pools.md @@ -16,9 +16,8 @@ You do not need to do anything, unless you are participating in a pool and also :::info Nomination Pools are live on Polkadot! Nomination pools are a new feature for Polkadot’s staking system that allows users to pool their -{{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} tokens together on-chain to nominate -validators and receive rewards, significantly improving the system’s scalability. Now, anyone with -as little as +tokens together on-chain to nominate validators and receive rewards, significantly improving the +system’s scalability. Now, anyone with as little as [1 DOT can receive rewards for staking natively on Polkadot](https://polkadot.network/blog/nomination-pools-are-live-stake-natively-with-just-1-dot/). Note that rewards are not guaranteed for those pools that do not have enough bonded funds to be included within the [bags list](./learn-staking-advanced.md#bags-list). **Only members of active @@ -50,34 +49,31 @@ Nomination Pools. If you are a developer, please join our ![Nomination Pools](../assets/staking/NPoS-Pools.png) -Nomination pools are one of the key features from the roadmap of staking improvements on -{{ kusama: Kusama :kusama }}{{ polkadot: Polkadot :polkadot }}. They are designed to -permissionlessly allow members to pool their funds together and act as a single nominator account. +Nomination pools are one of the key features from the roadmap of staking improvements. They are +designed to permissionlessly allow members to pool their funds together and act as a single +nominator account. -Due to the current runtime constraints, -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} can only handle -{{ polkadot: 22500 :polkadot }} {{ kusama: 12500 :kusama }} nominators comfortably in the +Due to the current runtime constraints, the relay chain can only handle a limited number of +nominators (22500 on Polkadot and 12500 on Kusama) comfortably in the [electing set](learn-nominator.md#staking-election-stages). As one of the objectives of the [NPoS algorithm](learn-phragmen.md) is to maximize the overall stake on the network, it can be -inferred that the staking system on {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} -favors nominators with a larger stake. Only the nominator accounts which back the validators in the -active set are eligible for receiving staking rewards. This leaves out nomination intents from the -accounts with lower token balance than the min-active nomination and places them in a waiting queue -to enter electing set. Nomination pools will be handy for members who want to participate in the -staking system with a stake much lower than the dynamic min-active nomination threshold on the -network. All operations are constant space and time complexity relative to the number of members, -eliminating any theoretical upper bound on the number of members the system can handle and thus -scaling the number of accounts that can participate and earn rewards in the staking system on -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}. In summary, each nomination pool is -viewed as a single nominator from the NPoS system point of view. +inferred that the staking system favors nominators with a larger stake. Only the nominator accounts +which back the validators in the active set are eligible for receiving staking rewards. This leaves +out nomination intents from the accounts with lower token balance than the min-active nomination and +places them in a waiting queue to enter electing set. Nomination pools will be handy for members who +want to participate in the staking system with a stake much lower than the dynamic min-active +nomination threshold on the network. All operations are constant space and time complexity relative +to the number of members, eliminating any theoretical upper bound on the number of members the +system can handle and thus scaling the number of accounts that can participate and earn rewards in +the staking system. In summary, each nomination pool is 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 -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} implements Nominated Proof of Staking -(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. +The term `delegator` is associated too much with Delegated Proof of Staking (DPoS), and since the +network implements Nominated Proof of Staking (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. ::: diff --git a/docs/learn/learn-nominator.md b/docs/learn/learn-nominator.md index 5d95584cfda8..a1576a8e903b 100644 --- a/docs/learn/learn-nominator.md +++ b/docs/learn/learn-nominator.md @@ -19,8 +19,9 @@ Discover the new [**Staking Dashboard**](https://staking.polkadot.cloud/#/overvi staking much easier and check this [extensive article list](https://support.polkadot.network/support/solutions/articles/65000182104) to help you get started. -{{ polkadot: You can now [stake natively with just 1 DOT and earn staking rewards](https://polkadot.network/blog/nomination-pools-are-live-stake-natively-with-just-1-dot/). :polkadot }} -{{ kusama: All the examples presented on Polkadot also apply to Kusama. :kusama }} + +You can now +[stake natively with just 1 DOT and earn staking rewards](https://polkadot.network/blog/nomination-pools-are-live-stake-natively-with-just-1-dot/). ::: @@ -47,10 +48,9 @@ Make sure you read those pages as well before nominating. ## Who are Nominators? -Nominators are one type of participant in the staking subsystem of -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}. They appoint their stake to the -validators, the second type of participant. By appointing their stake, they can elect the active set -of validators and share in the rewards that are paid out. +Nominators are one type of staking participant. They appoint their stake to the validators, the +second type of participant. By appointing their stake, they can elect the active set of validators +and share in the rewards that are paid out. While the [validators](../maintain/maintain-guides-how-to-validate-polkadot.md) are active participants in the network that engage in the block production and finality mechanisms, nominators @@ -62,57 +62,46 @@ being [slashed](./learn-offenses.md) if the validator gets slashed. ## Why Nominate? -- You become part of the {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} movement, a - group of diverse professionals and enthusiasts around the world aspiring to build and foster the - next-gen Internet, Web3: a decentralized, privacy-focused, and trustless internet. -- You are an essential piece of the puzzle, keeping - {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} secure. The bonded balance can be - used to vote in [Polkadot OpenGov](./learn-polkadot-opengov.md) and shape the future direction of - {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}. -- You will start to understand how {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} - works at a technical-level. When you feel comfortable with your nomination skills and knowledge, - you can open your [nomination pool](./learn-nomination-pools.md), help others secure the network - and earn rewards, and build your reputation as a trusted nomination pool operator. If you like to - be more involved, the next step is to become a [validator](./learn-validator.md). +- You become a network participant, a group of diverse professionals and enthusiasts around the + world aspiring to build and foster the next-gen Internet, Web3: a decentralized, privacy-focused, + and trustless internet. +- You are an essential piece of the puzzle, keeping the network secure. The bonded balance can be + used to vote in [Polkadot OpenGov](./learn-polkadot-opengov.md) and shape the network's future + direction. +- You will start to understand how Polkadot works at a technical-level. When you feel comfortable + with your nomination skills and knowledge, you can open your + [nomination pool](./learn-nomination-pools.md), help others secure the network and earn rewards, + and build your reputation as a trusted nomination pool operator. If you like to be more involved, + the next step is to become a [validator](./learn-validator.md). - By getting [staking](./learn-staking.md) rewards you keep up with or (likely) stay ahead of - {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} inflation. - -Nominators secure the relay chain by staking {{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} -and nominating validators. You may have an account with -{{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} and want to earn fresh -{{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }}. You could do so as a validator, which -requires experience setting up a node and running and maintaining it 24/7. - -On {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} you can also earn -{{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} by nominating one or more validators. Doing -so makes you a nominator for the validator(s) you chose. Pick your validators carefully - if they do -not behave properly, they will get slashed, and you will lose -{{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }}. However, if they follow the network rules, -you can share the staking rewards they generate. - -While your {{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} are staked for nominations, they -are 'locked' (bonded). You can + network inflation. + +Nominators secure the relay chain by staking native tokens (DOT on Polkadot or KSM on Kusama) and +nominating validators. You may have an account with DOT and want to earn fresh DOT. You could do so +as a validator, which requires experience setting up a node and running and maintaining it 24/7. + +On Polkadot, you can also earn DOT by nominating one or more validators. Doing so makes you a +nominator for the validator(s) you chose. Pick your validators carefully - +[if they do not behave properly, they will get slashed, and you will lose some DOT](./learn-offenses.md). +However, if they follow the network rules, you can share the staking rewards they generate. + +While your tokens are staked for nominations, they are 'locked' (bonded). You can [stop nominating at any time](./learn-guides-nominator.md#stop-nominating), but remember that the action is effective in the next era and does not automatically unbond your funds. Unbonding is a -separate action, and it takes effect after the unbonding period, which is -{{ polkadot: 28-day long on Polkadot :polkadot }}{{ kusama: 7-day long on Kusama :kusama }}. This is -calculated by taking the **bonding duration** (in eras), multiplying it by the **length of a single -era** (in hours), and dividing by the **hours in a day** (24). Example: -({{ polkadot: 28 × 24 ÷ 24 = 28 days :polkadot }}{{ kusama: 28 × 6 ÷ 24 = 7 days :kusama }}). A -staking lock will be visible on the Polkadot-JS UI during the unbonding period, and after it, the -staking lock can be unlocked, and the bonded funds become free balance you can transfer. +separate action, and it takes effect after the +[unbonding period](../general/chain-state-values.md#unbonding-duration). A staking lock will be +visible on the Polkadot-JS UI during the unbonding period, and after it, the staking lock can be +unlocked, and the bonded funds become free balance you can transfer. :::info Fast Unstaking -If you accidentally bonded your {{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} or your -bonded {{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} never backed any active validator, you +If you accidentally bonded your tokens or your bonded tokens never backed any active validator, you can now unbond them immediately. ::: -If your bonded balance did not back any validators in the last -{{ polkadot: 28 days on Polkadot (when the feature goes live) :polkadot }}{{ kusama: 7 days on Kusama :kusama }}, -you are eligible to perform fast unstaking. The +If your bonded balance did not back any validators in the last 28 days on Polkadot (7 days on +Kusama), you are eligible to perform fast unstaking. The [staking dashboard](https://staking.polkadot.cloud/#/overview) will automatically check if you qualify. For more information, visit the ["Fast Unstake" section in this support article](https://support.polkadot.network/support/solutions/articles/65000169433-can-i-transfer-dot-without-unbonding-and-waiting-28-days-). @@ -184,13 +173,14 @@ metrics shown as an example, followed by a brief description of each. all nominators who nominated Validator A. This includes the active count and all the other nominators whose stake in the current era is baking other validators. - Every nominator can select up to a maximum of {{ polkadot: 16 :polkadot }} - {{ kusama: 24 :kusama }} validators, which contributes towards maximizing the probability of - having the nominator’s stake applied to the validators active set. Nominating too few validators - could result in the nominators not receiving their rewards when none of them make it to the active - set or when those validators stop validating. The election algorithm attempts to maximize the - overall network stake while minimizing the variance of the active stake across the validators. For - additional information on the election process, check out the research behind + Every nominator can select up to + [a maximum number of validators](../general/chain-state-values.md#maximum-votes-per-nominator), + which contributes towards maximizing the probability of having the nominator’s stake applied to + the validators active set. Nominating too few validators could result in the nominators not + receiving their rewards when none of them make it to the active set or when those validators stop + validating. The election algorithm attempts to maximize the overall network stake while minimizing + the variance of the active stake across the validators. For additional information on the election + process, check out the research behind [nominated proof-of-stake](https://research.web3.foundation/Polkadot/protocols/NPoS). - **comm.**: Total commission kept by the validator (100% means the validator will keep all rewards @@ -203,13 +193,12 @@ metrics shown as an example, followed by a brief description of each. to payout their staking service clients and therefore do not provide any rewards to external nominators. The commission is just one piece of the puzzle you should consider when picking nominating validators. -- **total stake**: The total amount of {{ polkadot: DOT :polkadot }}{{ kusama: KSM :Kusama }} tokens - staked by nominators and the validator (i.e. own stake, see below). -- **own stake**: The amount of {{ polkadot: DOT :polkadot }}{{ kusama: KSM :Kusama }} tokens the - validator has put up as a stake. A higher own stake can be considered as having more "skin in the - game". This can imply increased trustworthiness. However, a validator not having a large amount of - "own stake" is not automatically untrustworthy, as the validator could nominate from a different - address. +- **total stake**: The total amount of tokens staked by nominators and the validator (i.e. own + stake, see below). +- **own stake**: The amount of tokens the validator has put up as a stake. A higher own stake can be + considered as having more "skin in the game". This can imply increased trustworthiness. However, a + validator not having a large amount of "own stake" is not automatically untrustworthy, as the + validator could nominate from a different address. - **return**: Average annual yield paid out to nominators (i.e. number of rewards divided by the number of bonded tokens). Note that nominating those with a higher yield may not guarantee similar future performance. @@ -348,8 +337,7 @@ fully distributed to one or more validators. That being said, you may not receiv nominated very few validator candidates and no one got elected, or your stake is small, and you are not part of the [top 22,500 nominators](./learn-staking-advanced.md#bags-list), or the validator you are nominating has 100% commission. It is generally wise to choose as many trustworthy validators as -you can {{ polkadot: (up to 16) :polkadot }}{{ kusama: (up to 24) :kusama }} to reduce the risk of -none of your nominated validators being elected. +you can to reduce the risk of none of your nominated validators being elected. :::info Not receiving Staking Rewards? @@ -404,18 +392,18 @@ Thus, for **nominator counters**, we have: - count of nominator intentions and [max possible nominator intentions](../general/chain-state-values.md#maximum-number-of-nominators) -- count of electing nominators, and maximum possible electing nominators - {{ polkadot: (22500) :polkadot }} {{ kusama: (12500) :kusama }} -- count of active nominators and maximum possible active nominators - {{ polkadot: (22500) :polkadot }} {{ kusama: (12500) :kusama }} +- count of electing nominators, and maximum possible electing nominators (22500 on Polkadot and + 12500 on Kusama) +- count of active nominators and maximum possible active nominators (22500 on Polkadot and 12500 on + Kusama) ### Active vs. Inactive Nomination When you go to the [Account actions](https://polkadot.js.org/apps/#/staking/actions) under staking page, you should see your bonded accounts and nomination status. If not, you can follow [this](./learn-guides-nominator.md#nominate-using-polkadot-js) guide to configure it first. Your -nominations will be effective in the next era; eras are roughly -{{ polkadot: 24 hours on Polkadot. :polkadot }}{{ kusama: 6 hours on Kusama. :kusama }} +nominations will be effective in the next era; eras are roughly 24 hours on Polkadot (6 hours on +Kusama). ![Nominations](../assets/staking/polkadotjs_nominator_account.png) diff --git a/docs/learn/learn-offenses.md b/docs/learn/learn-offenses.md index f0d47d36ff09..328c1a1d4b54 100644 --- a/docs/learn/learn-offenses.md +++ b/docs/learn/learn-offenses.md @@ -21,9 +21,8 @@ staked tokens via [Nominated Proof-of-Stake](./learn-staking.md#nominated-proof- ::: -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} is a public permissionless network. -As such, it has a mechanism to disincentivize offenses and incentivize good behavior. Below, you can -find a summary of punishments for specific offenses: +Polkadot is a public permissionless network. As such, it has a mechanism to disincentivize offenses +and incentivize good behavior. Below, you can find a summary of punishments for specific offenses: | Offense | [Slash (%)](#slashing) | [On-chain Disabling](#disabling) | Off-chain Disabling | [Reputational Changes](#reputation-changes) | | :----------------------------------: | :--------------------: | :------------------------------: | :-----------------: | :-----------------------------------------: | @@ -43,8 +42,7 @@ To better understand the terminology used for offenses, it is recommended to get ::: -On {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}, there are six main validator -offenses as shown below. +On Polkadot, there are six main validator offenses as shown below. - **Backing Invalid:** A para-validator is backing an invalid block. - **ForInvalid Vote:** A validator (secondary checker) votes in favor of an invalid block. @@ -90,21 +88,19 @@ never duplicated, the probability of an honest equivocation slash decreases to n ## Punishments -On {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}, offenses to the network can be -punished depending on their severity. There are three main punishments: slashing, disabling, and -reputation changes. +On Polkadot, offenses to the network can be punished depending on their severity. There are three +main punishments: slashing, disabling, and reputation changes. ### Slashing **Slashing** will happen if a validator misbehaves in the network. They and their nominators will -get slashed by losing a percentage of their staked -{{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }}, from as little as 0.01% up to 100%. - -Any slashed {{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} will be added to the -[Treasury](./archive/learn-treasury.md). The rationale for this (rather than burning or distributing -them as rewards) is that slashes may be reverted by simply paying out from the Treasury. This would -be useful in situations such as faulty slashes. In the case of legitimate slashing, tokens are moved -away from malicious validators to those building the ecosystem through the normal Treasury process. +get slashed by losing a percentage of their staked tokens, from as little as 0.01% up to 100%. + +Any slashed token will be added to the [Treasury](./archive/learn-treasury.md). The rationale for +this (rather than burning or distributing them as rewards) is that slashes may be reverted by simply +paying out from the Treasury. This would be useful in situations such as faulty slashes. In the case +of legitimate slashing, tokens are moved away from malicious validators to those building the +ecosystem through the normal Treasury process. Slashing only occurs for active validations for a given nominator, and slashes are not mitigated by having other inactive or waiting nominations. They are also not mitigated by the validator operator diff --git a/docs/learn/learn-parachains-faq.md b/docs/learn/learn-parachains-faq.md index e85bdd98a068..3d44c1848607 100644 --- a/docs/learn/learn-parachains-faq.md +++ b/docs/learn/learn-parachains-faq.md @@ -15,38 +15,34 @@ import MessageBox from "../../components/MessageBox"; import "../../components/M ### What is "parachain consensus"? -"Parachain consensus" is special in that it will follow the {{ polkadot: Polkadot :polkadot }} -{{ kusama: Kusama :kusama }} relay chain. Parachains cannot use other consensus algorithms that -provide their own finality. Only sovereign chains (that must bridge to the relay chain via a -parachain) can control their own consensus. Parachains have control over how blocks are authored and -by whom. {{ polkadot: Polkadot :polkadot }} {{ kusama: Kusama :kusama }} guarantees valid state -transitions. Executing a block finality outside the context of the relay chain is outside the scope -of trust that {{ polkadot: Polkadot :polkadot }} {{ kusama: Kusama :kusama }} provides. +"Parachain consensus" is special in that it will follow the relay chain. Parachains cannot use other +consensus algorithms that provide their own finality. Only sovereign chains (that must bridge to the +relay chain via a parachain) can control their own consensus. Parachains have control over how +blocks are authored and by whom. The relay chain guarantees valid state transitions. Executing a +block finality outside the context of the relay chain is outside the scope of trust that the relay +chain provides. ### How about parachains that are not Substrate-based? Substrate provides [FRAME Pallets](https://docs.substrate.io/main-docs/fundamentals/runtime-intro/) as part of its framework to seamlessly build a rustic-based blockchain. Part of FRAME are pallets -that can be used for consensus. {{ polkadot: Polkadot :polkadot }} {{ kusama: Kusama :kusama }} -being a Substrate-based chain rely on BABE as the block production scheme and GRANDPA as the -finality gadget as part of its consensus mechanism. Collectively, this is a -[Hybrid Consensus Model](learn-consensus.md#hybrid-consensus), where block production and block -finality are separate. Parachains only need to produce blocks as they can rely on the relay chain to -validate the state transitions. Thus, parachains can have their own block production where the -[collators](learn-collator.md) act as the block producers, even if the parachain is not -Substrate-based. +that can be used for consensus. Polkadot, being a Substrate-based chain, relies on BABE as the block +production scheme and GRANDPA as the finality gadget as part of its consensus mechanism. +Collectively, this is a [Hybrid Consensus Model](learn-consensus.md#hybrid-consensus), where block +production and block finality are separate. Parachains only need to produce blocks as they can rely +on the relay chain to validate the state transitions. Thus, parachains can have their own block +production where the [collators](learn-collator.md) act as the block producers, even if the +parachain is not Substrate-based. ### Is 100 a hard limit on the number of Parachains that can be supported? -No.{{ polkadot: Polkadot :polkadot }} {{ kusama: Kusama :kusama }} network went through a -significant number of optimizations, and there are +No. The network went through a significant number of optimizations, and there are [several updates planned](https://polkadot.network/blog/polkadot-roadmap-roundup/) in the near future. The exact number of parachains that the relay chain can support without any degradation in performance is yet to be discovered. Also, with the [blockspace over blockchains](https://www.rob.tech/polkadot-blockspace-over-blockchains/) paradigm which brings on-demand parachains into the picture, there is no hard limit number on the number of -blockchains that can be supported by {{ polkadot: Polkadot :polkadot }} -{{ kusama: Kusama :kusama }}. +blockchains that can be supported by the relay chain. ### What happens to parachains when the number of validators drops below a certain threshold? @@ -127,16 +123,14 @@ leveraged for something else. The method for dividing the parachain slots into intervals was partly inspired by the desire to allow for a greater amount of parachain diversity, while preventing particularly large and -well-funded parachains from hoarding slots. By making each period a -{{ polkadot: three-month duration but the -overall slot a 2-year duration :polkadot }}{{ kusama: 6-week duration but the overall slot a 1-year -duration :kusama }}, the mechanism can cope with well-funded parachains, ensuring they secure a slot -at the end of their lease, while gradually allowing other parachains to enter the ecosystem to -occupy the durations that are not filled. For example, if a large, well-funded parachain has already -acquired a slot for range 1 - 8, they would be very interested in getting the next slot that would -open for 2 - 9. Under this mechanism, that parachain could acquire just period 9 (since that is the -only one required) and allow the 2 - 8 range of the second parachain slot to be occupied by another -party. +well-funded parachains from hoarding slots. By making each period a three-month duration but the +overall slot a 2-year duration (and 6-week duration but the overall slot a 1-year duration on +Kusama), the mechanism can cope with well-funded parachains, ensuring they secure a slot at the end +of their lease, while gradually allowing other parachains to enter the ecosystem to occupy the +durations that are not filled. For example, if a large, well-funded parachain has already acquired a +slot for range 1 - 8, they would be very interested in getting the next slot that would open for +2 - 9. Under this mechanism, that parachain could acquire just period 9 (since that is the only one +required) and allow the 2 - 8 range of the second parachain slot to be occupied by another party. ### Why is randomness difficult on blockchains? @@ -144,8 +138,7 @@ Generating a random number trustlessly on a transparent and open network opens u for bad actors to attempt to alter or manipulate the randomness. There have been a few solutions that have been proposed, including hash-onions like [RANDAO](https://github.com/randao/randao) and [verifiable random functions](https://en.wikipedia.org/wiki/Verifiable_random_function) (VRFs). The -latter is what {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} uses as a base for its -randomness. +latter is what the relay chain uses as a base for its randomness. ### Are there other ways of acquiring a slot besides the candle auction? diff --git a/docs/learn/learn-parachains-protocol.md b/docs/learn/learn-parachains-protocol.md index f96e89797195..ae39a1b8f6e7 100644 --- a/docs/learn/learn-parachains-protocol.md +++ b/docs/learn/learn-parachains-protocol.md @@ -51,21 +51,18 @@ its full state. ### Fishermen: Deprecated -Fishermen are not available on {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} and -are not planned for formal implementation, despite previous proposals in the +Fishermen are not planned for formal implementation, despite previous proposals in the [AnV protocol](./learn-parachains-protocol.md#availability-and-validity-anv-protocol). The idea behind Fishermen is that they are full nodes of parachains, like collators, but perform a -different role in relation to the {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} -network. Instead of packaging the state transitions and producing the next parachain blocks as -collators do, fishermen will watch this process and ensure no invalid state transitions are -included. +different role in relation to the network. Instead of packaging the state transitions and producing +the next parachain blocks as collators do, fishermen will watch this process and ensure no invalid +state transitions are included. To address the motivation behind the Fishermen design consideration, the current [secondary backing checkers](#assignments--secondary-checks) perform a similar role in relation to -the {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} network. From a security -standpoint, security is based on having at least one honest validator either among parachain -validators or secondary checker (more about this later on). +the network. From a security standpoint, security is based on having at least one honest validator +either among parachain validators or secondary checker (more about this later on). ## Protocols' Summary @@ -176,8 +173,8 @@ later on) that will be sent to all validators in the network. :::info Polkadot guarantees valid state transitions, not valid states -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} validators do not inspect every value -in a parachain's state, only those that are modified. This insures that the modification is valid. +Validators do not inspect every value in a parachain's state, only those that are modified. This +insures that the modification is valid. ::: @@ -210,14 +207,13 @@ the network can consider the candidate block available. The block is graduated t parachain block, and its header will be included in that fork of the relay chain. The information about the candidate availability is noted in the subsequent relay chain blocks of that fork. -The availability check by the block author ensures that -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} will only include blocks for which -the validators distributed their erasure-coded chunks, but it does not guarantee their validity. -Because the number of para-validators on each parachain is so low, collusion is a reasonable -concern. By separating block production ([BABE](./learn-consensus.md#block-production-babe)) from -finality ([GRANDPA](./learn-consensus.md/#finality-gadget-grandpa)), -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} can perform extra validity checks -after a block is produced but before it is finalized. +The availability check by the block author ensures that the relay chain will only include blocks for +which the validators distributed their erasure-coded chunks, but it does not guarantee their +validity. Because the number of para-validators on each parachain is so low, collusion is a +reasonable concern. By separating block production +([BABE](./learn-consensus.md#block-production-babe)) from finality +([GRANDPA](./learn-consensus.md/#finality-gadget-grandpa)), validators can perform extra validity +checks after a block is produced but before it is finalized. Thus, once the parablock is considered available and part of the parachain, it is still "pending approval". The Inclusion Pipeline must conclude for a specific parachain before a new block can be @@ -387,9 +383,9 @@ For detailed information about chain selection, see dedicated section in ## Candidate Receipts PoV are typically between 1 MB and 10 MB in size and are not included in the relay chain blocks. For -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} to scale to hundreds of parachains, -PoV need to be represented by something smaller on the relay chain: candidate receipts. A -para-validator constructs a candidate receipt for a parachain block by signing: +Polkadot to scale to hundreds of parachains, PoV need to be represented by something smaller on the +relay chain: candidate receipts. A para-validator constructs a candidate receipt for a parachain +block by signing: - The parachain ID. - The collator's ID and signature. @@ -411,31 +407,29 @@ constructs the receipt must also construct an erasure coding of the parachain bl An erasure coding takes a message (in this case, the parachain block and PoV) and creates a set of smaller messages such that you can reconstruct the original message by obtaining a fraction of the -smaller messages. In the case of {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} the -total number of smaller messages is equal to the total number of validators and the fraction is 1/3. +smaller messages. In the case of Polkadot, the total number of smaller messages is equal to the +total number of validators and the fraction is 1/3. The para-validator creates the erasure coding chunks, puts them into their Merkle tree, and sends out each chunk (together with the candidate receipt) to a corresponding validator on the Relay Chain. Validators who receive the receipts with an erasure coding chunk will include the receipt in the relay chain queue, where an author can include it in a block. -The type of erasure codes used by {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}'s -availability scheme are +The type of erasure codes used by Polkadot's availability scheme are [Reed-Solomon](https://en.wikipedia.org/wiki/Reed%E2%80%93Solomon_error_correction) codes, which already enjoy a battle-tested application in technology outside the blockchain industry. One example is found in the compact disk industry. CDs use Reed-Solomon codes to correct any missing data due to inconsistencies on the disk face such as dust particles or scratches. -In {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}, the erasure codes are used to -keep parachain state available to the system without requiring all validators to keep tabs on all -the parachains. Instead, validators share smaller pieces of the data and can later reconstruct the -entire data under the assumption that 1/3+1 of the validators can provide their pieces of the data. +In Polkadot, the erasure codes are used to keep parachain state available to the system without +requiring all validators to keep tabs on all the parachains. Instead, validators share smaller +pieces of the data and can later reconstruct the entire data under the assumption that 1/3+1 of the +validators can provide their pieces of the data. :::note The 1/3+1 threshold of validators that must be responsive to construct the full parachain state data -corresponds to {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}'s security assumption -about Byzantine nodes. +corresponds to Polkadot's security assumption about Byzantine nodes. ::: diff --git a/docs/learn/learn-parachains.md b/docs/learn/learn-parachains.md index 8b4897c886f5..b8cbca0c8472 100644 --- a/docs/learn/learn-parachains.md +++ b/docs/learn/learn-parachains.md @@ -14,9 +14,7 @@ import MessageBox from "../../components/MessageBox"; import "../../components/M :::info Testing on Rococo For information on how to participate in the crowdloan and parachain auction testing on Rococo, -please see the -{{ polkadot: [Rococo Content](../build/build-parachains.md##testing-a-parachains:-rococo-testnet) :polkadot }} -{{ kusama: [Rococo Content](../build/build-parachains.md##testing-a-parachains:-rococo-testnet) :kusama }} +please see the [Rococo Content](../build/build-parachains.md##testing-a-parachains:-rococo-testnet) on the parachain development guide. ::: @@ -31,17 +29,15 @@ but there is no specific need for them to be actual blockchains. ![One parachain](../assets/one-parachain.png) Due to their parallel nature, they can parallelize transaction processing and achieve scalability of -the {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} protocol. They -[inherit the security](#shared-security) of the entire network and can communicate with other -parachains through the [XCM](learn-xcm.md) format. +the protocol. They [inherit the security](#shared-security) of the entire network and can +communicate with other parachains through the [XCM](learn-xcm.md) format. Parachains are maintained by a network maintainer known as a [collator](learn-collator.md). The role of the collator node is to maintain a full node of the parachain, retain all necessary information about the parachain, and produce new block candidates to pass to the relay chain validators for -verification and inclusion in the shared state of -{{ polkadot: Polkadot. :polkadot }}{{ kusama: Kusama. :kusama }} The incentivization of a collator -node is an implementation detail of the parachain. They are not required to be staked on the Relay -Chain or own the native token unless stipulated by the parachain implementation. +verification and inclusion in the shared state. The incentivization of a collator node is an +implementation detail of the parachain. They are not required to be staked on the Relay Chain or own +the native token unless stipulated by the parachain implementation. ### State Transitions @@ -51,25 +47,23 @@ Petrowski provided in [this article](https://polkadot.network/blog/the-path-of-a good analogy of a state with a light switch that can be either on or off, which is one of the simplest examples of how a state machine functions. Each parachain has its own state, and the Relay Chain links all those states into one state, i.e. a state of states. A multi-chain network like -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} can be viewed like one computer's -state with many light switches where a **state transition function** is the logic to decide which -switches should be toggled. Parachains have their own transition rule, separate economies, -governance mechanisms, and users. +Polkadot can be viewed like one computer's state with many light switches where a **state transition +function** is the logic to decide which switches should be toggled. Parachains have their own +transition rule, separate economies, governance mechanisms, and users. A parachain's state is stored in a [Merkle tree](https://en.wikipedia.org/wiki/Merkle_tree). Merkle trees have the convenient property that if some values within the tree change, this will be reflected in the Merkle root (in this case, the state root). One can verify the change by only looking at the new values and the paths that are affected within the tree. -The {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} Host requires that the state -transitions performed on parachains be specified as a [Wasm](learn-wasm.md) executable. Proofs of -new state transitions that occur on a parachain must be validated against the registered state -transition function (STF) that is stored on the relay chain by the validators before -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} acknowledges a state transition has -occurred on a parachain. The key constraint regarding the logic of a parachain is that it must be -verifiable by the relay chain validators. Verification most commonly takes the form of a bundled -proof of a state transition known as a Proof-of-Verification (PoV) block, which is submitted for -checking to the validators from one or more parachain collators. +The Polkadot Host requires that the state transitions performed on parachains be specified as a +[Wasm](learn-wasm.md) executable. Proofs of new state transitions that occur on a parachain must be +validated against the registered state transition function (STF) that is stored on the relay chain +by the validators before the relay chain acknowledges a state transition has occurred on a +parachain. The key constraint regarding the logic of a parachain is that it must be verifiable by +the relay chain validators. Verification most commonly takes the form of a bundled proof of a state +transition known as a Proof-of-Verification (PoV) block, which is submitted for checking to the +validators from one or more parachain collators. ## Why Parachains? @@ -87,10 +81,10 @@ Parachains are a solution to two fundamental problems in blockchains: ### Parachain Benefits Parachains contain their own runtime/STF logic and benefit from the shared security and the -cross-consensus messaging provided by the {{ polkadot: Polkadot :polkadot }} relay chain. Parachains -permit high flexibility and customization but require more effort to create and maintain over time. -A production-grade parachain is typically more involved to create due to the complexity involved in -blockchain networks' technical and economic aspects. +cross-consensus messaging provided by the relay chain. Parachains permit high flexibility and +customization but require more effort to create and maintain over time. A production-grade parachain +is typically more involved to create due to the complexity involved in blockchain networks' +technical and economic aspects. Parachains grant the creators more space to build the monetary system and other chain aspects from the ground up. They will allow for a more concise and efficient execution of complex logic than a @@ -110,11 +104,9 @@ Some examples of features you can have on a parachain or parathread: ### Shared Security Shared security, sometimes referred as _pooled security_, is one of the unique value propositions -for chains considering becoming a [parachain](learn-parachains.md) and joining the -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} network. On a high level, shared -security means that all parachains that are connected to the -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} relay chain by leasing a parachain -slot will benefit from the economic security provided by the relay chain +for chains considering becoming a [parachain](learn-parachains.md) and joining the network. On a +high level, shared security means that all parachains that are connected to the relay chain by +leasing a parachain slot will benefit from the economic security provided by the relay chain [validators](learn-validator.md). The notion of shared security is different from inter-chain protocols that build on an architecture @@ -129,20 +121,18 @@ recently ( ), in which an unknown attacker double spent 219_500 ETC (~1.1 million USD). This was followed by two more 51% attacks on ETC. -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} overcomes security scalability -concerns since it gravitates all the economic incentives to the relay chain and allows the -parachains to tap into stronger guarantees at genesis. Sovereign chains must expend much more effort -to grow the value of their coin so that it is sufficiently secure against well-funded attackers. +Polkadot overcomes security scalability concerns since it gravitates all the economic incentives to +the relay chain and allows the parachains to tap into stronger guarantees at genesis. Sovereign +chains must expend much more effort to grow the value of their coin so that it is sufficiently +secure against well-funded attackers. ### PoW vs Parachain Model Let's compare the standard sovereign security model that exists on current proof-of-work (PoW) -chains to that of the shared security of -{{ polkadot: Polkadot. :polkadot }}{{ kusama: Kusama. :kusama }} Chains secured by their security -models, like Bitcoin, Zcash, and their derivatives, must bootstrap their independent network of -miners and maintain a competitive portion of honest hashing power. Since mining is becoming a larger -industry that increasingly centralizes key players, it is becoming more real that a single actor may -control enough hash power to attack a chain. +chains to Polkadot's shared security model. Bitcoin, Zcash, and their derivatives, must bootstrap +their independent network of miners and maintain a competitive portion of honest hashing power. +Since mining is becoming a larger industry that increasingly centralizes key players, it is becoming +more real that a single actor may control enough hash power to attack a chain. This means that smaller chains that cannot maintain a secure amount of hash power on their networks could potentially be attacked by a large mining cartel at the simple whim of redirecting its hash @@ -152,54 +142,49 @@ Ethereum Classic (see above), [Verge](https://coincentral.com/verge-suffers-51-attack-hard-forks-in-response/), [Bitcoin Gold](https://bitcoingold.org/responding-to-attacks/), and other cryptocurrencies. -On {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}, this disparity between chain -security will not be present. When a parachain connects to -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}, the relay chain validators become -the securers of that parachain's state transitions. The parachain will only have the overhead of -running a few collator nodes to keep the validators informed with the latest state transitions and -proofs/witness. Validators will then check these for the parachains to which they are assigned. In -this way, new parachains instantly benefit from the overall security of -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} even if they have just been launched. +On Polkadot, this disparity between chain security will not be present. When a parachain connects to +the relay chain, validators become the securers of that parachain's state transitions. The parachain +will only have the overhead of running a few collator nodes to keep the validators informed with the +latest state transitions and proofs/witness. Validators will then check these for the parachains to +which they are assigned. In this way, new parachains instantly benefit from the overall security +provided by the relay chain even if they have just been launched. ## Parachain Economies Parachains may have their economies with their native tokens. Schemes such as Proof-of-Stake are usually used to select the validator set to handle validation and finalization; parachains will not -be required to do either of those things. However, since -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} is not overly particular about what -the parachain can implement, it may be the choice of the parachain to implement a staking token, but -it's not generally necessary. +be required to do either of those things. However, since Polkadot is not overly particular about +what the parachain can implement, it may be the choice of the parachain to implement a staking +token, but it's not generally necessary. Collators may be incentivized through the inflation of a native parachain token. There may be other ways to incentivize the collator nodes that do not involve inflating the native parachain token. Transaction fees in a native parachain token can also be an implementation choice of parachains. -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} makes no hard and fast rules for how -the parachains decide on the original validity of transactions. For example, a parachain may be -implemented so that transactions must pay a minimum fee to collators to be valid. The relay chain -will enforce this validity. Similarly, a parachain could not include that in their implementation, -and {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} would still enforce its validity. +Polkadot makes no hard and fast rules for how the parachains decide on the original validity of +transactions. For example, a parachain may be implemented so that transactions must pay a minimum +fee to collators to be valid. The relay chain will enforce this validity. Similarly, a parachain +could not include that in their implementation, and the relay chain would still enforce its +validity. -Parachains are not required to have their token. If they do, it is up to the parachain to make the -economic case for their token, not {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}. +Parachains are not required to have their token. If they do, it is up to the parachain (and not the +relay chain) to make the economic case for their token. ## Parachain Slot Acquisition -There are two ways to allocate parachain slots on -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}: +There are two ways to allocate parachain slots: - Governance granted parachains, or "system parachains" - Auction granted parachains -[System parachains](#system-parachains) are allocated by -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}'s on-chain +[System parachains](#system-parachains) are allocated by Polkadot's on-chain [governance](./learn-polkadot-opengov.md) and are part of the network's protocol, such as bridges to other networks or chains. These typically do not have an economic model and help remove transactions from the relay chain, allowing for more efficient parachain processing. [Auction granted parachains](learn-auction.md) are granted in a permissionless auction. Parachain -teams can either bid with their own {{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} tokens, -or source them from the community using the [crowdloan functionality](learn-crowdloans.md). +teams can either bid with their own DOT (or KSM on Kusama) tokens, or source them from the community +using the [crowdloan functionality](learn-crowdloans.md). ### Parachain Lease Expiration @@ -230,15 +215,14 @@ On-demand parachains (previously called parathreads) are parachains that acquire ::: -On-demand parachains temporarily participate (on a block by block basis) in -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} security without needing to lease a -dedicated parachain slot. This is done through economically sharing the scarce resource of a -_parachain slot_ (or core) among several competing resources (parachains). Chains that otherwise -would not be able to acquire a full parachain slot or do not find it economically sensible to do so, -can participate in {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}'s shared security -as the [on-demand coretime](./learn-agile-coretime.md#on-demand-coretime) offers a graceful off-ramp -to parachains that no longer require a dedicated parachain slot, but would like to continue using -the relay chain. +On-demand parachains temporarily participate (on a block by block basis) in network security without +needing to lease a dedicated parachain slot. This is done through economically sharing the scarce +resource of a _parachain slot_ (or core) among several competing resources (parachains). Chains that +otherwise would not be able to acquire a full parachain slot or do not find it economically sensible +to do so, can participate in shared security as the +[on-demand coretime](./learn-agile-coretime.md#on-demand-coretime) offers a graceful off-ramp to +parachains that no longer require a dedicated parachain slot, but would like to continue using the +relay chain. ### Historical Context of On-demand parachains @@ -263,11 +247,10 @@ states: It can switch between these states with relatively minimal effort since the difference is more of an economic distinction than a technological one. -On-demand parachains have the exact same benefits for connecting to -{{ polkadot: Polkadot :polkadot }} {{ kusama: Kusama :kusama }} that a full parachain has. Namely, -it is able to send messages to other para-objects through [XCMP](learn-xcm.md###XCMP) and it is -secured under the full economic security of {{ polkadot: Polkadot :polkadot }} -{{ kusama: Kusama :kusama }}'s validator set. +On-demand parachains have the exact same benefits for connecting to the relay chain that a full +parachain has. Namely, it is able to send messages to other para-objects through +[XCMP](learn-xcm.md###XCMP) and it is secured under the full economic security of the relay chain +validator set. ## Parachains' Use Cases @@ -286,12 +269,10 @@ a few examples. ## Parachain Host -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} includes a blockchain called a relay -chain. A blockchain is a -[Directed Acyclic Graph](https://en.wikipedia.org/wiki/Directed_acyclic_graph) (DAG) of state -transitions, where every added block can be viewed as the head of the chain or fork with cumulative -state. All paths through the DAG terminate at the Genesis Block. A blockchain is a tree, as each -block can have only one parent. +A blockchain is a [Directed Acyclic Graph](https://en.wikipedia.org/wiki/Directed_acyclic_graph) +(DAG) of state transitions, where every added block can be viewed as the head of the chain or fork +with cumulative state. All paths through the DAG terminate at the Genesis Block. A blockchain is a +tree, as each block can have only one parent. A blockchain network is made of nodes that have a view of many forks of the chain and must decide which fork to follow. To construct the parachain host we need to answer two categories of questions @@ -355,14 +336,13 @@ necessary to determine which action to take. ## Parachain Hubs -While {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} enables crosschain -functionality amongst the parachains, it necessitates that there is some latency between the -dispatch of a message from one parachain until the destination parachain receives the message. In -the optimistic scenario, the latency for this message should be at least two blocks - one block for -the message to be dispatched and one block for the receiving parachain to process and produce a -block that acts upon the message. However, in some cases, we may see that the latency for messages -is higher if many messages are in queue to be processed or if no nodes are running both parachain -networks that can quickly gossip the message across the networks. +While the relay chain enables crosschain functionality amongst the parachains, it necessitates that +there is some latency between the dispatch of a message from one parachain until the destination +parachain receives the message. In the optimistic scenario, the latency for this message should be +at least two blocks - one block for the message to be dispatched and one block for the receiving +parachain to process and produce a block that acts upon the message. However, in some cases, we may +see that the latency for messages is higher if many messages are in queue to be processed or if no +nodes are running both parachain networks that can quickly gossip the message across the networks. Due to the necessary latency in sending crosschain messages, some parachains plan to become _hubs_ for an entire industry (see the [Asset Hub](./learn-assets.md) and diff --git a/docs/learn/learn-phragmen.md b/docs/learn/learn-phragmen.md index e37af4357319..8949c856a37c 100644 --- a/docs/learn/learn-phragmen.md +++ b/docs/learn/learn-phragmen.md @@ -9,11 +9,9 @@ slug: ../learn-phragmen ## NPoS Election Algorithms -Since validators are paid almost equally in -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} in each era, it is important that the -stake behind each validator is uniformly spread out. An election algorithm for Nominated Proof of -Staking (NPoS) on {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} will try to -optimize three metrics when computing a solution graph of nominators and validators: +Since validators are paid almost equally in in each era, it is important that the stake behind each +validator is uniformly spread out. An election algorithm for Nominated Proof of Staking (NPoS) will +try to optimize three metrics when computing a solution graph of nominators and validators: 1. Maximize the total amount at stake. 1. Maximize the stake behind the minimally staked validator. @@ -52,10 +50,10 @@ also tries to equalize the weights between the validators after each election ro #### Off-Chain Phragmén Given the large set of nominators and validators, Phragmén's method is a difficult optimization -problem. {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} uses off-chain workers to -compute the result off-chain and submit a transaction to propose the set of winners. The reason for -performing this computation off-chain is to keep a constant block time of six seconds and prevent -long block times at the end of each era, when the validator election takes place. +problem. Polkadot uses off-chain workers to compute the result off-chain and submit a transaction to +propose the set of winners. The reason for performing this computation off-chain is to keep a +constant block time of six seconds and prevent long block times at the end of each era, when the +validator election takes place. :::info Staking Miners @@ -230,15 +228,13 @@ is `2`, etc. ### Rationale -While this method works well if all voters have equal weight, this is not the case in -{{ polkadot: Polkadot. :polkadot }}{{ kusama: Kusama. :kusama }} Elections for both validators and -candidates for the {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} Council are -weighted by the number of tokens held by the voters. This makes elections more similar to a -corporate shareholder election than a traditional political election, where some members have more -pull than others. Someone with a single token will have much less voting power than someone -with 100. Although this may seem anti-democratic, in a pseudonymous system, it is trivial for -someone with 100 tokens to create 100 different accounts and spread their wealth to all of their -pseudonyms. +While this method works well if all voters have equal weight, this is not the case in Polkadot. +Elections for both validators and candidates for the Council are weighted by the number of tokens +held by the voters. This makes elections more similar to a corporate shareholder election than a +traditional political election, where some members have more pull than others. Someone with a single +token will have much less voting power than someone with 100. Although this may seem +anti-democratic, in a pseudonymous system, it is trivial for someone with 100 tokens to create 100 +different accounts and spread their wealth to all of their pseudonyms. Therefore, not only do we want to allow voters to have their preferences expressed in the result, but do so while keeping as equal a distribution of their stake as possible and express the wishes of @@ -633,11 +629,10 @@ to nominate. ### Phragmms (aka Balphragmms) `Phragmms`, formerly known as `Balphragmms`, is a new election rule inspired by Phragmén and -developed in-house for {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}. In general, -election rules on blockchains is an active topic of research. This is due to the conflicting -requirements for election rules and blockchains: elections are computationally expensive, but -blockchains are computationally limited. Thus, this work constitutes state of the art in terms of -optimization. +developed in-house for Polkadot. In general, election rules on blockchains is an active topic of +research. This is due to the conflicting requirements for election rules and blockchains: elections +are computationally expensive, but blockchains are computationally limited. Thus, this work +constitutes state of the art in terms of optimization. Proportional representation is a very important property for a decentralized network to have in order to maintain a sufficient level of decentralization. While this is already provided by the @@ -646,10 +641,10 @@ security guarantee described below. As far as we can tell, at the time of writin Kusama are the only blockchain networks that implement an election rule that guarantees proportional representation. -The security of a distributed and decentralized system such as -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} is directly related to the goal of -avoiding _overrepresentation_ of any minority. This is a stark contrast to traditional approaches to -proportional representation axioms, which typically only seek to avoid underrepresentation. +The security of a distributed and decentralized system such as Polkadot is directly related to the +goal of avoiding _overrepresentation_ of any minority. This is a stark contrast to traditional +approaches to proportional representation axioms, which typically only seek to avoid +underrepresentation. #### Maximin Support Objective and PJR @@ -672,10 +667,10 @@ strength deserve to have a number of representatives proportional to the group _Sequential Phragmén_ (`seqPhragmen`) and `MMS` are two efficient election rules that both achieve PJR. -Currently, {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} employs the `seqPhragmen` -method for validator and council elections. Although `seqPhramen` has a very fast runtime, it does -not provide constant-factor approximation for the maximin support problem. This is due to -`seqPhramen` only performing an _approximate_ rebalancing of the distribution of stake. +Currently, Polkadot employs the `seqPhragmen` method for validator and council elections. Although +`seqPhramen` has a very fast runtime, it does not provide constant-factor approximation for the +maximin support problem. This is due to `seqPhramen` only performing an _approximate_ rebalancing of +the distribution of stake. In contrast, `MMS` is another standard greedy algorithm that simultaneously achieves the PJR property and provides a constant factor approximation for maximin support, although with a @@ -727,10 +722,9 @@ inserts them with higher support values. - Unlike `seqPhragmen`, in `Phragmms`, the edge weight vector _w_ is completely rebalanced after each iteration of the algorithm. -The `Phragmms` election rule is currently being implemented on -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}. Once completed, it will become one -of the most sophisticated election rules implemented on a blockchain. For the first time, this -election rule will provide both fair representation (PJR) and security (constant-factor +The `Phragmms` election rule is currently being implemented on Polkadot. Once completed, it will +become one of the most sophisticated election rules implemented on a blockchain. For the first time, +this election rule will provide both fair representation (PJR) and security (constant-factor approximation for the maximin support objection) to a blockchain network. #### Algorithm diff --git a/docs/learn/learn-polkadot-opengov-treasury.md b/docs/learn/learn-polkadot-opengov-treasury.md index aa01ea5d602d..fee90033cb51 100644 --- a/docs/learn/learn-polkadot-opengov-treasury.md +++ b/docs/learn/learn-polkadot-opengov-treasury.md @@ -88,9 +88,8 @@ bottom right corner. Then, ![polkassembly-write-proposal](../assets/polkassembly-write-proposal.png) - Create a preimage: an existing preimage can be linked, or a new one can be created. To create a - preimage, add the beneficiary address and the - {{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} amount. The track will be auto-selected - and the user can proceed with the creation of a preimage. + preimage, add the beneficiary address and the token amount. The track will be auto-selected and + the user can proceed with the creation of a preimage. ![polkassembly-create-preimage](../assets/polkassembly-create-preimage.png) @@ -99,13 +98,11 @@ bottom right corner. Then, ## Sub-treasuries -The {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} treasury currently operates on a -single account on-chain. The above tracks manage the outflow of the treasury on the network. With -_sub_-treasuries, having treasury accounts that correspond to each +The treasury currently operates on a single account on-chain. The above tracks manage the outflow of +the treasury on the network. With _sub_-treasuries, having treasury accounts that correspond to each [collective](./learn-system-chains#collectives) is also possible. -Rather than have many referenda through OpenGov, the -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} Treasury can allocate funds to each +Rather than have many referenda through OpenGov, the treasury can allocate funds to each sub-treasury (through [governance](./learn-polkadot-opengov)), from which each respective collective can spend funds (depending on their specific rule set). @@ -115,16 +112,15 @@ instances of this pallet. ## Multi-Asset Treasury Support -The treasuries can support multiple asset types and thus can spend assets other than -{{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} held within the treasury, and their transfers -and interactions across the chains facilitated by [cross-consensus messaging](./learn-xcm.md). These -assets have a few requirements: +The treasuries can support multiple asset types and thus can spend assets other than DOT (or KSM on +Kusama) held within the treasury, and their transfers and interactions across the chains facilitated +by [cross-consensus messaging](./learn-xcm.md). These assets have a few requirements: 1. The asset is listed on the [AssetHub system parachain](https://assethub-polkadot.subscan.io/). 2. The asset is active and has sufficient liquidity to be utilized for payouts. 3. The asset has a set conversion rate, as per OpenGov referenda on the Treasurer track (set via the asset rate pallet). This conversion rate defines a fixed-point representation for converting from - that asset to {{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }}. + that asset to the native asset (DOT or KSM). 4. The asset must be approved and onboarded via OpenGov to become spendable via the treasury as a valid spend method. @@ -150,7 +146,7 @@ Bounties are managed by curators, where the curator is usually a so managing those funds with a multisig is a good practice to enhance security. Essentially, curators are multisig addresses with agency over a portion of the treasury to promote events, fix a bug or vulnerability, develop a strategy, or monitor a set of tasks related to a specific topic, all -for the benefit of the {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} ecosystem. +for the benefit of the ecosystem. A proposer can [submit a bounty proposal](./learn-guides-bounties.md#submit-a-bounty-proposal) to OpenGov, diff --git a/docs/learn/learn-polkadot-opengov.md b/docs/learn/learn-polkadot-opengov.md index 4e5da766193f..6d95d8cc9245 100644 --- a/docs/learn/learn-polkadot-opengov.md +++ b/docs/learn/learn-polkadot-opengov.md @@ -24,20 +24,19 @@ For additional support about Polkadot OpenGov, see the ::: -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} uses a sophisticated governance -mechanism that allows it to evolve gracefully overtime at the ultimate behest of its assembled -stakeholders. The goal is to ensure that most of the stake can always command the network. +Polkadot uses a sophisticated governance mechanism that allows it to evolve gracefully overtime at +the ultimate behest of its assembled stakeholders. The goal is to ensure that most of the stake can +always command the network. -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} brings together various novel -mechanisms, including an amorphous (abstract) form of state-transition function stored on-chain -defined in a platform-agnostic language (i.e. [WebAssembly](learn-wasm.md)), and several on-chain -voting mechanisms such as referenda and batch approval voting. All changes to the protocol must be -agreed upon by stake-weighted referenda. +Polkadot brings together various novel mechanisms, including an amorphous (abstract) form of +state-transition function stored on-chain defined in a platform-agnostic language (i.e. +[WebAssembly](learn-wasm.md)), and several on-chain voting mechanisms such as referenda and batch +approval voting. All changes to the protocol must be agreed upon by stake-weighted referenda. ## Premise -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}'s first governance system -([Governance V1](./archive/learn-governance.md)) included three main components. +Polkadot's first governance system ([Governance V1](./archive/learn-governance.md)) included three +main components. - The [Technical Committee](./archive/learn-governance.md#technical-committee): A technocratic committee to manage upgrade timelines. @@ -51,19 +50,17 @@ mature to improve their shortcomings and keep up with modern advancements. In Go referenda carried the same weight as only one referendum could be voted on at a time (except for emergency proposals), and the voting period could last multiple weeks. Also, an [alternating voting timetable](./archive/learn-governance.md#alternating-voting-timetable) allowed -to vote either for a public referendum or a council motion every -{{ polkadot: 28 days :polkadot }}{{ kusama: 7 days :kusama }}. This resulted in the system favoring -careful consideration of very few proposals instead of broad consideration of many. +to vote either for a public referendum or a council motion every 28 days (7 days on Kusama). This +resulted in the system favoring careful consideration of very few proposals instead of broad +consideration of many. Polkadot OpenGov changes how the practical means of day-to-day decisions are made, making the repercussions of referenda better scoped and agile to increase the number of collective decisions the system can make at any given time. -The following content is focused on what the new Polkadot OpenGov version brings to the governance -on {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}, and on the main differences with -previous governance versions. We recommend learning about -[Governance v1](./archive/learn-governance.md) to better understand the need for and the direction -of Polkadot OpenGov. +The following content is focused on Polkadot OpenGov, and on the main differences with previous +governance versions. We recommend learning about [Governance v1](./archive/learn-governance.md) to +better understand the need for and the direction of Polkadot OpenGov. ## Summary @@ -72,9 +69,8 @@ decisions. Whether the public or the council initiated the proposal, it would ev through a referendum to let all holders (weighted by stake and conviction) make the decision. The Council fulfilled its role as the representative of the public, guardian of the treasury and -initiator of legislation, but it was often seen as a centralized entity. To further decentralize -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}, Polkadot OpenGov proposes the -following main changes: +initiator of legislation, but it was often seen as a centralized entity. To further decentralize the +network, Polkadot OpenGov proposes the following main changes: - Migrating all responsibilities of the Council to the public via a direct democracy voting system. - Dissolving the current [Council](./archive/learn-governance.md#council) collective @@ -285,10 +281,9 @@ Delegations under Governance v1 will need to be re-issued under OpenGov. ::: -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} utilizes an idea called voluntary -locking that allows token holders to increase their voting power by declaring how long they are -willing to lock up their tokens; hence, the number of votes for each token holder will be calculated -by the following formula: +Polkadot utilizes an idea called voluntary locking that allows token holders to increase their +voting power by declaring how long they are willing to lock up their tokens; hence, the number of +votes for each token holder will be calculated by the following formula: ``` votes = tokens * conviction_multiplier @@ -310,21 +305,14 @@ the tokens are locked. See below an example that shows how voluntary locking works. -Peter: Votes `No` with -{{ polkadot: 10 DOT for a 32-week :polkadot }}{{ kusama: 1 KSM for a 32-week :kusama }} lock period -=> {{ polkadot: 10 x 6 = 60 Votes :polkadot }}{{ kusama: 1 x 6 = 6 Votes :kusama }} +Peter: Votes `No` with 10 DOT for a 32-week lock period => 10 x 6 = 60 Votes -Logan: Votes `Yes` with -{{ polkadot: 20 DOT for one week :polkadot }}{{ kusama: 2 KSM for one week :kusama }} lock period => -{{ polkadot: 20 x 1 = 20 Votes :polkadot }}{{ kusama: 2 x 1 = 2 Votes :kusama }} +Logan: Votes `Yes` with 20 DOT for one week lock period => 20 x 1 = 20 Votes -Kevin: Votes `Yes` with -{{ polkadot: 15 DOT for a 2-week :polkadot }}{{ kusama: 1.5 KSM for a 2-week :kusama }} lock period -=> {{ polkadot: 15 x 2 = 30 Votes :polkadot }}{{ kusama: 1.5 x 2 = 3 Votes :kusama }} +Kevin: Votes `Yes` with 15 DOT for a 2-week lock period => 15 x 2 = 30 Votes -Even though both Logan and Kevin vote with more -{{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} than Peter, the lock period for both of them -is less than Peter’s, leading to their voting power counting as less. +Even though both Logan and Kevin vote with more DOT than Peter, the lock period for both of them is +less than Peter’s, leading to their voting power counting as less. :::info Staked tokens can be used in governance @@ -361,19 +349,14 @@ satisfy the approval and support criteria for the **Confirmation Period**. conviction) compared to the total possible votes ([active issuance](learn-DOT.md#token-issuance)) that could be made in the system. In case of _split_ votes, only _aye_ and _abstain_ will count. -For example, let us consider a hypothetical example where the total active issuance is -{{ polkadot: 100 DOT :polkadot }}{{ kusama: 100 KSM :kusama }} +For example, let us consider a hypothetical example where the total active issuance is 100 DOT. -- An account A votes "Aye" with 10 {{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} with 4x - conviction -- An account B votes "Nay" with 5 {{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} with 2x - conviction -- An account C votes "Abstain" with 20 {{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }}. (no - conviction can be applied to "Abstain" votes) +- An account A votes "Aye" with 10 DOT with 4x conviction +- An account B votes "Nay" with 5 DOT with 2x conviction +- An account C votes "Abstain" with 20 DOT. (no conviction can be applied to "Abstain" votes) -In this scenario, only 35 {{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} from the total -active issuance participated in voting on the referendum. Now, let us calculate the Approval and -Support values for that referendum. +In this scenario, only 35 DOT from the total active issuance participated in voting on the +referendum. Now, let us calculate the Approval and Support values for that referendum. - Approval is calculated as (Aye') / (Aye' + Nay’), where Aye' and Nay' are the votes after applying the conviction multiplier. Hence, Approval = (10 x 4) / (10 x 4 + 5 x 2) = 40/50 which is 80%. @@ -482,8 +465,7 @@ Blacklisting referenda in Polkadot OpenGov is ## Voting on a Referendum -If you are a voter, it means that you will vote with your -{{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} on each single referendum. +If you are a voter, it means that you will vote with your tokens on each single referendum. In Governance V1, voters could cast only an _aye_ or _nay_ vote. In Polkadot OpenGov, voters can additionally cast a _abstain_ and _split_ votes. @@ -493,11 +475,8 @@ abstaining or splitting the votes. :::info Only the last vote counts -Voting a second time replaces your original vote, e.g. voting with 10 -{{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }}, then a second extrinsic to vote with 5 -{{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }}, means that you are voting with 5 -{{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }}, not 10 -{{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }}. +Voting a second time replaces your original vote, e.g. voting with 10 DOT, then a second extrinsic +to vote with 5 DOT, means that you are voting with 5 DOT, not 10 DOT. ::: @@ -530,7 +509,7 @@ If you vote without conviction, the referendum is ongoing, and you remove the vo your tokens immediately. If the referendum ended, you can remove your vote and unlock your tokens immediately, regardless of whether you are on the winning or losing side of the referendum. The governance app or interface you used for participating in Polkadot OpenGov should show an option to -unlock your {{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }}. +unlock your tokens. ### Voting with Conviction @@ -542,13 +521,12 @@ you will get a conviction lock. Conviction locks are calculated from the time the referendum ended but are applied when you remove the vote. -For example, if you voted with conviction 1x with 10 -{{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }}, those 10 -{{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} will be locked for 7 days after the -referendum ends (assuming you are on the winning side). If you remove the vote 3 days after the -referendum ended, your tokens will be locked for 4 more days. If you remove it on the 8th day after -the end of the referendum, the tokens can be unlocked right away (after you remove the vote). When -you remove the vote, the lock expiration block is calculated and added to the chain state. +For example, if you voted with conviction 1x with 10 DOT, those 10 DOT will be locked for 7 days +after the referendum ends (assuming you are on the winning side). If you remove the vote 3 days +after the referendum ended, your tokens will be locked for 4 more days. If you remove it on the 8th +day after the end of the referendum, the tokens can be unlocked right away (after you remove the +vote). When you remove the vote, the lock expiration block is calculated and added to the chain +state. If you voted on multiple referenda, and you are on the winning side of all those referenda, you will get multiple conviction voting locks for all those referenda. **Locks do not stack**; the length and diff --git a/docs/learn/learn-proxies.md b/docs/learn/learn-proxies.md index bc6791d442d0..ec3784a6f876 100644 --- a/docs/learn/learn-proxies.md +++ b/docs/learn/learn-proxies.md @@ -20,7 +20,7 @@ risk their lives to ensure the VIP's protection. But proxies are also useful in as efficient account management at the corporate level. They also provide an elegant solution to change signatories within multi-signature accounts, and they can be used within proxy calls and nested proxy calls. In this page we will explore all these interesting use cases of proxies within -the {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} ecosystem. +the Polkadot ecosystem. Shown below is an example of how you might use these accounts. Imagine you have one stash account as your primary token-holding account and don't want to access it very often, but you want to @@ -43,14 +43,11 @@ participate in the network. ## Proxy Types -When a proxy account makes a transaction, -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} filters the desired transaction to -ensure that the proxy account has the appropriate permission to make that transaction on behalf of -the proxied account. For example, staking proxies have permission to do only staking-related -transactions. +When a proxy account makes a transaction, Polkadot filters the desired transaction to ensure that +the proxy account has the appropriate permission to make that transaction on behalf of the proxied +account. For example, staking proxies have permission to do only staking-related transactions. -When you set a proxy, you must choose a type of proxy for the relationship. -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} offers: +When you set a proxy, you must choose a type of proxy for the relationship with the proxied account. - **Any**: allow any transaction, including balance transfers. In most cases, this should be avoided as the proxy account is used more frequently than the cold account and is therefore less secure. @@ -101,9 +98,8 @@ every proxy the account has, an additional amount defined by the ## Time-delayed Proxy We can add a layer of security to proxies by giving them a delay time. The delay will be quantified -in blocks. {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} has approximately 6 -seconds of block time. A delay value of 10 will mean ten blocks, which equals about one minute -delay. +in blocks. Polkadot has approximately 6 seconds of block time. A delay value of 10 will mean ten +blocks, which equals about one minute delay. The proxy will announce its intended action and will wait for the number of blocks defined in the delay time before executing it. Within this time window, the intended action may be canceled by diff --git a/docs/learn/learn-runtime-upgrades.md b/docs/learn/learn-runtime-upgrades.md index 796e33214193..a4287cee18f0 100644 --- a/docs/learn/learn-runtime-upgrades.md +++ b/docs/learn/learn-runtime-upgrades.md @@ -7,9 +7,9 @@ keywords: [runtime, upgrades, releases, forkless] slug: ../learn-runtime-upgrades --- -Runtime upgrades allow the {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} relay -chain, parachains, and solo blockchains built with the Polkadot SDK to change their core business -logic (referred to as the **runtime**) without the need for a hard fork. +Runtime upgrades allow the relay chain, parachains, and solo blockchains built with the Polkadot SDK +to change their core business logic (referred to as the **runtime**) without the need for a hard +fork. ## Forkless Upgrades @@ -26,16 +26,13 @@ Kusama and their respective parachains), give the relay chain, its parachains, a standalone solo chains built with the Polkadot SDK the ability to upgrade their runtime (the chain's "business logic") without a hard fork of the respective network. -Rather than encoding the runtime in the nodes, -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} nodes contain a WebAssembly +Rather than encoding the runtime in the nodes, Polkadot nodes contain a WebAssembly [execution host](learn-polkadot-host). They maintain consensus on a very low-level and well-established instruction set. Upgrades can be small, isolated, and very specific by deploying WebAssembly on-chain and having nodes auto-enact the new logic at a particular block height. -The {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} runtime is stored on the -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} blockchain itself. -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} can upgrade its runtime by upgrading -the logic stored on-chain and removes the coordination challenge of requiring thousands of node +The runtime is stored on the blockchain itself. Polkadot can upgrade its runtime by upgrading the +logic stored on-chain and removes the coordination challenge of requiring thousands of node operators to upgrade in advance of a given block number. Polkadot stakeholders propose and approve upgrades through the [on-chain governance](./learn-polkadot-opengov.md) system, which also enacts them autonomously once the runtime upgrade referendum is approved through on-chain voting. @@ -76,8 +73,8 @@ transaction constructed based on a runtime version will not be valid in later ru you can’t submit a transaction before the upgrade, it is better to wait and construct it afterward. Although upgrading your nodes is generally not necessary to follow an upgrade, we recommend -following the {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} releases and upgrading -promptly, especially for high-priority or critical releases. +following the Polkadot releases and upgrading promptly, especially for high-priority or critical +releases. :::info New Client Releases @@ -124,9 +121,8 @@ to upgrade their clients within a specific time frame, for example, if a release changes to networking. It is essential to check the release notes, starting with the upgrade priority and acting accordingly. -General infrastructure providers, aside from following the -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} releases and upgrading in a timely -manner, should monitor changes to runtime events and auxiliary tooling, such as the +General infrastructure providers, aside from following the runtime releases and upgrading in a +timely manner, should monitor changes to runtime events and auxiliary tooling, such as the [Substrate API Sidecar](https://github.com/paritytech/substrate-api-sidecar). Transactions constructed for runtime `n` will not work for any other runtime `>n`. If a runtime diff --git a/docs/learn/learn-spree.md b/docs/learn/learn-spree.md index 2b516352df67..2d05139342ee 100644 --- a/docs/learn/learn-spree.md +++ b/docs/learn/learn-spree.md @@ -9,9 +9,8 @@ slug: ../learn-spree --- Shared Protected Runtime Execution Enclaves (SPREE) sometimes referred to as "trust wormholes," are -fragments of logic comparable to runtime modules in Substrate, but live on the -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} relay chain and maybe opted into by -parachains. +fragments of logic comparable to runtime modules in Substrate, but live on the relay chain and maybe +opted into by parachains. SPREE in brief was described with the following properties and functions: @@ -35,10 +34,8 @@ be changed through an interface with each parachain. SmartProtocols are the prec ## What is a SPREE module? SPREE modules are fragments of logic (in concrete terms they are blobs of -[WebAssembly](learn-wasm.md) code) that are uploaded onto -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} through a governance mechanism or by -parachains. Once the blob is uploaded to -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}, all other parachains can decide to +[WebAssembly](learn-wasm.md) code) that are uploaded onto Polkadot through a governance mechanism or +by parachains. Once the blob is uploaded to the relay chain, all other parachains can decide to opt-in to the logic. The SPREE module would retain its own storage independent of the parachain, but would be callable through an interface with the parachain. Parachains will send messages to the SPREE module synchronously. @@ -57,12 +54,11 @@ book. Now we can also consult the same book that the cook has, and we have a pre of what will happen when we tell the cook to make a soufflé. In this example, “make a soufflé” was the message in XCMP and the cookbook was the SPREE module. -In concrete terms, SPREE modules could be useful for various functionality on -{{ polkadot: Polkadot. :polkadot }}{{ kusama: Kusama. :kusama }}. One suggested use case of SPREE -modules is for a trustless decentralized exchange that is offered as functionality to any parachain -without any extra effort from parachain developers. One can imagine this working by having a SPREE -module that exposes the interface for the incrementing and decrementing of balances of various -assets based on a unique identifier. +In concrete terms, SPREE modules could be useful for various functionality on Polkadot. One +suggested use case of SPREE modules is for a trustless decentralized exchange that is offered as +functionality to any parachain without any extra effort from parachain developers. One can imagine +this working by having a SPREE module that exposes the interface for the incrementing and +decrementing of balances of various assets based on a unique identifier. ## Why? @@ -82,13 +78,12 @@ change the total supply of tokens and a basic interface. ![spree example](../assets/SPREE/spree_module.png) -The diagram above is a simplification of the -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} system. +The diagram above is a simplification of the Polkadot system. -In this diagram, we see that the Wasm code for SPREE module "X" has been uploaded to the -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} relay chain. The two cylinders "A" -and "B" represent two distinct parachains that have both opted-in to this SPREE module creating two -distinct instances of it with their own XCMP endpoints "A.X" and "B.X". +In this diagram, we see that the Wasm code for SPREE module "X" has been uploaded to the relay +chain. The two cylinders "A" and "B" represent two distinct parachains that have both opted-in to +this SPREE module creating two distinct instances of it with their own XCMP endpoints "A.X" and +"B.X". In the example, we assume that this SPREE module "X" contains the functionality for incrementing or decrementing the balance of a particular asset that is unique to this module. diff --git a/docs/learn/learn-staking-advanced.md b/docs/learn/learn-staking-advanced.md index 67d6851bbaf2..6efd6c85f775 100644 --- a/docs/learn/learn-staking-advanced.md +++ b/docs/learn/learn-staking-advanced.md @@ -35,29 +35,27 @@ and earn staking rewards. For additional information, check out ::: -This page is meant to be an advanced guide to staking with -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}. For a more general introduction, -checkout the [Introduction to Staking](./learn-staking.md) page. +This page is meant to be an advanced guide to staking with the relay chain. For a more general +introduction, checkout the [Introduction to Staking](./learn-staking.md) page. ## Staking Proxies -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} makes it possible to create accounts -having special permissions also called **proxy accounts**. For more details about proxy accounts -visit the [dedicated page](./learn-proxies.md) on this wiki. +Polkadot makes it possible to create accounts having special permissions also called **proxy +accounts**. For more details about proxy accounts visit the [dedicated page](./learn-proxies.md) on +this wiki. Proxy accounts are special accounts which can sign [**extrinsic calls**](./learn-transactions.md#pallets-and-extrinsics) made to specific **pallets** on behalf of the proxied account. There is thus the possibility to create staking proxy accounts that can be used to sign extrinsic calls specific to the staking, session and utility pallets. -Staking on {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} is not a set-and-forget -action, as a nominator you will need to monitor the performance of your validators and make changes -if needed. There will be this transactions such as nominating that will be needed to regularly -signed. Each time you sign with an account, in the case of hot accounts, you expose the private key -of that account to the internet with consequent risk of attack. A hot stash will be exposed all the -time a transaction is signed. Even in the case of a cold stash created with a Ledger device, signing -with the stash will build a transaction history that might tell something about your habits and -preferences, or even your location. +Staking is not a set-and-forget action, as a nominator you will need to monitor the performance of +your validators and make changes if needed. There will be this transactions such as nominating that +will be needed to regularly signed. Each time you sign with an account, in the case of hot accounts, +you expose the private key of that account to the internet with consequent risk of attack. A hot +stash will be exposed all the time a transaction is signed. Even in the case of a cold stash created +with a Ledger device, signing with the stash will build a transaction history that might tell +something about your habits and preferences, or even your location. Ideally, accounts with high economic power like the stash must be and remain as isolated as possible. With a staking proxy, the stash account is fully isolated when signing for staking-related @@ -88,8 +86,8 @@ For a demo about bags list see [this video tutorial](https://youtu.be/hIIZRJLrBZ ::: -In {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}'s NPoS nomination intents are -placed in a semi-sorted list called [bags-list](https://github.com/paritytech/substrate/pull/9507). +In Polkadot's NPoS nomination intents are placed in a semi-sorted list called +[bags-list](https://github.com/paritytech/substrate/pull/9507). {{ kusama: The bags list example below uses DOT for explaining the concepts. :kusama }} The Bags-List substrate pallet is designed to be self-maintaining, with minimal effort from the blockchain, making it extremely scalable. The bags list has two primary components, bags and nodes @@ -134,8 +132,8 @@ rewards/slashing do not. See the [bags-list](learn-nominator.md#bags-list) secti information. The bags-list is capable of including an unlimited number of nodes, subject to the chain's runtime -storage. In the current staking system configuration, at most {{ polkadot: 22500 :polkadot }} -{{ kusama: 12500 :kusama }} nominators in the bags-list come out as the electing nominators. See +storage. In the current staking system configuration, at most 22500 nominators in the bags-list +(12500 on Kusama) come out as the electing nominators. See [Staking Election Stages](learn-nominator.md#staking-election-stages) section for more info. This means that only a portion of the nomination intents is kept. Once the nomination period ends, @@ -157,10 +155,10 @@ staking/election system. :::caution Minimum active nomination threshold to earn rewards is dynamic -Submitting a nomination intent does not guarantee staking rewards. The stake of the top -{{ polkadot: 22500 :polkadot }} {{ kusama: 12500 :kusama }} nominators is applied to the validators -in the active set. To avail of staking rewards, ensure that the number of tokens bonded is higher -than the minimum active bond. For more information, see the [nominator guide](learn-nominator.md). +Submitting a nomination intent does not guarantee staking rewards. The stake of the top 22500 +nominators (12500 on Kusama) is applied to the validators in the active set. To avail of staking +rewards, ensure that the number of tokens bonded is higher than the minimum active bond. For more +information, see the [nominator guide](learn-nominator.md). ::: @@ -269,10 +267,9 @@ reputation will be able to charge slightly higher commission fees (which is fair ## Simple Payouts -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} makes stakers claim their rewards for -past eras by submitting a transaction. This naturally leads to spreading out reward distribution, as -people make transactions at disparate times, rather than updating the accounts of all stakers in a -single block. +Polkadot makes stakers claim their rewards for past eras by submitting a transaction. This naturally +leads to spreading out reward distribution, as people make transactions at disparate times, rather +than updating the accounts of all stakers in a single block. Even if everyone submitted a reward claim at the same time, the fact that they are individual transactions would allow the block construction algorithm to process only a limited number per block @@ -280,19 +277,17 @@ and ensure that the network maintains a constant block time. If all rewards were block, this could cause serious issues with the stability of the network. Simple payouts require one transaction per validator, per [era](../general/glossary.md##era), to -claim rewards. The reason {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} requires -this is to avoid an attack where someone has several thousand accounts nominating a single -validator. The major cost in reward distribution is mutating the accounts in storage, and -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} cannot pay out several thousand -accounts in a single transaction. +claim rewards. The reason Polkadot requires this is to avoid an attack where someone has several +thousand accounts nominating a single validator. The major cost in reward distribution is mutating +the accounts in storage, and Polkadot cannot pay out several thousand accounts in a single +transaction. ### Claiming Rewards -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} stores the last 84 eras of reward -information (e.g. maps of era number to validator points, staking rewards, nomination exposure, -etc.). Rewards will not be claimable more than 84 eras after they were earned. This means that all -rewards must be claimed within a maximum of 84 eras, although under certain circumstances (described -below) this may be as low as 28 eras. +The relay chain stores the last 84 eras of reward information (e.g. maps of era number to validator +points, staking rewards, nomination exposure, etc.). Rewards will not be claimable more than 84 eras +after they were earned. This means that all rewards must be claimed within a maximum of 84 eras, +although under certain circumstances (described below) this may be as low as 28 eras. If a validator kills their stash, any remaining rewards will no longer be claimable. Before doing this, however, they would need to first stop validating and then unbond the funds in their stash, diff --git a/docs/learn/learn-staking.md b/docs/learn/learn-staking.md index d86b56b384df..040bd16d19d0 100644 --- a/docs/learn/learn-staking.md +++ b/docs/learn/learn-staking.md @@ -40,8 +40,7 @@ Check the wiki doc on [nomination pools](learn-nomination-pools.md) for more inf ::: -Here you will learn about what staking is, why it is important and how it works on -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}. +Here you will learn about what staking is, why it is important, and how it works. ## Proof-of-Stake (PoS) @@ -62,11 +61,10 @@ who are responsible for adding blocks to the chain must compete to solve difficu puzzles to add blocks - a solution that has been criticized for the wastage of energy. For doing this work, miners are typically rewarded with tokens. -In PoS networks like {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} the security of -the network depends on the amount of capital locked on the chain: the more the capital locked, the -lower the chance of an attack on the network, as the attacker needs to incur a heavy loss to -orchestrate a successful attack (more on this later on). The process of locking tokens on the chain -is called **staking**. +In PoS networks like Polkadot, the security of the network depends on the amount of capital locked +on the chain: the more the capital locked, the lower the chance of an attack on the network, as the +attacker needs to incur a heavy loss to orchestrate a successful attack (more on this later on). The +process of locking tokens on the chain is called **staking**. Similar to the miners in PoW networks, PoS networks have **validators**, but they do not have to compete with each other to solve mathematical puzzles. They are instead pre-selected to produce the @@ -86,19 +84,18 @@ to get rewarded, and the PoS network rewards good behavior and punishes bad beha ## Nominated Proof-of-Stake (NPoS) -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} implements -[Nominated Proof-of-Stake (NPoS)](learn-consensus.md/#nominated-proof-of-stake), a relatively novel -and sophisticated mechanism to select the validators who are allowed to participate in its -[consensus](learn-consensus.md) protocol. NPoS encourages -{{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} holders to participate as **nominators**. +Polkadot implements [Nominated Proof-of-Stake (NPoS)](learn-consensus.md/#nominated-proof-of-stake), +a relatively novel and sophisticated mechanism to select the validators who are allowed to +participate in its [consensus](learn-consensus.md) protocol. NPoS encourages token holders to +participate as **nominators**. Any potential validators can indicate their intention to be a validator candidate. Their candidacies -are made public to all nominators, and a nominator, in turn, submits a list of up to -{{ polkadot: 16 :polkadot }} {{ kusama: 24 :kusama }} candidates that it supports, and the network -will automatically distribute the stake among validators in an even manner so that the economic -security is maximized. In the next era, a certain number of validators having the most -{{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} backing get elected and become active. For -more information about the election algorithm go to [this](learn-phragmen.md) page on the wiki or +are made public to all nominators, and a nominator, in turn, submits a +[capped list of candidates](../general/chain-state-values.md#maximum-votes-per-nominator) that it +supports, and the network will automatically distribute the stake among validators in an even manner +so that the economic security is maximized. In the next era, a certain number of validators having +the highest backing get elected and become active. For more information about the election algorithm +go to [this](learn-phragmen.md) page on the wiki or [this](https://research.web3.foundation/Polkadot/protocols/NPoS/Paper) research article. As a nominator, a [minimum bond](../general/chain-state-values.md#minimum-bond-to-participate-in-staking) is required to submit an intention to nominate, which can be thought of as registering to be a @@ -118,7 +115,7 @@ on the amount of tokens being staked, in addition to the selected nominations. ### Nominating Validators -Nominating on {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} requires 2 actions: +Nominating requires 2 actions: - Locking tokens on-chain. - Selecting a set of validators, to whom these locked tokens will automatically be allocated to. @@ -131,38 +128,34 @@ tokens will be referred to as bonded tokens. Once the previous 2 steps are completed and you are nominating, your bonded tokens could be allocated to one or more of your selected validators, and this happens every time the active -validator set changes. This validator set is updated every era on -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}. - -Unlike other staking systems, {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} -automatically chooses which of your selected validators will be backed by your bonded tokens. -Selecting a group of validators increases your chances of consistently backing at least one who is -active. This results in your bonded tokens being allocated to validators more often, which means -more network security and more rewards. This is in strong contrast to other staking systems that -only allow you to back one validator; if that validator is not active, you as a staker will also not -be. {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}'s nomination model solves this. - -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} uses tools ranging from election -theory to game theory to discrete optimization, to develop an efficient validator selection process -that offers fair representation and security, thus avoiding uneven power and influence among -validators. The election algorithms used by -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} are based on the Proportional -Justified Representation (PJR) methods like [Phragmen](learn-phragmen.md). For more information -about PJR methods visit [this](https://research.web3.foundation/Polkadot/protocols/NPoS/Overview) -research article. +validator set changes. This validator set is updated every era. + +Unlike other staking systems, Polkadot automatically chooses which of your selected validators will +be backed by your bonded tokens. Selecting a group of validators increases your chances of +consistently backing at least one who is active. This results in your bonded tokens being allocated +to validators more often, which means more network security and more rewards. This is in strong +contrast to other staking systems that only allow you to back one validator; if that validator is +not active, you as a staker will also not be. + +Polkadot's nomination model solves this. It uses tools ranging from election theory to game theory +to discrete optimization, to develop an efficient validator selection process that offers fair +representation and security, thus avoiding uneven power and influence among validators. The election +algorithms are based on the Proportional Justified Representation (PJR) methods like +[Phragmen](learn-phragmen.md). For more information about PJR methods visit +[this](https://research.web3.foundation/Polkadot/protocols/NPoS/Overview) research article. ### Eras and Sessions The stake from nominators is used to increase the number of tokens held by such candidates, increasing their chance of being selected by the election algorithm for block production during a -specific **era**. An era is a period of {{ polkadot: 24 :polkadot }}{{ kusama: 6 :kusama }} hours -during which an **active set** of validators is producing blocks and performing other actions on the -chain. This means that not all validators are in the active set and such set changes between eras. -Each era is divided into 6 epochs or **sessions** during which validators are assigned as block -producers to specific time frames or **slots**. This means that validators know the slots when they -will be required to produce a block within a specific session, but they do not know all the slots -within a specific era. Having sessions adds a layer of security because it decreases the chance of -having multiple validators assigned to a slot colluding to harm the network. +specific **era**. An era is a period of 24 hours (6 hours on Kusama) during which an **active set** +of validators is producing blocks and performing other actions on the chain. This means that not all +validators are in the active set and such set changes between eras. Each era is divided into 6 +epochs or **sessions** during which validators are assigned as block producers to specific time +frames or **slots**. This means that validators know the slots when they will be required to produce +a block within a specific session, but they do not know all the slots within a specific era. Having +sessions adds a layer of security because it decreases the chance of having multiple validators +assigned to a slot colluding to harm the network. ### Staking Rewards @@ -194,10 +187,10 @@ lead to centralization. ### Tasks and Responsibilities of a Nominator -**Validators.** Since validator slots are limited, most of those who wish to stake their -{{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} and contribute to the economic security of -the network will be nominators, thus here we focus on the role of nominators. However, it is worth -mentioning that validators do most of the heavy lifting: they run the validator nodes and manage +**Validators.** Since validator slots are limited, most of those who wish to stake their tokens and +contribute to the economic security of the network will be nominators, thus here we focus on the +role of nominators. However, it is worth mentioning that validators do most of the heavy lifting: +they run the validator nodes and manage [session keys](https://research.web3.foundation/Polkadot/security/keys/session), produce new block candidates in [BABE](learn-consensus.md/#block-production-babe), vote and come to consensus in [GRANDPA](learn-consensus.md/#finality-gadget-grandpa), validate the state transition function of @@ -259,7 +252,7 @@ To maximize rewards and minimize risk, one could select those validators that: - have era points above average (because they will get more rewards for being active), - have the total stake backing the validator below the average active validator stake (because they - will pay out more rewards per staked {{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }}), + will pay out more rewards per staked token), - have high own stake (because if slashed they have something to lose), - have low commission fees but not 0% (because it makes sense that for doing the heavy lifting, validators ask for a small commission), @@ -385,11 +378,8 @@ timeline. See the page on [Validator Payout Guide](../maintain/maintain-guides-v The distribution of staking rewards to the nominators is not automatic and needs to be triggered by someone. Typically the validators take care of this, but anyone can permissionlessly trigger rewards payout for all the nominators whose stake has backed a specific validator in the active set of that -era. Staking rewards are kept available for 84 eras. The following calculation can be used to -approximate this length in days on {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}: - -{{ polkadot: `84 eras` × `24 hours in a single era` ÷ `24 hours in a day` = `84 days` :polkadot }} -{{ kusama: `84 eras` × `6 hours in a single era` ÷ `24 hours in a day` = `21 days` :kusama }} +era. Staking rewards are kept available for +[a limited amount of time](../general/chain-state-values.md#staking-reward-retention). For more information on why this is so, see the page on [simple payouts](learn-staking-advanced.md). @@ -442,8 +432,7 @@ this wiki. :::info Fast Unstaking feature is live! -If you accidentally bonded your {{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} or your -bonded {{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} never backed any active validator, you +If you accidentally bonded your tokens or your bonded tokens never backed any active validator, you can now unbond them immediately. ::: @@ -460,14 +449,14 @@ automatically check if you qualify. For more information, visit the - Earn rewards for contributing to the network's security through staking. - Low barrier of entry through [Nomination Pools](learn-nomination-pools.md). -- Can choose up-to {{ polkadot: 16 :polkadot }} {{ kusama: 24 :kusama }} validators which can help - to decentralize the network through the sophisticated +- Can choose [multiple validators](../general/chain-state-values.md#maximum-votes-per-nominator) + which can help to decentralize the network through the sophisticated [NPoS system](learn-consensus.md/#nominated-proof-of-stake) - 10% inflation/year of the tokens is primarily intended for staking rewards. When the system staking rate matches with the ideal staking rate, the entire inflation of the network is given away as the staking rewards. -{{ polkadot: Up until now, the network has been following an inflation model that excludes the metric of active parachains. :polkadot }} + The ideal staking rate is a dynamic value - as the number of active parachains influences the available liquidity that is available to secure the network. @@ -512,19 +501,18 @@ The top bound on the [number of validators](../general/chain-state-values.md#act has not been determined yet, but should only be limited by the bandwidth strain of the network due to peer-to-peer message passing. -{{ polkadot: The estimate of the number of validators that Polkadot will have at maturity is around 1000. :polkadot }} -{{ polkadot: Kusama is already operating at this threshold. :polkadot }} +The estimate of the number of validators that Polkadot will have at maturity is around 1000, while +Kusama is already operating at this threshold. ## Why am I not receiving rewards? -Nominating on {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} is not a set-and-forget -action. Nominators need to monitor their nominations and ensure they are eligible to receive staking -rewards. Otherwise, they would be risking their funds to secure the chain with no reward. If you are -bonding significantly more than the Minimum Active Bond and yet not receiving rewards, your -nominations are all waiting, or your active validator has 100% commission. However, if you bond -funds close to the Minimum Active Bond, there could be several possibilities for not receiving -staking rewards. The table below can be used to troubleshoot why you might not be receiving staking -rewards using Polkadot-JS UI. +Nominating is not a set-and-forget action. Nominators need to monitor their nominations and ensure +they are eligible to receive staking rewards. Otherwise, they would be risking their funds to secure +the chain with no reward. If you are bonding significantly more than the Minimum Active Bond and yet +not receiving rewards, your nominations are all waiting, or your active validator has 100% +commission. However, if you bond funds close to the Minimum Active Bond, there could be several +possibilities for not receiving staking rewards. The table below can be used to troubleshoot why you +might not be receiving staking rewards using Polkadot-JS UI. | Nomination Status | What's happening? | Causes | What to do? | | :---------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | diff --git a/docs/learn/learn-system-chains.md b/docs/learn/learn-system-chains.md index 69b57bba4cda..4c2aff9154b2 100644 --- a/docs/learn/learn-system-chains.md +++ b/docs/learn/learn-system-chains.md @@ -55,10 +55,9 @@ The [Asset Hub](https://github.com/paritytech/polkadot-sdk/tree/master/cumulus#a Polkadot and Kusama are the first system parachains. The Asset Hub is an asset portal for the entire network. It helps asset creators (e.g. reserve -backed stablecoin issuers) to track the total issuance of their asset in the -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} network, including amounts that have -been transferred to other parachains. It is also the point where they can transact, to mint and -burn, to manage the on-chain asset. +backed stablecoin issuers) to track the total issuance of their asset in the network, including +amounts that have been transferred to other parachains. It is also the point where they can +transact, to mint and burn, to manage the on-chain asset. The Asset Hub also supports non-fungible assets (NFTs) via the [Uniques pallet](https://polkadot.js.org/docs/substrate/extrinsics#uniques) and the new @@ -69,9 +68,8 @@ This logic for asset management is not encoded in smart contracts, but rather di runtime of the chain. Because of the efficiency of executing logic in a parachain, fees and deposits are about 1/10th of their respective value on the relay chain. -These low fee levels mean that the Asset Hub is well suited for handling -{{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} balances and transfers as well as managing -on-chain assets. +These low fee levels mean that the Asset Hub is well suited for handling balances and transfers as +well as managing on-chain assets. ### Collectives diff --git a/docs/learn/learn-teleport.md b/docs/learn/learn-teleport.md index a72b7a28708e..8adc3a4697fa 100644 --- a/docs/learn/learn-teleport.md +++ b/docs/learn/learn-teleport.md @@ -9,12 +9,12 @@ slug: ../learn-teleport import RPC from "./../../components/RPC-Connection"; -One of the main properties that {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} -brings to the blockchain industry is secure interoperability. This interoperability allows for -**asset teleportation**, i.e., the process of moving assets (such as fungible and non-fungible -tokens) between chains (parachains) to use them as any other asset native to that chain. -Interoperability is possible through [XCM](learn-xcm.md) and [SPREE modules](learn-spree.md), which -together ensure that assets are not lost or duplicated across multiple chains. +One of the main properties that Polkadot brings to the blockchain industry is secure +interoperability. This interoperability allows for **asset teleportation**, i.e., the process of +moving assets (such as fungible and non-fungible tokens) between chains (parachains) to use them as +any other asset native to that chain. Interoperability is possible through [XCM](learn-xcm.md) and +[SPREE modules](learn-spree.md), which together ensure that assets are not lost or duplicated across +multiple chains. :::info Walk-through video tutorial about teleporting assets diff --git a/docs/learn/learn-transactions.md b/docs/learn/learn-transactions.md index c54272d96c37..57116144e238 100644 --- a/docs/learn/learn-transactions.md +++ b/docs/learn/learn-transactions.md @@ -12,11 +12,10 @@ from "@theme/TabItem"; import DocCardList from '@theme/DocCardList'; ## Pallets and Extrinsics -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} is built using -[Substrate](https://substrate.io/), a modular framework to efficiently build blockchains. -Substrate's FRAME development environment provides modules called pallets and support libraries that -you can use, modify, and extend to build the runtime logic to suit the needs of your blockchain. You -can explore Substrate's FRAME pallets on +Polkadot is built using [Substrate](https://substrate.io/), a modular framework to efficiently build +blockchains. Substrate's FRAME development environment provides modules called pallets and support +libraries that you can use, modify, and extend to build the runtime logic to suit the needs of your +blockchain. You can explore Substrate's FRAME pallets on [this dedicated page](https://docs.substrate.io/reference/frame-pallets/). Within each functional **pallet** on the blockchain, one can **call** its functions and execute them @@ -42,24 +41,21 @@ really are. Extrinsics can be one of 3 distinct types: - **Inherents:** are a special type of unsigned transaction made by block authors which carry information required to build a block such as timestamps, storage proofs and uncle blocks. -Signed transactions is the way that most users will interact with -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}. Signed transactions come from an -account that has funds, and therefore {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} -can charge a transaction fee as a way to prevent spam. +Signed transactions is the way that most users will interact with Polkadot. Signed transactions come +from an account that has funds, and therefore Polkadot can charge a transaction fee as a way to +prevent spam. Unsigned transactions are for special cases where a user needs to submit an extrinsic from a key pair that does not control funds. For example, validator's [session keys](learn-cryptography.md) -never control funds. Unsigned transactions are only used in special cases because, since -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} cannot charge a fee for them, each -one needs its own, custom validation logic. +never control funds. Unsigned transactions are only used in special cases because, since Polkadot +cannot charge a fee for them, each one needs its own, custom validation logic. Inherents are pieces of information that are not signed or included in the transaction queue. As such, only the block author can add inherents to a block. Inherents are assumed to be "true" simply because a sufficiently large number of validators have agreed on them being reasonable. For example, -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} blocks include a timestamp inherent. -There is no way to prove that a timestamp is true the way one proves the desire to send funds with a -signature. Rather, validators accept or reject the block based on how reasonable they find the -timestamp. In {{ polkadot: Polkadot, :polkadot }}{{ kusama: Kusama, :kusama }} it must be within +the relay chain blocks include a timestamp inherent. There is no way to prove that a timestamp is +true the way one proves the desire to send funds with a signature. Rather, validators accept or +reject the block based on how reasonable they find the timestamp. In Polkadot, it must be within some acceptable range of their own system clocks. Here are some key differences between the different types of extrinsics: @@ -74,16 +70,15 @@ Here are some key differences between the different types of extrinsics: ### Mortal and Immortal Extrinsics Transactions are generally irreversible once confirmed and added to the blockchain, an immutable -ledger of all transactions. This means users must exercise caution, as mistakes such as sending -{{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} to the wrong address cannot be reverted. The -permanence of transactions highlights the importance of careful verification before signing any -transaction on a blockchain network. It is usually a +ledger of all transactions. This means users must exercise caution, as mistakes such as sending DOT +to the wrong address cannot be reverted. The permanence of transactions highlights the importance of +careful verification before signing any transaction on a blockchain network. It is usually a [good practice not to blind sign transactions](../general/transaction-attacks.md) to avoid being victim of an attack. In blockchain terms, transactions can be **mortal** extrinsics (i.e. valid within a defined block interval, usually short), or **immortal** extrinsics (i.e. always valid). It is possible to make -immortal transactions on {{ polkadot: Polkadot. :polkadot }}{{ kusama: Kusama. :kusama }} However, +immortal transactions on Polkadot. However, [for security reasons](../general/transaction-attacks.md#replay-attack), it is highly recommended not to do so and most wallet software will not allow you to make an immortal extrinsic. @@ -94,10 +89,10 @@ of transfer. ### Vested Transfers -{{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} may have a lock to account for vesting funds. -Like other types of [locks](./learn-account-balances.md#locks), these funds cannot be transferred -but can be used in other parts of the protocol such as voting in governance or being staked as a -validator or nominator. +DOT may have a lock to account for vesting funds. Like other types of +[locks](./learn-account-balances.md#locks), these funds cannot be transferred but can be used in +other parts of the protocol such as voting in governance or being staked as a validator or +nominator. Vesting funds are on a release schedule that unlocks a constant number of tokens at each block (**linear vesting**) or the full amount after a specific block number (**cliff vesting**). In all @@ -120,8 +115,7 @@ funds to the desired destination account. ## Transaction Fees Storage and computation are limited resources in a blockchain network. Transaction fees prevent -individual users from consuming too many resources. -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} uses a **weight-based fee model** as +individual users from consuming too many resources. Polkadot uses a **weight-based fee model** as opposed to a gas-metering model. As such, fees are charged before transaction execution. Once the fee is paid, nodes will execute the transaction. @@ -160,13 +154,12 @@ details. ### Fee Multiplier -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} can add an additional fee to -transactions if the network becomes too busy and starts to decelerate the system. This additional -fee is known as the `Fee Multiplier` and its value is defined by the -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} runtime. The multiplier compares the -saturation of blocks; if the previous block is less saturated than the current block (implying an -uptrend in usage), the fee is slightly increased. Similarly, the fee is decreased if the previous -block is more saturated than the current block (implying a downtrend in usage). +Polkadot can add an additional fee to transactions if the network becomes too busy and starts to +decelerate the system. This additional fee is known as the `Fee Multiplier` and its value is defined +by the runtime. The multiplier compares the saturation of blocks; if the previous block is less +saturated than the current block (implying an uptrend in usage), the fee is slightly increased. +Similarly, the fee is decreased if the previous block is more saturated than the current block +(implying a downtrend in usage). The multiplier can create an incentive to avoid the production of low-priority or insignificant transactions. In contrast, those additional fees will decrease if the network calms down and @@ -200,11 +193,10 @@ transactions warrant limiting resources with other strategies. For example: ## Parachain Transactions -The transactions that take place within -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}'s parachains do not incur relay chain -transaction fees. Users of shard applications do not even need to hold DOT tokens, as each shard has -its own economic model and may or may not have a token. There are, however, situations where shards -themselves make transactions on the relay chain. +The transactions that take place within parachains do not incur relay chain transaction fees. Users +of shard applications do not even need to hold DOT tokens, as each shard has its own economic model +and may or may not have a token. There are, however, situations where shards themselves make +transactions on the relay chain. [Parachains](learn-parachains.md) have a dedicated slot on the relay chain for execution, so their collators do not need to own DOT in order to include blocks. The parachain will make some @@ -215,11 +207,10 @@ parachain's behalf. ## Block Limits and Transaction Priority -Blocks in {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} have both a maximum length -(in bytes) and a maximum weight. Block producers will fill blocks with transactions up to these -limits. A portion of each block - currently 25% - is reserved for critical transactions that are -related to the chain's operation. Block producers will only fill up to 75% of a block with normal -transactions. Some examples of operational transactions: +Relay chain blocks have both a maximum length (in bytes) and a maximum weight. Block producers will +fill blocks with transactions up to these limits. A portion of each block - currently 25% - is +reserved for critical transactions that are related to the chain's operation. Block producers will +only fill up to 75% of a block with normal transactions. Some examples of operational transactions: - Misbehavior reports - Council operations diff --git a/docs/learn/learn-validator.md b/docs/learn/learn-validator.md index 13744e3c912e..76ba717c4c47 100644 --- a/docs/learn/learn-validator.md +++ b/docs/learn/learn-validator.md @@ -11,15 +11,13 @@ import RPC from "./../../components/RPC-Connection"; :::info -This page provides a general overview of the role of validators in -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}. For more detailed information you -can read the [Parachain Protocol Overview](./learn-parachains-protocol.md). +This page provides a general overview of the role of validators in the Polkadot network. For more +detailed information you can read the [Parachain Protocol Overview](./learn-parachains-protocol.md). ::: -Validators secure the [relay chain](learn-architecture.md#relay-chain) by staking -{{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }}, validating proofs from collators and -participating in consensus with other validators. +Validators secure the [relay chain](learn-architecture.md#relay-chain) by staking native tokens, +validating proofs from collators and participating in consensus with other validators. Validators play a crucial role in adding new blocks to the relay chain and, by extension, to all parachains. This allows parties to complete cross-chain transactions via the relay chain. They @@ -79,11 +77,10 @@ system. Any instances of non-compliance with the consensus algorithms result in [**disputes**](./learn-parachains-protocol.md/#disputes) with the punishment of the validators on -the wrong side by removing some or all their staked -{{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }}, thereby discouraging bad actors. Good +the wrong side by removing some or all their staked tokens, thereby discouraging bad actors. Good performance, however, will be rewarded, with validators receiving block rewards (including -transaction fees) in the form of {{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} in exchange -for their activities. +transaction fees) in the form of native tokens (DOT or KSM on Kusama) in exchange for their +activities. Finally, validators participate in the [chain selection process within GRANDPA](./learn-parachains-protocol.md/#chain-selection), ensuring diff --git a/docs/learn/learn-xcm-transport.md b/docs/learn/learn-xcm-transport.md index 481298143d70..2874160185ab 100644 --- a/docs/learn/learn-xcm-transport.md +++ b/docs/learn/learn-xcm-transport.md @@ -15,8 +15,8 @@ mind that XCM is under active development. ::: With the XCM format established, common patterns for protocols of these messages are needed. -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} implements two message passing -protocols for acting on XCM messages between its constituent parachains. +Polkadot implements two message passing protocols for acting on XCM messages between its constituent +parachains. There are three primary methods for message passing, one of which is under development: @@ -49,9 +49,8 @@ ensure fidelity. It is the task of the relay chain validators to move transactio queue of one parachain into the input queue of the destination parachain. However, only the associated metadata is stored as a hash in the relay chain storage. -The input and output queue are sometimes referred to in the -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} codebase and associated documentation -as `ingress` and `egress` messages, respectively. +The input and output queue are sometimes referred to in the Polkadot codebase and associated +documentation as `ingress` and `egress` messages, respectively. :::info diff --git a/docs/learn/learn-xcm.md b/docs/learn/learn-xcm.md index fa9a4dff3d98..f3012ea74dbe 100644 --- a/docs/learn/learn-xcm.md +++ b/docs/learn/learn-xcm.md @@ -17,10 +17,10 @@ mind that XCM is under active development. The Cross-Consensus Message Format, or **XCM**, is a **messaging format** and language used to communicate between consensus systems. -One of {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}'s main functionalities is -interoperability amongst parachains and any other participating consensus-driven systems. XCM is the -language through which complex, cross-consensus interactions can occur. Two blockchains can "speak" -XCM to seamlessly interact with each other using a standard messaging format. +One of Polkadot's main functionalities is interoperability amongst parachains and any other +participating consensus-driven systems. XCM is the language through which complex, cross-consensus +interactions can occur. Two blockchains can "speak" XCM to seamlessly interact with each other using +a standard messaging format. :::info @@ -31,9 +31,8 @@ parachain, an EVM smart contract, or other bridged consensus systems. ::: -XCM is not meant to be only specific to -{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}, but rather its primary intention is -to define a **generic** and **common** format amongst different consensus systems to communicate. +XCM is not meant to be only specific to Polkadot, but rather its primary intention is to define a +**generic** and **common** format amongst different consensus systems to communicate. It's important to note that XCM does not define how messages are delivered but rather define how they should look, act, and contain relative instructions to the on-chain actions the message intends @@ -66,8 +65,7 @@ issues. :::note XCM is constantly in development - meaning the format is expected to change over time. XCM v3 is the -latest version, and is deployed on {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }}. -To view updates on the XCM format, visit the +latest version, and is deployed on Polkadot. To view updates on the XCM format, visit the [xcm-format repository](https://github.com/paritytech/xcm-format) to view any RFCs that have been submitted that would contribute to the next release.