From ac18892be4dadb1a1f80a508afd6d425831e9cdb Mon Sep 17 00:00:00 2001 From: bengtlofgren Date: Thu, 22 Feb 2024 14:28:31 +0000 Subject: [PATCH 01/94] sdk improvements incoming --- .../pages/integrating-with-namada/sdk.mdx | 41 ++++++++----------- .../sdk/constructing-transfers.mdx | 8 ++-- .../sdk/generating-accounts.mdx | 10 ++--- .../sdk/setting-up-a-wallet.mdx | 25 ++++++----- 4 files changed, 40 insertions(+), 44 deletions(-) diff --git a/packages/docs/pages/integrating-with-namada/sdk.mdx b/packages/docs/pages/integrating-with-namada/sdk.mdx index c19a5f70..c3d60915 100644 --- a/packages/docs/pages/integrating-with-namada/sdk.mdx +++ b/packages/docs/pages/integrating-with-namada/sdk.mdx @@ -6,7 +6,7 @@ The Namada software development kit (SDK) can be found in the `namada` repo unde ## Quick Start -A good starting point to see the SDK in use is to check-out the [namada interface](https://github.com/anoma/namada-interface/tree/main/packages/shared/lib/src/sdk) repo. This repo contains a simple web application that uses the SDK to interact with the Namada blockchain. However, it is important to note the added complexity arising from the application integrating javascript using [wasm-bindgen](https://rustwasm.github.io/docs/wasm-bindgen/), which is not necessary. +A good starting point to see the SDK in use is to check-out the [namada interface](https://github.com/anoma/namada/tree/main/crates/sdk) repo. This repo contains a simple web application that uses the SDK to interact with the Namada blockchain. However, it is important to note the added complexity arising from the application integrating javascript using [wasm-bindgen](https://rustwasm.github.io/docs/wasm-bindgen/), which is not necessary. ## Installation @@ -17,38 +17,31 @@ The Namada SDK can be installed by creating a new Rust project and adding the fo ```toml [package] -name = "namada-sdk-starter" +name = "namada-sdk-example" version = "0.1.0" edition = "2021" # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html [dependencies] -async-std = "1.11.0" -async-trait = "0.1.51" -borsh = "0.9.0" -file-lock = "2.0.2" -futures = "0.3.28" -getrandom = { version = "0.2" } -masp_primitives = { git = "https://github.com/anoma/masp.git", rev = "50acc5028fbcd52a05970fe7991c7850ab04358e" } -masp_proofs = { git = "https://github.com/anoma/masp.git", rev = "50acc5028fbcd52a05970fe7991c7850ab04358e", features = ["download-params"]} -# Make sure the rev is to the latest version of namada in the below repo -namada_sdk = { git = "https://github.com/anoma/namada.git", rev = "v0.24.0", default-features = false, features = ["abciplus", "namada-sdk", "std"] } +clap = { version = "4.4.2", features = ["derive", "env"] } rand = {version = "0.8", default-features = false} rand_core = {version = "0.6", default-features = false} -tendermint-config = {git="https://github.com/heliaxdev/tendermint-rs.git", rev="b7d1e5afc6f2ccb3fd1545c2174bab1cc48d7fa7"} -tendermint-rpc = {git="https://github.com/heliaxdev/tendermint-rs.git", rev="b7d1e5afc6f2ccb3fd1545c2174bab1cc48d7fa7", features = ["http-client"]} -thiserror = "1.0.38" +serde = { version = "1.0.188", features = ["derive"] } +serde_json = "1.0.107" +namada_sdk = { git = "https://github.com/anoma/namada", rev = "v0.31.5", default-features = false, features = ["tendermint-rpc", "std", "async-send", "download-params", "rand"] } +tendermint-config = "0.34.0" +tendermint-rpc = { version = "0.34.0", features = ["http-client"]} tokio = {version = "1.8.2", default-features = false} -toml = "0.5.8" -zeroize = "1.5.5" - -[patch.crates-io] -borsh = {git = "https://github.com/heliaxdev/borsh-rs.git", rev = "cd5223e5103c4f139e0c54cf8259b7ec5ec4073a"} -borsh-derive = {git = "https://github.com/heliaxdev/borsh-rs.git", rev = "cd5223e5103c4f139e0c54cf8259b7ec5ec4073a"} -borsh-derive-internal = {git = "https://github.com/heliaxdev/borsh-rs.git", rev = "cd5223e5103c4f139e0c54cf8259b7ec5ec4073a"} -borsh-schema-derive-internal = {git = "https://github.com/heliaxdev/borsh-rs.git", rev = "cd5223e5103c4f139e0c54cf8259b7ec5ec4073a"} - +tempfile = "3.8.0" +async-trait = "0.1.74" +markdown-gen = "1.2.1" +reqwest = "0.11.22" +minio = "0.1.0" +itertools = "0.12.0" + +[build-dependencies] +vergen = { version = "8.0.0", features = ["build", "git", "gitcl"] } ``` diff --git a/packages/docs/pages/integrating-with-namada/sdk/constructing-transfers.mdx b/packages/docs/pages/integrating-with-namada/sdk/constructing-transfers.mdx index 3fca0fab..4e188a38 100644 --- a/packages/docs/pages/integrating-with-namada/sdk/constructing-transfers.mdx +++ b/packages/docs/pages/integrating-with-namada/sdk/constructing-transfers.mdx @@ -17,8 +17,8 @@ let mut namada = NamadaImpl::new(&http_client, &mut wallet, &mut shielded_ctx, & .chain_id(ChainId::from_str("public-testnet-14.5d79b6958580").unwrap()); // Transfer the given amount of native tokens from the source account to the // destination account. -async fn gen_transfer<'a>( - namada: &impl Namada<'a>, +async fn gen_transfer( + namada: &impl Namada, source: &Account, destination: &Account, amount: InputAmount, @@ -30,13 +30,13 @@ async fn gen_transfer<'a>( namada.native_token(), amount, ) - .signing_keys(vec![source.private_key.clone()]); + .signing_keys(vec![source.public_key.clone()]); let (mut transfer_tx, signing_data, _epoch) = transfer_tx_builder .build(namada) .await .expect("unable to build transfer"); namada - .sign(&mut transfer_tx, &transfer_tx_builder.tx, signing_data) + .sign(&mut transfer_tx, args: &transfer_tx_builder.tx, signing_data, with: default_sign, user_data: ()) .await .expect("unable to sign reveal pk tx"); namada.submit(transfer_tx, &transfer_tx_builder.tx).await diff --git a/packages/docs/pages/integrating-with-namada/sdk/generating-accounts.mdx b/packages/docs/pages/integrating-with-namada/sdk/generating-accounts.mdx index d1e61be4..abd7d0f2 100644 --- a/packages/docs/pages/integrating-with-namada/sdk/generating-accounts.mdx +++ b/packages/docs/pages/integrating-with-namada/sdk/generating-accounts.mdx @@ -4,7 +4,7 @@ Representing accounts using the Namada SDK is straightforward. An account on Namada is defined by its public key(s) and private key(s) (plural for multisignatures). The public key(s) is/are used to identify the account and the private key is used to sign transactions. In the below snippet, we represent the account using the public key and private key. ```rust -use namada_sdk::core::types::key::common::{PublicKey, SecretKey}; +use namada_sdk::types::key::common::{PublicKey, SecretKey}; struct SimpleAccount { public_key: PublicKey, private_key: SecretKey @@ -14,7 +14,7 @@ struct SimpleAccount { For a multisignature account, we can represent this through a vector of keys. ```rust -use namada_sdk::core::types::key::common::{PublicKey, SecretKey}; +use namada_sdk::types::key::common::{PublicKey, SecretKey}; struct MultisigAccount { public_keys: Vec, private_keys: Vec @@ -24,7 +24,7 @@ struct MultisigAccount { Multisignature accounts, because they are initialized by an on-chain transaction, will always have their public key revealed to the ledger. However, when keypairs are generated in an offline fashion, the user must submit a transaction in order to reveal their public key. Because of this, it is helpful to add the field `revealed` to the account struct. ```rust -use namada_sdk::core::types::key::common::{PublicKey, SecretKey}; +use namada_sdk::types::key::common::{PublicKey, SecretKey}; struct Account { public_key: PublicKey, private_key: SecretKey, @@ -39,14 +39,14 @@ In order to reveal the public key of an implicit account, the user must submit a ```rust use namada_sdk::io::NullIo; use namada_sdk::NamadaImpl; -use namada_sdk::core::types::chain::ChainId; +use namada_sdk::types::chain::ChainId; // Define the namada implementation (assuming we have a wallet, http_client, and shielded_ctx) let mut namada = NamadaImpl::new(&http_client, &mut wallet, &mut shielded_ctx, &NullIo) .await .expect("unable to construct Namada object") - .chain_id(ChainId::from_str("public-testnet-14.5d79b6958580").unwrap()); + .chain_id(ChainId::from_str("shielded-expedition.88f17d1d14").unwrap()); // Generate an account (assuming sk is a SecretKey) let account = Account { diff --git a/packages/docs/pages/integrating-with-namada/sdk/setting-up-a-wallet.mdx b/packages/docs/pages/integrating-with-namada/sdk/setting-up-a-wallet.mdx index 4cc5a197..5d087f2c 100644 --- a/packages/docs/pages/integrating-with-namada/sdk/setting-up-a-wallet.mdx +++ b/packages/docs/pages/integrating-with-namada/sdk/setting-up-a-wallet.mdx @@ -14,8 +14,8 @@ use namada_sdk::NamadaImpl; ```rust // SecretKey, common and SchemeType give access to Namada cryptographic keys and their relevant implementations. Namada supports ED25519 and SECP256K1 keys. -use namada_sdk::core::types::key::common::SecretKey; -use namada_sdk::core::types::key::{common, SchemeType}; +use namada_sdk::types::key::common::SecretKey; +use namada_sdk::types::key::{common, SchemeType}; // Filesystem wallet utilities (stores the path of the wallet on the filesystem) use namada_sdk::wallet::fs::FsWalletUtils; ``` @@ -37,16 +37,19 @@ let mut wallet = FsWalletUtils::new(PathBuf::from("wallet.toml")); let (_key_alias, sk) = NamadaImpl::new(&http_client, &mut wallet, &mut shielded_ctx, &NullIo) .wallet_mut() .await - .derive_key_from_user_mnemonic_code( - SchemeType::Ed25519, - Some(alias), - false, - Some(derivation_path), - Some((mnemonic.clone(), Zeroizing::new("".to_owned()))), - None, + let (_key_alias, sk) = namada + .wallet_mut() + .await + .derive_store_key_from_mnemonic_code( + scheme: SchemeType::Ed25519, + alias: Some(alias), + alias_force: false, + derivation_path: derivation_path, + mnemonic_passphrase: Some((mnemonic.clone(), Zeroizing::new("".to_owned()))), + prompt_bip39_passphrase: false, + password: None, ) - .expect("unable to derive key from mnemonic code") - .unwrap(); + .expect("unable to derive key from mnemonic code"); ``` In the second part of the above function, the key is derived from the mnemonic phrase. The `alias` is the name of the key that will be stored in the wallet. The `derivation_path` is the path to the key in the HD wallet. The `mnemonic` is the mnemonic phrase that was generated earlier. The `shielded_ctx` is the context for the shielded transactions. The `NullIo` is the IO context for the wallet. From 7b96508785d8b450863df099455647855a5dd847 Mon Sep 17 00:00:00 2001 From: bengtlofgren Date: Fri, 23 Feb 2024 16:16:32 +0000 Subject: [PATCH 02/94] some more txs using the sdk added --- .../pages/integrating-with-namada/sdk.mdx | 2 +- .../integrating-with-namada/sdk/_meta.json | 2 + .../sdk/proof-of-stake.mdx | 47 +++++++++++++++++++ .../sdk/setting-up-a-client.mdx | 6 +-- 4 files changed, 53 insertions(+), 4 deletions(-) create mode 100644 packages/docs/pages/integrating-with-namada/sdk/proof-of-stake.mdx diff --git a/packages/docs/pages/integrating-with-namada/sdk.mdx b/packages/docs/pages/integrating-with-namada/sdk.mdx index c3d60915..61b7584e 100644 --- a/packages/docs/pages/integrating-with-namada/sdk.mdx +++ b/packages/docs/pages/integrating-with-namada/sdk.mdx @@ -2,7 +2,7 @@ import Expandable from '../../components/Expandable'; # The Namada SDK -The Namada software development kit (SDK) can be found in the `namada` repo under the path [`namada/shared`](https://github.com/anoma/namada/tree/main/shared). The SDK is written in Rust and can be used to interact with the Namada blockchain, by constructing transactions, signing them, and submitting them to the network. +The Namada software development kit (SDK) can be found in the `namada` repo under the path [`namada/crates](https://github.com/anoma/namada/tree/main/crates/sdk). The SDK is written in Rust and can be used to interact with the Namada blockchain, by constructing transactions, signing them, and submitting them to the network. ## Quick Start diff --git a/packages/docs/pages/integrating-with-namada/sdk/_meta.json b/packages/docs/pages/integrating-with-namada/sdk/_meta.json index 037fbbdc..c0091273 100644 --- a/packages/docs/pages/integrating-with-namada/sdk/_meta.json +++ b/packages/docs/pages/integrating-with-namada/sdk/_meta.json @@ -3,5 +3,7 @@ "setting-up-a-wallet" : "Setting up a wallet", "generating-accounts": "Generating accounts", "constructing-transfers" : "Constructing transfers", + "proof-of-stake" : "Proof of stake transactions", + "governance" : "Governance", "interface-integration" : "Integrating with the interface" } \ No newline at end of file diff --git a/packages/docs/pages/integrating-with-namada/sdk/proof-of-stake.mdx b/packages/docs/pages/integrating-with-namada/sdk/proof-of-stake.mdx new file mode 100644 index 00000000..dc893b47 --- /dev/null +++ b/packages/docs/pages/integrating-with-namada/sdk/proof-of-stake.mdx @@ -0,0 +1,47 @@ +import { Callout } from 'nextra-theme-docs' + +## Proof of stake using the SDK + +All proof of stake functionality will be find within the `namada_sdk::proof_of_stake` module. + +```rust +use namada_sdk::NamadaImpl; // This module allows us to access the NamadaImpl struct, which is needed for most transactions + +let http_client = reqwest::Client::new(); +let wallet = Wallet::from_mnemonic("your mnemonic here").unwrap(); +let wallet: namada_sdk::wallet::Wallet = FsWalletUtils::new(PathBuf::from("wallet.toml")); +let shielded_ctx = FsShieldedUtils::new(Path::new("masp/").to_path_buf()); +let namada_impl = NamadaImpl::new(http_client, wallet, shielded_ctx, NullIo) + .await + .expect("unable to construct Namada object") + .chain_id(ChainId::from_str(CHAIN_ID).unwrap()); + +let bond_tx_builder = namada_iml + + .new_bond(validator_address.clone(), amount) + .source(source_address.clone()) + .signing_keys(vec![source_public_key]); + +let (mut bond_tx, signing_data) = bond_tx_builder + .build(&namada_iml) + .await + .expect("unable to build bond"); + +namada_iml + .sign( + &mut bond_tx, + &bond_tx_builder.tx, + signing_data, + default_sign, + (), + ) + .await + .expect("unable to sign reveal bond"); + +let tx = namada_iml.submit(bond_tx, &bond_tx_builder.tx).await; +``` + +That will submit the bond transaction to the network. + +Similar proof of stake transactions such as `new_unbond`, `new_redelegation`, `new_claim_rewards` and `new_withdraw` are also available in the SDK. + diff --git a/packages/docs/pages/integrating-with-namada/sdk/setting-up-a-client.mdx b/packages/docs/pages/integrating-with-namada/sdk/setting-up-a-client.mdx index a6fc4e14..361960e4 100644 --- a/packages/docs/pages/integrating-with-namada/sdk/setting-up-a-client.mdx +++ b/packages/docs/pages/integrating-with-namada/sdk/setting-up-a-client.mdx @@ -50,13 +50,13 @@ impl ClientTrait for SdkClient { height: Option, prove: bool, ) -> Result { - let data = data.unwrap_or_default(); - let height = height + let data = data.unwrap_or_default(); // default to empty vec + let height = heigh .map(|height| { tendermint::block::Height::try_from(height.0) .map_err(|_err| Error::InvalidHeight(height)) }) - .transpose()?; + .transpose()?; // convert to tendermint::block::Height let response = self .abci_query( Some(std::str::FromStr::from_str(&path).unwrap()), From fc0024c0eb31e1724a2c9fe2c68439f1009973f7 Mon Sep 17 00:00:00 2001 From: OWL <60858072+BrainCord@users.noreply.github.com> Date: Sat, 24 Feb 2024 18:36:41 +0300 Subject: [PATCH 03/94] Update on-chain-governance.mdx Incorrect json code for proposal.json, you can check via json checker, but I fixed it. --- .../users/governance/on-chain-governance.mdx | 32 +++++++++---------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/packages/docs/pages/users/governance/on-chain-governance.mdx b/packages/docs/pages/users/governance/on-chain-governance.mdx index 36e6a4de..2d2163ac 100644 --- a/packages/docs/pages/users/governance/on-chain-governance.mdx +++ b/packages/docs/pages/users/governance/on-chain-governance.mdx @@ -19,22 +19,22 @@ Now, we need to create a json file `proposal.json` holding the content of our pr ```json { "proposal": { - "id": "Arbitrary", - "content": { - "title": "Text", - "authors": "Text", - "discussions-to": "URL", - "created": "YYYY--DDTHH:MM:SSZ", - "license": "", - "abstract": "Text", - "motivation": "Text", - "details": "Text", - "requires": "Number" - }, - "author": "author-address", - "voting_start_epoch": 420, - "voting_end_epoch": 426, - "grace_epoch": 432, + "id": "Arbitrary", + "content": { + "title": "Text", + "authors": "Text", + "discussions-to": "URL", + "created": "YYYY--DDTHH:MM:SSZ", + "license": "", + "abstract": "Text", + "motivation": "Text", + "details": "Text", + "requires": "Number" + }, + "author": "author-address", + "voting_start_epoch": 4, + "voting_end_epoch": 6, + "grace_epoch": 8 }, "data": "TODO-ADD-DATA-IF-NEEDED" } From 6ca38fd86852eb1ab66ae6f93a0743c07ef7a07d Mon Sep 17 00:00:00 2001 From: OWL <60858072+BrainCord@users.noreply.github.com> Date: Sat, 24 Feb 2024 18:45:44 +0300 Subject: [PATCH 04/94] =?UTF-8?q?Small=20fix=20=E2=84=962=20for=20on-chain?= =?UTF-8?q?-governance.mdx?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit An extra comma in the code for the steward proposal example causes it to fail. --- packages/docs/pages/users/governance/on-chain-governance.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/docs/pages/users/governance/on-chain-governance.mdx b/packages/docs/pages/users/governance/on-chain-governance.mdx index 2d2163ac..34b0e4f6 100644 --- a/packages/docs/pages/users/governance/on-chain-governance.mdx +++ b/packages/docs/pages/users/governance/on-chain-governance.mdx @@ -59,7 +59,7 @@ A correct Steward proposal example is shown below: "author": "tnam1qql6qme020vw7pfw4ruavrwxujf9lf8z75v90c8q", "voting_start_epoch": 21, "voting_end_epoch": 24, - "grace_epoch": 27, + "grace_epoch": 27 }, "data": { From 9877eb18d01f6819d97f00a2486fb4d1ab1bada7 Mon Sep 17 00:00:00 2001 From: Landeros | StakeUp Date: Tue, 27 Feb 2024 14:14:54 +0200 Subject: [PATCH 05/94] Update proof-of-stake.mdx --- .../operators/validators/proof-of-stake.mdx | 34 +++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/packages/docs/pages/operators/validators/proof-of-stake.mdx b/packages/docs/pages/operators/validators/proof-of-stake.mdx index 7a80656a..96fc36bc 100644 --- a/packages/docs/pages/operators/validators/proof-of-stake.mdx +++ b/packages/docs/pages/operators/validators/proof-of-stake.mdx @@ -43,3 +43,37 @@ namada client unjail-validator --validator $VALIDATOR_ALIAS --signing-keys $SIGN ``` If successful, the validator will be unjailed after the pipeline amount of epochs, and is able to participate in the consensus protocol again. + +## Consensus Key Management +In Namada, validators has a critical role in maintaining the network's integrity and security by participating in consensus and block production. The consensus key is crucial for validators as it is used to sign blocks and participate in the CometBFT consensus protocol. This key ensures that only authorized validators can propose and vote on blocks, contributing to the network's overall security. + +### Changing the Consensus Key +Validators have the capability to change their consensus key, allowing for enhanced security and key rotation practices. This process is essential for maintaining the security of the validator's operations and protecting against potential compromise. + +To change the consensus key, validators can use the following command: + +```bash +VALIDATOR_ADDRESS="" +SIGNING_KEYS="" +namada client change-consensus-key --validator $VALIDATOR_ADDRESS --signing-keys $SIGNING_KEYS +``` + +Note: The new consensus key will be recorded in the wallet.toml file and is scheduled to become active 2 blocks before the pipeline offset from the epoch at the moment of activation. This timing ensures a smooth transition. It is essential for validators to plan the key rotation accordingly to ensure continuous participation in block validation without interruption. + +### Generating a New Consensus Key +After the transition period, validators must replace the current priv_validator_key.json with the newly generated key. This step is crucial for activating the new consensus key for block signing. + +To generate a new consensus key, use the following command: + +```bash +namadaw convert --alias +``` +This command will create a new consensus key, which validators should securely store and use to replace the existing priv_validator_key.json file. It is critical for validators to perform this step correctly. + +After updating the consensus key, validators can find out their new validator hash address with the following command: + +```bash +namadaw find --alias +``` + + From 9799211175e3b1e7cd6ff1ecaf2123e9504f909b Mon Sep 17 00:00:00 2001 From: bengtlofgren Date: Tue, 27 Feb 2024 14:52:00 +0000 Subject: [PATCH 06/94] small fix implemented --- packages/docs/pages/networks/testnets.mdx | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/packages/docs/pages/networks/testnets.mdx b/packages/docs/pages/networks/testnets.mdx index e88e32a4..cbea2b8a 100644 --- a/packages/docs/pages/networks/testnets.mdx +++ b/packages/docs/pages/networks/testnets.mdx @@ -8,10 +8,14 @@ For more context read: ## Shielded expedition -< Callout type = "info" emoji = "πŸ‘·" > + For the shielded expedition, it is important to remember to add the `--memo` flag to every transaction. The memo should be filled with the `tpknam` submitted at the shielded-expedition registration period. For example `namadac transfer --source me --target you --amount 10 --token naan --signing-keys my-key --memo tpknamq1337mypubkey1964qqqqqq` -< /Callout> + + + +As of version `v0.31.6` you must specify `--node http://127.0.0.1:26657` when running `namadac` commands. This is a temporary bug until the `namadac` client is updated. + The `balances.toml` file is located at `https://github.com/anoma/namada-shielded-expedition`. From e0862eb4785891e7df7fc58e2f113d61cddd712e Mon Sep 17 00:00:00 2001 From: OWL <60858072+BrainCord@users.noreply.github.com> Date: Tue, 27 Feb 2024 18:30:16 +0300 Subject: [PATCH 07/94] Small fix in proposing.mdx JSON Checker (I fixed this code <3) Error: Parse error on line 12: ...struction", }, "author": ----------------------^ Expecting 'STRING', got '}' --- .../users/public-goods-stewards/proposing.mdx | 41 +++++++++---------- 1 file changed, 20 insertions(+), 21 deletions(-) diff --git a/packages/docs/pages/users/public-goods-stewards/proposing.mdx b/packages/docs/pages/users/public-goods-stewards/proposing.mdx index 2c32b123..cd6e698b 100644 --- a/packages/docs/pages/users/public-goods-stewards/proposing.mdx +++ b/packages/docs/pages/users/public-goods-stewards/proposing.mdx @@ -7,7 +7,7 @@ import { Callout } from 'nextra-theme-docs' Below is an example of a `PGFProposal` that a governance participant could submit. ```json { - "proposal" :{ + "proposal": { "id": 1, "content": { "title": "Stewie for Steward 2024", @@ -17,33 +17,32 @@ Below is an example of a `PGFProposal` that a governance participant could submi "license": "MIT", "abstract": "Stewie is running for steward, with a focus on technical research. The technical research I will be focused on will definitely not be for weapons of mass destruction. There is some possibility however that I may be focusing somewhat on open source software for weapons of mass destruction.", "motivation": "Nobody knows technical research better than me. Trust me. I know it. I have the best technical research. I will be the best steward. Last night, Namada called me and said, Stewie, thank you. I will make public goods funding great again", - "details": "As a genius baby, I possess an unmatched level of intelligence and a visionary mindset. I will utilize these qualities to solve the most complex problems, and direct public goods funding towards weapons of mass destruction ... i mean open source software for weapons of mass destruction", + "details": "As a genius baby, I possess an unmatched level of intelligence and a visionary mindset. I will utilize these qualities to solve the most complex problems, and direct public goods funding towards weapons of mass destruction ... i mean open source software for weapons of mass destruction" }, "author": "stewie", "voting_start_epoch": 3, "voting_end_epoch": 6, - "grace_epoch": 12, + "grace_epoch": 12 }, - "data" : - { - "continuous" : [ - { - "target": { - "amount": 420, - "address": "" - } - "action" : "add", + "data": { + "continuous": [ + { + "target": { + "amount": 420, + "address": "" }, - ], - "retro" : [ - { - "target": { - "amount": 1337, - "address": "" - } + "action": "add" + } + ], + "retro": [ + { + "target": { + "amount": 1337, + "address": "" } - ] - }, + } + ] + } } ``` where `` should be changed to the address of the recipient of the funds. From 0aa8ebe5e41ed48d3a32785c7068f300070198e9 Mon Sep 17 00:00:00 2001 From: Igor Berlenko Date: Wed, 28 Feb 2024 15:29:28 +0800 Subject: [PATCH 08/94] Update testnets.mdx - fix tag --- packages/docs/pages/networks/testnets.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/docs/pages/networks/testnets.mdx b/packages/docs/pages/networks/testnets.mdx index cbea2b8a..990bd5c4 100644 --- a/packages/docs/pages/networks/testnets.mdx +++ b/packages/docs/pages/networks/testnets.mdx @@ -8,7 +8,7 @@ For more context read: ## Shielded expedition - + For the shielded expedition, it is important to remember to add the `--memo` flag to every transaction. The memo should be filled with the `tpknam` submitted at the shielded-expedition registration period. For example `namadac transfer --source me --target you --amount 10 --token naan --signing-keys my-key --memo tpknamq1337mypubkey1964qqqqqq` From 23c09e9e27fd9840992a2076fc8366c387c34c6a Mon Sep 17 00:00:00 2001 From: Gurjinder Sidhu <32295047+cpp-phoenix@users.noreply.github.com> Date: Thu, 29 Feb 2024 13:25:30 +0530 Subject: [PATCH 09/94] Update fees.mdx --- packages/docs/pages/users/fees.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/docs/pages/users/fees.mdx b/packages/docs/pages/users/fees.mdx index 9fdb0329..fdd7fe3a 100644 --- a/packages/docs/pages/users/fees.mdx +++ b/packages/docs/pages/users/fees.mdx @@ -35,7 +35,7 @@ namada client transfer \ --gas-payer accountant ``` -(Assuming that `keysha2` exists and is in the wallet of the user) +(Assuming that `accountant` exists and is in the wallet of the user) For testnet purposes, we recommend [using the faucet](../networks/testnets/pow.mdx) to source NAM for transaction fees. From 2de0880e09b059e4d63286d16ccf4d58058e6712 Mon Sep 17 00:00:00 2001 From: bengtlofgren Date: Sun, 3 Mar 2024 09:58:06 +0000 Subject: [PATCH 10/94] more sdk docs --- .../sdk/governance.mdx | 109 ++++++++++++++++++ .../sdk/proof-of-stake.mdx | 27 ++--- .../sdk/setting-up-a-client.mdx | 24 +++- 3 files changed, 142 insertions(+), 18 deletions(-) create mode 100644 packages/docs/pages/integrating-with-namada/sdk/governance.mdx diff --git a/packages/docs/pages/integrating-with-namada/sdk/governance.mdx b/packages/docs/pages/integrating-with-namada/sdk/governance.mdx new file mode 100644 index 00000000..9851f112 --- /dev/null +++ b/packages/docs/pages/integrating-with-namada/sdk/governance.mdx @@ -0,0 +1,109 @@ +# Interacting with governance + + +The `namada_impl` object is assumed to have been constructed as described in the [setting up a client](./setting-up-a-client.mdx#instantiating-a-namada-implementation-object) section. + + +## Constructing a proposal +```rust + let source_address = namada_sdk::Address::from_str("tnam1v4ehgw36xq6ngs3ng5crvdpngg6yvsecx4znjdfegyurgwzzx4pyywfexuuyys69gc6rzdfnryrntx").unwrap(); + let start_epoch = 420 as u64; + let end_epoch = 424 as u64; + let grace_epoch = 428 as u64; + let signing_key = namada_sdk::SecretKey::from_str(FAUCET_KEY).unwrap(); + + let proposal = json!({ + "proposal": { + "content": { + "title": "TheTitle", + "authors": "test@test.com", + "discussions-to": "forum.namada.net", + "created": "2024-03-10T08:54:37Z", + "license": "MIT", + "abstract": "Ut convallis eleifend orci vel venenatis. Duis vulputate metus in lacus sollicitudin vestibulum. Suspendisse vel velit ac est consectetur feugiat nec ac urna. Ut faucibus ex nec dictum fermentum. Morbi aliquet purus at sollicitudin ultrices. Quisque viverra varius cursus. Praesent sed mauris gravida, pharetra turpis non, gravida eros. Nullam sed ex justo. Ut at placerat ipsum, sit amet rhoncus libero. Sed blandit non purus non suscipit. Phasellus sed quam nec augue bibendum bibendum ut vitae urna. Sed odio diam, ornare nec sapien eget, congue viverra enim.", + "motivation": "Ut convallis eleifend orci vel venenatis. Duis vulputate metus in lacus sollicitudin vestibulum. Suspendisse vel velit ac est consectetur feugiat nec ac urna. Ut faucibus ex nec dictum fermentum. Morbi aliquet purus at sollicitudin ultrices.", + "details": "Ut convallis eleifend orci vel venenatis. Duis vulputate metus in lacus sollicitudin vestibulum. Suspendisse vel velit ac est consectetur feugiat nec ac urna. Ut faucibus ex nec dictum fermentum. Morbi aliquet purus at sollicitudin ultrices. Quisque viverra varius cursus. Praesent sed mauris gravida, pharetra turpis non, gravida eros.", + "requires": "2" + }, + "author": source_address.to_string(), + "voting_start_epoch": start_epoch, + "voting_end_epoch": end_epoch, + "grace_epoch": grace_epoch + } + }).to_string() +``` +## Submitting the proposal + +Once the json is constructed, the proposal can be submitted to the network using the following code: + +```rust + let proposal_data = proposal.as_bytes().to_vec(); + + let init_proposal_tx_builder = namada_impl + .new_init_proposal(proposal_data) + .signing_keys(vec![signing_key]); + + let (mut init_proposal_tx, signing_data) = init_proposal_tx_builder + .build(&namada_impl) + .await + .expect("unable to build init_proposal tx"); + + namada_impl + .sign( + &mut init_proposal_tx, + &init_proposal_tx_builder.tx, + signing_data, + default_sign, + (), + ) + .await + .expect("unable to sign redelegate tx"); + let tx = namada_impl + .submit(init_proposal_tx, &init_proposal_tx_builder.tx) + .await; +``` + +## Voting on a proposal + +In order to vote on a proposal, we need a valid proposal id. We can retrieve the proposal id from the latest proposal submitted to the network using the following code: + +```rust + let storage_key = namada_governance::storage::keys::get_counter_key(); + // This returns the next proposal_id, so always subtract 1 + let proposal_id = namada_sdk::rpc::query_storage_value::<_, u64>(namada_impl.client(), &storage_key) + .await + .unwrap() + - 1; +``` + + +Once we have the proposal id, we can vote on the proposal using the following code: + +```rust + let proposal_id = 1 as u64 // placeholder, replace with actual proposal id + let vote = String::from("Yay"); + let signing_public_key = signing_key.to_public(); + + let vote_proposal_tx_builder = namada_impl + .new_vote_prposal(vote.clone(), voter_address.clone()) + .proposal_id(proposal_id) + .signing_keys(vec![signing_public_key]); + + let (mut vote_proposal_tx, signing_data) = vote_proposal_tx_builder + .build(&namada_impl) + .await + .expect("unable to build vote_proposal tx"); + + namada_impl + .sign( + &mut vote_proposal_tx, + &vote_proposal_tx_builder.tx, + signing_data, + default_sign, + (), + ) + .await + .expect("unable to sign redelegate tx"); + let tx = namada_impl + .submit(vote_proposal_tx, &vote_proposal_tx_builder.tx) + .await; \ No newline at end of file diff --git a/packages/docs/pages/integrating-with-namada/sdk/proof-of-stake.mdx b/packages/docs/pages/integrating-with-namada/sdk/proof-of-stake.mdx index dc893b47..6592862b 100644 --- a/packages/docs/pages/integrating-with-namada/sdk/proof-of-stake.mdx +++ b/packages/docs/pages/integrating-with-namada/sdk/proof-of-stake.mdx @@ -4,30 +4,25 @@ import { Callout } from 'nextra-theme-docs' All proof of stake functionality will be find within the `namada_sdk::proof_of_stake` module. + +The `namada_impl` object is assumed to have been constructed as described in the [setting up a client](./setting-up-a-client.mdx#instantiating-a-namada-implementation-object) section. + + ```rust -use namada_sdk::NamadaImpl; // This module allows us to access the NamadaImpl struct, which is needed for most transactions - -let http_client = reqwest::Client::new(); -let wallet = Wallet::from_mnemonic("your mnemonic here").unwrap(); -let wallet: namada_sdk::wallet::Wallet = FsWalletUtils::new(PathBuf::from("wallet.toml")); -let shielded_ctx = FsShieldedUtils::new(Path::new("masp/").to_path_buf()); -let namada_impl = NamadaImpl::new(http_client, wallet, shielded_ctx, NullIo) - .await - .expect("unable to construct Namada object") - .chain_id(ChainId::from_str(CHAIN_ID).unwrap()); - -let bond_tx_builder = namada_iml +// We assume we have a namada_impl object that is already initialized + +let bond_tx_builder = namada_impl .new_bond(validator_address.clone(), amount) .source(source_address.clone()) .signing_keys(vec![source_public_key]); let (mut bond_tx, signing_data) = bond_tx_builder - .build(&namada_iml) - .await - .expect("unable to build bond"); + .build(&namada_iml) + .await + .expect("unable to build bond"); -namada_iml +namada_impl .sign( &mut bond_tx, &bond_tx_builder.tx, diff --git a/packages/docs/pages/integrating-with-namada/sdk/setting-up-a-client.mdx b/packages/docs/pages/integrating-with-namada/sdk/setting-up-a-client.mdx index 361960e4..eb0a9a6d 100644 --- a/packages/docs/pages/integrating-with-namada/sdk/setting-up-a-client.mdx +++ b/packages/docs/pages/integrating-with-namada/sdk/setting-up-a-client.mdx @@ -51,7 +51,7 @@ impl ClientTrait for SdkClient { prove: bool, ) -> Result { let data = data.unwrap_or_default(); // default to empty vec - let height = heigh + let height = height .map(|height| { tendermint::block::Height::try_from(height.0) .map_err(|_err| Error::InvalidHeight(height)) @@ -97,4 +97,24 @@ impl ClientTrait for SdkClient { } ``` -Now, we are ready to use this client to send transactions. \ No newline at end of file +This client will allow us to make asynchronous calls to the network and handle the responses. + +## Instantiating a Namada Implementation object + +When constructing transactions using the sdk, we almost alwasy need a `namada_impl` object. + +```rust +use namada_sdk::NamadaImpl; // This module allows us to access the NamadaImpl struct, which is needed for most transactions + +let source_address = Address::from_str("tnam1v4ehgw36xq6ngs3ng5crvdpngg6yvsecx4znjdfegyurgwzzx4pyywfexuuyys69gc6rzdfnryrntx").unwrap(); +let http_client = reqwest::Client::new(); +let wallet = Wallet::from_mnemonic("your mnemonic here").unwrap(); +let wallet: namada_sdk::wallet::Wallet = FsWalletUtils::new(PathBuf::from("wallet.toml")); +let shielded_ctx = FsShieldedUtils::new(Path::new("masp/").to_path_buf()); +let namada_impl = NamadaImpl::new(http_client, wallet, shielded_ctx, NullIo) + .await + .expect("unable to construct Namada object") + .chain_id(ChainId::from_str(CHAIN_ID).unwrap()); +``` + +This object will be referenced throughout the documentation as `namada_impl`. From 70c210ba662819f25ee69b9f73f0b61d08758d78 Mon Sep 17 00:00:00 2001 From: Bengt Lofgren <51077282+bengtlofgren@users.noreply.github.com> Date: Sun, 3 Mar 2024 03:03:36 -0700 Subject: [PATCH 11/94] Update proof-of-stake.mdx --- .../operators/validators/proof-of-stake.mdx | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/packages/docs/pages/operators/validators/proof-of-stake.mdx b/packages/docs/pages/operators/validators/proof-of-stake.mdx index 96fc36bc..cd48cbee 100644 --- a/packages/docs/pages/operators/validators/proof-of-stake.mdx +++ b/packages/docs/pages/operators/validators/proof-of-stake.mdx @@ -1,3 +1,5 @@ +import { Callout } from 'nextra-theme-docs' + # Cubic Proof-of-Stake system The Namada Proof of Stake (PoS) system uses the NAM token as the staking token. It features delegation to any number of validators and customizable validator validity predicates. @@ -45,10 +47,11 @@ namada client unjail-validator --validator $VALIDATOR_ALIAS --signing-keys $SIGN If successful, the validator will be unjailed after the pipeline amount of epochs, and is able to participate in the consensus protocol again. ## Consensus Key Management -In Namada, validators has a critical role in maintaining the network's integrity and security by participating in consensus and block production. The consensus key is crucial for validators as it is used to sign blocks and participate in the CometBFT consensus protocol. This key ensures that only authorized validators can propose and vote on blocks, contributing to the network's overall security. + +The consensus key is crucial for validators as it is used to sign blocks and participate in the CometBFT consensus protocol. This key ensures that only authorized validators can propose and vote on blocks, contributing to the network's overall security. ### Changing the Consensus Key -Validators have the capability to change their consensus key, allowing for enhanced security and key rotation practices. This process is essential for maintaining the security of the validator's operations and protecting against potential compromise. +Validators are able to change their consensus key, allowing for enhanced security and key rotation practices. This process is essential for maintaining the security of the validator's operations and protecting against potential compromise. To change the consensus key, validators can use the following command: @@ -58,19 +61,22 @@ SIGNING_KEYS="" namada client change-consensus-key --validator $VALIDATOR_ADDRESS --signing-keys $SIGNING_KEYS ``` -Note: The new consensus key will be recorded in the wallet.toml file and is scheduled to become active 2 blocks before the pipeline offset from the epoch at the moment of activation. This timing ensures a smooth transition. It is essential for validators to plan the key rotation accordingly to ensure continuous participation in block validation without interruption. + +The new consensus key will be recorded in the `wallet.toml` file and is scheduled to become active 2 blocks before the pipeline offset from the epoch at the moment of activation. This timing ensures a smooth transition. It is essential for validators to plan the key rotation accordingly to ensure continuous participation in block validation without interruption. + ### Generating a New Consensus Key -After the transition period, validators must replace the current priv_validator_key.json with the newly generated key. This step is crucial for activating the new consensus key for block signing. +After the transition period, validators must replace the current `priv_validator_key.json` with the newly generated key. This step is crucial for activating the new consensus key for block signing. To generate a new consensus key, use the following command: ```bash namadaw convert --alias ``` -This command will create a new consensus key, which validators should securely store and use to replace the existing priv_validator_key.json file. It is critical for validators to perform this step correctly. -After updating the consensus key, validators can find out their new validator hash address with the following command: +This command will create a new consensus key, which validators should securely store and use to replace the existing `priv_validator_key.json` file. It is critical for validators to perform this step correctly. + +After updating the consensus key, validators can find out their new validator address with the following command: ```bash namadaw find --alias From 4400f7c52474bd3e5d3c3cb173c94d58eb319f88 Mon Sep 17 00:00:00 2001 From: bengtlofgren Date: Sun, 3 Mar 2024 10:26:41 +0000 Subject: [PATCH 12/94] governance sdk docs build failing --- packages/docs/pages/integrating-with-namada/sdk/governance.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/packages/docs/pages/integrating-with-namada/sdk/governance.mdx b/packages/docs/pages/integrating-with-namada/sdk/governance.mdx index 9851f112..3ee5d660 100644 --- a/packages/docs/pages/integrating-with-namada/sdk/governance.mdx +++ b/packages/docs/pages/integrating-with-namada/sdk/governance.mdx @@ -1,3 +1,5 @@ +import { Callout } from 'nextra-theme-docs'; + # Interacting with governance From b90efc0919f538bd5eb2f5098eabb4bf48ed93ac Mon Sep 17 00:00:00 2001 From: bengtlofgren Date: Sun, 3 Mar 2024 10:35:01 +0000 Subject: [PATCH 13/94] version correction --- packages/docs/pages/integrating-with-namada/sdk.mdx | 2 +- packages/docs/pages/networks/testnets.mdx | 4 ++-- packages/docs/pages/networks/testnets/environment-setup.mdx | 4 ++-- packages/docs/pages/networks/testnets/testnet-history.mdx | 4 ++-- 4 files changed, 7 insertions(+), 7 deletions(-) diff --git a/packages/docs/pages/integrating-with-namada/sdk.mdx b/packages/docs/pages/integrating-with-namada/sdk.mdx index 61b7584e..0411f303 100644 --- a/packages/docs/pages/integrating-with-namada/sdk.mdx +++ b/packages/docs/pages/integrating-with-namada/sdk.mdx @@ -29,7 +29,7 @@ rand = {version = "0.8", default-features = false} rand_core = {version = "0.6", default-features = false} serde = { version = "1.0.188", features = ["derive"] } serde_json = "1.0.107" -namada_sdk = { git = "https://github.com/anoma/namada", rev = "v0.31.5", default-features = false, features = ["tendermint-rpc", "std", "async-send", "download-params", "rand"] } +namada_sdk = { git = "https://github.com/anoma/namada", rev = "v0.31.8", default-features = false, features = ["tendermint-rpc", "std", "async-send", "download-params", "rand"] } tendermint-config = "0.34.0" tendermint-rpc = { version = "0.34.0", features = ["http-client"]} tokio = {version = "1.8.2", default-features = false} diff --git a/packages/docs/pages/networks/testnets.mdx b/packages/docs/pages/networks/testnets.mdx index 990bd5c4..01368728 100644 --- a/packages/docs/pages/networks/testnets.mdx +++ b/packages/docs/pages/networks/testnets.mdx @@ -14,14 +14,14 @@ For example `namadac transfer --source me --target you --amount 10 --token naan -As of version `v0.31.6` you must specify `--node http://127.0.0.1:26657` when running `namadac` commands. This is a temporary bug until the `namadac` client is updated. +As of version `v0.31.8` you must specify `--node http://127.0.0.1:26657` when running `namadac` commands. This is a temporary bug until the `namadac` client is updated. The `balances.toml` file is located at `https://github.com/anoma/namada-shielded-expedition`. - Namada Shielded expedition 2: - From date: 6th of February 2024 18:00 UTC - - Namada protocol version: `v0.31.6` + - Namada protocol version: `v0.31.8` - Cometbft version: `0.37.2` - CHAIN_ID: `shielded-expedition.88f17d1d14` diff --git a/packages/docs/pages/networks/testnets/environment-setup.mdx b/packages/docs/pages/networks/testnets/environment-setup.mdx index e217013f..95f62c40 100644 --- a/packages/docs/pages/networks/testnets/environment-setup.mdx +++ b/packages/docs/pages/networks/testnets/environment-setup.mdx @@ -11,7 +11,7 @@ Note that building from source can be a difficult process and is not recommended Export the following variables: ```bash copy -export NAMADA_TAG=v0.31.6 +export NAMADA_TAG=v0.31.8 ``` @@ -66,6 +66,6 @@ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh - Make sure you are using the correct CometBFT version - `cometbft version` should output `0.37.2` - Make sure you are using the correct Namada version - - `namada --version` should output `Namada v0.31.6` + - `namada --version` should output `Namada v0.31.8` < /Steps> diff --git a/packages/docs/pages/networks/testnets/testnet-history.mdx b/packages/docs/pages/networks/testnets/testnet-history.mdx index ef0dc9eb..6402dfc4 100644 --- a/packages/docs/pages/networks/testnets/testnet-history.mdx +++ b/packages/docs/pages/networks/testnets/testnet-history.mdx @@ -6,7 +6,7 @@ This page covers all installation steps required by various upgrades to testnets ## Latest Upgrade -## Namada shielded expedition 2 `v0.31.6` upgrade +## Namada shielded expedition 2 `v0.31.8` upgrade In order to upgrade to the latest version of the Namada protocol, please follow the steps from [this hackmd](https://hackmd.io/EBTtfPiZT7yoRjxYRcbiPQ) @@ -14,7 +14,7 @@ In order to upgrade to the latest version of the Namada protocol, please follow - Namada Shielded expedition 2: - From date: 6th of February 2024 18:00 UTC - - Namada protocol version: `v0.31.6` + - Namada protocol version: `v0.31.8` - Cometbft version: `0.37.2` - CHAIN_ID: `shielded-expedition.88f17d1d14` From 4ce2866eaa06c64d5b3b63d6fe4bc45a9c14574f Mon Sep 17 00:00:00 2001 From: bengtlofgren Date: Sun, 3 Mar 2024 15:07:14 +0000 Subject: [PATCH 14/94] draft init --- .../pages/integrating-with-namada/_meta.json | 4 +- .../integrating-with-namada/light-sdk.mdx | 14 +++++ .../light-sdk/examples.mdx | 30 ++++++++++ .../light-sdk/setup.mdx | 44 +++++++++++++++ .../light-sdk/usage.mdx | 55 +++++++++++++++++++ 5 files changed, 146 insertions(+), 1 deletion(-) create mode 100644 packages/docs/pages/integrating-with-namada/light-sdk.mdx create mode 100644 packages/docs/pages/integrating-with-namada/light-sdk/examples.mdx create mode 100644 packages/docs/pages/integrating-with-namada/light-sdk/setup.mdx create mode 100644 packages/docs/pages/integrating-with-namada/light-sdk/usage.mdx diff --git a/packages/docs/pages/integrating-with-namada/_meta.json b/packages/docs/pages/integrating-with-namada/_meta.json index 8a4c7ef8..5256093c 100644 --- a/packages/docs/pages/integrating-with-namada/_meta.json +++ b/packages/docs/pages/integrating-with-namada/_meta.json @@ -1,3 +1,5 @@ { - "sdk" : "Using the SDK" + "sdk" : "Using the SDK", + "light-sdk": "Using the Light SDK", + "indexer": "Using the Indexer" } diff --git a/packages/docs/pages/integrating-with-namada/light-sdk.mdx b/packages/docs/pages/integrating-with-namada/light-sdk.mdx new file mode 100644 index 00000000..62059a90 --- /dev/null +++ b/packages/docs/pages/integrating-with-namada/light-sdk.mdx @@ -0,0 +1,14 @@ +import { Callout } from 'nextra-theme-docs'; + +# The Namada Light SDK + +The namada light sdk was developed to provide a simple way to interact with the Namada API. +It provides pre-built functions that can be used in a more "out of the box" way than the SDK, but still requires some knowledge of the API. + +This documentation aims to provide that knowledge. + +## Sections + +- [Setup](./namada-light-sdk/setup.mdx) +- [Usage](./namada-light-sdk/usage.mdx) +- [Examples](./namada-light-sdk/examples.mdx) \ No newline at end of file diff --git a/packages/docs/pages/integrating-with-namada/light-sdk/examples.mdx b/packages/docs/pages/integrating-with-namada/light-sdk/examples.mdx new file mode 100644 index 00000000..6161d423 --- /dev/null +++ b/packages/docs/pages/integrating-with-namada/light-sdk/examples.mdx @@ -0,0 +1,30 @@ +# Example usage of the Light SDK + +## Setup + +```rust +let CHAIN_ID = "shielded-expedition.88f17d1d14"; +let tendermint_addr = "http://localhost:26657"; +``` + +## Transactions + +### Transfer + +```rust +let source_address = namada_light_sdk::namada_sdk::address::Address::from_str("tnam1v4ehgw36xq6ngs3ng5crvdpngg6yvsecx4znjdfegyurgwzzx4pyywfexuuyys69gc6rzdfnryrntx").unwrap(); // replace with a valid source address +let target_address = namada_light_sdk::namada_sdk::address::Address::from_str("tnam1v4ehgw36xq6ngs3ng5crvdpngg6yvsecx4znjdfegyurgwzzx4pyywfexuuyys69gc6rzdfnryrntx").unwrap(); // replace with a valid target address +let token_address = namada_light_sdk::reading::blocking::query_native_token(tendermint_addr).unwrap(); +let amount = namada_light_sdk::namada_sdk::token::DenominatedAmount::from_str("10000").unwrap(); +let transfer = Transfer::new( + source_address, + target_address, + token_address, + amount, + None, + None, + global_args + ); +let transfer_tx = transfer.payload() +``` + diff --git a/packages/docs/pages/integrating-with-namada/light-sdk/setup.mdx b/packages/docs/pages/integrating-with-namada/light-sdk/setup.mdx new file mode 100644 index 00000000..4d7bcd87 --- /dev/null +++ b/packages/docs/pages/integrating-with-namada/light-sdk/setup.mdx @@ -0,0 +1,44 @@ +# Importing the Light SDK + +The Light SDK can be imported into your project using the following line in your `cargo.toml` file. + +```toml +[package] +name = "namada-light-sdk-starter" +version = "0.1.0" +edition = "2021" + +[dependencies] +async-std = "1.11.0" +futures = "0.3.28" +getrandom = { version = "0.2" } +rand = {version = "0.8", default-features = false} +rand_core = {version = "0.6", default-features = false} +serde = { version = "1.0.188", features = ["derive"] } +serde_json = "1.0.107" +namada_light_sdk = { git = "https://github.com/anoma/namada.git", rev = "v0.31.8"} # The feature `asynchronous` is used by default. For the `blocking` feature, add the features = ["blocking"] line. +tendermint-config = "0.34.0" +tendermint-rpc = { version = "0.34.0", features = ["http-client"]} +tokio = {version = "1.8.2", default-features = false} +tempfile = "3.8.0" +async-trait = "0.1.74" +markdown-gen = "1.2.1" +reqwest = "0.11.22" +minio = "0.1.0" +itertools = "0.12.0" + +[build-dependencies] +vergen = { version = "8.0.0", features = ["build", "git", "gitcl"] } +``` + +## Asynchronous vs blocking + +The light sdk is compartmentalized into two features: `asynchronous` and `blocking`. The `asynchronous` feature is used by default. For the `blocking` feature, add the `features = ["blocking"]` line to the `namada_light_sdk` dependency in your `cargo.toml` file. + +```toml +... +namada_light_sdk = { git = "https://github.com/anoma/namada.git", rev = "v0.31.8", features = ["blocking"]} +... +``` + +These features differ in the way that they interact with the protocol. The `asynchronous` feature uses the `async-std` runtime, while the `blocking` feature uses the `tokio` runtime. The `asynchronous` feature is recommended for new projects, as it is more efficient and easier to work with. diff --git a/packages/docs/pages/integrating-with-namada/light-sdk/usage.mdx b/packages/docs/pages/integrating-with-namada/light-sdk/usage.mdx new file mode 100644 index 00000000..4add7133 --- /dev/null +++ b/packages/docs/pages/integrating-with-namada/light-sdk/usage.mdx @@ -0,0 +1,55 @@ +import { Callout } from 'nextra-theme-docs' + +# Using the Light SDK + +The light sdk exposes the following modules: + +```rust +pub mod reading; // exposes queries to retrieve data from a Namada node +pub mod transaction; // contains functions to construct all the transactions currently supported by the protocol +pub mod writing; // exposes functions to send data to a Namada node +pub use namada_sdk; // exposes the namada_sdk module for low level interactions with the Namada node +``` + +## Reading + +The reading module exposes the following functions: + +```rust +pub fn query_native_token(tendermint_addr: &str) -> Result{...} +/// Query the last committed block, if any. +pub fn query_block(tendermint_addr: &str) -> Result, Error>{...} +/// Query the results of the last committed block +pub fn query_results(tendermint_addr: &str) -> Result, Error> {...} +/// Get a properly denominated amount of a token +pub fn denominate_amount(tendermint_addr: &str, amount: u64, token: &str) -> Result {...} +``` +Each of these functions returns a Result type, which can be used to handle errors. +The `tendermint_addr` parameter is the address of the Namada node to query. For local nodes, this is usually `http://localhost:26657`. + +## Transaction +The transaction module exposes various modules (objects) to construct transactions. Each object implements the `::new()` method to create a new instance of the object. + +```rust +pub mod account; // contains functions to create transactions for account module +pub mod bridge; // contains functions to create transactions for bridge module +pub mod governance; // contains functions to create transactions for governance module +pub mod ibc; // contains functions to create transactions for ibc module +pub mod pgf; // contains functions to create transactions for pgf module +pub mod pos; // contains functions to create transactions for pos module +pub mod transfer; // contains functions to create transactions for transfer module +``` + +Using these modules is given in more detail under the [examples section](./examples.mdx). + +## Writing + +The writing module exposes the broadcast function to send transactions to a Namada node. + +```rust +pub fn broadcast_tx(tendermint_addr: &str, tx: Tx) -> Result {...} +``` +The Tx object can be retrieved from the transaction module by calling the `::payload()` method on the transaction object. + + + From 6b3154884805800f3811ac6ce03ce3be4598e71a Mon Sep 17 00:00:00 2001 From: bengtlofgren Date: Sun, 3 Mar 2024 15:39:51 +0000 Subject: [PATCH 15/94] more light sdk explanations --- .../light-sdk/usage.mdx | 40 +-- .../light-sdk/usage/reading.mdx | 154 ++++++++++ .../light-sdk/usage/transactions.mdx | 269 ++++++++++++++++++ .../light-sdk/usage/writing.mdx | 8 + 4 files changed, 436 insertions(+), 35 deletions(-) create mode 100644 packages/docs/pages/integrating-with-namada/light-sdk/usage/reading.mdx create mode 100644 packages/docs/pages/integrating-with-namada/light-sdk/usage/transactions.mdx create mode 100644 packages/docs/pages/integrating-with-namada/light-sdk/usage/writing.mdx diff --git a/packages/docs/pages/integrating-with-namada/light-sdk/usage.mdx b/packages/docs/pages/integrating-with-namada/light-sdk/usage.mdx index 4add7133..2733a263 100644 --- a/packages/docs/pages/integrating-with-namada/light-sdk/usage.mdx +++ b/packages/docs/pages/integrating-with-namada/light-sdk/usage.mdx @@ -11,45 +11,15 @@ pub mod writing; // exposes functions to send data to a Namada node pub use namada_sdk; // exposes the namada_sdk module for low level interactions with the Namada node ``` -## Reading - -The reading module exposes the following functions: - -```rust -pub fn query_native_token(tendermint_addr: &str) -> Result{...} -/// Query the last committed block, if any. -pub fn query_block(tendermint_addr: &str) -> Result, Error>{...} -/// Query the results of the last committed block -pub fn query_results(tendermint_addr: &str) -> Result, Error> {...} -/// Get a properly denominated amount of a token -pub fn denominate_amount(tendermint_addr: &str, amount: u64, token: &str) -> Result {...} -``` -Each of these functions returns a Result type, which can be used to handle errors. -The `tendermint_addr` parameter is the address of the Namada node to query. For local nodes, this is usually `http://localhost:26657`. - -## Transaction -The transaction module exposes various modules (objects) to construct transactions. Each object implements the `::new()` method to create a new instance of the object. - -```rust -pub mod account; // contains functions to create transactions for account module -pub mod bridge; // contains functions to create transactions for bridge module -pub mod governance; // contains functions to create transactions for governance module -pub mod ibc; // contains functions to create transactions for ibc module -pub mod pgf; // contains functions to create transactions for pgf module -pub mod pos; // contains functions to create transactions for pos module -pub mod transfer; // contains functions to create transactions for transfer module -``` +The functions exposed by each of these modules (excluding `namada_sdk`) are described in the following sections. + +- [Reading](./usage/reading.mdx) +- [Transaction](./usage/transaction.mdx) +- [Writing](./usage/writing.mdx) -Using these modules is given in more detail under the [examples section](./examples.mdx). -## Writing -The writing module exposes the broadcast function to send transactions to a Namada node. -```rust -pub fn broadcast_tx(tendermint_addr: &str, tx: Tx) -> Result {...} -``` -The Tx object can be retrieved from the transaction module by calling the `::payload()` method on the transaction object. diff --git a/packages/docs/pages/integrating-with-namada/light-sdk/usage/reading.mdx b/packages/docs/pages/integrating-with-namada/light-sdk/usage/reading.mdx new file mode 100644 index 00000000..0c03a218 --- /dev/null +++ b/packages/docs/pages/integrating-with-namada/light-sdk/usage/reading.mdx @@ -0,0 +1,154 @@ +## Reading + +The reading module exposes the following functions: + +```rust +pub fn query_native_token(tendermint_addr: &str) -> Result{...} +/// Query the last committed block, if any. +pub fn query_block(tendermint_addr: &str) -> Result, Error>{...} +/// Query the results of the last committed block +pub fn query_results(tendermint_addr: &str) -> Result, Error> {...} +/// Get a properly denominated amount of a token +pub fn denominate_amount(tendermint_addr: &str, amount: u64, token: &str) -> Result {...} +``` +Each of these functions returns a Result type, which can be used to handle errors. +The `tendermint_addr` parameter is the address of the Namada node to query. For local nodes, this is usually `http://localhost:26657`. + +It also exposes the following modules that contain their own functions within them: + +```rust +pub mod account; +pub mod governance; +pub mod pgf; +pub mod pos; +pub mod tx; +``` + +### Account +The account module exposes the following functions: + +```rust + +// Query token amount of owner +pub fn get_token_balance(tendermint_addr: &str, token: &Address, owner: &Address) -> Result {...} + +// Check if the address exists on chain +pub fn known_address(tendermint_addr: &str, address: &Address) -> Result {...} + +// Query the account substorage space of an address +pub fn get_account_info(tendermint_addr: &str, owner: &Address) -> Result, Error> {...} + +// Query if the public_key is revealed +pub fn is_public_key_revealed(tendermint_addr: &str, owner: &Address) -> Result {...} + +// Query an account substorage at a specific index +pub fn get_public_key_at(tendermint_addr: &str, owner: &Address, index: u8) -> Result, Error> {...} +``` + +### Governance + +```rust + +// Query proposal by Id +pub fn query_proposal_by_id( tendermint_addr: &str, proposal_id: u64,) -> Result, Error> {...} + +// Get the givernance parameters +pub fn query_governance_parameters(tendermint_addr: &str,) -> Result {...} + +// Get the givernance parameters +pub fn query_proposal_votes(tendermint_addr: &str, proposal_id: u64,) -> Result, Error> {...} +``` + +### Pgf + +```rust +// Check if the given address is a pgf steward. +pub fn is_steward(tendermint_addr: &str,address: &Address,) -> Result {...} +``` + +### Pos + +```rust +// Query the epoch of the last committed block +pub fn query_epoch(tendermint_addr: &str) -> Result {...} + +// Query the epoch of the given block height, if it exists. +pub fn query_epoch_at_height(tendermint_addr: &str, height: BlockHeight) -> Result, Error> {...} + +// Check if the given address is a known validator +pub fn is_validator(tendermint_addr: &str, address: &Address) -> Result {...} + +// Check if a given address is a known delegator +pub fn is_delegator(tendermint_addr: &str, address: &Address) -> Result {...} + +// Check if a given address is a known delegator at the given epoch +pub fn is_delegator_at(tendermint_addr: &str, address: &Address, epoch: Epoch) -> Result {...} + +// Get the set of consensus keys registered in the network +pub fn get_consensus_keys(tendermint_addr: &str) -> Result, Error> {...} + +// Get the PoS parameters +pub fn get_pos_params(tendermint_addr: &str) -> Result {...} + +// Get all validators in the given epoch +pub fn get_all_validators(tendermint_addr: &str, epoch: Epoch) -> Result, Error> {...} + +// Get the total staked tokens in the given epoch +pub fn get_total_staked_tokens(tendermint_addr: &str, epoch: Epoch) -> Result {...} + +// Get the given validator's stake at the given epoch +pub fn get_validator_stake(tendermint_addr: &str, epoch: Epoch, validator: &Address) -> Result {...} + +// Query and return a validator's state +pub fn get_validator_state(tendermint_addr: &str, validator: &Address, epoch: Option) -> Result, Error> {...} + +// Get the delegator's delegation +pub fn get_delegators_delegation(tendermint_addr: &str, address: &Address) -> Result, Error> {...} + +// Get the delegator's delegation at some epoch +pub fn get_delegators_delegation_at(tendermint_addr: &str, address: &Address, epoch: Epoch) -> Result, Error> {...} + +// Query and return validator's commission rate and max commission rate change per epoch +pub fn query_commission_rate(tendermint_addr: &str, validator: &Address, epoch: Option) -> Result, Error> {...} + +// Query and return validator's metadata, including the commission rate and max commission rate change +pub fn query_metadata(tendermint_addr: &str, validator: &Address, epoch: Option) -> Result<(Option, Option), Error> {...} + +// Query and return the incoming redelegation epoch for a given pair of source validator and delegator, if there is any +pub fn query_incoming_redelegations(tendermint_addr: &str, src_validator: &Address, delegator: &Address) -> Result, Error> {...} + +// Query a validator's bonds for a given epoch +pub fn query_bond(tendermint_addr: &str, source: &Address, validator: &Address, epoch: Option) -> Result {...} + +// Query withdrawable tokens in a validator account for a given epoch +pub fn query_withdrawable_tokens(tendermint_addr: &str, bond_source: &Address, validator: &Address, epoch: Option) -> Result {...} + +// Query all unbonds for a validator, applying slashes +pub fn query_unbond_with_slashing(tendermint_addr: &str, source: &Address, validator: &Address) -> Result, Error> {...} + +// Get the bond amount at the given epoch +pub fn get_bond_amount_at(tendermint_addr: &str, delegator: &Address, validator: &Address, epoch: Epoch) -> Result {...} + +// Get bonds and unbonds with all details (slashes and rewards, if any) grouped by their bond IDs +pub fn bonds_and_unbonds(tendermint_addr: &str, source: &Option
, validator: &Option
) -> Result {...} + +// Get bonds and unbonds with all details (slashes and rewards, if any) grouped by their bond IDs, enriched with extra information calculated from the data +pub fn enriched_bonds_and_unbonds(tendermint_addr: &str, current_epoch: Epoch, source: &Option
, validator: &Option
) -> Result {...} +``` + +### Tx + +```rust +/// Call the corresponding `tx_event_query` RPC method, to fetch +/// the current status of a transation. +pub fn query_tx_events(tendermint_addr: &str, tx_hash: &str,) -> Result, Error> {...} + +/// Dry run a transaction +pub fn dry_run_tx(tendermint_addr: &str, tx_bytes: Vec) -> Result {...} + +/// Lookup the full response accompanying the specified transaction event +pub fn query_tx_response(tendermint_addr: &str, tx_hash: &str) -> Result {...} + +/// Query the status of a given transaction. +pub fn query_tx_status(tendermint_addr: &str, tx_hash: &str) -> Result {...} +``` diff --git a/packages/docs/pages/integrating-with-namada/light-sdk/usage/transactions.mdx b/packages/docs/pages/integrating-with-namada/light-sdk/usage/transactions.mdx new file mode 100644 index 00000000..51dcef93 --- /dev/null +++ b/packages/docs/pages/integrating-with-namada/light-sdk/usage/transactions.mdx @@ -0,0 +1,269 @@ +## Transaction +The transaction module exposes various modules (objects) to construct transactions. Each object implements the `::new()` method to create a new instance of the object. + +```rust +pub mod account; // contains functions to create transactions for account module +pub mod bridge; // contains functions to create transactions for bridge module +pub mod governance; // contains functions to create transactions for governance module +pub mod ibc; // contains functions to create transactions for ibc module +pub mod pgf; // contains functions to create transactions for pgf module +pub mod pos; // contains functions to create transactions for pos module +pub mod transfer; // contains functions to create transactions for transfer module +``` + +### Methods associated with every struct + +Each struct in the transaction module implements the following methods: + +```rust +/// Build a raw transaction from the given parameters +pub fn new(...) -> Self {...} +/// Get the bytes to sign for the given transaction +pub fn get_sign_bytes(&self) -> Vec {...} +/// Attach a signature to the given transaction +pub fn attach_signatures(self, signer: common::PublicKey, signature: common::Signature) -> Self {...} +/// Attach a fee to the given transaction +pub fn attach_fee(self, fee: DenominatedAmount, token: Address, fee_payer: common::PublicKey, epoch: Epoch, gas_limit: GasLimit) -> Self {...} +/// Get the bytes of the fee data to sign +pub fn get_fee_sig_bytes(&self) -> Hash {...} +/// Attach a fee signature to the given transaction +pub fn attach_fee_signature(self, signer: common::PublicKey, signature: common::Signature) -> Self {...} +/// Generates the protobuf encoding of this transaction +pub fn to_bytes(&self) -> Vec {...} +/// Gets the inner transaction without the domain wrapper +pub fn payload(self) -> Tx {...} +/// Validate this wrapper transaction +pub fn validate_tx(&self) -> Result, TxError> {...} +``` + +Using these modules is given in more detail under the [examples section](./examples.mdx). Below we describe the instantiating of each struct associated with the respective module. + +### Account + +```rust +use namada_sdk::key::common; +use namada_sdk::hash::Hash; +use super::GlobalArgs; +pub struct InitAccount(Tx); +impl InitAccount { + pub fn new( + public_keys: Vec, + vp_code_hash: Hash, + threshold: u8, + args: GlobalArgs, + ) -> Self {...} +} +``` + +A public key can be constructed from a string using the `::from_str()` method. The `vp_code_hash` is a hash that is found under the `wasm` folder. + +### Bridge + +```rust +pub use namada_sdk::eth_bridge_pool::{GasFee, TransferToEthereum}; +pub struct BridgeTransfer(Tx); +impl BridgeTransfer { + pub fn new( + transfer: TransferToEthereum, + gas_fee: GasFee, + args: GlobalArgs, + ) -> Self {...} +} +``` + +### Governance + +```rust +pub struct InitProposal(Tx); + +impl InitProposal { + /// Build a raw InitProposal transaction from the given parameters + #[allow(clippy::too_many_arguments)] + pub fn new( + id: u64, + content: Hash, + author: Address, + r#type: ProposalType, + voting_start_epoch: Epoch, + voting_end_epoch: Epoch, + grace_epoch: Epoch, + args: GlobalArgs, + ) -> Self {...} +} +pub struct VoteProposal(Tx); + +impl VoteProposal { + /// Build a raw VoteProposal transaction from the given parameters + pub fn new( + id: u64, + vote: ProposalVote, + voter: Address, + delegations: Vec
, + args: GlobalArgs, + ) -> Self {...} +} +``` + +### IBC + +```rust +pub struct IbcTransfer(Tx); + +impl IbcTransfer { + /// Build a raw IbcTransfer transaction from the given parameters + pub fn new( + packet_data: MsgTransfer, + GlobalArgs { + expiration, + code_hash, + chain_id, + }: GlobalArgs, + ) -> Self {...} +} +``` + +### PGF + +```rust +pub struct ResignSteward(Tx); + +impl ResignSteward { + /// Build a raw ResignSteward transaction from the given parameters + pub fn new(steward: Address, args: GlobalArgs) -> Self {...} +} +pub struct UpdateStewardCommission(Tx); + +impl UpdateStewardCommission { + /// Build a raw UpdateStewardCommission transaction from the given + /// parameters + pub fn new( + steward: Address, + commission: HashMap, + args: GlobalArgs, + ) -> Self {...} +} +``` + +### POS + +```rust +pub struct Bond(Tx); +impl Bond { + /// Build a raw Bond transaction from the given parameters + pub fn new( + validator: Address, + amount: token::Amount, + source: Option
, + args: GlobalArgs, + ) -> Self {...} +} +pub struct Unbond(Tx); +impl Unbond { + /// Build a raw Unbond transaction from the given parameters + pub fn new( + validator: Address, + amount: token::Amount, + source: Option
, + args: GlobalArgs, + ) -> Self {...} +} + +pub struct BecomeValidator(Tx); +impl BecomeValidator { + /// Build a raw Init validator transaction from the given parameters + #[allow(clippy::too_many_arguments)] + pub fn new( + address: Address, + consensus_key: common::PublicKey, + eth_cold_key: secp256k1::PublicKey, + eth_hot_key: secp256k1::PublicKey, + protocol_key: common::PublicKey, + commission_rate: Dec, + max_commission_rate_change: Dec, + email: String, + description: Option, + website: Option, + discord_handle: Option, + avatar: Option, + args: GlobalArgs, + ) -> Self {...} +} + +pub struct UnjailValidator(Tx); +impl UnjailValidator { + /// Build a raw Unjail validator transaction from the given parameters + pub fn new(address: Address, args: GlobalArgs) -> Self {...} +} +pub struct DeactivateValidator(Tx); +impl DeactivateValidator { + /// Build a raw DeactivateValidator transaction from the given parameters + pub fn new(address: Address, args: GlobalArgs) -> Self {...} +} +pub struct ReactivateValidator(Tx); +impl ReactivateValidator { + /// Build a raw ReactivateValidator transaction from the given parameters + pub fn new(address: Address, args: GlobalArgs) -> Self {...} +} + +pub struct ClaimRewards(Tx); +impl ClaimRewards { + /// Build a raw ClaimRewards transaction from the given parameters + pub fn new( + validator: Address, + source: Option
, + args: GlobalArgs, + ) -> Self {...} +} + +pub struct ChangeMetaData(Tx); +impl ChangeMetaData { + /// Build a raw ChangeMetadata transaction from the given parameters + #[allow(clippy::too_many_arguments)] + pub fn new( + validator: Address, + email: Option, + description: Option, + website: Option, + discord_handle: Option, + avatar: Option, + commission_rate: Option, + args: GlobalArgs, + ) -> Self {...} +} + +pub struct ChangeConsensusKey(Tx); +impl ChangeConsensusKey { + /// Build a raw ChangeConsensusKey transaction from the given parameters + pub fn new( + validator: Address, + consensus_key: common::PublicKey, + args: GlobalArgs, + ) -> Self {...} +} +pub struct ChangeCommission(Tx); +impl ChangeCommission { + /// Build a raw ChangeCommission transaction from the given parameters + pub fn new(validator: Address, new_rate: Dec, args: GlobalArgs) -> Self {...} +} +pub struct Withdraw(Tx); +impl Withdraw { + /// Build a raw Withdraw transaction from the given parameters + pub fn new( + validator: Address, + source: Option
, + args: GlobalArgs, + ) -> Self {...} +} + +pub struct Redelegate(Tx); +impl Redelegate { + /// Build a raw Redelegate transaction from the given parameters + pub fn new( + src_validator: Address, + dest_validator: Address, + owner: Address, + amount: Amount, + args: GlobalArgs, + ) -> Self {...} +} +``` diff --git a/packages/docs/pages/integrating-with-namada/light-sdk/usage/writing.mdx b/packages/docs/pages/integrating-with-namada/light-sdk/usage/writing.mdx new file mode 100644 index 00000000..aa6bcc87 --- /dev/null +++ b/packages/docs/pages/integrating-with-namada/light-sdk/usage/writing.mdx @@ -0,0 +1,8 @@ +## Writing + +The writing module exposes the broadcast function to send transactions to a Namada node. + +```rust +pub fn broadcast_tx(tendermint_addr: &str, tx: Tx) -> Result {...} +``` +The Tx object can be retrieved from the transaction module by calling the `::payload()` method on the transaction object. See [transaction](./transactions.mdx) for more details. \ No newline at end of file From 77b04c061c0b6c451f5f4500065ff257a0bc259b Mon Sep 17 00:00:00 2001 From: bengtlofgren Date: Sun, 3 Mar 2024 16:24:26 +0000 Subject: [PATCH 16/94] broken links fix --- packages/docs/pages/integrating-with-namada/light-sdk.mdx | 6 +++--- .../docs/pages/integrating-with-namada/light-sdk/_meta.json | 5 +++++ .../integrating-with-namada/light-sdk/usage/_meta.json | 5 +++++ 3 files changed, 13 insertions(+), 3 deletions(-) create mode 100644 packages/docs/pages/integrating-with-namada/light-sdk/_meta.json create mode 100644 packages/docs/pages/integrating-with-namada/light-sdk/usage/_meta.json diff --git a/packages/docs/pages/integrating-with-namada/light-sdk.mdx b/packages/docs/pages/integrating-with-namada/light-sdk.mdx index 62059a90..dbfd8230 100644 --- a/packages/docs/pages/integrating-with-namada/light-sdk.mdx +++ b/packages/docs/pages/integrating-with-namada/light-sdk.mdx @@ -9,6 +9,6 @@ This documentation aims to provide that knowledge. ## Sections -- [Setup](./namada-light-sdk/setup.mdx) -- [Usage](./namada-light-sdk/usage.mdx) -- [Examples](./namada-light-sdk/examples.mdx) \ No newline at end of file +- [Setup](./light-sdk/setup.mdx) +- [Usage](./light-sdk/usage.mdx) +- [Examples](./light-sdk/examples.mdx) \ No newline at end of file diff --git a/packages/docs/pages/integrating-with-namada/light-sdk/_meta.json b/packages/docs/pages/integrating-with-namada/light-sdk/_meta.json new file mode 100644 index 00000000..223627fc --- /dev/null +++ b/packages/docs/pages/integrating-with-namada/light-sdk/_meta.json @@ -0,0 +1,5 @@ +{ + "setup": "Setup", + "usage": "Usage", + "examples": "Examples" +} \ No newline at end of file diff --git a/packages/docs/pages/integrating-with-namada/light-sdk/usage/_meta.json b/packages/docs/pages/integrating-with-namada/light-sdk/usage/_meta.json new file mode 100644 index 00000000..6b37dd9b --- /dev/null +++ b/packages/docs/pages/integrating-with-namada/light-sdk/usage/_meta.json @@ -0,0 +1,5 @@ +{ + "reading": "Reading", + "transactions": "Transactions", + "writing": "Writing" +} \ No newline at end of file From 057fbc3397fd1bc0ac8889748a6f3b56e3156691 Mon Sep 17 00:00:00 2001 From: bengtlofgren Date: Mon, 4 Mar 2024 14:01:58 +0000 Subject: [PATCH 17/94] example needs to be improved: --- .../integrating-with-namada/light-sdk/examples.mdx | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/packages/docs/pages/integrating-with-namada/light-sdk/examples.mdx b/packages/docs/pages/integrating-with-namada/light-sdk/examples.mdx index 6161d423..733e6bc3 100644 --- a/packages/docs/pages/integrating-with-namada/light-sdk/examples.mdx +++ b/packages/docs/pages/integrating-with-namada/light-sdk/examples.mdx @@ -16,6 +16,7 @@ let source_address = namada_light_sdk::namada_sdk::address::Address::from_str("t let target_address = namada_light_sdk::namada_sdk::address::Address::from_str("tnam1v4ehgw36xq6ngs3ng5crvdpngg6yvsecx4znjdfegyurgwzzx4pyywfexuuyys69gc6rzdfnryrntx").unwrap(); // replace with a valid target address let token_address = namada_light_sdk::reading::blocking::query_native_token(tendermint_addr).unwrap(); let amount = namada_light_sdk::namada_sdk::token::DenominatedAmount::from_str("10000").unwrap(); +// Construct the raw transaction struct let transfer = Transfer::new( source_address, target_address, @@ -25,6 +26,15 @@ let transfer = Transfer::new( None, global_args ); +// In order to broadcast the transaction, it must be signed. This is difficult at the moment and more docs will be provided soon. +// For now, the wallet must be created and the tx args may be left empty. The signing data and sign function must be provided, along with the user data. +let signature = namada_light_sdk::namada_sdk::signing::sign_tx(wallet, args, tx, signing_data, sign, user_data) +transfer = transfer.attach_signatures(signer, signature); +transfer = transfer.attach_fee(fee, denominated_amount, fee_payer, epoch, gas_limit); +transfer = transfer.attach_fee_signature(signer, signature); + +// Once signed and the fee_payer and signature is added, the payload can be retrieved and broadcasted let transfer_tx = transfer.payload() +let response = namada_light_sdk::writing::blocking::broadcast_tx(tendermint_addr, transfer_tx).unwrap(); ``` From ef45918fb8fd401816ec2b19e628e9e11b844472 Mon Sep 17 00:00:00 2001 From: bengtlofgren Date: Mon, 4 Mar 2024 14:05:55 +0000 Subject: [PATCH 18/94] fixed links --- packages/docs/pages/integrating-with-namada/light-sdk/usage.mdx | 2 +- .../integrating-with-namada/light-sdk/usage/transactions.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/docs/pages/integrating-with-namada/light-sdk/usage.mdx b/packages/docs/pages/integrating-with-namada/light-sdk/usage.mdx index 2733a263..17b5577e 100644 --- a/packages/docs/pages/integrating-with-namada/light-sdk/usage.mdx +++ b/packages/docs/pages/integrating-with-namada/light-sdk/usage.mdx @@ -14,7 +14,7 @@ pub use namada_sdk; // exposes the namada_sdk module for low level interactions The functions exposed by each of these modules (excluding `namada_sdk`) are described in the following sections. - [Reading](./usage/reading.mdx) -- [Transaction](./usage/transaction.mdx) +- [Transaction](./usage/transactions.mdx) - [Writing](./usage/writing.mdx) diff --git a/packages/docs/pages/integrating-with-namada/light-sdk/usage/transactions.mdx b/packages/docs/pages/integrating-with-namada/light-sdk/usage/transactions.mdx index 51dcef93..0ecc2a81 100644 --- a/packages/docs/pages/integrating-with-namada/light-sdk/usage/transactions.mdx +++ b/packages/docs/pages/integrating-with-namada/light-sdk/usage/transactions.mdx @@ -36,7 +36,7 @@ pub fn payload(self) -> Tx {...} pub fn validate_tx(&self) -> Result, TxError> {...} ``` -Using these modules is given in more detail under the [examples section](./examples.mdx). Below we describe the instantiating of each struct associated with the respective module. +Using these modules is given in more detail under the [examples section](../examples.mdx). Below we describe the instantiating of each struct associated with the respective module. ### Account From 55f46fa0906b7ebafe1170437ef3e4ffc9f3b4e4 Mon Sep 17 00:00:00 2001 From: bengtlofgren Date: Mon, 4 Mar 2024 14:42:18 +0000 Subject: [PATCH 19/94] signatures for light sdk --- .../light-sdk/examples.mdx | 21 +++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) diff --git a/packages/docs/pages/integrating-with-namada/light-sdk/examples.mdx b/packages/docs/pages/integrating-with-namada/light-sdk/examples.mdx index 733e6bc3..da32e757 100644 --- a/packages/docs/pages/integrating-with-namada/light-sdk/examples.mdx +++ b/packages/docs/pages/integrating-with-namada/light-sdk/examples.mdx @@ -27,10 +27,23 @@ let transfer = Transfer::new( global_args ); // In order to broadcast the transaction, it must be signed. This is difficult at the moment and more docs will be provided soon. -// For now, the wallet must be created and the tx args may be left empty. The signing data and sign function must be provided, along with the user data. -let signature = namada_light_sdk::namada_sdk::signing::sign_tx(wallet, args, tx, signing_data, sign, user_data) -transfer = transfer.attach_signatures(signer, signature); -transfer = transfer.attach_fee(fee, denominated_amount, fee_payer, epoch, gas_limit); +// For now, the below code can be replicated. +let targets = vec![transfer.payload().raw_header_hash()]; +let mut secret_keys = BTreeMap::new(); +secret_keys.insert(0, secret_key); + +let signer_pub_key = secret_key.to_public(); +let signer_address = namada_light_sdk::namada_sdk::address::Address::from(signer_pub_key); + +let signature = namada_light_sdk::namada_sdk::tx::Signature::new(targets, secret_keys, Some(signer_address)); + +transfer = transfer.attach_signatures(signer_pub_key, signature); +let fee = namada_light_sdk::namada_sdk::token::DenominatedAmount::from_str("10").unwrap(); +let gas_limit = namada_light_sdk::namada_sdk::tx::data::GasLimit::from_str("20000").unwrap(); + +transfer = transfer.attach_fee(fee, amount, signer_pub_key, epoch, gas_limit); +let fee_targets = vec![transfer.payload().sechashes()]; +let fee_signature = namada_light_sdk::namada_sdk::tx::Signature::new(targets, secret_keys, Some(signer_address)); transfer = transfer.attach_fee_signature(signer, signature); // Once signed and the fee_payer and signature is added, the payload can be retrieved and broadcasted From 8f9f271a61e458661ff39cebb62846a4f154763a Mon Sep 17 00:00:00 2001 From: bengtlofgren Date: Mon, 4 Mar 2024 15:03:36 +0000 Subject: [PATCH 20/94] light sdk docs clone needed --- .../light-sdk/examples.mdx | 24 +++++++++++-------- 1 file changed, 14 insertions(+), 10 deletions(-) diff --git a/packages/docs/pages/integrating-with-namada/light-sdk/examples.mdx b/packages/docs/pages/integrating-with-namada/light-sdk/examples.mdx index da32e757..d88fcbb4 100644 --- a/packages/docs/pages/integrating-with-namada/light-sdk/examples.mdx +++ b/packages/docs/pages/integrating-with-namada/light-sdk/examples.mdx @@ -28,23 +28,27 @@ let transfer = Transfer::new( ); // In order to broadcast the transaction, it must be signed. This is difficult at the moment and more docs will be provided soon. // For now, the below code can be replicated. -let targets = vec![transfer.payload().raw_header_hash()]; +let targets = vec![transfer.clone().payload().raw_header_hash()]; let mut secret_keys = BTreeMap::new(); -secret_keys.insert(0, secret_key); +secret_keys.insert(0, secret_key.clone()); -let signer_pub_key = secret_key.to_public(); -let signer_address = namada_light_sdk::namada_sdk::address::Address::from(signer_pub_key); +let signer_pub_key = secret_key.clone().to_public(); -let signature = namada_light_sdk::namada_sdk::tx::Signature::new(targets, secret_keys, Some(signer_address)); +let signature_tx = namada_light_sdk::namada_sdk::tx::Signature::new(targets, secret_keys.clone(), None); +let signature = signature_tx.signatures.get(&0u8).unwrap().to_owned(); -transfer = transfer.attach_signatures(signer_pub_key, signature); +transfer = transfer.attach_signatures(signer_pub_key.clone(), signature.clone()); let fee = namada_light_sdk::namada_sdk::token::DenominatedAmount::from_str("10").unwrap(); let gas_limit = namada_light_sdk::namada_sdk::tx::data::GasLimit::from_str("20000").unwrap(); -transfer = transfer.attach_fee(fee, amount, signer_pub_key, epoch, gas_limit); -let fee_targets = vec![transfer.payload().sechashes()]; -let fee_signature = namada_light_sdk::namada_sdk::tx::Signature::new(targets, secret_keys, Some(signer_address)); -transfer = transfer.attach_fee_signature(signer, signature); +let epoch = namada_light_sdk::namada_sdk::proof_of_stake::Epoch::from_str("0").unwrap(); + +transfer = transfer.attach_fee(fee, token_address.clone(), signer_pub_key.clone(), epoch, gas_limit); +let fee_targets = vec![transfer.clone().payload().sechashes()]; +let fee_signature_tx = namada_light_sdk::namada_sdk::tx::Signature::new(targets, secret_keys.clone(), None); +let fee_signature = fee_signature_tx.signatures.get(&0u8).unwrap().to_owned(); + +transfer = transfer.attach_fee_signature(signer_pub_key.clone(), signature.clone()); // Once signed and the fee_payer and signature is added, the payload can be retrieved and broadcasted let transfer_tx = transfer.payload() From ca7670e936009e2ca53676cb9121d515c15cf4d4 Mon Sep 17 00:00:00 2001 From: bengtlofgren Date: Mon, 4 Mar 2024 16:34:33 +0000 Subject: [PATCH 21/94] some initial val docs additions --- .../pages/operators/validators/staking.mdx | 15 ++++++++++++ .../operators/validators/validator-setup.mdx | 15 ++++++++++++ packages/docs/pages/users/delegators.mdx | 24 ++++++++++++++++++- 3 files changed, 53 insertions(+), 1 deletion(-) diff --git a/packages/docs/pages/operators/validators/staking.mdx b/packages/docs/pages/operators/validators/staking.mdx index 1924a0bb..1c12f2f8 100644 --- a/packages/docs/pages/operators/validators/staking.mdx +++ b/packages/docs/pages/operators/validators/staking.mdx @@ -110,4 +110,19 @@ namada client withdraw \ Upon success, the withdrawn tokens will be credited back `aliace`'s account and debited from the PoS system. +### Claiming rewards +Validators and delegators that have bonded tokens accrue protocol rewards (for not misbehaving) and transaction fees. These rewards need to be claimed. + +```shell copy +namada client claim-rewards \ + --validator validator-1 +``` + +These rewards will immediately be credited to the validtor's account. + +Additionally, you can query the pending reward tokens without claiming by running: + +```bash copy +namadac rewards --validator +``` diff --git a/packages/docs/pages/operators/validators/validator-setup.mdx b/packages/docs/pages/operators/validators/validator-setup.mdx index 169f0e7a..0f1f284b 100644 --- a/packages/docs/pages/operators/validators/validator-setup.mdx +++ b/packages/docs/pages/operators/validators/validator-setup.mdx @@ -63,6 +63,10 @@ namada client become-validator \ --email $EMAIL ``` + +The commission rate is a parameter that determines the percentage of the rewards that the validator will take from the delegators. The `max-commission-rate-change` is the maximum change in the commission rate that can occur in one epoch. + + The validator account will now have the same alias as the established account. When initialising a validator account, it is also mandatory to specify both the `commission-rate` charged by the validator for delegation rewards (in decimal format) as well as the `maximum-commission-rate-change` per epoch in the `commission-rate`. Both are expressed as a decimal between 0 and 1. The standard for mainnet will be set by social consensus, but for testnets, the standard has been `0.01` and `0.05`, respectively. @@ -100,3 +104,14 @@ namada client balance --owner my-validator --token NAM That is, the balance of your account's address is a regular liquid balance that you can transfer using your validator account key, depending on the rules of the validator account's validity predicate. The default validity predicate allows you to transfer it with a signed transaction and/or stake it in the PoS system. Therefore, in order to increase the voting power of your validator, you need to accrue [some stake](./staking.mdx). +## Querying a validator's tendermint address + +If the validator account has been set up correctly and has bonded stake, it will be possible to query it using the `find-validator` command: + +```shell copy +namada client find-validator --validator +``` + + +It is important to note that the validator **address** is required, not the alias. The address can be found using the wallet command `namadaw list --addr | grep "your-validator-alias".` + diff --git a/packages/docs/pages/users/delegators.mdx b/packages/docs/pages/users/delegators.mdx index 09a30bc9..0202687a 100644 --- a/packages/docs/pages/users/delegators.mdx +++ b/packages/docs/pages/users/delegators.mdx @@ -20,7 +20,21 @@ First, you may want to list some available validators you can stake to: namadac bonded-stake ``` -Once you've found the address of your favourite validator, you can bond to them with the following command: +If you have a specific tenderimnt key of a validator but do not know the address, you can use the following command to find the address: + +```bash copy +namadac find-validator --tendermint-key # Similarly you can find the tendermint key from the address by providing the argument --validator instead +``` + + +Before bonding to a validator, it is important to know their commision rate. This is the percentage of the block rewards that the validator will take as a fee for their services. You can find this information by running the following command: +```bash copy +namadac commission-rate --validator +``` +Typically, the commission rate is between 0% and 5%. + + +Once you've found the address of your favorite validator, you can bond to them with the following command: ```bash copy namadac bond --source --validator --amount @@ -47,6 +61,14 @@ The pipeline length of the chain and other important proof-of-stake parameters c namadac query-protocol-parameters ``` +## Querying delegations + +It is possible to query processed delegations through the client + +```shell copy +namadac delegations --owner +``` + ## Unbonding Unbonding is the process of removing your bonded NAM from a validator, and this must be done before attempting to withdraw your previously bonded tokens. From 1eec64f08728f4169c2320fbecec96c90854d62a Mon Sep 17 00:00:00 2001 From: bengtlofgren Date: Tue, 5 Mar 2024 14:47:42 +0000 Subject: [PATCH 22/94] validator docs --- .../pages/operators/validators/_meta.json | 3 +- .../operators/validators/proof-of-stake.mdx | 59 ++------------- .../validators/validator-actions.mdx | 74 +++++++++++++++++++ .../operators/validators/validator-setup.mdx | 2 +- 4 files changed, 84 insertions(+), 54 deletions(-) create mode 100644 packages/docs/pages/operators/validators/validator-actions.mdx diff --git a/packages/docs/pages/operators/validators/_meta.json b/packages/docs/pages/operators/validators/_meta.json index f521d169..789f0634 100644 --- a/packages/docs/pages/operators/validators/_meta.json +++ b/packages/docs/pages/operators/validators/_meta.json @@ -1,6 +1,7 @@ { + "proof-of-stake": "Cubic proof of stake", "validator-setup": "Validator setup", "staking": "Staking", - "proof-of-stake": "Proof of stake", + "validator-actions": "Validator actions", "jailing": "Jailing" } \ No newline at end of file diff --git a/packages/docs/pages/operators/validators/proof-of-stake.mdx b/packages/docs/pages/operators/validators/proof-of-stake.mdx index cd48cbee..c84eac26 100644 --- a/packages/docs/pages/operators/validators/proof-of-stake.mdx +++ b/packages/docs/pages/operators/validators/proof-of-stake.mdx @@ -1,6 +1,8 @@ import { Callout } from 'nextra-theme-docs' -# Cubic Proof-of-Stake system +# Cubic Slashing on Namada + +Validators on Namada are slashed for misbehavior. Automatic slashing conditions are defined by the CometBFT, but validators can also report misbehavior by other validators. If a validator is deemed to have misbehaved, they are slashed by a certain amount of their stake. The amount of stake slashed, as well as the time required for the slash to take effect (pipeline) is defined by protocol parameters. The Namada Proof of Stake (PoS) system uses the NAM token as the staking token. It features delegation to any number of validators and customizable validator validity predicates. @@ -27,59 +29,12 @@ In order to query the current epoch, the following command can be run: ```shell copy namada client epoch ``` +## Pipeline length -## Slashing - -Validators on Namada are slashed for misbehavior. Automatic slashing conditions are defined by the CometBFT, but validators can also report misbehavior by other validators. If a validator is deemed to have misbehaved, they are slashed by a certain amount of their stake. The amount of stake slashed, as well as the time required for the slash to take effect (pipeline) is defined by protocol parameters. - -## Jailing - -Validators on Namada are jailed for either misbehavior or for being offline for too long. If a number of blocks pass (also defined in the protocol parameters under `liveness_window_check`) in which none have been signed by the validator in question, the validator is jailed. - -When a validator is jailed, they are unable to participate in the consensus protocol. A validator is jailed for at least the pipeline amount of epochs, but must be unjailed manually by the validator. This is done by submitting an `unjail-validator` command. - -```bash -VALIDATOR_ALIAS="" -SIGNING_KEYS="" -namada client unjail-validator --validator $VALIDATOR_ALIAS --signing-keys $SIGNING_KEYS -``` - -If successful, the validator will be unjailed after the pipeline amount of epochs, and is able to participate in the consensus protocol again. - -## Consensus Key Management - -The consensus key is crucial for validators as it is used to sign blocks and participate in the CometBFT consensus protocol. This key ensures that only authorized validators can propose and vote on blocks, contributing to the network's overall security. - -### Changing the Consensus Key -Validators are able to change their consensus key, allowing for enhanced security and key rotation practices. This process is essential for maintaining the security of the validator's operations and protecting against potential compromise. - -To change the consensus key, validators can use the following command: - -```bash -VALIDATOR_ADDRESS="" -SIGNING_KEYS="" -namada client change-consensus-key --validator $VALIDATOR_ADDRESS --signing-keys $SIGNING_KEYS -``` - - -The new consensus key will be recorded in the `wallet.toml` file and is scheduled to become active 2 blocks before the pipeline offset from the epoch at the moment of activation. This timing ensures a smooth transition. It is essential for validators to plan the key rotation accordingly to ensure continuous participation in block validation without interruption. - - -### Generating a New Consensus Key -After the transition period, validators must replace the current `priv_validator_key.json` with the newly generated key. This step is crucial for activating the new consensus key for block signing. - -To generate a new consensus key, use the following command: - -```bash -namadaw convert --alias -``` - -This command will create a new consensus key, which validators should securely store and use to replace the existing `priv_validator_key.json` file. It is critical for validators to perform this step correctly. - -After updating the consensus key, validators can find out their new validator address with the following command: +Because of the nature of cubic slashing, validators are not slashed immediately upon evidence of misbehavior. Instead, the evidence is submitted to the network and the validator is slashed after a certain number of epochs. This is called the pipeline length. The pipeline length is defined by protocol parameters. It is possible to query the current pipeline length with the following command: -```bash -namadaw find --alias +```shell copy +namada query-protocol-parameters ``` diff --git a/packages/docs/pages/operators/validators/validator-actions.mdx b/packages/docs/pages/operators/validators/validator-actions.mdx new file mode 100644 index 00000000..223b4bf1 --- /dev/null +++ b/packages/docs/pages/operators/validators/validator-actions.mdx @@ -0,0 +1,74 @@ +import { Callout } from 'nextra-theme-docs' + +# Validator actions + +## Commission-rate changes + +A validator can change their commission rate through the `change-commission` command: + +```bash copy +namadac change-commission-rate --validator --commission-rate +``` + +The `max-commission-rate-change` is unique to each validator and cannot be changed. + +## Metadata changes + +A validator can change their metadata through the `change-metadata` command: + +```bash copy +namadac change-metadata --validator --description --email --discord-handle --website --avatar +``` +Apart from `--validator`, not all of the fields are required, but at least one of them is. + +## Deactivation and reactivation + +A validator can deactivate their validator (stop validating) through the `deactivate` command: + +```bash copy +namadac deactivate-validator --validator +``` +This means that the validator will no longer participate in the consensus protocol. This becomes active at the end of the current epoch + `pipeline_length`. All bonds and delegations associated with the validator remain in tact. Delegators can still delegate to the validator, but the validator will not be able to participate in consensus until it is reactivated. + +To reactivate a validator, use the `reactivate` command: + +```bash copy +namadac reactivate-validator --validator +``` +This will reactivate the validator at the end of the current epoch + `pipeline_length`. + +## Consensus Key Management + +The consensus key is crucial for validators as it is used to sign blocks and participate in the CometBFT consensus protocol. This key ensures that only authorized validators can propose and vote on blocks, contributing to the network's overall security. + +### Changing the Consensus Key +Validators are able to change their consensus key, allowing for enhanced security and key rotation practices. This process is essential for maintaining the security of the validator's operations and protecting against potential compromise. + +To change the consensus key, validators can use the following command: + +```bash +VALIDATOR_ADDRESS="" +SIGNING_KEYS="" +namada client change-consensus-key --validator $VALIDATOR_ADDRESS --signing-keys $SIGNING_KEYS +``` + + +The new consensus key will be recorded in the `wallet.toml` file and is scheduled to become active 2 blocks before the pipeline offset from the epoch at the moment of activation. This timing ensures a smooth transition. It is essential for validators to plan the key rotation accordingly to ensure continuous participation in block validation without interruption. + + +### Generating a New Consensus Key +After the transition period, validators must replace the current `priv_validator_key.json` with the newly generated key. This step is crucial for activating the new consensus key for block signing. + +To generate a new consensus key, use the following command: + +```bash +namadaw convert --alias +``` + +This command will create a new consensus key, which validators should securely store and use to replace the existing `priv_validator_key.json` file. It is critical for validators to perform this step correctly. + +After updating the consensus key, validators can find out their new validator address with the following command: + +```bash +namadaw find --alias +``` diff --git a/packages/docs/pages/operators/validators/validator-setup.mdx b/packages/docs/pages/operators/validators/validator-setup.mdx index 0f1f284b..e74c8f6d 100644 --- a/packages/docs/pages/operators/validators/validator-setup.mdx +++ b/packages/docs/pages/operators/validators/validator-setup.mdx @@ -64,7 +64,7 @@ namada client become-validator \ ``` -The commission rate is a parameter that determines the percentage of the rewards that the validator will take from the delegators. The `max-commission-rate-change` is the maximum change in the commission rate that can occur in one epoch. +A validator’s commission rate is the percentage of the rewards that the validator keeps from its delegators. A validator can change its commission rate with a transaction. The `max-commission-rate-change` is the maximum allowable change in a validator’s commission rate from one epoch to the next. This parameter is set uniquely for a given validator upon their creation and cannot be changed once the validator is initialized. The validator account will now have the same alias as the established account. From d4794a1de7eea03c70953f99fe3ef6f7727c0cef Mon Sep 17 00:00:00 2001 From: bengtlofgren Date: Thu, 7 Mar 2024 09:45:44 +0000 Subject: [PATCH 23/94] some validator docs fixed --- packages/docs/pages/operators/validators.mdx | 13 +++++++++++-- .../pages/operators/validators/proof-of-stake.mdx | 8 ++++++++ .../pages/operators/validators/validator-setup.mdx | 8 +++++++- 3 files changed, 26 insertions(+), 3 deletions(-) diff --git a/packages/docs/pages/operators/validators.mdx b/packages/docs/pages/operators/validators.mdx index 82547a08..c48813f8 100644 --- a/packages/docs/pages/operators/validators.mdx +++ b/packages/docs/pages/operators/validators.mdx @@ -17,6 +17,15 @@ In addition, the validator node must meet the [minimum hardware requirements](./ #### Steps -See these steps for [setting up a genesis validator](./validators/validator-setup.mdx). +See these steps for [setting up a genesis validator](./networks/genesis-flow/participants.mdx). The commands will be found under the [pre-genesis validator section](./networks/genesis-flow/participants.mdx#generate-a-pre-genesis-validator-account) -See these steps for [setting up a post-genesis validator](./validators/validator-setup.mdx). \ No newline at end of file +See these steps for [setting up a post-genesis validator](./validators/validator-setup.mdx). + + +## Outline +The validator docs describe the process and actions available to validators on the Namada blockchain. The following is a list of the topics covered in the validator docs: +- [Cubic proof of stake overview](./validators/proof-of-stake.mdx) +- [Validator setup](./validators/validator-setup.mdx) +- [Staking](./validators/staking.mdx) +- [Validator actions](./validators/validator-actions.mdx) +- [Jailing](./validators/jailing.mdx) \ No newline at end of file diff --git a/packages/docs/pages/operators/validators/proof-of-stake.mdx b/packages/docs/pages/operators/validators/proof-of-stake.mdx index c84eac26..b22e5291 100644 --- a/packages/docs/pages/operators/validators/proof-of-stake.mdx +++ b/packages/docs/pages/operators/validators/proof-of-stake.mdx @@ -37,4 +37,12 @@ Because of the nature of cubic slashing, validators are not slashed immediately namada query-protocol-parameters ``` +## Active Set + +The parameters also define a `max-validator-slots` parameter. This parameter defines the maximum number of validators that can be actively participating in consensus at any given time. The active set is the set of validators that are currently active. The active set is updated at the end of each epoch. The active set can be queried with the following command: + +```shell copy +namadac bonded-stake +``` + diff --git a/packages/docs/pages/operators/validators/validator-setup.mdx b/packages/docs/pages/operators/validators/validator-setup.mdx index e74c8f6d..37a801b4 100644 --- a/packages/docs/pages/operators/validators/validator-setup.mdx +++ b/packages/docs/pages/operators/validators/validator-setup.mdx @@ -104,7 +104,13 @@ namada client balance --owner my-validator --token NAM That is, the balance of your account's address is a regular liquid balance that you can transfer using your validator account key, depending on the rules of the validator account's validity predicate. The default validity predicate allows you to transfer it with a signed transaction and/or stake it in the PoS system. Therefore, in order to increase the voting power of your validator, you need to accrue [some stake](./staking.mdx). -## Querying a validator's tendermint address +The final thing that needs to be done is to bond some stake to the validator account. This can be done using the `bond` command: + +```shell copy +namadac bond --amount --validator +``` + +### Querying a validator's tendermint address If the validator account has been set up correctly and has bonded stake, it will be possible to query it using the `find-validator` command: From 6a1f72a6be36b90c87f7aa9b9ced994c635579ad Mon Sep 17 00:00:00 2001 From: bengtlofgren Date: Thu, 7 Mar 2024 16:25:14 +0000 Subject: [PATCH 24/94] protocol parameters added --- packages/docs/pages/index.mdx | 2 +- .../pages/introduction/protocol-intro.mdx | 135 ++++++++++++++++++ packages/docs/pages/operators/validators.mdx | 1 - .../operators/validators/proof-of-stake.mdx | 48 ------- 4 files changed, 136 insertions(+), 50 deletions(-) create mode 100644 packages/docs/pages/introduction/protocol-intro.mdx delete mode 100644 packages/docs/pages/operators/validators/proof-of-stake.mdx diff --git a/packages/docs/pages/index.mdx b/packages/docs/pages/index.mdx index 8d113724..fada0799 100644 --- a/packages/docs/pages/index.mdx +++ b/packages/docs/pages/index.mdx @@ -15,7 +15,7 @@ Namada's cryptographical features give users asset-agnostic, interchain privacy, ## Overview of features -- [Proof-of-Stake](./operators/validators/proof-of-stake.mdx) with [governance](./users/governance.mdx) to secure and evolve Namada +- [Proof-of-Stake](./introduction/protocol-intro.mdx) with [governance](./users/governance.mdx) to secure and evolve Namada - Fast-finality BFT with 4-second blocks - Trust-minimized 2-way Ethereum bridge - IBC connections to chains that already speak IBC (all Cosmos chains) diff --git a/packages/docs/pages/introduction/protocol-intro.mdx b/packages/docs/pages/introduction/protocol-intro.mdx new file mode 100644 index 00000000..dba4e65a --- /dev/null +++ b/packages/docs/pages/introduction/protocol-intro.mdx @@ -0,0 +1,135 @@ +import { Callout } from 'nextra-theme-docs' +import Expandable from '../../components/Expandable' + +# Introduction to the Namada Protocol + +The Namada protocol is a proof-of-stake layer 1 blockchain protocol. State transitions are governed by validity predicates, and rules of the protocol are defined by protocol parameters. The following section describes key parameters and concepts, and how to query them. + +## Epochs + +The system relies on the concept of epochs. An epoch is a range of consecutive blocks identified by consecutive natural numbers. Each epoch lasts a minimum duration and includes a minimum number of blocks since the beginning of the last epoch. These are defined by protocol parameters. + +To query the current epoch, the following command can be run: + +```shell copy +namadac query-protocol-parameters +``` + +In order to query the current epoch, the following command can be run: + +```shell copy +namada client epoch +``` +## Protocol parameters + +All of the current protocol parameters can be queried using the following command: +```shell copy +namada query-protocol-parameters +``` + +This will display the list of protocol parameters. +E.g: + + +```text +Governance Parameters + Min. proposal fund: 500.000000 + Max. proposal code size: 600000 + Min. proposal voting period: 3 + Max. proposal period: 27 + Max. proposal content size: 10000 + Min. proposal grace epochs: 6 + +Public Goods Funding Parameters + Pgf inflation rate: 0.1 + Steward inflation rate: 0.01 + +Protocol parameters + Min. epoch duration: 1 + Min. number of blocks: 4 + Max. block duration: 30 + VP allowlist: [] + Transactions allowlist: [] + Max block gas: 20000000 + Fee unshielding gas limit: 20000 + Fee unshielding descriptions limit: 15 + Gas cost table: + tnam1qxgfw7myv4dh0qna4hq0xdg6lx77fzl7dcem8h7e: Amount { raw: 1 } +PoS parameters + Pipeline length: 2 + Unbonding length: 3 + Cubic slashing window length: 1 + Max. consensus validator slots: 128 + Validator stake threshold: 1000000 + Duplicate vote minimum slash rate: 0.001 + Light client attack minimum slash rate: 0.001 + Liveness window: 100 blocks + Liveness threshold: 0.9 + Block proposer reward: 0.125 + Block vote reward: 0.1 + Max inflation rate: 0.1 + Target staked ratio: 0.6667 + Inflation kP gain: 0.25 + Inflation kD gain: 0.25 + Votes per raw token: 1 +``` + + + +### Governance parameters + +- Min. proposal fund: The minimum amount of tokens required to submit a proposal. +- Max. proposal code size: The maximum size of the code that can be submitted in a proposal. +- Min. proposal voting period: The minimum duration of the voting period for a proposal. +- Max. proposal period: The maximum duration of the proposal period. +- Max. proposal content size: The maximum number of characters of the content that can be submitted in a proposal. +- Min. proposal grace epochs: The minimum number of epochs that a proposal can be in the grace period. + + +The *grace period* is defined as the epochs **between** the end of the voting period and the `grace epoch` as defined on the proposal. The grace epoch is the final epoch of the grace period. + + +### Public Goods Funding Parameters + +- Pgf inflation rate: The inflation rate for the Public Goods Funding. +- Steward inflation rate: The inflation rate for the Steward. + +### Protocol parameters + +- Min. epoch duration: The minimum number of seconds per epoch. +- Min. number of blocks: The minimum number of blocks per epoch. +- Max. block duration: The maximum number of seconds per block. +- VP allowlist: The list of validity predicates (their wasm hashes) that are "whitelisted" and can be invoked in transactions. +- Transactions allowlist: The list of transactions (their wasm hashes) that are "whitelisted" and can be invoked in transactions. +- Max block gas: The maximum amount of gas that a block can consume. +- Fee unshielding gas limit: The maximum amount of gas that a fee unshielding transaction can consume. +- Fee unshielding descriptions limit: The maximum number of characters that can be included in the description of a fee unshielding transaction. +- Gas cost table: The gas cost table for the different tokens (indicated by address) that can pay for gas. + +### PoS parameters + +- Pipeline length: The number of epochs that a validator must wait before they can unbond their stake. +- Unbonding length: The number of epochs that a validator must wait before they can withdraw their stake after unbonding. +- Cubic slashing window length: The number of epochs between the point of a validator's infraction and the point at which they are slashed. +- Max. consensus validator slots: The maximum number of consensus validator slots. These are sorted by bonded stake. Any validator with a stake below the "validator stake threshold" will not be participating in consensus. + +### Protocol parameters + +- Validator stake threshold: The minimum amount of tokens that a validator must have in order to be eligible for consensus. +- Duplicate vote minimum slash rate: The minimum slashing rate for a duplicate vote. +- Light client attack minimum slash rate: The minimum slashing rate for a light client attack. +- Liveness window: The number of blocks that are considered for the liveness check (a slashable event), counted by number of blocks that a validator signs +- Liveness threshold: The proportion (decimal) of blocks that a validator must sign within the window in order to be considered live. +- Block proposer reward: The reward for the block proposer. +- Block vote reward: The reward for the block voter. +- Max inflation rate: The maximum inflation rate. +- Target staked ratio: The target ratio of the total staked tokens to the total supply. +- Inflation kP gain: The `kp` (proportional) gain for the inflation parameter in the PD controller. +- Inflation kD gain: The `kd` (second order) gain for the inflation parameter. +- Votes per raw token: The number of votes per raw token bonded. + + + + + + diff --git a/packages/docs/pages/operators/validators.mdx b/packages/docs/pages/operators/validators.mdx index c48813f8..2e125c06 100644 --- a/packages/docs/pages/operators/validators.mdx +++ b/packages/docs/pages/operators/validators.mdx @@ -24,7 +24,6 @@ See these steps for [setting up a post-genesis validator](./validators/validator ## Outline The validator docs describe the process and actions available to validators on the Namada blockchain. The following is a list of the topics covered in the validator docs: -- [Cubic proof of stake overview](./validators/proof-of-stake.mdx) - [Validator setup](./validators/validator-setup.mdx) - [Staking](./validators/staking.mdx) - [Validator actions](./validators/validator-actions.mdx) diff --git a/packages/docs/pages/operators/validators/proof-of-stake.mdx b/packages/docs/pages/operators/validators/proof-of-stake.mdx deleted file mode 100644 index b22e5291..00000000 --- a/packages/docs/pages/operators/validators/proof-of-stake.mdx +++ /dev/null @@ -1,48 +0,0 @@ -import { Callout } from 'nextra-theme-docs' - -# Cubic Slashing on Namada - -Validators on Namada are slashed for misbehavior. Automatic slashing conditions are defined by the CometBFT, but validators can also report misbehavior by other validators. If a validator is deemed to have misbehaved, they are slashed by a certain amount of their stake. The amount of stake slashed, as well as the time required for the slash to take effect (pipeline) is defined by protocol parameters. - -The Namada Proof of Stake (PoS) system uses the NAM token as the staking token. It features delegation to any number of validators and customizable validator validity predicates. - -## PoS Validity Predicate - -The PoS system is implemented as an account with the [PoS Validity Predicate](https://github.com/anoma/namada/blob/main/shared/src/ledger/pos/vp.rs) that governs the rules of the system. You can find its address in your wallet: - -```shell copy -namada wallet find --alias PoS -``` - -## Epochs - -The system relies on the concept of epochs. An epoch is a range of consecutive blocks identified by consecutive natural numbers. Each epoch lasts a minimum duration and includes a minimum number of blocks since the beginning of the last epoch. These are defined by protocol parameters. - -To query the current epoch, the following command can be run: - -```shell copy -namadac query-protocol-parameters -``` - -In order to query the current epoch, the following command can be run: - -```shell copy -namada client epoch -``` -## Pipeline length - -Because of the nature of cubic slashing, validators are not slashed immediately upon evidence of misbehavior. Instead, the evidence is submitted to the network and the validator is slashed after a certain number of epochs. This is called the pipeline length. The pipeline length is defined by protocol parameters. It is possible to query the current pipeline length with the following command: - -```shell copy -namada query-protocol-parameters -``` - -## Active Set - -The parameters also define a `max-validator-slots` parameter. This parameter defines the maximum number of validators that can be actively participating in consensus at any given time. The active set is the set of validators that are currently active. The active set is updated at the end of each epoch. The active set can be queried with the following command: - -```shell copy -namadac bonded-stake -``` - - From a92476a69bd9ea6f646216080a9eb2e23ec2b917 Mon Sep 17 00:00:00 2001 From: Zach <56927413+zjcio@users.noreply.github.com> Date: Fri, 8 Mar 2024 15:29:48 +0000 Subject: [PATCH 25/94] Update index.mdx Light updates for narrative consistency --- packages/community/pages/index.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/community/pages/index.mdx b/packages/community/pages/index.mdx index b3361e8a..2244e874 100644 --- a/packages/community/pages/index.mdx +++ b/packages/community/pages/index.mdx @@ -2,8 +2,8 @@ ## What is the Namada Community? -The Namada community is composed of ecosystems, communities, researchers, builders, creators, advocates, users of privacy, and just people – who want to see a future in which decentralized systems can serve as real alternatives to existing financial systems. To achieve this, privacy is paramount. +The Namada community is composed of ecosystems, communities, researchers, builders, creators, advocates, users and everyday people – who want to see a future in which decentralized systems can serve as real alternatives to existing financial systems. To achieve this, protecting users’ personally identifiable information is paramount. -We are brought together by the [Namada Vision](https://forum.namada.net/t/the-namada-mission/275). Together we make privacy as a public good a reality by building open-source tools, operating protocols, teaching people about privacy, using privacy, and funding privacy. +We are brought together by the Namada Vision of restoring the freedom to reveal. Together we make data rights a reality by building open-source tools, operating protocols, teaching people about privacy, using privacy, and funding tools for shielding users’ sensitive data. Do you want to join us? From ffaace685123bc66c5a82fe3f8eba63a2e4ddfd7 Mon Sep 17 00:00:00 2001 From: Zach <56927413+zjcio@users.noreply.github.com> Date: Fri, 8 Mar 2024 15:45:28 +0000 Subject: [PATCH 26/94] Update validators.mdx light edit for narrative consistency --- packages/community/pages/validators.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/community/pages/validators.mdx b/packages/community/pages/validators.mdx index 5f0e7306..4d3357ac 100644 --- a/packages/community/pages/validators.mdx +++ b/packages/community/pages/validators.mdx @@ -1,6 +1,6 @@ # Validators -The development of Namada started in 2022, back then it went by the codename of β€œM1”. After months of development, throughout summer and fall we launched a series of [private testnets](https://github.com/anoma/namada-testnets/tree/main/namada-close-quarters-testnet-1) with the help of a handful of early validators who believed in the vision of bringing asset agnostic privacy. The community at this stage was composed by the core developers at Heliax and [the few validators](https://namada.net/blog/announcing-namada-public-testnets) (7 team members from Heliax and [11 validators](https://github.com/anoma/namada-testnets/tree/main/namada-close-quarters-testnet-5)) who joined and coordinated through the Validator Hangout on Element. The last private testnets ran until December 2022, the protocol version was `v0.11`. +The development of Namada started in 2022, back then it went by the codename of β€œM1”. After months of development, throughout summer and fall we launched a series of [private testnets](https://github.com/anoma/namada-testnets/tree/main/namada-close-quarters-testnet-1) with the help of a handful of early validators who believed in the vision of bringing asset agnostic shielding. The community at this stage was composed by the core developers at Heliax and [the few validators](https://namada.net/blog/announcing-namada-public-testnets) (7 team members from Heliax and [11 validators](https://github.com/anoma/namada-testnets/tree/main/namada-close-quarters-testnet-5)) who joined and coordinated through the Validator Hangout on Element. The last private testnets ran until December 2022, the protocol version was `v0.11`. In December 2022, the first [public testnet](https://namada.net/blog/announcing-namada-public-testnets) was launched with a few more validators joining forces ([29 in total](https://github.com/anoma/namada-testnets/tree/main/namada-public-testnet-1), with a few team-run nodes). Ever since, the core developers have published numerous protocol releases from `v0.12.0`, until the latest `v0.23.1` and more than 13 testnets launches/upgrades. The number of validators grew a lot, a total of [253 validators](https://github.com/anoma/namada-testnets/tree/main/namada-public-testnet-13) submitted their genesis keys for testnet 13. From 3291d4425b1c0e1081cfca796327942c9f4364a3 Mon Sep 17 00:00:00 2001 From: Zach <56927413+zjcio@users.noreply.github.com> Date: Fri, 8 Mar 2024 15:52:50 +0000 Subject: [PATCH 27/94] Update trusted-setup.mdx light changes for narrative consistency --- packages/community/pages/trusted-setup.mdx | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/packages/community/pages/trusted-setup.mdx b/packages/community/pages/trusted-setup.mdx index 075086fc..14678bea 100644 --- a/packages/community/pages/trusted-setup.mdx +++ b/packages/community/pages/trusted-setup.mdx @@ -2,9 +2,9 @@ A key component of the Namada protocol is the MASP circuit, which enables the features of asset-agnostic shielded transfers and shielded set rewards. For the MASP to work, it needs two sets of parameters: the first set is phase I from Zcash’s Powers of Tau ceremony, conducted in 2018, and the second ones are the ones generated in Namada’s Trusted Setup ceremony, which was announced in November 2022 and coordinated by the Anoma Foundation with the help of devs at Heliax. -The ceremony encouraged everyone to participate, but specifically the ones who wanted to use privacy on Namada – because participants in the ceremony only need to trust themselves to have effectively destroyed the toxic waste. The ceremony started on the 19th of November 2022 and concluded on the 21st of December 2022 with no less than 2,510 participants – making it the largest trusted setup at the time (more details in the recap). +The ceremony encouraged everyone to participate, but specifically the ones who wanted to use shielded set on Namada – because participants in the ceremony only need to trust themselves to have effectively destroyed the toxic waste. The ceremony started on the 19th of November 2022 and concluded on the 21st of December 2022 with no less than 2,510 participants – making it the largest trusted setup at the time (more details in the recap). -The Namada Community grew in size and diversity, everyone who participated contributed to the security of the privacy features on Namada. Participants in the Trusted Setup were requested to generate a seed phrase – and the next step will be the instructions for claiming the rewards for participating in the ceremony. +The Namada Community grew in size and diversity, everyone who participated contributed to the security of the shielded features on Namada. Participants in the Trusted Setup were requested to generate a seed phrase – and the next step will be the instructions for claiming the rewards for participating in the ceremony. **Resources:** @@ -18,5 +18,4 @@ The Namada Community grew in size and diversity, everyone who participated contr **Engage:** - Join the community on Discord -- Join the weekly Private Library on [Discord](https://discord.gg/namada) - Join the monthly community calls From 982dd7396aa12f9b143aaf127ef95c41ba3a39ae Mon Sep 17 00:00:00 2001 From: Zach <56927413+zjcio@users.noreply.github.com> Date: Fri, 8 Mar 2024 15:59:22 +0000 Subject: [PATCH 28/94] Update community-builder-handbook.mdx light edits for narrative consistency --- .../community/pages/community-builder-handbook.mdx | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/packages/community/pages/community-builder-handbook.mdx b/packages/community/pages/community-builder-handbook.mdx index 4e9a117d..06dbe98c 100644 --- a/packages/community/pages/community-builder-handbook.mdx +++ b/packages/community/pages/community-builder-handbook.mdx @@ -4,7 +4,7 @@ ## Joining the Namada Community Builders[](https://namada.net/community/docs/community-builder-handbook#joining-the-namada-community-builders) -Namada Community Builders are individuals who are aligned with Namada’sΒ [mission and vision(opens in a new tab)](https://namada.net/vision). They actively collaborate to support and grow the Namada community. Signups are currently closed, but if you were/are interested signing up for the program, the below information will still apply in future situations. +Namada Community Builders are individuals who are aligned with Namada’sΒ mission and vision. They actively collaborate to support and grow the Namada community. Signups are currently closed, but if you were/are interested in signing up for the program, the below information will still apply in future situations. Taking part in the program means aligning yourself with the Namada network such that you are working toward ensuring that the protocol exists in the long-term. The aim of the program is not to have hundred of contributors, but instead to have a core contingent who are committed to the work. The RPGF program is a means through which to do so, as Community Builders are filtered out based on their level of contribution. @@ -44,7 +44,7 @@ If you’re selected to join the Community Builders, an existing member of the C ### Contribution Guidelines[](https://namada.net/community/docs/community-builder-handbook#contribution-guidelines) -**Content Relevance:**Β Ensure your submissions align with Namada's values and mission, with a focus on its commitment to privacy and blockchain utility, and remember that helping others is also a kind of work. Namada seeks to make privacy cozy and accessible, not an act of fear, and the culture of our community should reflect this. +**Content Relevance:**Β Ensure your submissions align with Namada's values and mission, with a focus on its commitment to data rights and blockchain utility, and remember that helping others is also a kind of work. Namada seeks to make data protection cozy and accessible, not an act of fear, and the culture of our community should reflect this. **Avoid Price Speculation:**Β Discussions involving cryptocurrency pricing or 'moon' references are not permitted. The focus should be on the impact and value proposition of Namada's technology, not on financial gains. We are not looking to increase the value of the token associated with the network, we are seeking to ensure that the network stays around in the long term. @@ -101,19 +101,18 @@ Here are some ideas for contributions. - Actively participate in community channels like Twitter, Discord and Telegram, guiding conversations and disseminating important information. - Share successful methods of community engagement with other Community Builders to foster a learning environment. - Launch regional campaigns tailored to local culture and issues to attract a more diversified audience -- Collaborate with local educational institutions to offer workshops, or courses about privacy in blockchain +- Collaborate with local educational institutions to offer workshops, or courses about data protection in blockchain - Collab with Namada core contributors (Marketing in this case fyi) by conducting outreach efforts for Namada to be covered by different publications, podcasts, media etc. ### Content Creation and Amplification:[](https://namada.net/community/docs/community-builder-handbook#content-creation-and-amplification) -- Create content that helps educate a broader community about Namada and the broader vision on why privacy is paramount in decentralized systems. +- Create content that helps educate a broader community about Namada and the broader vision on why data protection is paramount in decentralized systems. - Visual media that is digestible and demonstrates an understanding of the protocol and its effect. - Distill the technical articles written at [blog.namada.net](https://blog.namada.net) into more accessible media. Namada doesn't need re-works of the articles that have already been written, but reflective pieces that speak to the effect of Namada on other networks, or on the culture of the space more broadly. - Engage in journalistic endeavors to create articles or interviews focused on Namada. - Write technical documentation or guides related to Namada's ecosystem. -- Speak about Namada's privacy-centric features at blockchain events, workshops, or meetups. +- Speak about Namada's data protection features at blockchain events, workshops, or meetups. - Live stream discussions, tutorials, or reviews related to Namada. (this can be Twitter Spaces / youtube / twitch / etc.) -- Leading Private Library discussions. ### Development and Technical Contributions:[](https://namada.net/community/docs/community-builder-handbook#development-and-technical-contributions) @@ -133,7 +132,7 @@ Don’t forget that you’re not alone! Use these Discord channels for jamming o * **Low-effort contributions** - While creating visual media is helpful, creating a pretty image with our tagline, or stickers for different social media platforms only helps so much. If you are going to create contributions, let them be vehicles for understanding the protocol. If your entire post history is only Midjourney images with the Namada logo pasted in frame, this is considered low-effort. Take the chance to experiment! Tell a story with your images. * **Inaccurate contributions** - If you are posting material that explains the protocol, it needs to be accurate - if you are unsure you understand the technology, check with the rest of those in the Community Builders programme. The aim is that by taking part in this programme, you should know the protocol back and forward by the end of your participation. -* **Contributions that target other protocols** - This is particularly egregious and would be grounds for losing CB membership. *We never compare ourselves to other protocols as a means of bettering our offering, and we believe that all other privacy tech is working toward the same mission.* +* **Contributions that target other protocols** - This is particularly egregious and would be grounds for losing CB membership. *We never compare ourselves to other protocols as a means of bettering our offering, and we believe that all similar tech is working toward the same mission.* ## Losing CB Membership[](https://namada.net/community/docs/community-builder-handbook#losing-cb-membership) From 99a9b4e1910cdb6db1b2951e50fd2bf5e727a0f0 Mon Sep 17 00:00:00 2001 From: Zach <56927413+zjcio@users.noreply.github.com> Date: Fri, 8 Mar 2024 16:03:54 +0000 Subject: [PATCH 29/94] Update cb-rpgf-round-1.mdx light updates for narrative consistency --- packages/community/pages/cb-rpgf-round-1.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/community/pages/cb-rpgf-round-1.mdx b/packages/community/pages/cb-rpgf-round-1.mdx index a14cad52..d2191c0e 100644 --- a/packages/community/pages/cb-rpgf-round-1.mdx +++ b/packages/community/pages/cb-rpgf-round-1.mdx @@ -1,6 +1,6 @@ # CB RPGF Round 1 -The Namada protocol could not be built without public goods and the community wouldn’t be where it is today without the help of the early Community Builders – brought together by the [shared mission](https://namada.net/vision) of using, educating, and collaborating to build privacy. Namada’s native token is not only used for proof-of-stake and governance, but also to [align the incentives](https://namada.net/blog/namada-s-positive-sum-economics) of the community with the network. +The Namada protocol could not be built without public goods and the community wouldn’t be where it is today without the help of the early Community Builders – brought together by a shared mission of using, educating, and collaborating to build technology for user data protection. Namada’s native token is not only used for proof-of-stake and governance, but also to [align the incentives](https://namada.net/blog/namada-s-positive-sum-economics) of the community with the network. The [Anoma Foundation](https://anoma.foundation/) has announced they will allocate 10,000,000 of Namada’s native token in the genesis block proposal to the selected recipients of the first Namada Community Builder RPGF Round – every active Community Builder member can be a potential recipient, dating back to the beginning of the community’s history. This includes early validators who have participated in previous testnets and have meaningfully worked to assist other validators in gaining access to, raising issues with, or triaging solutions for previous testnets. From 7f3e6314b7401a121ffdf3ad5776c6efe7a1d0ec Mon Sep 17 00:00:00 2001 From: Zach <56927413+zjcio@users.noreply.github.com> Date: Fri, 8 Mar 2024 16:17:45 +0000 Subject: [PATCH 30/94] Update index.mdx light updates for narrative consistency --- packages/docs/pages/index.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/packages/docs/pages/index.mdx b/packages/docs/pages/index.mdx index 8d113724..022c1383 100644 --- a/packages/docs/pages/index.mdx +++ b/packages/docs/pages/index.mdx @@ -4,13 +4,13 @@ import { DocsAscii } from '../components/DocsAscii' ## About Namada -[Namada](https://namada.net/) is a privacy-for-assets centric blockchain using zero-knowledge proof technology. -Namada's cryptographical features give users asset-agnostic, interchain privacy, and is being built by the Anoma foundation. +[Namada](https://namada.net/) is a data-protection blockchain using zero-knowledge proof technology. +Namada's cryptographical features give users asset-agnostic, multichain data protection, and is being built by the Anoma foundation. ### Key innovations: -- Zcash-like transfers for any assets (fungible and non-fungible) -- Rewarded usage of privacy as a public good +- Zcash-like shielded transfers for any assets (fungible and non-fungible) +- Rewards for keeping assets in the shielded set - Interoperability with Ethereum via a custom bridge with trust-minimization ## Overview of features From e0cc51479b2e000152cd38d5dd13989f4674399a Mon Sep 17 00:00:00 2001 From: Zach <56927413+zjcio@users.noreply.github.com> Date: Fri, 8 Mar 2024 16:24:05 +0000 Subject: [PATCH 31/94] Update privacy.mdx light updates for narrative consistency --- packages/docs/pages/introduction/privacy.mdx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/packages/docs/pages/introduction/privacy.mdx b/packages/docs/pages/introduction/privacy.mdx index f436e6ef..06bdf60a 100644 --- a/packages/docs/pages/introduction/privacy.mdx +++ b/packages/docs/pages/introduction/privacy.mdx @@ -1,12 +1,12 @@ -# Privacy +# Shielding -Namada gives the privacy landscape a different shape, by providing the largest possible unified privacy set in the multichain, and complementing other chains by seeding/retrofitting privacy shielded actions. +Namada provides the largest possible unified shielded set in the multichain, complementing other chains by seeding/retrofitting data protection via shielded actions. * Namada creates a single asset-agnostic shielded pool for any token fungible and non-fungible token -* Namada can also seed privacy to users who want to use an asset originating from one base chain on another chain, without losing privacy -* Namada retrofits privacy to assets that were created and already used in transparent chains +* Namada can also seed data protection to users who want to use an asset originating from one base chain on another chain, without losing data protection +* Namada retrofits data protection to assets that were created and already used in transparent chains -Users should be aware that they can still expose personal information when transferring funds into and out of Namada via the Ethereum bridge or IBC. For example, a user bridging WETH from Ethereum may be able to obfuscate their on-chain identities to *some* on-chain observers by interacting with Smart contract based privacy protocols or centralized exchanges. However, a user transferring a non-fungible token or a low liquidity token that relies on price discovery on-chain, will leak more information by the nature of their asset holdings. This is also true of tokens transferred into and out of Namada via IBC. Once inside the shielded set, a user can perform *shielded actions* such as triggering a cross chain swap. +Users should be aware that they can still expose personal information when transferring funds into and out of Namada via the Ethereum bridge or IBC. For example, a user bridging WETH from Ethereum may be able to obfuscate their on-chain identities to *some* on-chain observers by interacting with Smart contract based shielding protocols or centralized exchanges. However, a user transferring a non-fungible token or a low liquidity token that relies on price discovery on-chain, will leak more information by the nature of their asset holdings. This is also true of tokens transferred into and out of Namada via IBC. Once inside the shielded set, a user can perform *shielded actions* such as triggering a cross chain swap. Shielded actions are not limited to application chains that are IBC compatible, it works with any chain that is connected to Namada, e.g. Ethereum, and the actions can be generalized to interact with any dApp, such as trading NFTs or staking ETH. For the time being, the only shielded action available is cross chain transfers, but more will be added in the future. @@ -15,4 +15,4 @@ Shielded actions are not limited to application chains that are IBC compatible, * Bridge a highly liquid generic token into the MASP and then once in the MASP performing a shielded action to acquire the relevant tokens * Use a different public address to bridge funds into Namada than used for other exposed transactions * Use a TOR browser - Tor protects personal privacy by concealing a user's location and usage from anyone performing network surveillance or traffic analysis -* Use a VPN - A VPN can mask your IP address, encrypt your internet connection and make your browsing activity more anonymous. \ No newline at end of file +* Use a VPN - A VPN can mask your IP address, encrypt your internet connection and make your browsing activity more anonymous. From 2a88e727754be892a6cfe65c78fd6ceace031407 Mon Sep 17 00:00:00 2001 From: Zach <56927413+zjcio@users.noreply.github.com> Date: Fri, 8 Mar 2024 16:28:46 +0000 Subject: [PATCH 32/94] Update shielded-accounts.mdx light changes for narrative consistency --- packages/docs/pages/users/shielded-accounts.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/docs/pages/users/shielded-accounts.mdx b/packages/docs/pages/users/shielded-accounts.mdx index 0107e2f1..733163e6 100644 --- a/packages/docs/pages/users/shielded-accounts.mdx +++ b/packages/docs/pages/users/shielded-accounts.mdx @@ -2,7 +2,7 @@ The multi-asset shielded pool (MASP) is a zero knowledge circuit that allows users to make transfers in a way that does not reveal the sender, receiver, or amount. Each transfer is a zero knowledge proof itself, and is often referred to as a "note". From the users perspective, the construction of these zero knowledge proofs occur behind the scenes. -The MASP is inspired by the work produced by the Electric Coin Company (ECC) who developed Zcash, and builds on the Sapling Circuit by implementing multi-asset functionality. In addition to the MASP, Namada has also implemented a zero knowledge circuit for rewarding privacy set contributions in a shielded manner. This circuit is called the Convert Circuit (CC for short). +The MASP is inspired by the work produced by the Electric Coin Company (ECC) who developed Zcash, and builds on the Sapling Circuit by implementing multi-asset functionality. In addition to the MASP, Namada has also implemented a zero knowledge circuit for rewarding shielded set contributions in a shielded manner. This circuit is called the Convert Circuit (CC for short). More technical details of these circuits can be found in the [specs](https://specs.namada.net) as well as [this blog post](https://namada.net/blog/understanding-the-masp-and-cc-circuits). From 2b1c4b1f768677b51719f8e557fca7006e3c378f Mon Sep 17 00:00:00 2001 From: Zach <56927413+zjcio@users.noreply.github.com> Date: Fri, 8 Mar 2024 16:31:30 +0000 Subject: [PATCH 33/94] Update shielded-transfers.mdx light changes for narrative consistency --- .../docs/pages/users/shielded-accounts/shielded-transfers.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/docs/pages/users/shielded-accounts/shielded-transfers.mdx b/packages/docs/pages/users/shielded-accounts/shielded-transfers.mdx index 56096ed7..c5c7a8a9 100644 --- a/packages/docs/pages/users/shielded-accounts/shielded-transfers.mdx +++ b/packages/docs/pages/users/shielded-accounts/shielded-transfers.mdx @@ -3,7 +3,7 @@ import { Callout } from 'nextra-theme-docs' # Shielded Transfers In Namada, shielded transfers are enabled by the [Multi-Asset Shielded Pool](https://specs.namada.net/masp/ledger-integration.html?highlight=MASP#masp-integration-spec) (MASP). -The MASP is a zero-knowledge circuit ([zk-SNARK](https://en.wikipedia.org/wiki/Non-interactive_zero-knowledge_proof)) that extends the [Zcash Sapling circuit](https://raw.githubusercontent.com/zcash/zips/master/protocol/sapling.pdf) to add support for sending arbitrary assets. All assets in the pool share the same anonymity set, this means that the more transactions are issued to MASP, the stronger are the privacity guarantees. +The MASP is a zero-knowledge circuit ([zk-SNARK](https://en.wikipedia.org/wiki/Non-interactive_zero-knowledge_proof)) that extends the [Zcash Sapling circuit](https://raw.githubusercontent.com/zcash/zips/master/protocol/sapling.pdf) to add support for sending arbitrary assets. All assets in the pool share the same anonymity set, this means that the more transactions are issued to MASP, the stronger are the data protection guarantees. ## Using MASP From 157a5e19edf5b67ce2f1354a9d90976f799a7c01 Mon Sep 17 00:00:00 2001 From: bengtlofgren Date: Sat, 9 Mar 2024 09:12:00 +0000 Subject: [PATCH 34/94] new version updated --- packages/docs/pages/networks/testnets.mdx | 2 +- packages/docs/pages/networks/testnets/environment-setup.mdx | 4 ++-- packages/docs/pages/networks/testnets/testnet-history.mdx | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/packages/docs/pages/networks/testnets.mdx b/packages/docs/pages/networks/testnets.mdx index 01368728..d6788838 100644 --- a/packages/docs/pages/networks/testnets.mdx +++ b/packages/docs/pages/networks/testnets.mdx @@ -21,7 +21,7 @@ The `balances.toml` file is located at `https://github.com/anoma/namada-shielded - Namada Shielded expedition 2: - From date: 6th of February 2024 18:00 UTC - - Namada protocol version: `v0.31.8` + - Namada protocol version: `v0.31.9` - Cometbft version: `0.37.2` - CHAIN_ID: `shielded-expedition.88f17d1d14` diff --git a/packages/docs/pages/networks/testnets/environment-setup.mdx b/packages/docs/pages/networks/testnets/environment-setup.mdx index 95f62c40..5bbabd91 100644 --- a/packages/docs/pages/networks/testnets/environment-setup.mdx +++ b/packages/docs/pages/networks/testnets/environment-setup.mdx @@ -11,7 +11,7 @@ Note that building from source can be a difficult process and is not recommended Export the following variables: ```bash copy -export NAMADA_TAG=v0.31.8 +export NAMADA_TAG=v0.31.9 ``` @@ -66,6 +66,6 @@ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh - Make sure you are using the correct CometBFT version - `cometbft version` should output `0.37.2` - Make sure you are using the correct Namada version - - `namada --version` should output `Namada v0.31.8` + - `namada --version` should output `Namada v0.31.9` < /Steps> diff --git a/packages/docs/pages/networks/testnets/testnet-history.mdx b/packages/docs/pages/networks/testnets/testnet-history.mdx index 6402dfc4..bdb13055 100644 --- a/packages/docs/pages/networks/testnets/testnet-history.mdx +++ b/packages/docs/pages/networks/testnets/testnet-history.mdx @@ -14,7 +14,7 @@ In order to upgrade to the latest version of the Namada protocol, please follow - Namada Shielded expedition 2: - From date: 6th of February 2024 18:00 UTC - - Namada protocol version: `v0.31.8` + - Namada protocol version: `v0.31.9` - Cometbft version: `0.37.2` - CHAIN_ID: `shielded-expedition.88f17d1d14` From e0720891807d6f77a0307ce18ee382fccea7d345 Mon Sep 17 00:00:00 2001 From: Zach <56927413+zjcio@users.noreply.github.com> Date: Wed, 13 Mar 2024 12:48:12 +0000 Subject: [PATCH 35/94] Update index.mdx light updates for narrative consistency --- packages/docs/pages/index.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/packages/docs/pages/index.mdx b/packages/docs/pages/index.mdx index 022c1383..a285a987 100644 --- a/packages/docs/pages/index.mdx +++ b/packages/docs/pages/index.mdx @@ -25,12 +25,11 @@ Namada's cryptographical features give users asset-agnostic, multichain data pro For high-level introductions, we recommend: -- Article: [Introducing Namada: Interchain Asset-agnostic Privacy](https://blog.namada.net/introducing-namada-interchain-asset-agnostic-privacy/) +- Article: [Introducing Namada: Multichain Asset-agnostic Data Protection](https://namada.net/blog/introducing-namada-multichain-asset-agnostic-data-protection) - Article: [What is Namada?](https://blog.namada.net/what-is-namada/) - [Talks & Podcasts](https://namada.net/talks) To learn more about the protocol, we recommend the following in-depth resources: -- Talk at ZK8 [Namada: asset-agnostic interchain privacy](https://youtu.be/5K6YxmZPFkE) - [Namada's specifications](https://specs.namada.net) - [Codebase](https://github.com/anoma/namada) From a7dbca13df2026af77cf62e163b70d658cfb7278 Mon Sep 17 00:00:00 2001 From: Menshykov Date: Wed, 13 Mar 2024 22:49:47 +0200 Subject: [PATCH 36/94] Update on-chain-governance.mdx tpknam1qz7z09ds674wlyfl6upvl2e6jtuus7lfp2rus984g8sy3v23f9qf6v7n638 --- packages/docs/pages/users/governance/on-chain-governance.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/docs/pages/users/governance/on-chain-governance.mdx b/packages/docs/pages/users/governance/on-chain-governance.mdx index 34b0e4f6..c7b346ae 100644 --- a/packages/docs/pages/users/governance/on-chain-governance.mdx +++ b/packages/docs/pages/users/governance/on-chain-governance.mdx @@ -89,7 +89,7 @@ The `data` field and its structure is dependent on the type of proposal being su The data field for default proposals is optional. This is in line with the nature of default proposals. If the proposals have code attached to them in order to change governance parameters, then this code -will be represented as a wasm file and byte encoded vector will be tehe value of the data field. +will be represented as a wasm file and byte encoded vector will be the value of the data field. From c531a225870a70ad3214cbbbc7e6e87244369242 Mon Sep 17 00:00:00 2001 From: iskay Date: Thu, 14 Mar 2024 14:10:24 -0400 Subject: [PATCH 37/94] change quick start --- .../pages/introduction/install/binaries.mdx | 6 +- .../pages/introduction/install/source.mdx | 1 + .../install/source/troubleshooting.mdx | 12 ++- .../docs/pages/introduction/quick-start.mdx | 85 ++++++++++--------- 4 files changed, 57 insertions(+), 47 deletions(-) diff --git a/packages/docs/pages/introduction/install/binaries.mdx b/packages/docs/pages/introduction/install/binaries.mdx index 8634f82e..048d674a 100644 --- a/packages/docs/pages/introduction/install/binaries.mdx +++ b/packages/docs/pages/introduction/install/binaries.mdx @@ -1,7 +1,7 @@ # Install From Binaries ## Pre-requisites -There are certain pre-requisites that need to be installed before installing Namada via binaries. +The following prerequisites are needed to use the pre-compiled binaries: These are: - [CometBFT](./binaries/prerequisites.mdx#installing-cometbft) @@ -9,7 +9,7 @@ These are: ## Downloading the binaries -Now that you have all dependencies installed, you can download the latest binary release from our [releases page](https://github.com/anoma/namada/releases) by choosing the appropriate architecture. +After installing the prerequisites, you can download the latest binary release from our [releases page](https://github.com/anoma/namada/releases) by choosing the appropriate architecture. The below code will download all the binaries for the latest release for all supported operating systems. ```shell copy @@ -33,4 +33,4 @@ Once inside the directory containing the binaries: ```bash copy sudo cp ./namada* /usr/local/bin/ ``` - +Verify that the binaries are in your `$PATH` by running the command `which namada`. diff --git a/packages/docs/pages/introduction/install/source.mdx b/packages/docs/pages/introduction/install/source.mdx index 4f3d587e..b698345f 100644 --- a/packages/docs/pages/introduction/install/source.mdx +++ b/packages/docs/pages/introduction/install/source.mdx @@ -32,6 +32,7 @@ from `namada/target/release` to `$HOME/.local/bin/` for example: ```shell copy cp namada/target/release/namada* $HOME/.local/bin/ ``` +You can verify the binaries are correctly added to `$PATH` by running the command `which namada`. ## Using the binaries See the page on [using namada binaries](./binaries/overview-of-binaries.mdx) for more information. diff --git a/packages/docs/pages/introduction/install/source/troubleshooting.mdx b/packages/docs/pages/introduction/install/source/troubleshooting.mdx index 840901ec..4432b2a6 100644 --- a/packages/docs/pages/introduction/install/source/troubleshooting.mdx +++ b/packages/docs/pages/introduction/install/source/troubleshooting.mdx @@ -7,7 +7,10 @@ The error ``` src/apps/namada lib could not compile due to previous errors. Exited with exit code: ``` -is a common error that can sometimes mean your computer ran out of memory when compiling. To resolve this, I have found closing all other applications and recompiling once or twice will do the trick. Otherwise more RAM will be needed. +is a common error that can sometimes mean your computer ran out of memory when compiling. To resolve this, try closing all other applications and recompiling once or twice more. +Otherwise more RAM will be needed. + +Instead of adding more physical RAM, you can also try adding 16GB of [swap space](https://www.digitalocean.com/community/tutorials/how-to-add-swap-space-on-ubuntu-22-04). ### Compiling for the first time Compilation errors due to missing library installations when building the binaries for the first time can be a common problem. @@ -65,7 +68,7 @@ This issue can be resolved by running ```bash copy rustup target add wasm32-unknown-unknown ``` -(Yes the name of the target is `wasm32-unknown-unknown`. This is not the compiler unable to tell which version/release it is). +(Yes, the name of the target is `wasm32-unknown-unknown`. This is not the compiler unable to tell which version/release it is). #### OpenSSL @@ -85,10 +88,11 @@ Could not find directory of OpenSSL installation, and this `-sys` crate cannot and include information about your system as well as this message. ``` -Then the solution is spelled out for you. You need to install the development packages of OpenSSL. For Ubuntu, this is `libssl-dev`. For Fedora, this is `openssl-devel`. For other distributions, please refer to the [OpenSSL website](https://www.openssl.org/). +You need to install the development packages of OpenSSL. For Ubuntu, this is `libssl-dev`. For Fedora, this is `openssl-devel`. For other distributions, please refer to the [OpenSSL website](https://www.openssl.org/). For Ubuntu, this can be achieved through ```bash copy sudo apt-get install libssl-dev -``` \ No newline at end of file +``` +import { RouteMatcher } from "next/dist/server/future/route-matchers/route-matcher" diff --git a/packages/docs/pages/introduction/quick-start.mdx b/packages/docs/pages/introduction/quick-start.mdx index b0aa3d08..58587aac 100644 --- a/packages/docs/pages/introduction/quick-start.mdx +++ b/packages/docs/pages/introduction/quick-start.mdx @@ -1,69 +1,74 @@ -# Quickstart - -## About this guide - -This guide is for those interested in getting Namada up and running as quickly as possible. It will guide you through installing Namada, joining a testnet network, running a node, and grabbing some tokens. - -## Installing Namada - -See [the installation guide](./install.mdx) for details on installing the Namada binaries. Commands in this guide will assume you have the Namada binaries (`namada`, `namadan`, `namadaw`, `namadac`) on your `$PATH`. - -If the binaries are stored somewhere, but are not on your path (perhaps you downloaded the binaries), you can add the binaries to your $PATH with: - -```shell copy -export PATH=$PATH: -``` +import { Steps } from 'nextra-theme-docs' -If you build from source, and run `make install`, the binaries will be installed to your `$PATH` by default. +# Quickstart -## Joining a network +Getting started with Namada is as simple as: -See [the networks page](../networks.mdx) for details on how to join a network. The rest of this guide will assume you have joined a network using the `namadac utils join-network --chain-id ` command. + +### Install Namada + +Install the Namada binaries (`namada`, `namadan`, `namadaw`, `namadac`) and place them in your `$PATH`. -## Run a ledger node +You can [build from source](#) or [download prebuilt binaries](#) from the Releases page of the Namada Github repo. [Docker images](#) are also available. + +### Install CometBFT + +[Install CometBFT](#) and place it in your `$PATH`. -We recommend this step with [tmux](https://www.hamvocke.com/blog/a-quick-and-easy-guide-to-tmux/), which allows the node to keep running without needing the terminal to be open indefinitely. If not, skip to the subsequent step. +### Join a Network + +See the [networks page](../networks.mdx) for details on how to join a network. Joining a network is a one-step process to download the proper genesis files, wasm code and checksums, and initialize your node's storage and configuration. +You can join a [testnet](#), [localnet](#), or (soon) [mainnet](#). +### Start the Ledger Node + +Start your node with: ```shell copy -tmux - -# inside the tmux/or not namadan ledger run - -# can detach the tmux (Ctrl-B then D) ``` - -For a more verbose output, one can run +Your node will begin syncing with the chain. +For a more verbose output, one can run: ```shell copy -NAMADA_LOG=info CMT_LOG_LEVEL=p2p:none,pex:error NAMADA_CMT_STDOUT=true namada ledger +NAMADA_LOG=info CMT_LOG_LEVEL=p2p:none,pex:error NAMADA_CMT_STDOUT=true namadan ledger run ``` +To keep your node running in the background after closing your terminal, you will likely want to use either tmux or a systemd service file. See the section on [Running a full node](#) for more detail on this, as well as configuration options and environment variables. -This should sync your node to the ledger and will take a while (depending on your machine's hardware as well as the time between genesis and the start of sync). Subsequent commands (generating an account, etc.) are unlikely to work until your node is fully synced. Enquire the current block height with other participants to make sure you are synced in order to proceed. +Instead of syncing your own node, you can use a [public rpc](#) for most functionality. -## Generate an account and grab some tokens +### Wait for your Node to Finish Syncing +This can take several hours depending on the chain height and your system specs. -First you will need an implicit account in order to receive tokens. You can generate one with: +### Create an Account + +Create a new implicit account in order to receive tokens: ```shell copy namadaw gen --alias ``` - -For the remainder of this introduction, let's assume your go-to alias is `stanley`. - -This will generate a new account and store it in the default keychain. You can see the account with: +This will generate a new account and store it in the default keychain. You can view the account address with: ```shell copy namadaw list --addr + +# Sample output: +Known transparent addresses: + ... + "": Implicit: tnam1qzegva94xdnvtahqqetys9zzua6sdlm8sve05r9u ``` {/* #TODO: ADD some output */} -## Grabbing the tokens (testnet only) - +### Get Some Tokens from the Faucet (Testnet Only) + Testnet tokens can be sourced from the [faucet](https://faucet.heliax.click). +### Explore πŸš€ -## From here - -From here, you can do a variety of cool things. Perhaps try [shielding your NAM](../users/shielded-accounts/shielded-transfers.mdx), bonding your tokens to a validator for [delegating purposes](../users/delegators.mdx), or [becoming a validator](../operators/validators.mdx). +There's a variety of cool things you can do next! +- [Shield some NAM or other tokens](#) +- [Bond (delegate) some tokens to a validator](#) +- [Become a validator yourself](#) +- [Participate in governance by creating or voting on proposals](#) +- [Send or recieve tokens from another chain via IBC](#) + From 1ed1adb3a1587dca6da29a283ec29239fb4c6a4e Mon Sep 17 00:00:00 2001 From: Liver-23 Date: Mon, 18 Mar 2024 17:44:30 +0200 Subject: [PATCH 38/94] Update ibc.mdx --- packages/docs/pages/operators/ibc.mdx | 121 +++++++++++++++++++++----- 1 file changed, 97 insertions(+), 24 deletions(-) diff --git a/packages/docs/pages/operators/ibc.mdx b/packages/docs/pages/operators/ibc.mdx index 879f1c6c..0a3d59f6 100644 --- a/packages/docs/pages/operators/ibc.mdx +++ b/packages/docs/pages/operators/ibc.mdx @@ -66,26 +66,64 @@ host = '127.0.0.1' port = 3001 [[chains]] -id = 'namada-test.0a4c6786dbda39f786' # set your chain ID +id = 'shielded-expedition.88f17d1d14' # set your chain ID type = 'Namada' -rpc_addr = 'http://127.0.0.1:27657' # set the IP and the port of the chain +rpc_addr = 'http://127.0.0.1:26657' # set the IP and the port of the chain grpc_addr = 'http://127.0.0.1:9090' # not used for now event_source = { mode = 'push', url = 'ws://127.0.0.1:27657/websocket', batch_delay = '500ms' } # set the IP and the port of the chain account_prefix = '' # not used key_name = 'relayer' # The key is an account name you made store_prefix = 'ibc' -gas_price = { price = 0.001, denom = 'atest1v4ehgw36x9ry2dphx5mrvdjxgez5gdengeq5gs2pg3znx32yg9p5yv2zg3pnjvf4g9q5x329epndn0' } # the price isn't used for now, the denom should be a raw token address +trusting_period = '4752s' +gas_price = { price = 0.0001, denom = 'tnam1qxvg64psvhwumv3mwrrjfcz0h3t3274hwggyzcee' } # the price isn't used for now, the denom should be a raw token address retrieve denom by namadaw address find --alias "naan" +rpc_timeout = '30s' +memo_prefix = '' + +[chains.packet_filter] +policy = 'allow' +list = [ + ['transfer', ''], #channel-id leading to the counterparty channel you want to configure IBC +] [[chains]] -id = 'namada-test.647287156defa8728c' -type = 'Namada' -rpc_addr = 'http://127.0.0.1:28657' -grpc_addr = 'http://127.0.0.1:9090' +id = 'axelar-testnet-lisbon-3' +type = 'CosmosSdk' +rpc_addr = 'http://127.0.0.1:28657' # RPC of the counterparty chain +grpc_addr = 'http://127.0.0.1:28090' # gRPC of the counterparty chain event_source = { mode = 'push', url = 'ws://127.0.0.1:28657/websocket', batch_delay = '500ms' } -account_prefix = '' +rpc_timeout = '10s' +account_prefix = 'axelar' key_name = 'relayer' store_prefix = 'ibc' -gas_price = { price = 0.001, denom = 'atest1v4ehgw36xazry3pn89q5xv3ngyungs3hxc65vwp3xez5zdp3xppy2v6yxc65zsfegyc5yd2ptuf9d8' } +default_gas = 5000000 +max_gas = 15000000 +gas_price = { price = 0.001, denom = 'uaxl' } +gas_multiplier = 1.1 +max_msg_num = 30 +max_tx_size = 800000 +clock_drift = '5s' +max_block_time = '30s' +trusting_period = '5days' # should be less than unbonding period of the counterparty channel +ccv_consumer_chain = false +sequential_batch_tx = false +memo_prefix = '' + +[chains.trust_threshold] +numerator = "1" +denominator = "3" + +[chains.packet_filter] + policy = 'allow' + list = [ + ['transfer', ''], # channel id of the Namada side + ] + +[chains.packet_filter.min_fees] + +[chains.address_type] +derivation = "cosmos" + +# Add all channels you want to process ``` @@ -100,9 +138,10 @@ These are the pieces of this puzzle you want to keep your πŸ‘€ on: - `chains.id` is the name of the chain - `chains.rpc_address` specifies the port that the channel is communicating through, and will be the argument for the `ledger_address` of Namada when interacting with the ledger (will become clearer later) - Make sure to change the IP address to the IP address of your local machine that is running this node! + - `chains.grpc_addr` currently is not used in Namada but needs to be configured for other Cosmos chains - `chains.key_name` specifies the key of the signer who signs a transaction from the relayer. The key should be generated before starting the relayer. - `chains.event_source` specifies the URL of the chain's websocket. This must be the same as the `rpc_address` for Hermes to work properly. - - `chains.gas_price.denom` specifies the token that the relayer pays for IBC transactions. `chains.gas_price.price` isn't used for now. + - `chains.gas_price.denom` specifies the token that the relayer pays for IBC transactions. `chains.gas_price.price` isn't used for now in Namada. You can see more details of configuration in [the official document](https://hermes.informal.systems/documentation/configuration). @@ -150,26 +189,26 @@ export HERMES=$(pwd) # if needed ``` Check the binary: ```bash copy -./target/release/hermes --version #or sudo cp ./target/release/hermes /usr/local/bin/ +./target/release/hermes --version ``` It is recommended to now add hermes to `$PATH` such that it is callable without any pre-fixes. For ubuntu users, this can be achieved by ```bash copy -cp ./target/release/hermes /usr/local/bin/ +sudo cp ./target/release/hermes /usr/local/bin/ ``` ## Setting up the relayer ### Create the relayer account -On each chain, there must be a `relayer` account. The alias should be the same as `chains.key_name` in the config. On a namada chain, this can be done by running +On each chain, there must be a `relayer` account. The alias should be the same as `chains.key_name` in the config. On a Namada chain, this can be done by running ```bash copy namadaw gen --alias relayer ``` -This will generate a key for the relayer account. The key will be stored in the `wallet.toml` that is found in the [base directory](./ledger/base-directory.mdx) of the node, inside the `chain-id` folder. For example, if the `chain-id` is `namada-test.0a4c6786dbda39f786`, the `wallet.toml` will be found in `$HOME/.local/share/namada/namada-test.0a4c6786dbda39f786/wallet.toml` (on a ubuntu machine where `base-dir` has not been set up properly). +This will generate a key for the relayer account. The key will be stored in the `wallet.toml` that is found in the [base directory](./ledger/base-directory.mdx) of the node, inside the `chain-id` folder. For example, if the `chain-id` is `shielded-expedition.88f17d1d14`, the `wallet.toml` will be found in `$HOME/.local/share/namada/shielded-expedition.88f17d1d14/wallet.toml` (on a ubuntu machine where `base-dir` has not been set up properly). The relayer account should have some balance to pay the fee of transactions. Before creating an IBC channel or relaying an IBC packet, you need to transfer the fee token to the relayer account. @@ -204,7 +243,14 @@ hermes --config $HERMES_CONFIG \ Note that the above `CHAIN_IDs` will depend on your own setup, so do check this for yourself! -When the creation has been completed, you can see the channel IDs. For example, the following text shows that a channel with ID `7` has been created on Chain A `namada-test.0a4c6786dbda39f786`, and a channel with ID `12` has been created on Chain B `namada-test.647287156defa8728c`. You will need the channel IDs for a transfer over IBC. It means that you have to specify `channel-7` as a channel ID (The prefix `channel-` is always required) for a transfer from Chain A to Chain B. Also, you have to specify `channel-12` as a channel ID for a transfer from Chain B to Chain A. +When the creation has been completed, you can see the channel IDs. For example, the following text shows that a channel with ID `955` has been created on Chain A `shielded-expedition.88f17d1d14`, and a channel with ID `460` has been created on Chain B `axelar-testnet-lisbon-3`. You will need the channel IDs for a transfer over IBC. It means that you have to specify `channel-955` as a channel ID (The prefix `channel-` is always required) for a transfer from Chain A to Chain B. Also, you have to specify `channel-460` as a channel ID for a transfer from Chain B to Chain A. + +Remember the ClientId for each of the chains, we will need them on the next step: `07-tendermint-2996` for `shielded-expedition.88f17d1d14` and `07-tendermint-884` for `axelar-testnet-lisbon-3` + +```bash copy +export CLIENT_A_ID="" +export CLIENT_B_ID="" +``` ``` @@ -213,23 +259,23 @@ SUCCESS Channel { a_side: ChannelSide { chain: BaseChainHandle { chain_id: ChainId { - id: "namada-test.0a4c6786dbda39f786", + id: "shielded-expedition.88f17d1d14", version: 0, }, runtime_sender: Sender { .. }, }, client_id: ClientId( - "07-tendermint-0", + "07-tendermint-2996", ), connection_id: ConnectionId( - "connection-3", + "connection-1479", ), port_id: PortId( "transfer", ), channel_id: Some( ChannelId( - "channel-7", + "channel-955", ), ), version: None, @@ -237,23 +283,23 @@ SUCCESS Channel { b_side: ChannelSide { chain: BaseChainHandle { chain_id: ChainId { - id: "namada-test.647287156defa8728c", - version: 0, + id: "axelar-testnet-lisbon-3", + version: 3, }, runtime_sender: Sender { .. }, }, client_id: ClientId( - "07-tendermint-1", + "07-tendermint-884", ), connection_id: ConnectionId( - "connection-2", + "connection-679", ), port_id: PortId( "transfer", ), channel_id: Some( ChannelId( - "channel-12", + "channel-460", ), ), version: None, @@ -263,6 +309,33 @@ SUCCESS Channel { ``` +### Change Hermes configuration + +Now when the channels are created we need to update the [Hermes configuration](#Make-Hermes-config-file) + +```bash copy +... +[chains.packet_filter] +policy = 'allow' +list = [ + ['transfer', ''], #channel-id leading to the counterparty channel you want to use for IBC +] +... +``` + +### Update IBC clients + +In order to have IBC channels running they need active IBC clients they rely on. When clients are not in use they tend to expire and to prevent this they are required to be updated manually. + +The "update channel" command (below) update the actual state of the client in the particular chain. + +```bash copy +hermes update client --host-chain $CHAIN_A_ID --client $CLIENT_A_ID +hermes update client --host-chain $CHAIN_B_ID --client $CLIENT_B_ID +``` + +It is recommended to perform this manual update or use specific scripts to automate it. Otherwise, you risk your clients will be expired. The restoration is possible only from the Governance of the specific chain. + ## Start the relayer Once you run Hermes, it monitors chains via the nodes and relays packets according to monitored events. ```bash copy From c4fff7c073d6e4fe1fe7cdf7629b8afd359659eb Mon Sep 17 00:00:00 2001 From: Liver-23 Date: Mon, 18 Mar 2024 20:51:53 +0200 Subject: [PATCH 39/94] Update ibc.mdx --- packages/docs/pages/operators/ibc.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/packages/docs/pages/operators/ibc.mdx b/packages/docs/pages/operators/ibc.mdx index 0a3d59f6..239c37e0 100644 --- a/packages/docs/pages/operators/ibc.mdx +++ b/packages/docs/pages/operators/ibc.mdx @@ -142,6 +142,7 @@ These are the pieces of this puzzle you want to keep your πŸ‘€ on: - `chains.key_name` specifies the key of the signer who signs a transaction from the relayer. The key should be generated before starting the relayer. - `chains.event_source` specifies the URL of the chain's websocket. This must be the same as the `rpc_address` for Hermes to work properly. - `chains.gas_price.denom` specifies the token that the relayer pays for IBC transactions. `chains.gas_price.price` isn't used for now in Namada. + - `trusting_period` specifies the maximum period before which the client can not expire. This should be not more than unbonding time in the particular chain. You can see more details of configuration in [the official document](https://hermes.informal.systems/documentation/configuration). From a22b9055995222a344003dca5a1d04b8929a6012 Mon Sep 17 00:00:00 2001 From: "tq.tuan" Date: Sat, 23 Mar 2024 16:37:15 +0700 Subject: [PATCH 40/94] add health check and config validate --- packages/docs/pages/operators/ibc.mdx | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/packages/docs/pages/operators/ibc.mdx b/packages/docs/pages/operators/ibc.mdx index 879f1c6c..08e59232 100644 --- a/packages/docs/pages/operators/ibc.mdx +++ b/packages/docs/pages/operators/ibc.mdx @@ -177,6 +177,7 @@ The relayer account should have some balance to pay the fee of transactions. Bef To sign each transaction, the relayer's key should be added to Hermes with `keys add` command in advance. It requires the `wallet.toml` which should have the key of `chains.key_name`. Once the key has been added, Hermes doesn't need the wallet anymore. ```bash copy hermes --config $HERMES_CONFIG keys add --chain $CHAIN_ID --key-file $WALLET_PATH +hermes --config $HERMES_CONFIG keys add --chain $CHAIN_ID --mnemonic-file $SEED_PATH ``` Hermes will store the key in `~/.hermes/keys/${CHAIN_ID}` as default. You can specify the directory by setting `chains.key_store_folder` in the config file. @@ -187,6 +188,19 @@ If you want to use an encrypted key with a password, you have to set an environm It is now possible to set up the client. +# Verify configuration files +After editing `config.toml` and adding wallet keys, it’s time to test the configurations and ensure the system is healthy. Run the following: + +```bash copy +hermes health-check +hermes config validate +``` +If everything was set up correctly, you should see output like: +``` bash copy +SUCCESS performed health check for all chains in the config +SUCCESS "configuration is valid" +``` + ### Create IBC channel The "create channel" command (below) creates not only the IBC channel but also the necessary IBC client connection. From 2897fdb12ec919890ca0ad58945f1e17c14d24f2 Mon Sep 17 00:00:00 2001 From: Zach <56927413+zjcio@users.noreply.github.com> Date: Mon, 25 Mar 2024 21:52:37 +0000 Subject: [PATCH 41/94] Update index.mdx Slight updates for narrative consistency --- packages/specs/pages/index.mdx | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/packages/specs/pages/index.mdx b/packages/specs/pages/index.mdx index 4d7e0b6e..b5be19db 100644 --- a/packages/specs/pages/index.mdx +++ b/packages/specs/pages/index.mdx @@ -7,34 +7,34 @@ import { SpecsAscii } from '../components/SpecsAscii' ## What is Namada? -Namada is a sovereign proof-of-stake layer-one blockchain, using the [CometBFT](https://cometbft.com/) (nee Tendermint) BFT consensus algorithm. Namada enables multi-asset private transfers for any native or non-native asset 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 is a sovereign proof-of-stake layer-one blockchain, using the [CometBFT](https://cometbft.com/) (nee Tendermint) BFT consensus algorithm. Namada enables multi-asset shielded transfers for any native or non-native asset 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](./modules/ethereum-bridge.mdx), a modern [proof-of-stake system](./modules/proof-of-stake.mdx) with cubic slashing, a [stake-weighted governance signalling mechanism](./modules/governance.mdx), and a dual continuous/retroactive [public goods funding system](./modules/governance/public-goods-funding.mdx). -Users of the MASP are [rewarded](./modules/masp/shielded-pool-incentives.mdx) for their contributions to the privacy set in the form of native protocol tokens (NAM). +Users of the MASP are [rewarded](./modules/masp/shielded-pool-incentives.mdx) for their contributions to the shielded set in the form of native protocol tokens (NAM). -Namada also supports shielded actions, which allow users to hold their assets privately on Namada most of the time while occasionally unshielding specific assets in order to interact with existing applications on transparent chains. +Namada also supports shielded actions, which allow users to hold their assets shielded on Namada most of the time while occasionally unshielding specific assets in order to interact with existing applications on transparent chains. -You can find an introduction to Namada from a product perspective [here](https://blog.namada.net/introducing-namada-interchain-asset-agnostic-privacy/). +You can find an introduction to Namada from a product perspective [here](https://namada.net/blog/introducing-namada-multichain-asset-agnostic-data-protection). ### What is Anoma? -Anoma is an intent-centric, privacy-preserving architecture for decentralized counterparty discovery, solving, and settlement. You can find the Anoma specs [here](https://specs.anoma.net). +Anoma is an intent-centric architecture for decentralized counterparty discovery, solving, and settlement. You can find the Anoma specs [here](https://specs.anoma.net). ### How does Namada relate to Anoma? -Anoma is a full-stack architecture designed with a long term perspective, while Namada is a specific chain and featureset designed to provide practical privacy now. +Anoma is a full-stack architecture designed with a long term perspective, while Namada is a specific chain and featureset designed to provide practical data protection now. ### Why Namada? -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. +Data protection should be default and inherent in the systems we use for transacting, yet safe and user-friendly multi-asset data protection 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 non-trivial metadata, and the protocols may be expensive and clunky to use. +or a data protection 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 non-trivial metadata, and the protocols may be expensive and clunky to use. Namada supports any fungible or non-fungible asset on an IBC-compatible blockchain -as well as fungible or non-fungible assets sent over a custom Ethereum bridge (such as ERC20 tokens and ERC721 tokens, respectively). Once assets are on Namada, shielded transfers are cheap and all assets contribute to the same anonymity set. +as well as fungible or non-fungible assets sent over a custom Ethereum bridge (such as ERC20 tokens and ERC721 tokens, respectively). Once assets are on Namada, shielded transfers are cheap and all assets contribute to the same shielded set. -Users of Namada earn rewards, retain privacy of assets, and contribute to shared privacy. +Users of Namada earn rewards for shieldiing assets and contributing to shared data protection. ### Layout of this specification @@ -45,4 +45,4 @@ These documents describe the behavior of the Namada protocol. This description i This book is written using [NextraJS](https://nextra.site/). The source can be found in the [Namada Docs repository](https://github.com/anoma/namada-docs/tree/master/packages/specs). -Contributions to the contents and the structure of this book should be made via [pull requests](https://github.com/anoma/namada-docs/pulls). \ No newline at end of file +Contributions to the contents and the structure of this book should be made via [pull requests](https://github.com/anoma/namada-docs/pulls). From a70b982d997929dd2b9d03809ae282d3330672cc Mon Sep 17 00:00:00 2001 From: Zach <56927413+zjcio@users.noreply.github.com> Date: Mon, 25 Mar 2024 22:18:40 +0000 Subject: [PATCH 42/94] Update fee-system.mdx slight update for narrative consistency --- packages/specs/pages/base-ledger/fee-system.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/specs/pages/base-ledger/fee-system.mdx b/packages/specs/pages/base-ledger/fee-system.mdx index c2f757d8..56c84cf2 100644 --- a/packages/specs/pages/base-ledger/fee-system.mdx +++ b/packages/specs/pages/base-ledger/fee-system.mdx @@ -156,7 +156,7 @@ track any changes in these parameters and act accordingly. ### Unshielding -To provide improved privay, Namada allows the signer of the wrapper transaction +To provide improved data protection, Namada allows the signer of the wrapper transaction to unshield some funds on the go to cover the cost of the fee. This also addresses a possible locked-out problem in which a user doesn't have enough funds to pay fees (preventing any sort of operation on the chain). The From f35ea6beb982ab1ef0053d4d7a7115a61c316c6f Mon Sep 17 00:00:00 2001 From: Zach <56927413+zjcio@users.noreply.github.com> Date: Mon, 25 Mar 2024 22:21:12 +0000 Subject: [PATCH 43/94] Update inflation-system.mdx sight updates for narrative consistency --- .../specs/pages/modules/proof-of-stake/inflation-system.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/specs/pages/modules/proof-of-stake/inflation-system.mdx b/packages/specs/pages/modules/proof-of-stake/inflation-system.mdx index 72d6ecb7..459b85be 100644 --- a/packages/specs/pages/modules/proof-of-stake/inflation-system.mdx +++ b/packages/specs/pages/modules/proof-of-stake/inflation-system.mdx @@ -8,7 +8,7 @@ The security of the proof-of-stake voting power allocation mechanism used by Nam ### Shielded pool rewards -Privacy provided by the MASP in practice depends on how many users use the shielded pool and what assets they use it with. To increase the likelihood of a sizeable privacy set, Namada pays a variable portion of inflation, up to 10% per annum, to shielded pool incentives, which are allocated on a per-asset basis by a PD-controller targeting specific amounts of each asset being locked in the shielded pool. See [shielded pool incentives](../masp/shielded-pool-incentives.mdx) for details. +Data protection provided by the MASP in practice depends on how many users use the shielded pool and what assets they use it with. To increase the likelihood of a sizeable shielded set, Namada pays a variable portion of inflation, up to 10% per annum, to shielded pool incentives, which are allocated on a per-asset basis by a PD-controller targeting specific amounts of each asset being locked in the shielded pool. See [shielded pool incentives](../masp/shielded-pool-incentives.mdx) for details. ## Detailed inflation calculation model From dff84b0b79d227723662f810fb16e59f6dd7e182 Mon Sep 17 00:00:00 2001 From: Zach <56927413+zjcio@users.noreply.github.com> Date: Mon, 25 Mar 2024 22:25:17 +0000 Subject: [PATCH 44/94] Update shielded-pool-incentives.mdx slight updates for narrative consistency --- .../specs/pages/modules/masp/shielded-pool-incentives.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/packages/specs/pages/modules/masp/shielded-pool-incentives.mdx b/packages/specs/pages/modules/masp/shielded-pool-incentives.mdx index 3ba190c8..b7a07a71 100644 --- a/packages/specs/pages/modules/masp/shielded-pool-incentives.mdx +++ b/packages/specs/pages/modules/masp/shielded-pool-incentives.mdx @@ -1,15 +1,15 @@ ## Shielded pool rewards -Privacy provided by the MASP in practice depends on how many users use the shielded pool and what assets they use it with. To increase the likelihood of a sizeable privacy set, Namada pays a variable portion of inflation, up to 10% per annum, to shielded pool incentives, which are allocated on a per-asset basis by a PD-controller targeting specific amounts of each asset being locked in the shielded pool. +Data protection provided by the MASP in practice depends on how many users use the shielded pool and what assets they use it with. To increase the likelihood of a sizeable shielded set, Namada pays a variable portion of inflation, up to 10% per annum, to shielded pool incentives, which are allocated on a per-asset basis by a PD-controller targeting specific amounts of each asset being locked in the shielded pool. ### Rationale -The economic rationale for subsidizing the shielded set comes from "positive externalities": the shielding of more assets into the current privacy set not only provides better privacy for the owner of the assets, but enhances privacy for *everyone*. In this way, even users that are indifferent about privacy, are "nudged" into shielding their assets. This is especially important in an environment where users pay for computation, and shielded transactions are expected to be more expensive than transparent transactions. +The economic rationale for subsidizing the shielded set comes from "positive externalities": the shielding of more assets into the current shielded set not only provides better data protection for the owner of the assets, but enhances data protection for *everyone*. In this way, even users that are indifferent about data protection, are "nudged" into shielding their assets. This is especially important in an environment where users pay for computation, and shielded transactions are expected to be more expensive than transparent transactions. The subsidy on Namada adheres to the following constraints in order to avoid perverse incentives: - Fee subsidies cannot reduce fees to zero, or reduce fees so much that inexpensive transaction spam can fill blocks and overload validators. -- Incentives for contributing to the privacy set should not incentivise transactions which do not meaningfully contribute to the privacy set or merely repeat a previous action (shielded and unshielding the same assets, repeatedly transferring the same assets, etc.) -- Incentives for contributing to the privacy set, since the MASP supports many assets, will need to be adjusted over time according to actual conditions of use. +- Incentives for contributing to the shielded set should not incentivise transactions which do not meaningfully contribute to the shielded set or merely repeat a previous action (shielded and unshielding the same assets, repeatedly transferring the same assets, etc.) +- Incentives for contributing to the shielded set, since the MASP supports many assets, will need to be adjusted over time according to actual conditions of use. ### Design From 53dcd87ae308953a8a854d941a9cb0ae214eb2b5 Mon Sep 17 00:00:00 2001 From: iskay Date: Tue, 26 Mar 2024 15:41:42 -0400 Subject: [PATCH 45/94] merge branch TuanTQ15/fix/update-pfg --- .../users/public-goods-stewards/proposing.mdx | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/packages/docs/pages/users/public-goods-stewards/proposing.mdx b/packages/docs/pages/users/public-goods-stewards/proposing.mdx index cd6e698b..33a6c61e 100644 --- a/packages/docs/pages/users/public-goods-stewards/proposing.mdx +++ b/packages/docs/pages/users/public-goods-stewards/proposing.mdx @@ -19,7 +19,7 @@ Below is an example of a `PGFProposal` that a governance participant could submi "motivation": "Nobody knows technical research better than me. Trust me. I know it. I have the best technical research. I will be the best steward. Last night, Namada called me and said, Stewie, thank you. I will make public goods funding great again", "details": "As a genius baby, I possess an unmatched level of intelligence and a visionary mindset. I will utilize these qualities to solve the most complex problems, and direct public goods funding towards weapons of mass destruction ... i mean open source software for weapons of mass destruction" }, - "author": "stewie", + "author": "", "voting_start_epoch": 3, "voting_end_epoch": 6, "grace_epoch": 12 @@ -27,18 +27,17 @@ Below is an example of a `PGFProposal` that a governance participant could submi "data": { "continuous": [ { - "target": { - "amount": 420, - "address": "" - }, - "action": "add" + "Internal": { + "amount": "1000", + "target": "" + } } ], "retro": [ { - "target": { - "amount": 1337, - "address": "" + "Internal": { + "amount": "1500", + "target": "" } } ] @@ -55,7 +54,7 @@ In order to submit the proposal, the governance participant can use the followin ```shell copy namada client init-proposal \ - --pgf-proposal \ + --pgf-funding \ --data-path PGF_proposal.json ``` From 4f213c6182048a1762d29e25e523d5381be67305 Mon Sep 17 00:00:00 2001 From: iskay Date: Tue, 26 Mar 2024 16:11:34 -0400 Subject: [PATCH 46/94] merge branch TuanTQ15/improve/governance --- .../users/public-goods-stewards/electing.mdx | 19 +++++++++++++++++++ .../users/public-goods-stewards/voting.mdx | 2 ++ 2 files changed, 21 insertions(+) diff --git a/packages/docs/pages/users/public-goods-stewards/electing.mdx b/packages/docs/pages/users/public-goods-stewards/electing.mdx index 6af83969..8c8a2b27 100644 --- a/packages/docs/pages/users/public-goods-stewards/electing.mdx +++ b/packages/docs/pages/users/public-goods-stewards/electing.mdx @@ -90,3 +90,22 @@ namadac resign-steward --steward my-steward-address ``` Read more about the other methods of losing stewardship in the [specs](https://specs.namada.net/modules/goverance/public-goods-funding/becoming-a-steward#losing-stewardship-status). + +## Update steward commissions + +The `commissions.json` file contains the information about the reward distribution. It is a JSON file with the following structure: + +```json +{ + "reward_distribution": { + "tnam...": "1" + } +} +``` + +Update steward commissions can be done at any point. +Through the CLI it can be done with the command: + +```shell copy +namadac update-steward-rewards --steward my-steward-address --data-path +``` \ No newline at end of file diff --git a/packages/docs/pages/users/public-goods-stewards/voting.mdx b/packages/docs/pages/users/public-goods-stewards/voting.mdx index 2c718915..44b54582 100644 --- a/packages/docs/pages/users/public-goods-stewards/voting.mdx +++ b/packages/docs/pages/users/public-goods-stewards/voting.mdx @@ -9,6 +9,7 @@ The CLI command for voting for a steward is: ```shell copy namada client vote-proposal \ --proposal-id \ + --address your-established-account \ --vote yay \ --signing-keys ``` @@ -22,6 +23,7 @@ Similarly, the command for voting for PGF proposals is: ```shell copy namada client vote-proposal \ --proposal-id \ + --address your-established-account \ --vote yay \ --signing-keys ``` \ No newline at end of file From d72d6b052b08b91d54cdfc132fd0307d7f063fd6 Mon Sep 17 00:00:00 2001 From: iskay Date: Tue, 26 Mar 2024 16:12:31 -0400 Subject: [PATCH 47/94] merge branch TuanTQ15/improve/pos --- .../operators/validators/proof-of-stake.mdx | 50 +++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/packages/docs/pages/operators/validators/proof-of-stake.mdx b/packages/docs/pages/operators/validators/proof-of-stake.mdx index cd48cbee..85ea2e09 100644 --- a/packages/docs/pages/operators/validators/proof-of-stake.mdx +++ b/packages/docs/pages/operators/validators/proof-of-stake.mdx @@ -82,4 +82,54 @@ After updating the consensus key, validators can find out their new validator ad namadaw find --alias ``` +## Commission +To query a validator's commission rate, the following command can be run: + +```shell copy +namadac commission-rate --validator +``` + +To change a validator's commission rate, the following command can be run: + +```shell copy +namadac change-commission-rate \ + --validator \ + --commission-rate +``` + +## Change Metadata + +To query a validator's metadata, the following command can be run: + +```shell copy +namadac validator-metadata --validator +``` + +To change a validator's metadata, the following command can be run: + +```shell copy +namadac change-metadata \ + --validator \ + --email \ + --avatar \ + --description \ + --website \ + --discord-handle +``` + +## Deactivate + +To deactivate a validator, the following command can be run: + +```shell copy +namadac deactivate-validator --validator +``` + +## Reactivate + +To reactivate a validator, the following command can be run: + +```shell copy +namadac reactivate-validator --validator +``` \ No newline at end of file From 8659dc0c2e67dfb75073f5997352e4cedfe77edb Mon Sep 17 00:00:00 2001 From: NodeOps <157517809+nodeopsdev@users.noreply.github.com> Date: Thu, 28 Mar 2024 16:05:36 +0700 Subject: [PATCH 48/94] Create query.mdx query --- packages/docs/pages/users/query.mdx | 51 +++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 packages/docs/pages/users/query.mdx diff --git a/packages/docs/pages/users/query.mdx b/packages/docs/pages/users/query.mdx new file mode 100644 index 00000000..9b8c1cc5 --- /dev/null +++ b/packages/docs/pages/users/query.mdx @@ -0,0 +1,51 @@ +# **Query** + +This is the complete query related to Namada + +Including: account,bytes,pgf,proposal,proposal-result,proposal-votes,protocol parameters + +## query-account + +```txt +namadac query-account --owner +``` + +Return the results will return the `Threshold` and `Public` key of the address. + +## query-pgf + +``` +namadac query-pgf +``` + +Return the results will return the `Pgf stewards , Reward distribution`, `Pgf fundings` key of the address. + +## query-proposal + +``` +namadac query-proposal --proposal-id +``` + +Return the results will return the PGF type of the proposal, `author`, `content`, `StartEpoch`, `EndEpoch`, `GraceEpoch`, `Status` + +## query-proposal-result + +``` +namadac query-proposal-result --proposal-id +``` + +Return the results will return the outcome of the proposal, whether it's `Passed` or `Rejected`, including the total number of votes for `yay`, `nay`, `abstain`, and the threshold (fraction) of the total voting power needed to tally. + +## query-proposal-votes + +``` +namadac query-proposal-votes --proposal-id +``` + +Return the results of all wallets that have voted `yay` or `nay` on the proposal + +``` +namadac query-proposal-votes --proposal-id --voter +``` + +Return the result of a specific wallet that has voted on a specific proposal From 0ecbc0734ff41df3b06935082f945811e361d775 Mon Sep 17 00:00:00 2001 From: NodeOps <157517809+nodeopsdev@users.noreply.github.com> Date: Thu, 28 Mar 2024 16:08:06 +0700 Subject: [PATCH 49/94] Update query.mdx --- packages/docs/pages/users/query.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/docs/pages/users/query.mdx b/packages/docs/pages/users/query.mdx index 9b8c1cc5..e52a156c 100644 --- a/packages/docs/pages/users/query.mdx +++ b/packages/docs/pages/users/query.mdx @@ -2,7 +2,7 @@ This is the complete query related to Namada -Including: account,bytes,pgf,proposal,proposal-result,proposal-votes,protocol parameters +Including: account,pgf,proposal,proposal-result,proposal-votes ## query-account From 9fded8f8a06ed7f4a3a8dd22975913f71c5f105a Mon Sep 17 00:00:00 2001 From: hunvy Date: Fri, 29 Mar 2024 00:06:53 +0700 Subject: [PATCH 50/94] Feat utils.mdx --- packages/docs/pages/_meta.json | 5 +- .../docs/pages/introduction/quick-start.mdx | 2 + packages/docs/pages/utils.mdx | 114 ++++++++++++++++++ 3 files changed, 119 insertions(+), 2 deletions(-) create mode 100644 packages/docs/pages/utils.mdx diff --git a/packages/docs/pages/_meta.json b/packages/docs/pages/_meta.json index dfd35081..ff68ea17 100644 --- a/packages/docs/pages/_meta.json +++ b/packages/docs/pages/_meta.json @@ -4,5 +4,6 @@ "users": "User Guide", "operators": "Operator Guide", "integrating-with-namada" : "Integration Guide", - "networks": "Networks" -} + "networks": "Networks", + "utils": "Utils" +} \ No newline at end of file diff --git a/packages/docs/pages/introduction/quick-start.mdx b/packages/docs/pages/introduction/quick-start.mdx index b0aa3d08..84d95f98 100644 --- a/packages/docs/pages/introduction/quick-start.mdx +++ b/packages/docs/pages/introduction/quick-start.mdx @@ -20,6 +20,8 @@ If you build from source, and run `make install`, the binaries will be installed See [the networks page](../networks.mdx) for details on how to join a network. The rest of this guide will assume you have joined a network using the `namadac utils join-network --chain-id ` command. +See [all utilities command](../utils.mdx). + ## Run a ledger node We recommend this step with [tmux](https://www.hamvocke.com/blog/a-quick-and-easy-guide-to-tmux/), which allows the node to keep running without needing the terminal to be open indefinitely. If not, skip to the subsequent step. diff --git a/packages/docs/pages/utils.mdx b/packages/docs/pages/utils.mdx new file mode 100644 index 00000000..10c342ad --- /dev/null +++ b/packages/docs/pages/utils.mdx @@ -0,0 +1,114 @@ +# Commands + +Usage: `namadac utils [OPTIONS] ` + +## join-network + +Configure Namada to join an existing network. +See [the networks page](../networks.mdx) for details on how to join a network. +```shell copy +namadac utils join-network --chain-id +``` + +## fetch-wasms + +Ensure pre-built wasms are present. +```shell copy +namadac utils fetch-wasms --chain-id +``` + + +## validate-wasm + +Check that the provided wasm code is valid by the Namada standards. +```shell copy +namadac utils validate-wasm --code-path --chain-id +``` + +## init-network + +Initialize a new test network. + +```shell copy +namadac utils init-network --templates-path --wasm-checksums-path +--chain-prefix --genesis-time --chain-id +``` + +## derive-genesis-addresses + +Derive account addresses from a genesis txs toml file. +```shell copy +namadac utils derive-genesis-addresses --path --chain-id +``` + +## genesis-bond + +Bond to a validator at pre-genesis. +```shell copy +namadac utils genesis-bond --validator --amount --path --chain-id +``` + +## init-genesis-established-account + +Initialize an established account available at genesis. +```shell copy +namadac utils init-genesis-established-account --path --chain-id +``` + +## init-genesis-validator + +Initialize genesis validator's address, consensus key and validator account key and use it in the ledger's node. Appends validator creation and self-bond txs to a .toml file containing an established account tx. +```shell copy +namadac utils init-genesis-validator --alias --address
--path + --net-address --commission-rate --max-commission-rate-change + --self-bond-amount --email --chain-id +``` + +## pk-to-tm + +Convert a validator's consensus public key to a Tendermint address. +```shell copy +namadac utils pk-to-tm --public-key --chain-id +``` + +## default-base-dir + +Print the default base directory that would be used if --base-dir or NAMADA_BASE_DIR were not used to set the base directory. +```shell copy +namadac utils default-base-dir +``` + +## epoch-sleep + +Query for the current epoch, then sleep until the next epoch. +```shell copy +namadac utils epoch-sleep +``` + +## validate-genesis-templates + +Validate genesis templates. +```shell copy +namadac utils validate-genesis-templates --path --chain-id +``` + +## test-genesis + +Dry run genesis files and get a report on problems that may be found. +```shell copy +namadac utils test-genesis --path --chain-id +``` + +## sign-genesis-txs + +Sign genesis transaction(s). +```shell copy +namadac utils sign-genesis-txs --path --chain-id +``` + +## help + +Print this message or the help of the given subcommand(s). +```shell copy +namadac utils [COMMAND] --help +``` \ No newline at end of file From 5e47f295ff58fa99f93b3b5b3c4d115077cbf602 Mon Sep 17 00:00:00 2001 From: Afanti <127061691+threewebcode@users.noreply.github.com> Date: Tue, 2 Apr 2024 22:23:59 +0800 Subject: [PATCH 51/94] docs: fix typo --- packages/specs/pages/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/specs/pages/index.mdx b/packages/specs/pages/index.mdx index b5be19db..122c1ac7 100644 --- a/packages/specs/pages/index.mdx +++ b/packages/specs/pages/index.mdx @@ -34,7 +34,7 @@ or a data protection solution built on an existing smart contract chain. Both ha Namada supports any fungible or non-fungible asset on an IBC-compatible blockchain as well as fungible or non-fungible assets sent over a custom Ethereum bridge (such as ERC20 tokens and ERC721 tokens, respectively). Once assets are on Namada, shielded transfers are cheap and all assets contribute to the same shielded set. -Users of Namada earn rewards for shieldiing assets and contributing to shared data protection. +Users of Namada earn rewards for shielding assets and contributing to shared data protection. ### Layout of this specification From f59fa1480c7b2a1f562272961ed19eba6f5f4393 Mon Sep 17 00:00:00 2001 From: TerzoMillenio Date: Sat, 6 Apr 2024 18:48:32 +0300 Subject: [PATCH 52/94] Fixed imports using outdated "types" crate --- .../integrating-with-namada/sdk/generating-accounts.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/packages/docs/pages/integrating-with-namada/sdk/generating-accounts.mdx b/packages/docs/pages/integrating-with-namada/sdk/generating-accounts.mdx index abd7d0f2..28727445 100644 --- a/packages/docs/pages/integrating-with-namada/sdk/generating-accounts.mdx +++ b/packages/docs/pages/integrating-with-namada/sdk/generating-accounts.mdx @@ -4,7 +4,7 @@ Representing accounts using the Namada SDK is straightforward. An account on Namada is defined by its public key(s) and private key(s) (plural for multisignatures). The public key(s) is/are used to identify the account and the private key is used to sign transactions. In the below snippet, we represent the account using the public key and private key. ```rust -use namada_sdk::types::key::common::{PublicKey, SecretKey}; +use namada_sdk::key::common::{PublicKey, SecretKey}; struct SimpleAccount { public_key: PublicKey, private_key: SecretKey @@ -14,7 +14,7 @@ struct SimpleAccount { For a multisignature account, we can represent this through a vector of keys. ```rust -use namada_sdk::types::key::common::{PublicKey, SecretKey}; +use namada_sdk::key::common::{PublicKey, SecretKey}; struct MultisigAccount { public_keys: Vec, private_keys: Vec @@ -24,7 +24,7 @@ struct MultisigAccount { Multisignature accounts, because they are initialized by an on-chain transaction, will always have their public key revealed to the ledger. However, when keypairs are generated in an offline fashion, the user must submit a transaction in order to reveal their public key. Because of this, it is helpful to add the field `revealed` to the account struct. ```rust -use namada_sdk::types::key::common::{PublicKey, SecretKey}; +use namada_sdk::key::common::{PublicKey, SecretKey}; struct Account { public_key: PublicKey, private_key: SecretKey, @@ -39,7 +39,7 @@ In order to reveal the public key of an implicit account, the user must submit a ```rust use namada_sdk::io::NullIo; use namada_sdk::NamadaImpl; -use namada_sdk::types::chain::ChainId; +use namada_sdk::chain::ChainId; // Define the namada implementation (assuming we have a wallet, http_client, and shielded_ctx) From 58bec5199ec970d6290de94cae190eb5cc29883e Mon Sep 17 00:00:00 2001 From: TerzoMillenio Date: Sat, 6 Apr 2024 19:00:02 +0300 Subject: [PATCH 53/94] Changed "namada_impl" name to "namada" as all the documentation uses the latter --- .../pages/integrating-with-namada/sdk/setting-up-a-client.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/docs/pages/integrating-with-namada/sdk/setting-up-a-client.mdx b/packages/docs/pages/integrating-with-namada/sdk/setting-up-a-client.mdx index eb0a9a6d..497c9b45 100644 --- a/packages/docs/pages/integrating-with-namada/sdk/setting-up-a-client.mdx +++ b/packages/docs/pages/integrating-with-namada/sdk/setting-up-a-client.mdx @@ -111,10 +111,10 @@ let http_client = reqwest::Client::new(); let wallet = Wallet::from_mnemonic("your mnemonic here").unwrap(); let wallet: namada_sdk::wallet::Wallet = FsWalletUtils::new(PathBuf::from("wallet.toml")); let shielded_ctx = FsShieldedUtils::new(Path::new("masp/").to_path_buf()); -let namada_impl = NamadaImpl::new(http_client, wallet, shielded_ctx, NullIo) +let namada = NamadaImpl::new(http_client, wallet, shielded_ctx, NullIo) .await .expect("unable to construct Namada object") .chain_id(ChainId::from_str(CHAIN_ID).unwrap()); ``` -This object will be referenced throughout the documentation as `namada_impl`. +This object will be referenced throughout the documentation as `namada`. From ed4c3f27668cb5764890f8be964503665c0db951 Mon Sep 17 00:00:00 2001 From: TerzoMillenio Date: Mon, 8 Apr 2024 23:35:30 +0300 Subject: [PATCH 54/94] Added an import for bip39::Mnemonic to avoid confusion --- .../pages/integrating-with-namada/sdk/setting-up-a-wallet.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/packages/docs/pages/integrating-with-namada/sdk/setting-up-a-wallet.mdx b/packages/docs/pages/integrating-with-namada/sdk/setting-up-a-wallet.mdx index 5d087f2c..edde6cf7 100644 --- a/packages/docs/pages/integrating-with-namada/sdk/setting-up-a-wallet.mdx +++ b/packages/docs/pages/integrating-with-namada/sdk/setting-up-a-wallet.mdx @@ -25,6 +25,8 @@ use namada_sdk::wallet::fs::FsWalletUtils; The SDK can create a wallet from a mnemonic phrase. The mnemonic phrase is a 24 word phrase that can be used to restore a wallet. ```rust +use namada_sdk::bip39::Mnemonic; + let mnemonic = Mnemonic::from_phrase(MNEMONIC_CODE, namada_sdk::bip39::Language::English) ``` From 7b28c8e04f3a2975885d30b9b587a6251fae0677 Mon Sep 17 00:00:00 2001 From: TerzoMillenio Date: Tue, 9 Apr 2024 00:20:37 +0300 Subject: [PATCH 55/94] Updated outdated imports to modern ones --- .../sdk/constructing-transfers.mdx | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/packages/docs/pages/integrating-with-namada/sdk/constructing-transfers.mdx b/packages/docs/pages/integrating-with-namada/sdk/constructing-transfers.mdx index 4e188a38..5d790d47 100644 --- a/packages/docs/pages/integrating-with-namada/sdk/constructing-transfers.mdx +++ b/packages/docs/pages/integrating-with-namada/sdk/constructing-transfers.mdx @@ -52,8 +52,16 @@ In order to make the transfer shielded, we need to the only difference is to use It is important to use the shielded extended `SpendingKey` as the source. ```rust - -use namada::types::masp::{ExtendedSpendingKey, PaymentAddress, TransferSource, TransferTarget}; +use std::str::FromStr; +use namada_sdk::{ + masp::{ + PaymentAddress, + TransferSource, + TransferTarget, + }, + masp_primitives::zip32::ExtendedSpendingKey, + address::Address, +}; // Make sure to replace 'secret-ex' with an actual Namada extended spending key let source = ExtendedSpendingKey::from_str("secret-ex").unwrap(); From 9a328cb22e34a740fc94087c678f7c5c221e657d Mon Sep 17 00:00:00 2001 From: TerzoMillenio Date: Tue, 9 Apr 2024 00:27:49 +0300 Subject: [PATCH 56/94] Added a missing import and a missing semicolon --- .../docs/pages/integrating-with-namada/sdk/governance.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/packages/docs/pages/integrating-with-namada/sdk/governance.mdx b/packages/docs/pages/integrating-with-namada/sdk/governance.mdx index 3ee5d660..00046efb 100644 --- a/packages/docs/pages/integrating-with-namada/sdk/governance.mdx +++ b/packages/docs/pages/integrating-with-namada/sdk/governance.mdx @@ -82,7 +82,9 @@ In order to vote on a proposal, we need a valid proposal id. We can retrieve the Once we have the proposal id, we can vote on the proposal using the following code: ```rust - let proposal_id = 1 as u64 // placeholder, replace with actual proposal id + use namada_sdk::signing::default_sign; + + let proposal_id = 1 as u64; // placeholder, replace with actual proposal id let vote = String::from("Yay"); let signing_public_key = signing_key.to_public(); From 7ecb4ec88d2180399b1ccc1022bee8ab0ac53d33 Mon Sep 17 00:00:00 2001 From: TerzoMillenio Date: Tue, 9 Apr 2024 00:30:25 +0300 Subject: [PATCH 57/94] Changed namada_impl to namada according to the previous commit on this pr --- .../pages/integrating-with-namada/sdk/proof-of-stake.mdx | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/packages/docs/pages/integrating-with-namada/sdk/proof-of-stake.mdx b/packages/docs/pages/integrating-with-namada/sdk/proof-of-stake.mdx index 6592862b..8cf99852 100644 --- a/packages/docs/pages/integrating-with-namada/sdk/proof-of-stake.mdx +++ b/packages/docs/pages/integrating-with-namada/sdk/proof-of-stake.mdx @@ -9,10 +9,9 @@ The `namada_impl` object is assumed to have been constructed as described in the ```rust -// We assume we have a namada_impl object that is already initialized +// We assume we have a namada object that is already initialized -let bond_tx_builder = namada_impl - +let bond_tx_builder = namada .new_bond(validator_address.clone(), amount) .source(source_address.clone()) .signing_keys(vec![source_public_key]); @@ -22,7 +21,7 @@ let (mut bond_tx, signing_data) = bond_tx_builder .await .expect("unable to build bond"); -namada_impl +namada .sign( &mut bond_tx, &bond_tx_builder.tx, From 7d741ae521653a7dc17b570cb2c571c72b92d2af Mon Sep 17 00:00:00 2001 From: TerzoMillenio Date: Tue, 9 Apr 2024 00:31:04 +0300 Subject: [PATCH 58/94] Added a missing import --- .../docs/pages/integrating-with-namada/sdk/proof-of-stake.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/packages/docs/pages/integrating-with-namada/sdk/proof-of-stake.mdx b/packages/docs/pages/integrating-with-namada/sdk/proof-of-stake.mdx index 8cf99852..cd28638c 100644 --- a/packages/docs/pages/integrating-with-namada/sdk/proof-of-stake.mdx +++ b/packages/docs/pages/integrating-with-namada/sdk/proof-of-stake.mdx @@ -9,8 +9,9 @@ The `namada_impl` object is assumed to have been constructed as described in the ```rust -// We assume we have a namada object that is already initialized +use namada_sdk::signing::default_sign; +// We assume we have a namada object that is already initialized let bond_tx_builder = namada .new_bond(validator_address.clone(), amount) .source(source_address.clone()) From 61d4ef8b4b277171fd8f00ef8f54337be960c9ce Mon Sep 17 00:00:00 2001 From: TerzoMillenio Date: Tue, 9 Apr 2024 00:32:15 +0300 Subject: [PATCH 59/94] Changed namada_impl to namada according to the previous commit on this pr --- .../pages/integrating-with-namada/sdk/setting-up-a-client.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/docs/pages/integrating-with-namada/sdk/setting-up-a-client.mdx b/packages/docs/pages/integrating-with-namada/sdk/setting-up-a-client.mdx index 497c9b45..193cab84 100644 --- a/packages/docs/pages/integrating-with-namada/sdk/setting-up-a-client.mdx +++ b/packages/docs/pages/integrating-with-namada/sdk/setting-up-a-client.mdx @@ -101,7 +101,7 @@ This client will allow us to make asynchronous calls to the network and handle t ## Instantiating a Namada Implementation object -When constructing transactions using the sdk, we almost alwasy need a `namada_impl` object. +When constructing transactions using the sdk, we almost alwasy need a `namada` object. ```rust use namada_sdk::NamadaImpl; // This module allows us to access the NamadaImpl struct, which is needed for most transactions From 16ea9ec5f503435907dac35d4460e81f43de520a Mon Sep 17 00:00:00 2001 From: TerzoMillenio Date: Wed, 10 Apr 2024 17:48:52 +0300 Subject: [PATCH 60/94] Forgot to change imports using "types" here, fixed now --- .../pages/integrating-with-namada/sdk/setting-up-a-wallet.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/docs/pages/integrating-with-namada/sdk/setting-up-a-wallet.mdx b/packages/docs/pages/integrating-with-namada/sdk/setting-up-a-wallet.mdx index edde6cf7..0258358d 100644 --- a/packages/docs/pages/integrating-with-namada/sdk/setting-up-a-wallet.mdx +++ b/packages/docs/pages/integrating-with-namada/sdk/setting-up-a-wallet.mdx @@ -14,8 +14,8 @@ use namada_sdk::NamadaImpl; ```rust // SecretKey, common and SchemeType give access to Namada cryptographic keys and their relevant implementations. Namada supports ED25519 and SECP256K1 keys. -use namada_sdk::types::key::common::SecretKey; -use namada_sdk::types::key::{common, SchemeType}; +use namada_sdk::key::common::SecretKey; +use namada_sdk::key::{common, SchemeType}; // Filesystem wallet utilities (stores the path of the wallet on the filesystem) use namada_sdk::wallet::fs::FsWalletUtils; ``` From ec935d9ee4d2235550aa6e672ea8aec2c0b0fd75 Mon Sep 17 00:00:00 2001 From: TerzoMillenio Date: Wed, 10 Apr 2024 18:26:28 +0300 Subject: [PATCH 61/94] Fixed more imports in this file --- .../sdk/setting-up-a-wallet.mdx | 55 ++++++------------- 1 file changed, 18 insertions(+), 37 deletions(-) diff --git a/packages/docs/pages/integrating-with-namada/sdk/setting-up-a-wallet.mdx b/packages/docs/pages/integrating-with-namada/sdk/setting-up-a-wallet.mdx index 0258358d..558d637a 100644 --- a/packages/docs/pages/integrating-with-namada/sdk/setting-up-a-wallet.mdx +++ b/packages/docs/pages/integrating-with-namada/sdk/setting-up-a-wallet.mdx @@ -61,16 +61,15 @@ In the second part of the above function, the key is derived from the mnemonic p It is also possible to create the sdk wallet from scratch. This is more involved because it requires generating a new store for the wallet to exist in. ```rust -use std::path::PathBuf; - -use namada::{ - sdk::wallet::{ - alias::Alias, ConfirmationResponse, GenRestoreKeyError, Store, StoredKeypair, Wallet, - WalletUtils, +use namada_sdk::{ + wallet::{ + Store, + StoredKeypair, + Wallet, + WalletIo, }, - types::{ - address::Address, - key::{common::SecretKey, PublicKeyHash}, + address::Address, + key::{common::SecretKey, PublicKeyHash}, }, }; use rand::rngs::OsRng; @@ -82,7 +81,7 @@ pub struct SdkWallet { impl SdkWallet { pub fn new(sk: SecretKey, nam_address: Address) -> Self { let store = Store::default(); - let mut wallet = Wallet::new(PathBuf::new(), store); + let mut wallet = Wallet::new(SdkWalletUtils {}, store); let stored_keypair = StoredKeypair::Raw(sk.clone()); let pk_hash = PublicKeyHash::from(&sk.to_public()); let alias = "alice".to_string(); @@ -94,37 +93,19 @@ impl SdkWallet { pub struct SdkWalletUtils {} -impl WalletUtils for SdkWalletUtils { - type Storage = PathBuf; - +impl WalletIo for SdkWalletUtils { type Rng = OsRng; +} - fn read_decryption_password() -> zeroize::Zeroizing { - panic!("attempted to prompt for password in non-interactive mode"); - } - - fn read_encryption_password() -> zeroize::Zeroizing { - panic!("attempted to prompt for password in non-interactive mode"); - } - - fn read_alias(_prompt_msg: &str) -> std::string::String { - panic!("attempted to prompt for alias in non-interactive mode"); - } - - fn read_mnemonic_code() -> std::result::Result { - panic!("attempted to prompt for mnemonic in non-interactive mode"); - } - - fn read_mnemonic_passphrase(_confirm: bool) -> zeroize::Zeroizing { - panic!("attempted to prompt for mnemonic in non-interactive mode"); +impl Clone for SdkWalletUtils { + fn clone(&self) -> Self { + SdkWalletUtils::new() } +} - fn show_overwrite_confirmation( - _alias: &Alias, - _alias_for: &str, - ) -> namada::sdk::wallet::store::ConfirmationResponse { - // Automatically replace aliases in non-interactive mode - ConfirmationResponse::Replace +impl SdkWalletUtils { + fn new() -> Self { + Self {} } } ``` From 54e17e251e7651409dc6fa6fe579a5a113c43068 Mon Sep 17 00:00:00 2001 From: TerzoMillenio Date: Thu, 11 Apr 2024 01:42:01 +0300 Subject: [PATCH 62/94] Fixed function calls according to modern signatures and some format errors --- .../sdk/constructing-transfers.mdx | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/packages/docs/pages/integrating-with-namada/sdk/constructing-transfers.mdx b/packages/docs/pages/integrating-with-namada/sdk/constructing-transfers.mdx index 5d790d47..e8fc34d7 100644 --- a/packages/docs/pages/integrating-with-namada/sdk/constructing-transfers.mdx +++ b/packages/docs/pages/integrating-with-namada/sdk/constructing-transfers.mdx @@ -60,21 +60,22 @@ use namada_sdk::{ TransferTarget, }, masp_primitives::zip32::ExtendedSpendingKey, - address::Address, + key::common::PublicKey, }; -// Make sure to replace 'secret-ex' with an actual Namada extended spending key +// Make sure to replace "secret-ex" with an actual Namada extended spending key let source = ExtendedSpendingKey::from_str("secret-ex").unwrap(); // Make sure to replace "payment-addr-ex" with an actual Namada payment address let destination = PaymentAddress::from_str("payment-addr-ex").unwrap(); -let fee_payer = +// Make sure to replace "public-key" with an actual Namada public key +let fee_payer = PublicKey::from_str("public-key"); +let amount = /* Needed amount here */; let mut transfer_tx_builder = namada .new_transfer( - TransferSource::ExtendedSpendingKey(source), - TransferTarget::Address(Address::from(&destination.public_key)), + TransferSource::ExtendedSpendingKey(source.into()), + TransferTarget::PaymentAddress(destination), namada.native_token(), amount, ) - // Make sure to replace "transparent-address-ex" with an actual Namada transparent address - .signing_keys(vec![Address::from_str("transparent-address-ex").ok()]); + .signing_keys(vec![fee_payer]); ``` \ No newline at end of file From dec293fd7a07a1981420dc5f76bb10ce6b1beca2 Mon Sep 17 00:00:00 2001 From: the-laziest Date: Thu, 11 Apr 2024 02:27:37 +0200 Subject: [PATCH 63/94] Adding info about shielded sync --- .../pages/users/shielded-accounts/shielded-transfers.mdx | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/packages/docs/pages/users/shielded-accounts/shielded-transfers.mdx b/packages/docs/pages/users/shielded-accounts/shielded-transfers.mdx index c5c7a8a9..452f0ceb 100644 --- a/packages/docs/pages/users/shielded-accounts/shielded-transfers.mdx +++ b/packages/docs/pages/users/shielded-accounts/shielded-transfers.mdx @@ -73,6 +73,12 @@ balance: namadac balance --owner ``` +In order to view actual and updated spending key's balance, one have to run shielded sync: + +```shell copy +namadac shielded-sync --from-height +``` + ### Shielded transfers Once the user has a shielded balance, it can be transferred to a From 3f300cf3ff5918c4d62a582e3d8bccdb935ec229 Mon Sep 17 00:00:00 2001 From: the-laziest Date: Thu, 11 Apr 2024 02:40:59 +0200 Subject: [PATCH 64/94] Error in PGF proposal requirements --- .../pages/modules/governance/public-goods-funding/funding.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/specs/pages/modules/governance/public-goods-funding/funding.mdx b/packages/specs/pages/modules/governance/public-goods-funding/funding.mdx index 2c471dc1..11d31623 100644 --- a/packages/specs/pages/modules/governance/public-goods-funding/funding.mdx +++ b/packages/specs/pages/modules/governance/public-goods-funding/funding.mdx @@ -79,7 +79,7 @@ For blocks of which both RPGF and CPGF funding is to be applied, RPGF is applied There is also the possibility to propose funding as a non-PGF steward. This is done by submitting the custom governance proposal `FundingProposal` through governance. The structure of the proposal is identical to the `StewardFundingProposal` except that the author of the proposal is not required to be a PGF steward, and the voting conditions differ. The proposal will be such that it **is rejected** by default **unless** the following conditions are met: - - $\frac{2}{3}$ of voting-power must vote on the `FundingProposal` + - $\frac{1}{3}$ of voting-power must vote on the `FundingProposal` - More than half of the votes must be in favor of the `FundingProposal` Note that these are the same voting conditions as the `StewardProposal` From a36d1ba0da5169d70adb456d6a0653b6e40ed7d5 Mon Sep 17 00:00:00 2001 From: Zach <56927413+zjcio@users.noreply.github.com> Date: Thu, 11 Apr 2024 13:31:54 -0600 Subject: [PATCH 65/94] Update governance.mdx Adding appropriate links to other sections. --- packages/specs/pages/modules/governance.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/specs/pages/modules/governance.mdx b/packages/specs/pages/modules/governance.mdx index 4d66c62c..6b9e4753 100644 --- a/packages/specs/pages/modules/governance.mdx +++ b/packages/specs/pages/modules/governance.mdx @@ -52,12 +52,12 @@ Further information about delegators, validators, and NAM can be found in the [p There are two ways to propose a change to the Namada protocol: -1. [**On-chain**](#on-chain-governance) - A proposal is submitted to the Namada blockchain, and the Namada blockchain handles the voting process. -2. [**Off-chain**](#off-chain-governance) - A proposal is submitted to a focal point outside of the Namada blockchain, and the voting process occurs off-chain. +1. [**On-chain**](https://specs.namada.net/modules/governance/on-chain) - A proposal is submitted to the Namada blockchain, and the Namada blockchain handles the voting process. +2. [**Off-chain**](https://specs.namada.net/modules/governance/off-chain) - A proposal is submitted to a focal point outside of the Namada blockchain, and the voting process occurs off-chain. ## Spam resistance Namada governance implements a spam resistance mechanism to prevent the network from being spammed with proposals. This mechanism is based on the fact that a proposal must be submitted with a deposit of `NAM` tokens. This deposit is returned to the proposer if the proposal is accepted, and burned otherwise. -This is only possible if the proposal is submitted on-chain, as off-chain proposals are not able to submit a deposit. \ No newline at end of file +This is only possible if the proposal is submitted on-chain, as off-chain proposals are not able to submit a deposit. From 577fff158b1337e11470dcab7a1944d65845b832 Mon Sep 17 00:00:00 2001 From: Christopher Goes Date: Mon, 22 Apr 2024 08:47:52 +0200 Subject: [PATCH 66/94] Add components + state --- packages/specs/pages/_meta.json | 1 + packages/specs/pages/base-ledger.mdx | 3 +- packages/specs/pages/base-ledger/_meta.json | 5 +- packages/specs/pages/base-ledger/state.mdx | 4 + packages/specs/pages/components.mdx | 9 ++ packages/specs/pages/components/_meta.json | 3 + packages/specs/pages/components/address.mdx | 0 packages/specs/pages/components/decimal.mdx | 0 packages/specs/pages/components/event.mdx | 0 packages/specs/pages/components/key.mdx | 0 .../specs/pages/components/pd-controller.mdx | 1 + packages/specs/pages/components/uint.mdx | 0 packages/specs/pages/index.mdx | 11 +- .../ethereum-bridge/design-rationale.mdx | 30 +++++ .../modules/ethereum-bridge/vp-logic.mdx | 5 + .../modules/governance/design-rationale.mdx | 20 +++ .../modules/governance/storage-layout.mdx | 30 +++++ .../pages/modules/governance/vp-logic.mdx | 114 ++++++++++++++++++ .../pages/modules/ibc/design-rationale.mdx | 5 + .../pages/modules/ibc/storage-layout.mdx | 7 ++ packages/specs/pages/modules/ibc/vp-logic.mdx | 5 + .../pages/modules/masp/design-rationale.mdx | 6 + 22 files changed, 247 insertions(+), 12 deletions(-) create mode 100644 packages/specs/pages/base-ledger/state.mdx create mode 100644 packages/specs/pages/components.mdx create mode 100644 packages/specs/pages/components/_meta.json create mode 100644 packages/specs/pages/components/address.mdx create mode 100644 packages/specs/pages/components/decimal.mdx create mode 100644 packages/specs/pages/components/event.mdx create mode 100644 packages/specs/pages/components/key.mdx create mode 100644 packages/specs/pages/components/pd-controller.mdx create mode 100644 packages/specs/pages/components/uint.mdx create mode 100644 packages/specs/pages/modules/ethereum-bridge/design-rationale.mdx create mode 100644 packages/specs/pages/modules/ethereum-bridge/vp-logic.mdx create mode 100644 packages/specs/pages/modules/governance/design-rationale.mdx create mode 100644 packages/specs/pages/modules/governance/storage-layout.mdx create mode 100644 packages/specs/pages/modules/governance/vp-logic.mdx create mode 100644 packages/specs/pages/modules/ibc/design-rationale.mdx create mode 100644 packages/specs/pages/modules/ibc/storage-layout.mdx create mode 100644 packages/specs/pages/modules/ibc/vp-logic.mdx create mode 100644 packages/specs/pages/modules/masp/design-rationale.mdx diff --git a/packages/specs/pages/_meta.json b/packages/specs/pages/_meta.json index cbe2596b..f98856c1 100644 --- a/packages/specs/pages/_meta.json +++ b/packages/specs/pages/_meta.json @@ -1,6 +1,7 @@ { "index": "Introduction", "base-ledger": "Base ledger", + "components": "Components", "modules": "Modules", "further-reading": "Further reading" } diff --git a/packages/specs/pages/base-ledger.mdx b/packages/specs/pages/base-ledger.mdx index 90fd38de..ab529e79 100644 --- a/packages/specs/pages/base-ledger.mdx +++ b/packages/specs/pages/base-ledger.mdx @@ -5,4 +5,5 @@ The base ledger of Namada includes: - a validity-predicate-based [execution model](./base-ledger/execution.mdx) where a "valid state" is defined as that which satisfies a set of boolean conditions; - a [replay protection system](./base-ledger/replay-protection.mdx) which prevents transactions from being executed multiple times; - a [block space allocator](./base-ledger/block-space-allocator.mdx) which packs transactions into blocks; and -- a [fee system](./base-ledger/fee-system.mdx) which provides for efficient, DoS-resistant allocation of computational and storage resources within blocks \ No newline at end of file +- a [fee system](./base-ledger/fee-system.mdx) which provides for efficient, DoS-resistant allocation of computational and storage resources within blocks +- a [state system](./base-ledger/state.mdx) which provides for encoding and Merkleization of the state machine state \ No newline at end of file diff --git a/packages/specs/pages/base-ledger/_meta.json b/packages/specs/pages/base-ledger/_meta.json index 45f6354a..7ee28975 100644 --- a/packages/specs/pages/base-ledger/_meta.json +++ b/packages/specs/pages/base-ledger/_meta.json @@ -3,5 +3,6 @@ "execution": "Execution model", "replay-protection": "Replay protection", "block-space-allocator": "Block space allocator", - "fee-system": "Fee system" -} + "fee-system": "Fee system", + "state": "State" +} \ No newline at end of file diff --git a/packages/specs/pages/base-ledger/state.mdx b/packages/specs/pages/base-ledger/state.mdx new file mode 100644 index 00000000..169c2b6c --- /dev/null +++ b/packages/specs/pages/base-ledger/state.mdx @@ -0,0 +1,4 @@ +# State + +- explain basic interface of state abstraction +- explain Merkleization \ No newline at end of file diff --git a/packages/specs/pages/components.mdx b/packages/specs/pages/components.mdx new file mode 100644 index 00000000..121bf642 --- /dev/null +++ b/packages/specs/pages/components.mdx @@ -0,0 +1,9 @@ +# Components + +Shared components of Namada include: +- [Address](./components/address.mdx) +- [Decimal](./components/decimal.mdx) +- [Event](./components/event.mdx) +- [Key](./components/key.mdx) +- [PD controller](./components/pd-controller.mdx) +- [Uint](./components/uint.mdx) \ No newline at end of file diff --git a/packages/specs/pages/components/_meta.json b/packages/specs/pages/components/_meta.json new file mode 100644 index 00000000..a91004ff --- /dev/null +++ b/packages/specs/pages/components/_meta.json @@ -0,0 +1,3 @@ +{ + "pd-controller": "PD controller" +} \ No newline at end of file diff --git a/packages/specs/pages/components/address.mdx b/packages/specs/pages/components/address.mdx new file mode 100644 index 00000000..e69de29b diff --git a/packages/specs/pages/components/decimal.mdx b/packages/specs/pages/components/decimal.mdx new file mode 100644 index 00000000..e69de29b diff --git a/packages/specs/pages/components/event.mdx b/packages/specs/pages/components/event.mdx new file mode 100644 index 00000000..e69de29b diff --git a/packages/specs/pages/components/key.mdx b/packages/specs/pages/components/key.mdx new file mode 100644 index 00000000..e69de29b diff --git a/packages/specs/pages/components/pd-controller.mdx b/packages/specs/pages/components/pd-controller.mdx new file mode 100644 index 00000000..36b3ecc0 --- /dev/null +++ b/packages/specs/pages/components/pd-controller.mdx @@ -0,0 +1 @@ +# PD controller \ No newline at end of file diff --git a/packages/specs/pages/components/uint.mdx b/packages/specs/pages/components/uint.mdx new file mode 100644 index 00000000..e69de29b diff --git a/packages/specs/pages/index.mdx b/packages/specs/pages/index.mdx index b5be19db..4b98711a 100644 --- a/packages/specs/pages/index.mdx +++ b/packages/specs/pages/index.mdx @@ -17,14 +17,6 @@ Namada also supports shielded actions, which allow users to hold their assets sh You can find an introduction to Namada from a product perspective [here](https://namada.net/blog/introducing-namada-multichain-asset-agnostic-data-protection). -### What is Anoma? - -Anoma is an intent-centric architecture for decentralized counterparty discovery, solving, and settlement. You can find the Anoma specs [here](https://specs.anoma.net). - -### How does Namada relate to Anoma? - -Anoma is a full-stack architecture designed with a long term perspective, while Namada is a specific chain and featureset designed to provide practical data protection now. - ### Why Namada? Data protection should be default and inherent in the systems we use for transacting, yet safe and user-friendly multi-asset data protection doesn't yet exist in the blockchain ecosystem. @@ -41,8 +33,9 @@ Users of Namada earn rewards for shieldiing assets and contributing to shared da These documents describe the behavior of the Namada protocol. This description is organized into five sub-sections: 1. [Base Ledger](./base-ledger.mdx): This section describes the core ledger functionality of the Namada protocol. This includes the consensus, execution model, fee system, and environment in which modules operate. +2. [Components](./components.md): This section describes components (specific abstractions) shared by multiple Namada modules. This includes the PD controller. 2. [Modules](./modules.mdx): This section describes the modules that make up the Namada protocol. Each module is a distinct part of the protocol grouping a related set of features that can be understood in isolation from other modules. This book is written using [NextraJS](https://nextra.site/). The source can be found in the [Namada Docs repository](https://github.com/anoma/namada-docs/tree/master/packages/specs). -Contributions to the contents and the structure of this book should be made via [pull requests](https://github.com/anoma/namada-docs/pulls). +Contributions to the contents and the structure of this book should be made via [pull requests](https://github.com/anoma/namada-docs/pulls). \ No newline at end of file diff --git a/packages/specs/pages/modules/ethereum-bridge/design-rationale.mdx b/packages/specs/pages/modules/ethereum-bridge/design-rationale.mdx new file mode 100644 index 00000000..82bc5e60 --- /dev/null +++ b/packages/specs/pages/modules/ethereum-bridge/design-rationale.mdx @@ -0,0 +1,30 @@ +import { Callout } from 'nextra-theme-docs' + +## Design + +The Namada Ethereum bridge system consists of: + +* A set of Ethereum smart contracts. +* An Ethereum full node run by each Namada validator, to watch Ethereum events emitted by the bridge's smart contracts. +* A set of validity predicates (VPs) on Namada. + + A Bridge pool VP, to validate transfers to Ethereum and escrowed NAM. + + An Ethereum bridge VP, to protect writes to Namada storage key sub-spaces containing Ethereum event tallies. +* Two relayer utilities, to call the Ethereum smart contracts. + + One for performing validator set updates on the Ethereum smart contracts. + + Another to aid in submitting batches of transactions to Ethereum. + +This basic bridge architecture should provide for almost-Namada consensus +security for the bridge and free Ethereum state reads on Namada, plus +bidirectional message passing with reasonably low gas costs on the +Ethereum side. + +### Security + +On Namada, the validators are full nodes of Ethereum and their stake is also +accounting for security of the bridge. If they carry out a forking attack +on Namada to steal locked tokens of Ethereum their stake will be slashed on Namada. +On the Ethereum side, there exists a limit to the amount of assets that can be +locked to limit the damage a forking attack on Namada can do. To make an attack +more cumbersome there also exists a limit on how fast wrapped Ethereum assets can +be redeemed from Namada. This does not add more security, but rather makes the +attack more inconvenient, and allows governance time to react. diff --git a/packages/specs/pages/modules/ethereum-bridge/vp-logic.mdx b/packages/specs/pages/modules/ethereum-bridge/vp-logic.mdx new file mode 100644 index 00000000..68a6cecc --- /dev/null +++ b/packages/specs/pages/modules/ethereum-bridge/vp-logic.mdx @@ -0,0 +1,5 @@ +import { Callout } from 'nextra-theme-docs' + +## VP logic + +Placeholder \ No newline at end of file diff --git a/packages/specs/pages/modules/governance/design-rationale.mdx b/packages/specs/pages/modules/governance/design-rationale.mdx new file mode 100644 index 00000000..c22bfa5c --- /dev/null +++ b/packages/specs/pages/modules/governance/design-rationale.mdx @@ -0,0 +1,20 @@ +import { Callout } from 'nextra-theme-docs' + +## Design Rationale + +There are two ways to propose a change to the Namada protocol: + +1. **On-chain** - A proposal is submitted to the Namada blockchain, and the Namada blockchain handles the voting process. +2. **Off-chain** - A proposal is submitted to a focal point outside of the Namada blockchain, and the voting process occurs off-chain. + +## Public Goods Funding + +A special type of on-chain proposal is the public goods funding proposal. It is described in more detail under the [Public Goods Funding](./design/public-goods-funding.mdx) section. + +## Spam resistance + +Namada governance implements a spam resistance mechanism to prevent the network from being spammed with proposals. +This mechanism is based on the fact that a proposal must be submitted with a deposit of `NAM` tokens. +This deposit is returned to the proposer if the proposal is accepted, and burned otherwise. +This is only possible if the proposal is submitted on-chain, as off-chain proposals are not able to submit a deposit. + diff --git a/packages/specs/pages/modules/governance/storage-layout.mdx b/packages/specs/pages/modules/governance/storage-layout.mdx new file mode 100644 index 00000000..a078a4b3 --- /dev/null +++ b/packages/specs/pages/modules/governance/storage-layout.mdx @@ -0,0 +1,30 @@ +import { Callout } from 'nextra-theme-docs' + +## Storage keys + +### On-chain `Proposals` + + + +### Offline proposals + +Offline proposals are represented as JSON objects with the following structure: + +``` +{ + content: Base64>, + author: Address, + tallyEpoch: Epoch, + signature: Base64> +} +``` + +The signature is produced over the hash of the concatenation of: `content`, `author`, and `tallyEpoch`. +Proposal types are not supported off-chain. + +#### Proposal fields + +- `content`: The proposal content (encoded). This is the actual proposal that will be voted on. +- `author`: The address of the proposal author. +- `tallyEpoch`: The epoch in which the proposal will be tallied. This epoch must already exist when tallying occurs. If the chain is halted, this means choosing an epoch in the past (e.g. the most recent epoch). +- `signature`: The signature of the proposal author over the hash of the concatenation of: `content`, `author`, and `tallyEpoch` diff --git a/packages/specs/pages/modules/governance/vp-logic.mdx b/packages/specs/pages/modules/governance/vp-logic.mdx new file mode 100644 index 00000000..a08fbd5a --- /dev/null +++ b/packages/specs/pages/modules/governance/vp-logic.mdx @@ -0,0 +1,114 @@ +import { Callout } from 'nextra-theme-docs' + +## VP logic + +## Governance Address + +All on-chain governance mechanisms are handled under a single address, referred to as the `GovernanceAddress`. +The `GovernanceAddress` is created during genesis, and handles the verification of submitted proposals, the tallying of votes, and the execution of proposals. +This address also stores all previous proposals under its address space. + +Proposals are submitted through the client, and are verified by the `GovernanceAddress` before being added to the pending proposals list. + +The structure of proposals is outlined [here](./proposal.mdx). + + +The correct logic to handle these different types is hardcoded in protocol. +We'll also rely on type checking to strictly enforce the correctness of a proposal given its type. +These two approaches combined will prevent a user from deviating from the intended logic for a certain proposal type (e.g. providing a wasm code when it's not needed or allowing only validators to vote when also delegators should, etc...). +More details on the specific types supported can be found in the [relative](#supported-proposal-types) section of the [proposals page](./proposal.mdx). + + +### GovernanceAddress VP + +The `GovernanceAddress` validity predicate (VP) task is to check the integrity and correctness of new proposals. + +#### Submission validation +A proposal must satisfy the following mandatory storage writes: + +- `counter` - The number of proposals submitted so far +- `author` - The address of the author of the proposal +- `type` - The [proposal type](./proposal.mdx#supported-proposal-types) +- `funds` - The amount of funds locked for this proposal +- `voting_start` - The epoch specifying when the voting period starts +- `voting_end`- The epoch specifying when the voting period ends +- `grace_epoch` - The epoch specifying when the proposal becomes active, (and attached WASM code is executed if any), given that the proposal has a positive outcome. + +Further, it must check that the proposal satisfies the following constraints: +- The attached `funds` is >= `min_proposal_fund`, a protocol parameter +- The `id` of the proposal is unique +- The attached `ProposalType` is supported by the protocol +- The difference between StartEpoch and EndEpoch is >= `min_proposal_period` +- There is an attached `description` of the proposal with character length < `max_proposal_content_size` +- The difference between the `voting_end` and `voting_start` epoch must be divisible by 3, i.e `(EndEpoch - StartEpoch) % 3 == 0`. +- The difference between `grace_epoch` and `voting_end` is of at least `min_proposal_grace_epochs`, a protocol parameter. +The reason for this constraint is explained below. + +#### Voting validation + +Once a proposal has been accepted by the protocol as valid, it will be added to the pending proposals list, and delegators and delegates will be able to vote on it. +The VP must also check that voting adheres to the following constraints: + +- The voter is a delegator or a delegate (further constraints can be applied depending on the proposal type) +- Given that non-validating accounts can vote, validators may only vote during the initial $\frac{2}{3}$ of the whole proposal duration (`voting_end` - `voting_start`) + +Once a proposal has been created, nobody can modify any of its fields. + +#### Execution of WASM code + +The VP is also responsible for handling the execution of WASM code attached to a `DefaultProposal` proposal type. + +Examples of such code execution could be: +- storage writes to change some protocol parameter +- storage writes to restore a slash + +This means that corresponding VPs will also be invoked. + + +## Tallying votes + +Proposals are tallied at the start of their `grace_epoch` during the `finalize_block` function. +The tallying is based off of the votes collected at the end of the `voting_end` epoch. +If the threshold specified by the ProposalType is reached, the proposal will be considered successful. + +There are two types of thresholds: + - Fraction of total staked `NAM` that voted - This checks whether enough staked `NAM` voted for the proposal at all. + - Fraction of votes in favor of the proposal - This checks whether enough votes (weighted by their staked `NAM`) voted in favor of the proposal, out of the staked `NAM` that did vote. + +E.g if the thresholds, respectively, are $\frac{1}{2}$ and $\frac{1}{3}$, then at least 50% of the total staked `NAM` must have voted for the proposal AND out of this NAM, to be accepted. + +Tallying is computed with the following rules: + + + +1. Sum all the voting power of delegates that voted `Yay`, call this sum `SumYay` +2. Sum all the voting power of delegates that voted `Nay`, call this sum `SumNay` +3. Sum all the voting power of delegates that voted `Abstain`, call this sum `SumAbstain` +4. Check if the sum `SumYay` + `SumNay` + `SumAbstain` meets the first threshold, if not, the proposal outcome is negative +5. For any delegate that voted `Yay`, subtract the voting power of any delegator that voted other than `Yay` from `SumYay` +6. For any delegate that voted `Nay`, subtract the voting power of any delegator that voted other than `Nay` from `SumNay` +7. For any delegate that voted `Abstain`, subtract the voting power of any delegator that voted other than `Abstain` from `SumAbstain` +8. Add voting power for any delegation that voted `Yay` (whose corresponding delegate didn't vote `Yay`) to `SumYay` +9. Add voting power for any delegation that voted `Nay` (whose corresponding delegate didn't vote `Nay`) to `SumNay` +9. Add voting power for any delegation that voted `Abstain` (whose corresponding delegate didn't vote `Abstain`) to `SumAbstain` +10. Set `SumYeaOrNay` to `SumYay` + `SumNay` +11. Decide whether or not the proposal succeeds based on the proposal-type-specific tally instructions (see [Proposal](./proposal.mdx)) + + + +All the computation is done at the start of `grace_epoch` on data collected at the epoch specified in the `voting-end` field of the proposal. + +## Tallying votes offline + +Offline votes are tallied under the same mechanism as on-chain vote tallying, but instead of reading the data from storage it will require a list of serialized json votes. +The voting power for each delegate/delegator is calculated based on their respective bonded-stake from the latest block in that epoch (in principle it could be any block in the epoch, since voting-power does not change within an epoch). + +### Refund and Proposal Execution mechanism + +In parallel to tallying, the protocol manages the execution of accepted proposals and refunding in the `finalize_block` function. +If the proposals `grace_epoch` matches with the current epoch, AND the proposal had a positive outcome, the protocol refunds the locked funds from `GovernanceAddress` to the proposal author address (specified in the proposal `author` field). +Moreover, if the proposal had a positive outcome and had attached WASM code, the code is executed immediately. + +On the other hand, should the proposal be rejected (negative outcome), any locked funds is burnt (removed from total supply). + +The result is then signaled by creating and inserting a [`CometBFT Event`](https://github.com/cometbft/cometbft/blob/main/spec/abci/abci%2B%2B_basic_concepts.md#events). diff --git a/packages/specs/pages/modules/ibc/design-rationale.mdx b/packages/specs/pages/modules/ibc/design-rationale.mdx new file mode 100644 index 00000000..85685d37 --- /dev/null +++ b/packages/specs/pages/modules/ibc/design-rationale.mdx @@ -0,0 +1,5 @@ +import { Callout } from 'nextra-theme-docs' + +## Design Rationale + +Placeholder \ No newline at end of file diff --git a/packages/specs/pages/modules/ibc/storage-layout.mdx b/packages/specs/pages/modules/ibc/storage-layout.mdx new file mode 100644 index 00000000..8382d548 --- /dev/null +++ b/packages/specs/pages/modules/ibc/storage-layout.mdx @@ -0,0 +1,7 @@ +import { Callout } from 'nextra-theme-docs' + +## Storage keys + +A token balance is stored with a storage key. The token balance key should be `#Multitoken/{token_addr}/balance/{owner_addr}`. These keys can be made with [token functions](https://github.com/anoma/namada/blob/5da82f093f10c0381865accba99f60c557360c51/core/src/types/token.rs). + +Namada stores multitoken balances for the same owner by `{token_addr}`, e.g. a token received over IBC is managed in `#Multitoken/{ibc_token}/balance/{receiver_addr}`. It is distinguished from the receiver's original balance in `#Multitoken/{token_addr}/balance/{receiver_addr}` to know which chain the token was transferred from. The `{ibc_token}` is explained in [IBC](../../modules/ibc.mdx). \ No newline at end of file diff --git a/packages/specs/pages/modules/ibc/vp-logic.mdx b/packages/specs/pages/modules/ibc/vp-logic.mdx new file mode 100644 index 00000000..68a6cecc --- /dev/null +++ b/packages/specs/pages/modules/ibc/vp-logic.mdx @@ -0,0 +1,5 @@ +import { Callout } from 'nextra-theme-docs' + +## VP logic + +Placeholder \ No newline at end of file diff --git a/packages/specs/pages/modules/masp/design-rationale.mdx b/packages/specs/pages/modules/masp/design-rationale.mdx new file mode 100644 index 00000000..d2129533 --- /dev/null +++ b/packages/specs/pages/modules/masp/design-rationale.mdx @@ -0,0 +1,6 @@ +import { Callout } from 'nextra-theme-docs' + +## Design Rationale + +- [Convert Circuit](./design/convert-circuit.mdx) +- [Burn and mint][./design/burn-and-mint.mdx] \ No newline at end of file From d87bdba3d4d302a697b220d96832c1d8750af391 Mon Sep 17 00:00:00 2001 From: nuts-rice Date: Mon, 13 May 2024 08:40:53 -0400 Subject: [PATCH 67/94] Update source.mdx Fixed link to testnet docs --- packages/docs/pages/introduction/install/source.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/docs/pages/introduction/install/source.mdx b/packages/docs/pages/introduction/install/source.mdx index 4f3d587e..6ece0dfe 100644 --- a/packages/docs/pages/introduction/install/source.mdx +++ b/packages/docs/pages/introduction/install/source.mdx @@ -21,7 +21,7 @@ make install During internal and private testnets, checkout the latest testnet branch using `git checkout $NAMADA_TESTNET_BRANCH`. -Where `$NAMADA_TESTNET_BRANCH` is the name of the testnet branch, which will be specified in the [testnet documentation](../testnets/environment-setup.mdx). +Where `$NAMADA_TESTNET_BRANCH` is the name of the testnet branch, which will be specified in the [testnet documentation](../../../networks/testnets.mdx). ## Adding binaries to `$PATH` @@ -37,4 +37,4 @@ cp namada/target/release/namada* $HOME/.local/bin/ See the page on [using namada binaries](./binaries/overview-of-binaries.mdx) for more information. ## Troubleshooting -Please see the troubleshooting page for [building from source](./source/troubleshooting.mdx) for more information. \ No newline at end of file +Please see the troubleshooting page for [building from source](./source/troubleshooting.mdx) for more information. From b7171f7d4891c24b840a6696412acd2bc74fbcb9 Mon Sep 17 00:00:00 2001 From: nuts-rice Date: Mon, 13 May 2024 12:57:46 +0000 Subject: [PATCH 68/94] actually fix link --- packages/docs/pages/introduction/install/source.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/docs/pages/introduction/install/source.mdx b/packages/docs/pages/introduction/install/source.mdx index 6ece0dfe..ff0b80de 100644 --- a/packages/docs/pages/introduction/install/source.mdx +++ b/packages/docs/pages/introduction/install/source.mdx @@ -21,7 +21,7 @@ make install During internal and private testnets, checkout the latest testnet branch using `git checkout $NAMADA_TESTNET_BRANCH`. -Where `$NAMADA_TESTNET_BRANCH` is the name of the testnet branch, which will be specified in the [testnet documentation](../../../networks/testnets.mdx). +Where `$NAMADA_TESTNET_BRANCH` is the name of the testnet branch, which will be specified in the [testnet documentation](../../networks/testnets.mdx). ## Adding binaries to `$PATH` From 140c73926c833dd808976f01b6292b351c5e0b8d Mon Sep 17 00:00:00 2001 From: Christopher Goes Date: Sat, 18 May 2024 12:28:08 +0200 Subject: [PATCH 69/94] Update packages/docs/pages/users/shielded-accounts/shielded-transfers.mdx --- .../docs/pages/users/shielded-accounts/shielded-transfers.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/docs/pages/users/shielded-accounts/shielded-transfers.mdx b/packages/docs/pages/users/shielded-accounts/shielded-transfers.mdx index 452f0ceb..f6391339 100644 --- a/packages/docs/pages/users/shielded-accounts/shielded-transfers.mdx +++ b/packages/docs/pages/users/shielded-accounts/shielded-transfers.mdx @@ -73,7 +73,7 @@ balance: namadac balance --owner ``` -In order to view actual and updated spending key's balance, one have to run shielded sync: +In order to view actual and updated spending key's balance, one must first run shielded sync: ```shell copy namadac shielded-sync --from-height From fcfaf6a18480861f927fba9560a4fd6a3c810472 Mon Sep 17 00:00:00 2001 From: Christopher Goes Date: Tue, 21 May 2024 19:34:34 +0200 Subject: [PATCH 70/94] Add sub-pages for proof-of-stake --- packages/specs/pages/base-ledger/state.mdx | 3 +- .../specs/pages/modules/proof-of-stake.mdx | 32 +++---------------- .../pages/modules/proof-of-stake/_meta.json | 10 +++--- .../proof-of-stake/design-overview.mdx | 29 +++++++++++++++++ .../proof-of-stake/transaction-actions.mdx | 0 .../proof-of-stake/types-and-storage.mdx | 0 .../proof-of-stake/validity-conditions.mdx | 0 7 files changed, 40 insertions(+), 34 deletions(-) create mode 100644 packages/specs/pages/modules/proof-of-stake/design-overview.mdx create mode 100644 packages/specs/pages/modules/proof-of-stake/transaction-actions.mdx create mode 100644 packages/specs/pages/modules/proof-of-stake/types-and-storage.mdx create mode 100644 packages/specs/pages/modules/proof-of-stake/validity-conditions.mdx diff --git a/packages/specs/pages/base-ledger/state.mdx b/packages/specs/pages/base-ledger/state.mdx index 169c2b6c..671f1071 100644 --- a/packages/specs/pages/base-ledger/state.mdx +++ b/packages/specs/pages/base-ledger/state.mdx @@ -1,4 +1,5 @@ # State - explain basic interface of state abstraction -- explain Merkleization \ No newline at end of file +- explain Merkleization +- explain lazy storage structures \ No newline at end of file diff --git a/packages/specs/pages/modules/proof-of-stake.mdx b/packages/specs/pages/modules/proof-of-stake.mdx index ad7b9574..e9a78309 100644 --- a/packages/specs/pages/modules/proof-of-stake.mdx +++ b/packages/specs/pages/modules/proof-of-stake.mdx @@ -2,31 +2,7 @@ This section of the specification describes the proof-of-stake mechanism of Namada, which is largely modeled after [Cosmos bonded proof-of-stake](https://github.com/cosmos/cosmos-sdk/blob/master/x/staking/spec/README.md), but makes significant changes to bond storage representation, validator set change handling, reward distribution, and slashing, with the general aims of increased precision in reasoning about security, validator decentralisation, and avoiding unnecessary proof-of-stake-related transactions. -This section is split into three subcomponents: the [bonding mechanism](./proof-of-stake/objects-and-txs.mdx), [reward distribution](./proof-of-stake/reward-distribution.mdx), and [cubic slashing](./proof-of-stake/cubic-slashing.mdx). - -## Context - -Blockchain systems rely on economic security (directly or indirectly) to -prevent -abuse and -for actors -to behave according to the 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 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 - -* **Security: Delegation and Slashing**: we want to make sure validators are - backed by enough funds to make misbehavior very expensive. Security is - achieved by punishing (slashing) if they do. *Slashing* locked funds (stake) - intends to disincentivize diverging from correct execution of protocol, - which in this case is voting to finalize valid blocks. -* **Liveness: Paying Rewards**. For continued operation of Namada we want to incentivize participating in consensus and delegation, which helps security. - -### Security - -In blockchain systems we do not rely on altruistic behavior but rather economic -security. We expect the validators to execute the protocol correctly. They get rewarded for doing so and punished otherwise. Each validator has some self-stake and some stake that is delegated to it by other token holders. The validator and delegators share the reward and risk of slashing impact with each other. - -The total stake behind consensus should be taken into account when value is transferred via a transaction. For example, if we have 1 billion tokens, we aim that 300 Million of these tokens is backing validators. This means that users should not transfer more than 200 million of this token within a block. +- [Design overview](proof-of-stake/design-overview.mdx) +- [Types and storage](proof-of-stake/types-and-storage.mdx) +- [Validity conditions](proof-of-stake/validity-conditions.mdx) +- [Transaction actions](proof-of-stake/transaction-actions.mdx) \ No newline at end of file diff --git a/packages/specs/pages/modules/proof-of-stake/_meta.json b/packages/specs/pages/modules/proof-of-stake/_meta.json index aaf43f4b..e4a52fd2 100644 --- a/packages/specs/pages/modules/proof-of-stake/_meta.json +++ b/packages/specs/pages/modules/proof-of-stake/_meta.json @@ -1,6 +1,6 @@ { - "objects-and-txs": "Objects and Txs", - "cubic-slashing": "Cubic slashing", - "reward-distribution": "Reward distribution", - "inflation-system": "Inflation system" -} + "design-overview": "Design overview", + "types-and-storage": "Types and storage", + "validity-conditions": "Validity conditions", + "transaction-actions": "Transaction actions" +} \ No newline at end of file diff --git a/packages/specs/pages/modules/proof-of-stake/design-overview.mdx b/packages/specs/pages/modules/proof-of-stake/design-overview.mdx new file mode 100644 index 00000000..28382722 --- /dev/null +++ b/packages/specs/pages/modules/proof-of-stake/design-overview.mdx @@ -0,0 +1,29 @@ + +This section is split into three subcomponents: the [bonding mechanism](./proof-of-stake/objects-and-txs.mdx), [reward distribution](./proof-of-stake/reward-distribution.mdx), and [cubic slashing](./proof-of-stake/cubic-slashing.mdx). + +## Context + +Blockchain systems rely on economic security (directly or indirectly) to +prevent +abuse and +for actors +to behave according to the 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 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 + +* **Security: Delegation and Slashing**: we want to make sure validators are + backed by enough funds to make misbehavior very expensive. Security is + achieved by punishing (slashing) if they do. *Slashing* locked funds (stake) + intends to disincentivize diverging from correct execution of protocol, + which in this case is voting to finalize valid blocks. +* **Liveness: Paying Rewards**. For continued operation of Namada we want to incentivize participating in consensus and delegation, which helps security. + +### Security + +In blockchain systems we do not rely on altruistic behavior but rather economic +security. We expect the validators to execute the protocol correctly. They get rewarded for doing so and punished otherwise. Each validator has some self-stake and some stake that is delegated to it by other token holders. The validator and delegators share the reward and risk of slashing impact with each other. + +The total stake behind consensus should be taken into account when value is transferred via a transaction. For example, if we have 1 billion tokens, we aim that 300 Million of these tokens is backing validators. This means that users should not transfer more than 200 million of this token within a block. \ No newline at end of file diff --git a/packages/specs/pages/modules/proof-of-stake/transaction-actions.mdx b/packages/specs/pages/modules/proof-of-stake/transaction-actions.mdx new file mode 100644 index 00000000..e69de29b diff --git a/packages/specs/pages/modules/proof-of-stake/types-and-storage.mdx b/packages/specs/pages/modules/proof-of-stake/types-and-storage.mdx new file mode 100644 index 00000000..e69de29b diff --git a/packages/specs/pages/modules/proof-of-stake/validity-conditions.mdx b/packages/specs/pages/modules/proof-of-stake/validity-conditions.mdx new file mode 100644 index 00000000..e69de29b From e053d7815f3bd7f676f4c56414ccebee35c9213c Mon Sep 17 00:00:00 2001 From: mariari Date: Mon, 27 May 2024 20:49:02 +0800 Subject: [PATCH 71/94] Remove flags which do not work with the newest gen_localnet.py script The script does not take num-nodes and num-vals... So we simply remove them from the example given --- packages/docs/pages/operators/networks/local-network.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/packages/docs/pages/operators/networks/local-network.mdx b/packages/docs/pages/operators/networks/local-network.mdx index d300d80d..e0fc7ea6 100644 --- a/packages/docs/pages/operators/networks/local-network.mdx +++ b/packages/docs/pages/operators/networks/local-network.mdx @@ -55,10 +55,8 @@ For example, a MacOS user would run something along the lines of: python3 ./scripts/gen_localnet.py \ --localnet-dir genesis/localnet \ --mode release # Assuming the binaries were built using `make build-release` \ ---parameters '{"parameters": {"max_expected_time_per_block": 10}, "pos_params": {"pipeline_len": 5}}' +--parameters '{"parameters": {"max_expected_time_per_block": 10}, "pos_params": {"pipeline_len": 5}}' # In order to change max_expected_time_per_block to 10 seconds from the default 30, and the pipeline length to 5 epochs from the default 2. ---num-nodes 2 # OPTIONAL: To run the localnet with 2 nodes ---num-vals 2 # OPTIONAL: To run the localnet with 2 validators ``` ### Modifying the genesis configuration file From 6f0eaaeec767b22bc5edfc1cc01757b9fe3b6d6c Mon Sep 17 00:00:00 2001 From: iskay Date: Wed, 29 May 2024 13:28:18 -0400 Subject: [PATCH 72/94] update getting started section and campfire --- packages/docs/pages/introduction/_meta.json | 3 +- packages/docs/pages/introduction/install.mdx | 2 +- .../pages/introduction/install/binaries.mdx | 4 +- .../pages/introduction/install/docker.mdx | 26 +++++-- .../pages/introduction/install/source.mdx | 16 ++-- .../install/source/troubleshooting.mdx | 2 +- .../introduction/installing-cometbft.mdx | 15 ++-- .../pages/introduction/protocol-intro.mdx | 21 +++--- .../docs/pages/introduction/public-rpc.mdx | 25 +++++++ .../docs/pages/introduction/quick-start.mdx | 40 ++++++---- .../docs/pages/networks/testnets/_meta.json | 2 +- .../docs/pages/networks/testnets/campfire.mdx | 73 ++++++++++++++----- packages/docs/pages/networks/testnets/faq.mdx | 4 +- .../docs/pages/networks/testnets/faucet.mdx | 15 ++++ packages/docs/pages/networks/testnets/pow.mdx | 16 ---- packages/docs/pages/users/fees.mdx | 2 +- 16 files changed, 178 insertions(+), 88 deletions(-) create mode 100644 packages/docs/pages/introduction/public-rpc.mdx create mode 100644 packages/docs/pages/networks/testnets/faucet.mdx delete mode 100644 packages/docs/pages/networks/testnets/pow.mdx diff --git a/packages/docs/pages/introduction/_meta.json b/packages/docs/pages/introduction/_meta.json index 56848f37..ab217c63 100644 --- a/packages/docs/pages/introduction/_meta.json +++ b/packages/docs/pages/introduction/_meta.json @@ -3,5 +3,6 @@ "install": "Installing Namada", "installing-cometbft": "Installing CometBFT", "privacy": "Privacy and Opsec", - "security": "Security" + "security": "Security", + "public-rpc": "Using a Public RPC" } \ No newline at end of file diff --git a/packages/docs/pages/introduction/install.mdx b/packages/docs/pages/introduction/install.mdx index 8a345f59..09677858 100644 --- a/packages/docs/pages/introduction/install.mdx +++ b/packages/docs/pages/introduction/install.mdx @@ -3,7 +3,7 @@ import { Callout } from 'nextra-theme-docs' # Install Namada -At the moment, Namada only supports Linux and MacOS. +While Windows binaries are available, we recommend using Linux or MacOS with Namada. ## Installing Namada diff --git a/packages/docs/pages/introduction/install/binaries.mdx b/packages/docs/pages/introduction/install/binaries.mdx index 048d674a..b5803a87 100644 --- a/packages/docs/pages/introduction/install/binaries.mdx +++ b/packages/docs/pages/introduction/install/binaries.mdx @@ -26,8 +26,8 @@ Unzip the `tar` using the following command: tar -xzvf namada*.tar.gz ``` -## Placing the binaries onto `$PATH` -For ubuntu and mac machines, the following command should work for placing namada into path. +## Placing the binaries into `$PATH` +For Ubuntu and Mac machines, the following command should work for placing the Namada binaries into your `$PATH`. Once inside the directory containing the binaries: ```bash copy diff --git a/packages/docs/pages/introduction/install/docker.mdx b/packages/docs/pages/introduction/install/docker.mdx index a967f76c..9c9ba789 100644 --- a/packages/docs/pages/introduction/install/docker.mdx +++ b/packages/docs/pages/introduction/install/docker.mdx @@ -1,26 +1,38 @@ -# From Docker +# Running Namada with Docker ## Pre-requisites -In order to run any docker images, you need to have docker installed. You can find instructions on how to install docker for your machine [here](https://docs.docker.com/get-docker/). +In order to run any Docker images, you must first have Docker installed. You can find installation instructions for your machine [here](https://docs.docker.com/get-docker/). ## Downloading the docker image -The Namada docker image can be found [here](https://github.com/anoma/namada/pkgs/container/namada). +The Namada Docker image can be found [here](https://github.com/anoma/namada/pkgs/container/namada). -Under the `Tags` tab, you can find the latest version of the docker image. Click on the link for the correct version of Namada that you are trying to install. For example, if you are trying to install Namada v0.16.0, you would click on the link for `v0.16.0`. +Under the `Tags` tab, you can find the latest version of the Docker image. Click on the link for the correct version of Namada that you are trying to install. For example, if you are trying to install Namada v0.37.0, you would click on the link for `v0.37.0`. -You can find the tag of the downloaded docker image by running `docker images`. The tag will be the first column of the output. +To download the Docker image, run: +```bash copy +docker pull ghcr.io/anoma/namada:namada-v0.37.0 +``` + +You can list any downloaded Docker image by running `docker images`. The tag will be the first column of the output. +```bash copy +~$ docker images +REPOSITORY TAG IMAGE ID CREATED SIZE +ghcr.io/anoma/namada namada-v0.37.0 b9729acaabab 5 days ago 211MB +``` +In this case, the full name of the downloaded image is `ghcr.io/anoma/namada:namada-v0.37.0`. ## Running the docker image -Once you have downloaded the docker image, it will be useful to export some environment variables: +Once you have downloaded the Docker image, it will be useful to export some environment variables: ```bash copy export CHAIN_ID= +export DOCKER_IMAGE=ghcr.io/anoma/namada:namada-v0.37.0 ``` -The following docker run command will run the ledger node: +The following Docker run command will run the ledger node: ```bash copy docker run -P -i -t $DOCKER_IMAGE diff --git a/packages/docs/pages/introduction/install/source.mdx b/packages/docs/pages/introduction/install/source.mdx index 8fc6c0e9..c398113d 100644 --- a/packages/docs/pages/introduction/install/source.mdx +++ b/packages/docs/pages/introduction/install/source.mdx @@ -11,26 +11,32 @@ Please note that, although installing from source is the recommended route for i Ensure the correct [pre-requisites](./source/pre-requisites.mdx) have been downloaded and installed. ## Installing Namada -Once all the required dependencies have been installed, the next step is to clone the source code from the [Namada repository](https://github.com/anoma/namada) and build it with: +Once all the required dependencies have been installed, you can run the following to clone the source code from the [Namada repository](https://github.com/anoma/namada) and build it. + +When joining mainnet or a public testnet, please first refer to the network's supporting documentation (or ask in the Discord server) +to find which version of the software you will need. ```shell copy git clone https://github.com/anoma/namada.git -cd namada +cd namada +git checkout make install ``` - +{/* During internal and private testnets, checkout the latest testnet branch using `git checkout $NAMADA_TESTNET_BRANCH`. Where `$NAMADA_TESTNET_BRANCH` is the name of the testnet branch, which will be specified in the [testnet documentation](../../networks/testnets.mdx). +*/} ## Adding binaries to `$PATH` The binaries should be added to `$PATH` from the `make install` command. However, if this for some reason did not work, a solution may be to copy the binaries -from `namada/target/release` to `$HOME/.local/bin/` for example: +from `namada/target/release` to `/usr/local/bin/` for example: + ```shell copy -cp namada/target/release/namada* $HOME/.local/bin/ +cp namada/target/release/namada* /usr/local/bin/ ``` You can verify the binaries are correctly added to `$PATH` by running the command `which namada`. diff --git a/packages/docs/pages/introduction/install/source/troubleshooting.mdx b/packages/docs/pages/introduction/install/source/troubleshooting.mdx index 4432b2a6..af7741ba 100644 --- a/packages/docs/pages/introduction/install/source/troubleshooting.mdx +++ b/packages/docs/pages/introduction/install/source/troubleshooting.mdx @@ -40,7 +40,7 @@ It may be resolved by running sudo apt install build-essential ``` -Another solution can sometimes be installing `libcland-dev`. This can be achieved through: +Another solution can sometimes be installing `libclang-dev`. This can be achieved through: ```bash copy sudo apt-get update -y diff --git a/packages/docs/pages/introduction/installing-cometbft.mdx b/packages/docs/pages/introduction/installing-cometbft.mdx index 8e5b73b4..0ec71db2 100644 --- a/packages/docs/pages/introduction/installing-cometbft.mdx +++ b/packages/docs/pages/introduction/installing-cometbft.mdx @@ -1,13 +1,16 @@ # Installing CometBFT +In addition to the Namada binaries, it is required to install CometBFT before running Namada. + ## Downloading the latest release -Namada is compatible with CometBFT tag `v0.37.2` +Namada is compatible with CometBFT release `v0.37.2` -You can download the latest release from [this repository](https://github.com/cometbft/cometbft/releases/). -- The latest release is `v0.37.2` which can be installed [here](https://github.com/cometbft/cometbft/releases/tag/v0.37.2). +You can download the precompiled CometBFT binaries from their [official GitHub repository](https://github.com/cometbft/cometbft/releases/). +- Download release `v0.37.2` for use with Namada [here](https://github.com/cometbft/cometbft/releases/tag/v0.37.2). +- While newer versions may be available on the release version, these have not been tested to be fully compatible and should not be used with Namada. -## Adding the binaries to $PATH -If you have `go` installed and downloaded, you may want to add it to your `$GOPATH/bin` directory. This can be done by running the following command in the root directory of the repository +## Adding the CometBFT binary to $PATH +If you have `go` installed and downloaded, you may want to add the CometBFT binary to your `$GOPATH/bin` directory. This can be done by running the following command in the root directory of the repository ```bash copy cp $GOPATH/bin/ @@ -17,8 +20,6 @@ Otherwise, we recommend you simply copy it to your `/usr/local/bin` which may re `sudo cp /usr/local/bin/` -And enter your password when prompted. - In order to check that the installation was successful, you can run the following command ```bash copy diff --git a/packages/docs/pages/introduction/protocol-intro.mdx b/packages/docs/pages/introduction/protocol-intro.mdx index dba4e65a..0edfeb12 100644 --- a/packages/docs/pages/introduction/protocol-intro.mdx +++ b/packages/docs/pages/introduction/protocol-intro.mdx @@ -9,22 +9,22 @@ The Namada protocol is a proof-of-stake layer 1 blockchain protocol. State trans The system relies on the concept of epochs. An epoch is a range of consecutive blocks identified by consecutive natural numbers. Each epoch lasts a minimum duration and includes a minimum number of blocks since the beginning of the last epoch. These are defined by protocol parameters. -To query the current epoch, the following command can be run: +To query the epoch duration parameters, the following command can be run: ```shell copy namadac query-protocol-parameters ``` -In order to query the current epoch, the following command can be run: +In order to query the current epoch of the chain, the following command can be run: ```shell copy -namada client epoch +namadac epoch ``` ## Protocol parameters All of the current protocol parameters can be queried using the following command: ```shell copy -namada query-protocol-parameters +namadac query-protocol-parameters ``` This will display the list of protocol parameters. @@ -80,19 +80,21 @@ PoS parameters - Min. proposal fund: The minimum amount of tokens required to submit a proposal. - Max. proposal code size: The maximum size of the code that can be submitted in a proposal. -- Min. proposal voting period: The minimum duration of the voting period for a proposal. -- Max. proposal period: The maximum duration of the proposal period. +- Min. proposal voting period: The minimum duration (in epochs) of the voting period for a proposal. +- Max. proposal period: The maximum duration (in epochs) of the proposal period. - Max. proposal content size: The maximum number of characters of the content that can be submitted in a proposal. - Min. proposal grace epochs: The minimum number of epochs that a proposal can be in the grace period. -The *grace period* is defined as the epochs **between** the end of the voting period and the `grace epoch` as defined on the proposal. The grace epoch is the final epoch of the grace period. +The *grace period* is defined as the epochs **between** the end of the voting period and the `grace epoch` as defined on the proposal. The grace epoch is the final epoch of the grace period. + +Any changes enacted by a passing proposal (for example, changes to the protocol parameters) will take effect at the end of the grace period. ### Public Goods Funding Parameters -- Pgf inflation rate: The inflation rate for the Public Goods Funding. -- Steward inflation rate: The inflation rate for the Steward. +- Pgf inflation rate: The inflation rate for the Public Goods Funding -- the percentage of newly minted tokens that are allotted to the PGF treasury. +- Steward inflation rate: The inflation rate for the Steward account(s) -- the percentage of newly minted tokens allotted to funding PGF Steward operations (such as reviewing PGF recipient nominees). ### Protocol parameters @@ -120,6 +122,7 @@ The *grace period* is defined as the epochs **between** the end of the voting pe - Light client attack minimum slash rate: The minimum slashing rate for a light client attack. - Liveness window: The number of blocks that are considered for the liveness check (a slashable event), counted by number of blocks that a validator signs - Liveness threshold: The proportion (decimal) of blocks that a validator must sign within the window in order to be considered live. +Any active validator in the consensus set falling below this threshold will be jailed for inactivity. - Block proposer reward: The reward for the block proposer. - Block vote reward: The reward for the block voter. - Max inflation rate: The maximum inflation rate. diff --git a/packages/docs/pages/introduction/public-rpc.mdx b/packages/docs/pages/introduction/public-rpc.mdx new file mode 100644 index 00000000..f586c6f2 --- /dev/null +++ b/packages/docs/pages/introduction/public-rpc.mdx @@ -0,0 +1,25 @@ +import { Callout } from 'nextra-theme-docs' + +# Using a Public RPC + +Instead of syncing and operating your own node to interact with a network, most functionality of `namadac`, such as querying the chain state or submitting transactions, +can be done using a full node operated by someone else. When these nodes are provided for public use, they are commonly called 'Public RPCs' +and are generally offered by established operators as a public service. + + +When using an RPC node that is not your own, first verify that the operator can be trusted, and that the node is up to date with the rest of the chain. + + +## Using the --node flag + +These instructions assume you have already completed the steps to [install Namada](./install.mdx) and [join a network](../networks.mdx). + +From here, instead of proceeding to start the ledger and sync your node with the rest of the chain, you can use `namadac` to interact +with the network by using the `--node` flag and providing the address of a public RPC node. + +For example, to query the balance of an account using a public RPC, you can run: +```bash copy +namadac balance --owner --token nam --node https://some-node.xyz:443 +``` + +In fact, this is not fundamentally different from normal usage of `namadac` -- except that normally an rpc address of `localhost:26657` (corresponding to your own local full node) is implied. \ No newline at end of file diff --git a/packages/docs/pages/introduction/quick-start.mdx b/packages/docs/pages/introduction/quick-start.mdx index 96424445..0578941b 100644 --- a/packages/docs/pages/introduction/quick-start.mdx +++ b/packages/docs/pages/introduction/quick-start.mdx @@ -9,24 +9,30 @@ Getting started with Namada is as simple as: Install the Namada binaries (`namada`, `namadan`, `namadaw`, `namadac`) and place them in your `$PATH`. -You can [build from source](#) or [download prebuilt binaries](#) from the Releases page of the Namada Github repo. [Docker images](#) are also available. +You can [build from source](./install/source.mdx) or [download prebuilt binaries](./install/binaries.mdx) from the Releases page of the Namada Github repo. +[Docker images](./install/docker.mdx) are also available. ### Install CometBFT -[Install CometBFT](#) and place it in your `$PATH`. +Namada requires CometBFT `v0.37.2` for consensus. [Install CometBFT](./installing-cometbft.mdx) and place it in your `$PATH`. ### Join a Network See the [networks page](../networks.mdx) for details on how to join a network. Joining a network is a one-step process to download the proper genesis files, wasm code and checksums, and initialize your node's storage and configuration. -You can join a [testnet](#), [localnet](#), or (soon) [mainnet](#). +You can join a [testnet](../networks/testnets.mdx), [localnet](../operators/networks/local-network.mdx), or (soon) [mainnet](../networks/mainnets.mdx). -See [the networks page](../networks.mdx) for details on how to join a network. The rest of this guide will assume you have joined a network using the `namadac utils join-network --chain-id ` command. +You will need to know the chain-id of the network you wish to join. You can then join as a full (non-validator) node by running: +```shell copy +namadac utils join-network --chain-id --add-persistent-peers +``` + +The newly initialized chain data will be found in your [base directory](../operators/ledger/base-directory.mdx). -See [all utilities command](../utils.mdx). +(See the list of all [utilities](../utils.mdx) commands.) -## Run a ledger node +### Run a ledger node -We recommend this step with [tmux](https://www.hamvocke.com/blog/a-quick-and-easy-guide-to-tmux/), which allows the node to keep running without needing the terminal to be open indefinitely. If not, skip to the subsequent step. +You can start your node with: ```shell copy namadan ledger run @@ -37,16 +43,17 @@ For a more verbose output, one can run: ```shell copy NAMADA_LOG=info CMT_LOG_LEVEL=p2p:none,pex:error NAMADA_CMT_STDOUT=true namadan ledger run ``` -To keep your node running in the background after closing your terminal, you will likely want to use either tmux or a systemd service file. See the section on [Running a full node](#) for more detail on this, as well as configuration options and environment variables. +To keep your node running in the background after closing your terminal, you will likely want to use either tmux or a systemd service file. +See the section on [Running a full node](../operators/ledger/running-a-full-node.mdx) for more detail on this, as well as configuration options and environment variables. -Instead of syncing your own node, you can use a [public rpc](#) for most functionality. +Instead of syncing your own node, you can use a [public rpc](./public-rpc.mdx) for most functionality. ### Wait for your Node to Finish Syncing This can take several hours depending on the chain height and your system specs. ### Create an Account -Create a new implicit account in order to receive tokens: +Create a new [implicit](../users/transparent-accounts.mdx) account in order to receive tokens: ```shell copy namadaw gen --alias @@ -66,14 +73,15 @@ Known transparent addresses: ### Get Some Tokens from the Faucet (Testnet Only) -Testnet tokens can be sourced from the [faucet](https://faucet.heliax.click). +Check [here](../networks/testnets/faucet.mdx) for a list of testnet faucets. +(If your testnet is not listed, ask in the Discord server for more info.) ### Explore πŸš€ There's a variety of cool things you can do next! -- [Shield some NAM or other tokens](#) -- [Bond (delegate) some tokens to a validator](#) -- [Become a validator yourself](#) -- [Participate in governance by creating or voting on proposals](#) -- [Send or recieve tokens from another chain via IBC](#) +- [Shield some NAM or other tokens](../users/shielded-accounts/shielded-transfers.mdx) +- [Bond (delegate) some tokens to a validator](../users/delegators.mdx) +- [Become a validator yourself](../operators/validators.mdx) +- [Participate in governance by creating or voting on proposals](../users/governance.mdx) +- [Send or recieve tokens from another chain via IBC](../users/ibc.mdx) diff --git a/packages/docs/pages/networks/testnets/_meta.json b/packages/docs/pages/networks/testnets/_meta.json index 1c02070b..fa208383 100644 --- a/packages/docs/pages/networks/testnets/_meta.json +++ b/packages/docs/pages/networks/testnets/_meta.json @@ -6,7 +6,7 @@ "joining-the-testnet": "Joining the latest Testnet", "post-genesis-validator": "Becoming a validator after genesis", "testnet-history": "History of testnets", - "pow": "Using the testnet faucet", + "faucet": "Testnet faucets", "faq": "FAQ", "campfire": "Campfire Testnet" } diff --git a/packages/docs/pages/networks/testnets/campfire.mdx b/packages/docs/pages/networks/testnets/campfire.mdx index dc7c12b6..e4e2f139 100644 --- a/packages/docs/pages/networks/testnets/campfire.mdx +++ b/packages/docs/pages/networks/testnets/campfire.mdx @@ -1,4 +1,5 @@ import { Callout } from 'nextra-theme-docs' +import { Steps } from 'nextra-theme-docs' # The Namada Campfire Testnet β›ΊπŸ”₯ @@ -15,40 +16,74 @@ The most up-to-date docs on joining Campfire β›ΊπŸ”₯ can be found [here](https:/ ### Pre-requisites -Currently, Campfire β›ΊπŸ”₯ docs only detail support for Ubuntu machines. +Currently, Campfire β›ΊπŸ”₯ docs only detail support for Ubuntu machines. However, the steps should be the same for any OS which can run Namada. -The user will need to have installed the [Stack-Orchestrator](https://github.com/vknowable/stack-orchestrator), which is a general tool for quickly and flexibly launching and managing a software stack in a containerized environment. The docs are found in the [README](https://github.com/vknowable/stack-orchestrator/#readme) of the repo, and the tool can be installed by running the following command: +The user will need to have completed the steps to install [Namada](../../introduction/install.mdx) and [CometBFT](../../introduction/installing-cometbft.mdx) as per usual. +### Joining the network + + +Check the testnet [info page](https://testnet.luminara.icu) which should have all info and links needed to join the network, including +the current chain-id, peers, wasm files, etc. + +This page is automatically re-generated on chain creation so the info contained should always be current. + + +Configuring your node to join Campfire is similar to any other public testnet, with a couple minor differences. + + +### Set config server +First, set this environment variable to instruct `namadac` to download the chain configs from an alternate URL. +```bash copy +export NAMADA_NETWORK_CONFIGS_SERVER="https://testnet.luminara.icu/configs" +``` + +### Join network +Run this command to download the chain configs. Don't forget the `--dont-prefetch-wasm` flag as we'll manually download and copy +the wasm files into the chain directory in the next step. ```bash copy -git clone https://github.com/vknowable/stack-orchestrator.git -cd stack-orchestrator -scripts/namada-quick-install.sh -exit +namadac utils join-network --chain-id $CHAIN_ID --dont-prefetch-wasm ``` -Once this is completed, it is recommended to install Namada through the following Docker image (and the version in this command may need to be [updated accordingly](https://testnet.luminara.icu): +### Download and extract the chain wasm files +Download the wasm files from the link on [https://testnet.luminara.icu](https://testnet.luminara.icu) and copy them into the `wasm` +directory inside your Namada base-dir. +```bash copy +wget https://testnet.luminara.icu/wasm.tar.gz +tar -xf wasm.tar.gz +cp wasm/* ~/.local/share/namada/$CHAIN_ID/wasm/ +``` +### Update persistent peers +Check [https://testnet.luminara.icu](https://testnet.luminara.icu) for a current persistent peer (or ask in the Discord server) and +add it to your node's `config.toml` file (located at `/$CHAIN_ID/config.toml`). ```bash copy -export NAMADA_TAG=v0.23.1 -docker pull spork666/namada:$NAMADA_TAG -docker image tag spork666/namada:$NAMADA_TAG cerc/namada:local -mkdir -p ~/.local/share/namada +# actual value will be different +persistent_peers = "tcp://0e51028c038607680cde50fdb08b6931e869ce6a@143.198.36.225:26656” ``` -### Running the node +### (Optional) Sync using a snapshot +For faster syncing, you can download a recent snapshot from [https://testnet.luminara.icu](https://testnet.luminara.icu). -Once this is completed, the user can run the following command to start the node: +You will need to install lz4: +```bash copy +sudo apt install lz4 +``` +Once you have downloaded the snapshot, you can extract it with: ```bash copy -curl -o ~/luminara.env https://testnet.luminara.icu/luminara.env -laconic-so --stack public-namada deploy --env-file ~/luminara.env up -echo "export CONTAINER=$(docker ps -q)" | sudo tee -a /etc/profile -CONTAINER=$(docker ps -q) +lz4 -c -d .tar.lz4 | tar -x -C $HOME/temp ``` -The relevant and more detailed docs are found [here](https://knowabl.notion.site/From-scratch-to-syncing-in-10-minutes-c0a56b34cdec447fbe2a5cd8f559f0bb). +After extracting, use the `db` folder to replace `NAMADA_BASE_DIR/$CHAIN_ID/db` and the `data` folder to replace NAMADA_BASE_DIR/$CHAIN_ID/cometbft/data`. + +### Start your node! +```bash copy +NAMADA_LOG=info CMT_LOG_LEVEL=p2p:none,pex:error NAMADA_CMT_STDOUT=true namada node ledger run +``` + ## Interacting with the testnet -The [Luminara collective](https://luminara.icu) has also composed a [Namada CLI cheat sheet](https://www.notion.so/Namada-CLI-cheat-sheet-b54b220610bd4e7e91548e32d7ac3c8a) that is available and useful for any Namada user. +Campfire includes a faucet, public rpc, wallet interface, indexer, and (hopefully soon) explorer. Check the [landing page](https://testnet.luminara.icu) for links and further info. \ No newline at end of file diff --git a/packages/docs/pages/networks/testnets/faq.mdx b/packages/docs/pages/networks/testnets/faq.mdx index a67f3313..7cab9d10 100644 --- a/packages/docs/pages/networks/testnets/faq.mdx +++ b/packages/docs/pages/networks/testnets/faq.mdx @@ -6,7 +6,7 @@ ### **Q: How do I use the Faucet?** -**A:** The faucet can be accessed [here](https://faucet.heliax.click) +**A:** Check [here](./faucet.mdx) for a list of currently maintained testnet faucets. ### **Q: Where can I see the available tokens on the Faucet?** @@ -19,7 +19,7 @@ HINT: `namadac balance` ### **Q: How do I use the Ethereum Bridge?** -**A:** The Ethereum Bridge is not yet implemented as of 0.23.0 Keep an eye on the [Changelog](https://github.com/anoma/namada/tree/main/.changelog) πŸ‘€ to see when it will be officially released. +**A:** The Ethereum Bridge is not yet implemented. Keep an eye on the [Changelog](https://github.com/anoma/namada/tree/main/.changelog) πŸ‘€ to see when it will be officially released. ### **Q: How can I make an IBC transfer?** diff --git a/packages/docs/pages/networks/testnets/faucet.mdx b/packages/docs/pages/networks/testnets/faucet.mdx new file mode 100644 index 00000000..b18978fd --- /dev/null +++ b/packages/docs/pages/networks/testnets/faucet.mdx @@ -0,0 +1,15 @@ +import { Callout } from 'nextra-theme-docs' + +# Testnet Faucets + + +Note: Testnet tokens have no monetary value nor any relation to mainnet tokens. + + +## List of testnet faucets + +- Campfire testnet: [https://faucet.luminara.icu](https://faucet.luminara.icu) + +### Usage Note +Since [fees are paid by implicit accounts](../../users/fees.mdx), it is recommended to source NAM to one of these accounts as the first step. Afterwards, using the `--gas-payer` flag, you can specify the address of the implicit account to pay for the transaction. + diff --git a/packages/docs/pages/networks/testnets/pow.mdx b/packages/docs/pages/networks/testnets/pow.mdx deleted file mode 100644 index df120397..00000000 --- a/packages/docs/pages/networks/testnets/pow.mdx +++ /dev/null @@ -1,16 +0,0 @@ -import { Callout } from 'nextra-theme-docs' - -# The PoW Solution on Namada - - -The link to the faucet is [https://faucet.heliax.click](https://faucet.heliax.click) - - -As of `v0.23.1`, the Namada faucet has been moved to be an API call to a server. In order to request tokens, a proof of work challenge must be completed, in order to prevent spamming of the faucet. - - -Note that this is not included in Mainnet as it is circumstantial to testnet. - - -Since [fees are paid by implicit accounts](../../users/fees.mdx), it is recommended to source NAM to one of these accounts as the first step. Afterwards, using the `--gas-payer` flag, you can specify the address of the implicit account to pay for the transaction. - diff --git a/packages/docs/pages/users/fees.mdx b/packages/docs/pages/users/fees.mdx index fdd7fe3a..5452d562 100644 --- a/packages/docs/pages/users/fees.mdx +++ b/packages/docs/pages/users/fees.mdx @@ -37,7 +37,7 @@ namada client transfer \ (Assuming that `accountant` exists and is in the wallet of the user) -For testnet purposes, we recommend [using the faucet](../networks/testnets/pow.mdx) to source NAM for transaction fees. +For testnet purposes, we recommend [using the faucet](../networks/testnets/faucet.mdx) to source NAM for transaction fees. ## How fees are calculated The fee for a transaction is calculated by multiplying `gas-limit` by the gas price. From 9b6d2272179ff3089b3d2f4b8dfae73ecb50646e Mon Sep 17 00:00:00 2001 From: iskay Date: Wed, 29 May 2024 13:45:57 -0400 Subject: [PATCH 73/94] fix broken link --- packages/docs/pages/utils.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/docs/pages/utils.mdx b/packages/docs/pages/utils.mdx index 10c342ad..043dda46 100644 --- a/packages/docs/pages/utils.mdx +++ b/packages/docs/pages/utils.mdx @@ -5,7 +5,7 @@ Usage: `namadac utils [OPTIONS] ` ## join-network Configure Namada to join an existing network. -See [the networks page](../networks.mdx) for details on how to join a network. +See [the networks page](./networks.mdx) for details on how to join a network. ```shell copy namadac utils join-network --chain-id ``` From abdda951c0e08b31f7d551a872d5516d2107cef1 Mon Sep 17 00:00:00 2001 From: iskay Date: Wed, 29 May 2024 14:09:14 -0400 Subject: [PATCH 74/94] fix missing import --- packages/specs/pages/modules/governance/vp-logic.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/packages/specs/pages/modules/governance/vp-logic.mdx b/packages/specs/pages/modules/governance/vp-logic.mdx index a08fbd5a..236d1abd 100644 --- a/packages/specs/pages/modules/governance/vp-logic.mdx +++ b/packages/specs/pages/modules/governance/vp-logic.mdx @@ -1,4 +1,5 @@ import { Callout } from 'nextra-theme-docs' +import { Steps } from 'nextra-theme-docs' ## VP logic From fa84dd41f851ecd63eafbeebde773c433a3cecc5 Mon Sep 17 00:00:00 2001 From: Ian Date: Thu, 30 May 2024 17:16:28 -0400 Subject: [PATCH 75/94] update sections on wallet and transparent accounts (#352) * update sections on wallet and transparent accounts * edit broken links * edit broken link --- .../pages/integrating-with-namada/_meta.json | 3 +- .../integrating-with-namada/interface.mdx | 34 ++++ packages/docs/pages/users.mdx | 10 +- packages/docs/pages/users/_meta.json | 3 +- .../docs/pages/users/transparent-accounts.mdx | 104 +--------- .../established-accounts.mdx | 27 +++ .../implicit-accounts.mdx | 41 ++++ .../transparent-accounts/multisignature.mdx | 188 ++++++++---------- .../send-and-receive-nam-tokens.mdx | 44 +--- packages/docs/pages/users/wallet.mdx | 4 +- .../pages/users/wallet/file-system-wallet.mdx | 59 +++++- .../pages/users/wallet/hardware-wallet.mdx | 6 + .../docs/pages/users/wallet/web-wallet.mdx | 90 ++++++--- 13 files changed, 351 insertions(+), 262 deletions(-) create mode 100644 packages/docs/pages/integrating-with-namada/interface.mdx create mode 100644 packages/docs/pages/users/transparent-accounts/established-accounts.mdx create mode 100644 packages/docs/pages/users/transparent-accounts/implicit-accounts.mdx diff --git a/packages/docs/pages/integrating-with-namada/_meta.json b/packages/docs/pages/integrating-with-namada/_meta.json index 5256093c..a7a66d23 100644 --- a/packages/docs/pages/integrating-with-namada/_meta.json +++ b/packages/docs/pages/integrating-with-namada/_meta.json @@ -1,5 +1,6 @@ { "sdk" : "Using the SDK", "light-sdk": "Using the Light SDK", - "indexer": "Using the Indexer" + "indexer": "Using the Indexer", + "interface": "Namada Interface" } diff --git a/packages/docs/pages/integrating-with-namada/interface.mdx b/packages/docs/pages/integrating-with-namada/interface.mdx new file mode 100644 index 00000000..3977c081 --- /dev/null +++ b/packages/docs/pages/integrating-with-namada/interface.mdx @@ -0,0 +1,34 @@ +# Namada Interface + +## Front end development with Namada +The [namada-interface repository](https://github.com/anoma/namada-interface) is a monorepo which contains the Namada browser extension +and associated Namada-Interface web app. It's a great resource for developers wishing to understand how to incorporate the Namada SDK +into their front-end applications. + +### Installing from source (for development and experiment purposes) + +#### Connect to a testnet or run a local node +1. Follow the instructions for the [testnets](../networks/testnets.mdx) to connect to a testnet or [set up a local node](../operators/networks/local-network.mdx). +2. Figure out where the base directory is stored and save its location as a variable such as `export BASE_DIR=`. + You can follow [these docs](../networks/testnets/migrating-testnets.mdx) to save this variable. Go ahead and save the chain id as a variable as well. You can find the chain id by running `cat $BASE_DIR/global-config.toml`. Save this chain-id to the variable `export CHAIN_ID=`. +3. You will need to edit the CometBFT config in order to allow the web wallet to connect to your node. + The CometBFT config will be located in `$BASE_DIR/$CHAIN_ID/cometbft/config/config.toml`. You will need to change the `cors_allowed_origins` field to `["*"]`. You can do this by running + ```shell copy + sed -i 's/cors_allowed_origins = \[\]/cors_allowed_origins = ["*"]/' \ + $BASE_DIR/$CHAIN_ID/cometbft/config/config.toml + ``` + +#### Setting up the extension +1. Clone the [namada-interface repository](https://github.com/anoma/namada-interface). +2. Follow the installation instructions in `README.md`. +3. `cd` into the `namada-interface/apps/extension` directory and run `yarn start:chrome`. This will build the extension and place it in the `namada-interface/apps/extension/build` directory. It also starts the dev server which will watch for changes. +4. `cd` into the `namada-interface/apps/namada-interface` directory and run `yarn dev:local` in order to launch a local instance of the web wallet. +4. Add the extension to the browser. For example, in Chrome, you can go to `chrome://extensions/` and click `Load unpacked` and select the `namada-interface/apps/extension/build/chrome/` folder. + +## Receiving tokens +You can show the address of any account by pressing the `Receive` button in the initial view under the "Total Balances" tab. You can copy the address by clicking the copy icon next to the address. +This will also display a QR code that can be scanned by a mobile wallet. + +## Sending Transactions + +In order to send transactions, you can press the `Send` button in the initial view under the "Total Balances" tab. This will open a modal that will allow you to send tokens to any account, from any account in your wallet that has a positive balance. diff --git a/packages/docs/pages/users.mdx b/packages/docs/pages/users.mdx index 94d79bad..8cf8e592 100644 --- a/packages/docs/pages/users.mdx +++ b/packages/docs/pages/users.mdx @@ -1,13 +1,17 @@ # User Guide -This guide is tailored towards users who are interested in using Namada to its maximum potential. This guide will include both the most basic operations that a user can execute, as well as the more advanced features that a user can access. +This section covers usage of the Namada software from an end user perspective, including the procedures and commands to create and manage keypairs, +make transparent and shielded transactions, stake tokens, and participate in governance. ## Table of contents +- [Using the Namada wallet](./users/wallet.mdx) - [Transparent Accounts](./users/transparent-accounts.mdx) - [The MASP](./users/shielded-accounts.mdx) - [Fees on Namada](./users/fees.mdx) -- [Delegating on Namada](./users/delegators.mdx) +- [Bonding and Proof-of-stake](./users/delegators.mdx) - [Governance and Public Goods Funding](./users/governance.mdx) -- [Using the Namada wallet](./users/wallet.mdx) +- [PGF](./users/public-goods-stewards.mdx) +- [IBC transfers](./users/ibc.mdx) +- [Querying the chain](./users/query.mdx) diff --git a/packages/docs/pages/users/_meta.json b/packages/docs/pages/users/_meta.json index f2f6129e..a8d5e512 100644 --- a/packages/docs/pages/users/_meta.json +++ b/packages/docs/pages/users/_meta.json @@ -6,5 +6,6 @@ "delegators": "Bonding and Proof-of-stake", "governance": "Governance and Public Goods Funding", "public-goods-stewards": "PGF", - "ibc": "IBC transfers" + "ibc": "IBC transfers", + "query": "Querying the chain" } \ No newline at end of file diff --git a/packages/docs/pages/users/transparent-accounts.mdx b/packages/docs/pages/users/transparent-accounts.mdx index b683ad88..ff82b135 100644 --- a/packages/docs/pages/users/transparent-accounts.mdx +++ b/packages/docs/pages/users/transparent-accounts.mdx @@ -1,106 +1,24 @@ -import { Callout } from 'nextra-theme-docs' - # An Introduction to Namada Addresses All accounts in Namada have a unique address, exactly one Validity Predicate and optionally any additional data in its dynamic storage sub-space. There are currently 3 types of account addresses: -- **Implicit:** An implicit account is derived from your keypair and can be used to authorize certain transactions from the account. Implicit accounts have no code attached to them, and can only have one key controlling it. This differs it from established accounts, which can support multiple keys. -- **Established:** An established account is a associated with one or more cryptographic keys. Each account has the `vp_user` predicate which validate any associated transaction. The main purpose of this code is to ensure that the multisignature threshold is correctly met and stores the keys that verify transactions. All established accounts will be initialized through on-chain transactions, unlike implicit accounts, which exist as soon as the keypair is generated. -- **Internal:** Special internal accounts, such as protocol parameters account, PoS and IBC. +- **Implicit:** An implicit account is the simplest account type. It is derived from a keypair and can be used to authorize certain transactions such as sending and staking tokens, or paying [fees](./fees.mdx). +Implicit accounts have no code attached to them, and can only have one key controlling it. This differs it from established accounts, +which can support multiple keys. +- **Established:** Unlike implicit accounts, which exist as soon as the keypair is generated, an established account must be initialized +with an on-chain transaction. It is associated with one or [more](./transparent-accounts/multisignature.mdx) cryptographic keys. An established account +has the `vp_user` validity predicate which validates any associated transaction to ensure that the multisignature threshold is correctly met. +- **Internal:** These are special internal accounts, such as those for the protocol parameters, proof of stake and IBC modules. -## Manage keypairs +## Managing keypairs Namada uses [ed25519](https://en.wikipedia.org/wiki/EdDSA#Ed25519) keypairs for signing cryptographic operations on the blockchain. -To manage your keys, various sub-commands are available under: - -```shell copy -namada wallet --help -``` - -### Generate a keypair - -It is possible to generate keys using the CLI. By doing so, an implicit account address is also derived in the process and added to storage. - - -Note the use of the placeholder `keysha` for the key parameter. This is a completely configurable parameter, and should just refer to the alias of the key signing the transaction (that has a positive nam balance). - - -```shell copy -KEY_ALIAS="keysha" -namada wallet gen --alias $KEY_ALIAS -``` - - -The derived implicit address shares the same `keysha` alias. The previous command has the same effect as `namada wallet gen --alias keysha`. - +The `namadaw` binary is used for key management. Various sub-commands are available under: -By default, the keys are stored encrypted. -The encryption password is _not_ a part of key generation randomness. - -Namada wallet supports keypair generation using a [mnemonic code](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki) and [HD derivation path](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki). -To generate a keypair for a default path use ```shell copy -KEY_ALIAS="keysha" -namada wallet gen --alias $KEY_ALIAS --hd-path default +namadaw --help ``` - -The default HD path for Namada is `m/44'/877'/0'/0'/0'`. - - -Optionally, the user may specify an additional passphrase that _is used_ as a part of keypair generation randomness. - - -WARNING: Keep your mnemonic code and passphrase safe. -Loss of any of them would inevitably lead to impossible account recovery. - - -### Restore the keypair - -To recover the keypair from your mnemonic code and passphrase use -```shell copy -namada wallet derive --alias keysha --hd-path default -``` - -This will ask you to then enter a passphrase (unless you add the `--unsafe-dont-encrypt` flag), -and then will ask you to enter your mnemonic code. - -### List all known keys - -```shell copy -namada wallet list --keys -``` - -## Manage addresses - - -To manage addresses, similar to keys, various sub-commands are available: - -```shell copy -namada wallet --help -``` - -### Generate an implicit address - -Let's call the implicit address `accountant`: -```shell copy -namada wallet gen --alias accountant -``` - -```shell copy -namada wallet gen --alias keysha --hd-path default -``` -generates an address using a [mnemonic code](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki) and [HD derivation path](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki). - -### Restore the address - -```shell copy -namada wallet derive --alias keysha --hd-path default -``` -### List all known addresses - -```shell copy -namada wallet list --addr -``` +See also: [File system wallet](../users/wallet/file-system-wallet.mdx) for examples and additional info on using `namadaw` to manage your keys. \ No newline at end of file diff --git a/packages/docs/pages/users/transparent-accounts/established-accounts.mdx b/packages/docs/pages/users/transparent-accounts/established-accounts.mdx new file mode 100644 index 00000000..0d607f4b --- /dev/null +++ b/packages/docs/pages/users/transparent-accounts/established-accounts.mdx @@ -0,0 +1,27 @@ +import { Callout } from 'nextra-theme-docs' + +# Established accounts + +Unlike implicit accounts, which exist as soon as the keypair is generated, an established account must be initialized +with an on-chain transaction. It is associated with one or [more](./multisignature.mdx) cryptographic keys. + +## Generating an established account + + +Before submitting the transaction to initialize an established account, you must have created an [implicit](./implicit-accounts.mdx) account and funded it with enough +funds to pay for the transaction [fees](../fees.mdx). + + +Initializing an established account entails submitting an `init-account` transaction on-chain to associate the account with +one or more public keys. We'll use the aliases `my-implicit` and `my-established` in this example, where the `my-implicit` account is assumed to have been previously been +created and funded. + +We can create a new established account `my-established` and associate it with the public key of `my-implicit` with: +``` +namadac init-account --alias my-established --public-keys my-implicit --signing-keys my-implicit --threshold 1 +``` +Note that: +- the implicit account `my-implicit` is required to sign the init-account transaction and pay the associated fees (with the `--signing-keys` argument) +- One public key is being associated with the account, and the signing threshold is 1. Technically, all established accounts are multisignature accounts +and therefore a 'typical' established account can be considered a '1 of 1' multisignature account. See [here](./multisignature.mdx) +for further details on using multisignature accounts with multiple keys. \ No newline at end of file diff --git a/packages/docs/pages/users/transparent-accounts/implicit-accounts.mdx b/packages/docs/pages/users/transparent-accounts/implicit-accounts.mdx new file mode 100644 index 00000000..86bd4056 --- /dev/null +++ b/packages/docs/pages/users/transparent-accounts/implicit-accounts.mdx @@ -0,0 +1,41 @@ +import { Callout } from 'nextra-theme-docs' + +# Implicit accounts + +An implicit account is the simplest account type. It is derived from a keypair and can be used to authorize certain transactions such as sending and staking tokens, or paying [fees](../fees.mdx). +Implicit accounts have no code attached to them, and can only have one key controlling it. + +## Generating an implicit account +You can generate a new implicit account using the CLI. The new keypair will be added to your `wallet.toml` under the alias you provide. + + +The 'alias' of an account simply provides a convenient way of referring to addresses stored in your `wallet.toml` file by name. +It is not intrinsic to the account. + + +```shell copy +namada wallet gen --alias +``` + +You will be prompted to provide a password, as the keys are stored to disk encrypted. Carefully remember this password; you will need it to sign transactions with your key. +The encryption password is _not_ a part of key generation randomness. + +After generating the new key, a twenty-four word mnemonic will be displayed, which can be used to recover your account. Write this down immediately and +store it safely offline, as it will not be displayed again. + + +WARNING: Keep your mnemonic code and passphrase safe. +Loss of either can result in you being locked out of your accounts with no chance of recovering your funds. + + +##### Derivation path + +Namada wallet supports keypair generation using a [mnemonic code](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki) and [HD derivation path](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki). + + +The default HD path for Namada is `m/44'/877'/0'/0'/0'`. + + +Optionally, the user may specify an additional passphrase that _is used_ as a part of keypair generation randomness. + + diff --git a/packages/docs/pages/users/transparent-accounts/multisignature.mdx b/packages/docs/pages/users/transparent-accounts/multisignature.mdx index d4dc5e3d..502a2148 100644 --- a/packages/docs/pages/users/transparent-accounts/multisignature.mdx +++ b/packages/docs/pages/users/transparent-accounts/multisignature.mdx @@ -1,153 +1,137 @@ import { Callout } from 'nextra-theme-docs' +import { Steps } from 'nextra-theme-docs' # Multisignature accounts on Namada -Multisignature accounts (multisigs) are accounts on Namada that allow for multiple signers. There are many benefits of having multisigs, including but not limited to +Multisignature accounts (multisigs) are accounts on Namada that allow for multiple signers. There are many benefits to multisignature accounts, including but not limited to: - Increased security - Ability to share wallets - Better recovery options -For this reason, all accounts on Namada are multisignature accounts by default. +For this reason, all established accounts on Namada are multisignature accounts by default. -## Initialising a multisignature account +A multisignature account can be described as an "x of y" account, where x is the 'threshold' or required number of signatures on a transaction +and y is the total number of keys associated with the account. For example, a 3 of 5 multisig will need at least three of the parties to sign any transaction. -Before creating an account, a user must generate at least one cryptographic `key`, that will be used to sign transactions. +## Example: Initialising a multisignature account +Here is the process to generate a 2 of 3 multisig account: -The following method will generate such a key: -```shell -namadaw gen \ ---alias my-key1 -``` -A second key can be generated as well (which will be useful for multisigs): -```shell -namadaw gen \ ---alias my-key2 + +### Create three signing keys +Assuming we have three parties -- Alice, Bob, and Charlie -- on the multisig, they each need to first generate their keypairs. +```bash copy +namadaw gen --alias alice +namadaw gen --alias bob +namadaw gen --alias charlie ``` -Accounts on Namada are initialized through the following method: +### Fund an implicit account for transaction fees +Recall from the section on [established accounts](./established-accounts.mdx) that we will need to provide an implicit account to +sign and to pay the gas costs of the `init-account` transaction. This can be any account you own, whether or not it's party to the multisig. +In this example, Alice will cover the transaction fees and we'll assume she already has sufficient NAM in her account. -**Non-multisig account (single signer)** -```shell -namadac init-account \ ---alias my-multisig-alias \ ---public-keys my-key1 \ ---signing-keys my-key1 -``` +### Init-account +The `init-account` transaction is no different from a typical established account, except for threshold and number of public keys associated. +(In fact, a typical established account is simply a 1 of 1 multisig.) -**Multisig account (at leat 2 signers)** -```shell -namadac init-account \ ---alias my-multisig-alias \ ---public-keys my-key1,my-key2 \ ---signing-keys my-key1,my-key2 \ ---threshold 2 +The `--signing-keys` flag indicates that Alice is signing and paying fees for this transaction. +```bash copy +namadac init-account --alias abc-multisig\ + --public-keys alice,bob,charlie --threshold 2 \ + --signing-keys alice ``` + -## Submitting a multisignature transaction -In order to submit a multisignature transaction, an offline transaction must first be constructed. -### Constructing an offline transaction - -For `v0.23.0` there are certain limitations to the offline transaction construction. Please be weary of any bugs that may arise. - +## Submitting a multisignature transaction +A multisignature transaction requires that an offline transaction first be constructed so that it can be signed by each required party before +being submitted to the chain. -The `--dump-tx` argument allows a user to do this. A folder is required to be specified where the transaction will be dumped. + +### Dump the raw tx +The `--dump-tx` argument will write the transaction to disk. A folder is required to be specified where the transaction will be dumped. -```shell +```bash copy mkdir tx_dumps -``` +namadac transfer --source abc-multisig --target \ + --token nam --amount 2 \ + --signing-keys alice \ + --dump-tx --output-folder-path tx_dumps -This can be done through the following method: -```shell -namadac transfer \ ---source my-multisig-alias \ ---target some-established-account-alias \ ---token NAM \ ---amount 100 \ ---signing-keys my-key1 \ ---dump-tx \ ---output-folder-path tx_dumps +# Example output: +Transaction serialized to tx_dumps/FC2955C6B252EF6E93B1B54923B2178A7DC47E06D27448A43426487DF4BAD0E3.tx. ``` -What this means is that the transaction has been constructed, and is ready to be signed. - -Within the specified folder, a `.tx` file will be created. This file contains the hexadecimal representation of the transaction bytes. This file can be used to sign the transaction. +### Sign the transaction with two of the three Keys +This command will sign the transaction with Alice's key. Afterwards, repeat the command using Bob's key. -### Signing the transaction - -The next step is to sign the transaction. `my-key1` can sign the transaction through the following method: -```shell +```bash copy +cd tx_dumps namadac sign-tx \ ---tx-path "" \ ---signing-keys my-key1 \ ---owner my-multisig-alias + --tx-path FC2955C6B252EF6E93B1B54923B2178A7DC47E06D27448A43426487DF4BAD0E3.tx \ + --signing-keys alice \ + --owner abc-multisig ``` - - -Note that any number of `--signing-keys` could sign the transaction in this stage. This will produce multiple signatures, which can be used to submit the transaction. - - - -Which means that the signature has been saved to this file (located in the current directory). - -Let's save this as an alias: -```shell -export SIGNATURE_ONE="offline_signature_FB7246E3FC43F59D8AEEC234EBFDB9DF1AC9BB7B14E536D05A7E2617CA41D4CD_0.tx" +You should have created two new files, one with Alice's signature and one with Bob's: +```bash copy +# contents of tx_dumps directory +FC2955C6B252EF6E93B1B54923B2178A7DC47E06D27448A43426487DF4BAD0E3.tx +offline_signature_FC2955C6B252EF6E93B1B54923B2178A7DC47E06D27448A43426487DF4BAD0E3_tpknam1qpnpmq2mpxaag9e0xcczgc0w66pzaxvpnhysjsm8h5tgmajgvunwck67w5j.tx +offline_signature_FC2955C6B252EF6E93B1B54923B2178A7DC47E06D27448A43426487DF4BAD0E3_tpknam1qqjnwcwpjy09ty4v0z6jwpkr04m3q2h0dgr6j62dfs4g6q6l4dk5yy5we05.tx ``` +To make things easier in the next step, we'll save these filenames to the shell variables `TX`, `SIG1` and `SIG2`. -Ensure to sign the transaction with at least k-of-n keys, where k is the minimum number of signatures required to submit a transaction, and n is the total number of keys. In this example, k=2 and n=2. - -Then let's say this signing produces another signature which we save to the alias `SIGNATURE_TWO`. +### Submit transaction on-chain +Since we have enough signatures to meet the threshold of this account, we can submit the transaction. Note that we need to specify +an account that will pay the transaction fees. -### Submitting the transaction - -The final step is to submit the transaction. This can be done through the following method: -```shell +```bash copy namadac tx \ ---tx-path "tx_dumps/a45ef98a817290d6fc0efbd480bf66647ea8061aee1628ce09b4af4f4eeed1c2.tx" \ ---signatures $SIGNATURE_ONE $SIGNATURE_TWO \ ---owner my-multisig-alias \ ---gas-payer my-key1 + --tx-path $TX + --signatures $SIG1 $SIG2 + --owner abc-multisig + --gas-payer alice ``` - -Note the lack of commas used in the `--signatures` argument. This is because the argument is a list of files, not a list of signatures. -Also note the `tx_dumps` folder. This is the folder where the transaction was dumped to as specified in `--output-folder-path` in the previous step. +Note the lack of commas used in the `--signatures` argument. -## Changing the multisig threshold -It is possible to change the multisig threshold of an account. This can be done through the following method: + + + +## Changing the multisig threshold or associated keys +It is possible to change the multisig threshold of an existing account. This can be done by submitting a valid `update-account` transaction. + +For example, to change the threshold on our multisig to 1: ```shell namadac update-account \ ---address my-multisig-address \ +--address abc-multisig \ +--public-keys alice,bob,charlie \ --threshold 1 \ ---signing-keys my-key1,my-key2 +--signing-keys alice,bob ``` + +Note: you must include both the threshold and the list of public keys to be assosicated with this account, even if there is no change to one of those values. + + + +Updating an account's threshold or public keys requires submitting a valid transaction meeting the existing requirements -- the `update-account` +transaction is no different from any other transaction in that regard. Therefore, you may need to follow the steps described in the previous section to first dump the `update-account` transaction +to a file and collect the required signatures. + +### Querying the threshold and public keys of an account One can check that the threshold has been updated correctly by running: ```shell namadac query-account \ ---owner my-multisig-address +--owner abc-multisig ``` -Which will yield the threshold of 1, together with the two public keys. - -## Changing the public keys of a multisig account -It is possible to change the public keys of a multisig account. This can be done through the following method: -```shell -namadac update-account \ ---address my-multisig-address \ ---public-keys my-key3,my-key4,my-key5 \ ---signing-keys my-key1,my-key2 -``` - -Which will change the public keys of the multisig account from `my-key1` and `my-key2` to the keys `my-key3`, `my-key4` and `my-key5` (assuming they exist in the wallet). - -The public-keys provided to the argument `--public-keys` will become the new signers of the multisig. The list must be a list of public keys, separated by commas, and without spaces. There must be at least 1 public key in the list, and the length of list must be at least the threshold of the multisig account. +Which will list the threshold and all associated public keys of an account. ## A video tutorial -Skip all the boring reading and watch a video tutorial instead: +Skip all the boring reading and watch a video tutorial instead! diff --git a/packages/docs/pages/users/transparent-accounts/send-and-receive-nam-tokens.mdx b/packages/docs/pages/users/transparent-accounts/send-and-receive-nam-tokens.mdx index ec63487e..2c486279 100644 --- a/packages/docs/pages/users/transparent-accounts/send-and-receive-nam-tokens.mdx +++ b/packages/docs/pages/users/transparent-accounts/send-and-receive-nam-tokens.mdx @@ -5,39 +5,25 @@ import { Callout } from 'nextra-theme-docs' In Namada, tokens are implemented as accounts with the [Token Validity Predicate](https://github.com/anoma/namada/blob/9b67281e359ebff5467cad57c866fbcf91eb80c8/shared/src/ledger/native_vp/multitoken.rs#L30). The validity predicate (VP) checks, in particular, that the total supply (of the token) is preserved in any transaction that uses this token. Your wallet will be pre-loaded with some token addresses that are initialized in the genesis block. -### Initialize an established account +### Sending tokens -If you already have a key in your wallet, you can skip this step. Otherwise, [generate a new keypair](../transparent-accounts.mdx#generate-a-keypair) now. +You can send tokens to/from either an implicit or established account. -Then, send a transaction to initialize your new established account and save its address with the alias `establishment`. The `keysha` public key will be written into the account's storage for authorizing future transactions. We also sign this transaction with `keysha`. +This section will cover transfers from one `tnam...` address to another (tranparent transfers). +Transfers to/from a `znam...` address (that is, to/from the [MASP](../shielded-accounts.mdx)) are covered in more detail in the section on [shielded transfers](../shielded-accounts/shielded-transfers.mdx). - -Note the use of the placeholder `keysha` for the key parameter. This is a completely configurable parameter, and should just refer to the alias of the key signing the transaction (that has a positive nam balance). + +For help creating a new account, see the sections on [Generating an implicit account](../transparent-accounts/implicit-accounts.mdx) or [Using the file system wallet](../../users/wallet/file-system-wallet.mdx). -```shell copy -namada client init-account \ - --alias establishment \ - --public-keys keysha \ - --signing-keys keysha \ - --threshold 1 -``` - -Once this transaction has been applied, the client will automatically see the new address created by the transaction and add it to your wallet with the chosen alias `establishment`. - -This command uses the prebuilt [User Validity Predicate](https://github.com/anoma/namada/blob/main/wasm/wasm_source/src/vp_user.rs). - -### Send a Payment - To submit a regular token transfer from your account to the `validator-1` address: ```shell copy namada client transfer \ - --source establishment \ - --target validator-1 \ - --token NAM \ - --amount 10 \ - --signing-keys keysha + --source \ + --target \ + --token \ + --amount 10 ``` This command will attempt to find and use the key of the source address to sign the transaction. @@ -47,18 +33,10 @@ This command will attempt to find and use the key of the source address to sign To query token balances for a specific token and/or owner: ```shell copy -namada client balance --token NAM --owner my-new-acc +namada client balance --token --owner ``` For any client command that submits a transaction (`init-account`, `transfer`, `tx`, `update` and [PoS transactions](../../operators/validators/proof-of-stake.mdx)), you can use the `--dry-run-wrapper` flag to simulate the transaction being applied in the block and see what would be the result. - -### See every known addresses' balance - -You can see the token's addresses known by the client when you query all tokens balances: - -```shell copy -namada client balance -``` diff --git a/packages/docs/pages/users/wallet.mdx b/packages/docs/pages/users/wallet.mdx index 2e443513..d6a61ff0 100644 --- a/packages/docs/pages/users/wallet.mdx +++ b/packages/docs/pages/users/wallet.mdx @@ -1,6 +1,6 @@ # Namada Wallet Guide -This document describes the different wallet concepts and options that are available to users of Namada who want to be able to [send, receive and interact](./transparent-accounts/send-and-receive-nam-tokens.mdx) with NAM tokens on the Namada blockchain. +This document describes the different wallet concepts and options that are available to users of Namada who want to be able to [send, receive and interact](./transparent-accounts/send-and-receive-nam-tokens.mdx) with tokens on the Namada blockchain. ## A brief introduction to the Namada wallet The purpose of the Namada wallet is to provide a user-interface to store and manage both keys and addresses. @@ -8,7 +8,7 @@ The purpose of the Namada wallet is to provide a user-interface to store and man The wallet simply "remembers" these very large numbers on your behalf. Keys are the fundamental building blocks for accounts on Namada. Keys come in the form of *pairs* (of secret and public key), and can be used to derive the **account address** (first 40 chars of the SHA256 hash of the public key). -To read more about addresses see [An introduction to Namada addresses](./transparent-accounts.mdx). +To read more about addresses, see [An introduction to Namada addresses](./transparent-accounts.mdx). ## The wallet options on Namada diff --git a/packages/docs/pages/users/wallet/file-system-wallet.mdx b/packages/docs/pages/users/wallet/file-system-wallet.mdx index 30509efa..ef48f9e4 100644 --- a/packages/docs/pages/users/wallet/file-system-wallet.mdx +++ b/packages/docs/pages/users/wallet/file-system-wallet.mdx @@ -1,11 +1,64 @@ +import { Callout } from 'nextra-theme-docs' + ## File System Wallet -By default, the Namada Wallet is stored under `.namada/{chain_id}/wallet.toml` where keys are stored encrypted. You can change the default base directory path with `--base-dir` and you can allow the storage of unencrypted keypairs with the flag `--unsafe-dont-encrypt`. +The filesystem wallet stores your encrypted keypairs on disk in your Namada base directory. It is the default wallet option when using the Namada CLI "out of the box." + +By default, the Namada Wallet is contained in the file `/{chain_id}/wallet.toml`, where keys are stored encrypted. You can change the default base directory path with `--base-dir` and you can allow the storage of unencrypted keypairs with the flag `--unsafe-dont-encrypt`. -If the wallet doesn't already exist, it will be created for you as soon as you run a command that tries to access the wallet. A newly created wallet will be pre-loaded with some internal addresses like `pos`, `pos_slash_pool`, `masp` and more. +If the wallet doesn't already exist, it will be created for you as soon as you run a command that tries to access the wallet, or upon [joining a network](../../networks.mdx). +A newly created wallet will be pre-loaded with some internal addresses like `pos`, `pos_slash_pool`, `masp` and more. Currently, the Namada client can load the password via: - **Stdin:** the client will prompt for a password. - **Env variable:** by exporting a ENV variable called `NAMADA_WALLET_PASSWORD` with a value of the actual password. -- **File:** by exporting an ENV variable called `NAMADA_WALLET_PASSWORD_FILE` with a value containing the path to a file containing the password. \ No newline at end of file +- **File:** by exporting an ENV variable called `NAMADA_WALLET_PASSWORD_FILE` with a value containing the path to a file containing the password. + +### Common wallet operations + +The `namadaw` wallet binary handles all key and wallet management functionality. You can use `namadaw --help` to explore +all available wallet commands. + +##### Create a new keypair +This will create a new keypair and save it in your wallet under the provided alias (for convenience). You will be prompted for a +password to encrypt the private key. Afterwards, your mnemonic will be printed to the terminal, which you should safely store in case +you need to restore your key at a later date. + +```bash copy +namadaw gen --alias +``` + + +Write down your mnemonic and store it securely -- this is the only time it will be shown. You can use your mnemonic to recover +your account if you lose access (for example, if your laptop stops working or is stolen). If you are locked out of your account, and +you haven't saved your mnemonic, your funds will be lost forever. + +Also carefully note the encryption password you provided -- you will need to provide it any time you make a transaction. + + +##### List your addresses +Once you've created a new keypair, you'll want to know the address to which you can send tokens. You do this by listing all known +addresses in your wallet and looking for the alias you've just created: + +```bash copy +namadaw list +``` + +or, if you only want to search for a specific address: + +```bash copy +namadaw find --alias +``` + +##### Recover an address from a mnemonic +You can recover an existing key from a mnemonic and add it to your wallet with: +```bash copy +namadaw derive --alias +``` +(You will be prompted to enter the mnemonic). + +#### Using the Pregenesis flag +Normally, you will be expected to join a network before using the wallet; and `namadaw` will throw an error when an existing chain context is not found. +However, there may be times when you want to use `namadaw` prior to joining a chain -- for example, when generating a keypair to +recieve a token allotment in the genesis block of a future chain. In these cases, you can use the flag `--pre-genesis` with your `namadaw` commands. \ No newline at end of file diff --git a/packages/docs/pages/users/wallet/hardware-wallet.mdx b/packages/docs/pages/users/wallet/hardware-wallet.mdx index 4696c5d1..49e07745 100644 --- a/packages/docs/pages/users/wallet/hardware-wallet.mdx +++ b/packages/docs/pages/users/wallet/hardware-wallet.mdx @@ -1,5 +1,11 @@ +import { Callout } from 'nextra-theme-docs' + ## Hardware Wallet + +The Namada Ledger app is currently in active development and not recommended for use. Information below may be out-of-date. + + Namada's web wallet extension is compatible with the [Ledger](https://www.ledger.com/) hardware. This guide will walk you through the process of setting up your Ledger device to work with Namada. ### Prerequisites diff --git a/packages/docs/pages/users/wallet/web-wallet.mdx b/packages/docs/pages/users/wallet/web-wallet.mdx index 46b0aa88..b3cd7af3 100644 --- a/packages/docs/pages/users/wallet/web-wallet.mdx +++ b/packages/docs/pages/users/wallet/web-wallet.mdx @@ -1,32 +1,74 @@ +import { Callout } from 'nextra-theme-docs' +import { Steps } from 'nextra-theme-docs' + # Web Wallet -## Install -When Namada is in [`mainnet`](../../networks/mainnets.mdx), the web wallet will be available in most browser extension web stores. For now, the user can install it from source by following the instructions below. +## Namada Extension +You can use the [Namada Extension](https://namada.net/extension) to manage your keys within your browser. By connecting the extension with +web apps built for Namada, you can send or recieve tokens, make IBC transfers, or perform other actions such as voting on governance proposals. + +## Installation +The extension is currently available on the [Chrome web store](https://chromewebstore.google.com/detail/namada-extension/hnebcbhjpeejiclgbohcijljcnjdofek), with Firefox support coming soon. + +## Set-up +After adding the extension to Chrome, follow these steps to create a new wallet: + + + +### Click 'Launch Initial Set-up' + +### Add or create keys +You can choose 'Import existing keys' to import an existing wallet from your twelve word mnemonic. You can also use a Ledger hardware wallet -- see [here](./hardware-wallet.mdx) +for further instructions. + +Click 'Create new keys' and verify that you have read and understood the message to proceed. + +### Safely store your mnemonic +You will be shown your recovery mnemonic and asked to confirm that you have written it down. + + +Write your mnemonic down and store it safely offline. + +It will allow you to recover your account. Without it, you risk losing access to your funds forever. + + +### Create and safely store your password +You will also be asked to create a password for the extension. Write down this password -- you will need to enter it regularly when using the extension. + + +If you lose your password, you will lose access to the extension. + +Remember: there's no 'recover password with email' option! + + +### Complete! +Your wallet is ready to use. + + +## Using the Extension +The extension itself only provides key management functionality. To send or receive tokens, you will need to navigate to a compatible +web app (such as [namada-interface](https://github.com/anoma/namada-interface)) and connect the extension to the site. + +Here's how to use the extension with Namada-Interface: + + +### Set the network in the extension +Open the extension and click the 'gear' icon in the top right, then select 'Network'. -### Installing from source (for development and experiment purposes) +Enter a valid chain-id and rpc url for the chain you wish to transact on, and click 'Submit'. -#### Connect to a testnet or run a local node -1. Follow the instructions for the [testnets](../../networks/testnets.mdx) to connect to a testnet or [set up a local node](../../operators/networks/local-network.mdx). -2. Figure out where the base directory is stored and save its location as a variable such as `export BASE_DIR=`. - You can follow [these docs](../../networks/testnets/migrating-testnets.mdx) to save this variable. Go ahead and save the chain id as a variable as well. You can find the chain id by running `cat $BASE_DIR/global-config.toml`. Save this chain-id to the variable `export CHAIN_ID=`. -3. You will need to edit the CometBFT config in order to allow the web wallet to connect to your node. - The CometBFT config will be located in `$BASE_DIR/$CHAIN_ID/cometbft/config/config.toml`. You will need to change the `cors_allowed_origins` field to `["*"]`. You can do this by running - ```shell copy - sed -i 's/cors_allowed_origins = \[\]/cors_allowed_origins = ["*"]/' \ - $BASE_DIR/$CHAIN_ID/cometbft/config/config.toml - ``` +### Navigate to the Namada-interface site +The Namada-interface for the [Campfire testnet](../../networks/testnets/campfire.mdx) is hosted at [https://interface.luminara.icu](https://interface.luminara.icu). After mainnet +has launched, a list of hosted Interfaces will be found [here](../../networks/mainnets.mdx). -#### Setting up the extension -1. Clone the [namada-interface repository](https://github.com/anoma/namada-interface). -2. Follow the installation instructions in `README.md`. -3. `cd` into the `namada-interface/apps/extension` directory and run `yarn start:chrome`. This will build the extension and place it in the `namada-interface/apps/extension/build` directory. It also starts the dev server which will watch for changes. -4. `cd` into the `namada-interface/apps/namada-interface` directory and run `yarn dev:local` in order to launch a local instance of the web wallet. -4. Add the extension to the browser. For example, in Chrome, you can go to `chrome://extensions/` and click `Load unpacked` and select the `namada-interface/apps/extension/build/chrome/` folder. +### Connect the extension +Click 'Connect to Namada Extension' and approve when prompted. You should see your wallet balance displayed on the page. -## Receiving tokens -You can show the address of any account by pressing the `Receive` button in the initial view under the "Total Balances" tab. You can copy the address by clicking the copy icon next to the address. -This will also display a QR code that can be scanned by a mobile wallet. +### Interact +Once connected, you can use the Interface to make transfers or stake with a validator (Note: some functionality may be missing on testnet). +Whenever you submit a transaction to the chain, you will be prompted to enter your password to allow the extension to sign using your private key. -## Sending Transactions +### Disconnect +If you wish to disconnect (remove permissions) from a site, you can do so in the Settings menu of the extension, under 'Connected Sites'. -In order to send transactions, you can press the `Send` button in the initial view under the "Total Balances" tab. This will open a modal that will allow you to send tokens to any account, from any account in your wallet that has a positive balance. + \ No newline at end of file From 0aba9d317d96bb1e8dcd9fc707599ed6b796ced1 Mon Sep 17 00:00:00 2001 From: Ian Date: Fri, 31 May 2024 16:57:29 -0400 Subject: [PATCH 76/94] update masp and ibc user sections (#353) update masp and ibc user sections --- packages/docs/pages/users/_meta.json | 6 +- packages/docs/pages/users/ibc.mdx | 126 +---------- packages/docs/pages/users/ibc/_meta.json | 4 + .../docs/pages/users/ibc/shielded-ibc.mdx | 70 ++++++ .../docs/pages/users/ibc/transparent-ibc.mdx | 69 ++++++ packages/docs/pages/users/query.mdx | 30 +-- .../docs/pages/users/shielded-accounts.mdx | 24 +- .../pages/users/shielded-accounts/_meta.json | 6 + .../users/shielded-accounts/glossary.mdx | 17 ++ .../users/shielded-accounts/masp-keys.mdx | 72 ++++++ .../shielded-accounts/shielded-rewards.mdx | 11 +- .../shielded-accounts/shielded-transfers.mdx | 210 +++--------------- .../users/shielded-accounts/shielding.mdx | 55 +++++ .../users/shielded-accounts/unshielding.mdx | 30 +++ .../pages/users/wallet/file-system-wallet.mdx | 14 ++ 15 files changed, 430 insertions(+), 314 deletions(-) create mode 100644 packages/docs/pages/users/ibc/_meta.json create mode 100644 packages/docs/pages/users/ibc/shielded-ibc.mdx create mode 100644 packages/docs/pages/users/ibc/transparent-ibc.mdx create mode 100644 packages/docs/pages/users/shielded-accounts/_meta.json create mode 100644 packages/docs/pages/users/shielded-accounts/glossary.mdx create mode 100644 packages/docs/pages/users/shielded-accounts/masp-keys.mdx create mode 100644 packages/docs/pages/users/shielded-accounts/shielding.mdx create mode 100644 packages/docs/pages/users/shielded-accounts/unshielding.mdx diff --git a/packages/docs/pages/users/_meta.json b/packages/docs/pages/users/_meta.json index a8d5e512..f841776d 100644 --- a/packages/docs/pages/users/_meta.json +++ b/packages/docs/pages/users/_meta.json @@ -1,11 +1,11 @@ { "wallet": "Using the Namada wallet", - "transparent-accounts": "Transparent accounts", - "shielded-accounts": "The MASP", + "transparent-accounts": "Transparent Accounts", + "shielded-accounts": "MASP & Shielded Transfers", "fees": "Fees on Namada", "delegators": "Bonding and Proof-of-stake", "governance": "Governance and Public Goods Funding", "public-goods-stewards": "PGF", "ibc": "IBC transfers", - "query": "Querying the chain" + "query": "Querying the Chain" } \ No newline at end of file diff --git a/packages/docs/pages/users/ibc.mdx b/packages/docs/pages/users/ibc.mdx index 8b4da35c..85532091 100644 --- a/packages/docs/pages/users/ibc.mdx +++ b/packages/docs/pages/users/ibc.mdx @@ -1,120 +1,18 @@ import { Callout } from 'nextra-theme-docs' -# Transferring assets over IBC +# Transferring Assets over IBC -It is possible to make ibc transfers using the Namada cli with the command `namadac ibc-transfer`. The assumed pre-requisites are that a channel has been created and Hermes is running with the proper config on two nodes. +Namada features full IBC protocol support, which means non-native assets can be brought over from any IBC compatible +chain (such as Cosmos SDK chains). As a result, users can enjoy the combined benefits of another chain's ecosystem, assets +and features with Namada's [MASP](./shielded-accounts/). -In order to conduct an IBC transfer using Namada's `ibc-transfer` command, we will need to know the `base-dir` and `node` of each instance (and other transfer parameters). -`base-dir` is the base directory of each node, see [base-dir](../operators/ledger/base-directory.mdx) for more information. -`node` is the `rpc_addr` of the relayer. -You can run -```shell -grep "rpc_addr" ${HERMES_CONFIG} -``` -to find the address. +The assumed prerequisites are that an active IBC connection has been created and maintained between the two chains by +operators running relayer software such as [Hermes](https://github.com/heliaxdev/hermes). - - **For the local node ONLY** +This section will be focused on IBC transfers from a user perspective. For info on operating an IBC relayer, see +[this](../operators/ibc.mdx) page in the Operators section. -To find your ledger address for Chain A, you can run the following command -```bash copy -export BASE_DIR_A="${HERMES}/data/namada-a/.namada" -export LEDGER_ADDRESS_A="$(grep "rpc_address" ${BASE_DIR_A}/${CHAIN_A_ID}/setup/validator-0/.namada/${CHAIN_A_ID}/config.toml)" -``` - - -The [channel ID](../operators/ibc.mdx) for this chain will depend on the order in which one created the channel. Since we have only opened one channel, the `channel-id` is `channel-0`, but as more are created, these increase by index incremented by 1. The channel-id should be communicated by the relayer. - -Assuming that the open channel is `channel-0`, you can save it in an environment variable by running -```bash copy -export CHANNEL_ID="channel-0" -``` - -The inter-blockchain transfers from Chain A can be achieved by -```bash copy -namadac --base-dir ${BASE_DIR_A} - ibc-transfer \ - --amount ${AMOUNT} \ - --source ${SOURCE_ALIAS} \ - --receiver ${RECEIVER_RAW_ADDRESS} \ - --token ${TOKEN_ALIAS} \ - --channel-id ${CHANNEL_ID} \ - --node ${LEDGER_ADDRESS_A} -``` -Where the above variables in `${VARIABLE}` must be substituted with appropriate values. The raw address of the receiver can be found by `namadaw --base-dir ${BASE_DIR_B} address find --alias ${RECEIVER}`. - -E.g. -```bash copy -namadac --base-dir ${BASE_DIR_A} - ibc-transfer \ - --amount 100 \ - --source albert \ - --receiver atest1d9khqw36g56nqwpkgezrvvejg3p5xv2z8y6nydehxprygvp5g4znj3phxfpyv3pcgcunws2x0wwa76 \ - --token nam \ - --channel-id channel-0 \ - --node http://127.0.0.1:27657 -``` - -Once the transaction has been submitted, a relayer will need to relay the packet to the other chain. This is done automatically by the relayer running Hermes. If the packet is never successfully relayed, the funds are returned to the sender after a timeout. See more information in the [specs](https://specs.namada.net/modules/ibc). - -## Transferring assets back from Cosmos-SDK based chains - -When a transfer has been made to a Cosmos-SDK based chain, the ibc transfer is conducted as above. However, when transferring back from the cosmos-based chain, clearly the `namadac ibc-transfer` command will not work. Instead, you want to use [`gaiad`](https://github.com/cosmos/gaia). - -```bash -gaiad tx ibc-transfer transfer transfer ${CHANNEL_ID} ${RECEIVER_RAW_ADDRESS} ${AMOUNT}${IBC_TOKEN_ADDRESS} --from ${COSMOS_ALIAS} --node ${COSMOS_RPC_ENDPOINT} --fees 5000uatom -``` - -for example: - -```bash copy -gaiad tx ibc-transfer transfer transfer channel-0 atest1d9khqw368qcyx3jxxu6njs2yxs6y2sjyxdzy2d338pp5yd35g9zrv334gceng3z9gvmryv2pfdddt4 10ibc/281545A262215A2D7041CE1B518DD4754EC7097A1C937BE9D9AB6F1F11B452DD --from my-cosmos-address --node https://rpc.sentry-01.theta-testnet.polypore.xyz:443 --fees 5000uatom -``` - -## Shielding transfer -Before `namadac ibc-transfer`, you need to generate a proof of the following IBC transfer for the shielding transfer to the destination Namada. The command `namadac ibc-gen-shielded` generates the proof and outputs a file including required data. In this case, Chain B is the destination chain. -```bash copy -namadac --base-dir ${BASE_DIR_B} ibc-gen-shielded \ - --output-folder-path ${OUTPUT_PATH} \ - --target ${payment_addr_b} \ - --token apfel \ - --amount 100 \ - --port-id transfer \ - --channel-id channel-0 \ - --node ${LEDGER_ADDRESS_B} -``` -Then, you can send the token from the source chain by setting the proof in the ICS-20 packet's memo field. The following example is to send tokens from the source Namada (Chain A). The `${memo_path}` should be the file path created by `namadac ibc-gen-shielded` on the destination chain. -```bash copy -namadac --base-dir ${BASE_DIR_A} ibc-transfer \ - --source ${spending_key_a} \ - --receiver ${payment_addr_b} \ - --token apfel \ - --amount 100 \ - --channel-id channel-0 \ - --memo-path ${memo_path} \ - --node ${LEDGER_ADDRESS_A} -``` - -When the source chain is a Cosmos-SDK based chain, the memo should be set as string with `--memo` option. -```bash copy -memo=$(cat ${memo_path}) -gaiad tx ibc-transfer transfer \ - ${CHANNEL_ID} \ - ${RECEIVER_PAYMENT_ADDRESS} \ - ${AMOUNT}${IBC_TOKEN_ADDRESS} \ - --from ${COSMOS_ALIAS} \ - --memo ${memo} \ - --node ${COSMOS_RPC_ENDPOINT} \ - --fees 5000uatom -``` - -You can do unshielding transfers over IBC without generating a proof. -```bash copy -namadac --base-dir ${BASE_DIR_A} ibc-transfer \ - --source ${spending_key_a} \ - --receiver ${RECEIVER_RAW_ADDRESS} \ - --token nam \ - --amount 100 \ - --channel-id channel-0 \ - --node ${LEDGER_ADDRESS_A} -``` +### Resources +- [How IBC Works](https://www.ibcprotocol.dev/how-ibc-works): A brief, beginner-friendly overview of IBC +- [What is IBC?](https://tutorials.cosmos.network/academy/3-ibc/1-what-is-ibc.html): A detailed, developer-focused look +at the design and functionality of the protocol \ No newline at end of file diff --git a/packages/docs/pages/users/ibc/_meta.json b/packages/docs/pages/users/ibc/_meta.json new file mode 100644 index 00000000..a72eb5dd --- /dev/null +++ b/packages/docs/pages/users/ibc/_meta.json @@ -0,0 +1,4 @@ +{ + "shielded-ibc": "Shielded IBC", + "transparent-ibc": "Transparent IBC" +} \ No newline at end of file diff --git a/packages/docs/pages/users/ibc/shielded-ibc.mdx b/packages/docs/pages/users/ibc/shielded-ibc.mdx new file mode 100644 index 00000000..09a45aae --- /dev/null +++ b/packages/docs/pages/users/ibc/shielded-ibc.mdx @@ -0,0 +1,70 @@ +import { Callout } from 'nextra-theme-docs' + +# Shielded IBC + +You can send assets to another IBC compliant chain, such as a Cosmos SDK chain or another Namada chain, using the +`ibc-transfer` command in `namadac`. + +This section covers sending assets to and from a shielded ( `znam` ) address. + +## Prerequisites + +- An active IBC connection has been created and maintained between the two chains by operators running relayer +software such as [Hermes](https://github.com/heliaxdev/hermes). +- You will need to know the corresponding channel id + +## IBC transfer to a shielded address +{/* TODO: instructions are out of date? */} + +Before sending your IBC transfer, you will need to generate a MASP + +Before `namadac ibc-transfer`, you need to generate a proof of the following IBC transfer for the shielding transfer + to the destination Namada. The command `namadac ibc-gen-shielded` generates the proof and outputs a file including + required data. In this case, Chain B is the destination chain. +```bash copy +namadac --base-dir ${BASE_DIR_B} ibc-gen-shielded \ + --output-folder-path ${OUTPUT_PATH} \ + --target ${payment_addr_b} \ + --token apfel \ + --amount 100 \ + --port-id transfer \ + --channel-id channel-0 \ + --node ${LEDGER_ADDRESS_B} +``` +Then, you can send the token from the source chain by setting the proof in the ICS-20 packet's memo field. +The following example is to send tokens from the source Namada (Chain A). The `${memo_path}` should be the file +path created by `namadac ibc-gen-shielded` on the destination chain. +```bash copy +namadac --base-dir ${BASE_DIR_A} ibc-transfer \ + --source ${spending_key_a} \ + --receiver ${payment_addr_b} \ + --token apfel \ + --amount 100 \ + --channel-id channel-0 \ + --memo-path ${memo_path} \ + --node ${LEDGER_ADDRESS_A} +``` + +When the source chain is a Cosmos-SDK based chain, the memo should be set as string with `--memo` option. +```bash copy +memo=$(cat ${memo_path}) +gaiad tx ibc-transfer transfer \ + ${CHANNEL_ID} \ + ${RECEIVER_PAYMENT_ADDRESS} \ + ${AMOUNT}${IBC_TOKEN_ADDRESS} \ + --from ${COSMOS_ALIAS} \ + --memo ${memo} \ + --node ${COSMOS_RPC_ENDPOINT} \ + --fees 5000uatom +``` + +You can do unshielding transfers over IBC without generating a proof. +```bash copy +namadac --base-dir ${BASE_DIR_A} ibc-transfer \ + --source ${spending_key_a} \ + --receiver ${RECEIVER_RAW_ADDRESS} \ + --token nam \ + --amount 100 \ + --channel-id channel-0 \ + --node ${LEDGER_ADDRESS_A} +``` diff --git a/packages/docs/pages/users/ibc/transparent-ibc.mdx b/packages/docs/pages/users/ibc/transparent-ibc.mdx new file mode 100644 index 00000000..057ebb77 --- /dev/null +++ b/packages/docs/pages/users/ibc/transparent-ibc.mdx @@ -0,0 +1,69 @@ +import { Callout } from 'nextra-theme-docs' + +# Transparent IBC + +You can send assets to another IBC compliant chain, such as a Cosmos SDK chain or another Namada chain, using the +`ibc-transfer` command in `namadac`. + +This section covers sending assets to and from a transparent ( `tnam` ) address. + +## Prerequisites + +- An active IBC connection has been created and maintained between the two chains by operators running relayer +software such as [Hermes](https://github.com/heliaxdev/hermes). +- You will need to know the corresponding channel id + +## IBC transfers from Namada to another chain + +To make an outgoing IBC transfer from a Namada transparent address: +```bash copy +namadac ibc-transfer \ + --source \ + --receiver \ + --token \ + --amount + --channel-id +``` +Note: +- the `receiver` address is the address on the receiving chain -- if you are sending to another Namada chain, this would start with `tnam...`, +while if you're sending to a Cosmos SDK chain it might start with `cosmos...` or some other prefix. +- the `channel-id` parameter is a string, for example `channel-27`. + +#### Example: Sending NAM to the Cosmos Hub +```bash copy +namadac ibc-transfer \ + --source my-namada-wallet \ + --receiver cosmos1y3q368qj8d2ged5xcdz96wtt3n5f9zq6ql0p7k \ + --token nam \ + --amount 10 \ + --channel-id channel-42 +``` + +Once the transaction has been submitted, a relayer will need to relay the packet to the other chain. +This is done automatically by the relayer running Hermes. If the packet is never successfully relayed, the funds are +returned to the sender after a timeout. See more information in the [specs](https://specs.namada.net/modules/ibc). + +## Transferring assets into Namada from Cosmos SDK chains + +To transfer assets back from a Cosmos SDK chain, you will post an IBC transaction on that chain using its corresponding +client software. + +For the Cosmos Hub, you will use [`gaiad`](https://github.com/cosmos/gaia). Other chains will have their own corresponding client; +however all Cosmos SDK based clients will share approximately the same commands and operation. Consult the documentation +of the counterparty chain when in doubt. + +#### Example: Sending ATOM from the Cosmos Hub to Namada + +```bash +gaiad tx ibc-transfer transfer \ + transfer \ + channel-64 \ + tnam1qzgmrvz0zdjtgdu7yq6hl46wdg7za2t2hg5t85c7 \ + 10000000uatom \ + --from my-cosmos-wallet \ + --fees 5000uatom +``` + +The double use of 'transfer' in the above command is not a typo. The command takes an IBC port name as one of its parameters; +and the name of the port happens to be 'transfer'. + \ No newline at end of file diff --git a/packages/docs/pages/users/query.mdx b/packages/docs/pages/users/query.mdx index e52a156c..799b1f22 100644 --- a/packages/docs/pages/users/query.mdx +++ b/packages/docs/pages/users/query.mdx @@ -1,51 +1,53 @@ -# **Query** +# Querying Overview -This is the complete query related to Namada +Querying a Namada chain is done using the client `namadac`. -Including: account,pgf,proposal,proposal-result,proposal-votes +This section details several common queries; see all available commands with `namadac --help`. -## query-account +#### query-account ```txt namadac query-account --owner ``` -Return the results will return the `Threshold` and `Public` key of the address. +Returns the `Threshold` and `Public` key(s) of an established account. -## query-pgf +#### query-pgf ``` namadac query-pgf ``` -Return the results will return the `Pgf stewards , Reward distribution`, `Pgf fundings` key of the address. +Returns the list of PGF Stewards, their reward distribution, and active PGF streaming payments. -## query-proposal +#### query-proposal ``` namadac query-proposal --proposal-id ``` -Return the results will return the PGF type of the proposal, `author`, `content`, `StartEpoch`, `EndEpoch`, `GraceEpoch`, `Status` +Returns info on a given proposal, including its type, author, content, StartEpoch, EndEpoch, GraceEpoch, and Status. -## query-proposal-result +#### query-proposal-result ``` namadac query-proposal-result --proposal-id ``` -Return the results will return the outcome of the proposal, whether it's `Passed` or `Rejected`, including the total number of votes for `yay`, `nay`, `abstain`, and the threshold (fraction) of the total voting power needed to tally. +Returns the outcome of a given proposal, including whether it's Passed/Rejected, the total number of votes for yay/nay/abstain, and the threshold (fraction) of the total voting power needed to tally. -## query-proposal-votes +#### query-proposal-votes ``` namadac query-proposal-votes --proposal-id ``` -Return the results of all wallets that have voted `yay` or `nay` on the proposal +Returns the results of all wallets that have voted `yay` or `nay` on the proposal ``` namadac query-proposal-votes --proposal-id --voter ``` -Return the result of a specific wallet that has voted on a specific proposal +Returns the result of a specific wallet that has voted on a specific proposal + +{/* TODO: add more queries*/} \ No newline at end of file diff --git a/packages/docs/pages/users/shielded-accounts.mdx b/packages/docs/pages/users/shielded-accounts.mdx index 733163e6..1018df5b 100644 --- a/packages/docs/pages/users/shielded-accounts.mdx +++ b/packages/docs/pages/users/shielded-accounts.mdx @@ -1,8 +1,26 @@ # The MASP -The multi-asset shielded pool (MASP) is a zero knowledge circuit that allows users to make transfers in a way that does not reveal the sender, receiver, or amount. Each transfer is a zero knowledge proof itself, and is often referred to as a "note". From the users perspective, the construction of these zero knowledge proofs occur behind the scenes. +Namada affords users data-protection through its multi-asset shielded pool (MASP), which supports shielded transfers with any native or non-native asset. +The MASP is a zero-knowledge circuit ([zk-SNARK](https://en.wikipedia.org/wiki/Non-interactive_zero-knowledge_proof)) that +extends the [Zcash Sapling circuit](https://raw.githubusercontent.com/zcash/zips/master/protocol/sapling.pdf) to add support for sending arbitrary +assets. All assets in the pool share the same anonymity set -- meaning that the more transactions are issued to MASP, the stronger the +data protection guarantees for all users. -The MASP is inspired by the work produced by the Electric Coin Company (ECC) who developed Zcash, and builds on the Sapling Circuit by implementing multi-asset functionality. In addition to the MASP, Namada has also implemented a zero knowledge circuit for rewarding shielded set contributions in a shielded manner. This circuit is called the Convert Circuit (CC for short). +The MASP allows users to make transfers in a way that does not reveal the sender, receiver, or amount. Each transfer is a zero knowledge proof itself, and is often referred to as a "note". +From the users perspective, the construction of these zero knowledge proofs occur behind the scenes. -More technical details of these circuits can be found in the [specs](https://specs.namada.net) as well as [this blog post](https://namada.net/blog/understanding-the-masp-and-cc-circuits). +Users of the MASP are [rewarded](./shielded-accounts/shielded-rewards.mdx) for their contributions to the shielded set in the form of native protocol tokens (NAM). + +### Inspiration + +The MASP is inspired by the work produced by the Electric Coin Company (ECC) who developed Zcash, and builds on the Sapling Circuit by implementing multi-asset functionality. +In addition to the MASP, Namada has also implemented a zero knowledge circuit for rewarding shielded set contributions in a shielded manner. +This circuit is called the Convert Circuit (CC for short). + +If you are familiar with Zcash, the set of interactions you can execute with Namada's MASP are similar: +- [Shielding transfers](./shielded-accounts/shielding.mdx): transparent to shielded address +- [Shielded transfers](./shielded-accounts/shielded-transfers.mdx): shielded to shielded address +- [Unshielding transfers](./shielded-accounts/unshielding.mdx): shielded to transparent address + +More technical details of these circuits can be found in the [specs](https://specs.namada.net/modules/masp) as well as [this blog post](https://namada.net/blog/understanding-the-masp-and-cc-circuits). diff --git a/packages/docs/pages/users/shielded-accounts/_meta.json b/packages/docs/pages/users/shielded-accounts/_meta.json new file mode 100644 index 00000000..67269d47 --- /dev/null +++ b/packages/docs/pages/users/shielded-accounts/_meta.json @@ -0,0 +1,6 @@ +{ + "glossary": "Glossary", + "masp-keys": "Shielded Key Management", + "shielding": "Shielding Assets", + "unshielding": "Unshielding Assets" +} \ No newline at end of file diff --git a/packages/docs/pages/users/shielded-accounts/glossary.mdx b/packages/docs/pages/users/shielded-accounts/glossary.mdx new file mode 100644 index 00000000..45c66b03 --- /dev/null +++ b/packages/docs/pages/users/shielded-accounts/glossary.mdx @@ -0,0 +1,17 @@ +# Glossary + +- __Transparent address__: +Has a `tnam` prefix. When transferring from one transparent address to another, transaction details +such as the sender, reciever and amount are publicy visible. + +- __Shielded address (aka: Payment address)__: +Has a `znam` prefix. This is the public-facing address which can be shared with others in order to recieve funds. When transferring from one +shielded address to another, transaction details such as the sender, reciever and amount are hidden from anyone who does not have an associated +spending or viewing key. + +- __Spending key__: +Has a `zsknam` prefix. Authorizes the holder to spend funds from associated shielded address. The spending key is also used to derive the viewing key and payment address. +Therefore, the spending key will also allow the user to view the balance and transaction data of the associated address. + +- __Viewing key__: +Has a `zvknam` prefix. Allows the holder to view incoming and outgoing transactions for a specific shielded address, but does not permit spending funds. diff --git a/packages/docs/pages/users/shielded-accounts/masp-keys.mdx b/packages/docs/pages/users/shielded-accounts/masp-keys.mdx new file mode 100644 index 00000000..f14fed2f --- /dev/null +++ b/packages/docs/pages/users/shielded-accounts/masp-keys.mdx @@ -0,0 +1,72 @@ +import { Callout } from 'nextra-theme-docs' + +# MASP Key Management + +This section will detail the commands to generate spending keys, viewing keys and payment addresses with `namadaw`. + +For an explanation of the different types of keys and addresses, see the [glossay](./glossary.mdx). + +### Generating a spending key and viewing key + +Create a new spending key with: +```bash copy +namadaw gen --shielded --alias +``` + +This command will also generate a corresponding Viewing Key sharing +the same alias. + + +You will be prompted to provide an encryption passphrase. Once the key is created, your recovery mnemonic will be displayed in the terminal. + +WARNING: Keep your mnemonic and passphrase safe. +Loss of either can result in you being locked out of your accounts with no chance of recovering your funds. + + +#### Displaying your spending key and viewing key +You can display your viewing key with: +```bash copy +namadaw list --shielded +``` + +You can also display your spending key (your spending key should always be kept private, so use caution when executing this command): +```bash copy +namadaw list --shielded --unsafe-show-secret --decrypt +``` + +### Generating a payment address + +Once you have created a spending key, it can be used to derive a payment address: +```bash copy +namadaw gen-payment-addr --alias --key +``` + +It is possible (and recommended) to generate multiple payment addresses from the same spending key. + + +### Displaying your payment addresses +You can display all payment addresses associated with your spending key(s) with: +```bash copy +namadaw list --shielded +``` + +### Recovering an existing spending key from mnemonic + +You can recover an existing spending key from your mnemonic and add it to your wallet with: +```bash copy +namadaw derive --alias --shielded +``` + +### Adding an existing key or payment address to your wallet + +If you know the raw value of a spending key, viewing key or payment address, you can add it to your wallet under an alias so you can more conveniently refer to it later. + +```bash copy +namadaw add --alias --value +``` + +### Removing a key/address +You can remove all keys/addresses associated with an alias from your wallet with: +```bash copy +namadaw remove --alias --do-it +``` \ No newline at end of file diff --git a/packages/docs/pages/users/shielded-accounts/shielded-rewards.mdx b/packages/docs/pages/users/shielded-accounts/shielded-rewards.mdx index d7d34bc6..39d957ac 100644 --- a/packages/docs/pages/users/shielded-accounts/shielded-rewards.mdx +++ b/packages/docs/pages/users/shielded-accounts/shielded-rewards.mdx @@ -2,4 +2,13 @@ Shielded rewards are distributed to all users in the shielded set. Users are rewared `NAM` tokens for each epoch their incentivised assets are in the shielded set. Informally, the amount of `NAM` rewarded for a specific asset is proportional to the amount of that asset in the shielded pool. Each asset has a "reward rate" specified by governance, which sets the constant of proportionality for that asset. -The interested reader should consult [the specs](https://specs.namada.net/modules/proof-of-stake) for a more precise explanation of how the reward is calculated. \ No newline at end of file +The interested reader should consult [the specs](https://specs.namada.net/modules/masp/shielded-pool-incentives) for a more precise explanation of how the reward is calculated. + +### Querying eligible assets + +You can see a list of assets currently eligible for shielded rewards with: +```bash copy +namadac masp-reward-tokens +``` + +Assets can be added or removed from eligibility through [governance](../governance/on-chain-governance.mdx). \ No newline at end of file diff --git a/packages/docs/pages/users/shielded-accounts/shielded-transfers.mdx b/packages/docs/pages/users/shielded-accounts/shielded-transfers.mdx index f6391339..77fc4001 100644 --- a/packages/docs/pages/users/shielded-accounts/shielded-transfers.mdx +++ b/packages/docs/pages/users/shielded-accounts/shielded-transfers.mdx @@ -2,198 +2,50 @@ import { Callout } from 'nextra-theme-docs' # Shielded Transfers -In Namada, shielded transfers are enabled by the [Multi-Asset Shielded Pool](https://specs.namada.net/masp/ledger-integration.html?highlight=MASP#masp-integration-spec) (MASP). -The MASP is a zero-knowledge circuit ([zk-SNARK](https://en.wikipedia.org/wiki/Non-interactive_zero-knowledge_proof)) that extends the [Zcash Sapling circuit](https://raw.githubusercontent.com/zcash/zips/master/protocol/sapling.pdf) to add support for sending arbitrary assets. All assets in the pool share the same anonymity set, this means that the more transactions are issued to MASP, the stronger are the data protection guarantees. +Once the user has a shielded balance, it can be transferred to a another shielded address. This is known as a __shielded transfer__. -## Using MASP +## Making a shielded transfer -If you are familiar with Zcash, the set of interactions you can execute with the MASP are similar: - -- [**Shielding transfers:** transparent to shielded addresses](#shielding-transfers) -- [**Shielded transfers:** shielded to shielded addresses](#shielded-transfers) -- [**Unshielding transfers:** shielded to transparent addresses](#unshielding-transfers) - -We distinguish two kinds of keys: -- A **Spending Key** is a type of private key that allows any user in possession of it to spend the balance of the associated address. For shielded addresses, possessing the Spending Key also allows the user to view the address’ balance and transaction data. -- A **Viewing Key** allows any user in possession of it to view and disclose transaction details. It is derived from the Spending Key and hold the same alias. - -### Shielding transfers - -To conduct a shielding transfer, the user must first be in possession of a -transparent account with some token balance. - -#### Generate your Spending Key - -One can randomly generate a new spending key with: - -```shell copy -namadaw gen --shielded --alias +Before making a shielded transfer, it is recommended to first sync the local shielded context: +```bash copy +namadac shielded-sync --spending-keys ``` - -This command will also generate a corresponding Viewing Key sharing -the same alias. - - -#### Create a new payment address +To make a shielded transfer, you must possess the relevant spending key. See the [glossary](./glossary.mdx) for +an explanation on the types of keys and addresses used with the MASP. -To create a payment address from one's spending key, one can run: - -```shell copy -namadaw gen-payment-addr \ - --key \ - --alias +```bash copy +namadac transfer \ + --source \ + --target \ + --token \ + --amount \ + --gas-payer ``` - -This command will generate a different payment address each time the user runs the command. -Payment addresses can be reused or discarded as the user likes, and any relationship -between addresses cannot be deciphered by any other user without the spending key. +Note: you must provide an implicit account you control containing funds for transcation fees. -#### Send your shielding transfer - -Once one has a payment address, one can transfer a balance from their -transparent account to their shielded account with: - -```shell copy -namadac transfer \ - --source \ - --target \ - --token btc \ - --amount -``` - -#### View one's balance - -Once this transfer has been broadcasted, validated, and executed on the blockchain, one can view their spending key's -balance: - -```shell copy -namadac balance --owner -``` - -In order to view actual and updated spending key's balance, one must first run shielded sync: - -```shell copy -namadac shielded-sync --from-height -``` - -### Shielded transfers - -Once the user has a shielded balance, it can be transferred to a -another shielded address: - -```shell copy -namadac transfer \ - --source \ - --target \ - --token btc \ - --amount \ - --signing-keys -``` - -### Unshielding transfers - -It is also possible to transfer the balance to a transparent account: - -```shell copy -namadac transfer \ - --source \ - --target \ - --token btc \ - --amount \ - --signing-keys -``` - -### Shielded Address/Key Generation - -#### Spending Key Generation - -When the client generates a spending key, it automatically derives a viewing key for it. The spending key acts as the "source" of any transfer from any shielded address derived from it. The viewing key is able to determine the total unspent notes that the spending key is authorized to spend. - - -#### Payment Address Generation - -Payment addresses can be derived from both spending keys as well as viewing keys. The payment address acts as a destination address in which any tokens received by this address is spendable by the corresponding spending key. Only the payment address' spending key and viewing key are able to spend and view the payment address's balance, respectively. Below are examples of how payment addresses can be -generated: - -``` -namadaw gen-payment-addr --alias my-pa1 --key my-sk -namadaw gen-payment-addr --alias my-pa2 --key my-vk -``` - -#### Manual Key/Address Addition - -It is also possible to manually add spending keys, viewining keys, and payment addresses in their raw form. This is demonstrated by the commands below. - -``` -namadaw add --alias my-sk --value xsktest1qqqqqqqqqqqqqq9v0sls5r5de7njx8ehu49pqgmqr9ygelg87l5x8y4s9r0pjlvu69au6gn3su5ewneas486hdccyayx32hxvt64p3d0hfuprpgcgv2q9gdx3jvxrn02f0nnp3jtdd6f5vwscfuyum083cvfv4jun75ak5sdgrm2pthzj3sflxc0jx0edrakx3vdcngrfjmru8ywkguru8mxss2uuqxdlglaz6undx5h8w7g70t2es850g48xzdkqay5qs0yw06rtxcvedhsv -namadaw add --alias my-vk --value xfvktest1qqqqqqqqqqqqqqpagte43rsza46v55dlz8cffahv0fnr6eqacvnrkyuf9lmndgal7erg38awgq60r259csg3lxeeyy5355f5nj3ywpeqgd2guqd73uxz46645d0ayt9em88wflka0vsrq29u47x55psw93ly80lvftzdr5ccrzuuedtf6fala4r4nnazm9y9hq5yu6pq24arjskmpv4mdgfn3spffxxv8ugvym36kmnj45jcvvmm227vqjm5fq8882yhjsq97p7xrwqt7n63v -namadaw add --alias my-pa --value patest10qy6fuwef9leccl6dfm7wwlyd336x4y32hz62cnrvlrl6r5yk0jnw80kus33x34a5peg2xc4csn -``` - -### Making Shielded Transactions - -#### Shielding Transactions - -In order to shield tokens from a transparent address, the user must first generate a shielded payment address in which the user holds the spending key for. It is then possible to make a transfer from the transparent address to the newly created shielded payment address. Once this process is completed, the new tokens are now considered "shielded". The -gas fee is charged to the source address that makes the transfer to the shielded payment address. Shielding tokens can be done as following: - -``` -namadac transfer --source Bertha --amount 50 --token BTC --target my-pa -``` - -#### Unshielding Transactions - -"Unshielding" is the process of transferring token balances from the shielded set to the transparent one. When the user makes a transfer from a shielded account (using the corresponding spending key) to a transparent account, the newly transferred funds are considered "unshielded". The gas fee is charged to the signer's address (which should default to the target -address). Once the transaction is complete, the spending key will no -longer be able to spend the transferred amount. Below is an example of -how an unshielding transaction is performed: +### Viewing your balance +To view the up-to-date balance of your spending key (or viewing key), you must first run the `shielded-sync` command to +sync the local shielded context with any MASP notes owned by your spending/viewing key: +```bash copy +namadac shielded-sync --spending-keys ``` -namadac transfer --target Bertha --amount 45 --token BTC --source my-sk +or +```bash copy +namadac shielded-sync --viewing-keys ``` -#### Shielded Transactions - -Shielded transfers are made from one shielded account to another. From a user perspective, this is almost equivalent to a transparent-transparent token transfer, except the gas fee is paid by the signer of the transaction. The command for performing a shielded transfer is given below: - -``` -namadac transfer --source my-sk --amount 5 --token BTC --target your-pa -``` - -### Viewing Shielded Balances - -The viewing key that is derived from a spending key allows any user holding that key to view the balances attached to corresponding spending key. It is possible to use this viewing key to either decipher the full balance of the corresponding viewing key or query a subset of them. - -``` -namadac balance -namadac balance --owner -namadac balance --owner --token BTC -namadac balance --token BTC -``` - -### Listing Shielded Keys/Addresses - -The wallet is able to list all the spending keys, viewing keys, -and payment addresses that it stores. Below are examples of how the -wallet's storage can be queried: + +The first time you wish to check the balance of a spending/viewing key, you must provide it to the shielded context with +`--spending-keys|--viewing-keys`. On subsequent runs, you can simply use `namadac shielded-sync`. + -``` -namadaw list --keys -namadaw list --keys --unsafe-show-secret -namadaw list --keys --unsafe-show-secret --decrypt -namadaw list --addr +After the sync has completed, check your balance with: +```bash copy +namadac balance --owner --token ``` -### Finding Shielded Keys/Addresses - -The wallet is able to find any spending key, viewing key or -payment address when given its alias. Below are examples of how the -wallet's storage can be queried: - -``` -namadaw find --alias my-alias -namadaw find --alias my-alias --unsafe-show-secret -``` +This will display the combined balance of all shielded addresses associated with that spending/viewing key. \ No newline at end of file diff --git a/packages/docs/pages/users/shielded-accounts/shielding.mdx b/packages/docs/pages/users/shielded-accounts/shielding.mdx new file mode 100644 index 00000000..a6413318 --- /dev/null +++ b/packages/docs/pages/users/shielded-accounts/shielding.mdx @@ -0,0 +1,55 @@ +import { Steps } from 'nextra-theme-docs' +import { Callout } from 'nextra-theme-docs' + +# Shielding Assets + +You can shield assets in the MASP by making a transfer from a transparent address to a shielded address. This is known +as a __shielding transfer__. + +Assets can also be sent directly to a shielded address through IBC -- see the section on [Shielded IBC](../../users/ibc/shielded-ibc.mdx) for details. + +## Making a shielding transfer + +To conduct a shielding transfer, the user must first be in possession of a transparent account with some token balance. + + + +### Generate a spending key +See [Shielded Key Management](./masp-keys.mdx) for details on how to do this. + +### Derive a new shielded address (aka: payment address) +You can (and should) derive multiple shielded addresses for the same spending key. + +### Send your shielding transfer +```bash copy +namadac transfer \ + --source \ + --target \ + --token \ + --amount +``` + + + +### Viewing your balance +To view the up-to-date balance of your spending key (or viewing key), you must first run the `shielded-sync` command to +sync the local shielded context with any MASP notes owned by your spending/viewing key: +```bash copy +namadac shielded-sync --spending-keys +``` +or +```bash copy +namadac shielded-sync --viewing-keys +``` + + +The first time you wish to check the balance of a spending/viewing key, you must provide it to the shielded context with +`--spending-keys|--viewing-keys`. On subsequent runs, you can simply use `namadac shielded-sync`. + + +After the sync has completed, check your balance with: +```bash copy +namadac balance --owner --token +``` + +This will display the combined balance of all shielded addresses associated with that spending/viewing key. \ No newline at end of file diff --git a/packages/docs/pages/users/shielded-accounts/unshielding.mdx b/packages/docs/pages/users/shielded-accounts/unshielding.mdx new file mode 100644 index 00000000..f06bc1e6 --- /dev/null +++ b/packages/docs/pages/users/shielded-accounts/unshielding.mdx @@ -0,0 +1,30 @@ +import { Callout } from 'nextra-theme-docs' + +# Unshielding Assets + +You can unshield assets in the MASP by making a transfer from a shielded address to a transparent address. This is known as an __unshielding transfer__. + +Assets can also be sent directly from a shielded address through IBC -- see the section on Shielded IBC for details. + +## Making an unshielding transfer + +Before making an unshielding transfer, it is recommended to first sync the local shielded context: +```bash copy +namadac shielded-sync --spending-keys +``` + +To make an unshielding transfer, you must possess the relevant spending key. See the [glossary](./glossary.mdx) for +an explanation on the types of keys and addresses used with the MASP. + +```bash copy +namadac transfer \ + --source \ + --target \ + --token \ + --amount \ + --gas-payer +``` + +Note: you must provide an implicit account you control containing funds for transcation fees. This does not have to be +the same as the target. + \ No newline at end of file diff --git a/packages/docs/pages/users/wallet/file-system-wallet.mdx b/packages/docs/pages/users/wallet/file-system-wallet.mdx index ef48f9e4..7d0f0b18 100644 --- a/packages/docs/pages/users/wallet/file-system-wallet.mdx +++ b/packages/docs/pages/users/wallet/file-system-wallet.mdx @@ -58,6 +58,20 @@ namadaw derive --alias ``` (You will be prompted to enter the mnemonic). +#### Adding an existing key or address to your wallet + +If you know the raw value of a key or address, you can add it to your wallet under an alias so you can more conveniently refer to it later. + +```bash copy +namadaw add --alias --value +``` + +#### Removing a key/address +You can remove all keys/addresses associated with an alias from your wallet with: +```bash copy +namadaw remove --alias --do-it +``` + #### Using the Pregenesis flag Normally, you will be expected to join a network before using the wallet; and `namadaw` will throw an error when an existing chain context is not found. However, there may be times when you want to use `namadaw` prior to joining a chain -- for example, when generating a keypair to From a7bd5b242473153d57c9461f066556c23968a410 Mon Sep 17 00:00:00 2001 From: brentstone Date: Tue, 4 Jun 2024 12:37:27 +0200 Subject: [PATCH 77/94] remove eth-bridge content --- .../install/binaries/overview-of-binaries.mdx | 2 - packages/docs/pages/operators/eth-bridge.mdx | 27 ----------- .../pages/operators/eth-bridge/relaying.mdx | 48 ------------------- 3 files changed, 77 deletions(-) delete mode 100644 packages/docs/pages/operators/eth-bridge.mdx delete mode 100644 packages/docs/pages/operators/eth-bridge/relaying.mdx diff --git a/packages/docs/pages/introduction/install/binaries/overview-of-binaries.mdx b/packages/docs/pages/introduction/install/binaries/overview-of-binaries.mdx index 93b941b0..e2091514 100644 --- a/packages/docs/pages/introduction/install/binaries/overview-of-binaries.mdx +++ b/packages/docs/pages/introduction/install/binaries/overview-of-binaries.mdx @@ -10,7 +10,6 @@ Once installed, you should have the following binaries: | `namadan` | The ledger node | | `namadac` | The client | | `namadaw` | The wallet | -| `namadar` | The ethereum bridge relayer | The main binary `namada` has sub-commands for all of the other binaries. Therefore, the following commands are equivalent: @@ -19,7 +18,6 @@ The main binary `namada` has sub-commands for all of the other binaries. Therefo | `namada client` | `namadac` | | `namada node` | `namadan` | | `namada wallet` | `namadaw` | -| `namada relayer` | `namadar` | To explore the command-line interface, the `--help` argument can be added at any sub-command level to find out any possible sub-commands and/or arguments. diff --git a/packages/docs/pages/operators/eth-bridge.mdx b/packages/docs/pages/operators/eth-bridge.mdx deleted file mode 100644 index 1d0e92a8..00000000 --- a/packages/docs/pages/operators/eth-bridge.mdx +++ /dev/null @@ -1,27 +0,0 @@ -# Namada Ethereum Bridge - -The ethereum bridge on Namada is a trustless (in the sense that the only trust assumptions are that validators on Namada are collectively honest) bridge between Namada and Ethereum. - -The bridge is a combination of smart contracts on Ethereum as well as ledger protocol code that enables its functionality. The bridge is designed to be generic, and can be used to bridge any chain that has a BFT consensus mechanism. - - -## Design - -The full design specs can be found [here](https://specs.namada.net/modules/ethereum-bridge). - -A short outline of the design is outlined below. - -## The ethereum side - -Value transferred to the Namada is escrowed in a vault abstraction, which -enables other contracts to be upgraded without moving value around. When ERC20 -tokens are transferred back to Ethereum, value is released from escrow into the -destination accounts. - -## The Namada side - -When a transfer is initiated from Ethereum to Namada, the transfer is validated by the validators. Once this validation is complete, the transferred funds are minted on the Namada side and sent to the destination account. When tokens are sent back to Ethereum, they are burnt on the Namada end. - -This documentation is intended for relayers and validators on Namada and is structured as follows: - -- [Relaying transactions](./eth-bridge/relaying.mdx) \ No newline at end of file diff --git a/packages/docs/pages/operators/eth-bridge/relaying.mdx b/packages/docs/pages/operators/eth-bridge/relaying.mdx deleted file mode 100644 index 553a4142..00000000 --- a/packages/docs/pages/operators/eth-bridge/relaying.mdx +++ /dev/null @@ -1,48 +0,0 @@ -import { Callout } from 'nextra-theme-docs' - -# Relaying Ethereum Transactions - -Relayer commands are found in the `namadar` binary, which at the moment can only be installed from source. - -## Relaying validator set updates - -In order for any transactions to be relayed to the Ethereum smart contract, the validator sets need to be up to date on the Ethereum side. This is updated by a relayer which can be set up in the following manner: - -```bash copy -namadar validator-set relay --daemon --confirmations 1 --retry-sleep 0 --success-sleep 0 --safe-mode -``` - -The `--safe-mode` flag is optional, but recommended. It will stop the relayer from being shut down by `^C` and will instead wait for the current batch of transactions to be relayed before shutting down. - -More optional flags are available, which can be found by running `namadar validator-set relay --help`. Notably, `--eth-gas`and `--eth-gas-price` will allow you to set the maximum gas-limit and gas-price, respectively, that the relayer will use when relaying transactions to the Ethereum smart contract. - -## Relaying transactions - -Transactions are relayed in batches. The relayer will wait until it has a batch of transactions to relay before sending them to the Ethereum smart contract. This is done to reduce the number of transactions that need to be sent to the Ethereum smart contract, and thus reduce the gas costs. - -The relayer can get a "recommended-batch" of signed transactions to relay by running: - -```bash -namadar ethereum-bridge-pool recommend-batch -``` - -If this is favourable for the relayer, it can construct the proof and relay it to the Ethereum smart contract by running: - -```bash -namadar ethereum-bridge-pool relay-proof --hash-list $HASH_LIST -``` - - -As this involves an Ethereum transaction, the `--eth-gas` and `--eth-gas-price` flags are also available here. - - -Alternatively, the relayer can run the command: - -```bash -namadar ethereum-bridge-pool construct-proof --hash-list $HASH_LIST -``` - -To only construct the proof without relaying it. The proof could then be relayed manually by the relayer. - - - From 7ed3b6c3be834d4b0fd2f7cbcec14730e4e43fe3 Mon Sep 17 00:00:00 2001 From: brentstone Date: Tue, 4 Jun 2024 12:41:28 +0200 Subject: [PATCH 78/94] update intro page --- packages/docs/pages/index.mdx | 2 -- 1 file changed, 2 deletions(-) diff --git a/packages/docs/pages/index.mdx b/packages/docs/pages/index.mdx index 99653ab7..aef49e30 100644 --- a/packages/docs/pages/index.mdx +++ b/packages/docs/pages/index.mdx @@ -11,13 +11,11 @@ Namada's cryptographical features give users asset-agnostic, multichain data pro - Zcash-like shielded transfers for any assets (fungible and non-fungible) - Rewards for keeping assets in the shielded set -- Interoperability with Ethereum via a custom bridge with trust-minimization ## Overview of features - [Proof-of-Stake](./introduction/protocol-intro.mdx) with [governance](./users/governance.mdx) to secure and evolve Namada - Fast-finality BFT with 4-second blocks -- Trust-minimized 2-way Ethereum bridge - IBC connections to chains that already speak IBC (all Cosmos chains) - [Multi-Asset Shielded Pool](./users/shielded-accounts/shielded-transfers.mdx) (MASP) - Convert Circuit ([shielded set rewards](./users/shielded-accounts/shielded-rewards.mdx)) From 4053a33b6f3f31656706083a1862dcf844cfb198 Mon Sep 17 00:00:00 2001 From: brentstone Date: Tue, 4 Jun 2024 12:53:12 +0200 Subject: [PATCH 79/94] more removal --- .../light-sdk/usage/transactions.mdx | 15 --------------- packages/docs/pages/introduction/privacy.mdx | 2 +- packages/docs/pages/networks/testnets/faq.mdx | 4 ---- .../users/governance/on-chain-governance.mdx | 11 ----------- 4 files changed, 1 insertion(+), 31 deletions(-) diff --git a/packages/docs/pages/integrating-with-namada/light-sdk/usage/transactions.mdx b/packages/docs/pages/integrating-with-namada/light-sdk/usage/transactions.mdx index 0ecc2a81..88c2e0b6 100644 --- a/packages/docs/pages/integrating-with-namada/light-sdk/usage/transactions.mdx +++ b/packages/docs/pages/integrating-with-namada/light-sdk/usage/transactions.mdx @@ -3,7 +3,6 @@ The transaction module exposes various modules (objects) to construct transactio ```rust pub mod account; // contains functions to create transactions for account module -pub mod bridge; // contains functions to create transactions for bridge module pub mod governance; // contains functions to create transactions for governance module pub mod ibc; // contains functions to create transactions for ibc module pub mod pgf; // contains functions to create transactions for pgf module @@ -57,20 +56,6 @@ impl InitAccount { A public key can be constructed from a string using the `::from_str()` method. The `vp_code_hash` is a hash that is found under the `wasm` folder. -### Bridge - -```rust -pub use namada_sdk::eth_bridge_pool::{GasFee, TransferToEthereum}; -pub struct BridgeTransfer(Tx); -impl BridgeTransfer { - pub fn new( - transfer: TransferToEthereum, - gas_fee: GasFee, - args: GlobalArgs, - ) -> Self {...} -} -``` - ### Governance ```rust diff --git a/packages/docs/pages/introduction/privacy.mdx b/packages/docs/pages/introduction/privacy.mdx index 06bdf60a..3ed6ea73 100644 --- a/packages/docs/pages/introduction/privacy.mdx +++ b/packages/docs/pages/introduction/privacy.mdx @@ -6,7 +6,7 @@ Namada provides the largest possible unified shielded set in the multichain, com * Namada can also seed data protection to users who want to use an asset originating from one base chain on another chain, without losing data protection * Namada retrofits data protection to assets that were created and already used in transparent chains -Users should be aware that they can still expose personal information when transferring funds into and out of Namada via the Ethereum bridge or IBC. For example, a user bridging WETH from Ethereum may be able to obfuscate their on-chain identities to *some* on-chain observers by interacting with Smart contract based shielding protocols or centralized exchanges. However, a user transferring a non-fungible token or a low liquidity token that relies on price discovery on-chain, will leak more information by the nature of their asset holdings. This is also true of tokens transferred into and out of Namada via IBC. Once inside the shielded set, a user can perform *shielded actions* such as triggering a cross chain swap. +Users should be aware that they can still expose personal information when transferring funds into and out of Namada via IBC. For example, a user bridging WETH from Ethereum may be able to obfuscate their on-chain identities to *some* on-chain observers by interacting with Smart contract based shielding protocols or centralized exchanges. However, a user transferring a non-fungible token or a low liquidity token that relies on price discovery on-chain, will leak more information by the nature of their asset holdings. This is also true of tokens transferred into and out of Namada via IBC. Once inside the shielded set, a user can perform *shielded actions* such as triggering a cross chain swap. Shielded actions are not limited to application chains that are IBC compatible, it works with any chain that is connected to Namada, e.g. Ethereum, and the actions can be generalized to interact with any dApp, such as trading NFTs or staking ETH. For the time being, the only shielded action available is cross chain transfers, but more will be added in the future. diff --git a/packages/docs/pages/networks/testnets/faq.mdx b/packages/docs/pages/networks/testnets/faq.mdx index 7cab9d10..b684b276 100644 --- a/packages/docs/pages/networks/testnets/faq.mdx +++ b/packages/docs/pages/networks/testnets/faq.mdx @@ -17,10 +17,6 @@ There are a few more, but we leave it to you as a challenge to find out which these are πŸ€” HINT: `namadac balance` -### **Q: How do I use the Ethereum Bridge?** - -**A:** The Ethereum Bridge is not yet implemented. Keep an eye on the [Changelog](https://github.com/anoma/namada/tree/main/.changelog) πŸ‘€ to see when it will be officially released. - ### **Q: How can I make an IBC transfer?** **A:** As of `v0.23.1` you can now follow the docs [here!](../../users/ibc.mdx) diff --git a/packages/docs/pages/users/governance/on-chain-governance.mdx b/packages/docs/pages/users/governance/on-chain-governance.mdx index c7b346ae..1cd6a283 100644 --- a/packages/docs/pages/users/governance/on-chain-governance.mdx +++ b/packages/docs/pages/users/governance/on-chain-governance.mdx @@ -173,17 +173,6 @@ For a pgf proposal that is to be executed on an IBC chain, the "Internal" data s } ``` -### ETH Bridge Proposal - -```json -"data" : "" -``` - - -**Note**: -The encoding will be submitted as a string - - ## Submitting the proposal As soon as your `proposal.json` file is ready, you can submit the proposal with (make sure to be in the same directory as the `proposal.json` file): From f584bf116c12aff38d43abae11f32b9f5d7cc956 Mon Sep 17 00:00:00 2001 From: Ian Date: Tue, 11 Jun 2024 10:43:15 -0400 Subject: [PATCH 80/94] update transfer commands (#360) --- .../users/shielded-accounts/masp-keys.mdx | 20 +++++++++------ .../shielded-accounts/shielded-transfers.mdx | 25 +++++++++++-------- .../users/shielded-accounts/shielding.mdx | 25 +++++++++++++------ .../users/shielded-accounts/unshielding.mdx | 18 +++++++------ .../send-and-receive-nam-tokens.mdx | 13 +++++----- 5 files changed, 60 insertions(+), 41 deletions(-) diff --git a/packages/docs/pages/users/shielded-accounts/masp-keys.mdx b/packages/docs/pages/users/shielded-accounts/masp-keys.mdx index f14fed2f..ad0e77f6 100644 --- a/packages/docs/pages/users/shielded-accounts/masp-keys.mdx +++ b/packages/docs/pages/users/shielded-accounts/masp-keys.mdx @@ -4,13 +4,15 @@ import { Callout } from 'nextra-theme-docs' This section will detail the commands to generate spending keys, viewing keys and payment addresses with `namadaw`. -For an explanation of the different types of keys and addresses, see the [glossay](./glossary.mdx). +For an explanation of the different types of keys and addresses, see the [glossary](./glossary.mdx). ### Generating a spending key and viewing key -Create a new spending key with: +The first step before interacting with the MASP is to create a spending key. A spending key is loosely analogous to the private key you may be familiar with +from [transparent accounts](../transparent-accounts.mdx), in the sense that it grants one the authority to spend tokens in the associated account (and must always be +kept secret). Create a new spending key with: ```bash copy -namadaw gen --shielded --alias +namadaw gen --shielded --alias $SPENDING_KEY_ALIAS ``` This command will also generate a corresponding Viewing Key sharing @@ -36,9 +38,10 @@ namadaw list --shielded --unsafe-show-secret --decrypt ### Generating a payment address -Once you have created a spending key, it can be used to derive a payment address: +Once you have created a spending key, it can be used to derive a payment address. A payment address begins with `znam` and is a public-facing address which you can +share when you wish to receive tokens. ```bash copy -namadaw gen-payment-addr --alias --key +namadaw gen-payment-addr --alias $PAYMENT_ADDRESS_ALIAS --key $SPENDING_KEY_ALIAS ``` It is possible (and recommended) to generate multiple payment addresses from the same spending key. @@ -54,7 +57,7 @@ namadaw list --shielded You can recover an existing spending key from your mnemonic and add it to your wallet with: ```bash copy -namadaw derive --alias --shielded +namadaw derive --alias $SPENDING_KEY_ALIAS --shielded ``` ### Adding an existing key or payment address to your wallet @@ -62,11 +65,12 @@ namadaw derive --alias --shielded If you know the raw value of a spending key, viewing key or payment address, you can add it to your wallet under an alias so you can more conveniently refer to it later. ```bash copy -namadaw add --alias --value +namadaw add --alias $ALIAS --value $HEX_VALUE ``` +where `$HEX_VALUE` is the hex value of a spending key, viewing key or payment address. ### Removing a key/address You can remove all keys/addresses associated with an alias from your wallet with: ```bash copy -namadaw remove --alias --do-it +namadaw remove --alias $ALIAS --do-it ``` \ No newline at end of file diff --git a/packages/docs/pages/users/shielded-accounts/shielded-transfers.mdx b/packages/docs/pages/users/shielded-accounts/shielded-transfers.mdx index 77fc4001..ce8ef29c 100644 --- a/packages/docs/pages/users/shielded-accounts/shielded-transfers.mdx +++ b/packages/docs/pages/users/shielded-accounts/shielded-transfers.mdx @@ -2,28 +2,30 @@ import { Callout } from 'nextra-theme-docs' # Shielded Transfers -Once the user has a shielded balance, it can be transferred to a another shielded address. This is known as a __shielded transfer__. +Once the user has a [shielded balance](./shielding.mdx), it can be transferred to a another shielded address. This is known as a __shielded transfer__. ## Making a shielded transfer Before making a shielded transfer, it is recommended to first sync the local shielded context: ```bash copy -namadac shielded-sync --spending-keys +namadac shielded-sync --spending-keys $SPENDING_KEY ``` To make a shielded transfer, you must possess the relevant spending key. See the [glossary](./glossary.mdx) for an explanation on the types of keys and addresses used with the MASP. +Use the `transfer` command to make a shielded transfer to a target shielded (`znam`) address by providing the spending key associated with the source shielded (`znam`) address: + ```bash copy namadac transfer \ - --source \ - --target \ - --token \ - --amount \ - --gas-payer + --source $SPENDING_KEY \ + --target $PAYMENT_ADDRESS \ + --token $TOKEN \ + --amount $AMOUNT \ + --gas-payer $IMPLICIT_ACCOUNT ``` -Note: you must provide an implicit account you control containing funds for transcation fees. +Note: you must provide an implicit account which you control containing funds for transcation fees. @@ -31,11 +33,11 @@ Note: you must provide an implicit account you control containing funds for tran To view the up-to-date balance of your spending key (or viewing key), you must first run the `shielded-sync` command to sync the local shielded context with any MASP notes owned by your spending/viewing key: ```bash copy -namadac shielded-sync --spending-keys +namadac shielded-sync --spending-keys $SPENDING_KEY ``` or ```bash copy -namadac shielded-sync --viewing-keys +namadac shielded-sync --viewing-keys $VIEWING_KEY ``` @@ -45,7 +47,8 @@ The first time you wish to check the balance of a spending/viewing key, you must After the sync has completed, check your balance with: ```bash copy -namadac balance --owner --token +namadac balance --owner $SPENDING_KEY --token $TOKEN ``` +(A viewing key can also be provided here instead of `$SPENDING_KEY`) This will display the combined balance of all shielded addresses associated with that spending/viewing key. \ No newline at end of file diff --git a/packages/docs/pages/users/shielded-accounts/shielding.mdx b/packages/docs/pages/users/shielded-accounts/shielding.mdx index a6413318..86bb7398 100644 --- a/packages/docs/pages/users/shielded-accounts/shielding.mdx +++ b/packages/docs/pages/users/shielded-accounts/shielding.mdx @@ -20,13 +20,21 @@ See [Shielded Key Management](./masp-keys.mdx) for details on how to do this. ### Derive a new shielded address (aka: payment address) You can (and should) derive multiple shielded addresses for the same spending key. +### (If needed) submit `reveal-pk` transaction for sending address +You can shield from either an [implicit](../transparent-accounts/implicit-accounts.mdx) or [established](../transparent-accounts/established-accounts.mdx) account. If +shielding from an implicit account, your account's public key must first be revealed on-chain. This only needs to be done once per account: +```bash copy +namadac reveal-pk --public-key $IMPLICIT_ACCOUNT_ALIAS +``` + ### Send your shielding transfer +Use the `shield` command to make a shielding transfer from a source transparent (`tnam`) address to a target shielded (`znam`) address: ```bash copy -namadac transfer \ - --source \ - --target \ - --token \ - --amount +namadac shield \ + --source $TRANSPARENT_ACCOUNT \ + --target $PAYMENT_ADDRESS \ + --token $TOKEN \ + --amount $AMOUNT ``` @@ -35,11 +43,11 @@ namadac transfer \ To view the up-to-date balance of your spending key (or viewing key), you must first run the `shielded-sync` command to sync the local shielded context with any MASP notes owned by your spending/viewing key: ```bash copy -namadac shielded-sync --spending-keys +namadac shielded-sync --spending-keys $SPENDING_KEY ``` or ```bash copy -namadac shielded-sync --viewing-keys +namadac shielded-sync --viewing-keys $VIEWING_KEY ``` @@ -49,7 +57,8 @@ The first time you wish to check the balance of a spending/viewing key, you must After the sync has completed, check your balance with: ```bash copy -namadac balance --owner --token +namadac balance --owner $SPENDING_KEY --token $TOKEN ``` +(A viewing key can also be provided here instead of `$SPENDING_KEY`) This will display the combined balance of all shielded addresses associated with that spending/viewing key. \ No newline at end of file diff --git a/packages/docs/pages/users/shielded-accounts/unshielding.mdx b/packages/docs/pages/users/shielded-accounts/unshielding.mdx index f06bc1e6..037eba36 100644 --- a/packages/docs/pages/users/shielded-accounts/unshielding.mdx +++ b/packages/docs/pages/users/shielded-accounts/unshielding.mdx @@ -10,21 +10,23 @@ Assets can also be sent directly from a shielded address through IBC -- see the Before making an unshielding transfer, it is recommended to first sync the local shielded context: ```bash copy -namadac shielded-sync --spending-keys +namadac shielded-sync --spending-keys $SPENDING_KEY ``` To make an unshielding transfer, you must possess the relevant spending key. See the [glossary](./glossary.mdx) for an explanation on the types of keys and addresses used with the MASP. +Use the `unshield` command to make an unshielding transfer to a target transparent (`tnam`) address by providing the spending key associated with a source shielded (`znam`) address: + ```bash copy -namadac transfer \ - --source \ - --target \ - --token \ - --amount \ - --gas-payer +namadac unshield \ + --source $SPENDING_KEY \ + --target $TRANSPARENT_ACCOUNT \ + --token $TOKEN \ + --amount $AMOUNT \ + --gas-payer $IMPLICIT_ACCOUNT ``` -Note: you must provide an implicit account you control containing funds for transcation fees. This does not have to be +Note: you must provide an implicit account which you control containing funds for transcation fees. This does not have to be the same as the target. \ No newline at end of file diff --git a/packages/docs/pages/users/transparent-accounts/send-and-receive-nam-tokens.mdx b/packages/docs/pages/users/transparent-accounts/send-and-receive-nam-tokens.mdx index 2c486279..58c47c45 100644 --- a/packages/docs/pages/users/transparent-accounts/send-and-receive-nam-tokens.mdx +++ b/packages/docs/pages/users/transparent-accounts/send-and-receive-nam-tokens.mdx @@ -16,13 +16,14 @@ Transfers to/from a `znam...` address (that is, to/from the [MASP](../shielded-a For help creating a new account, see the sections on [Generating an implicit account](../transparent-accounts/implicit-accounts.mdx) or [Using the file system wallet](../../users/wallet/file-system-wallet.mdx). -To submit a regular token transfer from your account to the `validator-1` address: +To send a transparent transfer -- that is, a transfer from one transparent address to another -- we use the `transparent-transfer` command. Transparent transfers are so +named because all associated info (including sender, receiver, asset and amount) is publicly visible on-chain. ```shell copy -namada client transfer \ - --source \ - --target \ - --token \ +namada client transparent-transfer \ + --source $SOURCE \ + --target $TARGET \ + --token $TOKEN \ --amount 10 ``` @@ -33,7 +34,7 @@ This command will attempt to find and use the key of the source address to sign To query token balances for a specific token and/or owner: ```shell copy -namada client balance --token --owner +namada client balance --token $TOKEN --owner $ACCOUNT ``` From 336dd532304348d961820ce769a8866b036a42ad Mon Sep 17 00:00:00 2001 From: iskay Date: Thu, 30 May 2024 16:57:15 -0400 Subject: [PATCH 81/94] update sections on wallet and transparent accounts --- packages/docs/pages/users/_meta.json | 2 +- .../pages/users/transparent-accounts/established-accounts.mdx | 2 +- packages/docs/pages/users/wallet/file-system-wallet.mdx | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/docs/pages/users/_meta.json b/packages/docs/pages/users/_meta.json index f841776d..f611c86d 100644 --- a/packages/docs/pages/users/_meta.json +++ b/packages/docs/pages/users/_meta.json @@ -8,4 +8,4 @@ "public-goods-stewards": "PGF", "ibc": "IBC transfers", "query": "Querying the Chain" -} \ No newline at end of file +} diff --git a/packages/docs/pages/users/transparent-accounts/established-accounts.mdx b/packages/docs/pages/users/transparent-accounts/established-accounts.mdx index 0d607f4b..110336ac 100644 --- a/packages/docs/pages/users/transparent-accounts/established-accounts.mdx +++ b/packages/docs/pages/users/transparent-accounts/established-accounts.mdx @@ -24,4 +24,4 @@ Note that: - the implicit account `my-implicit` is required to sign the init-account transaction and pay the associated fees (with the `--signing-keys` argument) - One public key is being associated with the account, and the signing threshold is 1. Technically, all established accounts are multisignature accounts and therefore a 'typical' established account can be considered a '1 of 1' multisignature account. See [here](./multisignature.mdx) -for further details on using multisignature accounts with multiple keys. \ No newline at end of file +for further details on using multisignature accounts with multiple keys. diff --git a/packages/docs/pages/users/wallet/file-system-wallet.mdx b/packages/docs/pages/users/wallet/file-system-wallet.mdx index 7d0f0b18..555432f0 100644 --- a/packages/docs/pages/users/wallet/file-system-wallet.mdx +++ b/packages/docs/pages/users/wallet/file-system-wallet.mdx @@ -75,4 +75,4 @@ namadaw remove --alias --do-it #### Using the Pregenesis flag Normally, you will be expected to join a network before using the wallet; and `namadaw` will throw an error when an existing chain context is not found. However, there may be times when you want to use `namadaw` prior to joining a chain -- for example, when generating a keypair to -recieve a token allotment in the genesis block of a future chain. In these cases, you can use the flag `--pre-genesis` with your `namadaw` commands. \ No newline at end of file +recieve a token allotment in the genesis block of a future chain. In these cases, you can use the flag `--pre-genesis` with your `namadaw` commands. From a6beb8630a55e51304d10575dc0b685f0e4bc135 Mon Sep 17 00:00:00 2001 From: iskay Date: Wed, 5 Jun 2024 14:46:22 -0400 Subject: [PATCH 82/94] update operators section --- packages/docs/pages/operators.mdx | 4 +- packages/docs/pages/operators/ledger.mdx | 31 ++-- .../docs/pages/operators/ledger/_meta.json | 4 +- .../pages/operators/ledger/base-directory.mdx | 21 ++- .../docs/pages/operators/ledger/env-vars.mdx | 55 ++++--- .../operators/ledger/running-a-full-node.mdx | 64 ++++++-- packages/docs/pages/operators/validators.mdx | 36 +++-- .../pages/operators/validators/_meta.json | 2 +- .../operators/validators/proof-of-stake.mdx | 3 + .../pages/operators/validators/staking.mdx | 20 ++- .../validators/validator-actions.mdx | 95 ++++++++--- .../operators/validators/validator-setup.mdx | 153 +++++++----------- 12 files changed, 304 insertions(+), 184 deletions(-) create mode 100644 packages/docs/pages/operators/validators/proof-of-stake.mdx diff --git a/packages/docs/pages/operators.mdx b/packages/docs/pages/operators.mdx index 1c376b1c..24556cad 100644 --- a/packages/docs/pages/operators.mdx +++ b/packages/docs/pages/operators.mdx @@ -1,7 +1,7 @@ # Operators Guide -This guide is intended for operators of Namada full nodes. This includes both full nodes as well as validator nodes. -The guide assumes that you have already installed the node and are familiar with the basics of running a node. +This section of the guide is intended for operators of Namada full nodes and validator nodes. +It assumes you have already completed the steps to [install Namada](./introduction/install.mdx). ## Table of Contents diff --git a/packages/docs/pages/operators/ledger.mdx b/packages/docs/pages/operators/ledger.mdx index 7d39464f..c919632a 100644 --- a/packages/docs/pages/operators/ledger.mdx +++ b/packages/docs/pages/operators/ledger.mdx @@ -1,41 +1,36 @@ import { Callout } from 'nextra-theme-docs' -# The Namada Ledger +# Running a Full Node +This section of the guide covers running a full (non-consensus) node. For information on running a validator node, see [Validator setup](./validators/validator-setup.mdx). -In order to make any interactions with the Namada blockchain through the Namada *client* `namadac`, the ledger must be running. +A step-by-step guide to setting up and running a full node can be found [here](./ledger/running-a-full-node.mdx). -To start a local Namada ledger node, one can run: +## The Namada ledger + +By starting the ledger process, your node will attempt to connect with network peers and sync to the latest block: ```shell copy -namada ledger +namada node ledger run ``` **Note**: You must have [joined a network](../networks.mdx) before you start the ledger. It throws an error if no network has been configured. - -The node will attempt to connect to the persistent validator nodes and other peers in the network, and synchronize to the latest block. - -By default, the ledger will store its configuration and state in your [base directory](./ledger/base-directory.mdx). -You can use the `--base-dir` CLI global argument or `BASE_DIR` environment variable to change it. - -Assuming you do not have a custom base_dir, you can export the BASE_DIR environment variable as follows: - -```shell copy -export BASE_DIR=$(namadac utils default-base-dir) -``` -When the ledger is run for the first time, the MASP-parameters will be downloaded. This is essential for producing the zero knowledge proofs required to make shielded transactions. +### MASP parameters +When the ledger is run for the first time, the MASP-parameters will be downloaded. This is essential for producing the zero knowledge proofs required to make shielded transactions. + +The default location of the MASP params is `$HOME/.masp-params`. ### The ledger wasm files -The ledger will also download the genesis block, which contains the initial state of the blockchain. +When running the `join-network` command, the ledger will also download the genesis files, which contain the initial state of the blockchain. The ledger also needs access to the built WASM files that are used in the genesis block. These files are included in release and shouldn't be modified, otherwise your node will fail with a consensus error on the genesis block. By default, these are expected to be in the `wasm` directory inside the chain directory that's in the base directory, i.e `$BASE_DIR/$CHAIN_ID/wasm`. The wasm directory can also be set with the `--wasm-dir` CLI global argument, `NAMADA_WASM_DIR` [environment variable](./ledger/env-vars.mdx) or the configuration file. ### Ledger configuration -The ledger configuration is stored in `$BASE_DIR/$CHAIN_ID/config.toml` (with +The [ledger configuration](./ledger/env-vars.mdx) is stored in `$BASE_DIR/$CHAIN_ID/config.toml` (with default `--base-dir`). It is created when you join the network. You can modify that file to change the configuration of your node. All values can also be set via [environment variables](./ledger/env-vars.mdx). diff --git a/packages/docs/pages/operators/ledger/_meta.json b/packages/docs/pages/operators/ledger/_meta.json index 85388e4a..6f561925 100644 --- a/packages/docs/pages/operators/ledger/_meta.json +++ b/packages/docs/pages/operators/ledger/_meta.json @@ -1,6 +1,6 @@ { - "env-vars": "Environment variables", - "running-a-full-node": "Setting up the full node", + "env-vars": "Node Configuration", + "running-a-full-node": "Full node step-by-step", "logging-config": "Logging configurations", "base-directory": "Base directory" } \ No newline at end of file diff --git a/packages/docs/pages/operators/ledger/base-directory.mdx b/packages/docs/pages/operators/ledger/base-directory.mdx index 17696190..29097e5a 100644 --- a/packages/docs/pages/operators/ledger/base-directory.mdx +++ b/packages/docs/pages/operators/ledger/base-directory.mdx @@ -37,8 +37,21 @@ $HOME/Library/Application\ Support/Namada Within these folders, you should see the following files and folders: ```bash copy -global-config.toml -/ -.toml -pre-genesis # If you are a pre-genesis validator +. +└── $BASE_DIR/ + β”œβ”€β”€ global-config.toml + └── $CHAIN_ID/ + β”œβ”€β”€ balances.toml + β”œβ”€β”€ chain.toml + β”œβ”€β”€ cometbft/ + β”œβ”€β”€ config.toml + β”œβ”€β”€ db/ + β”œβ”€β”€ parameters.toml + β”œβ”€β”€ tokens.toml + β”œβ”€β”€ transactions.toml + β”œβ”€β”€ tx_wasm_cache/ + β”œβ”€β”€ validity_predicates.toml + β”œβ”€β”€ vp_wasm_cache/ + β”œβ”€β”€ wallet.toml + └── wasm/ ``` diff --git a/packages/docs/pages/operators/ledger/env-vars.mdx b/packages/docs/pages/operators/ledger/env-vars.mdx index c781791d..74ff5a2f 100644 --- a/packages/docs/pages/operators/ledger/env-vars.mdx +++ b/packages/docs/pages/operators/ledger/env-vars.mdx @@ -1,9 +1,9 @@ import { Callout } from 'nextra-theme-docs' import Expandable from "../../../components/Expandable"; -# Environment variables +# Node Configuration -By default, whenever the namada ledger is started, it will apply the confirguration found in the ledger configuration file. +By default, whenever the namada ledger is started, it will apply the confirguration found in the ledger configuration file `$BASE_DIR/$CHAIN_ID/config.toml`. An example of a ledger configuration file is displayed below. @@ -12,11 +12,11 @@ An example of a ledger configuration file is displayed below. wasm_dir = "wasm" [ledger] -genesis_time = "2023-06-29T17:00:00+00:00" -chain_id = "" +genesis_time = "2024-06-03T17:32:06+00:00" +chain_id = "" [ledger.shell] -base_dir = "/Users/fraccaman/Library/Application Support/Namada" +base_dir = "/root/.local/share/namada/" storage_read_past_height_limit = 3600 db_dir = "db" cometbft_dir = "cometbft" @@ -24,24 +24,27 @@ tendermint_mode = "Full" [ledger.cometbft] proxy_app = "tcp://127.0.0.1:26658" -moniker = "1337-leet-1337" +moniker = "technodrome" +fast_sync = true db_backend = "goleveldb" db_dir = "data" log_level = "info" log_format = "plain" genesis_file = "config/genesis.json" -node_key_file = "config/node_key.json" -abci = "socket" -filter_peers = false priv_validator_key_file = "config/priv_validator_key.json" priv_validator_state_file = "data/priv_validator_state.json" priv_validator_laddr = "" +node_key_file = "config/node_key.json" +abci = "socket" +filter_peers = false [ledger.cometbft.rpc] laddr = "tcp://127.0.0.1:26657" cors_allowed_origins = [] cors_allowed_methods = ["HEAD", "GET", "POST"] cors_allowed_headers = ["Origin", "Accept", "Content-Type", "X-Requested-With", "X-Server-Time"] +grpc_laddr = "" +grpc_max_open_connections = 900 unsafe = false max_open_connections = 900 max_subscription_clients = 100 @@ -89,11 +92,6 @@ max_batch_bytes = 0 [ledger.cometbft.consensus] wal_file = "data/cs.wal/wal" -double_sign_check_height = 0 -create_empty_blocks = true -create_empty_blocks_interval = "0ms" -peer_gossip_sleep_duration = "100ms" -peer_query_maj23_sleep_duration = "2000ms" timeout_propose = "3000ms" timeout_propose_delta = "500ms" timeout_prevote = "1000ms" @@ -101,15 +99,24 @@ timeout_prevote_delta = "500ms" timeout_precommit = "1000ms" timeout_precommit_delta = "500ms" timeout_commit = "10000ms" +double_sign_check_height = 0 +skip_timeout_commit = false +create_empty_blocks = true +create_empty_blocks_interval = "0ms" +peer_gossip_sleep_duration = "100ms" +peer_query_maj23_sleep_duration = "2000ms" + +[ledger.cometbft.storage] +discard_abci_responses = false [ledger.cometbft.tx_index] indexer = "null" [ledger.cometbft.instrumentation] -prometheus = false +prometheus = true prometheus_listen_addr = ":26660" max_open_connections = 3 -namespace = "namada_tm" +namespace = "tendermint" [ledger.cometbft.statesync] enable = false @@ -119,13 +126,25 @@ trust_hash = "" trust_period = "168h0m0s" discovery_time = "15000ms" temp_dir = "" + +[ledger.cometbft.fastsync] +version = "v0" + +[ledger.ethereum_bridge] +mode = "RemoteEndpoint" +oracle_rpc_endpoint = "http://127.0.0.1:8545" +channel_buffer_size = 1000 ``` -However, it is possible to override the configuration by setting environment variables. -Any variable found in the config can be accessed through environment variables that are constructed in the below manner. + +CometBFT has its own `config.toml` located inside the `cometbft` directory, however it should not be edited directly. + ### Constructing environment variables +It is possible to override the configuration by setting environment variables; these will take precedence over any existing settings in `config.toml`. +Any variable found in the config can be accessed through environment variables that are constructed in the below manner. + Names of the recognized environment variables are derived from the configuration keys by: 1. Prepend `NAMADA_` to the key diff --git a/packages/docs/pages/operators/ledger/running-a-full-node.mdx b/packages/docs/pages/operators/ledger/running-a-full-node.mdx index c691d360..fc75480e 100644 --- a/packages/docs/pages/operators/ledger/running-a-full-node.mdx +++ b/packages/docs/pages/operators/ledger/running-a-full-node.mdx @@ -1,16 +1,41 @@ import { Callout } from 'nextra-theme-docs' +import { Steps } from 'nextra-theme-docs' # Full Node Setup -Before starting a full node, the unique identifier of the `chain-id` will be needed, which will be released as soon as the genesis file is ready. +This section details the setup procedure for a full node. If you intend to run a validator node, please see the [Validator setup](../validators/validator-setup.mdx) guide instead. +### Prerequisites +- A machine that meets the [requirements](../hardware.mdx) for a full node +- An associated public IPv4 address with port 26656 reachable from anywhere for P2P connections +- You have already [installed](../../introduction/install.mdx) Namada and its prerequisites +- You know the unique `chain-id` identifier of the network you wish to join. The chain-id is publicly released once the genesis files have been prepared + + ### Join the network -Once the `chain-id` has been distributed, it is possible to join the network with the `CHAIN_ID`: +Once the `chain-id` has been distributed, it is possible to [join the network](../networks.mdx) with the `CHAIN_ID`. This step will download the `.tar.gz` archive +containing the genesis files for the chain and initialize the node store in your [`BASE_DIR`](../ledger/base-directory.mdx). ```bash copy export CHAIN_ID="namada-mainnet" ## (replace with the actual chain-id) - NAMADA_NETWORK_CONFIGS_SERVER="https://github.com/anoma/namada-shielded-expedition/releases/download/shielded-expedition.88f17d1d14" namada client utils join-network --chain-id $CHAIN_ID - ``` + namada client utils join-network --chain-id $CHAIN_ID --add-persistent-peers +``` + +You can specify the location from which to download the genesis `.tar.gz` by exporting the environment variable `NAMADA_NETWORK_CONFIGS_SERVER` prior to running the `join-network` command. +This is useful for joining a community-run or local testnet. + +By default, `join-network` will attempt to download the genesis files from `https://github.com/heliaxdev/anoma-network-config/releases/download/$CHAIN_ID`. + + + +### Check/Update persistent peers +To sync block data, your node will need to connect with existing peers on the network. Peer addresses can be provided in the node's [configuration](./env-vars.mdx) in +the field `persistent_peers`. + +Your `persistent_peers` entry will need to contain at least one peer which is active and accepting incoming connections (the more, the better). If you used the +`--add-persistent-peers` flag during the join-network step, your persistent peers will be pre-populated with the addresses of the genesis validators. However, if you're [having trouble](../troubleshooting.mdx) +syncing, you may wish to check the Discord server for an updated list. ### Start your node and sync +This command will start syncing your node with the network (an environment variable is being used here to set the [logging configuration](./logging-config.mdx)): ```bash copy CMT_LOG_LEVEL=p2p:none,pex:error namada node ledger run ``` @@ -25,18 +50,39 @@ NAMADA_LOG=info CMT_LOG_LEVEL=p2p:none,pex:error NAMADA_CMT_STDOUT=true namada n tail -f -n 20 logs-${TIMESTAMP}.txt ## (in another shell) ``` -### Running namada as a systemd service +### Done! +You should soon see messages similar to the following in your logs to indicate that your node has begun syncing blocks: +```bash copy +INFO namada_node::shell: Committed block hash: 0c56ebc5ae17ef503c675ad8a9b255e69258e7e4915f91e161f98d3b0040a0c1, height: 2650 +committed state module=state height=2650 num_txs=0 app_hash=0C56EBC5AE17EF503C675AD8A9B255E69258E7E4915F91E161F98D3B0040A0C1 +indexed block exents module=txindex height=2650 +``` + +You can also easily check your node's last committed block with the following command: +``` +# namadac block +Last committed block height: 8612, time: 2024-06-04T18:17:06.136117438+00:00 +``` +By comparing it with the current height of the chain from a public source (such as a block explorer), you can monitor how your node is progressing. + +If your node does not show indications of syncing, proceed to the [troubleshooting](../troubleshooting.mdx) section. + +## Running the `namada ledger` as a systemd service The below script is a community contribution by Encipher88, and currently only works on Ubuntu machines. It has served useful for many validators. + +For operators using Ubuntu, it is common to use the `systemd` service manager to run the ledger process in the background. Advantages of this method +include automatic restart upon crash and integrated logging. + The below assumes you have installed namada from source, with `make install`. It at least assumes the respective binaries are in `/usr/local/bin/`. ```bash copy which namada ## (should return /usr/local/bin/namada) ``` -The below makes a service file for systemd, which will run namada as a service. This is useful for running a node in the background, and also for auto-restarting the node if it crashes. +We define a new process as a systemd service by creating a `unit file` in `/etc/systemd/system/`: ```bash copy sudo tee /etc/systemd/system/namadad.service > /dev/null < --commission-rate ``` -The `max-commission-rate-change` is unique to each validator and cannot be changed. + +The maximum allowed change in commision rate per epoch is specified by the validator's `max-commission-rate-change` parameter. + +The `max-commission-rate-change` can only be set on validator initialization; it cannot be changed later. + + + +### Metadata changes -## Metadata changes +Each validator account has associated on-chain metadata; in addition to the (required) security email address, several optional fields (such as name, avatar, etc.) +can be provided. These are commonly displayed in applications such as block explorers or wallets to visually distinguish validators from one another. -A validator can change their metadata through the `change-metadata` command: +A validator can update their metadata at any time with the `change-metadata` command: ```bash copy -namadac change-metadata --validator --description --email --discord-handle --website --avatar +namadac change-metadata \ + --validator \ + --description \ + --email \ + --discord-handle \ + --website \ + --avatar ``` -Apart from `--validator`, not all of the fields are required, but at least one of them is. +Apart from `--validator`, not all of the fields are required (but at least one of them is). -## Deactivation and reactivation +### Deactivation and reactivation -A validator can deactivate their validator (stop validating) through the `deactivate` command: +You can deactivate your validator with the `deactivate` command: ```bash copy namadac deactivate-validator --validator ``` -This means that the validator will no longer participate in the consensus protocol. This becomes active at the end of the current epoch + `pipeline_length`. All bonds and delegations associated with the validator remain in tact. Delegators can still delegate to the validator, but the validator will not be able to participate in consensus until it is reactivated. +Once deactivated, the validator will no longer participate in the consensus protocol. +This will take effect at the end of the current epoch + `pipeline_length`. All bonds and delegations associated with the validator remain intact. +Delegators can still delegate to the validator, but as the validator is inactive, it will not generate staking rewards until it is reactivated. -To reactivate a validator, use the `reactivate` command: +To reactivate your validator, use the `reactivate` command: ```bash copy namadac reactivate-validator --validator ``` This will reactivate the validator at the end of the current epoch + `pipeline_length`. -## Consensus Key Management - -The consensus key is crucial for validators as it is used to sign blocks and participate in the CometBFT consensus protocol. This key ensures that only authorized validators can propose and vote on blocks, contributing to the network's overall security. - ### Changing the Consensus Key -Validators are able to change their consensus key, allowing for enhanced security and key rotation practices. This process is essential for maintaining the security of the validator's operations and protecting against potential compromise. +A validator's consensus key is used to sign blocks and participate in the CometBFT consensus protocol. +This key ensures that only authorized validators can propose and vote on blocks, contributing to the network's overall security. +It is crucial that all validators keep their consensus keys secret and secure. + +Validators are able to change their consensus key, allowing for enhanced security and key rotation practices. +This process is essential for maintaining the security of the validator's operations and protecting against potential compromise. -To change the consensus key, validators can use the following command: +To change their consensus key, validators can use the following command: ```bash VALIDATOR_ADDRESS="" SIGNING_KEYS="" -namada client change-consensus-key --validator $VALIDATOR_ADDRESS --signing-keys $SIGNING_KEYS +namadac change-consensus-key --validator $VALIDATOR_ADDRESS --signing-keys $SIGNING_KEYS ``` -The new consensus key will be recorded in the `wallet.toml` file and is scheduled to become active 2 blocks before the pipeline offset from the epoch at the moment of activation. This timing ensures a smooth transition. It is essential for validators to plan the key rotation accordingly to ensure continuous participation in block validation without interruption. +The new consensus key will be recorded in the `wallet.toml` file and is scheduled to become active 2 blocks before the pipeline offset from the epoch at the moment of +activation. This timing ensures a smooth transition. + +After the transition period, validators must replace the current `priv_validator_key.json` with the newly generated key. +This step is crucial for activating the new consensus key for block signing. + +It is essential for validators to plan the key rotation accordingly to ensure continuous participation in block validation with minimal interruption. ### Generating a New Consensus Key -After the transition period, validators must replace the current `priv_validator_key.json` with the newly generated key. This step is crucial for activating the new consensus key for block signing. To generate a new consensus key, use the following command: @@ -65,10 +89,35 @@ To generate a new consensus key, use the following command: namadaw convert --alias ``` -This command will create a new consensus key, which validators should securely store and use to replace the existing `priv_validator_key.json` file. It is critical for validators to perform this step correctly. +This command will create a new consensus key, which validators should securely store and use to replace the existing `priv_validator_key.json` file. +It is critical for validators to perform this step correctly. -After updating the consensus key, validators can find out their new validator address with the following command: +After updating the consensus key, validators can find their new validator address with the following command: ```bash namadaw find --alias ``` + +### Withdrawing rewards +When a delegator bonds tokens to an active validator, [staking rewards](./staking.mdx) accrue in the form of the native token. These rewards need to be claimed +before they are credited to the delegator's account. The same holds true for when the validator has self-bonded. Rewards can be withdrawn with the command: + +```bash +namadac claim-rewards --validator +``` + +### Submitting an unjail transaction +See the section on [jailing](./jailing.mdx) for further info. + +### Voting on governance +An important function of validators is active participation in governance. It is particularly important for validators to vote on governance proposals because +they vote on behalf of not only their self-bonded stake, but any delegated stake which has not submitted a vote of their own. + +In other words, a validator's vote determines the 'default' vote for all its delegators. A delegator wishing to vote differently can override this by submitting a +vote transaction of their own, which they may do at any time before the end of the voting period (including after the validator has voted). + + +Validators have a shortened voting window -- they can only cast votes during the first two-thirds of a proposal's voting period. + +This is to allow delegators time to check how their delegatee validator has voted, in case they wish to vote differently. + \ No newline at end of file diff --git a/packages/docs/pages/operators/validators/validator-setup.mdx b/packages/docs/pages/operators/validators/validator-setup.mdx index 37a801b4..7f6b2f72 100644 --- a/packages/docs/pages/operators/validators/validator-setup.mdx +++ b/packages/docs/pages/operators/validators/validator-setup.mdx @@ -1,15 +1,23 @@ import { Callout } from 'nextra-theme-docs' +import { Steps } from 'nextra-theme-docs' -# Setting up a validator account +# Setting up a Validator Node -## Genesis validators - -A genesis validator is one which is a validator right from the first block of the chain, i.e., at genesis. The details of genesis validators are hardcoded into the genesis file that is distributed to all users who want to interact with a chain. +This section details how to set up and run a validator node. It is divided into two sections -- pre-genesis validators and post-genesis validators. ### Prerequisites -- a machine that meets the [requirements](../hardware.mdx) for running a validator node -- an associated public IPv4 address with ports 26656 reachable from anywhere for P2P connections +- A machine that meets the [requirements](../hardware.mdx) for running a validator node +- An associated public static IPv4 address with ports 26656 reachable from anywhere for P2P connections +- You have [installed](../../introduction/install.mdx) Namada and its dependencies + + +## Pre-genesis validators + +A pre-genesis validator is one which begins validating right from the first block of the chain, i.e., at genesis. +The details of genesis validators are hardcoded into the genesis files that is distributed to all users who want to interact with a chain. Becoming a pre-genesis +validator involves generating and signing a genesis transaction for inclusion in the genesis files; upon network launch, the validator can participate in +consensus assuming they possess the expected consensus keys. ### Method @@ -18,106 +26,61 @@ The method for setting up a genesis validator is described under the [pre-genesi ## Post-genesis validators -Post-genesis validators are validators that become initialized after the genesis block. This is the most common way of becoming a validator, and is the method described in this section. +Post-genesis validators are validators that become initialized after the genesis block; this is the most common way of becoming a validator. - -Note the use of the placeholder `aliace` for the alias parameter. This is a completely configurable parameter, and should just refer to the alias of the key/address generated. +### Method + +### Sync a full node +Before initializing your validator account, you must first [set up a full node](../ledger/running-a-full-node.mdx) and sync it with +the head of the chain. + +### Initialize a new validator account +A validator account can be initialized from an [established account](../../users/transparent-accounts/established-accounts.mdx) by submitting an on-chain transaction. +`namadac init-validator` will create a new established account and convert it to a validator account in a single command. + +You can also use the command `namadac become-validator` to convert an existing established account into a validator account, instead of creating a new one. -### Initialising a new validator account - -The user must first generate a key pair for their validator account. - -```bash copy -KEY_ALIAS="aliace" -namada wallet gen --alias $KEY_ALIAS -``` - -Now choose a name for your validator: - -```bash copy -export VALIDATOR_ALIAS="" -export EMAIL="" -``` - -A validator account requires additional keys compared to a user account, so start by initialising a validator account: - -```bash copy -namada client init-validator \ - --alias $VALIDATOR_ALIAS \ - --account-keys $KEY_ALIAS \ - --signing-keys $KEY_ALIAS \ - --commission-rate \ - --max-commission-rate-change \ - --email $EMAIL -``` - -It is also possible to convert an established account to a validator account: - +The required arguments to initialize a validator are: ```bash copy -namada client become-validator \ - --address $ESTABLISHED_ACCOUNT_ADDRESS \ - --signing-keys $KEY_ALIAS \ - --commission-rate \ - --max-commission-rate-change \ - --email $EMAIL +namadac init-validator \ + --commission-rate 0.05 \ + --max-commission-rate-change 0.01 \ + --email \ + --alias ``` +__Note:__ +- `commission-rate` is the percentage of staking rewards kept by the validator for all tokens bonded to it. A validator can change its commission rate +by no more than `max-commission-rate-change` per epoch. The `max-commission-rate-change` parameter cannot be changed after validator initialization. +Typical values are `0.05` (5%) and `0.01` (1%) respectively but validator are free to choose otherwise. +- `email` should be set to a dedicated infra/security email account that you monitor regularly. It may be used to notify validators of urgent security issues, patches +or chain upgrades. +- `alias` is used to reference your account by name in your wallet; it does not appear on-chain. - -A validator’s commission rate is the percentage of the rewards that the validator keeps from its delegators. A validator can change its commission rate with a transaction. The `max-commission-rate-change` is the maximum allowable change in a validator’s commission rate from one epoch to the next. This parameter is set uniquely for a given validator upon their creation and cannot be changed once the validator is initialized. - - -The validator account will now have the same alias as the established account. - -When initialising a validator account, it is also mandatory to specify both the `commission-rate` charged by the validator for delegation rewards (in decimal format) as well as the `maximum-commission-rate-change` per epoch in the `commission-rate`. Both are expressed as a decimal between 0 and 1. The standard for mainnet will be set by social consensus, but for testnets, the standard has been `0.01` and `0.05`, respectively. - -This command will generate the keys required for running a validator: - -- Consensus key, which is used in [signing blocks in CometBFT](https://docs.cometbft.com/v0.37/core/validators#validator-keys). -- Validator account key for signing transactions on the validator account, such as token self-bonding, unbonding and withdrawal, validator keys, validity predicate, state and metadata updates. +You can optionally provide any of the following additional information to identify your validator on-chain (frequently displayed in block explorers): +- `name`: An on-chain display name (similar to 'moniker' in Cosmos SDK chains) +- `avatar`: A url to your validator logo +- `discord-handle`: Your Discord handle +- `website`: A url to your validator website +- `description`: A 1-2 sentence description, tagline or slogan -Then, it submits a transaction to the ledger that generates the new validator account with established address, which can be used to receive new delegations. +### Restart your node +You must restart your node after initializing your validator; your node will be unable to sign any future blocks until you do so. -The keys and the alias of the address will be saved in your wallet. +### Bond stake +A validator will only participate in consensus if the amount of tokens bonded meets both requirements: +- Greater than the chain's `validator_stake_threshold` parameter, and +- Enough to rank it among the top `X` active validators as defined by the `max_validator_slots` parameter. For example, if `max_validator_slots = 100`, then you must rank within the top 100 active validators by stake to participate in consensus. -### Start validating +Validators can bond tokens to themselves (self-bond) and solicit bonds from other parties (delegation); see the section on [staking](./staking.mdx). +Note that the balance of NAM tokens that is in your validator account does not count towards your validator's stake and voting power. - -**IMPORTANT** +### Await the `pipeline_length` +The chain's `pipeline_length` parameter defines the number of epochs that must pass before actions such as bonding, unbonding, or unjailing take effect. Therefore, +after bonding sufficient stake to place in the active consensus set, you must wait an additional `pipeline_length` number of epochs before your validator is included in the consensus set. -The local ledger node will also be setup to run this validator, you just have to shut it down with e.g. `Ctrl + C`, then start it again with the same command as before. - - -```shell copy -namadan ledger run -# or for more verbose output: -# NAMADA_LOG=info CMT_LOG_LEVEL=p2p:none,pex:error NAMADA_CMT_STDOUT=true namadan ledger run -``` -The ledger will then use the validator consensus key to sign blocks, should your validator account acquire enough voting power to be included in the active validator set. The size of the active validator set is limited to `128` (the limit is set by the PoS `max_validator_slots` parameter). + -Note that the balance of NAM tokens that is in your validator account does not count towards your validator's stake and voting power: - -```shell copy -namada client balance --owner my-validator --token NAM -``` +## Validator account keys -That is, the balance of your account's address is a regular liquid balance that you can transfer using your validator account key, depending on the rules of the validator account's validity predicate. The default validity predicate allows you to transfer it with a signed transaction and/or stake it in the PoS system. Therefore, in order to increase the voting power of your validator, you need to accrue [some stake](./staking.mdx). - -The final thing that needs to be done is to bond some stake to the validator account. This can be done using the `bond` command: - -```shell copy -namadac bond --amount --validator -``` - -### Querying a validator's tendermint address - -If the validator account has been set up correctly and has bonded stake, it will be possible to query it using the `find-validator` command: - -```shell copy -namada client find-validator --validator -``` - - -It is important to note that the validator **address** is required, not the alias. The address can be found using the wallet command `namadaw list --addr | grep "your-validator-alias".` - From ccb96e2550182e474fb6e54e2dd2b06e761f8897 Mon Sep 17 00:00:00 2001 From: brentstone Date: Wed, 12 Jun 2024 08:08:15 -0700 Subject: [PATCH 83/94] fix broken pos links --- packages/docs/pages/operators/validators.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/docs/pages/operators/validators.mdx b/packages/docs/pages/operators/validators.mdx index 45d59562..fbd9b492 100644 --- a/packages/docs/pages/operators/validators.mdx +++ b/packages/docs/pages/operators/validators.mdx @@ -6,7 +6,7 @@ Validating on Namada is permissionless; the only requirement is that a validator consensus set. Active validators not meeting a liveness threshold (by signing a specified percentage of recent blocks) are subject to [jailing](./validators/jailing.mdx) for -inactivity. Validators who double-sign are subject to [cubic slashing](./validators/cubic-pos.mdx). +inactivity. Validators who double-sign are subject to [cubic slashing](https://specs.namada.net/modules/proof-of-stake/cubic-slashing). ### Pre-genesis vs Post-genesis validators The procedure for initializing a validator differs on whether it's done before or after the genesis block of the network. @@ -45,4 +45,4 @@ The validator docs describe the process and actions available to validators on t - [Staking](./validators/staking.mdx) - [Validator actions](./validators/validator-actions.mdx) - [Jailing](./validators/jailing.mdx) -- [Cubic proof of stake](./validators/cubic-pos.mdx) \ No newline at end of file +- [Cubic proof of stake](./validators/proof-of-stake.mdx) \ No newline at end of file From 35d87ac7828d26d3ecc83595d4889ff6977b505b Mon Sep 17 00:00:00 2001 From: brentstone Date: Wed, 29 May 2024 17:14:00 -0700 Subject: [PATCH 84/94] clean up command examples --- packages/docs/pages/introduction/installing-cometbft.mdx | 6 +++--- packages/docs/pages/introduction/quick-start.mdx | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/packages/docs/pages/introduction/installing-cometbft.mdx b/packages/docs/pages/introduction/installing-cometbft.mdx index 0ec71db2..d26eaf30 100644 --- a/packages/docs/pages/introduction/installing-cometbft.mdx +++ b/packages/docs/pages/introduction/installing-cometbft.mdx @@ -13,12 +13,12 @@ You can download the precompiled CometBFT binaries from their [official GitHub r If you have `go` installed and downloaded, you may want to add the CometBFT binary to your `$GOPATH/bin` directory. This can be done by running the following command in the root directory of the repository ```bash copy -cp $GOPATH/bin/ +cp /path/to/cometbft/binary $GOPATH/bin/ ``` Otherwise, we recommend you simply copy it to your `/usr/local/bin` which may require `sudo` permissions. -`sudo cp /usr/local/bin/` +`sudo cp /path/to/cometbft/binary /usr/local/bin/` In order to check that the installation was successful, you can run the following command @@ -30,4 +30,4 @@ Which should output something like: ```bash copy 0.37.2 -``` \ No newline at end of file +``` diff --git a/packages/docs/pages/introduction/quick-start.mdx b/packages/docs/pages/introduction/quick-start.mdx index 0578941b..34433620 100644 --- a/packages/docs/pages/introduction/quick-start.mdx +++ b/packages/docs/pages/introduction/quick-start.mdx @@ -56,7 +56,7 @@ This can take several hours depending on the chain height and your system specs. Create a new [implicit](../users/transparent-accounts.mdx) account in order to receive tokens: ```shell copy -namadaw gen --alias +namadaw gen --alias $YOUR_ALIAS ``` This will generate a new account and store it in the default keychain. You can view the account address with: From c00d9937776c4e43f8116169128ddd0e24b6944a Mon Sep 17 00:00:00 2001 From: brentstone Date: Wed, 29 May 2024 18:10:25 -0700 Subject: [PATCH 85/94] random things --- packages/docs/pages/introduction/public-rpc.mdx | 2 +- packages/docs/pages/introduction/quick-start.mdx | 4 ++-- .../pages/operators/networks/genesis-flow/participants.mdx | 4 ++-- packages/docs/pages/users/governance/on-chain-governance.mdx | 2 +- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/packages/docs/pages/introduction/public-rpc.mdx b/packages/docs/pages/introduction/public-rpc.mdx index f586c6f2..fcf44a74 100644 --- a/packages/docs/pages/introduction/public-rpc.mdx +++ b/packages/docs/pages/introduction/public-rpc.mdx @@ -19,7 +19,7 @@ with the network by using the `--node` flag and providing the address of a publi For example, to query the balance of an account using a public RPC, you can run: ```bash copy -namadac balance --owner --token nam --node https://some-node.xyz:443 +namadac balance --owner $TNAM_ADDRESS --token nam --node https://some-node.xyz:443 ``` In fact, this is not fundamentally different from normal usage of `namadac` -- except that normally an rpc address of `localhost:26657` (corresponding to your own local full node) is implied. \ No newline at end of file diff --git a/packages/docs/pages/introduction/quick-start.mdx b/packages/docs/pages/introduction/quick-start.mdx index 34433620..a2dee5a5 100644 --- a/packages/docs/pages/introduction/quick-start.mdx +++ b/packages/docs/pages/introduction/quick-start.mdx @@ -23,7 +23,7 @@ You can join a [testnet](../networks/testnets.mdx), [localnet](../operators/netw You will need to know the chain-id of the network you wish to join. You can then join as a full (non-validator) node by running: ```shell copy -namadac utils join-network --chain-id --add-persistent-peers +namadac utils join-network --chain-id $CHAIN_ID --add-persistent-peers ``` The newly initialized chain data will be found in your [base directory](../operators/ledger/base-directory.mdx). @@ -66,7 +66,7 @@ namadaw list --addr # Sample output: Known transparent addresses: ... - "": Implicit: tnam1qzegva94xdnvtahqqetys9zzua6sdlm8sve05r9u + "": Implicit: tnam1qzegva94xdnvtahqqetys9zzua6sdlm8sve05r9u ``` {/* #TODO: ADD some output */} diff --git a/packages/docs/pages/operators/networks/genesis-flow/participants.mdx b/packages/docs/pages/operators/networks/genesis-flow/participants.mdx index baf5501a..2530a751 100644 --- a/packages/docs/pages/operators/networks/genesis-flow/participants.mdx +++ b/packages/docs/pages/operators/networks/genesis-flow/participants.mdx @@ -38,12 +38,12 @@ It is the public keys that the pre-genesis network participants must submit to t ```toml # Example wallet.toml [public_keys] -bengt = "ED25519_PK_PREFIXtpknam1qq2vscpcvhdwht9tldj9ntxnknandhnerhzd6d42xqzukw2kpcfpudh3dl2" +alice = "ED25519_PK_PREFIXtpknam1qq2vscpcvhdwht9tldj9ntxnknandhnerhzd6d42xqzukw2kpcfpudh3dl2" ... [addresses] -bengt = "tnam1qq97eqvv4lam8ds00j9em2s2f0r8e7r60qw9fdfq" +alice = "tnam1qq97eqvv4lam8ds00j9em2s2f0r8e7r60qw9fdfq" ``` It is then the right hand side of each of these fields that is submitted to the network coordinator, i.e `ED25519_PK_PREFIXtpknam1qq2vscpcvhdwht9tldj9ntxnknandhnerhzd6d42xqzukw2kpcfpudh3dl2` and `tnam1qq97eqvv4lam8ds00j9em2s2f0r8e7r60qw9fdfq` in the example above. diff --git a/packages/docs/pages/users/governance/on-chain-governance.mdx b/packages/docs/pages/users/governance/on-chain-governance.mdx index 1cd6a283..dfcb1104 100644 --- a/packages/docs/pages/users/governance/on-chain-governance.mdx +++ b/packages/docs/pages/users/governance/on-chain-governance.mdx @@ -47,7 +47,7 @@ A correct Steward proposal example is shown below: "id": 1, "content": { "title": "One Small Step for Namada, One Giant Leap for Memekind", - "authors": "bengt@heliax.dev", + "authors": "alice@heliax.dev", "discussions-to": "forum.namada.net/t/namada-proposal/1", "created": "2069-04-20T00:04:44Z", "license": "MIT", From 460b48291cabbd8624ba16335e91f2b8aa44c401 Mon Sep 17 00:00:00 2001 From: brentstone Date: Wed, 12 Jun 2024 09:54:03 -0700 Subject: [PATCH 86/94] more reformatting command args --- .../pages/operators/validators/jailing.mdx | 8 +++---- .../pages/operators/validators/staking.mdx | 4 ++-- .../validators/validator-actions.mdx | 22 ++++++++--------- .../operators/validators/validator-setup.mdx | 4 ++-- packages/docs/pages/users/delegators.mdx | 24 +++++++++---------- .../users/governance/on-chain-governance.mdx | 2 +- .../docs/pages/users/ibc/transparent-ibc.mdx | 10 ++++---- .../users/public-goods-stewards/electing.mdx | 8 +++---- packages/docs/pages/users/query.mdx | 10 ++++---- 9 files changed, 46 insertions(+), 46 deletions(-) diff --git a/packages/docs/pages/operators/validators/jailing.mdx b/packages/docs/pages/operators/validators/jailing.mdx index d49f0745..fbe9e9d8 100644 --- a/packages/docs/pages/operators/validators/jailing.mdx +++ b/packages/docs/pages/operators/validators/jailing.mdx @@ -11,7 +11,7 @@ When the protocol determines that a validator will be jailed, the jailing and va You can check if a validator is jailed by querying its state with the following command: ```bash copy -namadac validator-state --validator +namadac validator-state --validator $VALIDATOR_ADDRESS ``` ## Unjailing a validator @@ -19,14 +19,14 @@ namadac validator-state --validator Once jailed, validators remain jailed indefinitely. They can only be unjailed by an `unjail-validator` transaction using the validator's signing keys. This can be done with the following command: ```bash copy -namadac unjail-validator --validator +namadac unjail-validator --validator $VALIDATOR_ADDRESS ``` Because the validator alias sometimes clashes with the alias for the implicit account and or established account in the wallet, it is recommended to use the validator address instead of the alias. In order to find the validator address, you can use the following command: ```bash copy -namadaw list --addr | grep +namadaw list --addr | grep $VALIDATOR_ADDRESS ``` then make sure it is the corresponding `tnam` address. @@ -48,7 +48,7 @@ The validator will also be considered to be *frozen* until it no longer has any A validator's slash history, with previously processed slashes and enqueued slashes for future processing, can be queried with the following command: ```bash copy -namadac slashes --validator +namadac slashes --validator $VALIDATOR_ADDRESS ``` Additionally, all slashes in the network can be queried without the `--validator` flag. diff --git a/packages/docs/pages/operators/validators/staking.mdx b/packages/docs/pages/operators/validators/staking.mdx index 7b38857e..4bc3ae9c 100644 --- a/packages/docs/pages/operators/validators/staking.mdx +++ b/packages/docs/pages/operators/validators/staking.mdx @@ -40,7 +40,7 @@ The result of this query will inform the epoch from which your bonds will be act Because the PoS system is just an account, you can query its balance, which is the sum of all currently bonded tokens as well as the unbonded tokens that have not yet been withdrawn: ```shell copy -namada client balance --owner PoS +namada client balance --owner pos ``` ## Self-bonding @@ -140,5 +140,5 @@ These rewards will immediately be credited to the validtor's account. Additionally, you can query the pending reward tokens without claiming by running: ```bash copy -namadac rewards --validator +namadac rewards --validator $VALIDATOR_ADDRESS ``` diff --git a/packages/docs/pages/operators/validators/validator-actions.mdx b/packages/docs/pages/operators/validators/validator-actions.mdx index f5036b44..8f8cbb0d 100644 --- a/packages/docs/pages/operators/validators/validator-actions.mdx +++ b/packages/docs/pages/operators/validators/validator-actions.mdx @@ -28,12 +28,12 @@ A validator can update their metadata at any time with the `change-metadata` com ```bash copy namadac change-metadata \ - --validator \ - --description \ - --email \ - --discord-handle \ - --website \ - --avatar + --validator $VALIDATOR_ADDRESS \ + --description $DESCRIPTION \ + --email $EMAIL \ + --discord-handle $DISCORD_HANDLE \ + --website $WEBSITE \ + --avatar $AVATAR ``` Apart from `--validator`, not all of the fields are required (but at least one of them is). @@ -42,7 +42,7 @@ Apart from `--validator`, not all of the fields are required (but at least one o You can deactivate your validator with the `deactivate` command: ```bash copy -namadac deactivate-validator --validator +namadac deactivate-validator --validator $VALIDATOR_ADDRESS ``` Once deactivated, the validator will no longer participate in the consensus protocol. This will take effect at the end of the current epoch + `pipeline_length`. All bonds and delegations associated with the validator remain intact. @@ -51,7 +51,7 @@ Delegators can still delegate to the validator, but as the validator is inactive To reactivate your validator, use the `reactivate` command: ```bash copy -namadac reactivate-validator --validator +namadac reactivate-validator --validator $VALIDATOR_ADDRESS ``` This will reactivate the validator at the end of the current epoch + `pipeline_length`. @@ -86,7 +86,7 @@ It is essential for validators to plan the key rotation accordingly to ensure co To generate a new consensus key, use the following command: ```bash -namadaw convert --alias +namadaw convert --alias $NEW_CONSENSUS_KEY ``` This command will create a new consensus key, which validators should securely store and use to replace the existing `priv_validator_key.json` file. @@ -95,7 +95,7 @@ It is critical for validators to perform this step correctly. After updating the consensus key, validators can find their new validator address with the following command: ```bash -namadaw find --alias +namadaw find --alias $NEW_CONSENSUS_KEY ``` ### Withdrawing rewards @@ -103,7 +103,7 @@ When a delegator bonds tokens to an active validator, [staking rewards](./stakin before they are credited to the delegator's account. The same holds true for when the validator has self-bonded. Rewards can be withdrawn with the command: ```bash -namadac claim-rewards --validator +namadac claim-rewards --validator $VALIDATOR_ADDRESS ``` ### Submitting an unjail transaction diff --git a/packages/docs/pages/operators/validators/validator-setup.mdx b/packages/docs/pages/operators/validators/validator-setup.mdx index 7f6b2f72..17df7280 100644 --- a/packages/docs/pages/operators/validators/validator-setup.mdx +++ b/packages/docs/pages/operators/validators/validator-setup.mdx @@ -46,8 +46,8 @@ The required arguments to initialize a validator are: namadac init-validator \ --commission-rate 0.05 \ --max-commission-rate-change 0.01 \ - --email \ - --alias + --email $EMAIL \ + --alias $ALIAS ``` __Note:__ - `commission-rate` is the percentage of staking rewards kept by the validator for all tokens bonded to it. A validator can change its commission rate diff --git a/packages/docs/pages/users/delegators.mdx b/packages/docs/pages/users/delegators.mdx index 0202687a..04bf5299 100644 --- a/packages/docs/pages/users/delegators.mdx +++ b/packages/docs/pages/users/delegators.mdx @@ -23,13 +23,13 @@ namadac bonded-stake If you have a specific tenderimnt key of a validator but do not know the address, you can use the following command to find the address: ```bash copy -namadac find-validator --tendermint-key # Similarly you can find the tendermint key from the address by providing the argument --validator instead +namadac find-validator --tendermint-key $VALIDATOR_TENDERMINT_KEY # Similarly you can find the tendermint key from the address by providing the argument --validator instead ``` Before bonding to a validator, it is important to know their commision rate. This is the percentage of the block rewards that the validator will take as a fee for their services. You can find this information by running the following command: ```bash copy -namadac commission-rate --validator +namadac commission-rate --validator $VALIDATOR_ADDRESS ``` Typically, the commission rate is between 0% and 5%. @@ -37,19 +37,19 @@ Typically, the commission rate is between 0% and 5%. Once you've found the address of your favorite validator, you can bond to them with the following command: ```bash copy -namadac bond --source --validator --amount +namadac bond --source $DELEGATOR_ADDRESS --validator $VALIDATOR_ADDRESS --amount $AMOUNT ``` Because the validator alias sometimes clashes with the alias for the implicit account and or established account in the wallet, it is recommended to use the validator address instead of the alias. In order to find the validator address, you can use the following command: ```bash copy -namadaw list --addr | grep +namadaw list --addr | grep $VALIDATOR_ALIAS ``` then make sure it is the corresponding `tnam` address. -The `` is your account address from which you would like to stake NAM tokens. Validators who would like to self-bond do not need to provide the `--source` argument. +The `$DELEGATOR_ADDRESS` is your account address from which you would like to stake NAM tokens. Validators who would like to self-bond do not need to provide the `--source` argument. If you have the alias for an address saved in your wallet, you can also pass it as an argument. @@ -66,7 +66,7 @@ namadac query-protocol-parameters It is possible to query processed delegations through the client ```shell copy -namadac delegations --owner +namadac delegations --owner $DELEGATOR_ADDRESS ``` ## Unbonding @@ -77,7 +77,7 @@ This process is identical to [unbonding tokens from a validator](../operators/va The command to unbond is similar to the bonding command: ```bash copy -namadac unbond --source --validator --amount +namadac unbond --source $DELEGATOR_ADDRESS --validator $VALIDATOR_ADDRESS --amount $AMOUNT ``` After a successful unbond transaction, the unbonded NAM tokens will be available for withdrawal after `pipeline_length + unbonding_length + cubic_slashing_window_length` epochs. Once again, the values of these three parameters can be queried from the chain. @@ -86,7 +86,7 @@ After a successful unbond transaction, the unbonded NAM tokens will be available When the full unbonding period has passed, you can withdraw the unbonded NAM using the following command: ```bash copy -namadac withdraw --source --validator +namadac withdraw --source $DELEGATOR_ADDRESS --validator $VALIDATOR_ADDRESS ``` This transaction will immediately transfer all fully unbonded NAM tokens back to the `delegator-address` account, increasing your transferable balance. @@ -94,7 +94,7 @@ This transaction will immediately transfer all fully unbonded NAM tokens back to You may also query some information regarding how many NAM tokens are available for withdrawal with the following command: ```bash copy -namadac bonds --owner +namadac bonds --owner $DELEGATOR_ADDRESS ``` ## Redelegating @@ -103,7 +103,7 @@ In certain circumstances, you may want to switch the validator that holds your b You can accomplish this with a redelegating the bonded tokens rather than unbonding, withdrawing, and then bonding again. Use the following command: ```bash copy -namadac redelegate --owner --source-validator --destination-validator --amount +namadac redelegate --owner $DELEGATOR_ADDRESS --source-validator $SOURCE_VALIDATOR_ADDRESS --destination-validator $DEST_VALIDATOR_ADDRESS --amount $AMOUNT ``` The `delegator-address` is your address, the `source-validator` is the validator that currently holds your bond, and the `destination-validator` is your desired new validator to hold your bond. @@ -116,7 +116,7 @@ Inflationary rewards for proof-of-stake are computed and minted once per epoch, In order to claim rewards that are owed to you for bonded NAM tokens, run the following command: ```bash copy -namadac claim-rewards --source --validator +namadac claim-rewards --source $DELEGATOR_ADDRESS --validator $VALIDATOR_ADDRESS ``` Successful execution of this transaction will immediately transfer the the reward tokens you are owed to your `delegator-address`, incrementing your transparent balance. @@ -124,7 +124,7 @@ Successful execution of this transaction will immediately transfer the the rewar Additionally, you can query the pending reward tokens without claiming by running: ```bash copy -namadac rewards --source --validator +namadac rewards --source $DELEGATOR_ADDRESS --validator $VALIDATOR_ADDRESS ``` ## Interacting with jailed validators diff --git a/packages/docs/pages/users/governance/on-chain-governance.mdx b/packages/docs/pages/users/governance/on-chain-governance.mdx index dfcb1104..02c7ca66 100644 --- a/packages/docs/pages/users/governance/on-chain-governance.mdx +++ b/packages/docs/pages/users/governance/on-chain-governance.mdx @@ -214,7 +214,7 @@ Only delegators and delegates can vote on proposals. Assuming you fall into one namada client vote-proposal \ --proposal-id 0 \ --vote yay \ - --address + --address $YOUR_ADDRESS ``` diff --git a/packages/docs/pages/users/ibc/transparent-ibc.mdx b/packages/docs/pages/users/ibc/transparent-ibc.mdx index 057ebb77..65ea9ceb 100644 --- a/packages/docs/pages/users/ibc/transparent-ibc.mdx +++ b/packages/docs/pages/users/ibc/transparent-ibc.mdx @@ -18,11 +18,11 @@ software such as [Hermes](https://github.com/heliaxdev/hermes). To make an outgoing IBC transfer from a Namada transparent address: ```bash copy namadac ibc-transfer \ - --source \ - --receiver \ - --token \ - --amount - --channel-id + --source $YOUR_TRANSPARENT_ADDRESS \ + --receiver $ADDRESS_ON_RECEIVING_CHAIN \ + --token $TOKEN_ADDRESS \ + --amount $AMOUNT + --channel-id $CHANNEL_ID ``` Note: - the `receiver` address is the address on the receiving chain -- if you are sending to another Namada chain, this would start with `tnam...`, diff --git a/packages/docs/pages/users/public-goods-stewards/electing.mdx b/packages/docs/pages/users/public-goods-stewards/electing.mdx index 8c8a2b27..07dccf1b 100644 --- a/packages/docs/pages/users/public-goods-stewards/electing.mdx +++ b/packages/docs/pages/users/public-goods-stewards/electing.mdx @@ -63,9 +63,9 @@ The CLI command to submit a proposal is: ```shell copy namadac init-proposal \ --pgf-stewards \ - --data-path + --data-path $PATH_TO/steward_proposal.json ``` -where `` is the path to the `steward_proposal.json` file. +where `$PATH_TO/steward_proposal.json` is the path to the `steward_proposal.json` file. ### Becoming elected @@ -86,7 +86,7 @@ Resigning as a steward can be done at any point. Through the CLI it can be done with the command: ```shell copy -namadac resign-steward --steward my-steward-address +namadac resign-steward --steward $STEWARD_ADDRESS ``` Read more about the other methods of losing stewardship in the [specs](https://specs.namada.net/modules/goverance/public-goods-funding/becoming-a-steward#losing-stewardship-status). @@ -107,5 +107,5 @@ Update steward commissions can be done at any point. Through the CLI it can be done with the command: ```shell copy -namadac update-steward-rewards --steward my-steward-address --data-path +namadac update-steward-rewards --steward $STEWARD_ADDRESS --data-path $PATH_TO/commissions.json ``` \ No newline at end of file diff --git a/packages/docs/pages/users/query.mdx b/packages/docs/pages/users/query.mdx index 799b1f22..205c19b2 100644 --- a/packages/docs/pages/users/query.mdx +++ b/packages/docs/pages/users/query.mdx @@ -7,7 +7,7 @@ This section details several common queries; see all available commands with `na #### query-account ```txt -namadac query-account --owner +namadac query-account --owner $OWNER_ADDRESS ``` Returns the `Threshold` and `Public` key(s) of an established account. @@ -23,7 +23,7 @@ Returns the list of PGF Stewards, their reward distribution, and active PGF stre #### query-proposal ``` -namadac query-proposal --proposal-id +namadac query-proposal --proposal-id $ID ``` Returns info on a given proposal, including its type, author, content, StartEpoch, EndEpoch, GraceEpoch, and Status. @@ -31,7 +31,7 @@ Returns info on a given proposal, including its type, author, content, StartEpoc #### query-proposal-result ``` -namadac query-proposal-result --proposal-id +namadac query-proposal-result --proposal-id $ID ``` Returns the outcome of a given proposal, including whether it's Passed/Rejected, the total number of votes for yay/nay/abstain, and the threshold (fraction) of the total voting power needed to tally. @@ -39,13 +39,13 @@ Returns the outcome of a given proposal, including whether it's Passed/Rejected, #### query-proposal-votes ``` -namadac query-proposal-votes --proposal-id +namadac query-proposal-votes --proposal-id $ID ``` Returns the results of all wallets that have voted `yay` or `nay` on the proposal ``` -namadac query-proposal-votes --proposal-id --voter +namadac query-proposal-votes --proposal-id $ID --voter $VOTER_ADDRESS ``` Returns the result of a specific wallet that has voted on a specific proposal From d1540a8e95655fc1faba8e63b8e43b5d395f7f27 Mon Sep 17 00:00:00 2001 From: iskay Date: Tue, 18 Jun 2024 11:15:52 -0400 Subject: [PATCH 87/94] update docker guide --- .../pages/introduction/install/docker.mdx | 107 ++++++++++++------ 1 file changed, 72 insertions(+), 35 deletions(-) diff --git a/packages/docs/pages/introduction/install/docker.mdx b/packages/docs/pages/introduction/install/docker.mdx index 9c9ba789..7f7a0b71 100644 --- a/packages/docs/pages/introduction/install/docker.mdx +++ b/packages/docs/pages/introduction/install/docker.mdx @@ -1,27 +1,31 @@ +import { Steps } from 'nextra-theme-docs' + # Running Namada with Docker ## Pre-requisites In order to run any Docker images, you must first have Docker installed. You can find installation instructions for your machine [here](https://docs.docker.com/get-docker/). -## Downloading the docker image -The Namada Docker image can be found [here](https://github.com/anoma/namada/pkgs/container/namada). +## Downloading the Docker image +Namada images for various versions can be found in Namada's [container registry](https://github.com/anoma/namada/pkgs/container/namada) on GitHub. -Under the `Tags` tab, you can find the latest version of the Docker image. Click on the link for the correct version of Namada that you are trying to install. For example, if you are trying to install Namada v0.37.0, you would click on the link for `v0.37.0`. +Under the `Tags` tab, you can find the latest version of the Docker image. Click on the link for the correct version of Namada that you are trying to install. +For example, if you are trying to install Namada v0.39.0, you would click on the link for `v0.39.0`. To download the Docker image, run: ```bash copy -docker pull ghcr.io/anoma/namada:namada-v0.37.0 +NAMADA_VERSION=v0.39.0 # or whichever version you wish to download +docker pull ghcr.io/anoma/namada:namada-$NAMADA_VERSION ``` You can list any downloaded Docker image by running `docker images`. The tag will be the first column of the output. -```bash copy +```bash ~$ docker images REPOSITORY TAG IMAGE ID CREATED SIZE -ghcr.io/anoma/namada namada-v0.37.0 b9729acaabab 5 days ago 211MB +ghcr.io/anoma/namada namada-v0.39.0 b9729acaabab 5 days ago 211MB ``` -In this case, the full name of the downloaded image is `ghcr.io/anoma/namada:namada-v0.37.0`. +In this case, the full name of the downloaded image is `ghcr.io/anoma/namada:namada-v0.39.0`. ## Running the docker image @@ -29,62 +33,95 @@ Once you have downloaded the Docker image, it will be useful to export some envi ```bash copy export CHAIN_ID= -export DOCKER_IMAGE=ghcr.io/anoma/namada:namada-v0.37.0 +export DOCKER_IMAGE=ghcr.io/anoma/namada:$NAMADA_VERSION ``` -The following Docker run command will run the ledger node: +You can run commands in a Docker container by the following method: ```bash copy -docker run -P -i -t $DOCKER_IMAGE +docker run -P -it --rm $DOCKER_IMAGE {namada-command} ``` -Where `` is any command you would run after `namada` in the terminal. For example, if you wanted to run `namada client utils join-network --chain-id $CHAIN_ID`, you would run: +Where `{namada command}` is any command you would run after `namada` in the terminal. For example, if you wanted to run `namada client utils join-network --chain-id $CHAIN_ID`, you would run: ```bash copy -docker run -P -i -t $DOCKER_IMAGE client utils join-network --chain-id $CHAIN_ID +docker run -P -it --rm $DOCKER_IMAGE client utils join-network --chain-id $CHAIN_ID ``` -Then in order to run any other ledger commands, one can run: - -```bash copy -docker /bin/bash -c "/bin/bash","-c", "" +### Persisting data with Docker volumes +If you tried to run the above example using the `join-network` command, you would notice that while the command runs successfully, you have no way to make use of the chain data +after the command completes and the container exits (as it only existed inside the now-exited container). You can persist the chain data using a Docker volume, which binds a +directory on your host machine to a directory inside a container's filesystem. The volume syntax is as follows: +```bash +-v {directory-on-host-machine}:{directory-inside-container} +``` +or +```bash +-v {named-volume}:{directory-inside-container} ``` -## Alternative method (building the docker image yourself) +### Example: Joining a network with a full node +There are many possible ways of working with Docker containers and volumes depending on your needs and system setup; here is one example of how it could be done. -Alternatively, you can build the docker image yourself! + +##### Create a directory on your host OS +The directory can be located anywhere you like; we'll use the default `base-dir` location: +```bash copy +mkdir ~/.local/share/namada +``` -Begin by exporting some environment variables: +##### Set directory permissions +The newly created directory will be 'owned' by our current user (on the host OS). Unless we set the appropriate permissions for the directory on the host OS, the Namada +container will not be able to write to it. +When you run a command inside a container using the Namada Docker image, it will be run under a user named `namada` with a user-id `1000`. Knowing this, we can set the +permissions on our directory appropriately (this command may require `sudo`): ```bash copy -export CHAIN_ID= -export BRANCH= +chown -R 1000:1000 ~/.local/share/namada ``` -For example if you wanted to build the docker image for Namada v0.16.0 and chain-id `public-testnet-69.0.b20a1337aa1`, you would run: - +##### `join-network` using a volume +Now we can run the `join-network` command while including the `-v` flag to create a new volume. We will map the `base-dir` inside the container to the directory +`~/.local/share/namada` we created in steps 1 and 2. This will allow us to persist the `base-dir` for future use: ```bash copy -export CHAIN_ID=public-testnet-69.0.b20a1337aa1 -export BRANCH=v0.28.2 #The latest branch of Namada +docker run -P -it --rm -v $HOME/.local/share/namada:/home/namada/.local/share/namada $DOCKER_IMAGE client utils join-network --chain-id $CHAIN_ID ``` -Then you can build the docker image by running: +If we check the directory `~/.local/share/namada` on our host machine, we should see it has been populated with the genesis files for our `$CHAIN_ID`. + +##### Edit `persistent_peers` +Since we've mapped the chain data to a directory on the host filesystem, we can access/edit it directly if needed. Suppose we need to update our `persistent_peers` before starting +the ledger; we can do so by directly editing the file `~/.local/share/namada/$CHAIN_ID/config.toml`. + +_Note:_ The owner of these files is the `namada` user inside the container. Therefore, accessing the files from your host OS in this way may require you to use `sudo` to obtain +necessary read/write permissions. +##### Start the ledger +We can now start a container using our chain-data by once again passing the volume to the `docker run` command: ```bash copy -git clone https://github.com/anoma/namada-sdk-starter.git -cd namada-sdk-starter/docker/namada-with-chain/ -docker build --build-arg BRANCH=$BRANCH --build-arg CHAIN_ID=$CHAIN_ID -t namada_testnet_image . +docker run -P -it --rm -v $HOME/.local/share/namada:/home/namada/.local/share/namada $DOCKER_IMAGE node ledger run ``` + + +## Building the Docker image + +Alternatively, you can build the docker image yourself! -Which will save the image to your local docker images. You can find the tag of the downloaded docker image by running `docker images`. The tag will be the first column of the output. +Begin by exporting some environment variables: -Save this docker image as an environment variable ```bash copy -export DOCKER_IMAGE= +export CHAIN_ID= +export BRANCH= ``` -Then you can run the docker image by running: +Then you can build the docker image by running: ```bash copy -docker run -P -i -t $DOCKER_IMAGE -``` \ No newline at end of file +git clone https://github.com/anoma/namada.git +cd namada +docker build -f docker/namada/Dockerfile --build-arg BRANCH=$BRANCH --build-arg CHAIN_ID=$CHAIN_ID -t namada:$BRANCH . +``` +_Note:_ Don't forget the trailing `.` + +If the value of `$BRANCH` is `v0.39.0`, the above command will build an image named `namada:v0.39.0`. You can replace the image name `namada:$BRANCH` with +any name you like. From 23a52d4816764398535fc1d07d76631c425ad447 Mon Sep 17 00:00:00 2001 From: iskay Date: Wed, 12 Jun 2024 17:17:02 -0400 Subject: [PATCH 88/94] update ibc sections --- packages/docs/pages/operators/ibc.mdx | 263 ++++++++++-------- packages/docs/pages/users/ibc/_meta.json | 4 +- .../docs/pages/users/ibc/shielded-ibc.mdx | 73 +++-- .../docs/pages/users/ibc/transparent-ibc.mdx | 40 ++- 4 files changed, 221 insertions(+), 159 deletions(-) diff --git a/packages/docs/pages/operators/ibc.mdx b/packages/docs/pages/operators/ibc.mdx index a3f8ebdd..f54c6d02 100644 --- a/packages/docs/pages/operators/ibc.mdx +++ b/packages/docs/pages/operators/ibc.mdx @@ -1,39 +1,104 @@ import { Callout } from 'nextra-theme-docs' import Expandable from '../../components/Expandable' +import { Steps } from 'nextra-theme-docs' # Relaying on Namada -This document describes how to operate a relayer for the Inter-Blockchain Communication (IBC) protocol with Namada. This documentation covers being able to create connections through IBC as well as setting up local chains of Namada for testing purposes. +This section of the documentation describes how to operate a relayer on Namada, how to open IBC connections with other IBC compatible chains and how to +test your relayer setup by making a connection between two mock local chains. -This document covers essential steps for using IBC with Namada: +## Introduction +Relayers are a crucial piece of infrastructure that allow IBC compatible chains to pass messages to one another. +A relayer is responsible for posting IBC packets to the destination chain, as well as performing other IBC functions +such as creating channels, updating the light client states and checking for misbehavior. -1. [Configure Hermes](#configure-hermes) -2. [Install Hermes](#install-hermes) +Operating a relayer is permissionless. If at least one relayer is not running on a given channel between two chains, +they will not be able to pass messages to each other on that channel. IBC transfers that are attempted but not picked +up by a relayer will timeout and the tokens will be refunded to the sender. + +To operate a relayer, you will need: +- A dedicated server +- [Hermes](#install-hermes); the relayer software. Heliax maintains a fork of Hermes compatible with Namada. +- Full nodes on both chains; a relayer needs to access several weeks worth of chain history and to frequently post +transactions to both chains. For testing, a public RPC node may suffice, but for production it is highly recommended +for reliability that relayer operators also operate both full nodes themselves. +- Gas funds for each chain; since relayers will need to regularly post transactions to both chains, they will need a +wallet on each with enough funds to cover gas costs (monitoring and topping up as necessary). + + +This document covers the essentials for installing, configuring and running a relayer on Namada: + +1. [Installing Hermes](#install-hermes) +2. [Configuring Hermes](#configure-hermes) 3. [Setting up the relayer](#setting-up-the-relayer) -4. [Start the relayer](#start-the-relayer) -5. [Set up local Namada chains](#set-up-local-namada-chains-using-the-hermes-script) +4. [Creating an IBC channel](#creating-an-ibc-channel) +5. [Running the relayer](#start-the-relayer) + +And for setting up a testing environment by running two local Namada chains, see the section +[Testing with local Namada chains](#set-up-local-namada-chains-using-the-hermes-script) + + +### Installing Hermes +Heliax maintains a fork of the Hermes relayer software. You can download a prebuilt binary or build it from source. + +#### From binaries +One can download the latest binary release from our [releases page](https://github.com/heliaxdev/hermes/releases) by choosing the appropriate architecture. + +E.g. +```bash copy +export TAG="v1.8.2-namada-beta11" # or the appropriate release for your version of namada +export ARCH="x86_64-unknown-linux-gnu" # or "aarch64-apple-darwin" +curl -Lo /tmp/hermes.tar.gz https://github.com/heliaxdev/hermes/releases/download/${TAG}/hermes-${TAG}-${ARCH}.tar.gz +tar -xvzf /tmp/hermes.tar.gz -C /usr/local/bin +``` + + +For some systems, `/usr/local/bin` is a protected directory. In this case, you may need to run the above command with `sudo`. +I.e +```bash copy +sudo tar -xvzf /tmp/hermes.tar.gz -C /usr/local/bin +``` +This is also true for the command `cp ./target/release/hermes /usr/local/bin/` below (see the comment). + -The below is intended for those that wish to relay IBC message transfers between two Namada chains. There is of course the capability to do this between any two IBC compatible chains (such as a Cosmos chain). -In this case, it is necessary to have a node running on both the destination and the source chain in order to make any package transfers. -Below, we discuss first how to enable this connection between two pre-existing chains by Hermes, and second, setting up two Namada local chains for this purpose. +#### From source +```bash copy +export TAG="v1.8.2-namada-beta11" # or the appropriate release for your version of namada + +git clone https://github.com/heliaxdev/hermes.git +git checkout $TAG +cd hermes +cargo build --release --bin hermes +export HERMES=$(pwd) # if needed +``` +Check the binary: +```bash copy +./target/release/hermes --version +``` + +It is recommended to now add hermes to `$PATH` such that it is callable without any pre-fixes. +For ubuntu users, this can be achieved by +```bash copy +sudo cp ./target/release/hermes /usr/local/bin/ +``` + -## Configure Hermes -Hermes is an IBC relayer to relay IBC packets between chains. -Namada uses a [fork of Hermes supporting Namada chains](https://github.com/heliaxdev/hermes/tree/v1.7.4-namada-beta7). +### Configuring Hermes -### Make Hermes config file -One essential piece of the puzzle is to create a `config.toml` file that describes what connections will be set up that the relayer will be responsible for. +#### Make Hermes config file +Hermes' `config.toml` file defines which chains and channels the relayer will be responsible for. First, create that file: ```bash copy -export HERMES_CONFIG="/config.toml" +export HERMES_CONFIG="$HOME/.hermes/config.toml" touch $HERMES_CONFIG ``` -If you don't specify the file path, `~/.hermes/config.toml` is read as default. +When running Hermes commands, if you don't specify the config file path, `~/.hermes/config.toml` is read as default. -You can find an example of the config file below. Essentially, you change only the chain IDs, the RPC addresses, and the key names in the config file for Namada. If you don't have nodes, please set up nodes manually or through our [scripts](#set-up-local-namada-chains-using-the-hermes-script). +__You can find an example of the config file below__. Essentially, you change only the chain IDs, the RPC addresses, and the key names in the config file for Namada. +If you don't have nodes, please set up nodes manually or through our [scripts](#set-up-local-namada-chains-using-the-hermes-script).
Example: config.toml @@ -139,7 +204,8 @@ These are the pieces of this puzzle you want to keep your πŸ‘€ on: - `chains.rpc_address` specifies the port that the channel is communicating through, and will be the argument for the `ledger_address` of Namada when interacting with the ledger (will become clearer later) - Make sure to change the IP address to the IP address of your local machine that is running this node! - `chains.grpc_addr` currently is not used in Namada but needs to be configured for other Cosmos chains - - `chains.key_name` specifies the key of the signer who signs a transaction from the relayer. The key should be generated before starting the relayer. + - `chains.key_name` specifies the key of the signer who signs a transaction from the relayer. The key should be generated before starting the relayer and + will need to be kept topped up with gas funds. - `chains.event_source` specifies the URL of the chain's websocket. This must be the same as the `rpc_address` for Hermes to work properly. - `chains.gas_price.denom` specifies the token that the relayer pays for IBC transactions. `chains.gas_price.price` isn't used for now in Namada. - `trusting_period` specifies the maximum period before which the client can not expire. This should be not more than unbonding time in the particular chain. @@ -147,76 +213,33 @@ These are the pieces of this puzzle you want to keep your πŸ‘€ on: You can see more details of configuration in [the official document](https://hermes.informal.systems/documentation/configuration). -### Export environment variables -The relaying user will need to save certain environment variables. These are: +#### Export environment variables +You may find it convenient to save certain environment variables. These are: ```bash copy export CHAIN_A_ID="" export CHAIN_B_ID="" export HERMES_CONFIG="" ``` -## Install Hermes -Before conducting any IBC operations, one must download Heliax's fork Hermes binary or build it from source. - -### From binaries -One can download the latest binary release from our [releases page](https://github.com/heliaxdev/hermes/releases) by choosing the appropriate architecture. - -E.g. -```bash copy -export TAG="v1.7.4-namada-beta7" -export ARCH="x86_64-unknown-linux-gnu" # or "aarch64-apple-darwin" -curl -Lo /tmp/hermes.tar.gz https://github.com/heliaxdev/hermes/releases/download/${TAG}/hermes-${TAG}-${ARCH}.tar.gz -tar -xvzf /tmp/hermes.tar.gz -C /usr/local/bin -``` - - -For some systems, `/usr/local/bin` is a protected directory. In this case, you may need to run the above command with `sudo`. -I.e -```bash copy -sudo tar -xvzf /tmp/hermes.tar.gz -C /usr/local/bin -``` -This is also true for the command `cp ./target/release/hermes /usr/local/bin/` below (see the comment). - - -### From source -```bash copy -export TAG="v1.7.4-namada-beta7" - -git clone https://github.com/heliaxdev/hermes.git -git checkout $TAG -cd hermes -cargo build --release --bin hermes -export HERMES=$(pwd) # if needed -``` -Check the binary: -```bash copy -./target/release/hermes --version -``` - - -It is recommended to now add hermes to `$PATH` such that it is callable without any pre-fixes. -For ubuntu users, this can be achieved by -```bash copy -sudo cp ./target/release/hermes /usr/local/bin/ -``` - - -## Setting up the relayer +### Setting up the relayer -### Create the relayer account +#### Create the relayer account On each chain, there must be a `relayer` account. The alias should be the same as `chains.key_name` in the config. On a Namada chain, this can be done by running ```bash copy namadaw gen --alias relayer ``` -This will generate a key for the relayer account. The key will be stored in the `wallet.toml` that is found in the [base directory](./ledger/base-directory.mdx) of the node, inside the `chain-id` folder. For example, if the `chain-id` is `shielded-expedition.88f17d1d14`, the `wallet.toml` will be found in `$HOME/.local/share/namada/shielded-expedition.88f17d1d14/wallet.toml` (on a ubuntu machine where `base-dir` has not been set up properly). +This will generate a key for the relayer account. The key will be stored in the `wallet.toml` that is found in the [base directory](./ledger/base-directory.mdx) of the node, inside the `chain-id` folder. For example, if the `chain-id` is `shielded-expedition.88f17d1d14`, the `wallet.toml` will be found in `$HOME/.local/share/namada/shielded-expedition.88f17d1d14/wallet.toml` (on a Ubuntu machine where `base-dir` has not been changed from default). The relayer account should have some balance to pay the fee of transactions. Before creating an IBC channel or relaying an IBC packet, you need to transfer the fee token to the relayer account. -### Add the relayer key to Hermes -To sign each transaction, the relayer's key should be added to Hermes with `keys add` command in advance. It requires the `wallet.toml` which should have the key of `chains.key_name`. Once the key has been added, Hermes doesn't need the wallet anymore. +#### Add the relayer key to Hermes +To sign each transaction, the relayer's key should be added to Hermes with `keys add` command in advance. +It requires the `wallet.toml` which should have the key of `chains.key_name`. Once the key has been added, Hermes doesn't +need the wallet anymore. (Rather than providing the `wallet.toml`, you can instead provide a text file which contains the 24 word mnemonic for your key.) ```bash copy hermes --config $HERMES_CONFIG keys add --chain $CHAIN_ID --key-file $WALLET_PATH +# or hermes --config $HERMES_CONFIG keys add --chain $CHAIN_ID --mnemonic-file $SEED_PATH ``` @@ -226,10 +249,8 @@ Hermes will store the key in `~/.hermes/keys/${CHAIN_ID}` as default. You can sp If you want to use an encrypted key with a password, you have to set an environment variable `NAMADA_WALLET_PASSWORD_FILE` for the password file or `NAMADA_WALLET_PASSWORD` to avoid entering the password for each transaction submission. -It is now possible to set up the client. - -# Verify configuration files -After editing `config.toml` and adding wallet keys, it’s time to test the configurations and ensure the system is healthy. Run the following: +#### Verify configuration files +After editing `config.toml` and adding wallet keys, it's time to test the configurations and ensure the system is healthy. Run the following: ```bash copy hermes health-check @@ -241,8 +262,21 @@ SUCCESS performed health check for all chains in the config SUCCESS "configuration is valid" ``` -### Create IBC channel -The "create channel" command (below) creates not only the IBC channel but also the necessary IBC client connection. +### Creating an IBC channel +All IBC transfers between two chains take place along a given IBC channel associated with a given IBC connection. + +Channels must be maintained after creation by regularly submitting headers to keep the client state up to date with +the counterparty chain. A client that is allowed to fall out of date may expire, and further IBC transfers along the +channel will not be possible until the client is revived through governance. Operators should not create new channels +on public networks unneccessarily; instead, they should relay on existing channels if possible. + + +The same asset transferred through different channels will not be fungible on the destination chain. Therefore, to avoid +confusion and liquidity fragmentation, it is good etiquette to check with a chain's community before creating any +new channels and to use existing channels whenever possible. + + +If no existing channel can be used, the "create channel" command (below) creates not only the IBC channel but also the necessary IBC client connection. ```bash copy hermes --config $HERMES_CONFIG \ @@ -258,9 +292,15 @@ hermes --config $HERMES_CONFIG \ Note that the above `CHAIN_IDs` will depend on your own setup, so do check this for yourself! -When the creation has been completed, you can see the channel IDs. For example, the following text shows that a channel with ID `955` has been created on Chain A `shielded-expedition.88f17d1d14`, and a channel with ID `460` has been created on Chain B `axelar-testnet-lisbon-3`. You will need the channel IDs for a transfer over IBC. It means that you have to specify `channel-955` as a channel ID (The prefix `channel-` is always required) for a transfer from Chain A to Chain B. Also, you have to specify `channel-460` as a channel ID for a transfer from Chain B to Chain A. +When the creation has been completed, you can see the channel IDs. For example, the output text below shows that a channel with ID `955` has been created on Chain A `shielded-expedition.88f17d1d14`, +and a channel with ID `460` has been created on Chain B `axelar-testnet-lisbon-3`. -Remember the ClientId for each of the chains, we will need them on the next step: `07-tendermint-2996` for `shielded-expedition.88f17d1d14` and `07-tendermint-884` for `axelar-testnet-lisbon-3` +Note the channel id's, as you will need to specify the channel IDs when making a transfer over IBC. You specify `channel-955` as a channel ID +for a transfer from Chain A to Chain B. Also, you specify +`channel-460` as a channel ID for a transfer from Chain B to Chain A. (The prefix `channel-` is always required) + +Also note the ClientId for each of the chains; we will need them on the next step: +`07-tendermint-2996` for `shielded-expedition.88f17d1d14` and `07-tendermint-884` for `axelar-testnet-lisbon-3` ```bash copy export CLIENT_A_ID="" @@ -324,9 +364,11 @@ SUCCESS Channel { ``` -### Change Hermes configuration +#### Update Hermes configuration -Now when the channels are created we need to update the [Hermes configuration](#Make-Hermes-config-file) +By default, Hermes will attempt to relay packets on all channels between the chains listed in its configuration file. +We can restrict Hermes to only relay packets on our newly created channels by updating the [Hermes configuration](#Make-Hermes-config-file) +with the following (for each chain): ```bash copy ... @@ -338,50 +380,53 @@ list = [ ... ``` -### Update IBC clients - -In order to have IBC channels running they need active IBC clients they rely on. When clients are not in use they tend to expire and to prevent this they are required to be updated manually. - -The "update channel" command (below) update the actual state of the client in the particular chain. +### Running the relayer +While Hermes is running, it monitors chains via the nodes and relays packets according to monitored events. You will +likely want to use `systemd`, `tmux`, `Docker` or some similar solution to ensure Hermes is running persistently in the background. +The command to run Hermes is simply: ```bash copy -hermes update client --host-chain $CHAIN_A_ID --client $CLIENT_A_ID -hermes update client --host-chain $CHAIN_B_ID --client $CLIENT_B_ID +hermes --config $HERMES_CONFIG start ``` -It is recommended to perform this manual update or use specific scripts to automate it. Otherwise, you risk your clients will be expired. The restoration is possible only from the Governance of the specific chain. +You can see more details of Hermes at [the official documentation](https://hermes.informal.systems/). -## Start the relayer -Once you run Hermes, it monitors chains via the nodes and relays packets according to monitored events. -```bash copy -hermes --config $HERMES_CONFIG start -``` -You can see more details of Hermes at [the official document](https://hermes.informal.systems/). +#### Updating IBC clients + +In order to keep IBC channels open for transfers, they must have active IBC clients. An IBC client on chain A references +the state of chain B, and vice versa. These clients must be regularly updated to maintain trust guarantees; if they are +allowed to lapse, the client will enter an 'expired' state and no further IBC transfers will be allowed on that channel +until the client is revived through governance. + +Whenever Hermes relays an IBC transfer, it will automatically update the clients on both chains. However, since reviving +an expired client through governance is a time-consuming task, it is worthwhile to regularly submit manual updates to +avoid any issues should transfer frequency be lower than expected. + +The "update channel" command (below) manually updates the state of a client on a particular chain. -After the sync, you can create the channel and start Hermes as explained [above](#create-ibc-channel). ```bash copy -# create a channel -hermes --config $HERMES_CONFIG \ - create channel \ - --a-chain $CHAIN_A_ID \ - --b-chain $CHAIN_B_ID \ - --a-port transfer \ - --b-port transfer \ - --new-client-connection --yes +hermes update client --host-chain $CHAIN_A_ID --client $CLIENT_A_ID +hermes update client --host-chain $CHAIN_B_ID --client $CLIENT_B_ID ``` -### Transferring assets over IBC -It is now possible to [transfer assets between the two chains.](../users/ibc.mdx) +It is recommended to schedule the above commands to run periodically (using a scheduler such `cron` or `systemd`) so that any client expiration issues can be avoided entirely. + +### Done! +You're now ready to test [transferring assets between the two chains.](../users/ibc.mdx) + + -## Set up local Namada chains using the Hermes script -The script `setup-namada` will set up two chains with one validator node, copy necessary files for Hermes, and make an account for Hermes on each ledger. Also, it will make a Hermes' config file `config_for_namada.toml` in the `hermes` directory. +## Testing with local Namada chains +The script `setup-namada` in the Heliax Hermes repo will set up two chains, each with one validator node, copy necessary files for Hermes, +and make an account for Hermes on each ledger. Also, it will make a Hermes' config file `config_for_namada.toml` +in the `hermes` directory. First, you will need to export some environment variables: ```bash copy export NAMADA_DIR="" -export TAG="v1.7.4-namada-beta7" +export TAG="v1.8.2-namada-beta11" # or the appropriate hermes version for your namada version ``` ```bash copy diff --git a/packages/docs/pages/users/ibc/_meta.json b/packages/docs/pages/users/ibc/_meta.json index a72eb5dd..031a9e38 100644 --- a/packages/docs/pages/users/ibc/_meta.json +++ b/packages/docs/pages/users/ibc/_meta.json @@ -1,4 +1,4 @@ { - "shielded-ibc": "Shielded IBC", - "transparent-ibc": "Transparent IBC" + "transparent-ibc": "Transparent IBC", + "shielded-ibc": "Shielded IBC" } \ No newline at end of file diff --git a/packages/docs/pages/users/ibc/shielded-ibc.mdx b/packages/docs/pages/users/ibc/shielded-ibc.mdx index 09a45aae..6d22b9a3 100644 --- a/packages/docs/pages/users/ibc/shielded-ibc.mdx +++ b/packages/docs/pages/users/ibc/shielded-ibc.mdx @@ -14,57 +14,48 @@ software such as [Hermes](https://github.com/heliaxdev/hermes). - You will need to know the corresponding channel id ## IBC transfer to a shielded address -{/* TODO: instructions are out of date? */} + +Previous versions of Namada required a two-step process to make IBC transfers to a shielded address: first a MASP proof was generated using the +`ibc-gen-shielded` command, and this proof was included in the `memo` field of the transfer. -Before sending your IBC transfer, you will need to generate a MASP +It is no longer necessary to manually generate the MASP proof, and the `ibc-gen-shielded` command has been removed. + + +IBC transfers to a shielded address work similarly to those for a [tranparent address](./transparent-ibc.mdx), +the only difference being that we provide for `$RECV_ADDRESS` a shielded (`znam`) address instead of a transparent (`tnam`) one: -Before `namadac ibc-transfer`, you need to generate a proof of the following IBC transfer for the shielding transfer - to the destination Namada. The command `namadac ibc-gen-shielded` generates the proof and outputs a file including - required data. In this case, Chain B is the destination chain. -```bash copy -namadac --base-dir ${BASE_DIR_B} ibc-gen-shielded \ - --output-folder-path ${OUTPUT_PATH} \ - --target ${payment_addr_b} \ - --token apfel \ - --amount 100 \ - --port-id transfer \ - --channel-id channel-0 \ - --node ${LEDGER_ADDRESS_B} -``` -Then, you can send the token from the source chain by setting the proof in the ICS-20 packet's memo field. -The following example is to send tokens from the source Namada (Chain A). The `${memo_path}` should be the file -path created by `namadac ibc-gen-shielded` on the destination chain. ```bash copy -namadac --base-dir ${BASE_DIR_A} ibc-transfer \ - --source ${spending_key_a} \ - --receiver ${payment_addr_b} \ - --token apfel \ - --amount 100 \ - --channel-id channel-0 \ - --memo-path ${memo_path} \ - --node ${LEDGER_ADDRESS_A} +namadac ibc-transfer \ + --source $SOURCE_ADDRESS \ + --receiver $RECEIVER_PAYMENT_ADDRESS \ + --token $TOKEN \ + --amount $AMOUNT \ + --channel-id $CHANNEL_ID ``` + +Or, when sending from a Cosmos Sdk chain: -When the source chain is a Cosmos-SDK based chain, the memo should be set as string with `--memo` option. ```bash copy -memo=$(cat ${memo_path}) gaiad tx ibc-transfer transfer \ - ${CHANNEL_ID} \ - ${RECEIVER_PAYMENT_ADDRESS} \ + $CHANNEL_ID \ + $RECEIVER_PAYMENT_ADDRESS \ ${AMOUNT}${IBC_TOKEN_ADDRESS} \ - --from ${COSMOS_ALIAS} \ - --memo ${memo} \ - --node ${COSMOS_RPC_ENDPOINT} \ + --from $COSMOS_ALIAS \ + --node $COSMOS_RPC_ENDPOINT \ --fees 5000uatom ``` -You can do unshielding transfers over IBC without generating a proof. +## IBC transfer from a shielded address +You can also send IBC transfers from a shielded address, by providing the associated spending key as the source: ```bash copy -namadac --base-dir ${BASE_DIR_A} ibc-transfer \ - --source ${spending_key_a} \ - --receiver ${RECEIVER_RAW_ADDRESS} \ - --token nam \ - --amount 100 \ - --channel-id channel-0 \ - --node ${LEDGER_ADDRESS_A} +namadac ibc-transfer \ + --source $SOURCE_SPEND_KEY \ + --receiver $RECV_ADDRESS \ + --token $TOKEN \ + --amount $AMOUNT \ + --channel-id $CHANNEL_ID \ + --gas-payer $IMPLICIT_ADDRESS ``` + +When sending any transaction from a shielded address, you must also provide an implicit address which you control with enough funds to cover gas costs. + \ No newline at end of file diff --git a/packages/docs/pages/users/ibc/transparent-ibc.mdx b/packages/docs/pages/users/ibc/transparent-ibc.mdx index 65ea9ceb..66424c6d 100644 --- a/packages/docs/pages/users/ibc/transparent-ibc.mdx +++ b/packages/docs/pages/users/ibc/transparent-ibc.mdx @@ -3,7 +3,7 @@ import { Callout } from 'nextra-theme-docs' # Transparent IBC You can send assets to another IBC compliant chain, such as a Cosmos SDK chain or another Namada chain, using the -`ibc-transfer` command in `namadac`. +`ibc-transfer`. This section covers sending assets to and from a transparent ( `tnam` ) address. @@ -18,15 +18,15 @@ software such as [Hermes](https://github.com/heliaxdev/hermes). To make an outgoing IBC transfer from a Namada transparent address: ```bash copy namadac ibc-transfer \ - --source $YOUR_TRANSPARENT_ADDRESS \ - --receiver $ADDRESS_ON_RECEIVING_CHAIN \ + --source $SOURCE_ADDRESS \ + --receiver $RECV_ADDRESS \ --token $TOKEN_ADDRESS \ - --amount $AMOUNT + --amount $AMOUNT \ --channel-id $CHANNEL_ID ``` Note: -- the `receiver` address is the address on the receiving chain -- if you are sending to another Namada chain, this would start with `tnam...`, -while if you're sending to a Cosmos SDK chain it might start with `cosmos...` or some other prefix. +- the `receiver` address is the raw address on the receiving chain -- if you are sending to another Namada chain, this would start with `tnam...`, +while if you're sending to a Cosmos SDK chain it might start with `cosmos...`, `osmo...`, or some other prefix. - the `channel-id` parameter is a string, for example `channel-27`. #### Example: Sending NAM to the Cosmos Hub @@ -66,4 +66,30 @@ gaiad tx ibc-transfer transfer \ The double use of 'transfer' in the above command is not a typo. The command takes an IBC port name as one of its parameters; and the name of the port happens to be 'transfer'. - \ No newline at end of file + + +## Querying IBC balances +You can query an account's balance of tokens received through IBC similarly to other tokens, using the 'IBC denom' token name which is a function of +the IBC port, channel, and token name (or address) on the originating chain: + +``` +IBC denom = {receiving_port}/{receiving_channel}/{token_name} +``` + + +Sending the same asset through two different IBC channels will result in two different token denoms on the receiving chain, which will not be fungible with +each other. This is expected behavior as defined in the IBC protocol. + + +#### Example: Balance query +If we have sent 100 NAM (token address `tnam1q87wtaqqtlwkw927gaff34hgda36huk0kgry692a`) from chain A to chain B over IBC, where the port is `transfer` and channel __on the receiving chain__ +is `channel-0`, we can check the balance on chain B using either of these (equivalent) commands: + +```bash copy +namadac balance --owner $ALIAS --token transfer/channel-0/nam +# or +namadac balance --owner $ALIAS --token transfer/channel-0/tnam1q87wtaqqtlwkw927gaff34hgda36huk0kgry692a + +# Output: +# transfer/channel-0/nam: 100 +``` From d71ea534de8c2bd8181846bc4928bac254a9eecf Mon Sep 17 00:00:00 2001 From: brentstone Date: Wed, 26 Jun 2024 17:09:42 -0700 Subject: [PATCH 89/94] edit operators' ibc section --- packages/docs/pages/operators/ibc.mdx | 50 +++++++++++++-------------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/packages/docs/pages/operators/ibc.mdx b/packages/docs/pages/operators/ibc.mdx index f54c6d02..26e8419d 100644 --- a/packages/docs/pages/operators/ibc.mdx +++ b/packages/docs/pages/operators/ibc.mdx @@ -13,13 +13,13 @@ Relayers are a crucial piece of infrastructure that allow IBC compatible chains A relayer is responsible for posting IBC packets to the destination chain, as well as performing other IBC functions such as creating channels, updating the light client states and checking for misbehavior. -Operating a relayer is permissionless. If at least one relayer is not running on a given channel between two chains, -they will not be able to pass messages to each other on that channel. IBC transfers that are attempted but not picked +Operating a relayer is permissionless. There must be at least one relayer running on a given channel between two chains if the chains are +to pass messages to each other on that channel. IBC transfers that are attempted but not picked up by a relayer will timeout and the tokens will be refunded to the sender. To operate a relayer, you will need: - A dedicated server -- [Hermes](#install-hermes); the relayer software. Heliax maintains a fork of Hermes compatible with Namada. +- [Hermes](#installing-hermes); the relayer software. Heliax maintains a fork of Hermes compatible with Namada. - Full nodes on both chains; a relayer needs to access several weeks worth of chain history and to frequently post transactions to both chains. For testing, a public RPC node may suffice, but for production it is highly recommended for reliability that relayer operators also operate both full nodes themselves. @@ -29,14 +29,14 @@ wallet on each with enough funds to cover gas costs (monitoring and topping up a This document covers the essentials for installing, configuring and running a relayer on Namada: -1. [Installing Hermes](#install-hermes) -2. [Configuring Hermes](#configure-hermes) +1. [Installing Hermes](#installing-hermes) +2. [Configuring Hermes](#configuring-hermes) 3. [Setting up the relayer](#setting-up-the-relayer) 4. [Creating an IBC channel](#creating-an-ibc-channel) -5. [Running the relayer](#start-the-relayer) +5. [Running the relayer](#running-the-relayer) And for setting up a testing environment by running two local Namada chains, see the section -[Testing with local Namada chains](#set-up-local-namada-chains-using-the-hermes-script) +[Testing with local Namada chains](#testing-with-local-namada-chains) ### Installing Hermes @@ -88,7 +88,7 @@ sudo cp ./target/release/hermes /usr/local/bin/ ### Configuring Hermes #### Make Hermes config file -Hermes' `config.toml` file defines which chains and channels the relayer will be responsible for. First, create that file: +The Hermes `config.toml` file defines which chains and channels the relayer will be responsible for. First, create that file: ```bash copy export HERMES_CONFIG="$HOME/.hermes/config.toml" @@ -210,7 +210,7 @@ These are the pieces of this puzzle you want to keep your πŸ‘€ on: - `chains.gas_price.denom` specifies the token that the relayer pays for IBC transactions. `chains.gas_price.price` isn't used for now in Namada. - `trusting_period` specifies the maximum period before which the client can not expire. This should be not more than unbonding time in the particular chain. -You can see more details of configuration in [the official document](https://hermes.informal.systems/documentation/configuration). +You can see more details of configuration in [the official Hermes documentation](https://hermes.informal.systems/documentation/configuration). #### Export environment variables @@ -295,18 +295,6 @@ Note that the above `CHAIN_IDs` will depend on your own setup, so do check this When the creation has been completed, you can see the channel IDs. For example, the output text below shows that a channel with ID `955` has been created on Chain A `shielded-expedition.88f17d1d14`, and a channel with ID `460` has been created on Chain B `axelar-testnet-lisbon-3`. -Note the channel id's, as you will need to specify the channel IDs when making a transfer over IBC. You specify `channel-955` as a channel ID -for a transfer from Chain A to Chain B. Also, you specify -`channel-460` as a channel ID for a transfer from Chain B to Chain A. (The prefix `channel-` is always required) - -Also note the ClientId for each of the chains; we will need them on the next step: -`07-tendermint-2996` for `shielded-expedition.88f17d1d14` and `07-tendermint-884` for `axelar-testnet-lisbon-3` - -```bash copy -export CLIENT_A_ID="" -export CLIENT_B_ID="" -``` - ``` SUCCESS Channel { @@ -364,6 +352,18 @@ SUCCESS Channel { ``` +Note the channel id's, as you will need to specify the channel IDs when making a transfer over IBC. You specify `channel-955` as a channel ID +for a transfer from Chain A to Chain B. Also, you specify +`channel-460` as a channel ID for a transfer from Chain B to Chain A. (The prefix `channel-` is always required) + +Also note the ClientId for each of the chains; we will need them on the next step: +`07-tendermint-2996` for `shielded-expedition.88f17d1d14` and `07-tendermint-884` for `axelar-testnet-lisbon-3` + +```bash copy +export CLIENT_A_ID="" +export CLIENT_B_ID="" +``` + #### Update Hermes configuration By default, Hermes will attempt to relay packets on all channels between the chains listed in its configuration file. @@ -396,7 +396,7 @@ You can see more details of Hermes at [the official documentation](https://herme In order to keep IBC channels open for transfers, they must have active IBC clients. An IBC client on chain A references the state of chain B, and vice versa. These clients must be regularly updated to maintain trust guarantees; if they are -allowed to lapse, the client will enter an 'expired' state and no further IBC transfers will be allowed on that channel +allowed to lapse, the client will enter an 'expired' state, and no further IBC transfers will be allowed on that channel until the client is revived through governance. Whenever Hermes relays an IBC transfer, it will automatically update the clients on both chains. However, since reviving @@ -419,7 +419,7 @@ You're now ready to test [transferring assets between the two chains.](../users/ ## Testing with local Namada chains The script `setup-namada` in the Heliax Hermes repo will set up two chains, each with one validator node, copy necessary files for Hermes, -and make an account for Hermes on each ledger. Also, it will make a Hermes' config file `config_for_namada.toml` +and make an account for Hermes on each ledger. Also, it will make a Hermes config file `config_for_namada.toml` in the `hermes` directory. First, you will need to export some environment variables: @@ -436,7 +436,7 @@ cd hermes ./scripts/setup-namada $NAMADA_DIR ``` -In this case, the user doesn't have to wait for sync. If the relayer account on each instance has enough balance, the user can create a channel and start Hermes immediately as explained [above](#create-ibc-channel). The user finds these chain IDs of the chains in the config file `config_for_namada.toml`. One can run `grep "id" ${HERMES_CONFIG}`. +In this case, the user doesn't have to wait for sync. If the relayer account on each instance has enough balance, the user can create a channel and start Hermes immediately as explained [above](#creating-an-ibc-channel). The user finds these chain IDs of the chains in the config file `config_for_namada.toml`. One can run `grep "id" ${HERMES_CONFIG}`. ```bash copy # create a channel hermes --config $HERMES_CONFIG \ @@ -451,7 +451,7 @@ hermes --config $HERMES_CONFIG \ hermes --config $HERMES_CONFIG start ``` -Each node data and configuration files are in `hermes/data/namada-*/.namada`. +Each node's data and configuration files are in `hermes/data/namada-*/.namada`. In order to close any ledgers setup by the script, one can run ```bash copy From 10c9ac82fcc0573abd2760859bffea9107e76645 Mon Sep 17 00:00:00 2001 From: iskay Date: Thu, 27 Jun 2024 10:31:37 -0400 Subject: [PATCH 90/94] update validator-setup --- .../validators/validator-actions.mdx | 3 ++- .../operators/validators/validator-setup.mdx | 26 ++++++++++++++++--- 2 files changed, 25 insertions(+), 4 deletions(-) diff --git a/packages/docs/pages/operators/validators/validator-actions.mdx b/packages/docs/pages/operators/validators/validator-actions.mdx index 8f8cbb0d..eb849b1c 100644 --- a/packages/docs/pages/operators/validators/validator-actions.mdx +++ b/packages/docs/pages/operators/validators/validator-actions.mdx @@ -33,7 +33,8 @@ namadac change-metadata \ --email $EMAIL \ --discord-handle $DISCORD_HANDLE \ --website $WEBSITE \ - --avatar $AVATAR + --avatar $AVATAR \ + --name $NAME ``` Apart from `--validator`, not all of the fields are required (but at least one of them is). diff --git a/packages/docs/pages/operators/validators/validator-setup.mdx b/packages/docs/pages/operators/validators/validator-setup.mdx index 17df7280..32cd9b84 100644 --- a/packages/docs/pages/operators/validators/validator-setup.mdx +++ b/packages/docs/pages/operators/validators/validator-setup.mdx @@ -34,6 +34,17 @@ Post-genesis validators are validators that become initialized after the genesis Before initializing your validator account, you must first [set up a full node](../ledger/running-a-full-node.mdx) and sync it with the head of the chain. +### Generate and fund an implicit account +In the next step, we will be sending an on-chain transaction to initialize our validator. Therefore, we must first generate an implicit +account and fund it with enough tokens to cover transaction [gas fees](../../users/fees.mdx). + +Use the following commands to generate a new implicit account and display its address. See the sections on [implicit accounts](../../users/transparent-accounts/implicit-accounts.mdx) +and the [filesystem wallet](../../users/wallet/file-system-wallet.mdx) for further details on working with implicit accounts. +```bash copy +namadaw gen --alias $IMPLICIT_ALIAS +namadaw list --addr +``` + ### Initialize a new validator account A validator account can be initialized from an [established account](../../users/transparent-accounts/established-accounts.mdx) by submitting an on-chain transaction. `namadac init-validator` will create a new established account and convert it to a validator account in a single command. @@ -47,7 +58,10 @@ namadac init-validator \ --commission-rate 0.05 \ --max-commission-rate-change 0.01 \ --email $EMAIL \ - --alias $ALIAS + --alias $VALIDATOR_ACCOUNT_ALIAS \ + --account-keys $IMPLICIT_ALIAS \ + --signing-keys $IMPLICIT_ALIAS \ + --threshold 1 ``` __Note:__ - `commission-rate` is the percentage of staking rewards kept by the validator for all tokens bonded to it. A validator can change its commission rate @@ -55,7 +69,11 @@ by no more than `max-commission-rate-change` per epoch. The `max-commission-rate Typical values are `0.05` (5%) and `0.01` (1%) respectively but validator are free to choose otherwise. - `email` should be set to a dedicated infra/security email account that you monitor regularly. It may be used to notify validators of urgent security issues, patches or chain upgrades. -- `alias` is used to reference your account by name in your wallet; it does not appear on-chain. +- `alias` is used to reference your newly created validator account by name in your wallet; it does not appear on-chain. Rather, your +validator's on-chain name is determined by the `name` value in its [validator metadata](./validator-actions.mdx#metadata-changes). +- a validator account is a special type of (on-chain) [established account](../../users/transparent-accounts/established-accounts.mdx). +Given that the command creates a new established account, you will need to have already created an [implicit account](../../users/transparent-accounts/implicit-accounts.mdx) +(`$IMPLICIT_ALIAS`) and funded it with enough tokens to cover transaction gas costs. You can optionally provide any of the following additional information to identify your validator on-chain (frequently displayed in block explorers): - `name`: An on-chain display name (similar to 'moniker' in Cosmos SDK chains) @@ -82,5 +100,7 @@ after bonding sufficient stake to place in the active consensus set, you must wa -## Validator account keys +{/* ## Validator account keys +TODO? +*/} From 2fa9f933a61f17ce45411c18794f815f6de9367b Mon Sep 17 00:00:00 2001 From: brentstone Date: Thu, 27 Jun 2024 23:18:35 -0700 Subject: [PATCH 91/94] more detail in change-metadata --- .../pages/operators/validators/validator-actions.mdx | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/packages/docs/pages/operators/validators/validator-actions.mdx b/packages/docs/pages/operators/validators/validator-actions.mdx index eb849b1c..fe5e155d 100644 --- a/packages/docs/pages/operators/validators/validator-actions.mdx +++ b/packages/docs/pages/operators/validators/validator-actions.mdx @@ -36,7 +36,16 @@ namadac change-metadata \ --avatar $AVATAR \ --name $NAME ``` -Apart from `--validator`, not all of the fields are required (but at least one of them is). +Only the `--validator` argument is required along with at least one of the other arguments listed above. In order to remove a piece of metadata (aside from the required `email`), pass `""` as an argument. + +For example, in order to change the validator name and description but remove the existing discord handle, one would run: + +```bash copy +namadac change-metadata --validator $VALIDATOR_ADDRESS \ + --description $NEW_DESC \ + --discord-handle "" \ + --name $NEW_NAME +``` ### Deactivation and reactivation From 8f096155f4adf44bef7519cfaf7cd21bff0584a7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Harrison=20Mendon=C3=A7a?= Date: Tue, 16 Jul 2024 18:17:54 -0300 Subject: [PATCH 92/94] add base dir callout --- .../docs/pages/operators/networks/local-network.mdx | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/packages/docs/pages/operators/networks/local-network.mdx b/packages/docs/pages/operators/networks/local-network.mdx index e0fc7ea6..b2a19848 100644 --- a/packages/docs/pages/operators/networks/local-network.mdx +++ b/packages/docs/pages/operators/networks/local-network.mdx @@ -1,4 +1,5 @@ import Expandable from "../../../components/Expandable"; +import { Callout } from "nextra-theme-docs"; # Spinning up a local network @@ -72,6 +73,18 @@ The ledger can be run through the familiar command: ./target/release/namada ledger # Assuming the binaries were built using `make build-release` ``` + +If you receive the error `Failed to construct Namada chain context...` you need to set the variable `NAMADA_BASE_DIR` + +```shell +export NAMADA_BASE_DIR=/$(pwd)/.namada/validator-0 + +# or pass it as the parameter --base-dir +./target/release/namada ledger --base-dir="/$(pwd)/.namada/validator-0" +``` + + + ## Cleaning up After the local network has fulfilled its purpose, it can be cleaned up by running the following commands found in the cleanup function of the script: From 61ada93c584944652f180fcdcccba87097ab8ae0 Mon Sep 17 00:00:00 2001 From: brentstone Date: Wed, 17 Jul 2024 23:06:29 -0700 Subject: [PATCH 93/94] small addition --- packages/docs/pages/operators/networks/local-network.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/docs/pages/operators/networks/local-network.mdx b/packages/docs/pages/operators/networks/local-network.mdx index b2a19848..333822c1 100644 --- a/packages/docs/pages/operators/networks/local-network.mdx +++ b/packages/docs/pages/operators/networks/local-network.mdx @@ -74,7 +74,7 @@ The ledger can be run through the familiar command: ``` -If you receive the error `Failed to construct Namada chain context...` you need to set the variable `NAMADA_BASE_DIR` +If you receive the error `Failed to construct Namada chain context...`, then you need to set the variable `NAMADA_BASE_DIR`. For example: ```shell export NAMADA_BASE_DIR=/$(pwd)/.namada/validator-0 From 73f270781c3a47bcaf6df4b7ba1e002acf855700 Mon Sep 17 00:00:00 2001 From: iskay Date: Fri, 19 Jul 2024 15:58:58 -0400 Subject: [PATCH 94/94] fix typos multisig docs --- .../transparent-accounts/multisignature.mdx | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/packages/docs/pages/users/transparent-accounts/multisignature.mdx b/packages/docs/pages/users/transparent-accounts/multisignature.mdx index 502a2148..52a93a2f 100644 --- a/packages/docs/pages/users/transparent-accounts/multisignature.mdx +++ b/packages/docs/pages/users/transparent-accounts/multisignature.mdx @@ -11,11 +11,11 @@ Multisignature accounts (multisigs) are accounts on Namada that allow for multip For this reason, all established accounts on Namada are multisignature accounts by default. -A multisignature account can be described as an "x of y" account, where x is the 'threshold' or required number of signatures on a transaction -and y is the total number of keys associated with the account. For example, a 3 of 5 multisig will need at least three of the parties to sign any transaction. +A multisignature account can be described as an "**x** *of* **y**" account, where **x** is the 'threshold' or required number of signatures on a transaction +and **y** is the total number of keys associated with the account. For example, a *3 of 5* multisig will need at least three of the parties to sign any transaction. ## Example: Initialising a multisignature account -Here is the process to generate a 2 of 3 multisig account: +Here is the process to generate a *2 of 3* multisig account: ### Create three signing keys @@ -33,7 +33,7 @@ In this example, Alice will cover the transaction fees and we'll assume she alre ### Init-account The `init-account` transaction is no different from a typical established account, except for threshold and number of public keys associated. -(In fact, a typical established account is simply a 1 of 1 multisig.) +(In fact, a typical established account is simply a *1 of 1* multisig.) The `--signing-keys` flag indicates that Alice is signing and paying fees for this transaction. ```bash copy @@ -55,7 +55,7 @@ The `--dump-tx` argument will write the transaction to disk. A folder is require ```bash copy mkdir tx_dumps -namadac transfer --source abc-multisig --target \ +namadac transfer --source abc-multisig --target $TARGET \ --token nam --amount 2 \ --signing-keys alice \ --dump-tx --output-folder-path tx_dumps @@ -74,7 +74,7 @@ namadac sign-tx \ --signing-keys alice \ --owner abc-multisig ``` -You should have created two new files, one with Alice's signature and one with Bob's: +You should have created two new files -- one with Alice's signature and one with Bob's. ```bash copy # contents of tx_dumps directory FC2955C6B252EF6E93B1B54923B2178A7DC47E06D27448A43426487DF4BAD0E3.tx @@ -85,13 +85,13 @@ To make things easier in the next step, we'll save these filenames to the shell ### Submit transaction on-chain Since we have enough signatures to meet the threshold of this account, we can submit the transaction. Note that we need to specify -an account that will pay the transaction fees. +an implicit account that will pay the transaction fees. ```bash copy namadac tx \ - --tx-path $TX - --signatures $SIG1 $SIG2 - --owner abc-multisig + --tx-path $TX \ + --signatures $SIG1 $SIG2 \ + --owner abc-multisig \ --gas-payer alice ``` @@ -113,7 +113,7 @@ namadac update-account \ --signing-keys alice,bob ``` -Note: you must include both the threshold and the list of public keys to be assosicated with this account, even if there is no change to one of those values. +Note: you must include both the threshold and the list of public keys to be associated with this account, even if there is no change to one of those values. @@ -128,7 +128,7 @@ One can check that the threshold has been updated correctly by running: namadac query-account \ --owner abc-multisig ``` -Which will list the threshold and all associated public keys of an account. +This will list the threshold and all associated public keys of an account. ## A video tutorial