Merge pull request #333 from anoma/abuzer/specs-update

Update Namada Specs

documentation/specs/src/SUMMARY.md

@@ -2,7 +2,7 @@
 
 - [Introduction](./introduction.md)
 - [Base ledger](./base-ledger.md)
-    - [Consensus](./base-ledger/consensus.md)
+    - [Core Concepts](./base-ledger/core-concepts.md)
     - [Execution](./base-ledger/execution.md)
     - [Governance](./base-ledger/governance.md)
     - [Default account](./base-ledger/default-account.md)

documentation/specs/src/base-ledger.md

@@ -1,3 +1,3 @@
 ## Base ledger
 
-The base ledger of Namada includes a [consensus system](./base-ledger/consensus.md), validity predicate-based [execution system](./base-ledger/execution.md), and signalling-based [governance mechanism](./base-ledger/governance.md). Namada's ledger also includes proof-of-stake, slashing, fees, and inflation funding for staking rewards, shielded pool incentives, and public goods -- these are specified in the [economics section](./economics.md).
+The base ledger of Namada includes a [consensus system](./base-ledger/core-concepts.md), validity predicate-based [execution system](./base-ledger/execution.md), and signalling-based [governance mechanism](./base-ledger/governance.md). Namada's ledger also includes proof-of-stake, slashing, fees, and inflation funding for staking rewards, shielded pool incentives, and public goods -- these are specified in the [economics section](./economics.md)

documentation/specs/src/base-ledger/core-concepts.md

