Page Not Found
We could not find what you were looking for.
Please contact the owner of the site that linked you to the original URL and let them know their link is broken.
We could not find what you were looking for.
Please contact the owner of the site that linked you to the original URL and let them know their link is broken.
MinimumGasPricesParam",id:"zerocoins-in-minimumgaspricesparam",level:3},{value:"Coins Split",id:"coins-split",level:4},{value:"Fee Checks",id:"fee-checks",level:4},{value:"Bypass Message Types",id:"bypass-message-types",level:3},{value:"Fee Checks in DeliverTx",id:"fee-checks-in--delivertx",level:3},{value:"Consequences",id:"consequences",level:2},{value:"Positive",id:"positive",level:3},{value:"Negative",id:"negative",level:3},{value:"References",id:"references",level:2}],p={toc:m},d="wrapper";function c(e){let{components:n,...o}=e;return(0,a.yg)(d,(0,i.A)({},p,o,{components:n,mdxType:"MDXLayout"}),(0,a.yg)("h1",{id:"adr-002-globalfee-module"},"ADR 002: Globalfee Module"),(0,a.yg)("h2",{id:"changelog"},"Changelog"),(0,a.yg)("ul",null,(0,a.yg)("li",{parentName:"ul"},"2023-06-12: Initial Draft"),(0,a.yg)("li",{parentName:"ul"},"2024-06-06: Change status to deprecated")),(0,a.yg)("h2",{id:"status"},"Status"),(0,a.yg)("p",null,"Deprecated"),(0,a.yg)("h2",{id:"context"},"Context"),(0,a.yg)("p",null,"The globalfee module was created to manage a parameter called ",(0,a.yg)("inlineCode",{parentName:"p"},"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:"),(0,a.yg)("ul",null,(0,a.yg)("li",{parentName:"ul"},(0,a.yg)("p",{parentName:"li"},"In the globalfee module, several Cosmos SDK coins methods were redefined because of the allowance of zero-value coins in the ",(0,a.yg)("inlineCode",{parentName:"p"},"MinimumGasPricesParam"),". The ",(0,a.yg)("inlineCode",{parentName:"p"},"MinimumGasPricesParam")," is of ",(0,a.yg)("inlineCode",{parentName:"p"},"sdk.DecCoins")," type. In the Cosmos SDK, ",(0,a.yg)("inlineCode",{parentName:"p"},"sdk.DecCoins")," are ",(0,a.yg)("a",{parentName:"p",href:"https://github.com/cosmos/cosmos-sdk/blob/67f04e629623d4691c4b2e48806f7793a3aa211e/types/dec_coin.go#L160-L177"},"sanitized")," to remove zero-value coins. As a result, several methods from ",(0,a.yg)("inlineCode",{parentName:"p"},"sdk.Coins")," were ",(0,a.yg)("a",{parentName:"p",href:"https://github.com/cosmos/gaia/blob/890ab3aa2e5788537b0d2ebc9bafdc968340e0e5/x/globalfee/ante/fee_utils.go#L46-L104"},"redefined in the Gaia fee antehandler"),".")),(0,a.yg)("li",{parentName:"ul"},(0,a.yg)("p",{parentName:"li"},(0,a.yg)("inlineCode",{parentName:"p"},"BypassMinFeeMsgTypes")," exists in ",(0,a.yg)("inlineCode",{parentName:"p"},"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.")),(0,a.yg)("li",{parentName:"ul"},(0,a.yg)("p",{parentName:"li"},"The fee check logic is only executed in ",(0,a.yg)("inlineCode",{parentName:"p"},"CheckTx"),". This could enable malicious validators to change the fee check code and propose transactions that do not meet the fee requirement."))),(0,a.yg)("h2",{id:"decision"},"Decision"),(0,a.yg)("p",null,"To fix these problems, the following changes are added to the globalfee module:"),(0,a.yg)("ul",null,(0,a.yg)("li",{parentName:"ul"},(0,a.yg)("strong",{parentName:"li"},"ZeroCoins in ",(0,a.yg)("inlineCode",{parentName:"strong"},"MinimumGasPricesParam"),":"),"\\\nRefactor the fee check logics, in order to use the Cosmos SDK coins' methods instead of the redefined methods."),(0,a.yg)("li",{parentName:"ul"},(0,a.yg)("strong",{parentName:"li"},"Bypass Message Types:"),"\\\n",(0,a.yg)("inlineCode",{parentName:"li"},"BypassMinFeeMsgTypes")," is refactored to be a param of the globalfee module, in order to make the bypass messages deterministic."),(0,a.yg)("li",{parentName:"ul"},(0,a.yg)("strong",{parentName:"li"},"Check Fees in ",(0,a.yg)("inlineCode",{parentName:"strong"},"DeliverTx"),":"),"\\\nThe fee check is factored to executed in both ",(0,a.yg)("inlineCode",{parentName:"li"},"DeliverTx")," and ",(0,a.yg)("inlineCode",{parentName:"li"},"CheckTx"),". This is to prevent malicious validators from changing the fee check logic and allowing any transactions to pass fee check. As a consequence, ",(0,a.yg)("inlineCode",{parentName:"li"},"MinimumGasPricesParam")," is introduced as a globalfee param.")),(0,a.yg)("h3",{id:"zerocoins-in-minimumgaspricesparam"},"ZeroCoins in ",(0,a.yg)("inlineCode",{parentName:"h3"},"MinimumGasPricesParam")),(0,a.yg)("h4",{id:"coins-split"},"Coins Split"),(0,a.yg)("p",null,(0,a.yg)("inlineCode",{parentName:"p"},"CombinedFeeRequirement")," refers to the fee requirement that takes into account both ",(0,a.yg)("inlineCode",{parentName:"p"},"globalFees")," (",(0,a.yg)("inlineCode",{parentName:"p"},"MinimumGasPricesParam")," in the globalfee module) and ",(0,a.yg)("inlineCode",{parentName:"p"},"localFees")," (",(0,a.yg)("inlineCode",{parentName:"p"},"minimum-gas-prices")," in ",(0,a.yg)("inlineCode",{parentName:"p"},"app.toml"),"). This requirement is calculated as the maximum value between ",(0,a.yg)("inlineCode",{parentName:"p"},"globalFees")," and ",(0,a.yg)("inlineCode",{parentName:"p"},"localFees")," for denomination exists ",(0,a.yg)("inlineCode",{parentName:"p"},"globalFees"),".\nThe allowance of zero coins in the ",(0,a.yg)("inlineCode",{parentName:"p"},"MinimumGasPricesParam")," within the globalfee module implies that ",(0,a.yg)("inlineCode",{parentName:"p"},"CombinedFeeRequirement(globalFees, localFees)")," also permits zero coins. Therefore, the ",(0,a.yg)("inlineCode",{parentName:"p"},"CombinedFeeRequirement")," doesn't meet the requirements of certain ",(0,a.yg)("inlineCode",{parentName:"p"},"sdk.Coins")," methods. For instance, the ",(0,a.yg)("inlineCode",{parentName:"p"},"DenomsSubsetOf")," method requires coins that do not contain zero coins."),(0,a.yg)("p",null,"To address this issue, the ",(0,a.yg)("inlineCode",{parentName:"p"},"CombinedFeeRequirement")," and ",(0,a.yg)("inlineCode",{parentName:"p"},"feeCoins")," are split as shown in the chart below."),(0,a.yg)("pre",null,(0,a.yg)("code",{parentName:"pre",className:"language-mermaid"},"---\ntitle: Fee Requirements and Fee Splits\n---\nflowchart TD\n subgraph feeReq\n A[CombinedFeeRequirement]--\x3eB[/Split zero/nonzero coins/]\n B--\x3e|zero coins| C[zeroCoinFeesDenomReq];\n B--\x3e|nonzero coins| D[nonzeroCoinFeesDenomReq];\n\n end\n\n subgraph feeCoin\n E[feeCoins]--\x3eF[/Split by the denoms in zero/nonzero CoinFeesDenomReq/]\n F--\x3e|denoms in zeroCoinFeesDenomReq set| G[feeCoinsZeroDenom]\n F--\x3e|denoms in nonzeroCoinFeesDenomReq set| H[feeCoinsNonZeroDenom]\n end\n")),(0,a.yg)("p",null,"The ",(0,a.yg)("inlineCode",{parentName:"p"},"CombinedFeeRequirement")," is split into zero and non-zero coins, forming ",(0,a.yg)("inlineCode",{parentName:"p"},"nonZeroCoinFeesReq")," and ",(0,a.yg)("inlineCode",{parentName:"p"},"zeroCoinFeesDenomReq"),". Similarly, the paid fees (feeCoins) are split into ",(0,a.yg)("inlineCode",{parentName:"p"},"feeCoinsNonZeroDenom")," and ",(0,a.yg)("inlineCode",{parentName:"p"},"feeCoinsZeroDenom"),", based on the denominations of ",(0,a.yg)("inlineCode",{parentName:"p"},"nonZeroCoinFeesReq")," and ",(0,a.yg)("inlineCode",{parentName:"p"},"zeroCoinFeesDenomReq")," as shown in the following code snippet."),(0,a.yg)("pre",null,(0,a.yg)("code",{parentName:"pre",className:"language-go"}," nonZeroCoinFeesReq, zeroCoinFeesDenomReq := getNonZeroFees(feeRequired)\n\n // feeCoinsNonZeroDenom contains non-zero denominations from the feeRequired\n // feeCoinsNonZeroDenom is used to check if the fees meets the requirement imposed by nonZeroCoinFeesReq\n // when feeCoins does not contain zero coins' denoms in feeRequired\n feeCoinsNonZeroDenom, feeCoinsZeroDenom := splitCoinsByDenoms(feeCoins, zeroCoinFeesDenomReq)\n\n")),(0,a.yg)("h4",{id:"fee-checks"},"Fee Checks"),(0,a.yg)("p",null,"The Workflow of feeCheck is shown below:"),(0,a.yg)("pre",null,(0,a.yg)("code",{parentName:"pre",className:"language-mermaid"},"---\ntitle: Fee Check\n---\nflowchart TD\n\nA[feeCoinsNonZeroDenom]--\x3eB[/DenomsSubsetOf_nonZeroCoinFeesReq/];\nB--\x3e|yes|C[is_bypass_msg];\nB--\x3e|no|D((reject));\n\nC--\x3e|yes|pass1((pass));\nC--\x3e|no|D[/contain_zeroCoinFeesDenomReq_denom/];\n\nD--\x3e|yes|pass2((pass));\nD--\x3e|no|E[/feeCoinsZeroDenom_nonEmpty/];\n\n\nE--\x3e|yes|pass3((pass));\nE--\x3e|no|F[/IsAnyGTE_nonZeroCoinFeesDenomReq/];\n\nF--\x3e|yes|pass4((pass));\nF--\x3e|no|reject2((reject));\n")),(0,a.yg)("p",null,"The split enable checking ",(0,a.yg)("inlineCode",{parentName:"p"},"feeCoinsNonZeroDenom")," against ",(0,a.yg)("inlineCode",{parentName:"p"},"nonZeroCoinFeesReq"),", and ",(0,a.yg)("inlineCode",{parentName:"p"},"feeCoinsZeroDenom")," against\n",(0,a.yg)("inlineCode",{parentName:"p"},"zeroCoinFeesDenomReq")," (as shown in the following code snippet). In the check of ",(0,a.yg)("inlineCode",{parentName:"p"},"feeCoinsNonZeroDenom")," against ",(0,a.yg)("inlineCode",{parentName:"p"},"nonZeroCoinFeesReq"),", the Cosmos SDK coins' methods can be used since zero coins are removed from the ",(0,a.yg)("inlineCode",{parentName:"p"},"nonZeroCoinFeesReq"),", while in the check ",(0,a.yg)("inlineCode",{parentName:"p"},"feeCoinsZeroDenom")," against ",(0,a.yg)("inlineCode",{parentName:"p"},"zeroCoinFeesDenomReq"),", only denoms need to be checked."),(0,a.yg)("p",null,"Checking ",(0,a.yg)("inlineCode",{parentName:"p"},"feeCoinsNonZeroDenom")," against ",(0,a.yg)("inlineCode",{parentName:"p"},"nonZeroCoinFeesReq"),":"),(0,a.yg)("pre",null,(0,a.yg)("code",{parentName:"pre",className:"language-go"},' if !feeCoinsNonZeroDenom.IsAnyGTE(nonZeroCoinFeesReq) {\n return ctx, sdkerrors.Wrapf(sdkerrors.ErrInsufficientFee, "insufficient fees; got: %s required: %s", feeCoins.String(), feeRequired.String())\n }\n')),(0,a.yg)("p",null,"Here is an example of how the coins split and checked in fee antehandler:"),(0,a.yg)("p",null,(0,a.yg)("strong",{parentName:"p"},"assumption"),":"),(0,a.yg)("p",null,(0,a.yg)("inlineCode",{parentName:"p"},"globalfee=[1photon, 0uatom, 1stake]")," and ",(0,a.yg)("inlineCode",{parentName:"p"},"local min-gas-prices=[0.5stake]")),(0,a.yg)("p",null,(0,a.yg)("strong",{parentName:"p"},"fee requirement"),":"),(0,a.yg)("p",null,(0,a.yg)("inlineCode",{parentName:"p"},"combinedFeeRequirement=[1photon, 0uatom, 1stake]")),(0,a.yg)("p",null,(0,a.yg)("strong",{parentName:"p"},"split fee requirement"),":"),(0,a.yg)("p",null,"the ",(0,a.yg)("inlineCode",{parentName:"p"},"combinedFeeRequirement")," into ",(0,a.yg)("inlineCode",{parentName:"p"},"nonZeroCoinFeesReq=[0uatom]"),", and ",(0,a.yg)("inlineCode",{parentName:"p"},"nonZeroCoinFeesReq=[1photon, 1stake]")),(0,a.yg)("p",null,(0,a.yg)("strong",{parentName:"p"},"split the paid fees"),":"),(0,a.yg)("p",null,"if ",(0,a.yg)("inlineCode",{parentName:"p"},"paidFee=[1uatom, 0.5photon]"),",\nthe ",(0,a.yg)("inlineCode",{parentName:"p"},"splitCoinsByDenoms")," splits the paidFee into ",(0,a.yg)("inlineCode",{parentName:"p"},"feeCoinsZeroDenom=[1uatom]")," (the same denom as zero coins in ",(0,a.yg)("inlineCode",{parentName:"p"},"combinedFeeRequirement"),"), and ",(0,a.yg)("inlineCode",{parentName:"p"},"feeCoinsNonZeroDenom=[0.5stake]"),"\nthen ",(0,a.yg)("inlineCode",{parentName:"p"},"feeCoinsZeroDenom=[1uatom]")," is checked by ",(0,a.yg)("inlineCode",{parentName:"p"},"nonZeroCoinFeesReq=[1photon, 1stake]"),"."),(0,a.yg)("p",null,"Please note that ",(0,a.yg)("inlineCode",{parentName:"p"},"feeCoins")," does not contain zero coins. The fee coins are split according to the denoms in ",(0,a.yg)("inlineCode",{parentName:"p"},"zeroCoinFeesDenomReq")," or ",(0,a.yg)("inlineCode",{parentName:"p"},"nonZeroCoinFeesDenomReq"),". If feeCoins contains coins not in both ",(0,a.yg)("inlineCode",{parentName:"p"},"zeroCoinFeesDenomReq")," and ",(0,a.yg)("inlineCode",{parentName:"p"},"nonZeroCoinFeesDenomReq"),", the transaction should be rejected. On the contrary, if feeCoins' denoms are in either ",(0,a.yg)("inlineCode",{parentName:"p"},"zeroCoinFeesDenomReq")," or ",(0,a.yg)("inlineCode",{parentName:"p"},"nonZeroCoinFeesDenomReq"),", and ",(0,a.yg)("inlineCode",{parentName:"p"},"len(zeroCoinFeesDenomReq)!=0"),", the transaction can directly pass, otherwise, the fee amount need to be checked."),(0,a.yg)("h3",{id:"bypass-message-types"},"Bypass Message Types"),(0,a.yg)("p",null,(0,a.yg)("inlineCode",{parentName:"p"},"BypassMinFeeMsgTypes")," was a setup in ",(0,a.yg)("inlineCode",{parentName:"p"},"config/app.toml")," before the refactor. ",(0,a.yg)("inlineCode",{parentName:"p"},"BypassMinFeeMsgTypes")," is refactored to be a param of the globalfee module to get a network level agreement. Correspondingly,",(0,a.yg)("inlineCode",{parentName:"p"},"MaxTotalBypassMinFeeMsgGasUsage")," is also introduced as a globalfee param."),(0,a.yg)("h3",{id:"fee-checks-in--delivertx"},"Fee Checks in ",(0,a.yg)("inlineCode",{parentName:"h3"},"DeliverTx")),(0,a.yg)("p",null,"Implementing fee checks within the ",(0,a.yg)("inlineCode",{parentName:"p"},"DeliverTx")," function introduces a few requirements:"),(0,a.yg)("ul",null,(0,a.yg)("li",{parentName:"ul"},(0,a.yg)("strong",{parentName:"li"},"Deterministic Minimum Fee Requirement"),": For the ",(0,a.yg)("inlineCode",{parentName:"li"},"DeliverTx")," process, it is essential to have a deterministic minimum fee requirement. In ",(0,a.yg)("inlineCode",{parentName:"li"},"CheckTx"),", fee is checked by the ",(0,a.yg)("inlineCode",{parentName:"li"},"CombinedFeeRequirement(globalFees, localFees)"),", which considers both ",(0,a.yg)("inlineCode",{parentName:"li"},"minimum-gas-prices")," from ",(0,a.yg)("inlineCode",{parentName:"li"},"config/app.toml")," and ",(0,a.yg)("inlineCode",{parentName:"li"},"MinimumGasPricesParam")," from the globalfee Params (For more details, see ",(0,a.yg)("a",{parentName:"li",href:"/main/modules/globalfee"},"globalfee"),"). ",(0,a.yg)("inlineCode",{parentName:"li"},"CombinedFeeRequirement")," contains non-deterministic part: ",(0,a.yg)("inlineCode",{parentName:"li"},"minimum-gas-prices")," from ",(0,a.yg)("inlineCode",{parentName:"li"},"app.toml"),". Therefore, ",(0,a.yg)("inlineCode",{parentName:"li"},"CombinedFeeRequirement")," cannot be used in ",(0,a.yg)("inlineCode",{parentName:"li"},"DeliverTx"),". In ",(0,a.yg)("inlineCode",{parentName:"li"},"DeliverTx"),", only ",(0,a.yg)("inlineCode",{parentName:"li"},"MinimumGasPricesParam")," in globalfee Params is used for fee verification. The code implementation is shown below. ")),(0,a.yg)("pre",null,(0,a.yg)("code",{parentName:"pre",className:"language-go"},'func (mfd FeeDecorator) GetTxFeeRequired(ctx sdk.Context, tx sdk.FeeTx) (sdk.Coins, error) {\n // Get required global fee min gas prices\n // Note that it should never be empty since its default value is set to coin={"StakingBondDenom", 0}\n globalFees, err := mfd.GetGlobalFee(ctx, tx)\n if err != nil {\n return sdk.Coins{}, err\n }\n\n // In DeliverTx, the global fee min gas prices are the only tx fee requirements.\n if !ctx.IsCheckTx() {\n return globalFees, nil\n }\n\n // In CheckTx mode, the local and global fee min gas prices are combined\n // to form the tx fee requirements\n\n // Get local minimum-gas-prices\n localFees := GetMinGasPrice(ctx, int64(tx.GetGas()))\n\n // Return combined fee requirements\n return CombinedFeeRequirement(globalFees, localFees)\n}\n')),(0,a.yg)("ul",null,(0,a.yg)("li",{parentName:"ul"},(0,a.yg)("p",{parentName:"li"},(0,a.yg)("strong",{parentName:"p"},"Deterministic Bypass Parameters"),": The decision of whether a message can bypass the minimum fee has to be deterministic as well. To ensure this, ",(0,a.yg)("inlineCode",{parentName:"p"},"BypassMinFeeMsgTypes")," and ",(0,a.yg)("inlineCode",{parentName:"p"},"MaxTotalBypassMinFeeMsgGasUsage")," parameters are moved to a persistent store.")),(0,a.yg)("li",{parentName:"ul"},(0,a.yg)("p",{parentName:"li"},(0,a.yg)("strong",{parentName:"p"},"Module Initialization Order"),": The genutils module must be initialized before the globalfee module. This is due to the ",(0,a.yg)("inlineCode",{parentName:"p"},"DeliverGenTxs")," in the genutils module, is called during ",(0,a.yg)("inlineCode",{parentName:"p"},"initGenesis"),". This function executes ",(0,a.yg)("inlineCode",{parentName:"p"},"DeliverTx"),", which subsequently calls the AnteHandle in FeeDecorator, triggering the fee check in ",(0,a.yg)("inlineCode",{parentName:"p"},"DeliverTx"),".\nTo prevent the ",(0,a.yg)("inlineCode",{parentName:"p"},"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 ",(0,a.yg)("a",{parentName:"p",href:"https://github.com/cosmos/gaia/issues/2489"},"Gaia Issue #2489")," for more context."))),(0,a.yg)("h2",{id:"consequences"},"Consequences"),(0,a.yg)("h3",{id:"positive"},"Positive"),(0,a.yg)("p",null,"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."),(0,a.yg)("h3",{id:"negative"},"Negative"),(0,a.yg)("p",null,"The introduction of FeeDecorator has replaced the usage of ",(0,a.yg)("inlineCode",{parentName:"p"},"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."),(0,a.yg)("h2",{id:"references"},"References"),(0,a.yg)("ul",null,(0,a.yg)("li",{parentName:"ul"},(0,a.yg)("a",{parentName:"li",href:"../../modules/globalfee"},"Documentation of the globalfee module"))))}c.isMDXComponent=!0}}]);
\ No newline at end of file
diff --git a/assets/js/0ce6bca3.7f4755fc.js b/assets/js/0ce6bca3.7f4755fc.js
new file mode 100644
index 00000000000..16e4701e345
--- /dev/null
+++ b/assets/js/0ce6bca3.7f4755fc.js
@@ -0,0 +1 @@
+"use strict";(self.webpackChunkcosmos_hub_docs_site=self.webpackChunkcosmos_hub_docs_site||[]).push([[4036],{5680:(e,t,a)=>{a.d(t,{xA:()=>p,yg:()=>g});var n=a(6540);function r(e,t,a){return t in e?Object.defineProperty(e,t,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[t]=a,e}function i(e,t){var a=Object.keys(e);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(e);t&&(n=n.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),a.push.apply(a,n)}return a}function l(e){for(var t=1;tgaiad",id:"installing-gaiad",level:2},{value:"Cosmos Accounts",id:"cosmos-accounts",level:2},{value:"Restoring an Account from the Fundraiser",id:"restoring-an-account-from-the-fundraiser",level:3},{value:"On a Ledger Device",id:"on-a-ledger-device",level:4},{value:"On a Computer",id:"on-a-computer",level:4},{value:"Creating an Account",id:"creating-an-account",level:3},{value:"Using a Ledger Device",id:"using-a-ledger-device",level:4},{value:"Using a Computer",id:"using-a-computer",level:4},{value:"Accessing the Cosmos Hub Network",id:"accessing-the-cosmos-hub-network",level:2},{value:"Running Your Own Full-Node",id:"running-your-own-full-node",level:3},{value:"Connecting to a Remote Full-Node",id:"connecting-to-a-remote-full-node",level:3},{value:"Setting Up gaiad",id:"setting-up-gaiad",level:2},{value:"Querying the State",id:"querying-the-state",level:2},{value:"Sending Transactions",id:"sending-transactions",level:2},{value:"A Note on Gas and Fees",id:"a-note-on-gas-and-fees",level:3},{value:"Sending Tokens",id:"sending-tokens",level:3},{value:"Bonding Atoms and Withdrawing Rewards",id:"bonding-atoms-and-withdrawing-rewards",level:3},{value:"Participating in Governance",id:"participating-in-governance",level:2},{value:"Primer on Governance",id:"primer-on-governance",level:3},{value:"In Practice",id:"in-practice",level:3},{value:"Signing Transactions From an Offline Computer",id:"signing-transactions-from-an-offline-computer",level:3}],g={toc:d},p="wrapper";function u(e){let{components:n,...a}=e;return(0,o.yg)(p,(0,t.A)({},g,a,{components:n,mdxType:"MDXLayout"}),(0,o.yg)("p",null,"This document contains all the necessary information for delegators to interact with the Cosmos Hub through the Command-Line Interface (CLI)."),(0,o.yg)("p",null,"It also contains instructions on how to manage accounts, restore accounts from the fundraiser and use a ledger nano device."),(0,o.yg)("admonition",{type:"tip"},(0,o.yg)("p",{parentName:"admonition"},(0,o.yg)("strong",{parentName:"p"},"Very Important"),": Please assure that you follow the steps described hereinafter\ncarefully, as negligence in this significant process could lead to an indefinite\nloss of your Atoms. Therefore, read through the following instructions in their\nentirety prior to proceeding and reach out to us in case you need support."),(0,o.yg)("p",{parentName:"admonition"},"Please also note that you are about to interact with the Cosmos Hub, a\nblockchain technology containing highly experimental software. While the\nblockchain has been developed in accordance to the state of the art and audited\nwith utmost care, we can nevertheless expect to have issues, updates and bugs.\nFurthermore, interaction with blockchain technology requires\nadvanced technical skills and always entails risks that are outside our control.\nBy using the software, you confirm that you understand the inherent risks\nassociated with cryptographic software (see also risk section of the\n",(0,o.yg)("a",{parentName:"p",href:"https://github.com/cosmos/cosmos/blob/master/fundraiser/Interchain%20Cosmos%20Contribution%20Terms%20-%20FINAL.pdf"},"Interchain Cosmos Contribution terms"),') and that the Interchain Foundation and/or\nthe Tendermint Team may not be held liable for potential damages arising out of the use of the\nsoftware. Any use of this open source software released under the Apache 2.0 license is\ndone at your own risk and on a "AS IS" basis, without warranties or conditions\nof any kind.')),(0,o.yg)("p",null,"Please exercise extreme caution!"),(0,o.yg)("h2",{id:"table-of-contents"},"Table of Contents"),(0,o.yg)("ul",null,(0,o.yg)("li",{parentName:"ul"},(0,o.yg)("a",{parentName:"li",href:"#table-of-contents"},"Table of Contents")),(0,o.yg)("li",{parentName:"ul"},(0,o.yg)("a",{parentName:"li",href:"#installing-gaiad"},"Installing ",(0,o.yg)("inlineCode",{parentName:"a"},"gaiad"))),(0,o.yg)("li",{parentName:"ul"},(0,o.yg)("a",{parentName:"li",href:"#cosmos-accounts"},"Cosmos Accounts"),(0,o.yg)("ul",{parentName:"li"},(0,o.yg)("li",{parentName:"ul"},(0,o.yg)("a",{parentName:"li",href:"#restoring-an-account-from-the-fundraiser"},"Restoring an Account from the Fundraiser"),(0,o.yg)("ul",{parentName:"li"},(0,o.yg)("li",{parentName:"ul"},(0,o.yg)("a",{parentName:"li",href:"#on-a-ledger-device"},"On a Ledger Device")),(0,o.yg)("li",{parentName:"ul"},(0,o.yg)("a",{parentName:"li",href:"#on-a-computer"},"On a Computer")))),(0,o.yg)("li",{parentName:"ul"},(0,o.yg)("a",{parentName:"li",href:"#creating-an-account"},"Creating an Account"),(0,o.yg)("ul",{parentName:"li"},(0,o.yg)("li",{parentName:"ul"},(0,o.yg)("a",{parentName:"li",href:"#using-a-ledger-device"},"Using a Ledger Device")),(0,o.yg)("li",{parentName:"ul"},(0,o.yg)("a",{parentName:"li",href:"#using-a-computer"},"Using a Computer")))))),(0,o.yg)("li",{parentName:"ul"},(0,o.yg)("a",{parentName:"li",href:"#accessing-the-cosmos-hub-network"},"Accessing the Cosmos Hub Network"),(0,o.yg)("ul",{parentName:"li"},(0,o.yg)("li",{parentName:"ul"},(0,o.yg)("a",{parentName:"li",href:"#running-your-own-full-node"},"Running Your Own Full-Node")),(0,o.yg)("li",{parentName:"ul"},(0,o.yg)("a",{parentName:"li",href:"#connecting-to-a-remote-full-node"},"Connecting to a Remote Full-Node")))),(0,o.yg)("li",{parentName:"ul"},(0,o.yg)("a",{parentName:"li",href:"#setting-up-gaiad"},"Setting Up ",(0,o.yg)("inlineCode",{parentName:"a"},"gaiad"))),(0,o.yg)("li",{parentName:"ul"},(0,o.yg)("a",{parentName:"li",href:"#querying-the-state"},"Querying the State")),(0,o.yg)("li",{parentName:"ul"},(0,o.yg)("a",{parentName:"li",href:"#sending-transactions"},"Sending Transactions"),(0,o.yg)("ul",{parentName:"li"},(0,o.yg)("li",{parentName:"ul"},(0,o.yg)("a",{parentName:"li",href:"#a-note-on-gas-and-fees"},"A Note on Gas and Fees")),(0,o.yg)("li",{parentName:"ul"},(0,o.yg)("a",{parentName:"li",href:"#sending-tokens"},"Sending Tokens")),(0,o.yg)("li",{parentName:"ul"},(0,o.yg)("a",{parentName:"li",href:"#bonding-atoms-and-withdrawing-rewards"},"Bonding Atoms and Withdrawing Rewards")))),(0,o.yg)("li",{parentName:"ul"},(0,o.yg)("a",{parentName:"li",href:"#participating-in-governance"},"Participating in Governance"),(0,o.yg)("ul",{parentName:"li"},(0,o.yg)("li",{parentName:"ul"},(0,o.yg)("a",{parentName:"li",href:"#primer-on-governance"},"Primer on Governance")),(0,o.yg)("li",{parentName:"ul"},(0,o.yg)("a",{parentName:"li",href:"#in-practice"},"In Practice")),(0,o.yg)("li",{parentName:"ul"},(0,o.yg)("a",{parentName:"li",href:"#signing-transactions-from-an-offline-computer"},"Signing Transactions From an Offline Computer"))))),(0,o.yg)("h2",{id:"installing-gaiad"},"Installing ",(0,o.yg)("inlineCode",{parentName:"h2"},"gaiad")),(0,o.yg)("p",null,(0,o.yg)("inlineCode",{parentName:"p"},"gaiad"),": This is the command-line interface to interact with a ",(0,o.yg)("inlineCode",{parentName:"p"},"gaiad")," full-node."),(0,o.yg)("admonition",{type:"warning"},(0,o.yg)("p",{parentName:"admonition"},(0,o.yg)("strong",{parentName:"p"},"Please check that you download the latest stable release of ",(0,o.yg)("inlineCode",{parentName:"strong"},"gaiad")," that is available"))),(0,o.yg)("p",null,"[",(0,o.yg)("strong",{parentName:"p"},"Download the binaries"),"]","\nNot available yet."),(0,o.yg)("p",null,(0,o.yg)("a",{parentName:"p",href:"../getting-started/installation"},(0,o.yg)("strong",{parentName:"a"},"Install from source"))),(0,o.yg)("admonition",{type:"tip"},(0,o.yg)("p",{parentName:"admonition"},(0,o.yg)("inlineCode",{parentName:"p"},"gaiad")," is used from a terminal. To open the terminal, follow these steps:"),(0,o.yg)("ul",{parentName:"admonition"},(0,o.yg)("li",{parentName:"ul"},(0,o.yg)("strong",{parentName:"li"},"Windows"),": ",(0,o.yg)("inlineCode",{parentName:"li"},"Start")," > ",(0,o.yg)("inlineCode",{parentName:"li"},"All Programs")," > ",(0,o.yg)("inlineCode",{parentName:"li"},"Accessories")," > ",(0,o.yg)("inlineCode",{parentName:"li"},"Command Prompt")),(0,o.yg)("li",{parentName:"ul"},(0,o.yg)("strong",{parentName:"li"},"MacOS"),": ",(0,o.yg)("inlineCode",{parentName:"li"},"Finder")," > ",(0,o.yg)("inlineCode",{parentName:"li"},"Applications")," > ",(0,o.yg)("inlineCode",{parentName:"li"},"Utilities")," > ",(0,o.yg)("inlineCode",{parentName:"li"},"Terminal")),(0,o.yg)("li",{parentName:"ul"},(0,o.yg)("strong",{parentName:"li"},"Linux"),": ",(0,o.yg)("inlineCode",{parentName:"li"},"Ctrl")," + ",(0,o.yg)("inlineCode",{parentName:"li"},"Alt")," + ",(0,o.yg)("inlineCode",{parentName:"li"},"T")))),(0,o.yg)("h2",{id:"cosmos-accounts"},"Cosmos Accounts"),(0,o.yg)("p",null,"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 ",(0,o.yg)("a",{parentName:"p",href:"https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki"},"BIP32")," for more information on the HD wallet specification)."),(0,o.yg)("pre",null,(0,o.yg)("code",{parentName:"pre",className:"language-txt"}," Account 0 Account 1 Account 2\n\n+------------------+ +------------------+ +------------------+\n| | | | | |\n| Address 0 | | Address 1 | | Address 2 |\n| ^ | | ^ | | ^ |\n| | | | | | | | |\n| | | | | | | | |\n| | | | | | | | |\n| + | | + | | + |\n| Public key 0 | | Public key 1 | | Public key 2 |\n| ^ | | ^ | | ^ |\n| | | | | | | | |\n| | | | | | | | |\n| | | | | | | | |\n| + | | + | | + |\n| Private key 0 | | Private key 1 | | Private key 2 |\n| ^ | | ^ | | ^ |\n+------------------+ +------------------+ +------------------+\n | | |\n | | |\n | | |\n +--------------------------------------------------------------------+\n |\n |\n +---------+---------+\n | |\n | Mnemonic (Seed) |\n | |\n +-------------------+\n")),(0,o.yg)("p",null,"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."),(0,o.yg)("admonition",{type:"warning"},(0,o.yg)("p",{parentName:"admonition"},(0,o.yg)("strong",{parentName:"p"},"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."))),(0,o.yg)("p",null,"The address is a public string with a human-readable prefix (e.g. ",(0,o.yg)("inlineCode",{parentName:"p"},"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."),(0,o.yg)("h3",{id:"restoring-an-account-from-the-fundraiser"},"Restoring an Account from the Fundraiser"),(0,o.yg)("admonition",{type:"tip"},(0,o.yg)("p",{parentName:"admonition"},(0,o.yg)("em",{parentName:"p"},"NOTE: This section only concerns fundraiser participants"))),(0,o.yg)("p",null,"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."),(0,o.yg)("h4",{id:"on-a-ledger-device"},"On a Ledger Device"),(0,o.yg)("p",null,"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."),(0,o.yg)("admonition",{type:"warning"},(0,o.yg)("p",{parentName:"admonition"},"*NOTE: To do this, ",(0,o.yg)("strong",{parentName:"p"},"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 ",(0,o.yg)("inlineCode",{parentName:"p"},"Settings"),">",(0,o.yg)("inlineCode",{parentName:"p"},"Device"),">",(0,o.yg)("inlineCode",{parentName:"p"},"Reset All"),". ",(0,o.yg)("strong",{parentName:"p"},"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!!!*"))),(0,o.yg)("p",null,"The following steps need to be performed on an un-initialized ledger device:"),(0,o.yg)("ol",null,(0,o.yg)("li",{parentName:"ol"},"Connect your ledger device to the computer via USB"),(0,o.yg)("li",{parentName:"ol"},"Press both buttons"),(0,o.yg)("li",{parentName:"ol"},"Do ",(0,o.yg)("strong",{parentName:"li"},"NOT"),' choose the "Config as a new device" option. Instead, choose "Restore Configuration"'),(0,o.yg)("li",{parentName:"ol"},"Choose a PIN"),(0,o.yg)("li",{parentName:"ol"},"Choose the 12 words option"),(0,o.yg)("li",{parentName:"ol"},"Input each of the words you got during the fundraiser, in the correct order.")),(0,o.yg)("p",null,"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."),(0,o.yg)("p",null,"Next, click ",(0,o.yg)("a",{parentName:"p",href:"#using-a-ledger-device"},"here")," to learn how to generate an account."),(0,o.yg)("h4",{id:"on-a-computer"},"On a Computer"),(0,o.yg)("admonition",{type:"warning"},(0,o.yg)("p",{parentName:"admonition"},(0,o.yg)("strong",{parentName:"p"},"NOTE: It is more secure to perform this action on an offline computer"))),(0,o.yg)("p",null,"To restore an account using a fundraiser mnemonic and store the associated encrypted private key on a computer, use the following command:"),(0,o.yg)("pre",null,(0,o.yg)("code",{parentName:"pre",className:"language-bash"},"gaiad keys add