"Learn" section update

docs/glossary.md

@@ -4,6 +4,10 @@ title: Terms and Definitions
 sidebar_label: Terms and Definitions
 ---
 
+## Alexander
+
+The most up-to-date testnet for Polkadot.
+
 ## Block
 
 A collection of data, such as transactions, that together indicate a state transition of the blockchain.
@@ -44,6 +48,10 @@ The native token for Polkadot.  DOTs serve three purposes: network governance (a
 
 A generic term for a decentralized application, that is, one which runs as part of a distributed network as opposed to being run on a specific system or set of systems.
 
+## Equivocation
+
+Providing conflicting information to the network.  BABE equivocation entails creating multiple blocks in the same slot.  GRANDPA equivocation would consist of signing multiple conflicting chains.
+
 ## Extrinsic
 
 Generically, some function declared by the programmer, i.e., one that is not built-in to the language or framework.  Specifically for Polkadot, this refers to a binary blob which represents some state transition (such as a transaction) and is used for parachains to communicate via the relay chain.
@@ -72,6 +80,14 @@ The process of determining what changes to the network are permissible, such as
 
 An on-chain entity which consists of several on-chain accounts (starting at 6, eventually moving to the final value of 24) which can act as a representative for "passive" (non-voting) stakeholders.  Council members have two main tasks: proposing referenda for the overall stakeholder group to vote on and cancelling malicious referenda.
 
+## KSM
+
+The abbreviation for Kusama network tokens.
+
+## Kusama
+
+The "canary network" for Polkadot.  It consists of an early-release, unaudited version of the Polkadot software.  It is not a testnet - after the transition to NPoS, the network is entirely in the hands of the community (i.e., Kusama token holders).
+
 ## LIBP2P
 
 An open-source library for encrypted peer-to-peer communications and other networking functionality.  More information at: [https://libp2p.io/](https://libp2p.io/)
@@ -86,7 +102,7 @@ A tool which gives you information about a node, such as the latest blocks seale
 
 ## Nominated Proof of Stake (NPoS)
 
-A proof of stake system whereby nominators "lend" their stake to validators, as a show of faith in the good behavior of the validator.  Nominated proof-of-stake differs from delegated proof-of-stake in that nominators are subject to loss of stake if they nominate a bad validator; delegates are not subject to loss of stake based on the behavior of the validator.
+A proof of stake system whereby nominators "lend" their stake to validators, as a show of faith in the good behavior of the validator.  Nominated proof-of-stake differs from the more generic concept delegated proof of stake in that nominators are subject to loss of stake if they nominate a bad validator; delegates are not subject to loss of stake based on the behavior of the validator.  Note that some other blockchain technologies may use the term delegated proof of stake, even if delegates can be slashed.
 
 ## Nominator
 
@@ -160,6 +176,10 @@ Another name for the session "key" which is a BLS key for GRANDPA, a sr25519 key
 
 A session "key" is a BLS key for GRANDPA, a sr25519 key for BABE, and eventually an Ed25519 key for libp2p.
 
+## Slashing
+
+The removal of a percentage of an account's DOTs as a punishment for a validator acting maliciously or incompetently (e.g., equivocating or remaining offline for an extended period of time).
+
 ## Staking
 
 "Reserving" tokens (for Polkadot, DOTs) which are put up as "collateral" for a chance to produce a valid block (and thus obtain a block reward).  Validators and nominators (who back validators through NPoS) together stake their DOTs in order to add blocks to the relay chain.
@@ -172,6 +192,10 @@ A function which describes how the state of a blockchain can be transformed.  Fo
 
 An implementation of the Polkadot Runtime Environment which allows developers to generate parachains which are compatible with the Polkadot relay chain.
 
+## Tabling
+
+In Polkadot governance, bringing a proposal to a vote via referendum.  Note that this is the British meaning of "tabling", which is different than the US version, which means "to postpone" a measure.
+
 ## Transaction
 
 An individual element of the state transition function of a block, such as moving tokens from one account to another.

docs/learn-DOT.md

@@ -6,10 +6,9 @@ sidebar_label: DOT
 
 ## What are DOTs?
 
-DOT is the native token of the Polkadot network in a similar way that BTC is the native
-token of Bitcoin or Ether is the native token of the Ethereum Blockchain.
+DOT is the native token of the Polkadot network in a similar way that BTC is the native token of Bitcoin or Ether is the native token of the Ethereum Blockchain.
 
-Currently, DOTs have 15 decimal places, while the smallest unit is called the Planck. You can compare the Planck to Satoshis or Wei, while the DOT is like a bitcoin or an ether.
+Alexander testnet DOTs have 15 decimal places, while the smallest unit is called the Planck. Kusama tokens (KSM) have 12 decimal places.  You can compare the Planck to Satoshis or Wei, while the DOT is like a bitcoin or an ether.
 
 **The table show as below is the old version.**
 
@@ -28,20 +27,32 @@ Currently, DOTs have 15 decimal places, while the smallest unit is called the Pl
 | --- | --- |
 Planck| 1
 Point | 3
-Microdot (UDOT)| 6
-Millidot (MDOT)| 9
+Microdot (uDOT)| 6
+Millidot (mDOT)| 9
 Dot (DOT) | 12
 Blob | 15
 
+**Kusama**
+|Unit |Decimal Places|
+| --- | --- |
+Planck| 1
+Point | 3
+MicroKSM (uKSM)| 6
+MilliKSM (mKSM)| 9
+KSM (DOT) | 12
+
+
 ## What are the uses of DOTs?
 
 DOTs serve three key functions in Polkadot, (i) to be used for governance of the network, (ii) to be staked for operation of the network, and (iii) to be bonded to connect a chain to Polkadot as a parachain.
 
+DOTs can also serve ancillary functions by virtue of being a transferrable token.  For example, DOTs stored in the Treasury can be sent to teams working on relevant projects for the Polkadot network.
+
 ### DOTs for governance
 
-The first function of DOTs will be to entitle holders to control of the governance of the platform. Some functions which will be included under the governance mechanism include determining the fees of the network, the addition or removal of parachains, and exceptional events such as upgrades and fixes to the Polkadot platform.
+The first function of DOTs is to entitle holders to control of the governance of the platform. Some functions which are included under the governance mechanism include determining the fees of the network, the addition or removal of parachains, and exceptional events such as upgrades and fixes to the Polkadot platform.
 
-The governance mechanism will not be formally granted to all holders of DOTs but rather the underlying code of Polkadot will enable a holder of DOTs to participate in governance.
+Polkadot will enable any holder of DOTs to participate in governance.  For details on how holders can participate in governance, as well as their rights and responsibilities, see the [governance page](polkadot-learn-governance).
 
 ### DOTs for consensus
 
@@ -53,7 +64,7 @@ DOTs will have the ability to be bonded for a duration of time in order to add a
 
 ## Mainnet DOTs
 
-Web3 Foundation will distribute up to 20% of mainnet DOTs prior to network launch later this year (see [Light Paper](https://polkadot.network/Polkadot-lightpaper.pdf) or the [Polkadot Network FAQ](https://polkadot.network/faq/)). As Project Founder Gavin Wood said in his year-end recap, there may be a generally available public sale for some portion of that amount at some point this year. Subscribe to the Polkadot newsletter on [polkadot.network](https://polkadot.network/) for further updates.
+Web3 Foundation will distribute up to 20% of mainnet DOTs prior to network launch in 2019 (see the [Light Paper](https://polkadot.network/Polkadot-lightpaper.pdf) or the [Polkadot Network FAQ](https://polkadot.network/faq/)). As Project Founder Gavin Wood said in his year-end recap, there may be a generally available public sale for some portion of that amount at some point this year. Subscribe to the Polkadot newsletter on [polkadot.network](https://polkadot.network/) for further updates.
 
 _Warning: Mainnet DOT tokens are not transferrable until mainnet launch, expected late 2019. Therefore any transfers of Mainnet DOTs are illegitimate and unauthorized. DOTs can not be moved from a current allocation address. Individuals with an allocation of DOTs who transfer their DOT address to someone else can always keep a copy of their private key, therefore there is extreme risk for individuals participating in transfers of DOTs before mainnet launch._
 
@@ -68,3 +79,7 @@ DOTs are required to make transactions on the Polkadot network. Testnet DOTs do
 You can request DOTs from the [Polkadot faucet](https://faucet.polkadot.network/), the [BlockX Labs faucet](https://faucets.blockxlabs.com/) or ask someone to send you DOTs on the [Polkadot Watercooler](https://riot.im/app/#/room/#polkadot-watercooler:matrix.org).
 
 You can make your own DOTs by [becoming a validator](https://wiki.polkadot.network/en/latest/polkadot/node/guides/how-to-validate/).
+
+## Kusama Tokens
+
+Unlike testnet DOTs, Kusama tokens are not freely given away.  Kusama tokens are available via the [claims process](https://claim.kusama.network/) (if you have already purchased DOTs), the frictional faucet (online soon), or via [grant request](http://grants.web3.foundation) from the Web3 Foundation.

docs/learn-PRE.md

@@ -4,7 +4,7 @@ title: Polkadot Runtime Environment (PRE)
 sidebar_label: Polkadot Runtime Environment (PRE)
 ---
 
-The Polkadot Runtime Environment is an important component of the Polkadot protocol. It consists of the networking, consensus and Wasm VM and acts as the lower layers of the stack which are underlying the Polkadot runtime and the runtimes of the parachains. Loosely, the Polkadot RE can be thought of as synonymous with the Polkadot relay chain (although as stated below there is a clear separation between the chain logic and the PRE).
+The Polkadot Runtime Environment is an important component of the Polkadot protocol. It consists of the networking, consensus and Wasm VM subsystems, and acts as the lower layers of the stack underlying the Polkadot runtime and the runtimes of the parachains. Loosely, the Polkadot RE can be thought of as synonymous with a virtual machine running the Polkadot relay chain (although as stated below, there is a clear separation between the chain logic itself, and the PRE on which it runs).
 
 The components of the Polkadot RE are:
 

docs/learn-auction.md

@@ -4,12 +4,7 @@ title: Parachain Slots Auction
 sidebar_label: Parachain Slots Auction
 ---
 
-<div class="img-container">
-    <a href="https://slides.com/paritytech/validating-in-polkadot#/20" target="_blank">
-        <img alt="Polkadot's roadmap to 200 parachains" src="assets/parachain-roadmap.jpg"/>
-    </a>
-    Parachain auction schedule. [Click for slide]
-</div>
+![Parachain Roadmap](assets/parachain-roadmap.jpg)
 
 The parachain slots of Polkadot will be sold according to an unpermissioned [Candle auction](https://en.wikipedia.org/wiki/Candle_auction) which has been slightly modified to be secure on a blockchain.
 
@@ -21,21 +16,21 @@ Candle auctions were originally employed in 16th century for the sale of ships a
 
 When Candle auctions are used online, they require a random number to decide the moment of termination.
 
-Parachain slot auctions will differ slightly from a normal Candle auction in that it does not use the random number to decide the duration of its opening phase. Instead, it has a known open phase and will be retroactively determined (at the normal close) to have ended at some point in the past. So during the open phase, bids will continue to be accepted but, later bids have higher probability of losing since the retroactively determined close moment may be found to be preceding the moment a bid was submitted.
+Parachain slot auctions will differ slightly from a normal Candle auction in that it does not use the random number to decide the duration of its opening phase. Instead, it has a known open phase and will be retroactively determined (at the normal close) to have ended at some point in the past. So during the open phase, bids will continue to be accepted but, later bids have higher probability of losing since the retroactively determined close moment may be found to have preceded the time that a bid was submitted.
 
 ## Why use a Candle auction?
 
 The open and transparent nature of blockchain systems opens attack vectors which are non-existent in traditional auction formats. Normal open auctions in particular can be vulnerable to _auction sniping_ when implemented over the internet or on a blockchain.
 
 Auction sniping takes place when the end of an auction is known and bidders are hesitant to bid their true price early, in hopes of paying less than they actually value the item.
 
-For example, Alice may value an item at auction for 30 USD. She submits an initial bid of 10 USD in hopes of acquiring the items at a lower price. Alice's strategy is place incrementally higher bids until her true value of 30 USD is exceeded. Another bidder Eve values the same item at 11 USD. Eve's strategy is to watch the auction and submit a bid of 11 USD at the last second. Alice will have no time to respond to this bid before the close of the auction and will lose the item. The auction mechanism is sub-optimal because it has not discovered the true price of the item and the item has not gone to the actor whom valued it the most.
+For example, Alice may value an item at auction for 30 USD. She submits an initial bid of 10 USD in hopes of acquiring the items at a lower price. Alice's strategy is to place incrementally higher bids until her true value of 30 USD is exceeded. Another bidder Eve values the same item at 11 USD. Eve's strategy is to watch the auction and submit a bid of 11 USD at the last second. Alice will have no time to respond to this bid before the close of the auction and will lose the item. The auction mechanism is sub-optimal because it has not discovered the true price of the item and the item has not gone to the actor who valued it the most.
 
-On blockchains this may be even worse since it potentially gives the producer of the block an opportunity to snipe any auction at the last concluding block. There is also the possibility of a malicious bidder or a block producer to _grief_ honest bidders by sniping auctions.
+On blockchains this problem may be even worse, since it potentially gives the producer of the block an opportunity to snipe any auction at the last concluding block by adding it themselves and/or ignoring other bids. There is also the possibility of a malicious bidder or a block producer trying to _grief_ honest bidders by sniping auctions.
 
 For this reason, [Vickrey auctions](https://en.wikipedia.org/wiki/Vickrey_auction), a variant of second price auction in which bids are hidden and only revealed in a later phase, have emerged as a well-regarded mechanic. For example, it is implemented as the mechanism to auction human readable names on the [ENS](https://ens.domains). The Candle auction is another solution which does not need the two-step commit and reveal schemes (a main component of Vickrey auctions), and for this reason allows smart contracts to participate.
 
-Candle auctions make it so that everyone always know the states of the bid, but not when the auction will be determined to have "ended." This helps to ensure that bidders are willing to bid their true bids early. Otherwise they might find themselves in the situation that the auction was determined to have "ended" before they even bid.
+Candle auctions allow everyone to always know the states of the bid, but not when the auction will be determined to have "ended." This helps to ensure that bidders are willing to bid their true bids early. Otherwise, they might find themselves in the situation that the auction was determined to have "ended" before they even bid.
 
 ## How it's used in Polkadot
 
@@ -138,7 +133,7 @@ For the duration of the slot the `DOTs` bid in the auction will be locked up. Th
 
 ### How does this mechanism help ensure parachain diversity?
 
-The method for dividing the parachain slots into six month intervals was partly inspired by the desire to allow for a greater amount of parachain diversity, and prevent particularly large and well-funded parachains from hoarding slots. By making each period a six-month duration but the overall slot a 2-year duration, the mechanism can cope with well-funded parachains that will ensure they secure a slot at the end of their lease while gradually allowing other parachains to enter the ecosystem to occupy the six-month durations which are not filled. For example, if a large, well-funded parachain has already acquired a slot for range 1 - 4, they would be very interested in getting the next slot which would open for 2 - 5. Under this mechanism that parachain could acquire period 5 (since that is the only one it needs) and allow range 2 - 4 of the second parachain slot to be occupied by another.
+The method for dividing the parachain slots into six month intervals was partly inspired by the desire to allow for a greater amount of parachain diversity, and prevent particularly large and well-funded parachains from hoarding slots. By making each period a six-month duration but the overall slot a 2-year duration, the mechanism can cope with well-funded parachains that will ensure they secure a slot at the end of their lease, while gradually allowing other parachains to enter the ecosystem to occupy the six-month durations which are not filled. For example, if a large, well-funded parachain has already acquired a slot for range 1 - 4, they would be very interested in getting the next slot which would open for 2 - 5. Under this mechanism that parachain could acquire period 5 (since that is the only one it needs) and allow range 2 - 4 of the second parachain slot to be occupied by another.
 
 ### Why is randomness difficult on blockchains?