@@ -0,0 +1,3 @@
+# Consensus
+
+Namada uses [Tendermint Go](https://github.com/tendermint/tendermint) through the [tendermint-rs](https://github.com/heliaxdev/tendermint-rs) bindings in order to provide peer-to-peer transaction gossip, BFT consensus, and state machine replication for Namada's custom state machine.

documentation/specs/src/base-ledger/execution.md

@@ -2,17 +2,20 @@
 
 The Namada ledger execution system is based on an initial version of the [Anoma protocol](https://specs.anoma.net). The system implements a generic computational substrate with WASM-based transactions and validity predicate verification architecture, on top of which specific features of Namada such as IBC, proof-of-stake, and the MASP are built.
 
+## Validity predicates
+
+Conceptually, a validity predicate (VP) is a function from the transaction's data and the storage state prior and posterior to a transaction execution returning a boolean value. A transaction may modify any data in the accounts' dynamic storage sub-space. Upon transaction execution, the VPs associated with the accounts whose storage has been modified are invoked to verify the transaction. If any of them reject the transaction, all of its storage modifications are discarded. 
 ## Namada ledger
 
-The Namada ledger is built on top of [Tendermint](https://docs.tendermint.com/master/spec/)'s [ABCI](https://docs.tendermint.com/master/spec/abci/) interface with a slight deviation from the ABCI convention: in Namada, the transactions are currently *not* being executed in ABCI's `DeliverTx` method, but rather in the `EndBlock` method. The reason for this is to prepare for future DKG and threshold decryption integration, which has not yet been fully finished and hence is out-of-scope for the initial release version of Namada.
+The Namada ledger is built on top of [Tendermint](https://docs.tendermint.com/master/spec/)'s [ABCI](https://docs.tendermint.com/master/spec/abci/) interface with a slight deviation from the ABCI convention: in Namada, the transactions are currently *not* being executed in ABCI's [`DeliverTx` method](https://docs.tendermint.com/master/spec/abci/abci.html), but rather in the [`EndBlock` method](https://docs.tendermint.com/master/spec/abci/abci.html). The reason for this is to prepare for future DKG and threshold decryption integration. 
 
 The ledger features an account-based system (in which UTXO-based systems such as the MASP can be internally implemented as specific accounts), where each account has a unique address and a dynamic key-value storage sub-space. Every account in Namada is associated with exactly one validity predicate. Fungible tokens, for example, are accounts, whose rules are governed by their validity predicates. Many of the base ledger subsystems specified here are themselves just special Namada accounts too (e.g. PoS, IBC and MASP).
 
-Interaction with the Namada ledger are made possible via transactions (note [transaction whitelist](#transaction-and-validity-predicate-whitelist)). Please refer to the [protocol section](https://docs.anoma.network/master/specs/ledger.html#the-protocol) that specifies the transaction execution model. In Namada, transactions are allowed to perform arbitrary modifications to the storage of any account, but the transaction will be accepted and state changes applied only if all the validity predicates that were triggered by the transaction accept it. That is, the accounts whose storage sub-spaces were touched by the transaction and/or an account that was explicitly elected by the transaction as the verifier will all have their validity predicates verifying the transaction. A transaction can add any number of additional verifiers, but cannot remove the ones determined by the protocol. For example, a transparent fungible token transfer would typically trigger 3 validity predicates - those of the token, source and target addresses.
+Interaction with the Namada ledger are made possible via transactions (note transaction whitelist below). In Namada, transactions are allowed to perform arbitrary modifications to the storage of any account, but the transaction will be accepted and state changes applied only if all the validity predicates that were triggered by the transaction accept it. That is, the accounts whose storage sub-spaces were touched by the transaction and/or an account that was explicitly elected by the transaction as the verifier will all have their validity predicates verifying the transaction. A transaction can add any number of additional verifiers, but cannot remove the ones determined by the protocol. For example, a transparent fungible token transfer would typically trigger 3 validity predicates - those of the token, source and target addresses.
 
 ## Supported validity predicates
 
-Conceptually, a VP is a function from the transaction's data and the storage state prior and posterior to a transaction execution returning a boolean value. A transaction may modify any data in the accounts' dynamic storage sub-space. Upon transaction execution, the VPs associated with the accounts whose storage has been modified are invoked to verify the transaction. If any of them reject the transaction, all of its storage modifications are discarded. While the execution model is fully programmable, for Namada only a selected subset of provided validity predicates and transactions will be permitted through pre-defined whitelists configured at network launch. 
+While the execution model is fully programmable, for Namada only a selected subset of provided validity predicates and transactions will be permitted through pre-defined whitelists configured at network launch. 
 
 There are some native VPs for internal transparent addresses that are built into the ledger. All the other VPs are implemented as WASM programs. One can build a custom VP using the [VP template](https://github.com/anoma/anoma/tree/master/wasm/vp_template) or use one of the pre-defined VPs.
 
@@ -24,7 +27,7 @@ Supported validity predicates for Namada:
     - SlashFund (see [spec](./governance.md#SlashFundAddress))
     - Protocol parameters
 - WASM
-    - Fungible token (see [spec](./fungible-token.md))
+    - Fungible token (see [spec](./core-concepts.md))
     - MASP (see [spec](../masp.md))
-    - Implicit account VP (see [spec](./default-account.md))
-    - k-of-n multisignature VP (see [spec](./multisignature.md))
+    - Implicit account VP (see [spec](./core-concepts.md))
+    - k-of-n multisignature VP (see [spec](./core-concepts.md))

documentation/specs/src/base-ledger/governance.md

@@ -1,18 +1,31 @@
 # Namada Governance
 
+Before describing Namada governance, it is useful to define the concepts of validators, delegators, and NAM.
+
+Namada's economic model is based around a single native token, NAM, which is controlled by the protocol.
+
+A Namada validator is an account with a public consensus key, which may participate in producing blocks and governance activities. A validator may not also be a delegator.
+
+A Namada delegator is an account that delegates some tokens to a validator. A delegator may not also be a validator.
+
 Namada introduces a governance mechanism to propose and apply protocol changes with  or without the need for a hard fork. Anyone holding some `NAM` will be able to propose some changes to which delegators and validators will cast their `yay` or `nay` votes. Governance on Namada supports both `signaling` and `voting` mechanisms. The difference between the the two is that the former is needed when the changes require a hard fork. In cases where the chain is not able to produce blocks anymore, Namada relies on [off chain](#off-chain-protocol) signaling to agree on a common move.
 
+Further informtion regarding delegators, validators, and NAM is contained in the [economics section](../economics.md).
+
 ## On-chain protocol
 
 ### Governance Address
+
 Governance adds 2 internal addresses:
+
 - `GovernanceAddress`
 - `SlashFundAddress`
 
 The first internal address contains all the proposals under its address space.
 The second internal address holds the funds of rejected proposals.
 
 ### Governance storage
+
 Each proposal will be stored in a sub-key under the internal proposal address. The storage keys involved are:
 
 ```
@@ -26,6 +39,8 @@ Each proposal will be stored in a sub-key under the internal proposal address. T
 /\$GovernanceAddress/proposal/epoch/\$id: u64
 ```
 
+An epoch is a range of blocks or time that is defined by the base ledger and made available to the PoS system. This document assumes that epochs are identified by consecutive natural numbers. All the data relevant to PoS are [associated with epochs](../economics/proof-of-stake/bonding-mechanism.md#epoched-data).
+
 - `Author` address field will be used to credit the locked funds if the proposal is approved.
 - `/\$GovernanceAddress/proposal/\$epoch/\$id` is used for easing the ledger governance execution. `\$epoch` refers to the same value as the on specific in the `grace_epoch` field.
 - The `content` value should follow a standard format. We leverage a similar format to what is described in the [BIP2](https://github.com/bitcoin/bips/blob/master/bip-0002.mediawiki#bip-format-and-structure) document:
@@ -74,23 +89,25 @@ This is to leverage the `NAM` VP to check that the funds were correctly locked.
 The governance subkey, `/\$GovernanceAddress/proposal/\$id/funds` will be used after the tally step to know the exact amount of tokens to refund or move to Treasury.
 
 ### GovernanceAddress VP
-Just like Pos, also governance has his own storage space. The `GovernanceAddress` validity predicate task is to check the integrity and correctness of new proposals. A proposal, to be correct, must satisfy the following:
+
+Just like PoS, also governance has its own storage space. The `GovernanceAddress` validity predicate task is to check the integrity and correctness of new proposals. A proposal, to be correct, must satisfy the following:
+
 - Mandatory storage writes are:
-    - counter
-    - author
-    - funds
-    - voting_start epoch
-    - voting_end epoch
-    - grace_epoch
+  - counter
+  - author
+  - funds
+  - voting_start epoch
+  - voting_end epoch
+  - grace_epoch
 - Lock some funds >= `min_proposal_fund`
 - Contains a unique ID
 - Contains a start, end and grace Epoch
 - The difference between StartEpoch and EndEpoch should be >= `min_proposal_period`.
 - Should contain a text describing the proposal with length < `max_proposal_content_size` characters.
 - Vote can be done only by a delegator or validator
 - Validator can vote only in the initial 2/3 of the whole proposal duration (`end_epoch` - `start_epoch`)
-- Due to the previous requirement, the following must be true,`(EndEpoch - StartEpoch) % 3 == 0` 
-- If defined, `proposalCode` should be the wasm bytecode representation of 
+- Due to the previous requirement, the following must be true,`(EndEpoch - StartEpoch) % 3 == 0`
+- If defined, `proposalCode` should be the wasm bytecode representation of
   the changes. This code is triggered in case the proposal has a position outcome.
 - The difference between `grace_epoch` and `end_epoch` should be of at least `min_proposal_grace_epochs`
 
@@ -100,6 +117,7 @@ If `proposal_code`  is `Empty` or `None` , the proposal upgrade will need to be
 It is possible to check the actual implementation [here](https://github.com/anoma/namada/blob/master/shared/src/ledger/governance/mod.rs#L69).
 
 Example of `proposalCode` could be:
+
 - storage writes to change some protocol parameter
 - storage writes to restore a slash
 - storage writes to change a non-native vp
@@ -140,19 +158,20 @@ Vote transaction creates or modifies the following storage key:
 /\$GovernanceAddress/proposal/\$id/vote/\$delegation_address/\$voter_address: Enum(yay|nay)
 ```
 
-The storage key will only be created if the transaction is signed either by 
-a validator or a delegator. 
+The storage key will only be created if the transaction is signed either by
+a validator or a delegator.
 Validators will be able to vote only for 2/3 of the total voting period, while delegators can vote until the end of the voting period.
 
-If a delegator votes opposite to its validator, this will *override* the 
+If a delegator votes opposite to its validator, this will *override* the
 corresponding vote of this validator (e.g. if a delegator has a voting power of 200 and votes opposite to the delegator holding these tokens, than 200 will be subtracted from the voting power of the involved validator).
 
 As a small form of space/gas optimization, if a delegator votes accordingly to its validator, the vote will not actually be submitted to the chain. This logic is applied only if the following conditions are satisfied:
 
 - The transaction is not being forced
-- The vote is submitted in the last third of the voting period (the one exclusive to delegators). This second condition is necessary to prevent a validator from changing its vote after a delegator vote has been submitted, effectively stealing the delegator's vote.   
+- The vote is submitted in the last third of the voting period (the one exclusive to delegators). This second condition is necessary to prevent a validator from changing its vote after a delegator vote has been submitted, effectively stealing the delegator's vote.
 
 ### Tally
+
 At the beginning of each new epoch (and only then), in the `FinalizeBlock` event, tallying will occur for all the proposals ending at this epoch (specified via the `grace_epoch` field of the proposal).
 The proposal has a positive outcome if 2/3 of the staked `NAM` total is voting `yay`. Tallying is computed with the following rules:
 
@@ -166,42 +185,50 @@ All the computation above must be made at the epoch specified in the `start_epoc
 It is possible to check the actual implementation [here](https://github.com/anoma/namada/blob/master/shared/src/ledger/governance/utils.rs#L68).
 
 ### Refund and Proposal Execution mechanism
-Together with tallying, in the first block at the beginning of each epoch, in the `FinalizeBlock` event, the protocol will manage the execution of accepted proposals and refunding. For each ended proposal with a positive outcome, it will refund the locked funds from `GovernanceAddress` to the proposal author address (specified in the proposal `author` field). For each proposal that has been rejected, instead, the locked funds will be moved to the `SlashFundAddress`. Moreover, if the proposal had a positive outcome and `proposal_code` is defined, these changes will be executed right away.
+
+Together with tallying, in the first block at the beginning of each epoch, in the `FinalizeBlock` event, the protocol will manage the execution of accepted proposals and refunding. A successful proposal will refund the locked funds from `GovernanceAddress` to the proposal author address (specified in the proposal `author` field). A failed proposal will move locked funds to `SlashFundAddress`. Moreover, if the proposal had a positive outcome and `proposal_code` is defined, these changes will be executed right away.
 To summarize the execution of governance in the `FinalizeBlock` event:
 
 If the proposal outcome is positive and current epoch is equal to the proposal `grace_epoch`, in the `FinalizeBlock` event:
+
 - transfer the locked funds to the proposal `author`
 - execute any changes specified by `proposal_code`
 
 In case the proposal was rejected or if any error, in the `FinalizeBlock` event:
-- transfer the locked funds to `SlashFundAddress`
 
-The result is then signaled by creating and inserting a [`Tendermint Event`](https://github.com/tendermint/tendermint/blob/ab0835463f1f89dcadf83f9492e98d85583b0e71/docs/spec/abci/abci.md#events.
+- transfer the locked funds to `SlashFundAddress`
 
+The result is then signaled by creating and inserting a [`Tendermint Event`](https://github.com/tendermint/tendermint/blob/ab0835463f1f89dcadf83f9492e98d85583b0e71/docs/spec/abci/abci.md#events).
 
 ## SlashFundAddress
+
 Funds locked in `SlashFundAddress` address should be spendable only by proposals.
 
 ### SlashFundAddress storage
+
 ```
 /\$SlashFundAddress/?: Vec<u8>
 ```
 
 The funds will be stored under:
+
 ```
 /\$NAMAddress/balance/\$SlashFundAddress: u64
 ```
 
 ### SlashFundAddress VP
+
 The slash_fund validity predicate will approve a transfer only if the transfer has been made by the protocol (by checking the existence of `/\$GovernanceAddress/pending/\$proposal_id` storage key)
 
 It is possible to check the actual implementation [here](https://github.com/anoma/namada/blob/main/shared/src/ledger/slash_fund/mod.rs#L70).
 
 ## Off-chain protocol
 
 ### Create proposal
-A CLI command to create a signed JSON representation of the proposal. The 
+
+A CLI command to create a signed JSON representation of the proposal. The
 JSON will have the following structure:
+
 ```
 {
   content: Base64<Vec<u8>>,
@@ -216,8 +243,9 @@ The signature is produced over the hash of the concatenation of: `content`, `aut
 
 ### Create vote
 
-A CLI command to create a signed JSON representation of a vote. The JSON 
+A CLI command to create a signed JSON representation of a vote. The JSON
 will have the following structure:
+
 ```
 {
   proposalHash: Base64<Vec<u8>>,
@@ -230,6 +258,7 @@ will have the following structure:
 The proposalHash is produced over the concatenation of: `content`, `author`, `votingStart`, `votingEnd`, `voter` and `vote`.
 
 ### Tally
+
 Same mechanism as [on chain](#tally) tally but instead of reading the data from storage it will require a list of serialized json votes.
 
 ## Interfaces