diff --git a/documentation/specs/src/SUMMARY.md b/documentation/specs/src/SUMMARY.md index 65e2de1ddf..b7537eb315 100644 --- a/documentation/specs/src/SUMMARY.md +++ b/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) diff --git a/documentation/specs/src/base-ledger.md b/documentation/specs/src/base-ledger.md index b345208e58..a848fa4eac 100644 --- a/documentation/specs/src/base-ledger.md +++ b/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). \ No newline at end of file +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) \ No newline at end of file diff --git a/documentation/specs/src/base-ledger/core-concepts.md b/documentation/specs/src/base-ledger/core-concepts.md new file mode 100644 index 0000000000..083946f0b1 --- /dev/null +++ b/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. diff --git a/documentation/specs/src/base-ledger/execution.md b/documentation/specs/src/base-ledger/execution.md index 3395ffb858..24b5fb992b 100644 --- a/documentation/specs/src/base-ledger/execution.md +++ b/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)) diff --git a/documentation/specs/src/base-ledger/governance.md b/documentation/specs/src/base-ledger/governance.md index 40c7281af9..3079b6e6dc 100644 --- a/documentation/specs/src/base-ledger/governance.md +++ b/documentation/specs/src/base-ledger/governance.md @@ -1,11 +1,23 @@ # 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` @@ -13,6 +25,7 @@ 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,14 +89,16 @@ 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 @@ -89,8 +106,8 @@ Just like Pos, also governance has his own storage space. The `GovernanceAddress - 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,33 +185,39 @@ 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 ``` 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). @@ -200,8 +225,10 @@ It is possible to check the actual implementation [here](https://github.com/anom ## 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>, @@ -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>, @@ -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 diff --git a/documentation/specs/src/economics.md b/documentation/specs/src/economics.md index bf7346b63a..f18c7d7023 100644 --- a/documentation/specs/src/economics.md +++ b/documentation/specs/src/economics.md @@ -1,3 +1,3 @@ ## Economics -Namada's economic model is based around a single native token, NAM, which is controlled by the protocol. Users pay transaction fees in NAM and other tokens (see [fee system](./economics/fee-system.md)), so demand for NAM can be expected to track demand for block space. On the supply side, the protocol mints NAM at a fixed maximum per-annum rate based on a fraction of the current supply (see [inflation system](./economics/inflation-system.md)), which is directed to three areas of protocol subsidy: [proof-of-stake](./economics/proof-of-stake.md), [shielded pool incentives](./economics/shielded-pool-incentives.md), and [public-goods funding](./economics/public-goods-funding.md). Inflation rates for these three areas are adjusted independently (the first two on PD controllers and the third based on funding decisions) and excess tokens are slowly burned. \ No newline at end of file +Namada users pay transaction fees in NAM and other tokens (see [fee system](./economics/fee-system.md) and [governance](./base-ledger/governance.md)), so demand for NAM can be expected to track demand for block space. On the supply side, the protocol mints NAM at a fixed maximum per-annum rate based on a fraction of the current supply (see [inflation system](./economics/inflation-system.md)), which is directed to three areas of protocol subsidy: [proof-of-stake](./economics/proof-of-stake.md), [shielded pool incentives](./economics/shielded-pool-incentives.md), and [public-goods funding](./economics/public-goods-funding.md). Inflation rates for these three areas are adjusted independently (the first two on PD controllers and the third based on funding decisions) and excess tokens are slowly burned. \ No newline at end of file diff --git a/documentation/specs/src/economics/proof-of-stake.md b/documentation/specs/src/economics/proof-of-stake.md index 808f02e585..3102616e65 100644 --- a/documentation/specs/src/economics/proof-of-stake.md +++ b/documentation/specs/src/economics/proof-of-stake.md @@ -4,7 +4,7 @@ This section of the specification describes the proof-of-stake mechanism of Nama This section is split into three subcomponents: the [bonding mechanism](./proof-of-stake/bonding-mechanism.md), [reward distribution](./proof-of-stake/reward-distribution.md), and [cubic slashing](./proof-of-stake/cubic-slashing.md). -## Introduction +## Context Blockchain systems rely on economic security (directly or indirectly) to prevent @@ -13,7 +13,7 @@ for actors to behave according to protocol. The aim is that economic incentives promote correct long-term operation of the system and economic punishments discourage diverging from correct protocol execution either by mistake or -with the intent of carrying out attacks. Many PoS blockcains rely on the 1/3 Byzantine rule, where they make the assumption the adversary cannot control more 2/3 of the total stake or 2/3 of the actors. +with the intent of carrying out attacks. Many PoS blockchains rely on the 1/3 Byzantine rule, where they make the assumption the adversary cannot control more 2/3 of the total stake or 2/3 of the actors. ## Goals of Rewards and Slashing: Liveness and Security diff --git a/documentation/specs/src/economics/proof-of-stake/bonding-mechanism.md b/documentation/specs/src/economics/proof-of-stake/bonding-mechanism.md index ab0449e026..349e766def 100644 --- a/documentation/specs/src/economics/proof-of-stake/bonding-mechanism.md +++ b/documentation/specs/src/economics/proof-of-stake/bonding-mechanism.md @@ -1,9 +1,5 @@ # Bonding mechanism -## Epoch - -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](#epoched-data). - ### Epoched data Epoched data is data associated with a specific epoch that is set in advance. @@ -16,16 +12,11 @@ The data relevant to the PoS system in the ledger's state are epoched. Each data Changes to the epoched data do not take effect immediately. Instead, changes in epoch `n` are queued to take effect in the epoch `n + pipeline_length` for most cases and `n + unboding_length` for [unbonding](#unbond) actions. Should the same validator's data or same bonds (i.e. with the same identity) be updated more than once in the same epoch, the later update overrides the previously queued-up update. For bonds, the token amounts are added up. Once the epoch `n` has ended, the queued-up updates for epoch `n + pipeline_length` are final and the values become immutable. -## Entities - -- [Validator](#validator): An account with a public consensus key, which may participate in producing blocks and governance activities. A validator may not also be a delegator. -- [Delegator](#delegator): An account that delegates some tokens to a validator. A delegator may not also be a validator. - Additionally, any account may submit evidence for [a slashable misbehaviour](#slashing). ### Validator -A validator must have a public consensus key. Additionally, it may also specify optional metadata fields (TBA). +A validator must have a public consensus key. A validator may be in one of the following states: - *inactive*: @@ -115,7 +106,7 @@ Once an offence has been reported: - [cubic slashing](./cubic-slashing.md): escalated slashing -Instead of absolute values, validators' total bonded token amounts and bonds' and unbonds' token amounts are stored as their deltas (i.e. the change of quantity from a previous epoch) to allow distinguishing changes for different epoch, which is essential for determining whether tokens should be slashed. However, because slashes for a fault that occurred in epoch `n` may only be applied before the beginning of epoch `n + unbonding_length`, in epoch `m` we can sum all the deltas of total bonded token amounts and bonds and unbond with the same source and validator for epoch equal or less than `m - unboding_length` into a single total bonded token amount, single bond and single unbond record. This is to keep the total number of total bonded token amounts for a unique validator and bonds and unbonds for a unique pair of source and validator bound to a maximum number (equal to `unbonding_length`). +Instead of absolute values, validators' total bonded token amounts and bonds' and unbonds' token amounts are stored as their deltas (i.e. the change of quantity from a previous epoch) to allow distinguishing changes for different epoch, which is essential for determining whether tokens should be slashed. Slashes for a fault that occurred in epoch `n` may only be applied before the beginning of epoch `n + unbonding_length`. For this reason, in epoch `m` we can sum all the deltas of total bonded token amounts and bonds and unbond with the same source and validator for epoch equal or less than `m - unboding_length` into a single total bonded token amount, single bond and single unbond record. This is to keep the total number of total bonded token amounts for a unique validator and bonds and unbonds for a unique pair of source and validator bound to a maximum number (equal to `unbonding_length`). To disincentivize validators misbehaviour in the PoS system a validator may be slashed for any fault that it has done. An evidence of misbehaviour may be submitted by any account for a fault that occurred in epoch `n` anytime before the beginning of epoch `n + unbonding_length`. @@ -123,6 +114,11 @@ A valid evidence reduces the validator's total bonded token amount by the slash The invariant is that the sum of amounts that may be withdrawn from a misbehaving validator must always add up to the total bonded token amount. +## Initialization + +An initial validator set with self-bonded token amounts must be given on system initialization. + +This set is used to pre-compute epochs in the genesis block from epoch `0` to epoch `pipeline_length - 1`. ## System parameters @@ -296,8 +292,4 @@ struct Slash { } ``` -## Initialization - -An initial validator set with self-bonded token amounts must be given on system initialization. -This set is used to pre-compute epochs in the genesis block from epoch `0` to epoch `pipeline_length - 1`. diff --git a/documentation/specs/src/economics/proof-of-stake/cubic-slashing.md b/documentation/specs/src/economics/proof-of-stake/cubic-slashing.md index 4d4ac07523..d63347308e 100644 --- a/documentation/specs/src/economics/proof-of-stake/cubic-slashing.md +++ b/documentation/specs/src/economics/proof-of-stake/cubic-slashing.md @@ -31,4 +31,16 @@ calculateSlashRate slashes = Validator can later submit a transaction to unjail themselves after a configurable period. When the transaction is applied and accepted, the validator updates its state to "candidate" and is added back to the validator set starting at the epoch at pipeline offset (active or inactive, depending on its voting power). -At present, funds slashed are sent to the governance treasury. In the future we could potentially reward the slash discoverer with part of the slash, for which some sort of commit-reveal mechanism will be required to prevent front-running. +At present, funds slashed are sent to the governance treasury. + +## Slashes + +Slashes should lead to punishment for delegators who were contributing voting power to the validator at the height of the infraction, _as if_ the delegations were iterated over and slashed individually. + +This can be implemented as a negative inflation rate for a particular block. + +Instant redelegation is not supported. Redelegations must wait the unbonding period. + + \ No newline at end of file diff --git a/documentation/specs/src/economics/proof-of-stake/reward-distribution.md b/documentation/specs/src/economics/proof-of-stake/reward-distribution.md index 70f662f97a..730e423e76 100644 --- a/documentation/specs/src/economics/proof-of-stake/reward-distribution.md +++ b/documentation/specs/src/economics/proof-of-stake/reward-distribution.md @@ -152,16 +152,5 @@ The commission rate $c_V(e)$ is the same for all delegations to a validator $V$ While rewards are given out at the end of every epoch, voting power is only updated after the pipeline offset. According to the [proof-of-stake system](bonding-mechanism.md#epoched-data), at the current epoch `e`, the validator sets an only be updated for epoch `e + pipeline_offset`, and it should remain unchanged from epoch `e` to `e + pipeline_offset - 1`. Updating voting power in the current epoch would violate this rule. -## Slashes - -Slashes should lead to punishment for delegators who were contributing voting power to the validator at the height of the infraction, _as if_ the delegations were iterated over and slashed individually. - -This can be implemented as a negative inflation rate for a particular block. - -Instant redelegation is not supported. Redelegations must wait the unbonding period. - - diff --git a/documentation/specs/src/economics/public-goods-funding.md b/documentation/specs/src/economics/public-goods-funding.md index 96e82dfc93..bfb779b1fa 100644 --- a/documentation/specs/src/economics/public-goods-funding.md +++ b/documentation/specs/src/economics/public-goods-funding.md @@ -10,7 +10,7 @@ There is a lot of existing research into public-goods funding to which justice c Namada instantiates a dual proactive/retroactive public-goods funding model, stewarded by a public-goods council elected by limited liquid democracy. -This proposal requires the following protocol components: +This requires the following protocol components: - Limited liquid democracy / targeted delegation: Namada's current voting mechanism is altered to add targeted delegation. By default, each delegator delegates their vote in governance to their validator, but they can set an alternative governance delegate who can instead vote on their behalf (but whose vote can be overridden as usual). Validators can also set governance delegates, in which case those delegates can vote on their behalf, and on the behalf of all delegators to that validator who do not override the vote, unless the validator overrides the vote. This is a limited form of liquid democracy which could be extended in the future. - Funding council: bi-annually (every six months), Namada governance elects a public goods funding council by stake-weighted approval vote (see below). Public goods funding councils run as groups. The public goods funding council decides according to internal decision-making procedures (practically probably limited to a k-of-n multisignature) how to allocate continuous funding and retroactive funding during their term. Namada genesis includes an initial funding council, and the next election will occur six months after launch. - Continuous funding: Namada prints an amount of inflation fixed on a percentage basis dedicated to continuous funding. Each quarter, the public goods funding council selects recipients and amounts (which in total must receive all of the funds, although they could burn some) and submits this list to the protocol. Inflation is distributed continuously by the protocol to these recipients during that quarter. diff --git a/documentation/specs/src/further-reading.md b/documentation/specs/src/further-reading.md index 971007c530..d92add791f 100644 --- a/documentation/specs/src/further-reading.md +++ b/documentation/specs/src/further-reading.md @@ -1,3 +1,15 @@ ## Further reading -Thanks for reading! You can find further information about the state of Namada at [namada.net](https://namada.net). \ No newline at end of file +Thanks for reading! You can find further information about the project below: + +[The state of Namada](https://namada.net). +[The state of Anoma](https://anoma.net/) +[Anoma source code](https://github.com/anoma/anoma) +[Namada source code](https://github.com/anoma/namada) +[Anoma Community](https://anoma.net/community) +[Heliax](https://heliax.dev/) +[Anoma Medium page](https://medium.com/anomanetwork) +[Namada Docs](https://docs.namada.net/) +[Anoma Discord](https://discord.com/invite/anoma) +[Namada Twitter](https://twitter.com/namadanetwork) +[Anoma Twitter](https://twitter.com/anomanetwork) \ No newline at end of file diff --git a/documentation/specs/src/interoperability/ethereum-bridge.md b/documentation/specs/src/interoperability/ethereum-bridge.md index cfc5ce6841..c6d52e3447 100644 --- a/documentation/specs/src/interoperability/ethereum-bridge.md +++ b/documentation/specs/src/interoperability/ethereum-bridge.md @@ -320,7 +320,7 @@ struct MintWrappedNam { ``` If a user wishes to mint a wrapped Namada token on Ethereum, they must submit a transaction on Namada that: -- stores `MintWrappedNam` on chain somewhere - TBD +- stores `MintWrappedNam` on chain somewhere - sends the correct amount of Namada token to `#EthBridgeEscrow` Just as in redeeming Ethereum assets above, it is incumbent on the end user to @@ -385,7 +385,7 @@ appropriate state change, emit logs, etc. ## Starting the bridge Before the bridge can start running, some storage may need to be initialized in -Namada. TBD. +Namada. ## Resources which may be helpful: - [Gravity Bridge Solidity contracts](https://github.com/Gravity-Bridge/Gravity-Bridge/tree/main/solidity) @@ -393,5 +393,3 @@ Namada. TBD. - [Rainbow Bridge contracts](https://github.com/aurora-is-near/rainbow-bridge/tree/master/contracts) - [IBC in Solidity](https://github.com/hyperledger-labs/yui-ibc-solidity) -Operational notes: -1. We will bundle the Ethereum full node with the `namada` daemon executable. diff --git a/documentation/specs/src/interoperability/ibc.md b/documentation/specs/src/interoperability/ibc.md index 198266dd93..0848243d33 100644 --- a/documentation/specs/src/interoperability/ibc.md +++ b/documentation/specs/src/interoperability/ibc.md @@ -6,29 +6,27 @@ ## IBC transaction An IBC transaction [`tx_ibc.wasm`](https://github.com/anoma/anoma/blob/fd4b7ab36929f47369ae82c82966891cb0ccc625/wasm/wasm_source/src/lib.rs#L224-L233) is provided. We have to set an IBC message to the transaction data corresponding to execute an IBC operation. -The transaction decodes the data to an IBC message and handles IBC-related data, e.g. it makes a new connection ID and writes a new connection end for `MsgConnectionOpenTry`. The operations are implemented in [`IbcActions`](https://docs.anoma.network/master/rustdoc/anoma/ledger/ibc/handler/trait.IbcActions.html).The transaction doesn't check the validity for the state changes. IBC validity predicate is in charge of the validity. +The transaction decodes the data to an IBC message and handles IBC-related data, e.g. it makes a new connection ID and writes a new connection end for `MsgConnectionOpenTry`. The operations are implemented in [`IbcActions`](https://github.com/anoma/anoma/blob/50b5e77f04a9afc036656353335bd232fcdba8a7/vm_env/src/ibc.rs).The transaction doesn't check the validity for the state changes. IBC validity predicate is in charge of the validity. ## IBC validity predicate -[IBC validity predicate](https://docs.anoma.network/master/rustdoc/anoma/ledger/ibc/vp/struct.Ibc.html#impl-NativeVp) checks if an IBC-related transaction satisfies IBC protocol. When an IBC-related transaction is executed, i.e. a transaction changes the state of the key that contains [`InternalAddress::Ibc`](https://docs.anoma.network/master/rustdoc/anoma/types/address/enum.InternalAddress.html#variant.Ibc), IBC validity predicate (one of the native validity predicates) is executed. For example, if an IBC connection end is created in the transaction, IBC validity predicate validates the creation. If the creation with `MsgConnectionOpenTry` is invalid, e.g. the counterpart connection end doesn't exist, the validity predicate makes the transaction fail. +[IBC validity predicate](https://docs.anoma.network/master/rustdoc/anoma/ledger/ibc/vp/struct.Ibc.html#impl-NativeVp) checks if an IBC-related transaction satisfies IBC protocol. When an IBC-related transaction is executed, i.e. a transaction changes the state of the key that contains [`InternalAddress::Ibc`](https://github.com/anoma/anoma/blob/50b5e77f04a9afc036656353335bd232fcdba8a7/shared/src/types/address.rs), IBC validity predicate (one of the native validity predicates) is executed. For example, if an IBC connection end is created in the transaction, IBC validity predicate validates the creation. If the creation with `MsgConnectionOpenTry` is invalid, e.g. the counterpart connection end doesn't exist, the validity predicate makes the transaction fail. ## Fungible Token Transfer The transfer of fungible tokens over an IBC channel on separate chains is defined in [ICS20](https://github.com/cosmos/ibc/blob/master/spec/app/ics-020-fungible-token-transfer/README.md). -In Anoma, the sending tokens is triggered by a transaction having [MsgTransfer](https://github.com/informalsystems/ibc-rs/blob/0a952b295dbcf67bcabb79ce57ce92c9c8d7e5c6/modules/src/applications/ics20_fungible_token_transfer/msgs/transfer.rs#L20-L37) as transaction data. A packet including [`FungibleTokenPacketData`](https://docs.anoma.network/master/rustdoc/anoma/types/ibc/data/struct.FungibleTokenPacketData.html) is made from the message in the transaction execution. +In Anoma, the sending tokens is triggered by a transaction having [MsgTransfer](https://github.com/informalsystems/ibc-rs/blob/0a952b295dbcf67bcabb79ce57ce92c9c8d7e5c6/modules/src/applications/ics20_fungible_token_transfer/msgs/transfer.rs#L20-L37) as transaction data. A packet including [`FungibleTokenPacketData`](https://github.com/anoma/anoma/blob/50b5e77f04a9afc036656353335bd232fcdba8a7/shared/src/types/ibc/data.rs) is made from the message in the transaction execution. Anoma chain receives the tokens by a transaction having [MsgRecvPacket](https://github.com/informalsystems/ibc-rs/blob/0a952b295dbcf67bcabb79ce57ce92c9c8d7e5c6/modules/src/core/ics04_channel/msgs/recv_packet.rs#L19-L23) which has the packet including `FungibleTokenPacketData`. The sending and receiving tokens in a transaction are validated by not only -IBC validity predicate but also [IBC token validity predicate](https://docs. -anoma.network/master/rustdoc/anoma/ledger/ibc/vp/struct.IbcToken. -html#impl-NativeVp). IBC validity predicate validates if sending and receiving the packet is proper. IBC token validity predicate is also one of the native validity predicates and checks if the token transfer is valid. If the transfer is not valid, e.g. an unexpected amount is minted, the validity predicate makes the transaction fail. +IBC validity predicate but also [IBC token validity predicate](https://github.com/anoma/anoma/blob/50b5e77f04a9afc036656353335bd232fcdba8a7/shared/src/ledger/ibc/vp/token.rs). IBC validity predicate validates if sending and receiving the packet is proper. IBC token validity predicate is also one of the native validity predicates and checks if the token transfer is valid. If the transfer is not valid, e.g. an unexpected amount is minted, the validity predicate makes the transaction fail. A transaction escrowing/unescrowing a token changes the escrow account's balance of the token. The key is `{token_addr}/balance/{escrow_addr}`. A transaction burning a token changes the burn account's balance of the token. The key is `{token_addr}/balance/BURN_ADDR`. A transaction minting a token changes the mint account's balance of the token. The key is `{token_addr} -/balance/MINT_ADDR`. `{escrow_addr}`, `{BURN_ADDR}`, and `{MINT_ADDR}` are addresses of [`InternalAddress`](https://docs.anoma.network/master/rustdoc/anoma/types/address/enum.InternalAddress.html). When these addresses are included in the changed keys after transaction execution, IBC token validity predicate is executed. +/balance/MINT_ADDR`. `{escrow_addr}`, `{BURN_ADDR}`, and `{MINT_ADDR}` are addresses of [`InternalAddress`](https://github.com/anoma/anoma/blob/50b5e77f04a9afc036656353335bd232fcdba8a7/shared/src/types/address.rs). When these addresses are included in the changed keys after transaction execution, IBC token validity predicate is executed. ## IBC message diff --git a/documentation/specs/src/introduction.md b/documentation/specs/src/introduction.md index 6f4971e049..0d4f83fd33 100644 --- a/documentation/specs/src/introduction.md +++ b/documentation/specs/src/introduction.md @@ -2,31 +2,28 @@ Welcome to the Namada specifications! +## What is Namada? + Namada is a sovereign proof-of-stake blockchain, using Tendermint BFT consensus, that enables multi-asset private transfers for any native or non-native asset -using a multi-asset shielded pool derived from the Sapling circuit. Namada features -full IBC protocol support, a natively integrated Ethereum bridge, a modern proof-of-stake -system with automatic reward compounding and cubic slashing, a stake-weighted governance -signalling mechanism, and a proactive/retroactive public goods funding system. -Users of shielded transfers are rewarded for their contributions -to the privacy set in the form of native protocol tokens. A multi-asset shielded transfer wallet -is provided in order to facilitate safe and private user interaction with the protocol. +using a [multi-asset shielded pool](https://research.metastate.dev/multi-asset_shielded_pool/) derived from the [Sapling circuit](https://z.cash/upgrade/sapling/). Namada features full IBC protocol support, a natively integrated Ethereum bridge, a modern proof-of-stakesystem with automatic reward compounding and cubic slashing, a stake-weighted governance signalling mechanism, and a proactive/retroactive public goods funding system. Users of shielded transfers are rewarded for their contributions to the privacy set in the form of native protocol tokens. A multi-asset shielded transfer wallet is provided in order to facilitate safe and private user interaction with the protocol. + +You can learn more about Namada [here](https://medium.com/anomanetwork/introducing-namada-shielded-transfers-with-any-assets-dce2e579384c). +### What is Anoma? -### How does Namada relate to Anoma? +The Anoma protocol is designed to facilitate the operation of networked fractal instances, which intercommunicate but can utilise varied state machines and security models. +A fractal instance is an instance of the Anoma consensus and execution protocols operated by a set of networked validators. Anoma’s fractal instance architecture is an attempt to build a platform which is architecturally homogeneous and with a heterogeneous security model. Thus, different fractal instances may specialise in different tasks and serve different communities. Privacy should be default and inherent in the systems we use for transacting. -Namada is the first fractal instance launched as part of the Anoma ecosystem. +### How does Namada relate to Anoma? -The Anoma protocol is designed to facilitate the operation of networked fractal instances, -which intercommunicate but can utilise varied state machines and security models. Different -fractal instances may specialise in different tasks and serve different communities. The Namada -instance will be the first such fractal instance, and it will be focused exclusively on the use-case of private asset transfers. +The Namada instance will be the first such fractal instance, and it will be focused exclusively on the use-case of private asset transfers. Namada is a helpful stepping stone to finalise, test, and launch a protocol version that is simpler than the full +Anoma protocol but still encapsulates a unified and useful set of features. ### Raison d'être -Safe and user-friendly multi-asset privacy doesn't yet exist in the blockchain ecosystem. -Up until now users have had the choice of either a sovereign chain that reissues assets (e.g. Zcash) -or a privacy preserving solution built on an existing smart contract chain (e.g. Tornado Cash on -Ethereum). Both have large trade-offs: in the former case, users don't have +Privacy should be default and inherent in the systems we use for transacting. Yet safe and user-friendly multi-asset privacy doesn't yet exist in the blockchain ecosystem. +Up until now users have had the choice of either a sovereign chain that reissues assets (e.g. [Zcash](https://z.cash/)) +or a privacy preserving solution built on an existing smart contract chain. Both have large trade-offs: in the former case, users don't have assets that they actually want to transact with, and in the latter case, the restrictions of existing platforms mean that users leak a ton of metadata and the protocols are expensive and clunky to use. @@ -36,15 +33,7 @@ and fungible or non-fungible assets (such as ERC20 tokens) sent over a custom Et reduces transfer costs and streamlines UX as much as possible. Once assets are on Namada, shielded transfers are cheap and all assets contribute to the same anonymity set. -Namada is also a helpful stepping stone to finalise, test, -and launch a protocol version that is simpler than the full -Anoma protocol but still encapsulates a unified and useful -set of features. There are reasons to expect that it may -make sense for a fractal instance focused exclusively on -shielded transfers to exist in the long-term, as it can -provide throughput and user-friendliness guarantees which -are more difficult to provide with a more general platform. -Namada is designed to be such an instance. +Users on Namada can earn rewards, retain privacy of assets, and contribute to the overall privacy set. ### Layout of this specification diff --git a/documentation/specs/src/masp.md b/documentation/specs/src/masp.md index 4e1fadc087..d1a87e9b8b 100644 --- a/documentation/specs/src/masp.md +++ b/documentation/specs/src/masp.md @@ -7,4 +7,5 @@ See the following documents: - [Ledger integration](./masp/ledger-integration.md) - [Asset type schema](./masp/asset-type.md) - [Burn and mint](./masp/burn-and-mint.md) -- [Convert circuit](./masp/convert-circuit.md) \ No newline at end of file +- [Convert circuit](./masp/convert-circuit.md) +- [Shielded pool incentives](./economics/shielded-pool-incentives.md) \ No newline at end of file diff --git a/documentation/specs/src/masp/asset-type.md b/documentation/specs/src/masp/asset-type.md index 7504c7ef0f..bc6c701698 100644 --- a/documentation/specs/src/masp/asset-type.md +++ b/documentation/specs/src/masp/asset-type.md @@ -2,22 +2,22 @@ MASP notes carry balances that are some positive integer amount of an asset type. Per both the MASP specification and the implementation, the -asset *identifier* is an 32-byte Blake2s hash of an arbitrary asset +asset *identifier* is an 32-byte [Blake2s hash](https://www.blake2.net/) of an arbitrary asset *name* string, although the full 32-byte space is not used because the identifier must itself hash to an elliptic curve point (currently guaranteed by incrementing a nonce until the hash is a curve point). The final curve point is the asset *type* proper, used in computations. The following is a schema for the arbitrary asset name string intended -to support various uses; at least fungible tokens and NFTs, but possibly -others. +to support various uses - currently fungible tokens and NFTs, but possibly +others in future. The asset name string is built up from a number of segments, joined by a separator. We use `/` as the separator. Segments may be one of the following: -- **Controlling address** segment: an Anoma address which controls the +- **Controlling address** segment: a Namada address which controls the asset. For example, this is the fungible token address for a fungible token. This segment must be present, and must be first; it should in theory be an error to transparently transact in assets of this type diff --git a/documentation/specs/src/masp/burn-and-mint.md b/documentation/specs/src/masp/burn-and-mint.md index f66b8e28eb..2c9bb6e3b5 100644 --- a/documentation/specs/src/masp/burn-and-mint.md +++ b/documentation/specs/src/masp/burn-and-mint.md @@ -62,7 +62,7 @@ It is also critical not to allow cycles. For example, if $\{(A_1, -1), (A_2, 2)\ It may theoretically be possible to implement similar mechanisms with only the existing Spend and Output circuits. For example, a Merkle tree of many Notes could be created with asset generator $[-1] vb_1 + vb_2$ and many different values, allowing anyone to Spend these public Notes, which will only balance if proper amounts of asset type 1 are Spent and asset type 2 are Output. -However, the Nullifier integrity check of the Spend circuit reveals the nullifier of each of these Notes, which removes the privacy of the conversion as the public nullifier is linkable to the allowed conversion. In addition, each Note has a fixed value, preventing arbitrary value conversions. +However, the Nullifier integrity check of the Spend circuit reveals the nullifier of each of these Notes. This removes the privacy of the conversion as the public nullifier is linkable to the allowed conversion. In addition, each Note has a fixed value, preventing arbitrary value conversions. ## Conclusion diff --git a/documentation/specs/src/masp/ledger-integration.md b/documentation/specs/src/masp/ledger-integration.md index 0eed1d7d80..0f4f0cabd8 100644 --- a/documentation/specs/src/masp/ledger-integration.md +++ b/documentation/specs/src/masp/ledger-integration.md @@ -4,32 +4,31 @@ The overall aim of this integration is to have the ability to provide a multi-asset shielded pool following the MASP spec as an account on the -current Anoma blockchain implementation. +current Namada blockchain implementation. -## Shielded pool VP +## Shielded pool validity predicate (VP) -The shielded value pool can be an Anoma "established account" with a +The shielded value pool can be an Namada established account with a validity predicate which handles the verification of shielded transactions. Similarly to zcash, the asset balance of the shielded pool itself is transparent - that is, from the transparent perspective, the MASP is just an account holding assets. The shielded pool VP has the following functions: -- Accept only valid transactions involving assets moving in or out of +- Accepts only valid transactions involving assets moving in or out of the pool. -- Accept valid shielded-to-shielded transactions, which don't move - assets from the perspective of transparent Anoma. -- Publish the note commitment and nullifier reveal Merkle trees. +- Accepts valid shielded-to-shielded transactions, which don't move + assets from the perspective of transparent Namada. +- Publishes the note commitment and nullifier reveal Merkle trees. To make this possible, the host environment needs to provide verification primitives to VPs. One possibility is to provide a single -high-level "verify transaction output descriptions and proofs" -operation, but another is to provide cryptographic functions in the host +high-level operation to verify transaction output descriptions and proofs, but another is to provide cryptographic functions in the host environment and implement the verifier as part of the VP. -The shielded pool needs the ability to update the commitment and -nullifier Merkle trees as it receives transactions. This may possibly be -achievable via the temporary storage mechanism added for IBC, with the +In future, the shielded pool will be able to update the commitment and +nullifier Merkle trees as it receives transactions. This could likely be +achieved via the temporary storage mechanism added for IBC, with the trees finalized with each block. The input to the VP is the following set of state changes: @@ -37,7 +36,7 @@ The input to the VP is the following set of state changes: - updates to the shielded pool's asset balances - new encrypted notes - updated note and nullifier tree states (partial, because we only have - the last block's anchor?) + the last block's anchor) and the following data which is ancillary from the ledger's perspective: @@ -71,7 +70,7 @@ struct OutputDescription { c_enc: [u8; ENC_CIPHERTEXT_SIZE], // Encrypted note key recovery ciphertext c_out: [u8; OUT_CIPHERTEXT_SIZE], - // Zero-knowledge proof of the new encrypted note's location (?) + // Zero-knowledge proof of the new encrypted note's location zkproof: Proof, } ``` @@ -79,7 +78,7 @@ struct OutputDescription { Given these inputs: The VP must verify the proofs for all spend and output descriptions -(`bellman::groth16`), as well as the signature for spend notes. +([`bellman::groth16`](https://docs.rs/bellman/latest/bellman/groth16/index.html)), as well as the signature for spend notes. Encrypted notes from output descriptions must be published in the storage so that holders of the viewing key can view them; however, the @@ -89,15 +88,14 @@ Nullifiers and commitments must be appended to their respective Merkle trees in the VP's storage as well, which is a transaction-level rather than a block-level state update. -Additionally to the individual spend and output description +In addition to the individual spend and output description verifications, the final transparent asset value change described in the -transaction must equal the pool asset value change, and as an additional -sanity check, the pool's balance of any asset may not end up negative -(this may already be impossible?). (needs more input) +transaction must equal the pool asset value change. As an additional +sanity check, the pool's balance of any asset may not end up negative. NB: Shielded-to-shielded transactions in an asset do not, from the ledger's perspective, transact in that asset; therefore, the asset's own -VP is not run as described above, and cannot be because the shielded +VP cannot run as described above because the shielded pool is asset-hiding. ## Client capabilities @@ -116,7 +114,7 @@ if any, and proof data computed offline by the client. The client and wallet must be extended to support the shielded pool and the cryptographic operations needed to interact with it. From the -perspective of the transparent Anoma protocol, a shielded transaction is +perspective of the transparent Namada protocol, a shielded transaction is just a data write to the MASP storage, unless it moves value in or out of the pool. The client needs the capability to create notes, transactions, and proofs of transactions, but it has the advantage of @@ -148,7 +146,7 @@ For cryptographic details and further information, see Note that this structure is required only by the client; the VP only handles commitments to this data. -Diversifiers are selected (randomly?) by the client and used to +Diversifiers are selected by the client and used to diversify addresses and their associated keys. `v` and `t` identify the asset type and value. Asset identifiers are derived from asset names, which are arbitrary strings (in this case, token/other asset VP @@ -217,7 +215,7 @@ struct TxOut { ``` Note that in contrast to Sapling's UTXO based approach, our transparent inputs/outputs are based on the account model used -in the rest of Anoma. +in the rest of Namada. # Shielded Transfer Specification ## Transfer Format @@ -242,17 +240,17 @@ pub struct Transfer { ``` ## Conditions Below, the conditions necessary for a valid shielded or unshielded transfer are outlined: -* A shielded component equal to `None` indicates a transparent Anoma transaction -* Otherwise the shielded component must have the form `Some(x)` where `x` has the transaction encoding specified in the [Multi-Asset Shielded Pool Specication](https://raw.githubusercontent.com/anoma/masp/main/docs/multi-asset-shielded-pool.pdf) +* A shielded component equal to `None` indicates a transparent Namada transaction +* Otherwise the shielded component must have the form `Some(x)` where `x` has the transaction encoding specified in the [Multi-Asset Shielded Pool Specs]() * Hence for a shielded transaction to be valid: - * the `Transfer` must satisfy the usual conditions for Anoma ledger transfers (i.e. sufficient funds, ...) as enforced by token and account validity predicates - * the `Transaction` must satisfy the conditions specified in the [Multi-Asset Shielded Pool Specication](https://raw.githubusercontent.com/anoma/masp/main/docs/multi-asset-shielded-pool.pdf) - * the `Transaction` and `Transfer` together must additionaly satisfy the below boundary conditions intended to ensure consistency between the MASP validity predicate ledger and Anoma ledger + * the `Transfer` must satisfy the usual conditions for Namada ledger transfers (i.e. sufficient funds, ...) as enforced by token and account validity predicates + * the `Transaction` must satisfy the conditions specified in the [Multi-Asset Shielded Pool Specification](https://github.com/anoma/masp/blob/main/docs/multi-asset-shielded-pool.pdf) + * the `Transaction` and `Transfer` together must additionally satisfy the below boundary conditions intended to ensure consistency between the MASP validity predicate ledger and Namada ledger * A key equal to `None` indicates an unpinned shielded transaction; one that can only be found by scanning and trial-decrypting the entire shielded pool * Otherwise the key must have the form `Some(x)` where `x` is a `String` such that there exists no prior accepted transaction with the same key ### Boundary Conditions -Below, the conditions necessary to maintain consistency between the MASP validity predicate ledger and Anoma ledger are outlined: +Below, the conditions necessary to maintain consistency between the MASP validity predicate ledger and Namada ledger are outlined: * If the target address is the MASP validity predicate, then no transparent outputs are permitted in the shielded transaction * If the target address is not the MASP validity predicate, then: * there must be exactly one transparent output in the shielded transaction and: @@ -287,7 +285,7 @@ Below are miscellaneous remarks on the capabilities and limitations of the curre * This key must not be reused, this is in order to avoid revealing that multiple transactions are going to the same entity ## Multi-Asset Shielded Pool Specification Differences from Zcash Protocol Specification -The [Multi-Asset Shielded Pool Specication](https://media.githubusercontent.com/media/anoma/masp/main/docs/multi-asset-shielded-pool.pdf) referenced above is in turn an extension to the [Zcash Protocol Specification](https://zips.z.cash/protocol/protocol.pdf). Below, the changes from the Zcash Protocol Specification assumed to have been integrated into the Multi-Asset Shielded Pool Specification are listed: +The [Multi-Asset Shielded Pool Specification](https://github.com/anoma/masp/blob/main/docs/multi-asset-shielded-pool.pdf) referenced above is in turn an extension to the [Zcash Protocol Specification](https://zips.z.cash/protocol/protocol.pdf). Below, the changes from the Zcash Protocol Specification assumed to have been integrated into the Multi-Asset Shielded Pool Specification are listed: * [3.2 Notes](https://zips.z.cash/protocol/protocol.pdf#notes) * Sapling note tuple must include asset type * Note commitment must be parameterized by asset type @@ -391,7 +389,7 @@ Below, the changes from [ZIP 32: Shielded Hierarchical Deterministic Wallets](ht * For extended full viewing keys on the Testnet, the Human-Readable Part is "xfvktest" # Storage Interface Specification -Anoma nodes provide interfaces that allow Anoma clients to query for specific pinned transactions, transactions accepted into the shielded pool, and allowed conversions between various asset types. Below we describe the ABCI paths and the encodings of the responses to each type of query. +Namada nodes provide interfaces that allow Namada clients to query for specific pinned transactions, transactions accepted into the shielded pool, and allowed conversions between various asset types. Below we describe the ABCI paths and the encodings of the responses to each type of query. ## Shielded Transfer Query In order to determine shielded balances belonging to particular keys or spend one's balance, it is necessary to download the transactions that transferred the assets to you. To this end, the nth transaction in the shielded pool can be obtained by getting the value at the storage path `/tx-`. Note that indexing is 0-based. This will return a quadruple of the type below: @@ -414,7 +412,7 @@ When scanning the shielded pool, it is sometimes useful know when to stop scanni ## Pinned Transfer Query A transaction pinned to the key `x` in the shielded pool can be obtained indirectly by getting the value at the storage path `/pin-`. This will return the index of the desired transaction within the shielded pool encoded as a `u64`. At this point, the above shielded transaction query can then be used to obtain the actual transaction bytes. ## Conversion Query -In order for MASP clients to convert older asset types to their latest variants, they need to query nodes for currently valid conversions. This can be done by querying the ABCI path `conv/` where `asset-type` is a hexadecimal encoding of the asset identifier as defined in [Multi-Asset Shielded Pool Specication](https://media.githubusercontent.com/media/anoma/masp/main/docs/multi-asset-shielded-pool.pdf). This will return a quadruple of the type below: +In order for MASP clients to convert older asset types to their latest variants, they need to query nodes for currently valid conversions. This can be done by querying the ABCI path `conv/` where `asset-type` is a hexadecimal encoding of the asset identifier as defined in [Multi-Asset Shielded Pool Specification](https://github.com/anoma/masp/blob/main/docs/multi-asset-shielded-pool.pdf). This will return a quadruple of the type below: ``` ( /// the token address of this asset type @@ -427,4 +425,4 @@ In order for MASP clients to convert older asset types to their latest variants, MerklePath ) ``` -If no conversions are available the amount will be exactly zero, otherwise the amount must contain negative units of the queried asset type. +If no conversions are available, the amount will be exactly zero, otherwise the amount must contain negative units of the queried asset type. diff --git a/documentation/specs/src/masp/trusted-setup.md b/documentation/specs/src/masp/trusted-setup.md index acc14f723d..328a7fe231 100644 --- a/documentation/specs/src/masp/trusted-setup.md +++ b/documentation/specs/src/masp/trusted-setup.md @@ -1,8 +1,7 @@ # Namada Trusted Setup This spec assumes that you have some previous knowledge about Trusted Setup Ceremonies. If not, you might want to check the following two articles: [Setup Ceremonies - ZKProof](https://zkproof.org/2021/06/30/setup-ceremonies/) and [Parameter Generation - Zcash](https://z.cash/technology/paramgen/). -The Namada Trusted Setup (TS) consists of running the phase 2 of the MPC which is a circuit-specific step to construct the multi-asset shielded pool circuit. Our phase 2 takes as input the Powers of Tau (phase 1) ran by Zcash that can be found [here](https://download.z.cash/downloads/powersoftau/). - +The Namada Trusted Setup (TS) consists of running the phase 2 of the MPC which is a circuit-specific step to construct the multi-asset shielded pool circuit. Our phase 2 takes as input the Powers of Tau (phase 1) ran by Zcash that can be found [here](https://download.z.cash/downloads/powersoftau/). You can sign up for the Namada Trusted Setup [here](https://namada.net/trusted-setup.html). ## Contribution flow diff --git a/documentation/specs/src/user-interfaces/external-integrations.md b/documentation/specs/src/user-interfaces/external-integrations.md index f6fd4855b6..c459d52499 100644 --- a/documentation/specs/src/user-interfaces/external-integrations.md +++ b/documentation/specs/src/user-interfaces/external-integrations.md @@ -10,7 +10,7 @@ * Rosetta integration * Datahub integration * WalletConnect integration -* Ledger integration +* [Ledger integration](../masp/ledger-integration.md) * External integrations * Figment * P2P diff --git a/documentation/specs/src/user-interfaces/web-explorer-interface.md b/documentation/specs/src/user-interfaces/web-explorer-interface.md index 9c6225d674..c7dbfa3c80 100644 --- a/documentation/specs/src/user-interfaces/web-explorer-interface.md +++ b/documentation/specs/src/user-interfaces/web-explorer-interface.md @@ -1,9 +1,9 @@ # Web explorer interface * Block explorer - * Display PoS state - * Display governance state - * Display transparent transfers - * Display transfers in and out of the MASP - * Display total values for the MASP + * Displays PoS state + * Displays governance state + * Displays transparent transfers + * Displays transfers in and out of the MASP + * Displays total values for the MASP * Allows tx hashes of shielded transfers to be looked up for confirmation diff --git a/documentation/specs/src/user-interfaces/web-wallet-interface.md b/documentation/specs/src/user-interfaces/web-wallet-interface.md index 615a74178f..d34628ef6a 100644 --- a/documentation/specs/src/user-interfaces/web-wallet-interface.md +++ b/documentation/specs/src/user-interfaces/web-wallet-interface.md @@ -2,7 +2,7 @@ ## Application Features -The application consist of the an UI that allows the user to perform the following actions in an easy to use and consistent web application: +The application consists of a UI that allows the user to perform the following actions in an easy to use and consistent web application: ### Seed Phrase [hifi Designs](https://www.figma.com/file/aiWZpaXjPLW6fDjE7dpFaU/Projects-2021?node-id=4610%3A5890) @@ -16,9 +16,9 @@ The application consist of the an UI that allows the user to perform the followi * When entering the app, the user is being prompted for a password to decrypt the key pair to be able to perform actions [wireframe](https://www.figma.com/file/aiWZpaXjPLW6fDjE7dpFaU/Projects-2021?node-id=6442%3A5801) * Can create accounts derived from the master key pair * Can delete accounts -* User can integrated with Ledger hardware wallet - * Set up flow TBD - * Managing TBD +* User can integrate with Ledger hardware wallet + * Set up + * Management * Can see an overview of the assets in the account and all derived accounts [wireframe](https://www.figma.com/file/aiWZpaXjPLW6fDjE7dpFaU/Projects-2021?node-id=6442%3A5492) * Can see the details of a single asset, containing the following information [wireframe](https://www.figma.com/file/aiWZpaXjPLW6fDjE7dpFaU/Projects-2021?node-id=6442%3A5681) * Balance @@ -26,7 +26,6 @@ The application consist of the an UI that allows the user to perform the followi * Button to initiate a new transfer using this asset ### Transfers -[TBD]() * Can create transparent transfers * Can create shielded transfers * Bi-directional transfer between Namada and ETH @@ -35,7 +34,6 @@ The application consist of the an UI that allows the user to perform the followi * Supports approving transactions with Keplr ### Staking & Governance -[TBD]() * Can bond funds to a list of validators * Can un-bond funds to a list of validators * Can submit proposals diff --git a/documentation/specs/src/user-interfaces/web-wallet.md b/documentation/specs/src/user-interfaces/web-wallet.md index 370a0a5397..2196400f2f 100644 --- a/documentation/specs/src/user-interfaces/web-wallet.md +++ b/documentation/specs/src/user-interfaces/web-wallet.md @@ -142,7 +142,7 @@ User can: [Wireframe 2](https://www.figma.com/file/aiWZpaXjPLW6fDjE7dpFaU/Projects-2021?node-id=6496%3A14405) User can: view 1: -* enter the details (TBD) of the proposal +* enter the details of the proposal * see a summary of the proposal * submit the proposal