From 7789e3ee85a68a5967d787a688b04780cf214097 Mon Sep 17 00:00:00 2001 From: Dante Sanchez Date: Tue, 17 Feb 2026 09:57:41 -0500 Subject: [PATCH] add hub/v26 folder --- docs.json | 119 +++ hub/v26/architecture/PROCESS.mdx | 58 ++ hub/v26/architecture/README.mdx | 65 ++ hub/v26/architecture/adr/PROCESS.mdx | 58 ++ hub/v26/architecture/adr/README.mdx | 64 ++ .../adr/adr-001-interchain-accounts.mdx | 93 ++ .../architecture/adr/adr-002-globalfee.mdx | 187 ++++ .../adr/adr-003-ica-controller.mdx | 61 ++ .../architecture/templates/adr-template.mdx | 54 ++ hub/v26/delegators/README.mdx | 11 + hub/v26/delegators/delegator-faq.mdx | 97 +++ hub/v26/delegators/delegator-guide-cli.mdx | 545 ++++++++++++ hub/v26/delegators/delegator-security.mdx | 54 ++ hub/v26/getting-started/README.mdx | 9 + hub/v26/getting-started/installation.mdx | 153 ++++ hub/v26/getting-started/quickstart.mdx | 137 +++ .../getting-started/system-requirements.mdx | 18 + hub/v26/getting-started/what-is-gaia.mdx | 25 + hub/v26/governance/README.mdx | 20 + hub/v26/governance/best-practices.mdx | 182 ++++ hub/v26/governance/formatting.mdx | 136 +++ hub/v26/governance/process.mdx | 68 ++ hub/v26/governance/proposal-types/README.mdx | 26 + .../proposal-types/community-pool-spend.mdx | 63 ++ .../proposal-types/param-change.mdx | 62 ++ .../proposal-types/software-upgrade.mdx | 69 ++ .../governance/proposal-types/text-prop.mdx | 93 ++ hub/v26/governance/submitting.mdx | 272 ++++++ hub/v26/hub-tutorials/README.mdx | 11 + hub/v26/hub-tutorials/gaiad.mdx | 812 ++++++++++++++++++ hub/v26/hub-tutorials/join-mainnet.mdx | 463 ++++++++++ hub/v26/hub-tutorials/join-testnet.mdx | 82 ++ .../hub-tutorials/live-upgrade-tutorial.mdx | 95 ++ hub/v26/hub-tutorials/upgrade-node.mdx | 149 ++++ hub/v26/index.mdx | 72 ++ hub/v26/interchain-security/README.mdx | 48 ++ hub/v26/modules/README.mdx | 46 + hub/v26/modules/liquid.mdx | 21 + hub/v26/modules/metaprotocols.mdx | 70 ++ hub/v26/modules/tokenfactory.mdx | 551 ++++++++++++ hub/v26/resources/README.mdx | 11 + hub/v26/resources/archives.mdx | 22 + hub/v26/resources/genesis.mdx | 346 ++++++++ hub/v26/resources/hd-wallets.mdx | 58 ++ hub/v26/resources/ledger.mdx | 212 +++++ hub/v26/resources/reproducible-builds.mdx | 60 ++ hub/v26/resources/service-providers.mdx | 287 +++++++ hub/v26/validators/README.mdx | 15 + hub/v26/validators/kms/kms.mdx | 39 + hub/v26/validators/kms/kms_ledger.mdx | 113 +++ hub/v26/validators/overview.mdx | 35 + hub/v26/validators/security.mdx | 59 ++ hub/v26/validators/validator-faq.mdx | 354 ++++++++ hub/v26/validators/validator-setup.mdx | 176 ++++ 54 files changed, 7006 insertions(+) create mode 100644 hub/v26/architecture/PROCESS.mdx create mode 100644 hub/v26/architecture/README.mdx create mode 100644 hub/v26/architecture/adr/PROCESS.mdx create mode 100644 hub/v26/architecture/adr/README.mdx create mode 100644 hub/v26/architecture/adr/adr-001-interchain-accounts.mdx create mode 100644 hub/v26/architecture/adr/adr-002-globalfee.mdx create mode 100644 hub/v26/architecture/adr/adr-003-ica-controller.mdx create mode 100644 hub/v26/architecture/templates/adr-template.mdx create mode 100644 hub/v26/delegators/README.mdx create mode 100644 hub/v26/delegators/delegator-faq.mdx create mode 100644 hub/v26/delegators/delegator-guide-cli.mdx create mode 100644 hub/v26/delegators/delegator-security.mdx create mode 100644 hub/v26/getting-started/README.mdx create mode 100644 hub/v26/getting-started/installation.mdx create mode 100644 hub/v26/getting-started/quickstart.mdx create mode 100644 hub/v26/getting-started/system-requirements.mdx create mode 100644 hub/v26/getting-started/what-is-gaia.mdx create mode 100644 hub/v26/governance/README.mdx create mode 100644 hub/v26/governance/best-practices.mdx create mode 100644 hub/v26/governance/formatting.mdx create mode 100644 hub/v26/governance/process.mdx create mode 100644 hub/v26/governance/proposal-types/README.mdx create mode 100644 hub/v26/governance/proposal-types/community-pool-spend.mdx create mode 100644 hub/v26/governance/proposal-types/param-change.mdx create mode 100644 hub/v26/governance/proposal-types/software-upgrade.mdx create mode 100644 hub/v26/governance/proposal-types/text-prop.mdx create mode 100644 hub/v26/governance/submitting.mdx create mode 100644 hub/v26/hub-tutorials/README.mdx create mode 100644 hub/v26/hub-tutorials/gaiad.mdx create mode 100644 hub/v26/hub-tutorials/join-mainnet.mdx create mode 100644 hub/v26/hub-tutorials/join-testnet.mdx create mode 100644 hub/v26/hub-tutorials/live-upgrade-tutorial.mdx create mode 100644 hub/v26/hub-tutorials/upgrade-node.mdx create mode 100644 hub/v26/index.mdx create mode 100644 hub/v26/interchain-security/README.mdx create mode 100644 hub/v26/modules/README.mdx create mode 100644 hub/v26/modules/liquid.mdx create mode 100644 hub/v26/modules/metaprotocols.mdx create mode 100644 hub/v26/modules/tokenfactory.mdx create mode 100644 hub/v26/resources/README.mdx create mode 100644 hub/v26/resources/archives.mdx create mode 100644 hub/v26/resources/genesis.mdx create mode 100644 hub/v26/resources/hd-wallets.mdx create mode 100644 hub/v26/resources/ledger.mdx create mode 100644 hub/v26/resources/reproducible-builds.mdx create mode 100644 hub/v26/resources/service-providers.mdx create mode 100644 hub/v26/validators/README.mdx create mode 100644 hub/v26/validators/kms/kms.mdx create mode 100644 hub/v26/validators/kms/kms_ledger.mdx create mode 100644 hub/v26/validators/overview.mdx create mode 100644 hub/v26/validators/security.mdx create mode 100644 hub/v26/validators/validator-faq.mdx create mode 100644 hub/v26/validators/validator-setup.mdx diff --git a/docs.json b/docs.json index cca526a2f..fe482664f 100644 --- a/docs.json +++ b/docs.json @@ -4942,6 +4942,125 @@ ] } ] + }, + { + "version": "v26", + "tabs": [ + { + "tab": "Documentation", + "groups": [ + { + "group": "Cosmos Hub", + "pages": [ + "hub/v26/index", + { + "group": "Getting Started", + "pages": [ + "hub/v26/getting-started/README", + "hub/v26/getting-started/what-is-gaia", + "hub/v26/getting-started/installation", + "hub/v26/getting-started/quickstart", + "hub/v26/getting-started/system-requirements" + ] + }, + { + "group": "Hub Tutorials", + "pages": [ + "hub/v26/hub-tutorials/gaiad", + "hub/v26/hub-tutorials/join-mainnet", + "hub/v26/hub-tutorials/join-testnet", + "hub/v26/hub-tutorials/live-upgrade-tutorial", + "hub/v26/hub-tutorials/README", + "hub/v26/hub-tutorials/upgrade-node" + ] + }, + { + "group": "Validators", + "pages": [ + "hub/v26/validators/overview", + "hub/v26/validators/README", + "hub/v26/validators/security", + "hub/v26/validators/validator-faq", + "hub/v26/validators/validator-setup", + "hub/v26/validators/kms/kms_ledger", + "hub/v26/validators/kms/kms" + ] + }, + { + "group": "Delegators", + "pages": [ + "hub/v26/delegators/delegator-faq", + "hub/v26/delegators/delegator-guide-cli", + "hub/v26/delegators/delegator-security", + "hub/v26/delegators/README" + ] + }, + { + "group": "Governance", + "pages": [ + "hub/v26/governance/best-practices", + "hub/v26/governance/formatting", + "hub/v26/governance/process", + "hub/v26/governance/README", + "hub/v26/governance/submitting", + "hub/v26/governance/proposal-types/community-pool-spend", + "hub/v26/governance/proposal-types/param-change", + "hub/v26/governance/proposal-types/README", + "hub/v26/governance/proposal-types/software-upgrade", + "hub/v26/governance/proposal-types/text-prop" + ] + }, + { + "group": "Interchain Security", + "pages": [ + "hub/v26/interchain-security/README" + ] + }, + { + "group": "Modules", + "pages": [ + "hub/v26/modules/liquid", + "hub/v26/modules/metaprotocols", + "hub/v26/modules/tokenfactory", + "hub/v26/modules/README" + ] + }, + { + "group": "Architecture", + "pages": [ + "hub/v26/architecture/PROCESS", + "hub/v26/architecture/README", + "hub/v26/architecture/adr/adr-001-interchain-accounts", + "hub/v26/architecture/templates/adr-template", + "hub/v26/architecture/adr/adr-002-globalfee", + "hub/v26/architecture/adr/adr-003-ica-controller", + "hub/v26/architecture/adr/PROCESS", + "hub/v26/architecture/adr/README" + ] + }, + { + "group": "Resources", + "pages": [ + "hub/v26/resources/archives", + "hub/v26/resources/genesis", + "hub/v26/resources/hd-wallets", + "hub/v26/resources/ledger", + "hub/v26/resources/README", + "hub/v26/resources/reproducible-builds", + "hub/v26/resources/service-providers" + ] + }, + { + "group": "Telemetry", + "pages": [ + "hub/v26/telemetry/telemetry" + ] + } + ] + } + ] + } + ] } ] } diff --git a/hub/v26/architecture/PROCESS.mdx b/hub/v26/architecture/PROCESS.mdx new file mode 100644 index 000000000..710d20eeb --- /dev/null +++ b/hub/v26/architecture/PROCESS.mdx @@ -0,0 +1,58 @@ +--- +title: ADR Creation Process +--- +1. Copy the `adr-template.md` file. Use the following filename pattern: `adr-next_number-title.md` +2. Create a draft Pull Request and solicit input from the stewarding team, if you want to get an early feedback. +3. Make sure that the problem, the context and a recommended solution is clear and well documented. Be sure to document alternate solution spaces and give reasons why they have been discarded. +4. Add an entry to a list in the README file [Table of Contents](/hub/v26/architecture/README#adr-table-of-contents). +5. Create a Pull Request to propose a new ADR. + +## ADR life cycle + +ADR creation is an **iterative** process. Instead of trying to solve all decisions in a single ADR pull request, we MUST firstly understand the problem and collect feedback through a GitHub Issue. + +1. Every proposal SHOULD start with a new GitHub Issue or be a result of existing Issues. The Issue should contain just a brief proposal summary. + +2. Once the motivation is validated, a GitHub Pull Request (PR) is created with a new document based on the `adr-template.md`. + +3. An ADR doesn't have to arrive to `main` with an *accepted* status in a single PR. If the motivation is clear and the solution is sound, we SHOULD be able to merge it and keep a *proposed* status. It's preferable to have an iterative approach rather than long, not merged Pull Requests. + +4. If a *proposed* ADR is merged, then it should clearly document outstanding issues either in ADR document notes or in a GitHub Issue. + +5. The PR SHOULD always be merged. In the case of a faulty ADR, we still prefer to merge it with a *rejected* status. The only time the ADR SHOULD NOT be merged is if the author abandons it. + +6. Merged ADRs SHOULD NOT be deleted. + +### ADR status + +Status has two components: + +```text +{CONSENSUS STATUS} {IMPLEMENTATION STATUS} +``` + +IMPLEMENTATION STATUS is either `Implemented` or `Not Implemented`. + +#### Consensus Status + +```mermaid +flowchart TD + A[DRAFT] --> B[PROPOSED] + B --> C[LAST CALL YYYY-MM-DD] + B --> D[ABANDONED] + C --> E[ACCEPTED or REJECTED] + E --> F[SUPERSEDED by ADR-xxx] +``` + +* `DRAFT`: \[optional] an ADR which is work in progress, not being ready for a general review. This is to present an early work and get an early feedback in a Draft Pull Request form. +* `PROPOSED`: an ADR covering a full solution architecture and still in the review - project stakeholders haven't reached an agreement yet. +* `LAST CALL `: \[optional] clear notify that we are close to accept updates. Changing a status to `LAST CALL` means that social consensus (of Cosmos SDK maintainers) has been reached and we still want to give it a time to let the community react or analyze. +* `ACCEPTED`: ADR which will represent a currently implemented or to be implemented architecture design. +* `REJECTED`: ADR can go from PROPOSED or ACCEPTED to rejected if the consensus among project stakeholders will decide so. +* `SUPERSEEDED by ADR-xxx`: ADR which has been superseded by a new ADR. +* `ABANDONED`: the ADR is no longer pursued by the original authors. + +## Language used in ADR + +* The context/background should be written in the present tense. +* Avoid using a first, personal form. diff --git a/hub/v26/architecture/README.mdx b/hub/v26/architecture/README.mdx new file mode 100644 index 000000000..091319524 --- /dev/null +++ b/hub/v26/architecture/README.mdx @@ -0,0 +1,65 @@ +--- +title: Architecture Decision Records (ADR) +description: >- + This is a location to record all high-level architecture decisions for new + feature and module proposals in the Cosmos Hub. +--- +This is a location to record all high-level architecture decisions for new feature and module proposals in the Cosmos Hub. + +An Architectural Decision (**AD**) is a software design choice that addresses a functional or non-functional requirement that is architecturally significant. +An Architecturally Significant Requirement (**ASR**) is a requirement that has a measurable effect on a software system’s architecture and quality. +An Architectural Decision Record (**ADR**) captures a single AD, such as often done when writing personal notes or meeting minutes; the collection of ADRs created and maintained in a project constitute its decision log. All these are within the topic of Architectural Knowledge Management (AKM). + +You can read more about the ADR concept [here](https://adr.github.io/). + +## Rationale + +ADRs are intended to be the primary mechanism for proposing new feature designs and new processes, for collecting community input on an issue, and for documenting the design decisions. +An ADR should provide: + +* Context on the relevant goals and the current state +* Proposed changes to achieve the goals +* Summary of pros and cons +* Discarded solution spaces and why they were discarded +* References +* Changelog + +Note the distinction between an ADR and a spec. The ADR provides the context, intuition, reasoning, and +justification for a change in architecture, or for the architecture of something +new. The spec is much more compressed and streamlined summary of everything as +it stands today. + +If recorded decisions turn out to be lacking, convene a discussion, record the new decisions here, and then modify the code to match. + +## Creating new ADR + +Read about the [PROCESS](/hub/v26/architecture/PROCESS). + +### Use RFC 2119 Keywords + +When writing ADRs, follow the same best practices for writing RFCs. +When writing RFCs, key words are used to signify the requirements in the specification. +These words are often capitalized: "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL. +They are to be interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119). + +## ADR Table of Contents + +### Accepted + +* n/a + +### Proposed + +* n/a + +### Draft + +* n/a + +### Rejected + +* [ADR 001: Interchain Accounts](/hub/v26/architecture/adr/adr-001-interchain-accounts) + +### Deprecated + +* [ADR 002: Globalfee Module](/hub/v26/architecture/adr/adr-002-globalfee) diff --git a/hub/v26/architecture/adr/PROCESS.mdx b/hub/v26/architecture/adr/PROCESS.mdx new file mode 100644 index 000000000..18b6b8c73 --- /dev/null +++ b/hub/v26/architecture/adr/PROCESS.mdx @@ -0,0 +1,58 @@ +--- +title: ADR Creation Process +--- +1. Copy the `adr-template.md` file. Use the following filename pattern: `adr-next_number-title.md` +2. Create a draft Pull Request and solicit input from the stewarding team, if you want to get an early feedback. +3. Make sure that the problem, the context and a recommended solution is clear and well documented. Be sure to document alternate solution spaces and give reasons why they have been discarded. +4. Add an entry to a list in the README file [Table of Contents](/hub/v26/architecture/adr/README#adr-table-of-contents). +5. Create a Pull Request to propose a new ADR. + +## ADR life cycle + +ADR creation is an **iterative** process. Instead of trying to solve all decisions in a single ADR pull request, we MUST firstly understand the problem and collect feedback through a GitHub Issue. + +1. Every proposal SHOULD start with a new GitHub Issue or be a result of existing Issues. The Issue should contain just a brief proposal summary. + +2. Once the motivation is validated, a GitHub Pull Request (PR) is created with a new document based on the `adr-template.md`. + +3. An ADR doesn't have to arrive to `main` with an *accepted* status in a single PR. If the motivation is clear and the solution is sound, we SHOULD be able to merge it and keep a *proposed* status. It's preferable to have an iterative approach rather than long, not merged Pull Requests. + +4. If a *proposed* ADR is merged, then it should clearly document outstanding issues either in ADR document notes or in a GitHub Issue. + +5. The PR SHOULD always be merged. In the case of a faulty ADR, we still prefer to merge it with a *rejected* status. The only time the ADR SHOULD NOT be merged is if the author abandons it. + +6. Merged ADRs SHOULD NOT be deleted. + +### ADR status + +Status has two components: + +```text +{CONSENSUS STATUS} {IMPLEMENTATION STATUS} +``` + +IMPLEMENTATION STATUS is either `Implemented` or `Not Implemented`. + +#### Consensus Status + +```mermaid +flowchart TD + A[DRAFT] --> B[PROPOSED] + B --> C[LAST CALL YYYY-MM-DD] + B --> D[ABANDONED] + C --> E[ACCEPTED or REJECTED] + E --> F[SUPERSEDED by ADR-xxx] +``` + +* `DRAFT`: \[optional] an ADR which is work in progress, not being ready for a general review. This is to present an early work and get an early feedback in a Draft Pull Request form. +* `PROPOSED`: an ADR covering a full solution architecture and still in the review - project stakeholders haven't reached an agreement yet. +* `LAST CALL `: \[optional] clear notify that we are close to accept updates. Changing a status to `LAST CALL` means that social consensus (of Cosmos SDK maintainers) has been reached and we still want to give it a time to let the community react or analyze. +* `ACCEPTED`: ADR which will represent a currently implemented or to be implemented architecture design. +* `REJECTED`: ADR can go from PROPOSED or ACCEPTED to rejected if the consensus among project stakeholders will decide so. +* `SUPERSEEDED by ADR-xxx`: ADR which has been superseded by a new ADR. +* `ABANDONED`: the ADR is no longer pursued by the original authors. + +## Language used in ADR + +* The context/background should be written in the present tense. +* Avoid using a first, personal form. diff --git a/hub/v26/architecture/adr/README.mdx b/hub/v26/architecture/adr/README.mdx new file mode 100644 index 000000000..ccd878d5b --- /dev/null +++ b/hub/v26/architecture/adr/README.mdx @@ -0,0 +1,64 @@ +--- +title: Architecture Decision Records (ADR) +--- +{/* order: 1 parent: title: Architecture Decision Records (ADR) order: 10 */} + +This is a location to record all high-level architecture decisions for new feature and module proposals in the Cosmos Hub. + +An Architectural Decision (**AD**) is a software design choice that addresses a functional or non-functional requirement that is architecturally significant. +An Architecturally Significant Requirement (**ASR**) is a requirement that has a measurable effect on a software system’s architecture and quality. +An Architectural Decision Record (**ADR**) captures a single AD, such as often done when writing personal notes or meeting minutes; the collection of ADRs created and maintained in a project constitute its decision log. All these are within the topic of Architectural Knowledge Management (AKM). + +You can read more about the ADR concept [here](https://adr.github.io/). + +## Rationale + +ADRs are intended to be the primary mechanism for proposing new feature designs and new processes, for collecting community input on an issue, and for documenting the design decisions. +An ADR should provide: + +* Context on the relevant goals and the current state +* Proposed changes to achieve the goals +* Summary of pros and cons +* Discarded solution spaces and why they were discarded +* References +* Changelog + +Note the distinction between an ADR and a spec. The ADR provides the context, intuition, reasoning, and +justification for a change in architecture, or for the architecture of something +new. The spec is much more compressed and streamlined summary of everything as +it stands today. + +If recorded decisions turn out to be lacking, convene a discussion, record the new decisions here, and then modify the code to match. + +## Creating new ADR + +Read about the [PROCESS](/hub/v26/architecture/adr/PROCESS). + +### Use RFC 2119 Keywords + +When writing ADRs, follow the same best practices for writing RFCs. +When writing RFCs, key words are used to signify the requirements in the specification. +These words are often capitalized: "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL. +They are to be interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119). + +## ADR Table of Contents + +### Accepted + +* n/a + +### Proposed + +* [ADR 003: Interchain Accounts Controller Module](/hub/v26/architecture/adr/adr-003-ica-controller) + +### Draft + +* n/a + +### Rejected + +* [ADR 001: Interchain Accounts](/hub/v26/architecture/adr/adr-001-interchain-accounts) + +### Deprecated + +* [ADR 002: Globalfee Module](/hub/v26/architecture/adr/adr-002-globalfee) diff --git a/hub/v26/architecture/adr/adr-001-interchain-accounts.mdx b/hub/v26/architecture/adr/adr-001-interchain-accounts.mdx new file mode 100644 index 000000000..1421d527d --- /dev/null +++ b/hub/v26/architecture/adr/adr-001-interchain-accounts.mdx @@ -0,0 +1,93 @@ +--- +title: 'ADR 001: Interchain Accounts' +--- +{/* order: 2 */} + +## Changelog + +* 2022-02-04: added content +* 2022-01-19: init +* 2023-06-28: mark as rejected + +## Status + +REJECTED Not Implemented + +**Reason:** The IBC team decided to integrate this functionality directly into their codebase and maintain it, because multiple users require it. + +## Abstract + +This is the Core Interchain Accounts Module. It allows the Cosmos Hub to act as a host chain with interchain accounts that are controlled by external IBC connected "Controller" blockchains. Candidate chains include Umee, Quicksilver, Sommelier. It is also a necessary component for a Authentication Module that allows the Cosmos Hub to act as a Controller chain as well. This will be recorded in a separate ADR. + +## Rationale + +This allows the Hub to participate in advanced cross-chain defi operations, like Liquid Staking and various protocol controlled value applications. + +## Desired Outcome + +The hub can be used trustlessly as a host chain in the configuration of Interchain Accounts. + +## Consequences + +There has been preliminary work done to understand if this increases any security feature of the Cosmos Hub. One thought was that this capability is similar to contract to contract interactions which are possible on virtual machine blockchains like EVM chains. Those interactions introduced a new attack vector, called a re-entrancy bug, which was the culprit of "The DAO hack on Ethereum". We believe there is no risk of these kinds of attacks with Interchain Accounts because they require the interactions to be atomic and Interchain Accounts are asynchronous. + +#### Backwards Compatibility + +This is the first of its kind. + +#### Forward Compatibility + +There are future releases of Interchain Accounts which are expected to be backwards compatible. + +## Technical Specification + +[ICS-27 Spec](https://github.com/cosmos/ibc/blob/master/spec/app/ics-027-interchain-accounts/README.md) + +## Development + +* Integration requirements + * Development has occurred in [IBC-go](https://github.com/cosmos/ibc-go) and progress tracked on the project board there. +* Testing (Simulations, Core Team Testing, Partner Testing) + * Simulations and Core Team tested this module +* Audits (Internal Dev review, Third-party review, Bug Bounty) + * An internal audit, an audit from Informal Systems, and an audit from Trail of Bits all took place with fixes made to all findings. +* Networks (Testnets, Productionnets, Mainnets) + * Testnets + +## Governance \[optional] + +* **Needs Signaling Proposal** +* Core Community Governance + * N/A +* Steering Community + * N/A. Possibly Aditya Srinpal, Sean King, Bez? +* Timelines & Roadmap + * Expected to be released as part of IBC 3.0 in Feb 2022 (currently in [beta release](https://github.com/cosmos/ibc-go/releases/tag/v3.0.0-beta1)) + +## Project Integrations \[optional] + +* Gaia Integrations + * [PR](https://github.com/cosmos/gaia/pull/1150) +* Integration Partner + * IBC Team + +#### Downstream User Impact Report + +(Needs to be created) + +#### Upstream Partner Impact Report + +(Needs to be created) + +#### Inter-module Dependence Report + +(Needs to be created) + +## Support + +[Documentation](/ibc/next/apps/interchain-accounts/overview) + +## Additional Research & References + +* [Why Interchain Accounts Change Everything for Cosmos Interoperability](https://medium.com/chainapsis/why-interchain-accounts-change-everything-for-cosmos-interoperability-59c19032bf11) +* [Interchain Account Auth Module Demo Repo](https://github.com/cosmos/interchain-accounts) diff --git a/hub/v26/architecture/adr/adr-002-globalfee.mdx b/hub/v26/architecture/adr/adr-002-globalfee.mdx new file mode 100644 index 000000000..43b424fdf --- /dev/null +++ b/hub/v26/architecture/adr/adr-002-globalfee.mdx @@ -0,0 +1,187 @@ +--- +title: 'ADR 002: Globalfee Module [DEPRECATED]' +description: '- 2023-06-12: Initial Draft - 2024-06-06: Change status to deprecated' +--- +## Changelog + +* 2023-06-12: Initial Draft +* 2024-06-06: Change status to deprecated + +## Status + +Deprecated + +## Context + +The globalfee module was created to manage a parameter called `MinimumGasPricesParam`, which sets a network-wide minimum fee requirement. The intention was to stop random denominations from entering fee collections and to reduce the time validators take to check a long list of transaction fees. To address scenarios where no fee payment is required but the denominations for volunteered paid fees are still restricted, the zero coins was introduced to serve as a means of limiting the denoms. Nevertheless, the initial version of the globalfee module had some issues: + +* In the globalfee module, several Cosmos SDK coins methods were redefined because of the allowance of zero-value coins in the `MinimumGasPricesParam`. The `MinimumGasPricesParam` is of `sdk.DecCoins` type. In the Cosmos SDK, `sdk.DecCoins` are [sanitized](https://github.com/cosmos/cosmos-sdk/blob/67f04e629623d4691c4b2e48806f7793a3aa211e/types/dec_coin.go#L160-L177) to remove zero-value coins. As a result, several methods from `sdk.Coins` were [redefined in the Gaia fee antehandler](https://github.com/cosmos/gaia/blob/890ab3aa2e5788537b0d2ebc9bafdc968340e0e5/x/globalfee/ante/fee_utils.go#L46-L104). + +* `BypassMinFeeMsgTypes` exists in `app.toml`, which means each node can define its own value. Thus, it's not clear whether a transaction containing bypass-messages will be exempted from paying a fee. + +* The fee check logic is only executed in `CheckTx`. This could enable malicious validators to change the fee check code and propose transactions that do not meet the fee requirement. + +## Decision + +To fix these problems, the following changes are added to the globalfee module: + +* **ZeroCoins in `MinimumGasPricesParam`:**\ + Refactor the fee check logics, in order to use the Cosmos SDK coins' methods instead of the redefined methods. +* **Bypass Message Types:**\ + `BypassMinFeeMsgTypes` is refactored to be a param of the globalfee module, in order to make the bypass messages deterministic. +* **Check Fees in `DeliverTx`:**\ + The fee check is factored to executed in both `DeliverTx` and `CheckTx`. This is to prevent malicious validators from changing the fee check logic and allowing any transactions to pass fee check. As a consequence, `MinimumGasPricesParam` is introduced as a globalfee param. + +### ZeroCoins in `MinimumGasPricesParam` + +#### Coins Split + +`CombinedFeeRequirement` refers to the fee requirement that takes into account both `globalFees` (`MinimumGasPricesParam` in the globalfee module) and `localFees` (`minimum-gas-prices` in `app.toml`). This requirement is calculated as the maximum value between `globalFees` and `localFees` for denomination exists `globalFees`. +The allowance of zero coins in the `MinimumGasPricesParam` within the globalfee module implies that `CombinedFeeRequirement(globalFees, localFees)` also permits zero coins. Therefore, the `CombinedFeeRequirement` doesn't meet the requirements of certain `sdk.Coins` methods. For instance, the `DenomsSubsetOf` method requires coins that do not contain zero coins. + +To address this issue, the `CombinedFeeRequirement` and `feeCoins` are split as shown in the chart below. + +```mermaid expandable +--- +title: Fee Requirements and Fee Splits +--- +flowchart TD + subgraph feeReq + A[CombinedFeeRequirement]-->B[/Split zero/nonzero coins/] + B-->|zero coins| C[zeroCoinFeesDenomReq]; + B-->|nonzero coins| D[nonzeroCoinFeesDenomReq]; + + end + + subgraph feeCoin + E[feeCoins]-->F[/Split by the denoms in zero/nonzero CoinFeesDenomReq/] + F-->|denoms in zeroCoinFeesDenomReq set| G[feeCoinsZeroDenom] + F-->|denoms in nonzeroCoinFeesDenomReq set| H[feeCoinsNonZeroDenom] + end +``` + +The `CombinedFeeRequirement` is split into zero and non-zero coins, forming `nonZeroCoinFeesReq` and `zeroCoinFeesDenomReq`. Similarly, the paid fees (feeCoins) are split into `feeCoinsNonZeroDenom` and `feeCoinsZeroDenom`, based on the denominations of `nonZeroCoinFeesReq` and `zeroCoinFeesDenomReq` as shown in the following code snippet. + +```go +nonZeroCoinFeesReq, zeroCoinFeesDenomReq := getNonZeroFees(feeRequired) + + // feeCoinsNonZeroDenom contains non-zero denominations from the feeRequired + // feeCoinsNonZeroDenom is used to check if the fees meets the requirement imposed by nonZeroCoinFeesReq + // when feeCoins does not contain zero coins' denoms in feeRequired + feeCoinsNonZeroDenom, feeCoinsZeroDenom := splitCoinsByDenoms(feeCoins, zeroCoinFeesDenomReq) +``` + +#### Fee Checks + +The Workflow of feeCheck is shown below: + +```mermaid expandable +--- +title: Fee Check +--- +flowchart TD + +A[feeCoinsNonZeroDenom]-->B[/DenomsSubsetOf_nonZeroCoinFeesReq/]; +B-->|yes|C[is_bypass_msg]; +B-->|no|D((reject)); + +C-->|yes|pass1((pass)); +C-->|no|D[/contain_zeroCoinFeesDenomReq_denom/]; + +D-->|yes|pass2((pass)); +D-->|no|E[/feeCoinsZeroDenom_nonEmpty/]; + +E-->|yes|pass3((pass)); +E-->|no|F[/IsAnyGTE_nonZeroCoinFeesDenomReq/]; + +F-->|yes|pass4((pass)); +F-->|no|reject2((reject)); +``` + +The split enable checking `feeCoinsNonZeroDenom` against `nonZeroCoinFeesReq`, and `feeCoinsZeroDenom` against +`zeroCoinFeesDenomReq` (as shown in the following code snippet). In the check of `feeCoinsNonZeroDenom` against `nonZeroCoinFeesReq`, the Cosmos SDK coins' methods can be used since zero coins are removed from the `nonZeroCoinFeesReq`, while in the check `feeCoinsZeroDenom` against `zeroCoinFeesDenomReq`, only denoms need to be checked. + +Checking `feeCoinsNonZeroDenom` against `nonZeroCoinFeesReq`: + +```go +if !feeCoinsNonZeroDenom.IsAnyGTE(nonZeroCoinFeesReq) { + return ctx, sdkerrors.Wrapf(sdkerrors.ErrInsufficientFee, "insufficient fees; got: %s required: %s", feeCoins.String(), feeRequired.String()) +} +``` + +Here is an example of how the coins split and checked in fee antehandler: + +**assumption**: + +`globalfee=[1photon, 0uatom, 1stake]` and `local min-gas-prices=[0.5stake]` + +**fee requirement**: + +`combinedFeeRequirement=[1photon, 0uatom, 1stake]` + +**split fee requirement**: + +the `combinedFeeRequirement` into `nonZeroCoinFeesReq=[0uatom]`, and `nonZeroCoinFeesReq=[1photon, 1stake]` + +**split the paid fees**: + +if `paidFee=[1uatom, 0.5photon]`, +the `splitCoinsByDenoms` splits the paidFee into `feeCoinsZeroDenom=[1uatom]` (the same denom as zero coins in `combinedFeeRequirement`), and `feeCoinsNonZeroDenom=[0.5stake]` +then `feeCoinsZeroDenom=[1uatom]` is checked by `nonZeroCoinFeesReq=[1photon, 1stake]`. + +Please note that `feeCoins` does not contain zero coins. The fee coins are split according to the denoms in `zeroCoinFeesDenomReq` or `nonZeroCoinFeesDenomReq`. If feeCoins contains coins not in both `zeroCoinFeesDenomReq` and `nonZeroCoinFeesDenomReq`, the transaction should be rejected. On the contrary, if feeCoins' denoms are in either `zeroCoinFeesDenomReq` or `nonZeroCoinFeesDenomReq`, and `len(zeroCoinFeesDenomReq)!=0`, the transaction can directly pass, otherwise, the fee amount need to be checked. + +### Bypass Message Types + +`BypassMinFeeMsgTypes` was a setup in `config/app.toml` before the refactor. `BypassMinFeeMsgTypes` is refactored to be a param of the globalfee module to get a network level agreement. Correspondingly,`MaxTotalBypassMinFeeMsgGasUsage` is also introduced as a globalfee param. + +### Fee Checks in `DeliverTx` + +Implementing fee checks within the `DeliverTx` function introduces a few requirements: + +* **Deterministic Minimum Fee Requirement**: For the `DeliverTx` process, it is essential to have a deterministic minimum fee requirement. In `CheckTx`, fee is checked by the `CombinedFeeRequirement(globalFees, localFees)`, which considers both `minimum-gas-prices` from `config/app.toml` and `MinimumGasPricesParam` from the globalfee Params (For more details, see [globalfee](https://github.com/cosmos/gaia/blob/v16.0.0/docs/docs/modules/globalfee.md)). `CombinedFeeRequirement` contains non-deterministic part: `minimum-gas-prices` from `app.toml`. Therefore, `CombinedFeeRequirement` cannot be used in `DeliverTx`. In `DeliverTx`, only `MinimumGasPricesParam` in globalfee Params is used for fee verification. The code implementation is shown below. + +```go expandable +func (mfd FeeDecorator) + +GetTxFeeRequired(ctx sdk.Context, tx sdk.FeeTx) (sdk.Coins, error) { + // Get required global fee min gas prices + // Note that it should never be empty since its default value is set to coin={"StakingBondDenom", 0 +} + +globalFees, err := mfd.GetGlobalFee(ctx, tx) + if err != nil { + return sdk.Coins{ +}, err +} + + // In DeliverTx, the global fee min gas prices are the only tx fee requirements. + if !ctx.IsCheckTx() { + return globalFees, nil +} + + // In CheckTx mode, the local and global fee min gas prices are combined + // to form the tx fee requirements + + // Get local minimum-gas-prices + localFees := GetMinGasPrice(ctx, int64(tx.GetGas())) + + // Return combined fee requirements + return CombinedFeeRequirement(globalFees, localFees) +} +``` + +* **Deterministic Bypass Parameters**: The decision of whether a message can bypass the minimum fee has to be deterministic as well. To ensure this, `BypassMinFeeMsgTypes` and `MaxTotalBypassMinFeeMsgGasUsage` parameters are moved to a persistent store. + +* **Module Initialization Order**: The genutils module must be initialized before the globalfee module. This is due to the `DeliverGenTxs` in the genutils module, is called during `initGenesis`. This function executes `DeliverTx`, which subsequently calls the AnteHandle in FeeDecorator, triggering the fee check in `DeliverTx`. + To prevent the `DeliverGenTxs` go through a fee check, the initialization of the globalfee module should occur after the genutils module. This sequencing ensures that all necessary components are in place when the fee check occurs. See [Gaia Issue #2489](https://github.com/cosmos/gaia/issues/2489) for more context. + +## Consequences + +### Positive + +This refactor results in code that is easier to maintain. It prevents malicious validators from escaping fee checks and make the bypass messages work at network level. + +### Negative + +The introduction of FeeDecorator has replaced the usage of `MempoolFeeDecorator` in the Cosmos SDK. Currently, if both FeeDecorator and MempoolFeeDecorator are added to the AnteDecorator chain, it will result in redundant checks. However, there's potential for FeeDecorator and MempoolFeeDecorator to become incompatible in the future, depending on updates to the Cosmos SDK. diff --git a/hub/v26/architecture/adr/adr-003-ica-controller.mdx b/hub/v26/architecture/adr/adr-003-ica-controller.mdx new file mode 100644 index 000000000..982defcaf --- /dev/null +++ b/hub/v26/architecture/adr/adr-003-ica-controller.mdx @@ -0,0 +1,61 @@ +--- +title: 'ADR 003: Interchain Accounts Controller Module' +--- +## Changelog + +* 2024-03-08: Initial Draft + +## Status + +Proposed + +## Abstract + +The Interchain Accounts Controller IBC module allows users of one chain to create and control accounts on other chains. The Hub currently doesn't have ICA Controller module enabled, so it is not possible to create accounts on other chains from the Hub chain. + +## Context + +Enabling the ICA Controller module on the Hub would support various use cases. One such case could be the provider-based governance that would allow the ATOM stakers to participate in a governance on consumer chains. + +## Decision + +The ICA Controller module will be included in the application, so the Hub will have both ICA Host and Controller modules. The implementation will use the Controller module's built-in authentication mechanism, since we don't have a need for custom authentication logic. According to this, users will directly use `MsgRegisterInterchainAccount` and `MsgSendTx` messages defined by the Controller module. The possibility provided by the Controller module to define underlying application to have custom processing of IBC messages exchanged by the Controller module (e.g. `OnChanOpenInit`, `OnAcknowledgementPacket`, etc.) will not be used, since there is currently no need for this. + +```go expandable +// ICA Controller keeper +appKeepers.ICAControllerKeeper = icacontrollerkeeper.NewKeeper( + appCodec, + appKeepers.keys[icacontrollertypes.StoreKey], + appKeepers.GetSubspace(icacontrollertypes.SubModuleName), + appKeepers.IBCKeeper.ChannelKeeper, // ICS4Wrapper + appKeepers.IBCKeeper.ChannelKeeper, + &appKeepers.IBCKeeper.PortKeeper, + appKeepers.ScopedICAControllerKeeper, + bApp.MsgServiceRouter(), +) + +// Create ICA module +appKeepers.ICAModule = ica.NewAppModule(&appKeepers.ICAControllerKeeper, &appKeepers.ICAHostKeeper) + +// Create Interchain Accounts Controller Stack +var icaControllerStack porttypes.IBCModule = icacontroller.NewIBCMiddleware(nil, appKeepers.ICAControllerKeeper) + +// Add Interchain Accounts Controller IBC route +ibcRouter.AddRoute(icacontrollertypes.SubModuleName, icaControllerStack) +``` + +## Consequences + +### Positive + +* Users of the Hub will have a possibility to create and utilize Interchain Accounts on other IBC connected chains. + +### Negative + +### Neutral + +* Since we don't need to implement a custom authentication mechanism, we can rely on the one defined by the Controller module itself, implemented through the `MsgRegisterInterchainAccount` and `MsgSendTx` messages. + +## References + +[Link](https://github.com/cosmos/gaia/issues/2869) diff --git a/hub/v26/architecture/templates/adr-template.mdx b/hub/v26/architecture/templates/adr-template.mdx new file mode 100644 index 000000000..155ddc46e --- /dev/null +++ b/hub/v26/architecture/templates/adr-template.mdx @@ -0,0 +1,54 @@ +{/* order: false */} + +## Changelog + +* {'{'}date{'}'}: {'{'}changelog{'}'} + +## Status + +{'{'}DRAFT | PROPOSED{'}'} Not Implemented + +> Please have a look at the [PROCESS](/hub/v26/architecture/adr/PROCESS#adr-status) page. +> Use DRAFT if the ADR is in a draft stage (draft PR) or PROPOSED if it's in review. + +## Abstract + +> "If you can't explain it simply, you don't understand it well enough." Provide +> a simplified and layman-accessible explanation of the ADR. +> A short (\~200 word) description of the issue being addressed. + +## Context + +> This section contains all the context one needs to understand the current state, and why there is a problem. +> It should be as succinct as possible and introduce the high level idea behind the solution. +> The language in this section is value-neutral. It is simply describing facts. + +## Decision + +> This section explains all of the details of the proposed solution, including implementation details. +> It should also describe affects / corollary items that may need to be changed as a part of this. +> If the proposed change will be large, please also indicate a way to do the change to maximize ease of review. +> (e.g. the optimal split of things to do between separate PR's) + +## Consequences + +> This section describes the consequences, after applying the decision. +> All consequences should be summarized here, not just the "positive" ones. + +### Positive + +> {'{'}positive consequences{'}'} + +### Negative + +> {'{'}negative consequences{'}'} + +### Neutral + +> {'{'}neutral consequences{'}'} + +## References + +> Are there any relevant PR comments, issues that led up to this, or articles referenced for why we made the given design choice? If so link them here! + +* {'{'}reference link{'}'} diff --git a/hub/v26/delegators/README.mdx b/hub/v26/delegators/README.mdx new file mode 100644 index 000000000..2ad0c7c0e --- /dev/null +++ b/hub/v26/delegators/README.mdx @@ -0,0 +1,11 @@ +--- +title: Delegators +description: >- + This folder contains documentation relevant to delegators of the Cosmos Hub + and other gaia blockchains. +--- +This folder contains documentation relevant to delegators of the Cosmos Hub and other `gaia` blockchains. + +* [Delegator CLI Guide](/hub/v26/delegators/delegator-guide-cli) +* [Delegators FAQ](/hub/v26/delegators/delegator-faq) +* [Delegator Security Notice](/hub/v26/delegators/delegator-security) diff --git a/hub/v26/delegators/delegator-faq.mdx b/hub/v26/delegators/delegator-faq.mdx new file mode 100644 index 000000000..96bf125ba --- /dev/null +++ b/hub/v26/delegators/delegator-faq.mdx @@ -0,0 +1,97 @@ +--- +title: Delegator FAQ +--- +## What is a delegator? + +People who cannot or do not want to operate [validator nodes](/hub/v26/validators/overview) can still participate in the staking process as delegators. Indeed, validators are not chosen based on their self-delegated stake but based on their total stake, which is the sum of their self-delegated stake and of the stake that is delegated to them. This is an important property, as it makes delegators a safeguard against validators that exhibit bad behavior. If a validator misbehaves, their delegators will move their Atoms away from them, thereby reducing their stake. Eventually, if a validator's stake falls under the top 180 addresses with highest stake, they will exit the validator set. + +**Delegators share the revenue of their validators, but they also share the risks.** In terms of revenue, validators and delegators differ in that validators can apply a commission on the revenue that goes to their delegator before it is distributed. This commission is known to delegators beforehand and can only change according to predefined constraints (see [section](#choosing-a-validator) below). In terms of risk, delegators' Atoms can be slashed if their validator misbehaves. For more, see [Risks](#risks) section. + +To become delegators, Atom holders need to send a ["Delegate transaction"](/hub/v26/delegators/delegator-guide-cli#sending-transactions) where they specify how many Atoms they want to bond and to which validator. A list of validator candidates will be displayed in Cosmos Hub explorers. Later, if a delegator wants to unbond part or all of their stake, they need to send an "Unbond transaction". From there, the delegator will have to wait 3 weeks to retrieve their Atoms. Delegators can also send a "Rebond Transaction" to switch from one validator to another, without having to go through the 3 weeks waiting period. + +For a practical guide on how to become a delegator, click [here](/hub/v26/delegators/delegator-guide-cli). + +## Choosing a validator + +{/* markdown-link-check-disable-next-line */} +In order to choose their validators, delegators have access to a range of information directly in [Mintscan](https://mintscan.io/cosmos/validators) or other Cosmos block explorers. + +* **Validator's moniker**: Name of the validator candidate. +* **Validator's description**: Description provided by the validator operator. +* **Validator's website**: Link to the validator's website. +* **Initial commission rate**: The commission rate on revenue charged to any delegator by the validator (see below for more detail). +* **Commission max change rate:** The maximum daily increase of the validator's commission. This parameter cannot be changed by the validator operator. +* **Maximum commission:** The maximum commission rate this validator candidate can charge. This parameter cannot be changed by the validator operator. +* **Validator self-bond amount**: A validator with a high amount of self-delegated Atoms has more skin-in-the-game than a validator with a low amount. + +## Directives of delegators + +Being a delegator is not a passive task. Here are the main directives of a delegator: + +* **Perform careful due diligence on validators before delegating.** If a validator misbehaves, part of their total stake, which includes the stake of their delegators, can be slashed. Delegators should therefore carefully select validators they think will behave correctly. +* **Actively monitor their validator after having delegated.** Delegators should ensure that the validators they delegate to behave correctly, meaning that they have good uptime, do not double sign or get compromised, and participate in governance. They should also monitor the commission rate that is applied. If a delegator is not satisfied with its validator, they can unbond or switch to another validator (Note: Delegators do not have to wait for the unbonding period to switch validators. Rebonding takes effect immediately). +* **Participate in governance.** Delegators can and are expected to actively participate in governance. A delegator's voting power is proportional to the size of their bonded stake. If a delegator does not vote, they will inherit the vote of their validator(s). If they do vote, they override the vote of their validator(s). Delegators therefore act as a counterbalance to their validators. + +## Revenue + +Validators and delegators earn revenue in exchange for their services. This revenue is given in three forms: + +* **Block provisions (Atoms):** They are paid in newly created Atoms. Block provisions exist to incentivize Atom holders to stake. The yearly inflation rate is calculated to target 2/3 bonded stake. If the total bonded stake in the network is less than 2/3 of the total Atom supply, inflation increases until it reaches 20%. If the total bonded stake is more than 2/3 of the Atom supply, inflation decreases until it reaches 7%. This means that if total bonded stake stays less than 2/3 of the total Atom supply for a prolonged period of time, unbonded Atom holders can expect their Atom value to deflate by 20% (compounded) per year. +* **Transaction fees (various tokens):** Each transfer on the Cosmos Hub comes with transactions fees. These fees can be paid in any currency that is whitelisted by the Hub's governance. Fees are distributed to bonded Atom holders in proportion to their stake. The first whitelisted token at launch is the ATOM. + +## Validator Commission + +Each validator receives revenue based on their total stake. Before this revenue is distributed to delegators, the validator can apply a commission. In other words, delegators have to pay a commission to their validators on the revenue they earn. Let us look at a concrete example: + +We consider a validator whose stake (i.e. self-delegated stake + delegated stake) is 10% of the total stake of all validators. This validator has 20% self-delegated stake and applies a commission of 10%. Now let us consider a block with the following revenue: + +* 990 Atoms in block provisions +* 10 Atoms in transaction fees. + +This amounts to a total of 1000 Atoms and 100 Photons to be distributed among all staking pools. + +Our validator's staking pool represents 10% of the total stake, which means the pool obtains 100 Atoms and 10 Photons. Now let us look at the internal distribution of revenue: + +* Commission = `10% * 80% * 100` Atoms = 8 Atoms +* Validator's revenue = `20% * 100` Atoms + Commission = 28 Atoms +* Delegators' total revenue = `80% * 100` Atoms - Commission = 72 Atoms + +Then, each delegator in the staking pool can claim their portion of the delegators' total revenue. + +## Liquid Staking + +The Liquid Staking module enacts a safety framework and associated governance-controlled parameters to regulate the adoption of liquid staking. + +The LSM mitigates liquid staking risks by limiting the total amount of ATOM that can be liquid staked to a percentage of all staked ATOM. As an additional risk-mitigation feature, the LSM introduces a requirement that validators self-bond ATOM to be eligible for delegations from liquid staking providers or to be eligible to mint LSM tokens. This mechanism is called the “validator bond”, and is technically distinct from the current self-bond mechanism, but functions similarly. + +At the same time, the LSM introduces the ability for staked ATOM to be instantly liquid staked, without having to wait for the unbonding period. + +The LSM enables users to instantly liquid stake their staked ATOM, without having to wait the twenty-one day unbonding period. This is important, because a very large portion of the ATOM supply is currently staked. Liquid staking ATOM that is already staked incurs a switching cost in the form of three weeks’ forfeited staking rewards. The LSM eliminates this switching cost. + +A user would be able to visit any liquid staking provider that has integrated with the LSM and click a button to convert her staked ATOM to liquid staked ATOM. It would be as easy as liquid staking unstaked ATOM. + +Technically speaking, this is accomplished by using something called an “LSM share.” Using the liquid staking module, a user can tokenize their staked ATOM and turn it into LSM shares. LSM shares can be redeemed for underlying staked tokens and are transferable. After staked ATOM is tokenized it can be immediately transferred to a liquid staking provider in exchange for liquid staking tokens - without having to wait for the unbonding period. + +### Toggling the ability to tokenize shares + +Currently the liquid staking module facilitates the immediate conversion of staked assets into liquid staked tokens. Despite the many benefits that come with this capability, it does inadvertently negate a protective measure available via traditional staking, where an account can stake their tokens to render them illiquid in the event that their wallet is compromised (the attacker would first need to unbond, then transfer out the tokens). + +Tokenization obviates this potential recovery measure, as an attacker could tokenize and immediately transfer staked tokens to another wallet. So, as an additional protective measure, the staking module permit accounts to selectively disable the tokenization of their stake with the `DisableTokenizeShares` message. + +The `DisableTokenizeShares` message is exposed by the staking module and can be executed as follows: + +```sh +gaiad tx staking disable-tokenize-shares --from mykey +``` + +When tokenization is disabled, a lock is placed on the account, effectively preventing the tokenization of any delegations. Re-enabling tokenization would initiate the removal of the lock, but the process is not immediate. The lock removal is queued, with the lock itself persisting throughout the unbonding period. Following the completion of the unbonding period, the lock would be completely removed, restoring the account's ability to tokenize. For liquid staking protocols that enable the lock, this delay better positions the base layer to coordinate a recovery in the event of an exploit. + +## Risks + +Staking Atoms is not free of risk. First, staked Atoms are locked up, and retrieving them requires a 3 week waiting period called unbonding period. Additionally, if a validator misbehaves, a portion of their total stake can be slashed (i.e. destroyed). This includes the stake of their delegators. + +There is one main slashing condition: + +* **Double signing:** If someone reports on that a validator signed two different blocks with the same chain ID at the same height, this validator will get slashed. + +This is why Atom holders should perform careful due diligence on validators before delegating. It is also important that delegators actively monitor the activity of their validators. If a validator behaves suspiciously or is too often offline, delegators can choose to unbond from them or switch to another validator. **Delegators can also mitigate risk by distributing their stake across multiple validators.** diff --git a/hub/v26/delegators/delegator-guide-cli.mdx b/hub/v26/delegators/delegator-guide-cli.mdx new file mode 100644 index 000000000..ef291f01d --- /dev/null +++ b/hub/v26/delegators/delegator-guide-cli.mdx @@ -0,0 +1,545 @@ +--- +title: Delegator Guide (CLI) +description: >- + This document contains all the necessary information for delegators to + interact with the Cosmos Hub through the Command-Line Interface (CLI). +--- +This document contains all the necessary information for delegators to interact with the Cosmos Hub through the Command-Line Interface (CLI). + +It also contains instructions on how to manage accounts, restore accounts from the fundraiser and use a ledger nano device. + + +**Very Important**: Please assure that you follow the steps described hereinafter +carefully, as negligence in this significant process could lead to an indefinite +loss of your Atoms. Therefore, read through the following instructions in their +entirety prior to proceeding and reach out to us in case you need support. + +Please also note that you are about to interact with the Cosmos Hub, a +blockchain technology containing highly experimental software. While the +blockchain has been developed in accordance to the state of the art and audited +with utmost care, we can nevertheless expect to have issues, updates and bugs. +Furthermore, interaction with blockchain technology requires +advanced technical skills and always entails risks that are outside our control. +By using the software, you confirm that you understand the inherent risks +associated with cryptographic software (see also risk section of the +[Interchain Cosmos Contribution terms](https://github.com/cosmos/cosmos/blob/master/fundraiser/Interchain%20Cosmos%20Contribution%20Terms%20-%20FINAL.pdf)) and that the Interchain Foundation and/or +the Tendermint Team may not be held liable for potential damages arising out of the use of the +software. Any use of this open source software released under the Apache 2.0 license is +done at your own risk and on a "AS IS" basis, without warranties or conditions +of any kind. + + +Please exercise extreme caution! + +## Table of Contents + +* [Table of Contents](#table-of-contents) +* [Installing `gaiad`](#installing-gaiad) +* [Cosmos Accounts](#cosmos-accounts) + * [Restoring an Account from the Fundraiser](#restoring-an-account-from-the-fundraiser) + * [On a Ledger Device](#on-a-ledger-device) + * [On a Computer](#on-a-computer) + * [Creating an Account](#creating-an-account) + * [Using a Ledger Device](#using-a-ledger-device) + * [Using a Computer](#using-a-computer) +* [Accessing the Cosmos Hub Network](#accessing-the-cosmos-hub-network) + * [Running Your Own Full-Node](#running-your-own-full-node) + * [Connecting to a Remote Full-Node](#connecting-to-a-remote-full-node) +* [Setting Up `gaiad`](#setting-up-gaiad) +* [Querying the State](#querying-the-state) +* [Sending Transactions](#sending-transactions) + * [A Note on Gas and Fees](#a-note-on-gas-and-fees) + * [Sending Tokens](#sending-tokens) + * [Bonding Atoms and Withdrawing Rewards](#bonding-atoms-and-withdrawing-rewards) +* [Participating in Governance](#participating-in-governance) + * [Primer on Governance](#primer-on-governance) + * [In Practice](#in-practice) + * [Signing Transactions From an Offline Computer](#signing-transactions-from-an-offline-computer) + +## Installing `gaiad` + +`gaiad`: This is the command-line interface to interact with a `gaiad` full-node. + + +**Please check that you download the latest stable release of `gaiad` that is available** + + +\[**Download the binaries**] +Not available yet. + +[**Install from source**](/hub/v26/getting-started/installation) + + +`gaiad` is used from a terminal. To open the terminal, follow these steps: + +* **Windows**: `Start` > `All Programs` > `Accessories` > `Command Prompt` +* **MacOS**: `Finder` > `Applications` > `Utilities` > `Terminal` +* **Linux**: `Ctrl` + `Alt` + `T` + + +## Cosmos Accounts + +At the core of every Cosmos account, there is a seed, which takes the form of a 12 or 24-words mnemonic. From this mnemonic, it is possible to create any number of Cosmos accounts, i.e. pairs of private key/public key. This is called an HD wallet (see [BIP32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki) for more information on the HD wallet specification). + +```txt expandable + Account 0 Account 1 Account 2 + ++------------------+ +------------------+ +------------------+ +| | | | | | +| Address 0 | | Address 1 | | Address 2 | +| ^ | | ^ | | ^ | +| | | | | | | | | +| | | | | | | | | +| | | | | | | | | +| + | | + | | + | +| Public key 0 | | Public key 1 | | Public key 2 | +| ^ | | ^ | | ^ | +| | | | | | | | | +| | | | | | | | | +| | | | | | | | | +| + | | + | | + | +| Private key 0 | | Private key 1 | | Private key 2 | +| ^ | | ^ | | ^ | ++------------------+ +------------------+ +------------------+ + | | | + | | | + | | | + +--------------------------------------------------------------------+ + | + | + +---------+---------+ + | | + | Mnemonic (Seed) | + | | + +-------------------+ +``` + +The funds stored in an account are controlled by the private key. This private key is generated using a one-way function from the mnemonic. If you lose the private key, you can retrieve it using the mnemonic. However, if you lose the mnemonic, you will lose access to all the derived private keys. Likewise, if someone gains access to your mnemonic, they gain access to all the associated accounts. + + +**Do not lose or share your 12 words with anyone. To prevent theft or loss of funds, it is best to ensure that you keep multiple copies of your mnemonic, and store it in a safe, secure place and that only you know how to access. If someone is able to gain access to your mnemonic, they will be able to gain access to your private keys and control the accounts associated with them.** + + +The address is a public string with a human-readable prefix (e.g. `cosmos10snjt8dmpr5my0h76xj48ty80uzwhraqalu4eg`) that identifies your account. When someone wants to send you funds, they send it to your address. It is computationally infeasible to find the private key associated with a given address. + +### Restoring an Account from the Fundraiser + + +*NOTE: This section only concerns fundraiser participants* + + +If you participated in the fundraiser, you should be in possession of a 12-words mnemonic. Newly generated mnemonics use 24 words, but 12-word mnemonics are also compatible with all the Cosmos tools. + +#### On a Ledger Device + +At the core of a ledger device, there is a mnemonic used to generate accounts on multiple blockchains (including the Cosmos Hub). Usually, you will create a new mnemonic when you initialize your ledger device. However, it is possible to tell the ledger device to use a mnemonic provided by the user instead. Let us go ahead and see how you can input the mnemonic you obtained during the fundraiser as the seed of your ledger device. + + +*NOTE: To do this, **it is preferable to use a brand new ledger device.**. Indeed, there can be only one mnemonic per ledger device. If, however, you want to use a ledger that is already initialized with a seed, you can reset it by going in `Settings`>`Device`>`Reset All`. **Please note that this will wipe out the seed currently stored on the device. If you have not properly secured the associated mnemonic, you could lose your funds!!!*** + + +The following steps need to be performed on an un-initialized ledger device: + +1. Connect your ledger device to the computer via USB +2. Press both buttons +3. Do **NOT** choose the "Config as a new device" option. Instead, choose "Restore Configuration" +4. Choose a PIN +5. Choose the 12 words option +6. Input each of the words you got during the fundraiser, in the correct order. + +Your ledger is now correctly set up with your fundraiser mnemonic! Do not lose this mnemonic! If your ledger is compromised, you can always restore a new device again using the same mnemonic. + +Next, click [here](#using-a-ledger-device) to learn how to generate an account. + +#### On a Computer + + +**NOTE: It is more secure to perform this action on an offline computer** + + +To restore an account using a fundraiser mnemonic and store the associated encrypted private key on a computer, use the following command: + +```bash +gaiad keys add --recover +``` + +* `` is the name of the account. It is a reference to the account number used to derive the key pair from the mnemonic. You will use this name to identify your account when you want to send a transaction. +* You can add the optional `--account` flag to specify the path (`0`, `1`, `2`, ...) you want to use to generate your account. By default, account `0` is generated. + +The private key of account `0` will be saved in your operating system's credentials storage. +Each time you want to send a transaction, you will need to unlock your system's credentials store. +If you lose access to your credentials storage, you can always recover the private key with the +mnemonic. + + +**You may not be prompted for password each time you send a transaction since most operating systems +unlock user's credentials store upon login by default. If you want to change your credentials +store security policies please refer to your operating system manual.** + + +### Creating an Account + +To create an account, you just need to have `gaiad` installed. Before creating it, you need to know where you intend to store and interact with your private keys. The best options are to store them in an offline dedicated computer or a ledger device. Storing them on your regular online computer involves more risk, since anyone who infiltrates your computer through the internet could exfiltrate your private keys and steal your funds. + +#### Using a Ledger Device + + +**Only use Ledger devices that you bought factory new or trust fully** + + +When you initialize your ledger, a 24-word mnemonic is generated and stored in the device. This mnemonic is compatible with Cosmos and Cosmos accounts can be derived from it. Therefore, all you have to do is make your ledger compatible with `gaiad`. To do so, you need to go through the following steps: + +1. Download the Ledger Live app [here](https://www.ledger.com/ledger-live). +2. Connect your ledger via USB and update to the latest firmware +3. Go to the ledger live app store, and download the "Cosmos" application (this can take a while). **Note: You may have to enable `Dev Mode` in the `Settings` of Ledger Live to be able to download the "Cosmos" application**. +4. Navigate to the Cosmos app on your ledger device + +Then, to create an account, use the following command: + +```bash +gaiad keys add --ledger +``` + + +**This command will only work while the Ledger is plugged in and unlocked** + + +* `` is the name of the account. It is a reference to the account number used to derive the key pair from the mnemonic. You will use this name to identify your account when you want to send a transaction. +* You can add the optional `--account` flag to specify the path (`0`, `1`, `2`, ...) you want to use to generate your account. By default, account `0` is generated. + +#### Using a Computer + + +**NOTE: It is more secure to perform this action on an offline computer** + + +To generate an account, just use the following command: + +```bash +gaiad keys add +``` + +The command will generate a 24-words mnemonic and save the private and public keys for account `0` +at the same time. +Each time you want to send a transaction, you will need to unlock your system's credentials store. +If you lose access to your credentials storage, you can always recover the private key with the +mnemonic. + + +**You may not be prompted for password each time you send a transaction since most operating systems +unlock user's credentials store upon login by default. If you want to change your credentials +store security policies please refer to your operating system manual.** + + + +**Do not lose or share your 12 words with anyone. To prevent theft or loss of funds, it is best to ensure that you keep multiple copies of your mnemonic, and store it in a safe, secure place and that only you know how to access. If someone is able to gain access to your mnemonic, they will be able to gain access to your private keys and control the accounts associated with them.** + + + +After you have secured your mnemonic (triple check!), you can delete bash history to ensure no one can retrieve it: + +```bash +history -c +rm ~/.bash_history +``` + + + +* `` is the name of the account. It is a reference to the account number used to derive the key pair from the mnemonic. You will use this name to identify your account when you want to send a transaction. +* You can add the optional `--account` flag to specify the path (`0`, `1`, `2`, ...) you want to use to generate your account. By default, account `0` is generated. + +You can generate more accounts from the same mnemonic using the following command: + +```bash +gaiad keys add --recover --account 1 +``` + +This command will prompt you to input a passphrase as well as your mnemonic. Change the account number to generate a different account. + +## Accessing the Cosmos Hub Network + +In order to query the state and send transactions, you need a way to access the network. To do so, you can either run your own full-node, or connect to someone else's. + + +**NOTE: Do not share your mnemonic (12 or 24 words) with anyone. The only person who should ever need to know it is you. This is especially important if you are ever approached via email or direct message by someone requesting that you share your mnemonic for any kind of blockchain services or support. No one from Cosmos, the Tendermint team or the Interchain Foundation will ever send an email that asks for you to share any kind of account credentials or your mnemonic."**. + + +### Running Your Own Full-Node + +This is the most secure option, but comes with relatively high resource requirements. In order to run your own full-node, you need good bandwidth and at least 1TB of disk space. + +You will find the tutorial on how to install `gaiad` [here](/hub/v26/getting-started/installation), and the guide to run a full-node [here](/hub/v26/hub-tutorials/join-mainnet). + +### Connecting to a Remote Full-Node + +If you do not want or cannot run your own node, you can connect to someone else's full-node. You should pick an operator you trust, because a malicious operator could return incorrect query results or censor your transactions. However, they will never be able to steal your funds, as your private keys are stored locally on your computer or ledger device. Possible options of full-node operators include validators, wallet providers or exchanges. + +In order to connect to the full-node, you will need an address of the following form: `https://77.87.106.33:26657` (*Note: This is a placeholder*). This address has to be communicated by the full-node operator you choose to trust. You will use this address in the [following section](#setting-up-gaiad). + +## Setting Up `gaiad` + + +**Before setting up `gaiad`, make sure you have set up a way to [access the Cosmos Hub network](#accessing-the-cosmos-hub-network)** + + + +**Please check that you are always using the latest stable release of `gaiad`** + + +`gaiad` is the tool that enables you to interact with the node that runs on the Cosmos Hub network, whether you run it yourself or not. Let us set it up properly. + +In order to set up `gaiad`, use the following command: + +```bash +gaiad config +``` + +It allows you to set a default value for each given flag. + +First, set up the address of the full-node you want to connect to: + +```bash +gaiad config node : +**Before you can bond atoms and withdraw rewards, you need to [set up `gaiad`](#setting-up-gaiad)** + + +`gaiad` lets you query all relevant information from the blockchain, like account balances, amount of bonded tokens, outstanding rewards, governance proposals and more. Next is a list of the most useful commands for delegator. + +```bash expandable +// query account balances and other account-related information +gaiad query account + +// query the list of validators +gaiad query staking validators + +// query the information of a validator given their address (e.g. cosmosvaloper1n5pepvmgsfd3p2tqqgvt505jvymmstf6s9gw27) +gaiad query staking validator + +// query all delegations made from a delegator given their address (e.g. cosmos10snjt8dmpr5my0h76xj48ty80uzwhraqalu4eg) +gaiad query staking delegations + +// query a specific delegation made from a delegator (e.g. cosmos10snjt8dmpr5my0h76xj48ty80uzwhraqalu4eg) to a validator (e.g. cosmosvaloper1n5pepvmgsfd3p2tqqgvt505jvymmstf6s9gw27) given their addresses +gaiad query staking delegation + +// query the rewards of a delegator given a delegator address (e.g. cosmos10snjt8dmpr5my0h76xj48ty80uzwhraqalu4eg) +gaiad query distribution rewards + +// query all proposals currently open for depositing +gaiad query gov proposals --status deposit_period + +// query all proposals currently open for voting +gaiad query gov proposals --status voting_period + +// query a proposal given its proposalID +gaiad query gov proposal +``` + +For more commands, just type: + +```bash +gaiad query +``` + +For each command, you can use the `-h` or `--help` flag to get more information. + +## Sending Transactions + + +On Cosmos Hub mainnet, the accepted denom is `uatom`, where `1atom = 1,000,000uatom` + + +### A Note on Gas and Fees + +Transactions on the Cosmos Hub network need to include a transaction fee in order to be processed. This fee pays for the gas required to run the transaction. The formula is the following: + +```js +fees = ceil(gas * gasPrices) +``` + +The `gas` is dependent on the transaction. Different transaction require different amount of `gas`. The `gas` amount for a transaction is calculated as it is being processed, but there is a way to estimate it beforehand by using the `auto` value for the `gas` flag. Of course, this only gives an estimate. You can adjust this estimate with the flag `--gas-adjustment` (default `1.0`) if you want to be sure you provide enough `gas` for the transaction. For the remainder of this tutorial, we will use a `--gas-adjustment` of `1.5`. + +The `gasPrice` is the price of each unit of `gas`. Each validator sets a `min-gas-price` value, and will only include transactions that have a `gasPrice` greater than their `min-gas-price`. + +The transaction `fees` are the product of `gas` and `gasPrice`. As a user, you have to input 2 out of 3. The higher the `gasPrice`/`fees`, the higher the chance that your transaction will get included in a block. + + +For mainnet, the recommended `gas-prices` is `0.0025uatom`. + + +### Sending Tokens + + +**Before you can bond atoms and withdraw rewards, you need to [set up `gaiad`](#setting-up-gaiad) and [create an account](#creating-an-account)** + + + +**Note: These commands need to be run on an online computer. It is more secure to perform them commands using a Ledger Nano S device. For the offline procedure, click [here](#signing-transactions-from-an-offline-computer).** + + +```bash +// Send a certain amount of tokens to an address +// Ex value for parameters (do not actually use these values in your tx!!): =cosmos16m93fezfiezhvnjajzrfyszml8qm92a0w67ntjhd3d0 =1000000uatom +// Ex value for flags: =0.0025uatom + +gaiad tx bank send [from_key_or_address] [to_address] [amount] [flags] +``` + +### Bonding Atoms and Withdrawing Rewards + + +**Before you can bond atoms and withdraw rewards, you need to [set up `gaiad`](#setting-up-gaiad) and [create an account](#creating-an-account)** + + + +**Before bonding Atoms, please read the [delegator faq](/hub/v26/delegators/delegator-faq) to understand the risk and responsibilities involved with delegating** + + + +**Note: These commands need to be run on an online computer. It is more secure to perform them commands using a ledger device. For the offline procedure, click [here](#signing-transactions-from-an-offline-computer).** + + +```bash expandable +// Bond a certain amount of Atoms to a given validator +// ex value for flags: =cosmosvaloper18thamkhnj9wz8pa4nhnp9rldprgant57pk2m8s, =10000000uatom, =0.0025uatom + +gaiad tx staking delegate --from --gas auto --gas-adjustment 1.5 --gas-prices + +// Redelegate a certain amount of Atoms from a validator to another +// Can only be used if already bonded to a validator +// Redelegation takes effect immediately, there is no waiting period to redelegate +// After a redelegation, no other redelegation can be made from the account for the next 3 weeks +// ex value for flags: =cosmosvaloper18thamkhnj9wz8pa4nhnp9rldprgant57pk2m8s, =100000000uatom, =0.0025uatom + +gaiad tx staking redelegate --from --gas auto --gas-adjustment 1.5 --gas-prices + +// Withdraw all rewards +// ex value for flag: =0.0025uatom + +gaiad tx distribution withdraw-all-rewards --from --gas auto --gas-adjustment 1.5 --gas-prices + +// Unbond a certain amount of Atoms from a given validator +// You will have to wait 3 weeks before your Atoms are fully unbonded and transferrable +// ex value for flags: =cosmosvaloper18thamkhnj9wz8pa4nhnp9rldprgant57pk2m8s, =10000000uatom, =0.0025uatom + +gaiad tx staking unbond --from --gas auto --gas-adjustment 1.5 --gas-prices +``` + + +**If you use a connected Ledger, you will be asked to confirm the transaction on the device before it is signed and broadcast to the network. Note that the command will only work while the Ledger is plugged in and unlocked.** + + +To confirm that your transaction went through, you can use the following queries: + +```bash +// your balance should change after you bond Atoms or withdraw rewards +gaiad query account + +// you should have delegations after you bond Atom +gaiad query staking delegations + +// this returns your tx if it has been included +// use the tx hash that was displayed when you created the tx +gaiad query tx + +``` + +Double check with a block explorer if you interact with the network through a trusted full-node. + +## Participating in Governance + +### Primer on Governance + +The Cosmos Hub has a built-in governance system that lets bonded Atom holders vote on proposals. There are three types of proposal: + +* `Text Proposals`: These are the most basic type of proposals. They can be used to get the opinion of the network on a given topic. +* `Parameter Proposals`: These are used to update the value of an existing parameter. +* `Software Upgrade Proposal`: These are used to propose an upgrade of the Hub's software. + +Any Atom holder can submit a proposal. In order for the proposal to be open for voting, it needs to come with a `deposit` that is greater than a parameter called `minDeposit`. The `deposit` need not be provided in its entirety by the submitter. If the initial proposer's `deposit` is not sufficient, the proposal enters the `deposit_period` status. Then, any Atom holder can increase the deposit by sending a `depositTx`. + +Once the `deposit` reaches `minDeposit`, the proposal enters the `voting_period`, which lasts 2 weeks. Any **bonded** Atom holder can then cast a vote on this proposal. The options are `Yes`, `No`, `NoWithVeto` and `Abstain`. The weight of the vote is based on the amount of bonded Atoms of the sender. If they don't vote, delegator inherit the vote of their validator. However, delegators can override their validator's vote by sending a vote themselves. + +At the end of the voting period, the proposal is accepted if there are more than 50% `Yes` votes (excluding `Abstain` votes) and less than 33.33% of `NoWithVeto` votes (excluding `Abstain` votes). + +### In Practice + + +**Before you can bond atoms and withdraw rewards, you need to [bond Atoms](#bonding-atoms-and-withdrawing-rewards)** + + + +**Note: These commands need to be run on an online computer. It is more secure to perform them commands using a ledger device. For the offline procedure, click [here](#signing-transactions-from-an-offline-computer).** + + +```bash expandable +// Submit a Proposal +// =text/parameter_change/software_upgrade +// ex value for flag: =0.0025uatom + +// the proposal must meet the minimum deposit amount - please check the current chain params +gaiad tx gov submit-legacy-proposal --title "Test Text Proposal" --description "My awesome proposal" --type "text" --deposit=10000000uatom --gas auto --gas-adjustment 1.5 --gas-prices --from + +// Increase deposit of a proposal +// Retrieve proposalID from $gaiad query gov proposals --status deposit_period +// ex value for parameter: =10000000uatom + +gaiad tx gov deposit --gas auto --gas-adjustment 1.5 --gas-prices --from + +// Vote on a proposal +// Retrieve proposalID from $gaiad query gov proposals --status voting_period +//