diff --git a/.gitbook/.gitbook/assets/blog-hero.png b/.gitbook/.gitbook/assets/blog-hero.png deleted file mode 100644 index c143cf1f..00000000 Binary files a/.gitbook/.gitbook/assets/blog-hero.png and /dev/null differ diff --git a/.gitbook/.gitbook/assets/bridge-hero.png b/.gitbook/.gitbook/assets/bridge-hero.png deleted file mode 100644 index c074626f..00000000 Binary files a/.gitbook/.gitbook/assets/bridge-hero.png and /dev/null differ diff --git a/.gitbook/.gitbook/assets/code-hero.png b/.gitbook/.gitbook/assets/code-hero.png deleted file mode 100644 index ca5b1dca..00000000 Binary files a/.gitbook/.gitbook/assets/code-hero.png and /dev/null differ diff --git a/.gitbook/.gitbook/assets/dev-hero.png b/.gitbook/.gitbook/assets/dev-hero.png deleted file mode 100644 index 248e1caf..00000000 Binary files a/.gitbook/.gitbook/assets/dev-hero.png and /dev/null differ diff --git a/.gitbook/.gitbook/assets/explorer-hero.png b/.gitbook/.gitbook/assets/explorer-hero.png deleted file mode 100644 index 20757c5d..00000000 Binary files a/.gitbook/.gitbook/assets/explorer-hero.png and /dev/null differ diff --git a/.gitbook/.gitbook/assets/inj-hero.png b/.gitbook/.gitbook/assets/inj-hero.png deleted file mode 100644 index 7df965a4..00000000 Binary files a/.gitbook/.gitbook/assets/inj-hero.png and /dev/null differ diff --git a/.gitbook/.gitbook/assets/launch-market-hero.png b/.gitbook/.gitbook/assets/launch-market-hero.png deleted file mode 100644 index 8683ad04..00000000 Binary files a/.gitbook/.gitbook/assets/launch-market-hero.png and /dev/null differ diff --git a/.gitbook/.gitbook/assets/launch-token-hero.png b/.gitbook/.gitbook/assets/launch-token-hero.png deleted file mode 100644 index 5f0b63e1..00000000 Binary files a/.gitbook/.gitbook/assets/launch-token-hero.png and /dev/null differ diff --git a/.gitbook/.gitbook/assets/start-ehro.png b/.gitbook/.gitbook/assets/start-ehro.png deleted file mode 100644 index 80edcefd..00000000 Binary files a/.gitbook/.gitbook/assets/start-ehro.png and /dev/null differ diff --git a/.gitbook/.gitbook/assets/token-hero.png b/.gitbook/.gitbook/assets/token-hero.png deleted file mode 100644 index a41be782..00000000 Binary files a/.gitbook/.gitbook/assets/token-hero.png and /dev/null differ diff --git a/.gitbook/.gitbook/assets/trader-hero.png b/.gitbook/.gitbook/assets/trader-hero.png deleted file mode 100644 index c9059d20..00000000 Binary files a/.gitbook/.gitbook/assets/trader-hero.png and /dev/null differ diff --git a/.gitbook/.gitbook/assets/txs-hero.png b/.gitbook/.gitbook/assets/txs-hero.png deleted file mode 100644 index 10606904..00000000 Binary files a/.gitbook/.gitbook/assets/txs-hero.png and /dev/null differ diff --git a/.gitbook/.gitbook/assets/user-hero.png b/.gitbook/.gitbook/assets/user-hero.png deleted file mode 100644 index 24da65a5..00000000 Binary files a/.gitbook/.gitbook/assets/user-hero.png and /dev/null differ diff --git a/.gitbook/.gitbook/assets/validator-hero.png b/.gitbook/.gitbook/assets/validator-hero.png deleted file mode 100644 index 38bdae57..00000000 Binary files a/.gitbook/.gitbook/assets/validator-hero.png and /dev/null differ diff --git a/.gitbook/.gitbook/assets/wallet-hero (1).png b/.gitbook/.gitbook/assets/wallet-hero (1).png deleted file mode 100644 index 558bdf86..00000000 Binary files a/.gitbook/.gitbook/assets/wallet-hero (1).png and /dev/null differ diff --git a/.gitbook/.gitbook/assets/wallet-hero.png b/.gitbook/.gitbook/assets/wallet-hero.png deleted file mode 100644 index 2b86359f..00000000 Binary files a/.gitbook/.gitbook/assets/wallet-hero.png and /dev/null differ diff --git a/.gitbook/README.md b/.gitbook/README.md deleted file mode 100644 index 44ab0cf1..00000000 --- a/.gitbook/README.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -description: >- - Brief summary about Injective and overview of its countless possibilities that - make it the best choice for onboarding developers. ---- - -# About Injective - -Injective is a lightning-fast, interoperable, layer-one blockchain optimized for building premier Web3 financial applications. Injective provides developers with robust plug-and-play modules such as a fully decentralized orderbook, binary options, real-world asset (RWA) module, and more, allowing developers to build a diverse array of sophisticated applications. - -### What is Injective?[​](https://docs.injective.network/learn/introduction#what-is-injective) - -Injective is the blockchain built for finance. - -Injective is the only blockchain where developers can find robust out-of-the-box modules, such as a completely decentralized orderbook that can be utilized to build a diverse array of sophisticated applications. Moreover, Injective is an open, interoperable smart contracts platform. - -Injective is built with the Cosmos SDK, enabling instant transaction finality through the Tendermint proof-of-stake consensus framework. Moreover, Injective excels in enabling swift cross-chain transactions, seamlessly bridging prominent layer-one networks like Ethereum, Solana, Cosmos Hub, and more. - -The Injective ecosystem is a network of decentralized applications that focus on providing the best in-class user experience. By providing the unrestricted and unprecedented ability to access decentralized financial markets, products, services, and toolings, the Injective ecosystem empowers individuals with the ability to allocate capital more efficiently. - -### Why Build on Injective?[​](https://docs.injective.network/learn/introduction#why-build-on-injective) - -* Optimized for decentralized finance: Injective provides out-of-the-box financial primitives such as a fully decentralized orderbook to allow developers to create mainstream dApps. For instance, applications can leverage the orderbook to launch exchanges, prediction markets, and various other on-chain strategies. -* Interoperable: Injective is natively interoperable across many sovereign blockchain networks while also being IBC-enabled. Injective can facilitate seamless cross-chain transactions across Ethereum, Moonbeam, IBC-enabled chains such as CosmosHub, and Wormhole integrated chains such as Solana, Avalanche, etc. -* Build dApps Using CosmWasm: Injective supports CosmWasm, a novel smart contracting platform built for the Cosmos ecosystem. This means developers can easily launch their own smart-contract powered applications on Injective. Smart-contracts that work on other chains supporting CosmWasm can seamlessly be migrated to Injective. -* Launch Ethereum and IBC compatible tokens: Since Injective supports cross-chain transactions with Ethereum and all IBC-enabled chains, tokens launched on Injective can be exposed to multiple networks by default. -* Intuitive developer experience: Utilize flexible and expressive development environments powered by Rust and Golang. - -Start building on Injective[\ -](https://docs.unichain.org/docs/getting-started/setting-up-a-wallet) ---------------------------------------------------------------------- - -
Getting StartedStart your Injective Journeygetting-startedstart-ehro.png
Are you a User?Learn how to create a walletcreate-a-wallet.mduser-hero.png
Are you a Developer?Learn how to build on Injectivegetting-starteddev-hero.png
Are you a Trader?Learn how to start trading on Injectivegetting-started.mdtrader-hero.png
Are you a Validator?Learn how to run sentry and validator nodesgetting-startedvalidator-hero.png
Are you just curious?Feel free to explore the docsexplorer-hero.png
diff --git a/.gitbook/SUMMARY.md b/.gitbook/SUMMARY.md deleted file mode 100644 index 81f7d514..00000000 --- a/.gitbook/SUMMARY.md +++ /dev/null @@ -1,203 +0,0 @@ -# Table of contents - -* [About Injective](README.md) -* [Getting Started](getting-started/README.md) - * [Wallet](getting-started/wallet/README.md) - * [Create a wallet](getting-started/wallet/create-a-wallet.md) - * [Accounts](getting-started/wallet/accounts.md) - * [Staking](getting-started/wallet/staking.md) - * [Governance](getting-started/wallet/governance.md) - * [Auction](getting-started/wallet/auction.md) - * [Token Standards](getting-started/token-standards/README.md) - * [INJ coin](getting-started/token-standards/inj-coin.md) - * [Token Factory](getting-started/token-standards/token-factory.md) - * [CW20 Standard](getting-started/token-standards/cw20-standard.md) - * [Transactions](getting-started/transactions/README.md) - * [Gas and Fees](getting-started/transactions/gas-and-fees.md) -* [Guides](guides/README.md) - * [Create a Wallet](https://blog.injective.com/en/how-to-create-an-injective-wallet-2/) - * [Bridge](guides/bridge/README.md) - * [From Ethereum](https://blog.injective.com/en/how-to-bridge-from-ethereum-to-injective-using-metamask/) - * [Using Wormhole](https://blog.injective.com/en/how-to-bridge-to-injective-using-wormhole/) - * [Using IBC from Cosmos](https://blog.injective.com/en/how-to-bridge-from-cosmos-to-injective-using-keplr/) - * [From Solana](https://blog.injective.com/en/how-to-bridge-from-solana-to-injective-using-phantom/) - * [Launch a token](guides/launch-a-token.md) - * [Launch a market](guides/launch-a-market.md) - * [Get INJ](https://injective.com/getinj) -* [Toolkits](toolkits/README.md) - * [injectived](toolkits/injectived/README.md) - * [Install injectived](toolkits/injectived/install-injectived.md) - * [Using injectived](toolkits/injectived/using-injectived.md) - * [Commands](toolkits/injectived/advanced.md) - * [Injective TS SDK](https://docs.ts.injective.network) - * [Injective Go SDK](https://github.com/InjectiveLabs/sdk-go/) - * [Injective Python SDK](https://github.com/InjectiveLabs/sdk-python) - * [Injective CW SDK](https://github.com/InjectiveLabs/cw-injective) - * [The Graph](https://docs.substreams.dev/documentation/how-to-guides/injective) -* [References](references.md) -* [Glossary](glossary.md) - -## Developers - -* [Getting Started](developers/getting-started/README.md) - * [Guides](developers/getting-started/guides/README.md) - * [Testnet Proposals](developers/getting-started/guides/testnet-proposals.md) - * [Convert addresses](developers/getting-started/guides/convert-addresses.md) -* [Exchange Developers](developers/exchange-developers/README.md) - * [Build a DEX](https://docs.ts.injective.network/building-dapps/dapps-examples/dex) - * [Provider Oracle](developers/exchange-developers/provider-oracle.md) -* [EVM Developers](developers/evm-developers.md) -* [Cosmwasm Developers](developers/cosmwasm-developers/README.md) - * [Your First Smart Contract](developers/cosmwasm-developers/your-first-smart-contract.md) - * [Guides](developers/cosmwasm-developers/guides/README.md) - * [Local Development](developers/cosmwasm-developers/guides/local-development.md) - * [Mainnet Deployment](developers/cosmwasm-developers/guides/mainnet-deployment.md) - * [Whitelisting deployment address](developers/cosmwasm-developers/guides/whitelisting-deployment-address.md) - * [Create your Swap Contract](developers/cosmwasm-developers/guides/create-your-swap-contract.md) - * [Creating UIs](developers/cosmwasm-developers/guides/creating-uis.md) - * [CW20 Adapter](developers/cosmwasm-developers/page-1.md) - * [Injective Test Tube](developers/cosmwasm-developers/injective-test-tube.md) -* [Modules](developers/modules/README.md) - * [Injective](developers/modules/injective/README.md) - * [Auction](developers/modules/injective/auction/README.md) - * [State](developers/modules/injective/auction/01_state.md) - * [Messages](developers/modules/injective/auction/02_messages.md) - * [EndBlock](developers/modules/injective/auction/03_end_block.md) - * [Events](developers/modules/injective/auction/04_events.md) - * [Params](developers/modules/injective/auction/05_params.md) - * [Exchange](developers/modules/injective/exchange/README.md) - * [Derivative Markets Concepts](developers/modules/injective/exchange/00_derivative_market_concepts.md) - * [Spot Markets Concepts](developers/modules/injective/exchange/01_spot_market_concepts.md) - * [Binary Option Markets Concepts](developers/modules/injective/exchange/02_binary_options_markets.md) - * [Other Concepts](developers/modules/injective/exchange/02_other_concepts.md) - * [State](developers/modules/injective/exchange/03_state.md) - * [State Transitions](developers/modules/injective/exchange/04_state_transitions.md) - * [Messages](developers/modules/injective/exchange/05_messages.md) - * [Proposals](developers/modules/injective/exchange/06_proposals.md) - * [BeginBlock](developers/modules/injective/exchange/07_begin_block.md) - * [EndBlock](developers/modules/injective/exchange/08_end_block.md) - * [Events](developers/modules/injective/exchange/09_events.md) - * [Params](developers/modules/injective/exchange/10_params.md) - * [MsgPrivilegedExecuteContract](developers/modules/injective/exchange/11_msg_privileged_execute_contract.md) - * [Improvements](developers/modules/injective/exchange/07_future_improvements.md) - * [Insurance](developers/modules/injective/insurance/README.md) - * [State](developers/modules/injective/insurance/01_state.md) - * [State Transitions](developers/modules/injective/insurance/02_state_transition.md) - * [Messages](developers/modules/injective/insurance/03_messages.md) - * [EndBlock](developers/modules/injective/insurance/04_end_block.md) - * [Events](developers/modules/injective/insurance/05_events.md) - * [Params](developers/modules/injective/insurance/06_params.md) - * [Improvements](developers/modules/injective/insurance/07_future_improvements.md) - * [OCR](developers/modules/injective/ocr/README.md) - * [Concepts](developers/modules/injective/ocr/01_concepts.md) - * [State](developers/modules/injective/ocr/02_state.md) - * [Messages](developers/modules/injective/ocr/03_messages.md) - * [Proposals](developers/modules/injective/ocr/04_proposals.md) - * [BeginBlock](developers/modules/injective/ocr/05_begin_block.md) - * [Hooks](developers/modules/injective/ocr/06_hooks.md) - * [Events](developers/modules/injective/ocr/07_hooks.md) - * [Params](developers/modules/injective/ocr/08_params.md) - * [Oracle](developers/modules/injective/oracle/README.md) - * [State](developers/modules/injective/oracle/01_state.md) - * [Keeper](developers/modules/injective/oracle/02_keeper.md) - * [Messages](developers/modules/injective/oracle/03_messages.md) - * [Proposals](developers/modules/injective/oracle/04_proposals.md) - * [Events](developers/modules/injective/oracle/05_events.md) - * [Improvements](developers/modules/injective/oracle/06_future_improvements.md) - * [Peggy](developers/modules/injective/peggy/README.md) - * [Definitions](developers/modules/injective/peggy/01_definitions.md) - * [Workflow](developers/modules/injective/peggy/02_workflow.md) - * [State](developers/modules/injective/peggy/03_state.md) - * [Messages](developers/modules/injective/peggy/04_messages.md) - * [Slashing](developers/modules/injective/peggy/05_slashing.md) - * [EndBlock](developers/modules/injective/peggy/06_end_block.md) - * [Events](developers/modules/injective/peggy/07_events.md) - * [Params](developers/modules/injective/peggy/08_params.md) - * [Relay Semantics](developers/modules/injective/peggy/09_relay_semantics.md) - * [Improvements](developers/modules/injective/peggy/10_future_improvements.md) - * [Permissions](developers/modules/injective/permissions/README.md) - * [Concepts](developers/modules/injective/permissions/01_concepts.md) - * [State](developers/modules/injective/permissions/02_state.md) - * [State Transition](developers/modules/injective/permissions/03_state_transitions.md) - * [TokenFactory](developers/modules/injective/tokenfactory/README.md) - * [Concepts](developers/modules/injective/tokenfactory/01_concepts.md) - * [State](developers/modules/injective/tokenfactory/02_state.md) - * [Messages](developers/modules/injective/tokenfactory/03_messages.md) - * [Events](developers/modules/injective/tokenfactory/04_events.md) - * [Params](developers/modules/injective/tokenfactory/05_params.md) - * [WasmX](developers/modules/injective/wasmx/README.md) - * [Concepts](developers/modules/injective/wasmx/01_concepts.md) - * [Data](developers/modules/injective/wasmx/02_data.md) - * [Proposals](developers/modules/injective/wasmx/03_proposals.md) - * [Messages](developers/modules/injective/wasmx/04_messages.md) - * [Params](developers/modules/injective/wasmx/05_params.md) - * [Core](developers/modules/core/README.md) - * [Auth](developers/modules/core/auth/README.md) - * [AuthZ](developers/modules/core/authz/README.md) - * [Bank](developers/modules/core/bank/README.md) - * [Consensus](developers/modules/core/consensus/README.md) - * [Crisis](developers/modules/core/crisis/README.md) - * [Distribution](developers/modules/core/distribution/README.md) - * [Evidence](developers/modules/core/evidence/README.md) - * [Feegrant](developers/modules/core/feegrant/README.md) - * [Gov](developers/modules/core/gov/README.md) - * [Group](developers/modules/core/group/README.md) - * [Mint](developers/modules/core/mint/README.md) - * [NFT](developers/modules/core/nft/README.md) - * [Params](developers/modules/core/params/README.md) - * [Slashing](developers/modules/core/slashing/README.md) - * [Staking](developers/modules/core/staking/README.md) - * [Upgrade](developers/modules/core/upgrade/README.md) - * [Circuit](developers/modules/core/circuit/README.md) - * [Genutils](developers/modules/core/genutils.md) -* [Documentation](https://docs.ts.injective.network) - -## Nodes - -* [Getting Started](nodes/getting-started/README.md) - * [Interact with a node](nodes/getting-started/interact-with-a-node.md) - * [Running a node](nodes/getting-started/running-a-node/README.md) - * [Setting up the keyring](nodes/getting-started/running-a-node/1.-setting-up-the-keyring.md) - * [Join a network](nodes/getting-started/running-a-node/join-a-network.md) - * [Upgrade your node](nodes/getting-started/running-a-node/upgrade-your-node.md) -* [Validators](nodes/validators/README.md) - * [Mainnet](nodes/validators/mainnet/README.md) - * [Peggo](nodes/validators/mainnet/peggo.md) - * [Canonical Chain Upgrades](nodes/validators/mainnet/canonical-chain-upgrades/README.md) - * [Upgrade to 10002-rc1](nodes/validators/mainnet/canonical-chain-upgrades/canonical-10002-rc1.md) - * [Upgrade to 10002-rc2](nodes/validators/mainnet/canonical-chain-upgrades/canonical-10002-rc2.md) - * [Upgrade to 10003-rc1](nodes/validators/mainnet/canonical-chain-upgrades/canonical-10003-rc1.md) - * [Upgrade to 10004-rc1](nodes/validators/mainnet/canonical-chain-upgrades/canonical-10004-rc1.md) - * [Upgrade to 10004-rc1-patch](nodes/validators/mainnet/canonical-chain-upgrades/canonical-10004-rc1-patch.md) - * [Upgrade to 10005-rc1](nodes/validators/mainnet/canonical-chain-upgrades/canonical-10005-rc1.md) - * [Upgrade to 10006-rc1](nodes/validators/mainnet/canonical-chain-upgrades/canonical-10006-rc1.md) - * [Upgrade to 10007-rc1](nodes/validators/mainnet/canonical-chain-upgrades/canonical-10007-rc1.md) - * [Upgrade to 10008 - Camelot](nodes/validators/mainnet/canonical-chain-upgrades/canonical-10008.md) - * [Upgrade to 10009](nodes/validators/mainnet/canonical-chain-upgrades/canonical-10009.md) - * [Upgrade to v1.10](nodes/validators/mainnet/canonical-chain-upgrades/canonical-100010.md) - * [Upgrade to v1.11](nodes/validators/mainnet/canonical-chain-upgrades/canonical-10011.md) - * [Upgrade to v1.12.0](nodes/validators/mainnet/canonical-chain-upgrades/canonical-1-12.md) - * [Upgrade to v1.12.1](nodes/validators/mainnet/canonical-chain-upgrades/canonical-1-12-1.md) - * [Upgrade to v1.13.0](nodes/validators/mainnet/canonical-chain-upgrades/canonical-1.13.0.md) - * [Upgrade to v1.13.2](nodes/validators/mainnet/canonical-chain-upgrades/canonical-1.13.2.md) - * [Testnet](nodes/validators/testnet/README.md) - * [Testnet Peggo](nodes/validators/testnet/testnet-peggo.md) - * [Cosmosvisor](nodes/validators/cosmosvisor.md) -* [Public Endpoints](nodes/public-endpoints.md) -* [Private Nodes](nodes/private-nodes.md) -* [Injective Indexer Setup](https://injective.notion.site/Injective-Exchange-Service-Setup-Guide-7e59980634d54991862300670583d46a) - -## Traders - -* [Getting Started](traders/getting-started.md) -* [Documentation](https://docs.trading.injective.network) -* [API Reference](https://api.injective.exchange/) - -## Useful Links - -* [Injective 101](https://injective.notion.site/Injective-d48cbe6cb04141e082ff2c85a73ba67a?pvs=4) -* [Injective Hub](https://hub.injective.network) -* [Injective Explorer](https://explorer.injective.network) -* [Chain API Reference](https://sentry.lcd.injective.network/swagger/#/) -* [Indexer API Reference](https://api.injective.network/swagger/#/) -* [Testnet Faucet](https://testnet.faucet.injective.network) diff --git a/.gitbook/developers/cosmwasm-developers/README.md b/.gitbook/developers/cosmwasm-developers/README.md deleted file mode 100644 index 6f5fec01..00000000 --- a/.gitbook/developers/cosmwasm-developers/README.md +++ /dev/null @@ -1,5 +0,0 @@ -# Cosmwasm Developers - -CosmWasm is a novel smart contracting platform built for the Cosmos ecosystem. You can learn more about CosmWasm [here](https://docs.cosmwasm.com/docs/), or see the [CosmWasm Book](https://book.cosmwasm.com/index.html) for a guide on creating CosmWasm smart contracts. - -**Start your builder journey on Injective using Cosmwasm here** [your-first-smart-contract.md](your-first-smart-contract.md "mention") diff --git a/.gitbook/developers/cosmwasm-developers/guides/README.md b/.gitbook/developers/cosmwasm-developers/guides/README.md deleted file mode 100644 index b955b433..00000000 --- a/.gitbook/developers/cosmwasm-developers/guides/README.md +++ /dev/null @@ -1,2 +0,0 @@ -# Guides - diff --git a/.gitbook/developers/cosmwasm-developers/guides/create-your-swap-contract.md b/.gitbook/developers/cosmwasm-developers/guides/create-your-swap-contract.md deleted file mode 100644 index 547511ce..00000000 --- a/.gitbook/developers/cosmwasm-developers/guides/create-your-swap-contract.md +++ /dev/null @@ -1,89 +0,0 @@ -# Create your Swap Contract - -The [swap contract](https://github.com/InjectiveLabs/swap-contract) allows an instant swap between two different tokens. Under the hood, it uses atomic orders to place market orders in one or more spot markets. - -### Getting started - -Anyone can instantiate an instance of the swap contract. There is version of this contract uploaded on Injective mainnet already, and can be found [here](https://explorer.injective.network/code/67/). - -Before instantiating the contract, as the contract owner, you have three questions to answer: - -#### 1. Which address should be the fee recipient? - -Since orders placed by the swap contract are orders in the Injective Exchange Module, this means each order can have a fee recipient which can receive 40% of the trading fee. Typically, Exchange dApps will set the fee recipient as their own addresses. - -#### 2. What tokens should this contract support? - -Every token available in the contract must have a route defined. Route refers to which markets `token A` will go through in order to get `token B`. For example, if you would like to support swapping between ATOM and INJ, then you would have to set route by providing the contract the market IDs of ATOM/USDT and INJ/USDT, so that the it knows the route of swapping between ATOM and INJ would be ATOM ⇔ USDT ⇔ INJ. - -At this moment, the contract can only support markets quoted in USDT. - -#### 3. How much buffer should be provided to this contract? - -As the contract owner, you also have to provide funds to the contract which will be used when the swap happens. The buffer is used by the contract when it place orders. If the user wants to swap a big amount or swap in an illiquid market, then more buffer is required. An error will occur when the contract buffer cannot satisfy the user's input amount. - -At this moment, the buffer should only be USDT. - -### Messages - -#### Instantiate - -Initializes the contract state with the contract version and configuration details. The config includes an administrator address and a fee recipient address. - -```rust -pub fn instantiate( - deps: DepsMut, - env: Env, - info: MessageInfo, - msg: InstantiateMsg, -) -> Result, ContractError> -``` - -#### Execute - -Handles different types of transactions and admin functions: - -* SwapMinOutput: Swap with the minimum output quantity. -* SwapExactOutput: Swap with an exact output quantity. -* SetRoute: Set a swap route. -* DeleteRoute: Delete a swap route. -* UpdateConfig: Update the contract configuration. -* WithdrawSupportFunds: Withdraw the support funds from the contract. - -```rust -pub fn execute( - deps: DepsMut, - env: Env, - info: MessageInfo, - msg: ExecuteMsg, -) -> Result, ContractError> -``` - -#### Reply - -Handles the replies from other contracts or transactions. - -```rust -pub fn reply( - deps: DepsMut, - env: Env, - msg: Reply, -) -> Result, ContractError> -``` - -#### Query - -Handles various queries to the contract: - -* GetRoute: Get a specific swap route. -* GetOutputQuantity: Get the output quantity for a given input quantity. -* GetInputQuantity: Get the input quantity for a given output quantity. -* GetAllRoutes: Get all available swap routes. - -```rust -pub fn query(deps: Deps, env: Env, msg: QueryMsg) -> StdResult -``` - -### Repo - -The complete GitHub repository for the swap contract can be found [here](https://github.com/InjectiveLabs/swap-contract). diff --git a/.gitbook/developers/cosmwasm-developers/guides/creating-uis.md b/.gitbook/developers/cosmwasm-developers/guides/creating-uis.md deleted file mode 100644 index ffda4ae2..00000000 --- a/.gitbook/developers/cosmwasm-developers/guides/creating-uis.md +++ /dev/null @@ -1,19 +0,0 @@ -# Creating UIs - -{% hint style="info" %} -More comprehensive docs about creating UIs as well as bootstraping options can be found on the [TypeScript docs](https://docs.ts.injective.network/building-dapps/dapps-examples). -{% endhint %} - -We've interacted with our contract through the Injective CLI, but this is not ideal for most dApp users. A web UI can provide a much better experience! Rather than sending transaction messages through `injectived`, we can abstract away the complexity and provide the user with two buttons—one to increment the count, and one to reset the count. - -![](https://docs.injective.network/img/Counter\_website.png) - -For example, see the [counter website](https://injective-simple-cosmwasm-sc.netlify.app/). A high level guide on developing the frontend using Vue and the [Injective TS SDK](https://github.com/InjectiveLabs/injective-ts/tree/master/packages/sdk-ts) can be found in the [website repo here](https://github.com/InjectiveLabs/injective-simple-sc-counter-ui/tree/master/nuxt). For a React implementation, see [here](https://github.com/InjectiveLabs/injective-simple-sc-counter-ui/tree/master/next). - -Now, interacting with the contract is as simple as clicking a button and signing with MetaMask (make sure the account is set to Ethereum Goerli Testnet or you will receive a chain ID mismatch error). - -![](https://docs.injective.network/img/metamask\_select\_testnet.png) - -{% hint style="info" %} -You may notice that you get an "Unauthorized" error message when attempting to reset the count. This is expected behavior! Recall from the [contract logic for reset](https://docs.injective.network/develop/guides/injective-101/your-first-contract#reset) that only the contract owner is permitted to reset the count. Since you did not instantiate the exact contract that the frontend is interacting with, you don't have the required permissions to reset the count. -{% endhint %} diff --git a/.gitbook/developers/cosmwasm-developers/guides/local-development.md b/.gitbook/developers/cosmwasm-developers/guides/local-development.md deleted file mode 100644 index 1f261f78..00000000 --- a/.gitbook/developers/cosmwasm-developers/guides/local-development.md +++ /dev/null @@ -1,457 +0,0 @@ -# Local Development - -This guide will get you started deploying `cw20` smart contracts on a local Injective network running on your computer. - -We'll use the `cw20-base` contract from [CosmWasm's collection of specifications and contracts](https://github.com/CosmWasm/cw-plus) designed for production use on real networks. `cw20-base` is a basic implementation of a `cw20` compatible contract that can be imported in any custom contract you want to build on. It contains a straightforward but complete implementation of the cw20 spec along with all extensions. `cw20-base` can be deployed as-is or imported by other contracts. - -### Prerequisites - -Install Go, Rust, and other Cosmwasm dependencies by following the instructions: - -1. [Go](https://docs.cosmwasm.com/docs/getting-started/installation#go) -2. [Rust](https://docs.cosmwasm.com/docs/getting-started/installation#rust) - -Before starting, make sure you have [`rustup`](https://rustup.rs/) along with recent versions of `rustc` and `cargo` installed. Currently, we are testing on Rust v1.58.1+. - -You also need to have the `wasm32-unknown-unknown` target installed as well as the `cargo-generate` Rust crate. - -You can check versions via the following commands: - -```bash -rustc --version -cargo --version -rustup target list --installed -# if wasm32 is not listed above, run this -rustup target add wasm32-unknown-unknown -# to install cargo-generate, run this -cargo install cargo-generate -``` - -### injectived - -Make sure you have `injectived` installed locally. You can follow the [install-injectived.md](../../../toolkits/injectived/install-injectived.md "mention")guide to get `injectived` and other prerequisites running locally. - -Once you have `injectived` installed, you should also [start a local chain instance.](../../../toolkits/injectived/install-injectived.md#start-injectived) - -### Compile CosmWasm Contracts - -In this step, we will get all CW production template contracts and compile them using the [CosmWasm Rust Optimizer](https://github.com/CosmWasm/rust-optimizer) Docker image for compiling multiple contracts (called `workspace-optimizer`)—see [here](https://hub.docker.com/r/cosmwasm/workspace-optimizer/tags) (x86) or [here](https://hub.docker.com/r/cosmwasm/workspace-optimizer-arm64/tags) (ARM) for latest versions. This process may take a bit of time and CPU power. - -```bash -git clone https://github.com/CosmWasm/cw-plus -cd cw-plus -``` - -Non ARM (Non-Apple silicon) devices: - -```bash -docker run --rm -v "$(pwd)":/code \ ---mount type=volume,source="$(basename "$(pwd)")_cache",target=/code/target \ ---mount type=volume,source=registry_cache,target=/usr/local/cargo/registry \ -cosmwasm/workspace-optimizer:0.12.12 -``` - -Alternatively for Apple silicon devices (M1, M2, etc.) please use: - -```bash -docker run --rm -v "$(pwd)":/code \ ---mount type=volume,source="$(basename "$(pwd)")_cache",target=/code/target \ ---mount type=volume,source=registry_cache,target=/usr/local/cargo/registry \ -cosmwasm/workspace-optimizer-arm64:0.12.12 -``` - -The docker script builds and optimizes all the CW contracts in the repo, with the compiled contracts located under the `artifacts` directory. Now we can deploy the `cw20_base.wasm` contract (`cw20_base-aarch64.wasm` if compiled on an ARM device). - -### Upload the CosmWasm Contract to the Chain - -```bash -# inside the CosmWasm/cw-plus repo -yes 12345678 | injectived tx wasm store artifacts/cw20_base.wasm --from=genesis --chain-id="injective-1" --yes --gas-prices=500000000inj --gas=20000000 -``` - -**Output:** - -``` -code: 0 -codespace: "" -data: "" -events: [] -gas_used: "0" -gas_wanted: "0" -height: "0" -info: "" -logs: [] -raw_log: '[]' -timestamp: "" -tx: null -txhash: 4CFB63A47570C4CFBE8E669273B26BEF6EAFF922C07480CA42180C52219CE784 -``` - -Then query the transaction by the `txhash` to verify the contract was indeed deployed. - -```bash -injectived query tx 4CFB63A47570C4CFBE8E669273B26BEF6EAFF922C07480CA42180C52219CE784 -``` - -**Output:** - -```bash -code: 0 -codespace: "" -data: 0A460A1E2F636F736D7761736D2E7761736D2E76312E4D736753746F7265436F64651224080112205F8201CF5E2D7E6C15DB11ADF03D62DDDDC92B8D4FAE98C4F3C1C37F378E15D9 -events: -- attributes: - - index: true - key: YWNjX3NlcQ== - value: aW5qMTByZHN4ZGdyOGw4czBndnU4cnluaHUyMm5ueGtmeXRnNThjd204LzE= - type: tx -- attributes: - - index: true - key: c2lnbmF0dXJl - value: R29McmoxaDBtelNWN085SUNScStLbDdCVmdocDB6aU5EQ0Jwc1dFS1I1TlNXZkR2V1ZJejF0TEpGb0ZwSzlhNkFIQVdSVkZRNjExYitwSHdpY04wN1FFPQ== - type: tx -- attributes: - - index: true - key: c3BlbmRlcg== - value: aW5qMTByZHN4ZGdyOGw4czBndnU4cnluaHUyMm5ueGtmeXRnNThjd204 - - index: true - key: YW1vdW50 - value: MTAwMDAwMDAwMDAwMDAwMDBpbmo= - type: coin_spent -- attributes: - - index: true - key: cmVjZWl2ZXI= - value: aW5qMTd4cGZ2YWttMmFtZzk2MnlsczZmODR6M2tlbGw4YzVsNnM1eWU5 - - index: true - key: YW1vdW50 - value: MTAwMDAwMDAwMDAwMDAwMDBpbmo= - type: coin_received -- attributes: - - index: true - key: cmVjaXBpZW50 - value: aW5qMTd4cGZ2YWttMmFtZzk2MnlsczZmODR6M2tlbGw4YzVsNnM1eWU5 - - index: true - key: c2VuZGVy - value: aW5qMTByZHN4ZGdyOGw4czBndnU4cnluaHUyMm5ueGtmeXRnNThjd204 - - index: true - key: YW1vdW50 - value: MTAwMDAwMDAwMDAwMDAwMDBpbmo= - type: transfer -- attributes: - - index: true - key: c2VuZGVy - value: aW5qMTByZHN4ZGdyOGw4czBndnU4cnluaHUyMm5ueGtmeXRnNThjd204 - type: message -- attributes: - - index: true - key: ZmVl - value: MTAwMDAwMDAwMDAwMDAwMDBpbmo= - - index: true - key: ZmVlX3BheWVy - value: aW5qMTByZHN4ZGdyOGw4czBndnU4cnluaHUyMm5ueGtmeXRnNThjd204 - type: tx -- attributes: - - index: true - key: YWN0aW9u - value: L2Nvc213YXNtLndhc20udjEuTXNnU3RvcmVDb2Rl - type: message -- attributes: - - index: true - key: bW9kdWxl - value: d2FzbQ== - - index: true - key: c2VuZGVy - value: aW5qMTByZHN4ZGdyOGw4czBndnU4cnluaHUyMm5ueGtmeXRnNThjd204 - type: message -- attributes: - - index: true - key: Y29kZV9jaGVja3N1bQ== - value: NWY4MjAxY2Y1ZTJkN2U2YzE1ZGIxMWFkZjAzZDYyZGRkZGM5MmI4ZDRmYWU5OGM0ZjNjMWMzN2YzNzhlMTVkOQ== - - index: true - key: Y29kZV9pZA== - value: MQ== - type: store_code -- attributes: - - index: true - key: YWNjZXNzX2NvbmZpZw== - value: eyJwZXJtaXNzaW9uIjoiRXZlcnlib2R5IiwiYWRkcmVzcyI6IiIsImFkZHJlc3NlcyI6W119 - - index: true - key: Y2hlY2tzdW0= - value: Ilg0SUJ6MTR0Zm13VjJ4R3Q4RDFpM2QzSks0MVBycGpFODhIRGZ6ZU9GZGs9Ig== - - index: true - key: Y29kZV9pZA== - value: IjEi - - index: true - key: Y3JlYXRvcg== - value: ImluajEwcmRzeGRncjhsOHMwZ3Z1OHJ5bmh1MjJubnhrZnl0ZzU4Y3dtOCI= - type: cosmwasm.wasm.v1.EventCodeStored -gas_used: "2158920" -gas_wanted: "20000000" -height: "47" -info: "" -logs: -- events: - - attributes: - - key: access_config - value: '{"permission":"Everybody","address":"","addresses":[]}' - - key: checksum - value: '"X4IBz14tfmwV2xGt8D1i3d3JK41PrpjE88HDfzeOFdk="' - - key: code_id - value: '"1"' - - key: creator - value: '"inj10rdsxdgr8l8s0gvu8rynhu22nnxkfytg58cwm8"' - type: cosmwasm.wasm.v1.EventCodeStored - - attributes: - - key: action - value: /cosmwasm.wasm.v1.MsgStoreCode - - key: module - value: wasm - - key: sender - value: inj10rdsxdgr8l8s0gvu8rynhu22nnxkfytg58cwm8 - type: message - - attributes: - - key: code_checksum - value: 5f8201cf5e2d7e6c15db11adf03d62ddddc92b8d4fae98c4f3c1c37f378e15d9 - - key: code_id - value: "1" - type: store_code - log: "" - msg_index: 0 -raw_log: '[{"events":[{"type":"cosmwasm.wasm.v1.EventCodeStored","attributes":[{"key":"access_config","value":"{\"permission\":\"Everybody\",\"address\":\"\",\"addresses\":[]}"},{"key":"checksum","value":"\"X4IBz14tfmwV2xGt8D1i3d3JK41PrpjE88HDfzeOFdk=\""},{"key":"code_id","value":"\"1\""},{"key":"creator","value":"\"inj10rdsxdgr8l8s0gvu8rynhu22nnxkfytg58cwm8\""}]},{"type":"message","attributes":[{"key":"action","value":"/cosmwasm.wasm.v1.MsgStoreCode"},{"key":"module","value":"wasm"},{"key":"sender","value":"inj10rdsxdgr8l8s0gvu8rynhu22nnxkfytg58cwm8"}]},{"type":"store_code","attributes":[{"key":"code_checksum","value":"5f8201cf5e2d7e6c15db11adf03d62ddddc92b8d4fae98c4f3c1c37f378e15d9"},{"key":"code_id","value":"1"}]}]}]' -timestamp: "2023-03-06T15:48:30Z" -tx: - '@type': /cosmos.tx.v1beta1.Tx - auth_info: - fee: - amount: - - amount: "10000000000000000" - denom: inj - gas_limit: "20000000" - granter: "" - payer: "" - signer_infos: - - mode_info: - single: - mode: SIGN_MODE_DIRECT - public_key: - '@type': /injective.crypto.v1beta1.ethsecp256k1.PubKey - key: Ay+cc/lvd4Mn4pbgFkN87vWDaCXuXjVJYJGsdhrD09vk - sequence: "1" - body: - extension_options: [] - memo: "" - messages: - - '@type': /cosmwasm.wasm.v1.MsgStoreCode - instantiate_permission: null - sender: inj10rdsxdgr8l8s0gvu8rynhu22nnxkfytg58cwm8 - wasm_byte_code: YOUR_WASM_BYTE_HERE - non_critical_extension_options: [] - timeout_height: "0" - signatures: - - GoLrj1h0mzSV7O9ICRq+Kl7BVghp0ziNDCBpsWEKR5NSWfDvWVIz1tLJFoFpK9a6AHAWRVFQ611b+pHwicN07QE= -txhash: 4CFB63A47570C4CFBE8E669273B26BEF6EAFF922C07480CA42180C52219CE784 -``` - -Inspecting the output more closely, we can see the `code_id` of 1 for the contract - -```bash -logs: -- events: - - attributes: - - key: access_config - value: '{"permission":"Everybody","address":"","addresses":[]}' - - key: checksum - value: '"X4IBz14tfmwV2xGt8D1i3d3JK41PrpjE88HDfzeOFdk="' - - key: code_id - value: '"1"' - - key: creator - value: '"inj10rdsxdgr8l8s0gvu8rynhu22nnxkfytg58cwm8"' - type: cosmwasm.wasm.v1.EventCodeStored - - attributes: - - key: action - value: /cosmwasm.wasm.v1.MsgStoreCode - - key: module - value: wasm - - key: sender - value: inj10rdsxdgr8l8s0gvu8rynhu22nnxkfytg58cwm8 - type: message - - attributes: - - key: code_checksum - value: 5f8201cf5e2d7e6c15db11adf03d62ddddc92b8d4fae98c4f3c1c37f378e15d9 - - key: code_id - value: "1" - type: store_code - log: "" - msg_index: 0 -``` - -We’ve uploaded the contract code, but we still need to instantiate the contract. - -### Instantiate the Contract - -Before instantiating the contract, let's take a look at the CW-20 contract function signature for `instantiate`. - -```rust -#[cfg_attr(not(feature = "library"), entry_point)] -pub fn instantiate( - mut deps: DepsMut, - _env: Env, - _info: MessageInfo, - msg: InstantiateMsg, -) -> Result { -``` - -Notably, it contains the `InstantiateMsg` parameter which contains the token name, symbol, decimals, and other details. - -```rust -#[derive(Serialize, Deserialize, JsonSchema, Debug, Clone, PartialEq)] -pub struct InstantiateMsg { - pub name: String, - pub symbol: String, - pub decimals: u8, - pub initial_balances: Vec, - pub mint: Option, - pub marketing: Option, -} -``` - -The first step of instantiating the contract is to select an address to supply with our initial CW20 token allocation. In our case, we can just use the genesis address since we have the keys already set up, but feel free to generate new addresses and keys. - -{% hint style="warning" %} -Make sure you have the private keys for the address you choose—you won't be able to test token transfers from the address otherwise. In addition, the chosen address must be a valid address on the chain (the address must have received funds at some point in the past) and must have balances to pay for gas when executing the contract. -{% endhint %} - -To find the genesis address, run: - -```bash -yes 12345678 | injectived keys show genesis -``` - -**Output:** - -```bash -- name: genesis - type: local - address: inj10cfy5e6qt2zy55q2w2ux2vuq862zcyf4fmfpj3 - pubkey: '{"@type":"/injective.crypto.v1beta1.ethsecp256k1.PubKey","key":"ArtVkg9feLXjD4p6XRtWxVpvJUDhrcqk/5XYLsQI4slb"}' - mnemonic: "" -``` - -Run the CLI command with `code_id` `1` along with the JSON encoded initialization arguments (with your selected address) and a label (a human-readable name for this contract in lists) to instantiate the contract: - -```bash -CODE_ID=1 -INIT='{"name":"Albcoin","symbol":"ALB","decimals":6,"initial_balances":[{"address":"inj10cfy5e6qt2zy55q2w2ux2vuq862zcyf4fmfpj3","amount":"69420"}],"mint":{"minter":"inj10cfy5e6qt2zy55q2w2ux2vuq862zcyf4fmfpj3"},"marketing":{}}' -yes 12345678 | injectived tx wasm instantiate $CODE_ID $INIT --label="Albcoin Token" --from=genesis --chain-id="injective-1" --yes --gas-prices=500000000inj --gas=20000000 --no-admin -``` - -Now the address of the instantiated contract can be obtained on [http://localhost:10337/swagger/#/Query/ContractsByCode](http://localhost:10337/swagger/#/Query/ContractsByCode) - -And the contract info meta data can be obtained on [http://localhost:10337/swagger/#/Query/ContractInfo](http://localhost:10337/swagger/#/Query/ContractInfo) or by CLI query - -```bash -CONTRACT=$(injectived query wasm list-contract-by-code $CODE_ID --output json | jq -r '.contracts[-1]') -injectived query wasm contract $CONTRACT -``` - -**Output:** - -```bash -injectived query wasm contract $CONTRACT -address: inj14hj2tavq8fpesdwxxcu44rty3hh90vhujaxlnz -contract_info: - admin: "" - code_id: "1" - created: - block_height: "95" - tx_index: "0" - creator: inj10rdsxdgr8l8s0gvu8rynhu22nnxkfytg58cwm8 - extension: null - ibc_port_id: "" - label: Albcoin Token -``` - -### Querying the contract - -The entire contract state can be queried with: - -```bash -injectived query wasm contract-state all $CONTRACT -``` - -**Output:** - -```bash -models: -- key: 000762616C616E6365696E6A31306366793565367174327A793535713277327578327675713836327A63796634666D66706A33 - value: IjY5NDIwIg== -- key: 636F6E74726163745F696E666F - value: eyJjb250cmFjdCI6ImNyYXRlcy5pbzpjdzIwLWJhc2UiLCJ2ZXJzaW9uIjoiMS4wLjEifQ== -- key: 6D61726B6574696E675F696E666F - value: eyJwcm9qZWN0IjpudWxsLCJkZXNjcmlwdGlvbiI6bnVsbCwibG9nbyI6bnVsbCwibWFya2V0aW5nIjpudWxsfQ== -- key: 746F6B656E5F696E666F - value: eyJuYW1lIjoiQWxiY29pbiIsInN5bWJvbCI6IkFMQiIsImRlY2ltYWxzIjo2LCJ0b3RhbF9zdXBwbHkiOiI2OTQyMCIsIm1pbnQiOnsibWludGVyIjoiaW5qMTBjZnk1ZTZxdDJ6eTU1cTJ3MnV4MnZ1cTg2MnpjeWY0Zm1mcGozIiwiY2FwIjpudWxsfX0= -pagination: - next_key: null - total: "0" -``` - -The individual user’s token balance can also be queried with: - -```bash -BALANCE_QUERY='{"balance": {"address": "inj10cfy5e6qt2zy55q2w2ux2vuq862zcyf4fmfpj3"}}' -injectived query wasm contract-state smart $CONTRACT "$BALANCE_QUERY" --output json -``` - -**Output:** - -```bash -{"data":{"balance":"69420"}} -``` - -### Transferring Tokens - -```bash -TRANSFER='{"transfer":{"recipient":"inj1dzqd00lfd4y4qy2pxa0dsdwzfnmsu27hgttswz","amount":"420"}}' -yes 12345678 | injectived tx wasm execute $CONTRACT "$TRANSFER" --from genesis --chain-id="injective-1" --yes --gas-prices=500000000inj --gas=20000000 -``` - -Then confirm the balance transfer occurred successfully with: - -```bash -# first address balance query -BALANCE_QUERY='{"balance": {"address": "inj10cfy5e6qt2zy55q2w2ux2vuq862zcyf4fmfpj3"}}' -injectived query wasm contract-state smart $CONTRACT "$BALANCE_QUERY" --output json -``` - -**Output:** - -```bash -{"data":{"balance":"69000"}} -``` - -And confirm the recipient received the funds: - -```bash -# recipient's address balance query -BALANCE_QUERY='{"balance": {"address": "inj1dzqd00lfd4y4qy2pxa0dsdwzfnmsu27hgttswz"}}' -injectived query wasm contract-state smart $CONTRACT "$BALANCE_QUERY" --output json -``` - -**Output:** - -```bash -{"data":{"balance":"420"}} -``` - -## Testnet Development - -Here are the main differences between a `local` and `testnet` development/deployment - -* You can use our [Injective Testnet Faucet](https://testnet.faucet.injective.network) to get testnet funds to your address, -* You can use the [Injective Testnet Explorer](https://testnet.explorer.injective.network/codes/) to query your transactions and get more details, -* When you are using `injectived` you have to specify the `testnet` rpc using the `node` flag `--node=https://testnet.sentry.tm.injective.network:443` -* Instead of using `injective-1` as a `chainId` you should use `injective-888` i.e the `chain-id` flag should now be `--chain-id="injective-888"` -* You can use the [Injective Testnet Explorer](https://testnet.explorer.injective.network/codes/) to find information about the `codeId` of the uploaded smart contracts OR find your instantiated smart contract - -You can read more on the `injectived` and how to use it to query/send transactions against `testnet` [using-injectived.md](../../../toolkits/injectived/using-injectived.md "mention"). diff --git a/.gitbook/developers/cosmwasm-developers/guides/mainnet-deployment.md b/.gitbook/developers/cosmwasm-developers/guides/mainnet-deployment.md deleted file mode 100644 index c8a07da1..00000000 --- a/.gitbook/developers/cosmwasm-developers/guides/mainnet-deployment.md +++ /dev/null @@ -1,170 +0,0 @@ -# Mainnet Deployment - -This guide will get you started with the governance process of deploying and instantiating CosmWasm smart contracts on Injective Mainnet. - -### Submit a Code Upload Proposal - -In this section, you will learn how to submit a smart contract code proposal and vote for it. - -Injective network participants can propose smart contracts deployments and vote in governance to enable them. The `wasmd` authorization settings are by on-chain governance, which means deployment of a contract is completely determined by governance. Because of this, a governance proposal is the first step to uploading contracts to Injective mainnet. - -Sample usage of `injectived` to start a governance proposal to upload code to the chain: - -```bash -injectived tx wasm submit-proposal wasm-store artifacts/cw_controller.wasm ---title="Proposal Title" \ ---summary="Proposal Summary" \ ---instantiate-everybody true \ ---broadcast-mode=sync \ ---chain-id=injective-1 \ ---node=https://sentry.tm.injective.network:443 \ ---deposit=100000000000000000000inj \ ---gas=20000000 \ ---gas-prices=160000000inj \ ---from [YOUR_KEY] \ ---yes \ ---output json -``` - -The command `injectived tx gov submit-proposal wasm-store` submits a wasm binary proposal. The code will be deployed if the proposal is approved by governance. - -Let’s go through two key flags `instantiate-everybody` and `instantiate-only-address`, which set instantiation permissions of the uploaded code. By default, everyone can instantiate the contract. - -```bash ---instantiate-everybody boolean # Everybody can instantiate a contract from the code, optional ---instantiate-only-address string # Only this address can instantiate a contract instance from the code -``` - -### Contract Instantiation (No Governance) - -In most cases, you don’t need to push another governance proposal to instantiate. Simply instantiate with `injectived tx wasm instantiate`. You only need a governance proposal to _upload_ a contract. You don’t need to go through governance to instantiate unless if the contract has the `--instantiate-everybody` flag to set to `false`, and `--instantiate-only-address` flag set to the governance module. The default value for `--instantiate-everybody` is `true`, and in this case you can permissionlessly instantiate via `injectived tx wasm instantiate`. - -```bash -injectived tx wasm instantiate [code_id_int64] [json_encoded_init_args] --label [text] --admin [address,optional] --amount [coins,optional] [flags] -``` - -```bash -Flags: - -a, --account-number uint The account number of the signing account (offline mode only) - --admin string Address or key name of an admin - --amount string Coins to send to the contract during instantiation - --aux Generate aux signer data instead of sending a tx - -b, --broadcast-mode string Transaction broadcasting mode (sync|async) (default "sync") - --chain-id string The network chain ID - --dry-run ignore the --gas flag and perform a simulation of a transaction, but don't broadcast it (when enabled, the local Keybase is not accessible) - --fee-granter string Fee granter grants fees for the transaction - --fee-payer string Fee payer pays fees for the transaction instead of deducting from the signer - --fees string Fees to pay along with transaction; eg: 10uatom - --from string Name or address of private key with which to sign - --gas string gas limit to set per-transaction; set to "auto" to calculate sufficient gas automatically. Note: "auto" option doesn't always report accurate results. Set a valid coin value to adjust the result. Can be used instead of "fees". (default 200000) - --gas-adjustment float adjustment factor to be multiplied against the estimate returned by the tx simulation; if the gas limit is set manually this flag is ignored (default 1) - --gas-prices string Gas prices in decimal format to determine the transaction fee (e.g. 0.1uatom) - --generate-only Build an unsigned transaction and write it to STDOUT (when enabled, the local Keybase only accessed when providing a key name) - -h, --help help for instantiate - --keyring-backend string Select keyring's backend (os|file|kwallet|pass|test|memory) (default "os") - --keyring-dir string The client Keyring directory; if omitted, the default 'home' directory will be used - --label string A human-readable name for this contract in lists - --ledger Use a connected Ledger device - --no-admin You must set this explicitly if you don't want an admin - --node string : to tendermint rpc interface for this chain (default "tcp://localhost:26657") - --note string Note to add a description to the transaction (previously --memo) - --offline Offline mode (does not allow any online functionality) - -o, --output string Output format (text|json) (default "json") - -s, --sequence uint The sequence number of the signing account (offline mode only) - --sign-mode string Choose sign mode (direct|amino-json|direct-aux), this is an advanced feature - --timeout-height uint Set a block timeout height to prevent the tx from being committed past a certain height - --tip string Tip is the amount that is going to be transferred to the fee payer on the target chain. This flag is only valid when used with --aux, and is ignored if the target chain didn't enable the TipDecorator - -y, --yes Skip tx broadcasting prompt confirmation -``` - -An example `injectived tx wasm instantiate` can look something like this: - -```bash -injectived tx wasm instantiate \ -150 \ -'{"bank": "inj1egl894wme0d4d029hlv3kuqs0mc9atep2s89h8"}' \ ---label="LABEL" \ ---from=inj17vytdwqczqz72j65saukplrktd4gyfme5agf6c \ ---chain-id=injective-1 \ ---yes \ ---gas-prices 160000000inj \ ---gas=10000000 \ ---no-admin \ ---node=https://sentry.tm.injective.network:443 \ -``` - -### Contract Instantiation (Governance) - -As mentioned above, contract instantiation permissions on mainnet depend on the flags used when uploading the code. By default, it is set to permissionless, as we can verify on the genesis `wasmd` Injective setup: - -```json -"wasm": { - "codes": [], - "contracts": [], - "gen_msgs": [], - "params": { - "code_upload_access": { - "address": "", - "permission": "Everybody" - }, - "instantiate_default_permission": "Everybody" - }, - "sequences": [] - } -``` - -However, if the `--instantiate-everybody` flag is set to `false`, then the contract instantiation must go through governance. - -{% hint style="info" %} -The Injective testnet is permissionless by default in order to allow developers to easily deploy contracts. -{% endhint %} - -#### Contract Instantiation Proposal - -```bash - injectived tx gov submit-proposal instantiate-contract [code_id_int64] [json_encoded_init_args] --label [text] --title [text] --description [text] --run-as [address] --admin [address,optional] --amount [coins,optional] [flags] -``` - -```bash -Flags: - -a, --account-number uint The account number of the signing account (offline mode only) - --admin string Address of an admin - --amount string Coins to send to the contract during instantiation - -b, --broadcast-mode string Transaction broadcasting mode (sync|async|block) (default "sync") - --deposit string Deposit of proposal - --description string Description of proposal - --dry-run ignore the --gas flag and perform a simulation of a transaction, but dont broadcast it (when enabled, the local Keybase is not accessible) - --fee-account string Fee account pays fees for the transaction instead of deducting from the signer - --fees string Fees to pay along with transaction; eg: 10uatom - --from string Name or address of private key with which to sign - --gas string gas limit to set per-transaction; set to "auto" to calculate sufficient gas automatically (default 200000) - --gas-adjustment float adjustment factor to be multiplied against the estimate returned by the tx simulation; if the gas limit is set manually this flag is ignored (default 1) - --gas-prices string Gas prices in decimal format to determine the transaction fee (e.g. 0.1uatom) - --generate-only Build an unsigned transaction and write it to STDOUT (when enabled, the local Keybase is not accessible) - -h, --help help for instantiate-contract - --keyring-backend string Select keyrings backend (os|file|kwallet|pass|test|memory) (default "os") - --keyring-dir string The client Keyring directory; if omitted, the default 'home' directory will be used - --label string A human-readable name for this contract in lists - --ledger Use a connected Ledger device - --no-admin You must set this explicitly if you dont want an admin - --node string : to tendermint rpc interface for this chain (default "tcp://localhost:26657") - --note string Note to add a description to the transaction (previously --memo) - --offline Offline mode (does not allow any online functionality - -o, --output string Output format (text|json) (default "json") - --proposal string Proposal file path (if this path is given, other proposal flags are ignored) - --run-as string The address that pays the init funds. It is the creator of the contract and passed to the contract as sender on proposal execution - -s, --sequence uint The sequence number of the signing account (offline mode only) - --sign-mode string Choose sign mode (direct|amino-json), this is an advanced feature - --timeout-height uint Set a block timeout height to prevent the tx from being committed past a certain height - --title string Title of proposal - --type string Permission of proposal, types: store-code/instantiate/migrate/update-admin/clear-admin/text/parameter_change/software_upgrade - -y, --yes Skip tx broadcasting prompt confirmation -``` - -### Contract Migration - -Migration is the process through which a given smart contract's code can be swapped out or 'upgraded'. - -When instantiating a contract, there is an optional admin field that you can set. If it is left empty, the contract is immutable. If the admin is set (to an external account or governance contract), that account can trigger a migration. The admin can also reassign the admin role, or even make the contract fully immutable if desired. However, keep in mind that when migrating from an old contract to a new contract, the new contract needs to be aware of how the state was previously encoded. - -A more detailed description of the technical aspects of migration can be found in the [CosmWasm migration documentation](https://docs.cosmwasm.com/docs/smart-contracts/migration). diff --git a/.gitbook/developers/cosmwasm-developers/guides/whitelisting-deployment-address.md b/.gitbook/developers/cosmwasm-developers/guides/whitelisting-deployment-address.md deleted file mode 100644 index 6187e3e8..00000000 --- a/.gitbook/developers/cosmwasm-developers/guides/whitelisting-deployment-address.md +++ /dev/null @@ -1,33 +0,0 @@ -# Whitelisting deployment address - -Contract upload on Injective mainnet requires governance approval. You can read through the guide to do so in the [mainnet-deployment.md](mainnet-deployment.md "mention") guide. - -This structure has been put in place for multiple reasons: - -1. Historically, the community has discovered vulnerabilities in CosmWasm whereby certain contracts could cause a chain halt. Thus, requiring approval will be inherently more secure until the language matures and stabilizes over time. -2. Governance prevents un-audited and bogus contracts from being deployed into the network ensuring that hacks and scams will occur at a lesser degree. -3. This results in a more curated experience for ecosystem users since the blockchain does not fill up with unwanted transactions and contracts. - -This governance process is time-consuming for validators and the community. Injective builders additionally face a 4-day wait to roll out features, affecting developer experience and user growth. - -As of the Altaris chain upgrade, it is now possible to request whitelisting your address for contract uploads. - -## Submission Guidelines - -To be considered for a whitelist approval, it is strongly recommended to include all the following information in the governance proposal. Validators are recommended to contact the Foundation in Discord to verify the information submitted for each proposal before voting. - -1. Are the identities of the team members known to the community? -2. Has the team completed KYC/KYB with the Injective Foundation? -3. How long has the protocol been live on Injective mainnet? -4. Has the team developed applications in other ecosystems? (provide the details) - -## Voting Guidelines - -Users that meet these criteria will have a greater chance at receiving whitelist permissions: - -1. The project has completed Injective Foundation KYC/KYB and the team members' identities are known to the community. _Exception: Anonymous developers with proven credibility and successful apps in other ecosystems._ -2. The project has been live on mainnet for at least 1 month and has achieved significant TVL/usage. - -## Operational Guidelines - -It is strongly recommended to use a multisig or Ledger wallet for the whitelisted uploads. diff --git a/.gitbook/developers/cosmwasm-developers/injective-test-tube.md b/.gitbook/developers/cosmwasm-developers/injective-test-tube.md deleted file mode 100644 index 4b83b90a..00000000 --- a/.gitbook/developers/cosmwasm-developers/injective-test-tube.md +++ /dev/null @@ -1,335 +0,0 @@ -# Injective Test Tube - -`injective-test-tube` is a CosmWasm x Injective integration testing library that, unlike `cw-multi-test`, allows you to test your CosmWasm contract against the chain's actual logic instead of mocks. - -The `dev` branch depends on currently private repos, but you can use published versions instead. Please refer to [`CHANGELOG`](https://github.com/InjectiveLabs/test-tube/blob/dev/packages/injective-test-tube/CHANGELOG.md) for features and update information. - -### Getting Started - -To demonstrate how `injective-test-tube` works, let us use a simple example contract: [cw-whitelist](https://github.com/CosmWasm/cw-plus/tree/main/contracts/cw1-whitelist) from `cw-plus`. - -Here is how to setup the test: - -```rust -use cosmwasm_std::Coin; -use injective_test_tube::InjectiveTestApp; - -// create new injective appchain instance. -let app = InjectiveTestApp::new(); - -// create new account with initial funds -let accs = app - .init_accounts( - &[ - Coin::new(1_000_000_000_000, "usdt"), - Coin::new(1_000_000_000_000, "inj"), - ], - 2, - ) - .unwrap(); - -let admin = &accs[0]; -let new_admin = &accs[1]; -``` - -Now we have the appchain instance and accounts that have some initial balances and can interact with the appchain. This does not run Docker instance or spawning external process, it just loads the appchain's code as a library to create an in memory instance. - -Note that `init_accounts` is a convenience function that creates multiple accounts with the same initial balance. If you want to create just one account, you can use `init_account` instead. - -```rust -use cosmwasm_std::Coin; -use injective_test_tube::InjectiveTestApp; - -let app = InjectiveTestApp::new(); - -let account = app.init_account(&[ - Coin::new(1_000_000_000_000, "usdt"), - Coin::new(1_000_000_000_000, "inj"), -]); -``` - -Now if we want to test a cosmwasm contract, we need to - -* build the wasm file -* store code -* instantiate - -Then we can start interacting with our contract. Let's do just that. - -```rust -use cosmwasm_std::Coin; -use cw1_whitelist::msg::{InstantiateMsg}; // for instantiating cw1_whitelist contract -use injective_test_tube::{Account, Module, InjectiveTestApp, Wasm}; - -let app = InjectiveTestApp::new(); -let accs = app - .init_accounts( - &[ - Coin::new(1_000_000_000_000, "usdt"), - Coin::new(1_000_000_000_000, "inj"), - ], - 2, - ) - .unwrap(); -let admin = &accs[0]; -let new_admin = &accs[1]; - -// ============= NEW CODE ================ - -// `Wasm` is the module we use to interact with cosmwasm related logic on the appchain -// it implements `Module` trait which you will see more later. -let wasm = Wasm::new(&app); - -// Load compiled wasm bytecode -let wasm_byte_code = std::fs::read("./test_artifacts/cw1_whitelist.wasm").unwrap(); -let code_id = wasm - .store_code(&wasm_byte_code, None, admin) - .unwrap() - .data - .code_id; -``` - -Not that in this example, it loads wasm bytecode from [cw-plus release](https://github.com/CosmWasm/cw-plus/releases) for simple demonstration purposes. You might want to run `cargo wasm` and find your wasm file in `target/wasm32-unknown-unknown/release/.wasm`. - -```rust -use cosmwasm_std::Coin; -use cw1_whitelist::msg::{InstantiateMsg, QueryMsg, AdminListResponse}; -use injective_test_tube::{Account, Module, InjectiveTestApp, Wasm}; - -let app = InjectiveTestApp::new(); -let accs = app - .init_accounts( - &[ - Coin::new(1_000_000_000_000, "usdt"), - Coin::new(1_000_000_000_000, "inj"), - ], - 2, - ) - .unwrap(); -let admin = &accs[0]; -let new_admin = &accs[1]; - -let wasm = Wasm::new(&app); - - -let wasm_byte_code = std::fs::read("./test_artifacts/cw1_whitelist.wasm").unwrap(); -let code_id = wasm - .store_code(&wasm_byte_code, None, admin) - .unwrap() - .data - .code_id; - -// ============= NEW CODE ================ - -// instantiate contract with initial admin and make admin list mutable -let init_admins = vec![admin.address()]; -let contract_addr = wasm - .instantiate( - code_id, - &InstantiateMsg { - admins: init_admins.clone(), - mutable: true, - }, - None, // contract admin used for migration, not the same as cw1_whitelist admin - Some("Test label"), // contract label - &[], // funds - admin, // signer - ) - .unwrap() - .data - .address; - -// query contract state to check if contract instantiation works properly -let admin_list = wasm - .query::(&contract_addr, &QueryMsg::AdminList {}) - .unwrap(); - -assert_eq!(admin_list.admins, init_admins); -assert!(admin_list.mutable); -``` - -Now let's execute the contract and verify that the contract's state is updated properly. - -```rust -use cosmwasm_std::Coin; -use cw1_whitelist::msg::{InstantiateMsg, QueryMsg, ExecuteMsg, AdminListResponse}; -use injective_test_tube::{Account, Module, InjectiveTestApp, Wasm}; - -let app = InjectiveTestApp::new(); -let accs = app - .init_accounts( - &[ - Coin::new(1_000_000_000_000, "usdt"), - Coin::new(1_000_000_000_000, "inj"), - ], - 2, - ) - .unwrap(); -let admin = &accs[0]; -let new_admin = &accs[1]; - -let wasm = Wasm::new(&app); - - -let wasm_byte_code = std::fs::read("./test_artifacts/cw1_whitelist.wasm").unwrap(); -let code_id = wasm - .store_code(&wasm_byte_code, None, admin) - .unwrap() - .data - .code_id; - -// instantiate contract with initial admin and make admin list mutable -let init_admins = vec![admin.address()]; -let contract_addr = wasm - .instantiate( - code_id, - &InstantiateMsg { - admins: init_admins.clone(), - mutable: true, - }, - None, // contract admin used for migration, not the same as cw1_whitelist admin - Some("Test label"), // contract label - &[], // funds - admin, // signer - ) - .unwrap() - .data - .address; - -let admin_list = wasm - .query::(&contract_addr, &QueryMsg::AdminList {}) - .unwrap(); - -assert_eq!(admin_list.admins, init_admins); -assert!(admin_list.mutable); - -// ============= NEW CODE ================ - -// update admin list and rechec the state -let new_admins = vec![new_admin.address()]; -wasm.execute::( - &contract_addr, - &ExecuteMsg::UpdateAdmins { - admins: new_admins.clone(), - }, - &[], - admin, -) -.unwrap(); - -let admin_list = wasm - .query::(&contract_addr, &QueryMsg::AdminList {}) - .unwrap(); - -assert_eq!(admin_list.admins, new_admins); -assert!(admin_list.mutable); -``` - -### Debugging - -In your contract code, if you want to debug, you can use [`deps.api.debug(..)`](https://docs.rs/cosmwasm-std/latest/cosmwasm\_std/trait.Api.html#tymethod.debug) which will print the debug message to stdout. `wasmd` disabled this by default but `InjectiveTestApp` allows stdout emission so that you can debug your smart contract while running tests. - -### Using Module Wrapper - -In some cases, you might want to interact directly with appchain logic to setup the environment or query appchain's state. Module wrappers provides convenient functions to interact with the appchain's module. - -Let's try to interact with `Exchange` module: - -```rust -use cosmwasm_std::{Addr, Coin}; -use injective_std::types::injective::exchange::v1beta1::{ - MarketStatus, MsgInstantSpotMarketLaunch, - QuerySpotMarketsRequest, QuerySpotMarketsResponse, SpotMarket, -}; -use injective_test_tube::{Account, Exchange, InjectiveTestApp}; -use test_tube_inj::Module; - -let app = InjectiveTestApp::new(); -let signer = app - .init_account(&[ - Coin::new(10_000_000_000_000_000_000_000u128, "inj"), - Coin::new(100_000_000_000_000_000_000u128, "usdt"), - ]) - .unwrap(); -let trader = app - .init_account(&[ - Coin::new(10_000_000_000_000_000_000_000u128, "inj"), - Coin::new(100_000_000_000_000_000_000u128, "usdt"), - ]) - .unwrap(); -let exchange = Exchange::new(&app); - -exchange - .instant_spot_market_launch( - MsgInstantSpotMarketLaunch { - sender: signer.address(), - ticker: "INJ/USDT".to_owned(), - base_denom: "inj".to_owned(), - quote_denom: "usdt".to_owned(), - min_price_tick_size: "10000".to_owned(), - min_quantity_tick_size: "100000".to_owned(), - }, - &signer, - ) - .unwrap(); - -exchange - .instant_spot_market_launch( - MsgInstantSpotMarketLaunch { - sender: signer.address(), - ticker: "INJ/USDT".to_owned(), - base_denom: "inj".to_owned(), - quote_denom: "usdt".to_owned(), - min_price_tick_size: "10000".to_owned(), - min_quantity_tick_size: "100000".to_owned(), - }, - &signer, - ) - .unwrap_err(); - -app.increase_time(1u64); - -let spot_markets = exchange - .query_spot_markets(&QuerySpotMarketsRequest { - status: "Active".to_owned(), - market_ids: vec![], - }) - .unwrap(); - -let expected_response = QuerySpotMarketsResponse { - markets: vec![SpotMarket { - ticker: "INJ/USDT".to_string(), - base_denom: "inj".to_string(), - quote_denom: "usdt".to_string(), - maker_fee_rate: "-100000000000000".to_string(), - taker_fee_rate: "1000000000000000".to_string(), - relayer_fee_share_rate: "400000000000000000".to_string(), - market_id: "0xd5a22be807011d5e42d5b77da3f417e22676efae494109cd01c242ad46630115" - .to_string(), - status: MarketStatus::Active.into(), - min_price_tick_size: "10000".to_string(), - min_quantity_tick_size: "100000".to_string(), - }], -}; -assert_eq!(spot_markets, expected_response); -``` - -Additional examples can be found in the [modules](https://github.com/InjectiveLabs/test-tube/tree/dev/packages/injective-test-tube/src/module)) directory. - -### Versioning - -The version of injective-test-tube is determined by the versions of its dependencies, injective and test-tube, as well as its own changes. The version is represented in the format A.B.C, where: - -* A is the major version of injective, -* B is the minor version of test-tube, -* C is the patch number of injective-test-tube itself. - -When a new version of injective is released and contains breaking changes, we will also release breaking changes from test-tube if any and increment the major version of injective-test-tube. This way, it's clear that the new version of injective-test-tube is not backwards-compatible with previous versions. - -When adding a new feature to injective-test-tube that is backward-compatible, the minor version number will be incremented. - -When fixing bugs or making other changes that are `injective-test-tube` specific and backward-compatible, the patch number will be incremented. - -Please review the upgrade guide for upgrading the package, in case of breaking changes - -It is important to note that we track the version of the package independent of the version of dependencies. diff --git a/.gitbook/developers/cosmwasm-developers/page-1.md b/.gitbook/developers/cosmwasm-developers/page-1.md deleted file mode 100644 index 7778015c..00000000 --- a/.gitbook/developers/cosmwasm-developers/page-1.md +++ /dev/null @@ -1,203 +0,0 @@ -# CW20 Adapter - -In this document, we'll explain the CW20 Adapter Contract that allows exchanging CW-20 tokens for Injective issued native tokens (using the TokenFactory module) and vice-versa. For the CW-20 Adapter GitHub repository, see [here](https://github.com/InjectiveLabs/cw20-adapter/tree/master/contracts/cw20-adapter). - -## Background - -CW-20 is a specification for fungible tokens in CosmWasm, loosely based on ERC-20 specification. It allows creating and handling of arbitrary fungible tokens within CosmWasm, specifying methods for creating, minting and burning and transferring those tokens between accounts. The adapter contract will ensure that only authorized source CW-20 contracts can mint tokens (to avoid creating “counterfeit” tokens). - -While the CW-20 standard is relatively mature and complete, the tokens exist purely within the CosmWasm context and are entirely managed by the issuing contract (including keeping track of account balances). That means that they cannot interact directly with any Injective/Cosmos chain functionality (for example, it’s not possible to trade them via the Injective exchange module, or to transfer without involving issuing contracts). - -Considering the above, it’s necessary to provide a solution that would work as a bridge between CW20 and the Injective bank module. - -The workflow of the contract is - -* Register a new CW-20 token -* Exchange amount of X CW-20 tokens for Y TokenFactory tokens (original CW-20 tokens will be held by the contract) -* Exchange Y TF tokens back for X CW-20 tokens (CW-20 tokens are released and TokenFactory tokens are burned) - -### Messages - -#### `RegisterCw20Contract { addr: Addr }` - -Registers a new CW-20 contract (`addr`) that will be handled by the adapter and creates a new TokenFactory token in format `factory/{adapter_contract}/{cw20_contract}`. - -```rust -ExecuteMsg::RegisterCw20Contract { addr } => execute_register::handle_register_msg(deps, env, info, addr) - -pub fn handle_register_msg( - deps: DepsMut, - env: Env, - info: MessageInfo, - addr: Addr, -) -> Result, ContractError> { - if is_contract_registered(&deps, &addr) { - return Err(ContractError::ContractAlreadyRegistered); - } - let required_funds = query_denom_creation_fee(&deps.querier)?; - if info.funds.len() > required_funds.len() { - return Err(ContractError::SuperfluousFundsProvided); - } - - let mut provided_funds = info.funds.iter(); - - for required_coin in &required_funds { - let pf = provided_funds - .find(|c| -> bool { c.denom == required_coin.denom }) - .ok_or(ContractError::NotEnoughBalanceToPayDenomCreationFee)?; - - match pf.amount.cmp(&required_coin.amount) { - Ordering::Greater => return Err(ContractError::SuperfluousFundsProvided), - Ordering::Less => return Err(ContractError::NotEnoughBalanceToPayDenomCreationFee), - Ordering::Equal => {} - } - } - - let create_denom_msg = register_contract_and_get_message(deps, &env, &addr)?; - Ok(Response::new().add_message(create_denom_msg)) -} -``` - -#### `Receive { sender: String, amount: Uint128, msg: Binary }` - -Implementation of the Receiver CW-20 interface. - -{% hint style="danger" %} -Must be called by the CW-20 contract only. -{% endhint %} - -```rust -ExecuteMsg::Receive { sender, amount, msg: _ } => execute_receive::handle_on_received_cw20_funds_msg(deps, env, info, sender, amount) - -pub fn handle_on_received_cw20_funds_msg( - deps: DepsMut, - env: Env, - info: MessageInfo, - recipient: String, - amount: Uint128, -) -> Result, ContractError> { - if!info.funds.is_empty() { - return Err(ContractError::SuperfluousFundsProvided); - } - let mut response = Response::new(); - let token_contract = info.sender; - if!is_contract_registered(&deps, &token_contract) { - ensure_sufficient_create_denom_balance(&deps, &env)?; - response = response.add_message(register_contract_and_get_message(deps, &env, &token_contract)?); - } - let master = env.contract.address; - - let denom = get_denom(&master, &token_contract); - let coins_to_mint = Coin::new(amount.u128(), denom); - let mint_tf_tokens_message = create_mint_tokens_msg(master, coins_to_mint, recipient); - - Ok(response.add_message(mint_tf_tokens_message)) -} -``` - -#### `RedeemAndTransfer { recipient: Option }` - -Redeem attached TokenFactory tokens and transfer CW-20 tokens to the recipient. If the recipient is not provided, they will be sent to the message sender. - -#### `RedeemAndSend { recipient: String, submessage: Binary }` - -Redeem attached TokenFactory tokens and send CW-20 tokens to the recipient contract. Caller may provide optional submessage. - -```rust -ExecuteMsg::RedeemAndTransfer { recipient } => execute_redeem::handle_redeem_msg(deps, env, info, recipient, None) - -ExecuteMsg::RedeemAndSend { recipient, submsg } => execute_redeem::handle_redeem_msg(deps, env, info, Some(recipient), Some(submsg)) - -pub fn handle_redeem_msg( - deps: DepsMut, - env: Env, - info: MessageInfo, - recipient: Option, - submessage: Option, -) -> Result, ContractError> { - let recipient = recipient.unwrap_or_else(|| info.sender.to_string()); - - if info.funds.len() > 1 { - return Err(ContractError::SuperfluousFundsProvided); - } - let tokens_to_exchange = info - .funds - .iter() - .find_map(|c| -> Option { - match AdapterDenom::new(&c.denom) { - Ok(denom) => Some(AdapterCoin { amount: c.amount, denom }), - Err(_) => None, - } - }) - .ok_or(ContractError::NoRegisteredTokensProvided)?; - - let cw20_addr = tokens_to_exchange.denom.cw20_addr.clone(); - let is_contract_registered = CW20_CONTRACTS.contains(deps.storage, &tokens_to_exchange.denom.cw20_addr); - if!is_contract_registered { - return Err(ContractError::NoRegisteredTokensProvided); - } - - let burn_tf_tokens_message = create_burn_tokens_msg(env.contract.address, tokens_to_exchange.as_coin()); - - let cw20_message: WasmMsg = match submessage { - None => WasmMsg::Execute { - contract_addr: cw20_addr, - msg: to_binary(&Cw20ExecuteMsg::Transfer { - recipient, - amount: tokens_to_exchange.amount, - })?, - funds: vec![], - }, - Some(msg) => WasmMsg::Execute { - contract_addr: cw20_addr, - msg: to_binary(&Cw20ExecuteMsg::Send { - contract: recipient, - amount: tokens_to_exchange.amount, - msg, - })?, - funds: vec![], - }, - }; - Ok(Response::new().add_message(cw20_message).add_message(burn_tf_tokens_message)) -} -``` - -#### `UpdateMetadata { addr : Addr}` - -Will query the CW-20 address (if registered) for metadata and will call setMetadata in the bank module (using TokenFactory access method). - -```rust -ExecuteMsg::UpdateMetadata { addr } => execute_metadata::handle_update_metadata(deps, env, addr) - -pub fn handle_update_metadata( - deps: DepsMut, - env: Env, - cw20_addr: Addr, -) -> Result, ContractError> { - let is_contract_registered = CW20_CONTRACTS.contains(deps.storage, cw20_addr.as_str()); - if!is_contract_registered { - return Err(ContractError::ContractNotRegistered); - } - let token_metadata = fetch_cw20_metadata(&deps, cw20_addr.as_str())?; - - let denom = get_denom(&env.contract.address, &cw20_addr); - let set_metadata_message = create_set_token_metadata_msg(denom, token_metadata.name, token_metadata.symbol, token_metadata.decimals); - - Ok(Response::new().add_message(set_metadata_message)) -} - -Queries -RegisteredContracts {} -Return a list of registered CW-20 contracts. - -QueryMsg::RegisteredContracts {} => to_binary(&query::registered_contracts(deps)?) - -pub fn registered_contracts(deps: Deps) -> StdResult> {} - -NewDenomFee {} -Returns a fee required to register a new tokenFactory denom. - -QueryMsg::NewDenomFee {} => to_binary(&query::new_denom_fee(deps)?) - -pub fn new_denom_fee(deps: Deps) -> StdResult {} -``` diff --git a/.gitbook/developers/cosmwasm-developers/your-first-smart-contract.md b/.gitbook/developers/cosmwasm-developers/your-first-smart-contract.md deleted file mode 100644 index 4a538d98..00000000 --- a/.gitbook/developers/cosmwasm-developers/your-first-smart-contract.md +++ /dev/null @@ -1,787 +0,0 @@ -# Your First Smart Contract - -Within this section, we'll explain how to setup your environment for CosmWasm Smart Contracts Development. - -### Prerequisites - -Before starting, make sure you have [`rustup`](https://rustup.rs/) along with recent versions of `rustc` and `cargo` installed. Currently, we are testing on Rust v1.58.1+. - -You also need to have the `wasm32-unknown-unknown` target installed as well as the `cargo-generate` Rust crate. - -You can check versions via the following commands: - -```bash -rustc --version -cargo --version -rustup target list --installed -# if wasm32 is not listed above, run this -rustup target add wasm32-unknown-unknown -# to install cargo-generate, run this -cargo install cargo-generate -``` - -### Objectives - -* Create and interact with a smart contract that increases and resets a counter to a given value -* Understand the basics of a CosmWasm smart contract, learn how to deploy it on Injective, and interact with it using Injective tools - -### CosmWasm Contract Basics - -A smart contract can be considered an instance of a [singleton object](https://en.wikipedia.org/wiki/Singleton\_pattern) whose internal state is persisted on the blockchain. Users can trigger state changes by sending the smart contract JSON messages, and users can also query its state by sending a request formatted as a JSON message. These JSON messages are different than Injective blockchain messages such as `MsgSend` and `MsgExecuteContract`. - -As a smart contract writer, your job is to define 3 functions that compose your smart contract's interface: - -* `instantiate()`: a constructor which is called during contract instantiation to provide initial state -* `execute()`: gets called when a user wants to invoke a method on the smart contract -* `query()`: gets called when a user wants to get data out of a smart contract - -In our [sample counter contract](https://github.com/InjectiveLabs/cw-counter/blob/59b9fed82864103eb704a58d20ddb4bf94c69787/src/msg.rs), we will implement one `instantiate`, one `query`, and two `execute` methods. - -### Start with a Template - -In your working directory, quickly launch your smart contract with the recommended folder structure and build options by running the following commands: - -```bash -cargo generate --git https://github.com/CosmWasm/cw-template.git --branch 1.0 --name my-first-contract -cd my-first-contract -``` - -This helps get you started by providing the basic boilerplate and structure for a smart contract. In the [`src/contract.rs`](https://github.com/InjectiveLabs/cw-counter/blob/ea3b781447a87f052e4b8308d5c73a30481ed61f/src/contract.rs) file you will find that the standard CosmWasm entrypoints [`instantiate()`](https://github.com/InjectiveLabs/cw-counter/blob/ea3b781447a87f052e4b8308d5c73a30481ed61f/src/contract.rs#L15), [`execute()`](https://github.com/InjectiveLabs/cw-counter/blob/ea3b781447a87f052e4b8308d5c73a30481ed61f/src/contract.rs#L35), and [`query()`](https://github.com/InjectiveLabs/cw-counter/blob/ea3b781447a87f052e4b8308d5c73a30481ed61f/src/contract.rs#L72) are properly exposed and hooked up. - -### State - -{% hint style="info" %} -You can learn more about CosmWasm [State on their documentation](https://github.com/CosmWasm/docs/blob/archive/dev-academy/develop-smart-contract/01-intro.md#contract-state) -{% endhint %} - -`State` handles the state of the database where smart contract data is stored and accessed. - -The [starting template](https://github.com/InjectiveLabs/cw-counter/blob/ea3b781447a87f052e4b8308d5c73a30481ed61f/src/state.rs) has the following basic state, a singleton struct `State` containing: - -* `count`, a 32-bit integer with which `execute()` messages will interact by increasing or resetting it. -* `owner`, the sender `address` of the `MsgInstantiateContract`, which will determine if certain execution messages are permitted. - -```c -// src/state.rs -use schemars::JsonSchema; -use serde::{Deserialize, Serialize}; - -use cosmwasm_std::Addr; -use cw_storage_plus::Item; - -#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)] -pub struct State { - pub count: i32, - pub owner: Addr, -} - -pub const STATE: Item = Item::new("state"); -``` - -Injective smart contracts have the ability to keep persistent state through Injective's native LevelDB, a bytes-based key-value store. As such, any data you wish to persist should be assigned a unique key, which may be used to index and retrieve the data. - -Data can only be persisted as raw bytes, so any notion of structure or data type must be expressed as a pair of serializing and deserializing functions. For instance, objects must be stored as bytes, so you must supply both the function that encodes the object into bytes to save it on the blockchain, as well as the function that decodes the bytes back into data types that your contract logic can understand. The choice of byte representation is up to you, so long as it provides a clean, bi-directional mapping. - -Fortunately, the CosmWasm team has provided utility crates such as [`cosmwasm_storage`](https://crates.io/crates/cosmwasm-storage), which provides convenient high-level abstractions for data containers such as a "singleton" and "bucket", which automatically provide serialization and deserialization for commonly-used types such as structs and Rust numbers. For a more efficient storage mechanism, the team has also provided the [`cw-storage-plus`](https://docs.cosmwasm.com/docs/smart-contracts/state/cw-plus/) crate. - -Notice how the `State` struct holds both `count` and `owner`. In addition, the `derive` attribute is applied to auto-implement some useful traits: - -* `Serialize`: provides serialization -* `Deserialize`: provides deserialization -* `Clone`: makes the struct copyable -* `Debug`: enables the struct to be printed to string -* `PartialEq`: provides equality comparison -* `JsonSchema`: auto-generates a JSON schema - -`Addr` refers to a human-readable Injective address prefixed with `inj`, e.g. `inj1clw20s2uxeyxtam6f7m84vgae92s9eh7vygagt`. - -### InstantiateMsg - -{% hint style="info" %} -You can learn more about CosmWasm [InstantiateMsg on their documentation](https://github.com/CosmWasm/docs/blob/archive/dev-academy/develop-smart-contract/01-intro.md#instantiatemsg) -{% endhint %} - -The `InstantiateMsg` is provided to the contract when a user instantiates a contract on the blockchain through a `MsgInstantiateContract`. This provides the contract with its configuration as well as its initial state. - -On the Injective blockchain, the uploading of a contract's code and the instantiation of a contract are regarded as separate events, unlike on Ethereum. This is to allow a small set of vetted contract archetypes to exist as multiple instances sharing the same base code, but be configured with different parameters (imagine one canonical ERC20, and multiple tokens that use its code). - -#### Example - -For your contract, the contract creator is expected to supply the initial state in a JSON message. We can see in the message definition below that the message holds one parameter `count`, which represents the initial count. - -```json -{ - "count": 100 -} -``` - -#### Message Definition - -```c -// src/msg.rs - -use schemars::JsonSchema; -use serde::{Deserialize, Serialize}; - -#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)] -pub struct InstantiateMsg { - pub count: i32, -} - -``` - -#### Contract Logic - -In `contract.rs`, you will define your first entry-point, `instantiate()`, or where the contract is instantiated and passed its `InstantiateMsg`. Extract the count from the message and set up your initial state where: - -* `count` is assigned the count from the message -* `owner` is assigned to the sender of the `MsgInstantiateContract` - -```c -// src/contract.rs -#[cfg_attr(not(feature = "library"), entry_point)] -pub fn instantiate( - deps: DepsMut, - _env: Env, - info: MessageInfo, - msg: InstantiateMsg, -) -> Result { - let state = State { - count: msg.count, - owner: info.sender.clone(), - }; - set_contract_version(deps.storage, CONTRACT_NAME, CONTRACT_VERSION)?; - STATE.save(deps.storage, &state)?; - - Ok(Response::new() - .add_attribute("method", "instantiate") - .add_attribute("owner", info.sender) - .add_attribute("count", msg.count.to_string())) -} -``` - -### ExecuteMsg - -{% hint style="info" %} - You can learn more about CosmWasm [ExecuteMsg on their documentation](https://github.com/CosmWasm/docs/blob/archive/tutorials/simple-option/develop.md#executemsg-executemsg) -{% endhint %} - -The `ExecuteMsg` is a JSON message passed to the `execute()` function through a `MsgExecuteContract`. Unlike the `InstantiateMsg`, the `ExecuteMsg` can exist as several different types of messages to account for the different types of functions that a smart contract can expose to a user. The [`execute()` function](https://github.com/InjectiveLabs/cw-counter/blob/ea3b781447a87f052e4b8308d5c73a30481ed61f/src/contract.rs#L35) demultiplexes these different types of messages to its appropriate message handler logic. - -We have [two ExecuteMsg](https://github.com/InjectiveLabs/cw-counter/blob/59b9fed82864103eb704a58d20ddb4bf94c69787/src/msg.rs#L9): `Increment` and `Reset`. - -* `Increment` has no input parameter and increases the value of count by 1. -* `Reset` takes a 32-bit integer as a parameter and resets the value of `count` to the input parameter. - -#### Example - -**Increment** - -Any user can increment the current count by 1. - -```json -{ - "increment": {} -} -``` - -**Reset** - -Only the owner can reset the count to a specific number. See Logic below for the implementation details. - -```json -{ - "reset": { - "count": 5 - } -} -``` - -#### Message Definition - -For `ExecuteMsg`, an `enum` can be used to multiplex over the different types of messages that your contract can understand. The `serde` attribute rewrites your attribute keys in snake case and lower case, so you'll have `increment` and `reset` instead of `Increment` and `Reset` when serializing and deserializing across JSON. - -```c -// src/msg.rs - -#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)] -#[serde(rename_all = "snake_case")] -pub enum ExecuteMsg { - Increment {}, - Reset { count: i32 }, -} -``` - -#### Logic - -```c -// src/contract.rs - -#[cfg_attr(not(feature = "library"), entry_point)] -pub fn execute( - deps: DepsMut, - _env: Env, - info: MessageInfo, - msg: ExecuteMsg, -) -> Result { - match msg { - ExecuteMsg::Increment {} => try_increment(deps), - ExecuteMsg::Reset { count } => try_reset(deps, info, count), - } -} -``` - -This is your `execute()` method, which uses Rust's pattern matching to route the received `ExecuteMsg` to the appropriate handling logic, either dispatching a `try_increment()` or a `try_reset()` call depending on the message received. - -```c -pub fn try_increment(deps: DepsMut) -> Result { - STATE.update(deps.storage, |mut state| -> Result<_, ContractError> { - state.count += 1; - Ok(state) - })?; - - Ok(Response::new().add_attribute("method", "try_increment")) -} -``` - -First, it acquires a mutable reference to the storage to update the item located at key `state`. It then updates the state's count by returning an `Ok` result with the new state. Finally, it terminates the contract's execution with an acknowledgement of success by returning an `Ok` result with the `Response`. - -```c -// src/contract.rs - -pub fn try_reset(deps: DepsMut, info: MessageInfo, count: i32) -> Result { - STATE.update(deps.storage, |mut state| -> Result<_, ContractError> { - if info.sender != state.owner { - return Err(ContractError::Unauthorized {}); - } - state.count = count; - Ok(state) - })?; - Ok(Response::new().add_attribute("method", "reset")) -} -``` - -The logic for reset is very similar to increment—except this time, it first checks that the message sender is permitted to invoke the reset function (in this case, it must be the contract owner). - -### QueryMsg - -{% hint style="info" %} -You can learn more about CosmWasm [QueryMsg in their documentation](https://docs.cosmwasm.com/docs/smart-contracts/query) -{% endhint %} - -The `GetCount` [query message](https://github.com/InjectiveLabs/cw-counter/blob/59b9fed82864103eb704a58d20ddb4bf94c69787/src/msg.rs#L16) has no parameters and returns the `count` value. - -See the implementation details in Logic below. - -#### Example - -The template contract only supports one type of `QueryMsg`: - -**GetCount** - -The request: - -```json -{ - "get_count": {} -} -``` - -Which should return: - -```json -{ - "count": 5 -} -``` - -#### Message Definition - -To support data queries in the contract, you'll have to define both a `QueryMsg` format (which represents requests), as well as provide the structure of the query's output—`CountResponse` in this case. You must do this because `query()` will send information back to the user through structured JSON, so you must make the shape of your response known. See Generating JSON Schema for more info. - -Add the following to your `src/msg.rs`: - -```c -// src/msg.rs -#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)] -#[serde(rename_all = "snake_case")] -pub enum QueryMsg { - // GetCount returns the current count as a json-encoded number - GetCount {}, -} - -// Define a custom struct for each query response -#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)] -pub struct CountResponse { - pub count: i32, -} -``` - -#### Logic - -The logic for `query()` is similar to that of `execute()`; however, since `query()` is called without the end-user making a transaction, the `env` argument is omitted as no information is necessary. - -```c -// src/contract.rs - -#[cfg_attr(not(feature = "library"), entry_point)] -pub fn query(deps: Deps, _env: Env, msg: QueryMsg) -> StdResult { - match msg { - QueryMsg::GetCount {} => to_binary(&query_count(deps)?), - } -} - -fn query_count(deps: Deps) -> StdResult { - let state = STATE.load(deps.storage)?; - Ok(CountResponse { count: state.count }) -} -``` - -### Unit test - -Unit tests should be run as the first line of assurance before deploying the code on chain. They are quick to execute and can provide helpful backtraces on failures with the `RUST_BACKTRACE=1` flag: - -```c -cargo unit-test // run this with RUST_BACKTRACE=1 for helpful backtraces -``` - -You can find the [unit test implementation](https://github.com/InjectiveLabs/cw-counter/blob/59b9fed82864103eb704a58d20ddb4bf94c69787/src/contract.rs#L88) at `src/contract.rs` - -### Building the Contract - -Now that we understand and have tested the contract, we can run the following command to build the contract. This will check for any preliminary errors before we optimize the contract in the next step. - -```bash -cargo wasm -``` - -Next, we must optimize the contract in order to ready the code for upload to the chain. - -{% hint style="info" %} -Read more details on [preparing the Wasm bytecode for production](https://github.com/InjectiveLabs/cw-counter/blob/59b9fed82864103eb704a58d20ddb4bf94c69787/Developing.md#preparing-the-wasm-bytecode-for-production) -{% endhint %} - -CosmWasm has [rust-optimizer](https://github.com/CosmWasm/rust-optimizer), an optimizing compiler that can produce a small and consistent build output. The easiest method to use the tool is to use a published Docker image—check [here](https://hub.docker.com/r/cosmwasm/rust-optimizer/tags) for the latest x86 version, or [here](https://hub.docker.com/r/cosmwasm/rust-optimizer-arm64/tags) for the latest ARM version. With Docker running, run the following command to mount the contract code to `/code` and optimize the output (you can use an absolute path instead of `$(pwd)` if you don't want to `cd` to the directory first): - -```bash -docker run --rm -v "$(pwd)":/code \ - --mount type=volume,source="$(basename "$(pwd)")_cache",target=/code/target \ - --mount type=volume,source=registry_cache,target=/usr/local/cargo/registry \ - cosmwasm/rust-optimizer:0.12.12 -``` - -If you're on an ARM64 machine, you should use a docker image built for ARM64: - -```bash -docker run --rm -v "$(pwd)":/code \ - --mount type=volume,source="$(basename "$(pwd)")_cache",target=/code/target \ - --mount type=volume,source=registry_cache,target=/usr/local/cargo/registry \ - cosmwasm/rust-optimizer-arm64:0.12.12 -``` - -{% hint style="info" %} -CosmWasm does not recommend using the ARM64 version of the compiler because it produces different Wasm artifacts from the Intel/AMD version. For release/production, only contracts built with Intel/AMD optimizers are recommended for use. See [here](https://github.com/CosmWasm/rust-optimizer#notice) for the note from CosmWasm. -{% endhint %} - -{% hint style="warning" %} -You may receive an `` Unable to update registry `crates-io` `` error while running the command. Try adding the following lines to the `Cargo.toml` file located within the contract directory and running the command again: - -```toml -[net] -git-fetch-with-cli = true -``` - -See [The Cargo Book](https://doc.rust-lang.org/cargo/reference/config.html#netgit-fetch-with-cli) for more information. -{% endhint %} - -This produces an `artifacts` directory with a `PROJECT_NAME.wasm`, as well as `checksums.txt`, containing the Sha256 hash of the Wasm file. The Wasm file is compiled deterministically (anyone else running the same docker on the same git commit should get the identical file with the same Sha256 hash). - -### Install `injectived` - -`injectived` is the command-line interface and daemon that connects to Injective and enables you to interact with the Injective blockchain. - -If you want to interact with your Smart Contract locally using CLI, you have to have `injectived` installed. To do so, you can follow the installation guidelines here [#install-injectived](your-first-smart-contract.md#install-injectived "mention"). - -Alternatively, a Docker image has been prepared to make this tutorial easier. - -{% hint style="info" %} -If you install `injectived` from the binary, ignore the docker commands. On the [public endpoints section](../../nodes/public-endpoints.md) you can find the right --node info to interact with Mainnet and Testnet. -{% endhint %} - -Executing this command will make the docker container execute indefinitely. - -```bash -docker run --name="injective-core-staging" \ --v=/artifacts:/var/artifacts \ ---entrypoint=sh public.ecr.aws/l9h3g6c6/injective-core:staging \ --c "tail -F anything" -``` - -Note: `directory_to_which_you_cloned_cw-template` must be an absolute path. The absolute path can easily be found by running the `pwd` command from inside the CosmWasm/cw-counter directory. - -Open a new terminal and go into the Docker container to initialize the chain: - -```bash -docker exec -it injective-core-staging sh -``` - -Let’s start by adding `jq` dependency, which will be needed later on: - -```bash -# inside the "injective-core-staging" container -apk add jq -``` - -Now we can proceed to local chain initialization and add a test user called `testuser` (when prompted use 12345678 as password). We will only use the test user to generate a new private key that will later on be used to sign messages on the testnet: - -```sh -# inside the "injective-core-staging" container -injectived keys add testuser -``` - -**OUTPUT** - -``` -- name: testuser - type: local - address: inj1exjcp8pkvzqzsnwkzte87fmzhfftr99kd36jat - pubkey: '{"@type":"/injective.crypto.v1beta1.ethsecp256k1.PubKey","key":"Aqi010PsKkFe9KwA45ajvrr53vfPy+5vgc3aHWWGdW6X"}' - mnemonic: "" - -**Important** write this mnemonic phrase in a safe place. -It is the only way to recover your account if you ever forget your password. - -wash wise evil buffalo fiction quantum planet dial grape slam title salt dry and some more words that should be here -``` - -Take a moment to write down the address or export it as an env variable, as you will need it to proceed: - -```bash -# inside the "injective-core-staging" container -export INJ_ADDRESS= -``` - -{% hint style="info" %} -You can request testnet funds for your recently generated test address using the [Injective test faucet](https://faucet.injective.network/). -{% endhint %} - -Now you have successfully created `testuser` an Injective Testnet. It should also hold some funds after requesting `testnet` funds from the faucet. - -To confirm, search for your address on the [Injective Testnet Explorer](https://testnet.explorer.injective.network/) to check your balance. - -Alternatively, you can verify it by [querying the bank balance](https://sentry.testnet.lcd.injective.network/swagger/#/Query/AllBalances) or with curl: - -```bash -curl -X GET "https://sentry.testnet.lcd.injective.network/cosmos/bank/v1beta1/balances/" -H "accept: application/json" -``` - -## Upload the Wasm Contract - -Now it's time to upload the `.wasm` file that you compiled in the previous steps to the Injective Testnet. Please note that the procedure for mainnet is different and [requires a governance proposal.](guides/mainnet-deployment.md) - -```bash -# inside the "injective-core-staging" container, or from the contract directory if running injectived locally -yes 12345678 | injectived tx wasm store artifacts/my_first_contract.wasm \ ---from=$(echo $INJ_ADDRESS) \ ---chain-id="injective-888" \ ---yes --fees=1000000000000000inj --gas=2000000 \ ---node=https://sentry.testnet.tm.injective.network:443 -``` - -**Output:** - -```bash -code: 0 -codespace: "" -data: "" -events: [] -gas_used: "0" -gas_wanted: "0" -height: "0" -info: "" -logs: [] -raw_log: '[]' -timestamp: "" -tx: null -txhash: 912458AA8E0D50A479C8CF0DD26196C49A65FCFBEEB67DF8A2EA22317B130E2C -``` - -Check your address on the [Injective Testnet Explorer](https://testnet.explorer.injective.network), and look for a transaction with the `txhash` returned from storing the code on chain. The transaction type should be `MsgStoreCode`. - -You can see all stored codes on Injective Testnet under [Code](https://testnet.explorer.injective.network/codes/). - -{% hint style="info" %} -There are different ways to find the code that you just stored: - -* Look for the TxHash on the Injective Explorer [codes list](https://testnet.explorer.injective.network/codes/); it is most likely the most recent. -* Use `injectived` to query transaction info. -{% endhint %} - -To query the transaction use the `txhash` and verify the contract was deployed. - -```sh -injectived query tx 912458AA8E0D50A479C8CF0DD26196C49A65FCFBEEB67DF8A2EA22317B130E2C --node=https://sentry.testnet.tm.injective.network:443 -``` - -Inspecting the output more closely, we can see the `code_id` of `290` for the uploaded contract: - -```bash -- events: - - attributes: - - key: access_config - value: '{"permission":"Everybody","address":""}' - - key: checksum - value: '"+OdoniOsDJ1T9EqP2YxobCCwFAqNdtYA4sVGv7undY0="' - - key: code_id - value: '"290"' - - key: creator - value: '"inj1h3gepa4tszh66ee67he53jzmprsqc2l9npq3ty"' - type: cosmwasm.wasm.v1.EventCodeStored - - attributes: - - key: action - value: /cosmwasm.wasm.v1.MsgStoreCode - - key: module - value: wasm - - key: sender - value: inj1h3gepa4tszh66ee67he53jzmprsqc2l9npq3ty - type: message - - attributes: - - key: code_id - value: "290" - type: store_code -``` - -Let's export your `code_id` as an ENV variable—we'll need it to instantiate the contract. You can skip this step and manually add it later, but keep note of the ID. - -```bash -export CODE_ID= -``` - -## Generating JSON Schema - -While the Wasm calls `instantiate`, `execute`, and `query` accept JSON, this is not enough information to use them. We need to expose the schema for the expected messages to the clients. - -In order to make use of JSON-schema auto-generation, you should register each of the data structures that you need schemas for. - -```c -// examples/schema.rs - -use std::env::current_dir; -use std::fs::create_dir_all; - -use cosmwasm_schema::{export_schema, remove_schemas, schema_for}; - -use my_first_contract::msg::{CountResponse, HandleMsg, InitMsg, QueryMsg}; -use my_first_contract::state::State; - -fn main() { - let mut out_dir = current_dir().unwrap(); - out_dir.push("schema"); - create_dir_all(&out_dir).unwrap(); - remove_schemas(&out_dir).unwrap(); - - export_schema(&schema_for!(InstantiateMsg), &out_dir); - export_schema(&schema_for!(ExecuteMsg), &out_dir); - export_schema(&schema_for!(QueryMsg), &out_dir); - export_schema(&schema_for!(State), &out_dir); - export_schema(&schema_for!(CountResponse), &out_dir); -} -``` - -The schemas can then be generated with - -```bash -cargo schema -``` - -which will output 5 files in `./schema`, corresponding to the 3 message types the contract accepts, the query response message, and the internal `State`. - -These files are in standard JSON Schema format, which should be usable by various client side tools, either to auto-generate codecs, or just to validate incoming JSON with respect to the defined schema. - -Take a minute to generate the schema ([take a look at it here](https://github.com/InjectiveLabs/cw-counter/blob/master/schema/cw-counter.json)) and get familiar with it, as you will need to it for the next steps. - -## Instantiate the Contract - -Now that we have the code on Injective, it is time to instantiate the contract to interact with it. - -{% hint style="info" %} -Reminder On CosmWasm, the upload of a contract's code and the instantiation of a contract are regarded as separate events -{% endhint %} - -To instantiate the contract, run the following CLI command with the code\_id you got in the previous step, along with the [JSON encoded initialization arguments](https://github.com/InjectiveLabs/cw-counter/blob/ea3b781447a87f052e4b8308d5c73a30481ed61f/schema/cw-counter.json#L7) and a label (a human-readable name for this contract in lists). - -```bash -INIT='{"count":99}' -yes 12345678 | injectived tx wasm instantiate $CODE_ID $INIT \ ---label="CounterTestInstance" \ ---from=$(echo $INJ_ADDRESS) \ ---chain-id="injective-888" \ ---yes --fees=1000000000000000inj \ ---gas=2000000 \ ---no-admin \ ---node=https://sentry.testnet.tm.injective.network:443 -``` - -**Output:** - -```bash -code: 0 -codespace: "" -data: "" -events: [] -gas_used: "0" -gas_wanted: "0" -height: "0" -info: "" -logs: [] -raw_log: '[]' -timestamp: "" -tx: null -txhash: 01804F525FE336A5502E3C84C7AE00269C7E0B3DC9AA1AB0DDE3BA62CF93BE1D -``` - -{% hint style="info" %} -You can find the contract address and metadata by: - -* Looking on the [Testnet Explorer](https://testnet.explorer.injective.network/contracts/) -* Querying the [ContractsByCode](https://k8s.testnet.lcd.injective.network/swagger/#/Query/ContractsByCode) and [ContractInfo](https://k8s.testnet.lcd.injective.network/swagger/#/Query/ContractInfo) APIs -* Querying through the CLI - -```bash -injectived query wasm contract inj1ady3s7whq30l4fx8sj3x6muv5mx4dfdlcpv8n7 --node=https://sentry.testnet.tm.injective.network:443 -``` -{% endhint %} - -### Querying the Contract - -As we know from earlier, the only QueryMsg we have is `get_count`. - -```bash -GET_COUNT_QUERY='{"get_count":{}}' -injectived query wasm contract-state smart inj1ady3s7whq30l4fx8sj3x6muv5mx4dfdlcpv8n7 "$GET_COUNT_QUERY" \ ---node=https://sentry.testnet.tm.injective.network:443 \ ---output json -``` - -**Output:** - -```bash -{"data":{"count":99}} -``` - -We see that `count` is 99, as set when we instantiated the contract. - -{% hint style="info" %} -If you query the same contract, you may receive a different response as others may have interacted with the contract and incremented or reset the count. -{% endhint %} - -### Execute the Contract - -Let's now interact with the contract by incrementing the counter. - -```bash -INCREMENT='{"increment":{}}' -yes 12345678 | injectived tx wasm execute inj1ady3s7whq30l4fx8sj3x6muv5mx4dfdlcpv8n7 "$INCREMENT" --from=$(echo $INJ_ADDRESS) \ ---chain-id="injective-888" \ ---yes --fees=1000000000000000inj --gas=2000000 \ ---node=https://sentry.testnet.tm.injective.network:443 \ ---output json -``` - -If we query the contract for the count, we see: - -```bash -{"data":{"count":100}} -``` - -{% hint style="info" %} -**yes 12345678 |** automatically pipes (passes) the passphrase to the input of **injectived tx wasm execute** so you do not need to enter it manually. -{% endhint %} - -To reset the counter: - -```bash -RESET='{"reset":{"count":999}}' -yes 12345678 | injectived tx wasm execute inj1ady3s7whq30l4fx8sj3x6muv5mx4dfdlcpv8n7 "$RESET" \ ---from=$(echo $INJ_ADDRESS) \ ---chain-id="injective-888" \ ---yes --fees=1000000000000000inj --gas=2000000 \ ---node=https://sentry.testnet.tm.injective.network:443 \ ---output json -``` - -Now, if we query the contract again, we see the count has been reset to the provided value: - -```bash -{"data":{"count":999}} -``` - -## Cosmos Messages - -In addition to defining custom smart contract logic, CosmWasm also allows contracts to interact with the underlying Cosmos SDK functionalities. One common use case is to send tokens from the contract to a specified address using the Cosmos SDK's bank module. - -### Example: Bank Send - -The `BankMsg::Send` message allows the contract to transfer tokens to another address. This can be useful in various scenarios, such as distributing rewards or returning funds to users. - -:::note If you want to send funds and execute a function on another contract at the same time, don't use BankMsg::Send. Instead, use WasmMsg::Execute and set the respective funds field. ::: - -### Constructing the Message - -You can construct a `BankMsg::Send` message within your contract's `execute` function. This message requires specifying the recipient address and the amount to send. Here's an example of how to construct this message: - -```rust -use cosmwasm_std::{BankMsg, Coin, Response, MessageInfo}; - -pub fn try_send( - info: MessageInfo, - recipient_address: String, - amount: Vec, -) -> Result { - let send_message = BankMsg::Send { - to_address: recipient_address, - amount, - }; - - let response = Response::new().add_message(send_message); - Ok(response) -} -``` - -### Usage in a Smart Contract - -In your contract, you can add a new variant to your ExecuteMsg enum to handle this bank send functionality. For example: - -```rust -#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)] -#[serde(rename_all = "snake_case")] -pub enum ExecuteMsg { - // ... other messages ... - SendTokens { recipient: String, amount: Vec }, -} -``` - -Then, in the `execute` function, you can add a case to handle this message: - -```rust -#[cfg_attr(not(feature = "library"), entry_point)] -pub fn execute( - deps: DepsMut, - env: Env, - info: MessageInfo, - msg: ExecuteMsg, -) -> Result { - match msg { - // ... other message handling ... - ExecuteMsg::SendTokens { recipient, amount } => try_send(info, recipient, amount), - } -} -``` - -## Testing - -As with other smart contract functions, you should add unit tests to ensure your bank send functionality works as expected. This includes testing different scenarios, such as sending various token amounts and handling errors correctly. - -You may use [test-tube](https://github.com/InjectiveLabs/test-tube) for running integration tests that include a local Injective chain. - -Congratulations! You've created and interacted with your first Injective smart contract and now know how to get started with CosmWasm development on Injective. Continue to Creating a Frontend for Your Contract for a guide on creating a web UI. diff --git a/.gitbook/developers/evm-developers.md b/.gitbook/developers/evm-developers.md deleted file mode 100644 index df05afe2..00000000 --- a/.gitbook/developers/evm-developers.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -hidden: true ---- - -# EVM Developers - -🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 - -This page is currently under work in progress. - -🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 diff --git a/.gitbook/developers/exchange-developers/README.md b/.gitbook/developers/exchange-developers/README.md deleted file mode 100644 index b5c93016..00000000 --- a/.gitbook/developers/exchange-developers/README.md +++ /dev/null @@ -1,15 +0,0 @@ -# Exchange Developers - -Injective marks the forefront of exchange-focused layer-1 blockchains offering decentralized perpetual swaps, futures, and spot trading. It fully taps into the possibilities of decentralized derivatives and borderless DeFi. Every component is designed to embody complete trustlessness, resistance to censorship, public verifiability, and resilience against front-running. - -Injective enables traders to create and trade arbitrary spot and derivatives markets. Injective also enables on-chain limit orderbook management, on-chain trade execution, on-chain order matching, on-chain transaction settlement, and on-chain trading incentive distribution through the logic codified by the Injective Chain's [Exchange Module](https://docs.injective.network/develop/modules/injective/exchange/). - -### Build an Orderbook DEX on Injective - -As an incentive mechanism to encourage exchanges to build on Injective and source trading activity, exchanges that originate orders into the shared orderbook of Injective's exchange protocol ([read more](https://docs.injective.network/develop/modules/injective/exchange/)) are rewarded with $$β=40%β=40%$$ of the trading fee from orders that they source. The exchange protocol implements a global minimum trading fee of $$rm=0.1%rm​=0.1%$$ for makers and $$rt=0.2%rt​=0.2%$$ for takers. - -The goal of Injective's incentive mechanism is to allow exchanges competing amongst each other to provide a better user experience and to better serve users, broadening access to DeFi for users all around the world. - -An exchange can easily set up a client (such as a UI on web or mobile) and an API provider. - -Head to our TypeScript documentation to [bootstrap your DEX ](https://docs.ts.injective.network/building-dapps/dapps-examples/dex)with few clicks! diff --git a/.gitbook/developers/exchange-developers/provider-oracle.md b/.gitbook/developers/exchange-developers/provider-oracle.md deleted file mode 100644 index 354bf286..00000000 --- a/.gitbook/developers/exchange-developers/provider-oracle.md +++ /dev/null @@ -1,21 +0,0 @@ -# Provider Oracle - -{% hint style="info" %} -Prerequisite reading [Injective Oracle Module](../modules/injective/oracle/) -{% endhint %} - -The goal of this section is to provide users a guide on how to launch and maintain an oracle provider on Injective. These oracles can be used for various purposes, like Perpetual Markets, Expiry Futures Markets, [Binary Options markets](https://docs.injective.network/develop/modules/injective/exchange/binary\_options\_markets), etc. - -First, what is an oracle provider? It's an oracle **TYPE** that allows external parties to relay price feed to the Injective chain. These external parties are called providers. A provider identifies each external party and all of the price feeds provided on the chain are stored under that particular provider. This allows custom price feed to be created on Injective which can power creative and advanced markets being launched on Injective. - -The first thing developers need to do is register their provider under the Oracle Provider type. You can do that by submitting a `GrantProviderPrivilegeProposal` governance proposal. Once the proposal passes, your provider will be registered and you can relay price feeds. You can do it in a CLI environment using `injectived` (`grant-provider-privilege-proposal [providerName] [relayers] --title [title] --description [desc] [flags]`) or using any of our SDKs to create the message and broadcast it to the chain. - -{% hint style="info" %} -You can see an example on how to submit this proposal in the Oracle Module Proposals Section -{% endhint %} - -_Note: the `relayers` of the `GrantProviderPrivilegeProposal` are addresses that will be whitelisted to submit the price feeds to Injective._ - -Once the proposal passes, the `relayers` can use the `MsgRelayProviderPrices` to submit prices for a base/quote pair within their provider namespace of the Oracle Provider Type oracle on Injective. You can do it in a CLI environment using `injectived` (`relay-provider-prices [providerName] [symbol:prices] [flags]`) or using any of our SDKs to create the message and broadcast it to the chain. - -Finally, you can use these price feeds to create your Derivative Markets. diff --git a/.gitbook/developers/getting-started/README.md b/.gitbook/developers/getting-started/README.md deleted file mode 100644 index 17d17203..00000000 --- a/.gitbook/developers/getting-started/README.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -description: >- - This goal of this section is to help developers build their projects on - Injective ---- - -# Getting Started - -Injective is the only blockchain specifically designed for cross-chain trading, derivatives, DeFi and Web3 applications. Injective is poised to become the premier destination for DeFi ecosystem builders globally. It already has one of the fastest-growing exchange applications of all time, which promotes further confidence among developers looking to deploy on Injective. - -* **Built for DeFi:** Create novel DeFi applications with fast block times, zero gas fees and instant transaction finality. -* **Order book Infrastructure**: Native decentralized order book infrastructure that can support all financial primitives (spot, perpetuals, expiry contracts, indices, etc. -* **Ethereum compatibility:** Leverage Injective's native Ethereum compatibility in your applications while scaling transactions to be 1000X faster and cheaper than Ethereum. -* **Unprecedented interoperability:** Explore limitless possibilities for cross-chain interoperability across Ethereum, Cosmos and 10+ prominent layer one protocols. -* **MEV Resistant**: Complete MEV resistance due to the Injective Chain’s frequent batch auction consensus mechanism. -* **Fully customizable:** Ship your products with the ability to swiftly modify any parameter to fit your DeFi and Web3 use case. -* **Dual Smart Contract Layer**: Deploy dApps on CosmWasm or EVM to suit your needs. -* **Horizontal scalability:** Run your application across parallel chains to reach millions of users with infinite scalability. -* **Intuitive developer experience:** Iterate your dApps rapidly with familiar tooling, mainstream languages (Go/Rust), negligible costs and low barriers to entry. -* **Highly secure:** Protected by a distributed group of global validators with a proven track record in crypto and major traditional finance institutions. -* **Environmentally friendly:** Injective’s consensus mechanism leads to a 99% lower carbon footprint. - -## What are you interested in building? - -
ExchangeLearn how to build a decentralized exchange like Helixexchange-developerstrader-hero.png
CosmwasmLearn how to use Cosmwasm to build any kind of dAppcosmwasm-developerslaunch-token-hero.png
Native ModulesLearn more about what Injective's native modules offermodulestxs-hero.png
- diff --git a/.gitbook/developers/getting-started/guides/README.md b/.gitbook/developers/getting-started/guides/README.md deleted file mode 100644 index 16b0fdc0..00000000 --- a/.gitbook/developers/getting-started/guides/README.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -description: >- - This section contains some simple developer guides to help your building - journey on Injective. ---- - -# Guides - diff --git a/.gitbook/developers/getting-started/guides/convert-addresses.md b/.gitbook/developers/getting-started/guides/convert-addresses.md deleted file mode 100644 index 261d25fd..00000000 --- a/.gitbook/developers/getting-started/guides/convert-addresses.md +++ /dev/null @@ -1,59 +0,0 @@ -# Convert addresses - -Within this document, we'll outline some examples on how to convert addresses between different formats and derivation paths. - -### Convert Hex <> Bech32 address - -As we've mentioned in the [wallet](../../../getting-started/wallet/ "mention")section, Injective addresses are compatible with Ethereum addresses. You can convert between the two formats easily. - -### Using TypeScript - -You can easily convert between an Injective address and Ethereum address by using our utility functions in the `@injectivelabs/sdk-ts` package: - -```typescript -import { getInjectiveAddress, getEthereumAddress } from '@injectivelabs/sdk-ts' - -const injectiveAddress = 'inj1...' -const ethereumAddress = '0x..' - -console.log('Injective address from Ethereum address => ', getInjectiveAddress(ethereumAddress)) -console.log('Ethereum address from Injective address => ', getEthereumAddress(injectiveAddress)) -``` - -### **Convert Cosmos address to Injective Address** - -As Injective has a different derivation path than the default Cosmos one, you need the `publicKey` of the account to convert a Cosmos `publicAddress` to Injective one. - -### Using TypeScript - -```typescript -import { config } from "dotenv"; -import { ChainRestAuthApi, PublicKey } from "@injectivelabs/sdk-ts"; - -config(); - -(async () => { - const chainApi = new ChainRestAuthApi( - "https://rest.cosmos.directory/cosmoshub" - ); - - const cosmosAddress = "cosmos1.."; - const account = await chainApi.fetchCosmosAccount(cosmosAddress); - - if (!account.pub_key?.key) { - console.log("No public key found"); - return; - } - - console.log( - "injectiveAddress", - PublicKey.fromBase64(account.pub_key.key || "") - .toAddress() - .toBech32() - ); -})(); -``` - -{% hint style="info" %} -More examples can be found on the [TypeScript docs](https://docs.ts.injective.network/wallet/wallet-accounts) -{% endhint %} diff --git a/.gitbook/developers/getting-started/guides/testnet-proposals.md b/.gitbook/developers/getting-started/guides/testnet-proposals.md deleted file mode 100644 index 5c20ad5e..00000000 --- a/.gitbook/developers/getting-started/guides/testnet-proposals.md +++ /dev/null @@ -1,23 +0,0 @@ -# Testnet Proposals - -Let's say that you want to submit a proposal on `testnet`. Because there is a short period of voting time for the proposals, we recommend lowering the deposit on the proposal to not make the proposal go into voting stage directly. Basically, it should be slightly less than `min_deposit` value. - -Once you submit the proposal, you should teach out to the team: - -1. Join the [Injective Discord server](https://discord.gg/injective) and find the relevant channel. -2. Join the [Injective Developer Telegram channel](https://t.me/+8Y\_0HOFLhnRlZDU9). - -Here is an example for the `GrantProviderPrivilegeProposal` - -```bash -injectived tx oracle grant-provider-privilege-proposal YOUR_PROVIDER \ - YOUR_ADDRESS_HERE \ - --title="TITLE OF THE PROPOSAL" \ - --description="Registering PROVIDER as an oracle provider" \ - --chain-id=injective-888 \ - --from=local_key \ - --node=https://testnet.sentry.tm.injective.network:443 \ - --gas-prices=160000000inj \ - --gas=20000000 \ - --deposit="40000000000000000000inj" <-- use this amount -``` diff --git a/.gitbook/developers/modules/README.md b/.gitbook/developers/modules/README.md deleted file mode 100644 index 986e8b39..00000000 --- a/.gitbook/developers/modules/README.md +++ /dev/null @@ -1,7 +0,0 @@ -# Modules - -🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 - -This page is currently under work in progress. - -🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 diff --git a/.gitbook/developers/modules/core/README.md b/.gitbook/developers/modules/core/README.md deleted file mode 100644 index b0790a93..00000000 --- a/.gitbook/developers/modules/core/README.md +++ /dev/null @@ -1,14 +0,0 @@ -import { - HomepageSection as Section -} from "../../../../src/components/HomepageComponents"; -import ComponentsGrid from "@theme/DocCardList"; - -# Core Modules - -
- -
diff --git a/.gitbook/developers/modules/core/auth/README.md b/.gitbook/developers/modules/core/auth/README.md deleted file mode 100644 index bd9f18a3..00000000 --- a/.gitbook/developers/modules/core/auth/README.md +++ /dev/null @@ -1,710 +0,0 @@ ---- -sidebar_position: 1 ---- - -# `x/auth` - -## Abstract - -This document specifies the auth module of the Cosmos SDK. - -The auth module is responsible for specifying the base transaction and account types -for an application, since the SDK itself is agnostic to these particulars. It contains -the middlewares, where all basic transaction validity checks (signatures, nonces, auxiliary fields) -are performed, and exposes the account keeper, which allows other modules to read, write, and modify accounts. - -This module is used in the Cosmos Hub. - -## Contents - -* [Concepts](#concepts) - * [Gas & Fees](#gas--fees) -* [State](#state) - * [Accounts](#accounts) -* [AnteHandlers](#antehandlers) -* [Keepers](#keepers) - * [Account Keeper](#account-keeper) -* [Parameters](#parameters) -* [Client](#client) - * [CLI](#cli) - * [gRPC](#grpc) - * [REST](#rest) - -## Concepts - -**Note:** The auth module is different from the [authz module](../authz/). - -The differences are: - -* `auth` - authentication of accounts and transactions for Cosmos SDK applications and is responsible for specifying the base transaction and account types. -* `authz` - authorization for accounts to perform actions on behalf of other accounts and enables a granter to grant authorizations to a grantee that allows the grantee to execute messages on behalf of the granter. - -### Gas & Fees - -Fees serve two purposes for an operator of the network. - -Fees limit the growth of the state stored by every full node and allow for -general purpose censorship of transactions of little economic value. Fees -are best suited as an anti-spam mechanism where validators are disinterested in -the use of the network and identities of users. - -Fees are determined by the gas limits and gas prices transactions provide, where -`fees = ceil(gasLimit * gasPrices)`. Txs incur gas costs for all state reads/writes, -signature verification, as well as costs proportional to the tx size. Operators -should set minimum gas prices when starting their nodes. They must set the unit -costs of gas in each token denomination they wish to support: - -`simd start ... --minimum-gas-prices=0.00001stake;0.05photinos` - -When adding transactions to mempool or gossipping transactions, validators check -if the transaction's gas prices, which are determined by the provided fees, meet -any of the validator's minimum gas prices. In other words, a transaction must -provide a fee of at least one denomination that matches a validator's minimum -gas price. - -CometBFT does not currently provide fee based mempool prioritization, and fee -based mempool filtering is local to node and not part of consensus. But with -minimum gas prices set, such a mechanism could be implemented by node operators. - -Because the market value for tokens will fluctuate, validators are expected to -dynamically adjust their minimum gas prices to a level that would encourage the -use of the network. - -## State - -### Accounts - -Accounts contain authentication information for a uniquely identified external user of an SDK blockchain, -including public key, address, and account number / sequence number for replay protection. For efficiency, -since account balances must also be fetched to pay fees, account structs also store the balance of a user -as `sdk.Coins`. - -Accounts are exposed externally as an interface, and stored internally as -either a base account or vesting account. Module clients wishing to add more -account types may do so. - -* `0x01 | Address -> ProtocolBuffer(account)` - -#### Account Interface - -The account interface exposes methods to read and write standard account information. -Note that all of these methods operate on an account struct conforming to the -interface - in order to write the account to the store, the account keeper will -need to be used. - -```go -// AccountI is an interface used to store coins at a given address within state. -// It presumes a notion of sequence numbers for replay protection, -// a notion of account numbers for replay protection for previously pruned accounts, -// and a pubkey for authentication purposes. -// -// Many complex conditions can be used in the concrete struct which implements AccountI. -type AccountI interface { - proto.Message - - GetAddress() sdk.AccAddress - SetAddress(sdk.AccAddress) error // errors if already set. - - GetPubKey() crypto.PubKey // can return nil. - SetPubKey(crypto.PubKey) error - - GetAccountNumber() uint64 - SetAccountNumber(uint64) error - - GetSequence() uint64 - SetSequence(uint64) error - - // Ensure that account implements stringer - String() string -} -``` - -##### Base Account - -A base account is the simplest and most common account type, which just stores all requisite -fields directly in a struct. - -```protobuf -// BaseAccount defines a base account type. It contains all the necessary fields -// for basic account functionality. Any custom account type should extend this -// type for additional functionality (e.g. vesting). -message BaseAccount { - string address = 1; - google.protobuf.Any pub_key = 2; - uint64 account_number = 3; - uint64 sequence = 4; -} -``` - -### Vesting Account - -See [Vesting](https://docs.cosmos.network/main/modules/auth/vesting/). - -## AnteHandlers - -The `x/auth` module presently has no transaction handlers of its own, but does expose the special `AnteHandler`, used for performing basic validity checks on a transaction, such that it could be thrown out of the mempool. -The `AnteHandler` can be seen as a set of decorators that check transactions within the current context, per [ADR 010](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-010-modular-antehandler.md). - -Note that the `AnteHandler` is called on both `CheckTx` and `DeliverTx`, as CometBFT proposers presently have the ability to include in their proposed block transactions which fail `CheckTx`. - -### Decorators - -The auth module provides `AnteDecorator`s that are recursively chained together into a single `AnteHandler` in the following order: - -* `SetUpContextDecorator`: Sets the `GasMeter` in the `Context` and wraps the next `AnteHandler` with a defer clause to recover from any downstream `OutOfGas` panics in the `AnteHandler` chain to return an error with information on gas provided and gas used. - -* `RejectExtensionOptionsDecorator`: Rejects all extension options which can optionally be included in protobuf transactions. - -* `MempoolFeeDecorator`: Checks if the `tx` fee is above local mempool `minFee` parameter during `CheckTx`. - -* `ValidateBasicDecorator`: Calls `tx.ValidateBasic` and returns any non-nil error. - -* `TxTimeoutHeightDecorator`: Check for a `tx` height timeout. - -* `ValidateMemoDecorator`: Validates `tx` memo with application parameters and returns any non-nil error. - -* `ConsumeGasTxSizeDecorator`: Consumes gas proportional to the `tx` size based on application parameters. - -* `DeductFeeDecorator`: Deducts the `FeeAmount` from first signer of the `tx`. If the `x/feegrant` module is enabled and a fee granter is set, it deducts fees from the fee granter account. - -* `SetPubKeyDecorator`: Sets the pubkey from a `tx`'s signers that does not already have its corresponding pubkey saved in the state machine and in the current context. - -* `ValidateSigCountDecorator`: Validates the number of signatures in `tx` based on app-parameters. - -* `SigGasConsumeDecorator`: Consumes parameter-defined amount of gas for each signature. This requires pubkeys to be set in context for all signers as part of `SetPubKeyDecorator`. - -* `SigVerificationDecorator`: Verifies all signatures are valid. This requires pubkeys to be set in context for all signers as part of `SetPubKeyDecorator`. - -* `IncrementSequenceDecorator`: Increments the account sequence for each signer to prevent replay attacks. - -## Keepers - -The auth module only exposes one keeper, the account keeper, which can be used to read and write accounts. - -### Account Keeper - -Presently only one fully-permissioned account keeper is exposed, which has the ability to both read and write -all fields of all accounts, and to iterate over all stored accounts. - -```go -// AccountKeeperI is the interface contract that x/auth's keeper implements. -type AccountKeeperI interface { - // Return a new account with the next account number and the specified address. Does not save the new account to the store. - NewAccountWithAddress(sdk.Context, sdk.AccAddress) types.AccountI - - // Return a new account with the next account number. Does not save the new account to the store. - NewAccount(sdk.Context, types.AccountI) types.AccountI - - // Check if an account exists in the store. - HasAccount(sdk.Context, sdk.AccAddress) bool - - // Retrieve an account from the store. - GetAccount(sdk.Context, sdk.AccAddress) types.AccountI - - // Set an account in the store. - SetAccount(sdk.Context, types.AccountI) - - // Remove an account from the store. - RemoveAccount(sdk.Context, types.AccountI) - - // Iterate over all accounts, calling the provided function. Stop iteration when it returns true. - IterateAccounts(sdk.Context, func(types.AccountI) bool) - - // Fetch the public key of an account at a specified address - GetPubKey(sdk.Context, sdk.AccAddress) (crypto.PubKey, error) - - // Fetch the sequence of an account at a specified address. - GetSequence(sdk.Context, sdk.AccAddress) (uint64, error) - - // Fetch the next account number, and increment the internal counter. - NextAccountNumber(sdk.Context) uint64 -} -``` - -## Parameters - -The auth module contains the following parameters: - -| Key | Type | Example | -| ---------------------- | --------------- | ------- | -| MaxMemoCharacters | uint64 | 256 | -| TxSigLimit | uint64 | 7 | -| TxSizeCostPerByte | uint64 | 10 | -| SigVerifyCostED25519 | uint64 | 590 | -| SigVerifyCostSecp256k1 | uint64 | 1000 | - -## Client - -### CLI - -A user can query and interact with the `auth` module using the CLI. - -### Query - -The `query` commands allow users to query `auth` state. - -```bash -simd query auth --help -``` - -#### account - -The `account` command allow users to query for an account by it's address. - -```bash -simd query auth account [address] [flags] -``` - -Example: - -```bash -simd query auth account cosmos1... -``` - -Example Output: - -```bash -'@type': /cosmos.auth.v1beta1.BaseAccount -account_number: "0" -address: cosmos1zwg6tpl8aw4rawv8sgag9086lpw5hv33u5ctr2 -pub_key: - '@type': /cosmos.crypto.secp256k1.PubKey - key: ApDrE38zZdd7wLmFS9YmqO684y5DG6fjZ4rVeihF/AQD -sequence: "1" -``` - -#### accounts - -The `accounts` command allow users to query all the available accounts. - -```bash -simd query auth accounts [flags] -``` - -Example: - -```bash -simd query auth accounts -``` - -Example Output: - -```bash -accounts: -- '@type': /cosmos.auth.v1beta1.BaseAccount - account_number: "0" - address: cosmos1zwg6tpl8aw4rawv8sgag9086lpw5hv33u5ctr2 - pub_key: - '@type': /cosmos.crypto.secp256k1.PubKey - key: ApDrE38zZdd7wLmFS9YmqO684y5DG6fjZ4rVeihF/AQD - sequence: "1" -- '@type': /cosmos.auth.v1beta1.ModuleAccount - base_account: - account_number: "8" - address: cosmos1yl6hdjhmkf37639730gffanpzndzdpmhwlkfhr - pub_key: null - sequence: "0" - name: transfer - permissions: - - minter - - burner -- '@type': /cosmos.auth.v1beta1.ModuleAccount - base_account: - account_number: "4" - address: cosmos1fl48vsnmsdzcv85q5d2q4z5ajdha8yu34mf0eh - pub_key: null - sequence: "0" - name: bonded_tokens_pool - permissions: - - burner - - staking -- '@type': /cosmos.auth.v1beta1.ModuleAccount - base_account: - account_number: "5" - address: cosmos1tygms3xhhs3yv487phx3dw4a95jn7t7lpm470r - pub_key: null - sequence: "0" - name: not_bonded_tokens_pool - permissions: - - burner - - staking -- '@type': /cosmos.auth.v1beta1.ModuleAccount - base_account: - account_number: "6" - address: cosmos10d07y265gmmuvt4z0w9aw880jnsr700j6zn9kn - pub_key: null - sequence: "0" - name: gov - permissions: - - burner -- '@type': /cosmos.auth.v1beta1.ModuleAccount - base_account: - account_number: "3" - address: cosmos1jv65s3grqf6v6jl3dp4t6c9t9rk99cd88lyufl - pub_key: null - sequence: "0" - name: distribution - permissions: [] -- '@type': /cosmos.auth.v1beta1.BaseAccount - account_number: "1" - address: cosmos147k3r7v2tvwqhcmaxcfql7j8rmkrlsemxshd3j - pub_key: null - sequence: "0" -- '@type': /cosmos.auth.v1beta1.ModuleAccount - base_account: - account_number: "7" - address: cosmos1m3h30wlvsf8llruxtpukdvsy0km2kum8g38c8q - pub_key: null - sequence: "0" - name: mint - permissions: - - minter -- '@type': /cosmos.auth.v1beta1.ModuleAccount - base_account: - account_number: "2" - address: cosmos17xpfvakm2amg962yls6f84z3kell8c5lserqta - pub_key: null - sequence: "0" - name: fee_collector - permissions: [] -pagination: - next_key: null - total: "0" -``` - -#### params - -The `params` command allow users to query the current auth parameters. - -```bash -simd query auth params [flags] -``` - -Example: - -```bash -simd query auth params -``` - -Example Output: - -```bash -max_memo_characters: "256" -sig_verify_cost_ed25519: "590" -sig_verify_cost_secp256k1: "1000" -tx_sig_limit: "7" -tx_size_cost_per_byte: "10" -``` - -### Transactions - -The `auth` module supports transactions commands to help you with signing and more. Compared to other modules you can access directly the `auth` module transactions commands using the only `tx` command. - -Use directly the `--help` flag to get more information about the `tx` command. - -```bash -simd tx --help -``` - -#### `sign` - -The `sign` command allows users to sign transactions that was generated offline. - -```bash -simd tx sign tx.json --from $ALICE > tx.signed.json -``` - -The result is a signed transaction that can be broadcasted to the network thanks to the broadcast command. - -More information about the `sign` command can be found running `simd tx sign --help`. - -#### `sign-batch` - -The `sign-batch` command allows users to sign multiples offline generated transactions. -The transactions can be in one file, with one tx per line, or in multiple files. - -```bash -simd tx sign txs.json --from $ALICE > tx.signed.json -``` - -or - -```bash -simd tx sign tx1.json tx2.json tx3.json --from $ALICE > tx.signed.json -``` - -The result is multiples signed transactions. For combining the signed transactions into one transactions, use the `--append` flag. - -More information about the `sign-batch` command can be found running `simd tx sign-batch --help`. - -#### `multi-sign` - -The `multi-sign` command allows users to sign transactions that was generated offline by a multisig account. - -```bash -simd tx multisign transaction.json k1k2k3 k1sig.json k2sig.json k3sig.json -``` - -Where `k1k2k3` is the multisig account address, `k1sig.json` is the signature of the first signer, `k2sig.json` is the signature of the second signer, and `k3sig.json` is the signature of the third signer. - -##### Nested multisig transactions - -To allow transactions to be signed by nested multisigs, meaning that a participant of a multisig account can be another multisig account, the `--skip-signature-verification` flag must be used. - -```bash -# First aggregate signatures of the multisig participant -simd tx multi-sign transaction.json ms1 ms1p1sig.json ms1p2sig.json --signature-only --skip-signature-verification > ms1sig.json - -# Then use the aggregated signatures and the other signatures to sign the final transaction -simd tx multi-sign transaction.json k1ms1 k1sig.json ms1sig.json --skip-signature-verification -``` - -Where `ms1` is the nested multisig account address, `ms1p1sig.json` is the signature of the first participant of the nested multisig account, `ms1p2sig.json` is the signature of the second participant of the nested multisig account, and `ms1sig.json` is the aggregated signature of the nested multisig account. - -`k1ms1` is a multisig account comprised of an individual signer and another nested multisig account (`ms1`). `k1sig.json` is the signature of the first signer of the individual member. - -More information about the `multi-sign` command can be found running `simd tx multi-sign --help`. - -#### `multisign-batch` - -The `multisign-batch` works the same way as `sign-batch`, but for multisig accounts. -With the difference that the `multisign-batch` command requires all transactions to be in one file, and the `--append` flag does not exist. - -More information about the `multisign-batch` command can be found running `simd tx multisign-batch --help`. - -#### `validate-signatures` - -The `validate-signatures` command allows users to validate the signatures of a signed transaction. - -```bash -$ simd tx validate-signatures tx.signed.json -Signers: - 0: cosmos1l6vsqhh7rnwsyr2kyz3jjg3qduaz8gwgyl8275 - -Signatures: - 0: cosmos1l6vsqhh7rnwsyr2kyz3jjg3qduaz8gwgyl8275 [OK] -``` - -More information about the `validate-signatures` command can be found running `simd tx validate-signatures --help`. - -#### `broadcast` - -The `broadcast` command allows users to broadcast a signed transaction to the network. - -```bash -simd tx broadcast tx.signed.json -``` - -More information about the `broadcast` command can be found running `simd tx broadcast --help`. - - -### gRPC - -A user can query the `auth` module using gRPC endpoints. - -#### Account - -The `account` endpoint allow users to query for an account by it's address. - -```bash -cosmos.auth.v1beta1.Query/Account -``` - -Example: - -```bash -grpcurl -plaintext \ - -d '{"address":"cosmos1.."}' \ - localhost:9090 \ - cosmos.auth.v1beta1.Query/Account -``` - -Example Output: - -```bash -{ - "account":{ - "@type":"/cosmos.auth.v1beta1.BaseAccount", - "address":"cosmos1zwg6tpl8aw4rawv8sgag9086lpw5hv33u5ctr2", - "pubKey":{ - "@type":"/cosmos.crypto.secp256k1.PubKey", - "key":"ApDrE38zZdd7wLmFS9YmqO684y5DG6fjZ4rVeihF/AQD" - }, - "sequence":"1" - } -} -``` - -#### Accounts - -The `accounts` endpoint allow users to query all the available accounts. - -```bash -cosmos.auth.v1beta1.Query/Accounts -``` - -Example: - -```bash -grpcurl -plaintext \ - localhost:9090 \ - cosmos.auth.v1beta1.Query/Accounts -``` - -Example Output: - -```bash -{ - "accounts":[ - { - "@type":"/cosmos.auth.v1beta1.BaseAccount", - "address":"cosmos1zwg6tpl8aw4rawv8sgag9086lpw5hv33u5ctr2", - "pubKey":{ - "@type":"/cosmos.crypto.secp256k1.PubKey", - "key":"ApDrE38zZdd7wLmFS9YmqO684y5DG6fjZ4rVeihF/AQD" - }, - "sequence":"1" - }, - { - "@type":"/cosmos.auth.v1beta1.ModuleAccount", - "baseAccount":{ - "address":"cosmos1yl6hdjhmkf37639730gffanpzndzdpmhwlkfhr", - "accountNumber":"8" - }, - "name":"transfer", - "permissions":[ - "minter", - "burner" - ] - }, - { - "@type":"/cosmos.auth.v1beta1.ModuleAccount", - "baseAccount":{ - "address":"cosmos1fl48vsnmsdzcv85q5d2q4z5ajdha8yu34mf0eh", - "accountNumber":"4" - }, - "name":"bonded_tokens_pool", - "permissions":[ - "burner", - "staking" - ] - }, - { - "@type":"/cosmos.auth.v1beta1.ModuleAccount", - "baseAccount":{ - "address":"cosmos1tygms3xhhs3yv487phx3dw4a95jn7t7lpm470r", - "accountNumber":"5" - }, - "name":"not_bonded_tokens_pool", - "permissions":[ - "burner", - "staking" - ] - }, - { - "@type":"/cosmos.auth.v1beta1.ModuleAccount", - "baseAccount":{ - "address":"cosmos10d07y265gmmuvt4z0w9aw880jnsr700j6zn9kn", - "accountNumber":"6" - }, - "name":"gov", - "permissions":[ - "burner" - ] - }, - { - "@type":"/cosmos.auth.v1beta1.ModuleAccount", - "baseAccount":{ - "address":"cosmos1jv65s3grqf6v6jl3dp4t6c9t9rk99cd88lyufl", - "accountNumber":"3" - }, - "name":"distribution" - }, - { - "@type":"/cosmos.auth.v1beta1.BaseAccount", - "accountNumber":"1", - "address":"cosmos147k3r7v2tvwqhcmaxcfql7j8rmkrlsemxshd3j" - }, - { - "@type":"/cosmos.auth.v1beta1.ModuleAccount", - "baseAccount":{ - "address":"cosmos1m3h30wlvsf8llruxtpukdvsy0km2kum8g38c8q", - "accountNumber":"7" - }, - "name":"mint", - "permissions":[ - "minter" - ] - }, - { - "@type":"/cosmos.auth.v1beta1.ModuleAccount", - "baseAccount":{ - "address":"cosmos17xpfvakm2amg962yls6f84z3kell8c5lserqta", - "accountNumber":"2" - }, - "name":"fee_collector" - } - ], - "pagination":{ - "total":"9" - } -} -``` - -#### Params - -The `params` endpoint allow users to query the current auth parameters. - -```bash -cosmos.auth.v1beta1.Query/Params -``` - -Example: - -```bash -grpcurl -plaintext \ - localhost:9090 \ - cosmos.auth.v1beta1.Query/Params -``` - -Example Output: - -```bash -{ - "params": { - "maxMemoCharacters": "256", - "txSigLimit": "7", - "txSizeCostPerByte": "10", - "sigVerifyCostEd25519": "590", - "sigVerifyCostSecp256k1": "1000" - } -} -``` - -### REST - -A user can query the `auth` module using REST endpoints. - -#### Account - -The `account` endpoint allow users to query for an account by it's address. - -```bash -/cosmos/auth/v1beta1/account?address={address} -``` - -#### Accounts - -The `accounts` endpoint allow users to query all the available accounts. - -```bash -/cosmos/auth/v1beta1/accounts -``` - -#### Params - -The `params` endpoint allow users to query the current auth parameters. - -```bash -/cosmos/auth/v1beta1/params -``` diff --git a/.gitbook/developers/modules/core/authz/README.md b/.gitbook/developers/modules/core/authz/README.md deleted file mode 100644 index 676654a2..00000000 --- a/.gitbook/developers/modules/core/authz/README.md +++ /dev/null @@ -1,355 +0,0 @@ ---- -sidebar_position: 1 ---- - -# `x/authz` - -## Abstract - -`x/authz` is an implementation of a Cosmos SDK module, per [ADR 30](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-030-authz-module.md), that allows -granting arbitrary privileges from one account (the granter) to another account (the grantee). Authorizations must be granted for a particular Msg service method one by one using an implementation of the `Authorization` interface. - -## Contents - -* [Concepts](#concepts) - * [Authorization and Grant](#authorization-and-grant) - * [Built-in Authorizations](#built-in-authorizations) - * [Gas](#gas) -* [State](#state) - * [Grant](#grant) - * [GrantQueue](#grantqueue) -* [Messages](#messages) - * [MsgGrant](#msggrant) - * [MsgRevoke](#msgrevoke) - * [MsgExec](#msgexec) -* [Events](#events) -* [Client](#client) - * [CLI](#cli) - * [gRPC](#grpc) - * [REST](#rest) - -## Concepts - -### Authorization and Grant - -The `x/authz` module defines interfaces and messages grant authorizations to perform actions -on behalf of one account to other accounts. The design is defined in the [ADR 030](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-030-authz-module.md). - -A *grant* is an allowance to execute a Msg by the grantee on behalf of the granter. -Authorization is an interface that must be implemented by a concrete authorization logic to validate and execute grants. Authorizations are extensible and can be defined for any Msg service method even outside of the module where the Msg method is defined. See the `SendAuthorization` example in the next section for more details. - -**Note:** The authz module is different from the [auth (authentication)](../auth/) module that is responsible for specifying the base transaction and account types. - -```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/x/authz/authorizations.go#L11-L25 -``` - -### Built-in Authorizations - -The Cosmos SDK `x/authz` module comes with following authorization types: - -#### GenericAuthorization - -`GenericAuthorization` implements the `Authorization` interface that gives unrestricted permission to execute the provided Msg on behalf of granter's account. - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/authz/v1beta1/authz.proto#L14-L22 -``` - -```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/x/authz/generic_authorization.go#L16-L29 -``` - -* `msg` stores Msg type URL. - -#### SendAuthorization - -`SendAuthorization` implements the `Authorization` interface for the `cosmos.bank.v1beta1.MsgSend` Msg. - -* It takes a (positive) `SpendLimit` that specifies the maximum amount of tokens the grantee can spend. The `SpendLimit` is updated as the tokens are spent. -* It takes an (optional) `AllowList` that specifies to which addresses a grantee can send token. - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/bank/v1beta1/authz.proto#L11-L30 -``` - -```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/x/bank/types/send_authorization.go#L29-L62 -``` - -* `spend_limit` keeps track of how many coins are left in the authorization. -* `allow_list` specifies an optional list of addresses to whom the grantee can send tokens on behalf of the granter. - -#### StakeAuthorization - -`StakeAuthorization` implements the `Authorization` interface for messages in the [staking module](https://docs.cosmos.network/v0.44/modules/staking/). It takes an `AuthorizationType` to specify whether you want to authorise delegating, undelegating or redelegating (i.e. these have to be authorised seperately). It also takes a required `MaxTokens` that keeps track of a limit to the amount of tokens that can be delegated/undelegated/redelegated. If left empty, the amount is unlimited. Additionally, this Msg takes an `AllowList` or a `DenyList`, which allows you to select which validators you allow or deny grantees to stake with. - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/staking/v1beta1/authz.proto#L11-L35 -``` - -```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/x/staking/types/authz.go#L15-L35 -``` - -### Gas - -In order to prevent DoS attacks, granting `StakeAuthorization`s with `x/authz` incurs gas. `StakeAuthorization` allows you to authorize another account to delegate, undelegate, or redelegate to validators. The authorizer can define a list of validators they allow or deny delegations to. The Cosmos SDK iterates over these lists and charge 10 gas for each validator in both of the lists. - -Since the state maintaining a list for granter, grantee pair with same expiration, we are iterating over the list to remove the grant (incase of any revoke of paritcular `msgType`) from the list and we are charging 20 gas per iteration. - -## State - -### Grant - -Grants are identified by combining granter address (the address bytes of the granter), grantee address (the address bytes of the grantee) and Authorization type (its type URL). Hence we only allow one grant for the (granter, grantee, Authorization) triple. - -* Grant: `0x01 | granter_address_len (1 byte) | granter_address_bytes | grantee_address_len (1 byte) | grantee_address_bytes | msgType_bytes -> ProtocolBuffer(AuthorizationGrant)` - -The grant object encapsulates an `Authorization` type and an expiration timestamp: - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/authz/v1beta1/authz.proto#L24-L32 -``` - -### GrantQueue - -We are maintaining a queue for authz pruning. Whenever a grant is created, an item will be added to `GrantQueue` with a key of expiration, granter, grantee. - -In `EndBlock` (which runs for every block) we continuously check and prune the expired grants by forming a prefix key with current blocktime that passed the stored expiration in `GrantQueue`, we iterate through all the matched records from `GrantQueue` and delete them from the `GrantQueue` & `Grant`s store. - -```go reference -https://github.com/cosmos/cosmos-sdk/blob/5f4ddc6f80f9707320eec42182184207fff3833a/x/authz/keeper/keeper.go#L378-L403 -``` - -* GrantQueue: `0x02 | expiration_bytes | granter_address_len (1 byte) | granter_address_bytes | grantee_address_len (1 byte) | grantee_address_bytes -> ProtocalBuffer(GrantQueueItem)` - -The `expiration_bytes` are the expiration date in UTC with the format `"2006-01-02T15:04:05.000000000"`. - -```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/x/authz/keeper/keys.go#L77-L93 -``` - -The `GrantQueueItem` object contains the list of type urls between granter and grantee that expire at the time indicated in the key. - -## Messages - -In this section we describe the processing of messages for the authz module. - -### MsgGrant - -An authorization grant is created using the `MsgGrant` message. -If there is already a grant for the `(granter, grantee, Authorization)` triple, then the new grant overwrites the previous one. To update or extend an existing grant, a new grant with the same `(granter, grantee, Authorization)` triple should be created. - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/authz/v1beta1/tx.proto#L35-L45 -``` - -The message handling should fail if: - -* both granter and grantee have the same address. -* provided `Expiration` time is less than current unix timestamp (but a grant will be created if no `expiration` time is provided since `expiration` is optional). -* provided `Grant.Authorization` is not implemented. -* `Authorization.MsgTypeURL()` is not defined in the router (there is no defined handler in the app router to handle that Msg types). - -### MsgRevoke - -A grant can be removed with the `MsgRevoke` message. - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/authz/v1beta1/tx.proto#L69-L78 -``` - -The message handling should fail if: - -* both granter and grantee have the same address. -* provided `MsgTypeUrl` is empty. - -NOTE: The `MsgExec` message removes a grant if the grant has expired. - -### MsgExec - -When a grantee wants to execute a transaction on behalf of a granter, they must send `MsgExec`. - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/authz/v1beta1/tx.proto#L52-L63 -``` - -The message handling should fail if: - -* provided `Authorization` is not implemented. -* grantee doesn't have permission to run the transaction. -* if granted authorization is expired. - -## Events - -The authz module emits proto events defined in [the Protobuf reference](https://buf.build/cosmos/cosmos-sdk/docs/main/cosmos.authz.v1beta1#cosmos.authz.v1beta1.EventGrant). - -## Client - -### CLI - -A user can query and interact with the `authz` module using the CLI. - -#### Query - -The `query` commands allow users to query `authz` state. - -```bash -simd query authz --help -``` - -##### grants - -The `grants` command allows users to query grants for a granter-grantee pair. If the message type URL is set, it selects grants only for that message type. - -```bash -simd query authz grants [granter-addr] [grantee-addr] [msg-type-url]? [flags] -``` - -Example: - -```bash -simd query authz grants cosmos1.. cosmos1.. /cosmos.bank.v1beta1.MsgSend -``` - -Example Output: - -```bash -grants: -- authorization: - '@type': /cosmos.bank.v1beta1.SendAuthorization - spend_limit: - - amount: "100" - denom: stake - expiration: "2022-01-01T00:00:00Z" -pagination: null -``` - -#### Transactions - -The `tx` commands allow users to interact with the `authz` module. - -```bash -simd tx authz --help -``` - -##### exec - -The `exec` command allows a grantee to execute a transaction on behalf of granter. - -```bash - simd tx authz exec [tx-json-file] --from [grantee] [flags] -``` - -Example: - -```bash -simd tx authz exec tx.json --from=cosmos1.. -``` - -##### grant - -The `grant` command allows a granter to grant an authorization to a grantee. - -```bash -simd tx authz grant --from [flags] -``` - -Example: - -```bash -simd tx authz grant cosmos1.. send --spend-limit=100stake --from=cosmos1.. -``` - -##### revoke - -The `revoke` command allows a granter to revoke an authorization from a grantee. - -```bash -simd tx authz revoke [grantee] [msg-type-url] --from=[granter] [flags] -``` - -Example: - -```bash -simd tx authz revoke cosmos1.. /cosmos.bank.v1beta1.MsgSend --from=cosmos1.. -``` - -### gRPC - -A user can query the `authz` module using gRPC endpoints. - -#### Grants - -The `Grants` endpoint allows users to query grants for a granter-grantee pair. If the message type URL is set, it selects grants only for that message type. - -```bash -cosmos.authz.v1beta1.Query/Grants -``` - -Example: - -```bash -grpcurl -plaintext \ - -d '{"granter":"cosmos1..","grantee":"cosmos1..","msg_type_url":"/cosmos.bank.v1beta1.MsgSend"}' \ - localhost:9090 \ - cosmos.authz.v1beta1.Query/Grants -``` - -Example Output: - -```bash -{ - "grants": [ - { - "authorization": { - "@type": "/cosmos.bank.v1beta1.SendAuthorization", - "spendLimit": [ - { - "denom":"stake", - "amount":"100" - } - ] - }, - "expiration": "2022-01-01T00:00:00Z" - } - ] -} -``` - -### REST - -A user can query the `authz` module using REST endpoints. - -```bash -/cosmos/authz/v1beta1/grants -``` - -Example: - -```bash -curl "localhost:1317/cosmos/authz/v1beta1/grants?granter=cosmos1..&grantee=cosmos1..&msg_type_url=/cosmos.bank.v1beta1.MsgSend" -``` - -Example Output: - -```bash -{ - "grants": [ - { - "authorization": { - "@type": "/cosmos.bank.v1beta1.SendAuthorization", - "spend_limit": [ - { - "denom": "stake", - "amount": "100" - } - ] - }, - "expiration": "2022-01-01T00:00:00Z" - } - ], - "pagination": null -} -``` diff --git a/.gitbook/developers/modules/core/bank/README.md b/.gitbook/developers/modules/core/bank/README.md deleted file mode 100644 index a7eba4ae..00000000 --- a/.gitbook/developers/modules/core/bank/README.md +++ /dev/null @@ -1,1039 +0,0 @@ ---- -sidebar_position: 1 ---- - -# `x/bank` - -## Abstract - -This document specifies the bank module of the Cosmos SDK. - -The bank module is responsible for handling multi-asset coin transfers between -accounts and tracking special-case pseudo-transfers which must work differently -with particular kinds of accounts (notably delegating/undelegating for vesting -accounts). It exposes several interfaces with varying capabilities for secure -interaction with other modules which must alter user balances. - -In addition, the bank module tracks and provides query support for the total -supply of all assets used in the application. - -This module is used in the Cosmos Hub. - -## Contents - -* [Supply](#supply) - * [Total Supply](#total-supply) -* [Module Accounts](#module-accounts) - * [Permissions](#permissions) -* [State](#state) -* [Params](#params) -* [Keepers](#keepers) -* [Messages](#messages) -* [Events](#events) - * [Message Events](#message-events) - * [Keeper Events](#keeper-events) -* [Parameters](#parameters) - * [SendEnabled](#sendenabled) - * [DefaultSendEnabled](#defaultsendenabled) -* [Client](#client) - * [CLI](#cli) - * [Query](#query) - * [Transactions](#transactions) -* [gRPC](#grpc) - -## Supply - -The `supply` functionality: - -* passively tracks the total supply of coins within a chain, -* provides a pattern for modules to hold/interact with `Coins`, and -* introduces the invariant check to verify a chain's total supply. - -### Total Supply - -The total `Supply` of the network is equal to the sum of all coins from the -account. The total supply is updated every time a `Coin` is minted (eg: as part -of the inflation mechanism) or burned (eg: due to slashing or if a governance -proposal is vetoed). - -## Module Accounts - -The supply functionality introduces a new type of `auth.Account` which can be used by -modules to allocate tokens and in special cases mint or burn tokens. At a base -level these module accounts are capable of sending/receiving tokens to and from -`auth.Account`s and other module accounts. This design replaces previous -alternative designs where, to hold tokens, modules would burn the incoming -tokens from the sender account, and then track those tokens internally. Later, -in order to send tokens, the module would need to effectively mint tokens -within a destination account. The new design removes duplicate logic between -modules to perform this accounting. - -The `ModuleAccount` interface is defined as follows: - -```go -type ModuleAccount interface { - auth.Account // same methods as the Account interface - - GetName() string // name of the module; used to obtain the address - GetPermissions() []string // permissions of module account - HasPermission(string) bool -} -``` - -> **WARNING!** -> Any module or message handler that allows either direct or indirect sending of funds must explicitly guarantee those funds cannot be sent to module accounts (unless allowed). - -The supply `Keeper` also introduces new wrapper functions for the auth `Keeper` -and the bank `Keeper` that are related to `ModuleAccount`s in order to be able -to: - -* Get and set `ModuleAccount`s by providing the `Name`. -* Send coins from and to other `ModuleAccount`s or standard `Account`s - (`BaseAccount` or `VestingAccount`) by passing only the `Name`. -* `Mint` or `Burn` coins for a `ModuleAccount` (restricted to its permissions). - -### Permissions - -Each `ModuleAccount` has a different set of permissions that provide different -object capabilities to perform certain actions. Permissions need to be -registered upon the creation of the supply `Keeper` so that every time a -`ModuleAccount` calls the allowed functions, the `Keeper` can lookup the -permissions to that specific account and perform or not perform the action. - -The available permissions are: - -* `Minter`: allows for a module to mint a specific amount of coins. -* `Burner`: allows for a module to burn a specific amount of coins. -* `Staking`: allows for a module to delegate and undelegate a specific amount of coins. - -## State - -The `x/bank` module keeps state of the following primary objects: - -1. Account balances -2. Denomination metadata -3. The total supply of all balances -4. Information on which denominations are allowed to be sent. - -In addition, the `x/bank` module keeps the following indexes to manage the -aforementioned state: - -* Supply Index: `0x0 | byte(denom) -> byte(amount)` -* Denom Metadata Index: `0x1 | byte(denom) -> ProtocolBuffer(Metadata)` -* Balances Index: `0x2 | byte(address length) | []byte(address) | []byte(balance.Denom) -> ProtocolBuffer(balance)` -* Reverse Denomination to Address Index: `0x03 | byte(denom) | 0x00 | []byte(address) -> 0` - -## Params - -The bank module stores it's params in state with the prefix of `0x05`, -it can be updated with governance or the address with authority. - -* Params: `0x05 | ProtocolBuffer(Params)` - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/bank/v1beta1/bank.proto#L12-L23 -``` - -## Keepers - -The bank module provides these exported keeper interfaces that can be -passed to other modules that read or update account balances. Modules -should use the least-permissive interface that provides the functionality they -require. - -Best practices dictate careful review of `bank` module code to ensure that -permissions are limited in the way that you expect. - -### Denied Addresses - -The `x/bank` module accepts a map of addresses that are considered blocklisted -from directly and explicitly receiving funds through means such as `MsgSend` and -`MsgMultiSend` and direct API calls like `SendCoinsFromModuleToAccount`. - -Typically, these addresses are module accounts. If these addresses receive funds -outside the expected rules of the state machine, invariants are likely to be -broken and could result in a halted network. - -By providing the `x/bank` module with a blocklisted set of addresses, an error occurs for the operation if a user or client attempts to directly or indirectly send funds to a blocklisted account, for example, by using [IBC](https://ibc.cosmos.network). - -### Common Types - -#### Input - -An input of a multiparty transfer - -```protobuf -// Input models transaction input. -message Input { - string address = 1; - repeated cosmos.base.v1beta1.Coin coins = 2; -} -``` - -#### Output - -An output of a multiparty transfer. - -```protobuf -// Output models transaction outputs. -message Output { - string address = 1; - repeated cosmos.base.v1beta1.Coin coins = 2; -} -``` - -### BaseKeeper - -The base keeper provides full-permission access: the ability to arbitrary modify any account's balance and mint or burn coins. - -Restricted permission to mint per module could be achieved by using baseKeeper with `WithMintCoinsRestriction` to give specific restrictions to mint (e.g. only minting certain denom). - -```go -// Keeper defines a module interface that facilitates the transfer of coins -// between accounts. -type Keeper interface { - SendKeeper - WithMintCoinsRestriction(MintingRestrictionFn) BaseKeeper - - InitGenesis(context.Context, *types.GenesisState) - ExportGenesis(context.Context) *types.GenesisState - - GetSupply(ctx context.Context, denom string) sdk.Coin - HasSupply(ctx context.Context, denom string) bool - GetPaginatedTotalSupply(ctx context.Context, pagination *query.PageRequest) (sdk.Coins, *query.PageResponse, error) - IterateTotalSupply(ctx context.Context, cb func(sdk.Coin) bool) - GetDenomMetaData(ctx context.Context, denom string) (types.Metadata, bool) - HasDenomMetaData(ctx context.Context, denom string) bool - SetDenomMetaData(ctx context.Context, denomMetaData types.Metadata) - IterateAllDenomMetaData(ctx context.Context, cb func(types.Metadata) bool) - - SendCoinsFromModuleToAccount(ctx context.Context, senderModule string, recipientAddr sdk.AccAddress, amt sdk.Coins) error - SendCoinsFromModuleToModule(ctx context.Context, senderModule, recipientModule string, amt sdk.Coins) error - SendCoinsFromAccountToModule(ctx context.Context, senderAddr sdk.AccAddress, recipientModule string, amt sdk.Coins) error - DelegateCoinsFromAccountToModule(ctx context.Context, senderAddr sdk.AccAddress, recipientModule string, amt sdk.Coins) error - UndelegateCoinsFromModuleToAccount(ctx context.Context, senderModule string, recipientAddr sdk.AccAddress, amt sdk.Coins) error - MintCoins(ctx context.Context, moduleName string, amt sdk.Coins) error - BurnCoins(ctx context.Context, moduleName string, amt sdk.Coins) error - - DelegateCoins(ctx context.Context, delegatorAddr, moduleAccAddr sdk.AccAddress, amt sdk.Coins) error - UndelegateCoins(ctx context.Context, moduleAccAddr, delegatorAddr sdk.AccAddress, amt sdk.Coins) error - - // GetAuthority gets the address capable of executing governance proposal messages. Usually the gov module account. - GetAuthority() string - - types.QueryServer -} -``` - -### SendKeeper - -The send keeper provides access to account balances and the ability to transfer coins between -accounts. The send keeper does not alter the total supply (mint or burn coins). - -```go -// SendKeeper defines a module interface that facilitates the transfer of coins -// between accounts without the possibility of creating coins. -type SendKeeper interface { - ViewKeeper - - AppendSendRestriction(restriction SendRestrictionFn) - PrependSendRestriction(restriction SendRestrictionFn) - ClearSendRestriction() - - InputOutputCoins(ctx sdk.Context, input types.Input, outputs []types.Output) error - SendCoins(ctx sdk.Context, fromAddr, toAddr sdk.AccAddress, amt sdk.Coins) error - - GetParams(ctx context.Context) types.Params - SetParams(ctx context.Context, params types.Params) error - - IsSendEnabledDenom(ctx context.Context, denom string) bool - SetSendEnabled(ctx context.Context, denom string, value bool) - SetAllSendEnabled(ctx context.Context, sendEnableds []*types.SendEnabled) - DeleteSendEnabled(ctx context.Context, denom string) - IterateSendEnabledEntries(ctx context.Context, cb func(denom string, sendEnabled bool) (stop bool)) - GetAllSendEnabledEntries(ctx context.Context) []types.SendEnabled - - IsSendEnabledCoin(ctx context.Context, coin sdk.Coin) bool - IsSendEnabledCoins(ctx context.Context, coins ...sdk.Coin) error - - BlockedAddr(addr sdk.AccAddress) bool -} -``` - -#### Send Restrictions - -The `SendKeeper` applies a `SendRestrictionFn` before each transfer of funds. - -```golang -// A SendRestrictionFn can restrict sends and/or provide a new receiver address. -type SendRestrictionFn func(ctx context.Context, fromAddr, toAddr sdk.AccAddress, amt sdk.Coins) (newToAddr sdk.AccAddress, err error) -``` - -After the `SendKeeper` (or `BaseKeeper`) has been created, send restrictions can be added to it using the `AppendSendRestriction` or `PrependSendRestriction` functions. -Both functions compose the provided restriction with any previously provided restrictions. -`AppendSendRestriction` adds the provided restriction to be run after any previously provided send restrictions. -`PrependSendRestriction` adds the restriction to be run before any previously provided send restrictions. -The composition will short-circuit when an error is encountered. I.e. if the first one returns an error, the second is not run. - -During `SendCoins`, the send restriction is applied after coins are removed from the from address, but before adding them to the to address. -During `InputOutputCoins`, the send restriction is applied after the input coins are removed and once for each output before the funds are added. - -A send restriction function should make use of a custom value in the context to allow bypassing that specific restriction. - -Send Restrictions are not placed on `ModuleToAccount` or `ModuleToModule` transfers. This is done due to modules needing to move funds to user accounts and other module accounts. This is a design decision to allow for more flexibility in the state machine. The state machine should be able to move funds between module accounts and user accounts without restrictions. - -Secondly this limitation would limit the usage of the state machine even for itself. users would not be able to receive rewards, not be able to move funds between module accounts. In the case that a user sends funds from a user account to the community pool and then a governance proposal is used to get those tokens into the users account this would fall under the discretion of the app chain developer to what they would like to do here. We can not make strong assumptions here. -Thirdly, this issue could lead into a chain halt if a token is disabled and the token is moved in the begin/endblock. This is the last reason we see the current change and more damaging then beneficial for users. - -For example, in your module's keeper package, you'd define the send restriction function: - -```golang -var _ banktypes.SendRestrictionFn = Keeper{}.SendRestrictionFn - -func (k Keeper) SendRestrictionFn(ctx context.Context, fromAddr, toAddr sdk.AccAddress, amt sdk.Coins) (sdk.AccAddress, error) { - // Bypass if the context says to. - if mymodule.HasBypass(ctx) { - return toAddr, nil - } - - // Your custom send restriction logic goes here. - return nil, errors.New("not implemented") -} -``` - -The bank keeper should be provided to your keeper's constructor so the send restriction can be added to it: - -```golang -func NewKeeper(cdc codec.BinaryCodec, storeKey storetypes.StoreKey, bankKeeper mymodule.BankKeeper) Keeper { - rv := Keeper{/*...*/} - bankKeeper.AppendSendRestriction(rv.SendRestrictionFn) - return rv -} -``` - -Then, in the `mymodule` package, define the context helpers: - -```golang -const bypassKey = "bypass-mymodule-restriction" - -// WithBypass returns a new context that will cause the mymodule bank send restriction to be skipped. -func WithBypass(ctx context.Context) context.Context { - return sdk.UnwrapSDKContext(ctx).WithValue(bypassKey, true) -} - -// WithoutBypass returns a new context that will cause the mymodule bank send restriction to not be skipped. -func WithoutBypass(ctx context.Context) context.Context { - return sdk.UnwrapSDKContext(ctx).WithValue(bypassKey, false) -} - -// HasBypass checks the context to see if the mymodule bank send restriction should be skipped. -func HasBypass(ctx context.Context) bool { - bypassValue := ctx.Value(bypassKey) - if bypassValue == nil { - return false - } - bypass, isBool := bypassValue.(bool) - return isBool && bypass -} -``` - -Now, anywhere where you want to use `SendCoins` or `InputOutputCoins`, but you don't want your send restriction applied: - -```golang -func (k Keeper) DoThing(ctx context.Context, fromAddr, toAddr sdk.AccAddress, amt sdk.Coins) error { - return k.bankKeeper.SendCoins(mymodule.WithBypass(ctx), fromAddr, toAddr, amt) -} -``` - -### ViewKeeper - -The view keeper provides read-only access to account balances. The view keeper does not have balance alteration functionality. All balance lookups are `O(1)`. - -```go -// ViewKeeper defines a module interface that facilitates read only access to -// account balances. -type ViewKeeper interface { - ValidateBalance(ctx context.Context, addr sdk.AccAddress) error - HasBalance(ctx context.Context, addr sdk.AccAddress, amt sdk.Coin) bool - - GetAllBalances(ctx context.Context, addr sdk.AccAddress) sdk.Coins - GetAccountsBalances(ctx context.Context) []types.Balance - GetBalance(ctx context.Context, addr sdk.AccAddress, denom string) sdk.Coin - LockedCoins(ctx context.Context, addr sdk.AccAddress) sdk.Coins - SpendableCoins(ctx context.Context, addr sdk.AccAddress) sdk.Coins - SpendableCoin(ctx context.Context, addr sdk.AccAddress, denom string) sdk.Coin - - IterateAccountBalances(ctx context.Context, addr sdk.AccAddress, cb func(coin sdk.Coin) (stop bool)) - IterateAllBalances(ctx context.Context, cb func(address sdk.AccAddress, coin sdk.Coin) (stop bool)) -} -``` - -## Messages - -### MsgSend - -Send coins from one address to another. - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/bank/v1beta1/tx.proto#L38-L53 -``` - -The message will fail under the following conditions: - -* The coins do not have sending enabled -* The `to` address is restricted - -### MsgMultiSend - -Send coins from one sender and to a series of different address. If any of the receiving addresses do not correspond to an existing account, a new account is created. - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/bank/v1beta1/tx.proto#L58-L69 -``` - -The message will fail under the following conditions: - -* Any of the coins do not have sending enabled -* Any of the `to` addresses are restricted -* Any of the coins are locked -* The inputs and outputs do not correctly correspond to one another - -### MsgUpdateParams - -The `bank` module params can be updated through `MsgUpdateParams`, which can be done using governance proposal. The signer will always be the `gov` module account address. - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/bank/v1beta1/tx.proto#L74-L88 -``` - -The message handling can fail if: - -* signer is not the gov module account address. - -### MsgSetSendEnabled - -Used with the x/gov module to set create/edit SendEnabled entries. - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/bank/v1beta1/tx.proto#L96-L117 -``` - -The message will fail under the following conditions: - -* The authority is not a bech32 address. -* The authority is not x/gov module's address. -* There are multiple SendEnabled entries with the same Denom. -* One or more SendEnabled entries has an invalid Denom. - -## Events - -The bank module emits the following events: - -### Message Events - -#### MsgSend - -| Type | Attribute Key | Attribute Value | -| -------- | ------------- | ------------------ | -| transfer | recipient | {recipientAddress} | -| transfer | amount | {amount} | -| message | module | bank | -| message | action | send | -| message | sender | {senderAddress} | - -#### MsgMultiSend - -| Type | Attribute Key | Attribute Value | -| -------- | ------------- | ------------------ | -| transfer | recipient | {recipientAddress} | -| transfer | amount | {amount} | -| message | module | bank | -| message | action | multisend | -| message | sender | {senderAddress} | - -### Keeper Events - -In addition to message events, the bank keeper will produce events when the following methods are called (or any method which ends up calling them) - -#### MintCoins - -```json -{ - "type": "coinbase", - "attributes": [ - { - "key": "minter", - "value": "{{sdk.AccAddress of the module minting coins}}", - "index": true - }, - { - "key": "amount", - "value": "{{sdk.Coins being minted}}", - "index": true - } - ] -} -``` - -```json -{ - "type": "coin_received", - "attributes": [ - { - "key": "receiver", - "value": "{{sdk.AccAddress of the module minting coins}}", - "index": true - }, - { - "key": "amount", - "value": "{{sdk.Coins being received}}", - "index": true - } - ] -} -``` - -#### BurnCoins - -```json -{ - "type": "burn", - "attributes": [ - { - "key": "burner", - "value": "{{sdk.AccAddress of the module burning coins}}", - "index": true - }, - { - "key": "amount", - "value": "{{sdk.Coins being burned}}", - "index": true - } - ] -} -``` - -```json -{ - "type": "coin_spent", - "attributes": [ - { - "key": "spender", - "value": "{{sdk.AccAddress of the module burning coins}}", - "index": true - }, - { - "key": "amount", - "value": "{{sdk.Coins being burned}}", - "index": true - } - ] -} -``` - -#### addCoins - -```json -{ - "type": "coin_received", - "attributes": [ - { - "key": "receiver", - "value": "{{sdk.AccAddress of the address beneficiary of the coins}}", - "index": true - }, - { - "key": "amount", - "value": "{{sdk.Coins being received}}", - "index": true - } - ] -} -``` - -#### subUnlockedCoins/DelegateCoins - -```json -{ - "type": "coin_spent", - "attributes": [ - { - "key": "spender", - "value": "{{sdk.AccAddress of the address which is spending coins}}", - "index": true - }, - { - "key": "amount", - "value": "{{sdk.Coins being spent}}", - "index": true - } - ] -} -``` - -## Parameters - -The bank module contains the following parameters - -### SendEnabled - -The SendEnabled parameter is now deprecated and not to be use. It is replaced -with state store records. - - -### DefaultSendEnabled - -The default send enabled value controls send transfer capability for all -coin denominations unless specifically included in the array of `SendEnabled` -parameters. - -## Client - -### CLI - -A user can query and interact with the `bank` module using the CLI. - -#### Query - -The `query` commands allow users to query `bank` state. - -```shell -simd query bank --help -``` - -##### balances - -The `balances` command allows users to query account balances by address. - -```shell -simd query bank balances [address] [flags] -``` - -Example: - -```shell -simd query bank balances cosmos1.. -``` - -Example Output: - -```yml -balances: -- amount: "1000000000" - denom: stake -pagination: - next_key: null - total: "0" -``` - -##### denom-metadata - -The `denom-metadata` command allows users to query metadata for coin denominations. A user can query metadata for a single denomination using the `--denom` flag or all denominations without it. - -```shell -simd query bank denom-metadata [flags] -``` - -Example: - -```shell -simd query bank denom-metadata --denom stake -``` - -Example Output: - -```yml -metadata: - base: stake - denom_units: - - aliases: - - STAKE - denom: stake - description: native staking token of simulation app - display: stake - name: SimApp Token - symbol: STK -``` - -##### total - -The `total` command allows users to query the total supply of coins. A user can query the total supply for a single coin using the `--denom` flag or all coins without it. - -```shell -simd query bank total [flags] -``` - -Example: - -```shell -simd query bank total --denom stake -``` - -Example Output: - -```yml -amount: "10000000000" -denom: stake -``` - -##### send-enabled - -The `send-enabled` command allows users to query for all or some SendEnabled entries. - -```shell -simd query bank send-enabled [denom1 ...] [flags] -``` - -Example: - -```shell -simd query bank send-enabled -``` - -Example output: - -```yml -send_enabled: -- denom: foocoin - enabled: true -- denom: barcoin -pagination: - next-key: null - total: 2 -``` - -#### Transactions - -The `tx` commands allow users to interact with the `bank` module. - -```shell -simd tx bank --help -``` - -##### send - -The `send` command allows users to send funds from one account to another. - -```shell -simd tx bank send [from_key_or_address] [to_address] [amount] [flags] -``` - -Example: - -```shell -simd tx bank send cosmos1.. cosmos1.. 100stake -``` - -## gRPC - -A user can query the `bank` module using gRPC endpoints. - -### Balance - -The `Balance` endpoint allows users to query account balance by address for a given denomination. - -```shell -cosmos.bank.v1beta1.Query/Balance -``` - -Example: - -```shell -grpcurl -plaintext \ - -d '{"address":"cosmos1..","denom":"stake"}' \ - localhost:9090 \ - cosmos.bank.v1beta1.Query/Balance -``` - -Example Output: - -```json -{ - "balance": { - "denom": "stake", - "amount": "1000000000" - } -} -``` - -### AllBalances - -The `AllBalances` endpoint allows users to query account balance by address for all denominations. - -```shell -cosmos.bank.v1beta1.Query/AllBalances -``` - -Example: - -```shell -grpcurl -plaintext \ - -d '{"address":"cosmos1.."}' \ - localhost:9090 \ - cosmos.bank.v1beta1.Query/AllBalances -``` - -Example Output: - -```json -{ - "balances": [ - { - "denom": "stake", - "amount": "1000000000" - } - ], - "pagination": { - "total": "1" - } -} -``` - -### DenomMetadata - -The `DenomMetadata` endpoint allows users to query metadata for a single coin denomination. - -```shell -cosmos.bank.v1beta1.Query/DenomMetadata -``` - -Example: - -```shell -grpcurl -plaintext \ - -d '{"denom":"stake"}' \ - localhost:9090 \ - cosmos.bank.v1beta1.Query/DenomMetadata -``` - -Example Output: - -```json -{ - "metadata": { - "description": "native staking token of simulation app", - "denomUnits": [ - { - "denom": "stake", - "aliases": [ - "STAKE" - ] - } - ], - "base": "stake", - "display": "stake", - "name": "SimApp Token", - "symbol": "STK" - } -} -``` - -### DenomsMetadata - -The `DenomsMetadata` endpoint allows users to query metadata for all coin denominations. - -```shell -cosmos.bank.v1beta1.Query/DenomsMetadata -``` - -Example: - -```shell -grpcurl -plaintext \ - localhost:9090 \ - cosmos.bank.v1beta1.Query/DenomsMetadata -``` - -Example Output: - -```json -{ - "metadatas": [ - { - "description": "native staking token of simulation app", - "denomUnits": [ - { - "denom": "stake", - "aliases": [ - "STAKE" - ] - } - ], - "base": "stake", - "display": "stake", - "name": "SimApp Token", - "symbol": "STK" - } - ], - "pagination": { - "total": "1" - } -} -``` - -### DenomOwners - -The `DenomOwners` endpoint allows users to query metadata for a single coin denomination. - -```shell -cosmos.bank.v1beta1.Query/DenomOwners -``` - -Example: - -```shell -grpcurl -plaintext \ - -d '{"denom":"stake"}' \ - localhost:9090 \ - cosmos.bank.v1beta1.Query/DenomOwners -``` - -Example Output: - -```json -{ - "denomOwners": [ - { - "address": "cosmos1..", - "balance": { - "denom": "stake", - "amount": "5000000000" - } - }, - { - "address": "cosmos1..", - "balance": { - "denom": "stake", - "amount": "5000000000" - } - }, - ], - "pagination": { - "total": "2" - } -} -``` - -### TotalSupply - -The `TotalSupply` endpoint allows users to query the total supply of all coins. - -```shell -cosmos.bank.v1beta1.Query/TotalSupply -``` - -Example: - -```shell -grpcurl -plaintext \ - localhost:9090 \ - cosmos.bank.v1beta1.Query/TotalSupply -``` - -Example Output: - -```json -{ - "supply": [ - { - "denom": "stake", - "amount": "10000000000" - } - ], - "pagination": { - "total": "1" - } -} -``` - -### SupplyOf - -The `SupplyOf` endpoint allows users to query the total supply of a single coin. - -```shell -cosmos.bank.v1beta1.Query/SupplyOf -``` - -Example: - -```shell -grpcurl -plaintext \ - -d '{"denom":"stake"}' \ - localhost:9090 \ - cosmos.bank.v1beta1.Query/SupplyOf -``` - -Example Output: - -```json -{ - "amount": { - "denom": "stake", - "amount": "10000000000" - } -} -``` - -### Params - -The `Params` endpoint allows users to query the parameters of the `bank` module. - -```shell -cosmos.bank.v1beta1.Query/Params -``` - -Example: - -```shell -grpcurl -plaintext \ - localhost:9090 \ - cosmos.bank.v1beta1.Query/Params -``` - -Example Output: - -```json -{ - "params": { - "defaultSendEnabled": true - } -} -``` - -### SendEnabled - -The `SendEnabled` enpoints allows users to query the SendEnabled entries of the `bank` module. - -Any denominations NOT returned, use the `Params.DefaultSendEnabled` value. - -```shell -cosmos.bank.v1beta1.Query/SendEnabled -``` - -Example: - -```shell -grpcurl -plaintext \ - localhost:9090 \ - cosmos.bank.v1beta1.Query/SendEnabled -``` - -Example Output: - -```json -{ - "send_enabled": [ - { - "denom": "foocoin", - "enabled": true - }, - { - "denom": "barcoin" - } - ], - "pagination": { - "next-key": null, - "total": 2 - } -} -``` diff --git a/.gitbook/developers/modules/core/circuit/README.md b/.gitbook/developers/modules/core/circuit/README.md deleted file mode 100644 index f3b75389..00000000 --- a/.gitbook/developers/modules/core/circuit/README.md +++ /dev/null @@ -1,170 +0,0 @@ -# `x/circuit` - -## Concepts - -Circuit Breaker is a module that is meant to avoid a chain needing to halt/shut down in the presence of a vulnerability, instead the module will allow specific messages or all messages to be disabled. When operating a chain, if it is app specific then a halt of the chain is less detrimental, but if there are applications built on top of the chain then halting is expensive due to the disturbance to applications. - -Circuit Breaker works with the idea that an address or set of addresses have the right to block messages from being executed and/or included in the mempool. Any address with a permission is able to reset the circuit breaker for the message. - -The transactions are checked and can be rejected at two points: - -* In `CircuitBreakerDecorator` [ante handler](https://docs.cosmos.network/main/learn/advanced/baseapp#antehandler): - -```go reference -https://github.com/cosmos/cosmos-sdk/blob/x/circuit/v0.1.0/x/circuit/ante/circuit.go#L27-L41 -``` - -* With a [message router check](https://docs.cosmos.network/main/learn/advanced/baseapp#msg-service-router): - -```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.50.1/baseapp/msg_service_router.go#L104-L115 -``` - -:::note -The `CircuitBreakerDecorator` works for most use cases, but [does not check the inner messages of a transaction](https://docs.cosmos.network/main/learn/beginner/tx-lifecycle#antehandler). This some transactions (such as `x/authz` transactions or some `x/gov` transactions) may pass the ante handler. **This does not affect the circuit breaker** as the message router check will still fail the transaction. -This tradeoff is to avoid introducing more dependencies in the `x/circuit` module. Chains can re-define the `CircuitBreakerDecorator` to check for inner messages if they wish to do so. -::: - -## State - -### Accounts - -* AccountPermissions `0x1 | account_address -> ProtocolBuffer(CircuitBreakerPermissions)` - -```go -type level int32 - -const ( - // LEVEL_NONE_UNSPECIFIED indicates that the account will have no circuit - // breaker permissions. - LEVEL_NONE_UNSPECIFIED = iota - // LEVEL_SOME_MSGS indicates that the account will have permission to - // trip or reset the circuit breaker for some Msg type URLs. If this level - // is chosen, a non-empty list of Msg type URLs must be provided in - // limit_type_urls. - LEVEL_SOME_MSGS - // LEVEL_ALL_MSGS indicates that the account can trip or reset the circuit - // breaker for Msg's of all type URLs. - LEVEL_ALL_MSGS - // LEVEL_SUPER_ADMIN indicates that the account can take all circuit breaker - // actions and can grant permissions to other accounts. - LEVEL_SUPER_ADMIN -) - -type Access struct { - level int32 - msgs []string // if full permission, msgs can be empty -} -``` - - -### Disable List - -List of type urls that are disabled. - -* DisableList `0x2 | msg_type_url -> []byte{}` - -## State Transitions - -### Authorize - -Authorize, is called by the module authority (default governance module account) or any account with `LEVEL_SUPER_ADMIN` to give permission to disable/enable messages to another account. There are three levels of permissions that can be granted. `LEVEL_SOME_MSGS` limits the number of messages that can be disabled. `LEVEL_ALL_MSGS` permits all messages to be disabled. `LEVEL_SUPER_ADMIN` allows an account to take all circuit breaker actions including authorizing and deauthorizing other accounts. - -```protobuf - // AuthorizeCircuitBreaker allows a super-admin to grant (or revoke) another - // account's circuit breaker permissions. - rpc AuthorizeCircuitBreaker(MsgAuthorizeCircuitBreaker) returns (MsgAuthorizeCircuitBreakerResponse); -``` - -### Trip - -Trip, is called by an authorized account to disable message execution for a specific msgURL. If empty, all the msgs will be disabled. - -```protobuf - // TripCircuitBreaker pauses processing of Msg's in the state machine. - rpc TripCircuitBreaker(MsgTripCircuitBreaker) returns (MsgTripCircuitBreakerResponse); -``` - -### Reset - -Reset is called by an authorized account to enable execution for a specific msgURL of previously disabled message. If empty, all the disabled messages will be enabled. - -```protobuf - // ResetCircuitBreaker resumes processing of Msg's in the state machine that - // have been been paused using TripCircuitBreaker. - rpc ResetCircuitBreaker(MsgResetCircuitBreaker) returns (MsgResetCircuitBreakerResponse); -``` - -## Messages - -### MsgAuthorizeCircuitBreaker - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/main/proto/cosmos/circuit/v1/tx.proto#L25-L75 -``` - -This message is expected to fail if: - -* the granter is not an account with permission level `LEVEL_SUPER_ADMIN` or the module authority - -### MsgTripCircuitBreaker - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/main/proto/cosmos/circuit/v1/tx.proto#L77-L93 -``` - -This message is expected to fail if: - -* if the signer does not have a permission level with the ability to disable the specified type url message - -### MsgResetCircuitBreaker - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/main/proto/cosmos/circuit/v1/tx.proto#L95-109 -``` - -This message is expected to fail if: - -* if the type url is not disabled - -## Events - list and describe event tags - -The circuit module emits the following events: - -### Message Events - -#### MsgAuthorizeCircuitBreaker - -| Type | Attribute Key | Attribute Value | -|---------|---------------|---------------------------| -| string | granter | {granterAddress} | -| string | grantee | {granteeAddress} | -| string | permission | {granteePermissions} | -| message | module | circuit | -| message | action | authorize_circuit_breaker | - -#### MsgTripCircuitBreaker - -| Type | Attribute Key | Attribute Value | -|----------|---------------|--------------------| -| string | authority | {authorityAddress} | -| []string | msg_urls | []string{msg_urls} | -| message | module | circuit | -| message | action | trip_circuit_breaker | - -#### ResetCircuitBreaker - -| Type | Attribute Key | Attribute Value | -|----------|---------------|--------------------| -| string | authority | {authorityAddress} | -| []string | msg_urls | []string{msg_urls} | -| message | module | circuit | -| message | action | reset_circuit_breaker | - - -## Keys - list of key prefixes used by the circuit module - -* `AccountPermissionPrefix` - `0x01` -* `DisableListPrefix` - `0x02` - -## Client - list and describe CLI commands and gRPC and REST endpoints diff --git a/.gitbook/developers/modules/core/consensus/README.md b/.gitbook/developers/modules/core/consensus/README.md deleted file mode 100644 index 902280a6..00000000 --- a/.gitbook/developers/modules/core/consensus/README.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -sidebar_position: 1 ---- - -# `x/consensus` - -Functionality to modify CometBFT's ABCI consensus params. diff --git a/.gitbook/developers/modules/core/crisis/README.md b/.gitbook/developers/modules/core/crisis/README.md deleted file mode 100644 index e4e29d0a..00000000 --- a/.gitbook/developers/modules/core/crisis/README.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -sidebar_position: 1 ---- - -# `x/crisis` - -## Overview - -The crisis module halts the blockchain under the circumstance that a blockchain -invariant is broken. Invariants can be registered with the application during the -application initialization process. - -## Contents - -* [State](#state) -* [Messages](#messages) -* [Events](#events) -* [Parameters](#parameters) -* [Client](#client) - * [CLI](#cli) - -## State - -### ConstantFee - -Due to the anticipated large gas cost requirement to verify an invariant (and -potential to exceed the maximum allowable block gas limit) a constant fee is -used instead of the standard gas consumption method. The constant fee is -intended to be larger than the anticipated gas cost of running the invariant -with the standard gas consumption method. - -The ConstantFee param is stored in the module params state with the prefix of `0x01`, -it can be updated with governance or the address with authority. - -* Params: `mint/params -> legacy_amino(sdk.Coin)` - -## Messages - -In this section we describe the processing of the crisis messages and the -corresponding updates to the state. - -### MsgVerifyInvariant - -Blockchain invariants can be checked using the `MsgVerifyInvariant` message. - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/crisis/v1beta1/tx.proto#L26-L42 -``` - -This message is expected to fail if: - -* the sender does not have enough coins for the constant fee -* the invariant route is not registered - -This message checks the invariant provided, and if the invariant is broken it -panics, halting the blockchain. If the invariant is broken, the constant fee is -never deducted as the transaction is never committed to a block (equivalent to -being refunded). However, if the invariant is not broken, the constant fee will -not be refunded. - -## Events - -The crisis module emits the following events: - -### Handlers - -#### MsgVerifyInvariance - -| Type | Attribute Key | Attribute Value | -|-----------|---------------|------------------| -| invariant | route | {invariantRoute} | -| message | module | crisis | -| message | action | verify_invariant | -| message | sender | {senderAddress} | - -## Parameters - -The crisis module contains the following parameters: - -| Key | Type | Example | -|-------------|---------------|-----------------------------------| -| ConstantFee | object (coin) | {"denom":"uatom","amount":"1000"} | - -## Client - -### CLI - -A user can query and interact with the `crisis` module using the CLI. - -#### Transactions - -The `tx` commands allow users to interact with the `crisis` module. - -```bash -simd tx crisis --help -``` - -##### invariant-broken - -The `invariant-broken` command submits proof when an invariant was broken to halt the chain - -```bash -simd tx crisis invariant-broken [module-name] [invariant-route] [flags] -``` - -Example: - -```bash -simd tx crisis invariant-broken bank total-supply --from=[keyname or address] -``` diff --git a/.gitbook/developers/modules/core/distribution/README.md b/.gitbook/developers/modules/core/distribution/README.md deleted file mode 100644 index 32858fd6..00000000 --- a/.gitbook/developers/modules/core/distribution/README.md +++ /dev/null @@ -1,1049 +0,0 @@ ---- -sidebar_position: 1 ---- - -# `x/distribution` - -## Overview - -This _simple_ distribution mechanism describes a functional way to passively -distribute rewards between validators and delegators. Note that this mechanism does -not distribute funds in as precisely as active reward distribution mechanisms and -will therefore be upgraded in the future. - -The mechanism operates as follows. Collected rewards are pooled globally and -divided out passively to validators and delegators. Each validator has the -opportunity to charge commission to the delegators on the rewards collected on -behalf of the delegators. Fees are collected directly into a global reward pool -and validator proposer-reward pool. Due to the nature of passive accounting, -whenever changes to parameters which affect the rate of reward distribution -occurs, withdrawal of rewards must also occur. - -* Whenever withdrawing, one must withdraw the maximum amount they are entitled - to, leaving nothing in the pool. -* Whenever bonding, unbonding, or re-delegating tokens to an existing account, a - full withdrawal of the rewards must occur (as the rules for lazy accounting - change). -* Whenever a validator chooses to change the commission on rewards, all accumulated - commission rewards must be simultaneously withdrawn. - -The above scenarios are covered in `hooks.md`. - -The distribution mechanism outlined herein is used to lazily distribute the -following rewards between validators and associated delegators: - -* multi-token fees to be socially distributed -* inflated staked asset provisions -* validator commission on all rewards earned by their delegators stake - -Fees are pooled within a global pool. The mechanisms used allow for validators -and delegators to independently and lazily withdraw their rewards. - -## Shortcomings - -As a part of the lazy computations, each delegator holds an accumulation term -specific to each validator which is used to estimate what their approximate -fair portion of tokens held in the global fee pool is owed to them. - -```text -entitlement = delegator-accumulation / all-delegators-accumulation -``` - -Under the circumstance that there was constant and equal flow of incoming -reward tokens every block, this distribution mechanism would be equal to the -active distribution (distribute individually to all delegators each block). -However, this is unrealistic so deviations from the active distribution will -occur based on fluctuations of incoming reward tokens as well as timing of -reward withdrawal by other delegators. - -If you happen to know that incoming rewards are about to significantly increase, -you are incentivized to not withdraw until after this event, increasing the -worth of your existing _accum_. See [#2764](https://github.com/cosmos/cosmos-sdk/issues/2764) -for further details. - -## Effect on Staking - -Charging commission on Atom provisions while also allowing for Atom-provisions -to be auto-bonded (distributed directly to the validators bonded stake) is -problematic within BPoS. Fundamentally, these two mechanisms are mutually -exclusive. If both commission and auto-bonding mechanisms are simultaneously -applied to the staking-token then the distribution of staking-tokens between -any validator and its delegators will change with each block. This then -necessitates a calculation for each delegation records for each block - -which is considered computationally expensive. - -In conclusion, we can only have Atom commission and unbonded atoms -provisions or bonded atom provisions with no Atom commission, and we elect to -implement the former. Stakeholders wishing to rebond their provisions may elect -to set up a script to periodically withdraw and rebond rewards. - -## Contents - -* [Concepts](#concepts) -* [State](#state) - * [FeePool](#feepool) - * [Validator Distribution](#validator-distribution) - * [Delegation Distribution](#delegation-distribution) - * [Params](#params) -* [Begin Block](#begin-block) -* [Messages](#messages) -* [Hooks](#hooks) -* [Events](#events) -* [Parameters](#parameters) -* [Client](#client) - * [CLI](#cli) - * [gRPC](#grpc) - -## Concepts - -In Proof of Stake (PoS) blockchains, rewards gained from transaction fees are paid to validators. The fee distribution module fairly distributes the rewards to the validators' constituent delegators. - -Rewards are calculated per period. The period is updated each time a validator's delegation changes, for example, when the validator receives a new delegation. -The rewards for a single validator can then be calculated by taking the total rewards for the period before the delegation started, minus the current total rewards. -To learn more, see the [F1 Fee Distribution paper](https://github.com/cosmos/cosmos-sdk/tree/main/docs/spec/fee_distribution/f1_fee_distr.pdf). - -The commission to the validator is paid when the validator is removed or when the validator requests a withdrawal. -The commission is calculated and incremented at every `BeginBlock` operation to update accumulated fee amounts. - -The rewards to a delegator are distributed when the delegation is changed or removed, or a withdrawal is requested. -Before rewards are distributed, all slashes to the validator that occurred during the current delegation are applied. - -### Reference Counting in F1 Fee Distribution - -In F1 fee distribution, the rewards a delegator receives are calculated when their delegation is withdrawn. This calculation must read the terms of the summation of rewards divided by the share of tokens from the period which they ended when they delegated, and the final period that was created for the withdrawal. - -Additionally, as slashes change the amount of tokens a delegation will have (but we calculate this lazily, -only when a delegator un-delegates), we must calculate rewards in separate periods before / after any slashes -which occurred in between when a delegator delegated and when they withdrew their rewards. Thus slashes, like -delegations, reference the period which was ended by the slash event. - -All stored historical rewards records for periods which are no longer referenced by any delegations -or any slashes can thus be safely removed, as they will never be read (future delegations and future -slashes will always reference future periods). This is implemented by tracking a `ReferenceCount` -along with each historical reward storage entry. Each time a new object (delegation or slash) -is created which might need to reference the historical record, the reference count is incremented. -Each time one object which previously needed to reference the historical record is deleted, the reference -count is decremented. If the reference count hits zero, the historical record is deleted. - -## State - -### FeePool - -All globally tracked parameters for distribution are stored within -`FeePool`. Rewards are collected and added to the reward pool and -distributed to validators/delegators from here. - -Note that the reward pool holds decimal coins (`DecCoins`) to allow -for fractions of coins to be received from operations like inflation. -When coins are distributed from the pool they are truncated back to -`sdk.Coins` which are non-decimal. - -* FeePool: `0x00 -> ProtocolBuffer(FeePool)` - -```go -// coins with decimal -type DecCoins []DecCoin - -type DecCoin struct { - Amount math.LegacyDec - Denom string -} -``` - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/distribution/v1beta1/distribution.proto#L116-L123 -``` - -### Validator Distribution - -Validator distribution information for the relevant validator is updated each time: - -1. delegation amount to a validator is updated, -2. any delegator withdraws from a validator, or -3. the validator withdraws its commission. - -* ValidatorDistInfo: `0x02 | ValOperatorAddrLen (1 byte) | ValOperatorAddr -> ProtocolBuffer(validatorDistribution)` - -```go -type ValidatorDistInfo struct { - OperatorAddress sdk.AccAddress - SelfBondRewards sdkmath.DecCoins - ValidatorCommission types.ValidatorAccumulatedCommission -} -``` - -### Delegation Distribution - -Each delegation distribution only needs to record the height at which it last -withdrew fees. Because a delegation must withdraw fees each time it's -properties change (aka bonded tokens etc.) its properties will remain constant -and the delegator's _accumulation_ factor can be calculated passively knowing -only the height of the last withdrawal and its current properties. - -* DelegationDistInfo: `0x02 | DelegatorAddrLen (1 byte) | DelegatorAddr | ValOperatorAddrLen (1 byte) | ValOperatorAddr -> ProtocolBuffer(delegatorDist)` - -```go -type DelegationDistInfo struct { - WithdrawalHeight int64 // last time this delegation withdrew rewards -} -``` - -### Params - -The distribution module stores it's params in state with the prefix of `0x09`, -it can be updated with governance or the address with authority. - -* Params: `0x09 | ProtocolBuffer(Params)` - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/distribution/v1beta1/distribution.proto#L12-L42 -``` - -## Begin Block - -At each `BeginBlock`, all fees received in the previous block are transferred to -the distribution `ModuleAccount` account. When a delegator or validator -withdraws their rewards, they are taken out of the `ModuleAccount`. During begin -block, the different claims on the fees collected are updated as follows: - -* The reserve community tax is charged. -* The remainder is distributed proportionally by voting power to all bonded validators - -### The Distribution Scheme - -See [params](#params) for description of parameters. - -Let `fees` be the total fees collected in the previous block, including -inflationary rewards to the stake. All fees are collected in a specific module -account during the block. During `BeginBlock`, they are sent to the -`"distribution"` `ModuleAccount`. No other sending of tokens occurs. Instead, the -rewards each account is entitled to are stored, and withdrawals can be triggered -through the messages `FundCommunityPool`, `WithdrawValidatorCommission` and -`WithdrawDelegatorReward`. - -#### Reward to the Community Pool - -The community pool gets `community_tax * fees`, plus any remaining dust after -validators get their rewards that are always rounded down to the nearest -integer value. - -#### Reward To the Validators - -The proposer receives no extra rewards. All fees are distributed among all the -bonded validators, including the proposer, in proportion to their consensus power. - -```text -powFrac = validator power / total bonded validator power -voteMul = 1 - community_tax -``` - -All validators receive `fees * voteMul * powFrac`. - -#### Rewards to Delegators - -Each validator's rewards are distributed to its delegators. The validator also -has a self-delegation that is treated like a regular delegation in -distribution calculations. - -The validator sets a commission rate. The commission rate is flexible, but each -validator sets a maximum rate and a maximum daily increase. These maximums cannot be exceeded and protect delegators from sudden increases of validator commission rates to prevent validators from taking all of the rewards. - -The outstanding rewards that the operator is entitled to are stored in -`ValidatorAccumulatedCommission`, while the rewards the delegators are entitled -to are stored in `ValidatorCurrentRewards`. The [F1 fee distribution scheme](#concepts) is used to calculate the rewards per delegator as they -withdraw or update their delegation, and is thus not handled in `BeginBlock`. - -#### Example Distribution - -For this example distribution, the underlying consensus engine selects block proposers in -proportion to their power relative to the entire bonded power. - -All validators are equally performant at including pre-commits in their proposed -blocks. Then hold `(pre_commits included) / (total bonded validator power)` -constant so that the amortized block reward for the validator is `( validator power / total bonded power) * (1 - community tax rate)` of -the total rewards. Consequently, the reward for a single delegator is: - -```text -(delegator proportion of the validator power / validator power) * (validator power / total bonded power) - * (1 - community tax rate) * (1 - validator commission rate) -= (delegator proportion of the validator power / total bonded power) * (1 - -community tax rate) * (1 - validator commission rate) -``` - -## Messages - -### MsgSetWithdrawAddress - -By default, the withdraw address is the delegator address. To change its withdraw address, a delegator must send a `MsgSetWithdrawAddress` message. -Changing the withdraw address is possible only if the parameter `WithdrawAddrEnabled` is set to `true`. - -The withdraw address cannot be any of the module accounts. These accounts are blocked from being withdraw addresses by being added to the distribution keeper's `blockedAddrs` array at initialization. - -Response: - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/distribution/v1beta1/tx.proto#L49-L60 -``` - -```go -func (k Keeper) SetWithdrawAddr(ctx context.Context, delegatorAddr sdk.AccAddress, withdrawAddr sdk.AccAddress) error - if k.blockedAddrs[withdrawAddr.String()] { - fail with "`{withdrawAddr}` is not allowed to receive external funds" - } - - if !k.GetWithdrawAddrEnabled(ctx) { - fail with `ErrSetWithdrawAddrDisabled` - } - - k.SetDelegatorWithdrawAddr(ctx, delegatorAddr, withdrawAddr) -``` - -### MsgWithdrawDelegatorReward - -A delegator can withdraw its rewards. -Internally in the distribution module, this transaction simultaneously removes the previous delegation with associated rewards, the same as if the delegator simply started a new delegation of the same value. -The rewards are sent immediately from the distribution `ModuleAccount` to the withdraw address. -Any remainder (truncated decimals) are sent to the community pool. -The starting height of the delegation is set to the current validator period, and the reference count for the previous period is decremented. -The amount withdrawn is deducted from the `ValidatorOutstandingRewards` variable for the validator. - -In the F1 distribution, the total rewards are calculated per validator period, and a delegator receives a piece of those rewards in proportion to their stake in the validator. -In basic F1, the total rewards that all the delegators are entitled to between to periods is calculated the following way. -Let `R(X)` be the total accumulated rewards up to period `X` divided by the tokens staked at that time. The delegator allocation is `R(X) * delegator_stake`. -Then the rewards for all the delegators for staking between periods `A` and `B` are `(R(B) - R(A)) * total stake`. -However, these calculated rewards don't account for slashing. - -Taking the slashes into account requires iteration. -Let `F(X)` be the fraction a validator is to be slashed for a slashing event that happened at period `X`. -If the validator was slashed at periods `P1, ..., PN`, where `A < P1`, `PN < B`, the distribution module calculates the individual delegator's rewards, `T(A, B)`, as follows: - -```go -stake := initial stake -rewards := 0 -previous := A -for P in P1, ..., PN`: - rewards = (R(P) - previous) * stake - stake = stake * F(P) - previous = P -rewards = rewards + (R(B) - R(PN)) * stake -``` - -The historical rewards are calculated retroactively by playing back all the slashes and then attenuating the delegator's stake at each step. -The final calculated stake is equivalent to the actual staked coins in the delegation with a margin of error due to rounding errors. - -Response: - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/distribution/v1beta1/tx.proto#L66-L77 -``` - -### WithdrawValidatorCommission - -The validator can send the WithdrawValidatorCommission message to withdraw their accumulated commission. -The commission is calculated in every block during `BeginBlock`, so no iteration is required to withdraw. -The amount withdrawn is deducted from the `ValidatorOutstandingRewards` variable for the validator. -Only integer amounts can be sent. If the accumulated awards have decimals, the amount is truncated before the withdrawal is sent, and the remainder is left to be withdrawn later. - -### FundCommunityPool - -This message sends coins directly from the sender to the community pool. - -The transaction fails if the amount cannot be transferred from the sender to the distribution module account. - -```go -func (k Keeper) FundCommunityPool(ctx context.Context, amount sdk.Coins, sender sdk.AccAddress) error { - if err := k.bankKeeper.SendCoinsFromAccountToModule(ctx, sender, types.ModuleName, amount); err != nil { - return err - } - - feePool, err := k.FeePool.Get(ctx) - if err != nil { - return err - } - - feePool.CommunityPool = feePool.CommunityPool.Add(sdk.NewDecCoinsFromCoins(amount...)...) - - if err := k.FeePool.Set(ctx, feePool); err != nil { - return err - } - - return nil -} -``` - -### Common distribution operations - -These operations take place during many different messages. - -#### Initialize delegation - -Each time a delegation is changed, the rewards are withdrawn and the delegation is reinitialized. -Initializing a delegation increments the validator period and keeps track of the starting period of the delegation. - -```go -// initialize starting info for a new delegation -func (k Keeper) initializeDelegation(ctx context.Context, val sdk.ValAddress, del sdk.AccAddress) { - // period has already been incremented - we want to store the period ended by this delegation action - previousPeriod := k.GetValidatorCurrentRewards(ctx, val).Period - 1 - - // increment reference count for the period we're going to track - k.incrementReferenceCount(ctx, val, previousPeriod) - - validator := k.stakingKeeper.Validator(ctx, val) - delegation := k.stakingKeeper.Delegation(ctx, del, val) - - // calculate delegation stake in tokens - // we don't store directly, so multiply delegation shares * (tokens per share) - // note: necessary to truncate so we don't allow withdrawing more rewards than owed - stake := validator.TokensFromSharesTruncated(delegation.GetShares()) - k.SetDelegatorStartingInfo(ctx, val, del, types.NewDelegatorStartingInfo(previousPeriod, stake, uint64(ctx.BlockHeight()))) -} -``` - -### MsgUpdateParams - -Distribution module params can be updated through `MsgUpdateParams`, which can be done using governance proposal and the signer will always be gov module account address. - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/distribution/v1beta1/tx.proto#L133-L147 -``` - -The message handling can fail if: - -* signer is not the gov module account address. - -## Hooks - -Available hooks that can be called by and from this module. - -### Create or modify delegation distribution - -* triggered-by: `staking.MsgDelegate`, `staking.MsgBeginRedelegate`, `staking.MsgUndelegate` - -#### Before - -* The delegation rewards are withdrawn to the withdraw address of the delegator. - The rewards include the current period and exclude the starting period. -* The validator period is incremented. - The validator period is incremented because the validator's power and share distribution might have changed. -* The reference count for the delegator's starting period is decremented. - -#### After - -The starting height of the delegation is set to the previous period. -Because of the `Before`-hook, this period is the last period for which the delegator was rewarded. - -### Validator created - -* triggered-by: `staking.MsgCreateValidator` - -When a validator is created, the following validator variables are initialized: - -* Historical rewards -* Current accumulated rewards -* Accumulated commission -* Total outstanding rewards -* Period - -By default, all values are set to a `0`, except period, which is set to `1`. - -### Validator removed - -* triggered-by: `staking.RemoveValidator` - -Outstanding commission is sent to the validator's self-delegation withdrawal address. -Remaining delegator rewards get sent to the community fee pool. - -Note: The validator gets removed only when it has no remaining delegations. -At that time, all outstanding delegator rewards will have been withdrawn. -Any remaining rewards are dust amounts. - -### Validator is slashed - -* triggered-by: `staking.Slash` -* The current validator period reference count is incremented. - The reference count is incremented because the slash event has created a reference to it. -* The validator period is incremented. -* The slash event is stored for later use. - The slash event will be referenced when calculating delegator rewards. - -## Events - -The distribution module emits the following events: - -### BeginBlocker - -| Type | Attribute Key | Attribute Value | -|-----------------|---------------|--------------------| -| proposer_reward | validator | {validatorAddress} | -| proposer_reward | reward | {proposerReward} | -| commission | amount | {commissionAmount} | -| commission | validator | {validatorAddress} | -| rewards | amount | {rewardAmount} | -| rewards | validator | {validatorAddress} | - -### Handlers - -#### MsgSetWithdrawAddress - -| Type | Attribute Key | Attribute Value | -|----------------------|------------------|----------------------| -| set_withdraw_address | withdraw_address | {withdrawAddress} | -| message | module | distribution | -| message | action | set_withdraw_address | -| message | sender | {senderAddress} | - -#### MsgWithdrawDelegatorReward - -| Type | Attribute Key | Attribute Value | -|---------|---------------|---------------------------| -| withdraw_rewards | amount | {rewardAmount} | -| withdraw_rewards | validator | {validatorAddress} | -| message | module | distribution | -| message | action | withdraw_delegator_reward | -| message | sender | {senderAddress} | - -#### MsgWithdrawValidatorCommission - -| Type | Attribute Key | Attribute Value | -|------------|---------------|-------------------------------| -| withdraw_commission | amount | {commissionAmount} | -| message | module | distribution | -| message | action | withdraw_validator_commission | -| message | sender | {senderAddress} | - -## Parameters - -The distribution module contains the following parameters: - -| Key | Type | Example | -| ------------------- | ------------ | -------------------------- | -| communitytax | string (dec) | "0.020000000000000000" [0] | -| withdrawaddrenabled | bool | true | - -* [0] `communitytax` must be positive and cannot exceed 1.00. -* `baseproposerreward` and `bonusproposerreward` were parameters that are deprecated in v0.47 and are not used. - -:::note -The reserve pool is the pool of collected funds for use by governance taken via the `CommunityTax`. -Currently with the Cosmos SDK, tokens collected by the CommunityTax are accounted for but unspendable. -::: - -## Client - -## CLI - -A user can query and interact with the `distribution` module using the CLI. - -#### Query - -The `query` commands allow users to query `distribution` state. - -```shell -simd query distribution --help -``` - -##### commission - -The `commission` command allows users to query validator commission rewards by address. - -```shell -simd query distribution commission [address] [flags] -``` - -Example: - -```shell -simd query distribution commission cosmosvaloper1... -``` - -Example Output: - -```yml -commission: -- amount: "1000000.000000000000000000" - denom: stake -``` - -##### community-pool - -The `community-pool` command allows users to query all coin balances within the community pool. - -```shell -simd query distribution community-pool [flags] -``` - -Example: - -```shell -simd query distribution community-pool -``` - -Example Output: - -```yml -pool: -- amount: "1000000.000000000000000000" - denom: stake -``` - -##### params - -The `params` command allows users to query the parameters of the `distribution` module. - -```shell -simd query distribution params [flags] -``` - -Example: - -```shell -simd query distribution params -``` - -Example Output: - -```yml -base_proposer_reward: "0.000000000000000000" -bonus_proposer_reward: "0.000000000000000000" -community_tax: "0.020000000000000000" -withdraw_addr_enabled: true -``` - -##### rewards - -The `rewards` command allows users to query delegator rewards. Users can optionally include the validator address to query rewards earned from a specific validator. - -```shell -simd query distribution rewards [delegator-addr] [validator-addr] [flags] -``` - -Example: - -```shell -simd query distribution rewards cosmos1... -``` - -Example Output: - -```yml -rewards: -- reward: - - amount: "1000000.000000000000000000" - denom: stake - validator_address: cosmosvaloper1.. -total: -- amount: "1000000.000000000000000000" - denom: stake -``` - -##### slashes - -The `slashes` command allows users to query all slashes for a given block range. - -```shell -simd query distribution slashes [validator] [start-height] [end-height] [flags] -``` - -Example: - -```shell -simd query distribution slashes cosmosvaloper1... 1 1000 -``` - -Example Output: - -```yml -pagination: - next_key: null - total: "0" -slashes: -- validator_period: 20, - fraction: "0.009999999999999999" -``` - -##### validator-outstanding-rewards - -The `validator-outstanding-rewards` command allows users to query all outstanding (un-withdrawn) rewards for a validator and all their delegations. - -```shell -simd query distribution validator-outstanding-rewards [validator] [flags] -``` - -Example: - -```shell -simd query distribution validator-outstanding-rewards cosmosvaloper1... -``` - -Example Output: - -```yml -rewards: -- amount: "1000000.000000000000000000" - denom: stake -``` - -##### validator-distribution-info - -The `validator-distribution-info` command allows users to query validator commission and self-delegation rewards for validator. - -````shell -simd query distribution validator-distribution-info cosmosvaloper1... -``` - -Example Output: - -```yml -commission: -- amount: "100000.000000000000000000" - denom: stake -operator_address: cosmosvaloper1... -self_bond_rewards: -- amount: "100000.000000000000000000" - denom: stake -``` - -#### Transactions - -The `tx` commands allow users to interact with the `distribution` module. - -```shell -simd tx distribution --help -``` - -##### fund-community-pool - -The `fund-community-pool` command allows users to send funds to the community pool. - -```shell -simd tx distribution fund-community-pool [amount] [flags] -``` - -Example: - -```shell -simd tx distribution fund-community-pool 100stake --from cosmos1... -``` - -##### set-withdraw-addr - -The `set-withdraw-addr` command allows users to set the withdraw address for rewards associated with a delegator address. - -```shell -simd tx distribution set-withdraw-addr [withdraw-addr] [flags] -``` - -Example: - -```shell -simd tx distribution set-withdraw-addr cosmos1... --from cosmos1... -``` - -##### withdraw-all-rewards - -The `withdraw-all-rewards` command allows users to withdraw all rewards for a delegator. - -```shell -simd tx distribution withdraw-all-rewards [flags] -``` - -Example: - -```shell -simd tx distribution withdraw-all-rewards --from cosmos1... -``` - -##### withdraw-rewards - -The `withdraw-rewards` command allows users to withdraw all rewards from a given delegation address, -and optionally withdraw validator commission if the delegation address given is a validator operator and the user proves the `--commission` flag. - -```shell -simd tx distribution withdraw-rewards [validator-addr] [flags] -``` - -Example: - -```shell -simd tx distribution withdraw-rewards cosmosvaloper1... --from cosmos1... --commission -``` - -### gRPC - -A user can query the `distribution` module using gRPC endpoints. - -#### Params - -The `Params` endpoint allows users to query parameters of the `distribution` module. - -Example: - -```shell -grpcurl -plaintext \ - localhost:9090 \ - cosmos.distribution.v1beta1.Query/Params -``` - -Example Output: - -```json -{ - "params": { - "communityTax": "20000000000000000", - "baseProposerReward": "00000000000000000", - "bonusProposerReward": "00000000000000000", - "withdrawAddrEnabled": true - } -} -``` - -#### ValidatorDistributionInfo - -The `ValidatorDistributionInfo` queries validator commission and self-delegation rewards for validator. - -Example: - -```shell -grpcurl -plaintext \ - -d '{"validator_address":"cosmosvalop1..."}' \ - localhost:9090 \ - cosmos.distribution.v1beta1.Query/ValidatorDistributionInfo -``` - -Example Output: - -```json -{ - "commission": { - "commission": [ - { - "denom": "stake", - "amount": "1000000000000000" - } - ] - }, - "self_bond_rewards": [ - { - "denom": "stake", - "amount": "1000000000000000" - } - ], - "validator_address": "cosmosvalop1..." -} -``` - -#### ValidatorOutstandingRewards - -The `ValidatorOutstandingRewards` endpoint allows users to query rewards of a validator address. - -Example: - -```shell -grpcurl -plaintext \ - -d '{"validator_address":"cosmosvalop1.."}' \ - localhost:9090 \ - cosmos.distribution.v1beta1.Query/ValidatorOutstandingRewards -``` - -Example Output: - -```json -{ - "rewards": { - "rewards": [ - { - "denom": "stake", - "amount": "1000000000000000" - } - ] - } -} -``` - -#### ValidatorCommission - -The `ValidatorCommission` endpoint allows users to query accumulated commission for a validator. - -Example: - -```shell -grpcurl -plaintext \ - -d '{"validator_address":"cosmosvalop1.."}' \ - localhost:9090 \ - cosmos.distribution.v1beta1.Query/ValidatorCommission -``` - -Example Output: - -```json -{ - "commission": { - "commission": [ - { - "denom": "stake", - "amount": "1000000000000000" - } - ] - } -} -``` - -#### ValidatorSlashes - -The `ValidatorSlashes` endpoint allows users to query slash events of a validator. - -Example: - -```shell -grpcurl -plaintext \ - -d '{"validator_address":"cosmosvalop1.."}' \ - localhost:9090 \ - cosmos.distribution.v1beta1.Query/ValidatorSlashes -``` - -Example Output: - -```json -{ - "slashes": [ - { - "validator_period": "20", - "fraction": "0.009999999999999999" - } - ], - "pagination": { - "total": "1" - } -} -``` - -#### DelegationRewards - -The `DelegationRewards` endpoint allows users to query the total rewards accrued by a delegation. - -Example: - -```shell -grpcurl -plaintext \ - -d '{"delegator_address":"cosmos1...","validator_address":"cosmosvalop1..."}' \ - localhost:9090 \ - cosmos.distribution.v1beta1.Query/DelegationRewards -``` - -Example Output: - -```json -{ - "rewards": [ - { - "denom": "stake", - "amount": "1000000000000000" - } - ] -} -``` - -#### DelegationTotalRewards - -The `DelegationTotalRewards` endpoint allows users to query the total rewards accrued by each validator. - -Example: - -```shell -grpcurl -plaintext \ - -d '{"delegator_address":"cosmos1..."}' \ - localhost:9090 \ - cosmos.distribution.v1beta1.Query/DelegationTotalRewards -``` - -Example Output: - -```json -{ - "rewards": [ - { - "validatorAddress": "cosmosvaloper1...", - "reward": [ - { - "denom": "stake", - "amount": "1000000000000000" - } - ] - } - ], - "total": [ - { - "denom": "stake", - "amount": "1000000000000000" - } - ] -} -``` - -#### DelegatorValidators - -The `DelegatorValidators` endpoint allows users to query all validators for given delegator. - -Example: - -```shell -grpcurl -plaintext \ - -d '{"delegator_address":"cosmos1..."}' \ - localhost:9090 \ - cosmos.distribution.v1beta1.Query/DelegatorValidators -``` - -Example Output: - -```json -{ - "validators": ["cosmosvaloper1..."] -} -``` - -#### DelegatorWithdrawAddress - -The `DelegatorWithdrawAddress` endpoint allows users to query the withdraw address of a delegator. - -Example: - -```shell -grpcurl -plaintext \ - -d '{"delegator_address":"cosmos1..."}' \ - localhost:9090 \ - cosmos.distribution.v1beta1.Query/DelegatorWithdrawAddress -``` - -Example Output: - -```json -{ - "withdrawAddress": "cosmos1..." -} -``` - -#### CommunityPool - -The `CommunityPool` endpoint allows users to query the community pool coins. - -Example: - -```shell -grpcurl -plaintext \ - localhost:9090 \ - cosmos.distribution.v1beta1.Query/CommunityPool -``` - -Example Output: - -```json -{ - "pool": [ - { - "denom": "stake", - "amount": "1000000000000000000" - } - ] -} -``` diff --git a/.gitbook/developers/modules/core/evidence/README.md b/.gitbook/developers/modules/core/evidence/README.md deleted file mode 100644 index 82cd03ba..00000000 --- a/.gitbook/developers/modules/core/evidence/README.md +++ /dev/null @@ -1,440 +0,0 @@ ---- -sidebar_position: 1 ---- - -# `x/evidence` - -* [Concepts](#concepts) -* [State](#state) -* [Messages](#messages) -* [Events](#events) -* [Parameters](#parameters) -* [BeginBlock](#beginblock) -* [Client](#client) - * [CLI](#cli) - * [REST](#rest) - * [gRPC](#grpc) - -## Abstract - -`x/evidence` is an implementation of a Cosmos SDK module, per [ADR 009](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-009-evidence-module.md), -that allows for the submission and handling of arbitrary evidence of misbehavior such -as equivocation and counterfactual signing. - -The evidence module differs from standard evidence handling which typically expects the -underlying consensus engine, e.g. CometBFT, to automatically submit evidence when -it is discovered by allowing clients and foreign chains to submit more complex evidence -directly. - -All concrete evidence types must implement the `Evidence` interface contract. Submitted -`Evidence` is first routed through the evidence module's `Router` in which it attempts -to find a corresponding registered `Handler` for that specific `Evidence` type. -Each `Evidence` type must have a `Handler` registered with the evidence module's -keeper in order for it to be successfully routed and executed. - -Each corresponding handler must also fulfill the `Handler` interface contract. The -`Handler` for a given `Evidence` type can perform any arbitrary state transitions -such as slashing, jailing, and tombstoning. - -## Concepts - -### Evidence - -Any concrete type of evidence submitted to the `x/evidence` module must fulfill the -`Evidence` contract outlined below. Not all concrete types of evidence will fulfill -this contract in the same way and some data may be entirely irrelevant to certain -types of evidence. An additional `ValidatorEvidence`, which extends `Evidence`, -has also been created to define a contract for evidence against malicious validators. - -```go -// Evidence defines the contract which concrete evidence types of misbehavior -// must implement. -type Evidence interface { - proto.Message - - Route() string - String() string - Hash() []byte - ValidateBasic() error - - // Height at which the infraction occurred - GetHeight() int64 -} - -// ValidatorEvidence extends Evidence interface to define contract -// for evidence against malicious validators -type ValidatorEvidence interface { - Evidence - - // The consensus address of the malicious validator at time of infraction - GetConsensusAddress() sdk.ConsAddress - - // The total power of the malicious validator at time of infraction - GetValidatorPower() int64 - - // The total validator set power at time of infraction - GetTotalPower() int64 -} -``` - -### Registration & Handling - -The `x/evidence` module must first know about all types of evidence it is expected -to handle. This is accomplished by registering the `Route` method in the `Evidence` -contract with what is known as a `Router` (defined below). The `Router` accepts -`Evidence` and attempts to find the corresponding `Handler` for the `Evidence` -via the `Route` method. - -```go -type Router interface { - AddRoute(r string, h Handler) Router - HasRoute(r string) bool - GetRoute(path string) Handler - Seal() - Sealed() bool -} -``` - -The `Handler` (defined below) is responsible for executing the entirety of the -business logic for handling `Evidence`. This typically includes validating the -evidence, both stateless checks via `ValidateBasic` and stateful checks via any -keepers provided to the `Handler`. In addition, the `Handler` may also perform -capabilities such as slashing and jailing a validator. All `Evidence` handled -by the `Handler` should be persisted. - -```go -// Handler defines an agnostic Evidence handler. The handler is responsible -// for executing all corresponding business logic necessary for verifying the -// evidence as valid. In addition, the Handler may execute any necessary -// slashing and potential jailing. -type Handler func(context.Context, Evidence) error -``` - - -## State - -Currently the `x/evidence` module only stores valid submitted `Evidence` in state. -The evidence state is also stored and exported in the `x/evidence` module's `GenesisState`. - -```protobuf -// GenesisState defines the evidence module's genesis state. -message GenesisState { - // evidence defines all the evidence at genesis. - repeated google.protobuf.Any evidence = 1; -} - -``` - -All `Evidence` is retrieved and stored via a prefix `KVStore` using prefix `0x00` (`KeyPrefixEvidence`). - - -## Messages - -### MsgSubmitEvidence - -Evidence is submitted through a `MsgSubmitEvidence` message: - -```protobuf -// MsgSubmitEvidence represents a message that supports submitting arbitrary -// Evidence of misbehavior such as equivocation or counterfactual signing. -message MsgSubmitEvidence { - string submitter = 1; - google.protobuf.Any evidence = 2; -} -``` - -Note, the `Evidence` of a `MsgSubmitEvidence` message must have a corresponding -`Handler` registered with the `x/evidence` module's `Router` in order to be processed -and routed correctly. - -Given the `Evidence` is registered with a corresponding `Handler`, it is processed -as follows: - -```go -func SubmitEvidence(ctx Context, evidence Evidence) error { - if _, err := GetEvidence(ctx, evidence.Hash()); err == nil { - return errorsmod.Wrap(types.ErrEvidenceExists, strings.ToUpper(hex.EncodeToString(evidence.Hash()))) - } - if !router.HasRoute(evidence.Route()) { - return errorsmod.Wrap(types.ErrNoEvidenceHandlerExists, evidence.Route()) - } - - handler := router.GetRoute(evidence.Route()) - if err := handler(ctx, evidence); err != nil { - return errorsmod.Wrap(types.ErrInvalidEvidence, err.Error()) - } - - ctx.EventManager().EmitEvent( - sdk.NewEvent( - types.EventTypeSubmitEvidence, - sdk.NewAttribute(types.AttributeKeyEvidenceHash, strings.ToUpper(hex.EncodeToString(evidence.Hash()))), - ), - ) - - SetEvidence(ctx, evidence) - return nil -} -``` - -First, there must not already exist valid submitted `Evidence` of the exact same -type. Secondly, the `Evidence` is routed to the `Handler` and executed. Finally, -if there is no error in handling the `Evidence`, an event is emitted and it is persisted to state. - - -## Events - -The `x/evidence` module emits the following events: - -### Handlers - -#### MsgSubmitEvidence - -| Type | Attribute Key | Attribute Value | -| --------------- | ------------- | --------------- | -| submit_evidence | evidence_hash | {evidenceHash} | -| message | module | evidence | -| message | sender | {senderAddress} | -| message | action | submit_evidence | - - -## Parameters - -The evidence module does not contain any parameters. - - -## BeginBlock - -### Evidence Handling - -CometBFT blocks can include -[Evidence](https://github.com/cometbft/cometbft/blob/main/spec/abci/abci%2B%2B_basic_concepts.md#evidence) that indicates if a validator committed malicious behavior. The relevant information is forwarded to the application as ABCI Evidence in `abci.RequestBeginBlock` so that the validator can be punished accordingly. - -#### Equivocation - -The Cosmos SDK handles two types of evidence inside the ABCI `BeginBlock`: - -* `DuplicateVoteEvidence`, -* `LightClientAttackEvidence`. - -The evidence module handles these two evidence types the same way. First, the Cosmos SDK converts the CometBFT concrete evidence type to an SDK `Evidence` interface using `Equivocation` as the concrete type. - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/evidence/v1beta1/evidence.proto#L12-L32 -``` - -For some `Equivocation` submitted in `block` to be valid, it must satisfy: - -`Evidence.Timestamp >= block.Timestamp - MaxEvidenceAge` - -Where: - -* `Evidence.Timestamp` is the timestamp in the block at height `Evidence.Height` -* `block.Timestamp` is the current block timestamp. - -If valid `Equivocation` evidence is included in a block, the validator's stake is -reduced (slashed) by `SlashFractionDoubleSign` as defined by the `x/slashing` module -of what their stake was when the infraction occurred, rather than when the evidence was discovered. -We want to "follow the stake", i.e., the stake that contributed to the infraction -should be slashed, even if it has since been redelegated or started unbonding. - -In addition, the validator is permanently jailed and tombstoned to make it impossible for that -validator to ever re-enter the validator set. - -The `Equivocation` evidence is handled as follows: - -```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/x/evidence/keeper/infraction.go#L26-L140 -``` - -**Note:** The slashing, jailing, and tombstoning calls are delegated through the `x/slashing` module -that emits informative events and finally delegates calls to the `x/staking` module. See documentation -on slashing and jailing in [State Transitions](../staking/README.md#state-transitions). - -## Client - -### CLI - -A user can query and interact with the `evidence` module using the CLI. - -#### Query - -The `query` commands allows users to query `evidence` state. - -```bash -simd query evidence --help -``` - -#### evidence - -The `evidence` command allows users to list all evidence or evidence by hash. - -Usage: - -```bash -simd query evidence evidence [flags] -``` - -To query evidence by hash - -Example: - -```bash -simd query evidence evidence "DF0C23E8634E480F84B9D5674A7CDC9816466DEC28A3358F73260F68D28D7660" -``` - -Example Output: - -```bash -evidence: - consensus_address: cosmosvalcons1ntk8eualewuprz0gamh8hnvcem2nrcdsgz563h - height: 11 - power: 100 - time: "2021-10-20T16:08:38.194017624Z" -``` - -To get all evidence - -Example: - -```bash -simd query evidence list -``` - -Example Output: - -```bash -evidence: - consensus_address: cosmosvalcons1ntk8eualewuprz0gamh8hnvcem2nrcdsgz563h - height: 11 - power: 100 - time: "2021-10-20T16:08:38.194017624Z" -pagination: - next_key: null - total: "1" -``` - -### REST - -A user can query the `evidence` module using REST endpoints. - -#### Evidence - -Get evidence by hash - -```bash -/cosmos/evidence/v1beta1/evidence/{hash} -``` - -Example: - -```bash -curl -X GET "http://localhost:1317/cosmos/evidence/v1beta1/evidence/DF0C23E8634E480F84B9D5674A7CDC9816466DEC28A3358F73260F68D28D7660" -``` - -Example Output: - -```bash -{ - "evidence": { - "consensus_address": "cosmosvalcons1ntk8eualewuprz0gamh8hnvcem2nrcdsgz563h", - "height": "11", - "power": "100", - "time": "2021-10-20T16:08:38.194017624Z" - } -} -``` - -#### All evidence - -Get all evidence - -```bash -/cosmos/evidence/v1beta1/evidence -``` - -Example: - -```bash -curl -X GET "http://localhost:1317/cosmos/evidence/v1beta1/evidence" -``` - -Example Output: - -```bash -{ - "evidence": [ - { - "consensus_address": "cosmosvalcons1ntk8eualewuprz0gamh8hnvcem2nrcdsgz563h", - "height": "11", - "power": "100", - "time": "2021-10-20T16:08:38.194017624Z" - } - ], - "pagination": { - "total": "1" - } -} -``` - -### gRPC - -A user can query the `evidence` module using gRPC endpoints. - -#### Evidence - -Get evidence by hash - -```bash -cosmos.evidence.v1beta1.Query/Evidence -``` - -Example: - -```bash -grpcurl -plaintext -d '{"evidence_hash":"DF0C23E8634E480F84B9D5674A7CDC9816466DEC28A3358F73260F68D28D7660"}' localhost:9090 cosmos.evidence.v1beta1.Query/Evidence -``` - -Example Output: - -```bash -{ - "evidence": { - "consensus_address": "cosmosvalcons1ntk8eualewuprz0gamh8hnvcem2nrcdsgz563h", - "height": "11", - "power": "100", - "time": "2021-10-20T16:08:38.194017624Z" - } -} -``` - -#### All evidence - -Get all evidence - -```bash -cosmos.evidence.v1beta1.Query/AllEvidence -``` - -Example: - -```bash -grpcurl -plaintext localhost:9090 cosmos.evidence.v1beta1.Query/AllEvidence -``` - -Example Output: - -```bash -{ - "evidence": [ - { - "consensus_address": "cosmosvalcons1ntk8eualewuprz0gamh8hnvcem2nrcdsgz563h", - "height": "11", - "power": "100", - "time": "2021-10-20T16:08:38.194017624Z" - } - ], - "pagination": { - "total": "1" - } -} -``` diff --git a/.gitbook/developers/modules/core/feegrant/README.md b/.gitbook/developers/modules/core/feegrant/README.md deleted file mode 100644 index 07524449..00000000 --- a/.gitbook/developers/modules/core/feegrant/README.md +++ /dev/null @@ -1,396 +0,0 @@ ---- -sidebar_position: 1 ---- - -# `x/feegrant` - -## Abstract - -This document specifies the fee grant module. For the full ADR, please see [Fee Grant ADR-029](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-029-fee-grant-module.md). - -This module allows accounts to grant fee allowances and to use fees from their accounts. Grantees can execute any transaction without the need to maintain sufficient fees. - -## Contents - -* [Concepts](#concepts) -* [State](#state) - * [FeeAllowance](#feeallowance) - * [FeeAllowanceQueue](#feeallowancequeue) -* [Messages](#messages) - * [Msg/GrantAllowance](#msggrantallowance) - * [Msg/RevokeAllowance](#msgrevokeallowance) -* [Events](#events) -* [Msg Server](#msg-server) - * [MsgGrantAllowance](#msggrantallowance-1) - * [MsgRevokeAllowance](#msgrevokeallowance-1) - * [Exec fee allowance](#exec-fee-allowance) -* [Client](#client) - * [CLI](#cli) - * [gRPC](#grpc) - -## Concepts - -### Grant - -`Grant` is stored in the KVStore to record a grant with full context. Every grant will contain `granter`, `grantee` and what kind of `allowance` is granted. `granter` is an account address who is giving permission to `grantee` (the beneficiary account address) to pay for some or all of `grantee`'s transaction fees. `allowance` defines what kind of fee allowance (`BasicAllowance` or `PeriodicAllowance`, see below) is granted to `grantee`. `allowance` accepts an interface which implements `FeeAllowanceI`, encoded as `Any` type. There can be only one existing fee grant allowed for a `grantee` and `granter`, self grants are not allowed. - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/feegrant/v1beta1/feegrant.proto#L83-L93 -``` - -`FeeAllowanceI` looks like: - -```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/x/feegrant/fees.go#L9-L32 -``` - -### Fee Allowance types - -There are two types of fee allowances present at the moment: - -* `BasicAllowance` -* `PeriodicAllowance` -* `AllowedMsgAllowance` - -### BasicAllowance - -`BasicAllowance` is permission for `grantee` to use fee from a `granter`'s account. If any of the `spend_limit` or `expiration` reaches its limit, the grant will be removed from the state. - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/feegrant/v1beta1/feegrant.proto#L15-L28 -``` - -* `spend_limit` is the limit of coins that are allowed to be used from the `granter` account. If it is empty, it assumes there's no spend limit, `grantee` can use any number of available coins from `granter` account address before the expiration. - -* `expiration` specifies an optional time when this allowance expires. If the value is left empty, there is no expiry for the grant. - -* When a grant is created with empty values for `spend_limit` and `expiration`, it is still a valid grant. It won't restrict the `grantee` to use any number of coins from `granter` and it won't have any expiration. The only way to restrict the `grantee` is by revoking the grant. - -### PeriodicAllowance - -`PeriodicAllowance` is a repeating fee allowance for the mentioned period, we can mention when the grant can expire as well as when a period can reset. We can also define the maximum number of coins that can be used in a mentioned period of time. - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/feegrant/v1beta1/feegrant.proto#L34-L68 -``` - -* `basic` is the instance of `BasicAllowance` which is optional for periodic fee allowance. If empty, the grant will have no `expiration` and no `spend_limit`. - -* `period` is the specific period of time, after each period passes, `period_can_spend` will be reset. - -* `period_spend_limit` specifies the maximum number of coins that can be spent in the period. - -* `period_can_spend` is the number of coins left to be spent before the period_reset time. - -* `period_reset` keeps track of when a next period reset should happen. - -### AllowedMsgAllowance - -`AllowedMsgAllowance` is a fee allowance, it can be any of `BasicFeeAllowance`, `PeriodicAllowance` but restricted only to the allowed messages mentioned by the granter. - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/feegrant/v1beta1/feegrant.proto#L70-L81 -``` - -* `allowance` is either `BasicAllowance` or `PeriodicAllowance`. - -* `allowed_messages` is array of messages allowed to execute the given allowance. - -### FeeGranter flag - -`feegrant` module introduces a `FeeGranter` flag for CLI for the sake of executing transactions with fee granter. When this flag is set, `clientCtx` will append the granter account address for transactions generated through CLI. - -```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/client/cmd.go#L249-L260 -``` - -```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/client/tx/tx.go#L109-L109 -``` - -```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/x/auth/tx/builder.go#L275-L284 -``` - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/tx/v1beta1/tx.proto#L203-L224 -``` - -Example cmd: - -```go -./simd tx gov submit-proposal --title="Test Proposal" --description="My awesome proposal" --type="Text" --from validator-key --fee-granter=cosmos1xh44hxt7spr67hqaa7nyx5gnutrz5fraw6grxn --chain-id=testnet --fees="10stake" -``` - -### Granted Fee Deductions - -Fees are deducted from grants in the `x/auth` ante handler. To learn more about how ante handlers work, read the [Auth Module AnteHandlers Guide](../auth/README.md#antehandlers). - -### Gas - -In order to prevent DoS attacks, using a filtered `x/feegrant` incurs gas. The SDK must assure that the `grantee`'s transactions all conform to the filter set by the `granter`. The SDK does this by iterating over the allowed messages in the filter and charging 10 gas per filtered message. The SDK will then iterate over the messages being sent by the `grantee` to ensure the messages adhere to the filter, also charging 10 gas per message. The SDK will stop iterating and fail the transaction if it finds a message that does not conform to the filter. - -**WARNING**: The gas is charged against the granted allowance. Ensure your messages conform to the filter, if any, before sending transactions using your allowance. - -### Pruning - -A queue in the state maintained with the prefix of expiration of the grants and checks them on EndBlock with the current block time for every block to prune. - -## State - -### FeeAllowance - -Fee Allowances are identified by combining `Grantee` (the account address of fee allowance grantee) with the `Granter` (the account address of fee allowance granter). - -Fee allowance grants are stored in the state as follows: - -* Grant: `0x00 | grantee_addr_len (1 byte) | grantee_addr_bytes | granter_addr_len (1 byte) | granter_addr_bytes -> ProtocolBuffer(Grant)` - -```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/x/feegrant/feegrant.pb.go#L222-L230 -``` - -### FeeAllowanceQueue - -Fee Allowances queue items are identified by combining the `FeeAllowancePrefixQueue` (i.e., 0x01), `expiration`, `grantee` (the account address of fee allowance grantee), `granter` (the account address of fee allowance granter). Endblocker checks `FeeAllowanceQueue` state for the expired grants and prunes them from `FeeAllowance` if there are any found. - -Fee allowance queue keys are stored in the state as follows: - -* Grant: `0x01 | expiration_bytes | grantee_addr_len (1 byte) | grantee_addr_bytes | granter_addr_len (1 byte) | granter_addr_bytes -> EmptyBytes` - -## Messages - -### Msg/GrantAllowance - -A fee allowance grant will be created with the `MsgGrantAllowance` message. - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/feegrant/v1beta1/tx.proto#L25-L39 -``` - -### Msg/RevokeAllowance - -An allowed grant fee allowance can be removed with the `MsgRevokeAllowance` message. - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/feegrant/v1beta1/tx.proto#L41-L54 -``` - -## Events - -The feegrant module emits the following events: - -## Msg Server - -### MsgGrantAllowance - -| Type | Attribute Key | Attribute Value | -| ------- | ------------- | ---------------- | -| message | action | set_feegrant | -| message | granter | {granterAddress} | -| message | grantee | {granteeAddress} | - -### MsgRevokeAllowance - -| Type | Attribute Key | Attribute Value | -| ------- | ------------- | ---------------- | -| message | action | revoke_feegrant | -| message | granter | {granterAddress} | -| message | grantee | {granteeAddress} | - -### Exec fee allowance - -| Type | Attribute Key | Attribute Value | -| ------- | ------------- | ---------------- | -| message | action | use_feegrant | -| message | granter | {granterAddress} | -| message | grantee | {granteeAddress} | - -### Prune fee allowances - -| Type | Attribute Key | Attribute Value | -| ------- | ------------- | ---------------- | -| message | action | prune_feegrant | -| message | pruner | {prunerAddress} | - - -## Client - -### CLI - -A user can query and interact with the `feegrant` module using the CLI. - -#### Query - -The `query` commands allow users to query `feegrant` state. - -```shell -simd query feegrant --help -``` - -##### grant - -The `grant` command allows users to query a grant for a given granter-grantee pair. - -```shell -simd query feegrant grant [granter] [grantee] [flags] -``` - -Example: - -```shell -simd query feegrant grant cosmos1.. cosmos1.. -``` - -Example Output: - -```yml -allowance: - '@type': /cosmos.feegrant.v1beta1.BasicAllowance - expiration: null - spend_limit: - - amount: "100" - denom: stake -grantee: cosmos1.. -granter: cosmos1.. -``` - -##### grants - -The `grants` command allows users to query all grants for a given grantee. - -```shell -simd query feegrant grants [grantee] [flags] -``` - -Example: - -```shell -simd query feegrant grants cosmos1.. -``` - -Example Output: - -```yml -allowances: -- allowance: - '@type': /cosmos.feegrant.v1beta1.BasicAllowance - expiration: null - spend_limit: - - amount: "100" - denom: stake - grantee: cosmos1.. - granter: cosmos1.. -pagination: - next_key: null - total: "0" -``` - -#### Transactions - -The `tx` commands allow users to interact with the `feegrant` module. - -```shell -simd tx feegrant --help -``` - -##### grant - -The `grant` command allows users to grant fee allowances to another account. The fee allowance can have an expiration date, a total spend limit, and/or a periodic spend limit. - -```shell -simd tx feegrant grant [granter] [grantee] [flags] -``` - -Example (one-time spend limit): - -```shell -simd tx feegrant grant cosmos1.. cosmos1.. --spend-limit 100stake -``` - -Example (periodic spend limit): - -```shell -simd tx feegrant grant cosmos1.. cosmos1.. --period 3600 --period-limit 10stake -``` - -##### revoke - -The `revoke` command allows users to revoke a granted fee allowance. - -```shell -simd tx feegrant revoke [granter] [grantee] [flags] -``` - -Example: - -```shell -simd tx feegrant revoke cosmos1.. cosmos1.. -``` - -### gRPC - -A user can query the `feegrant` module using gRPC endpoints. - -#### Allowance - -The `Allowance` endpoint allows users to query a granted fee allowance. - -```shell -cosmos.feegrant.v1beta1.Query/Allowance -``` - -Example: - -```shell -grpcurl -plaintext \ - -d '{"grantee":"cosmos1..","granter":"cosmos1.."}' \ - localhost:9090 \ - cosmos.feegrant.v1beta1.Query/Allowance -``` - -Example Output: - -```json -{ - "allowance": { - "granter": "cosmos1..", - "grantee": "cosmos1..", - "allowance": {"@type":"/cosmos.feegrant.v1beta1.BasicAllowance","spendLimit":[{"denom":"stake","amount":"100"}]} - } -} -``` - -#### Allowances - -The `Allowances` endpoint allows users to query all granted fee allowances for a given grantee. - -```shell -cosmos.feegrant.v1beta1.Query/Allowances -``` - -Example: - -```shell -grpcurl -plaintext \ - -d '{"address":"cosmos1.."}' \ - localhost:9090 \ - cosmos.feegrant.v1beta1.Query/Allowances -``` - -Example Output: - -```json -{ - "allowances": [ - { - "granter": "cosmos1..", - "grantee": "cosmos1..", - "allowance": {"@type":"/cosmos.feegrant.v1beta1.BasicAllowance","spendLimit":[{"denom":"stake","amount":"100"}]} - } - ], - "pagination": { - "total": "1" - } -} -``` diff --git a/.gitbook/developers/modules/core/genutil/README.md b/.gitbook/developers/modules/core/genutil/README.md deleted file mode 100644 index 45cb4535..00000000 --- a/.gitbook/developers/modules/core/genutil/README.md +++ /dev/null @@ -1,89 +0,0 @@ -# `x/genutil` - -## Concepts - -The `genutil` package contains a variety of genesis utility functionalities for usage within a blockchain application. Namely: - -* Genesis transactions related (gentx) -* Commands for collection and creation of gentxs -* `InitChain` processing of gentxs -* Genesis file creation -* Genesis file validation -* Genesis file migration -* CometBFT related initialization - * Translation of an app genesis to a CometBFT genesis - -## Genesis - -Genutil contains the data structure that defines an application genesis. -An application genesis consist of a consensus genesis (g.e. CometBFT genesis) and application related genesis data. - -```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-rc.0/x/genutil/types/genesis.go#L24-L34 -``` - -The application genesis can then be translated to the consensus engine to the right format: - -```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-rc.0/x/genutil/types/genesis.go#L126-L136 -``` - -```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-rc.0/server/start.go#L397-L407 -``` - -## Client - -### CLI - -The genutil commands are available under the `genesis` subcommand. - -#### add-genesis-account - -Add a genesis account to `genesis.json`. Learn more [here](https://docs.cosmos.network/main/run-node/run-node#adding-genesis-accounts). - -#### collect-gentxs - -Collect genesis txs and output a `genesis.json` file. - -```shell -simd genesis collect-gentxs -``` - -This will create a new `genesis.json` file that includes data from all the validators (we sometimes call it the "super genesis file" to distinguish it from single-validator genesis files). - -#### gentx - -Generate a genesis tx carrying a self delegation. - -```shell -simd genesis gentx [key_name] [amount] --chain-id [chain-id] -``` - -This will create the genesis transaction for your new chain. Here `amount` should be at least `1000000000stake`. -If you provide too much or too little, you will encounter an error when starting a node. - -#### migrate - -Migrate genesis to a specified target (SDK) version. - -```shell -simd genesis migrate [target-version] -``` - -:::tip -The `migrate` command is extensible and takes a `MigrationMap`. This map is a mapping of target versions to genesis migrations functions. -When not using the default `MigrationMap`, it is recommended to still call the default `MigrationMap` corresponding the SDK version of the chain and prepend/append your own genesis migrations. -::: - -#### validate-genesis - -Validates the genesis file at the default location or at the location passed as an argument. - -```shell -simd genesis validate-genesis -``` - -:::warning -Validate genesis only validates if the genesis is valid at the **current application binary**. For validating a genesis from a previous version of the application, use the `migrate` command to migrate the genesis to the current version. -::: diff --git a/.gitbook/developers/modules/core/genutils.md b/.gitbook/developers/modules/core/genutils.md deleted file mode 100644 index ccf79c83..00000000 --- a/.gitbook/developers/modules/core/genutils.md +++ /dev/null @@ -1,2 +0,0 @@ -# Genutils - diff --git a/.gitbook/developers/modules/core/gov/README.md b/.gitbook/developers/modules/core/gov/README.md deleted file mode 100644 index 87b2fc5f..00000000 --- a/.gitbook/developers/modules/core/gov/README.md +++ /dev/null @@ -1,2547 +0,0 @@ ---- -sidebar_position: 1 ---- - -# `x/gov` - -## Abstract - -This paper specifies the Governance module of the Cosmos SDK, which was first -described in the [Cosmos Whitepaper](https://cosmos.network/about/whitepaper) in -June 2016. - -The module enables Cosmos SDK based blockchain to support an on-chain governance -system. In this system, holders of the native staking token of the chain can vote -on proposals on a 1 token 1 vote basis. Next is a list of features the module -currently supports: - -* **Proposal submission:** Users can submit proposals with a deposit. Once the -minimum deposit is reached, the proposal enters voting period. The minimum deposit can be reached by collecting deposits from different users (including proposer) within deposit period. -* **Vote:** Participants can vote on proposals that reached MinDeposit and entered voting period. -* **Inheritance and penalties:** Delegators inherit their validator's vote if -they don't vote themselves. -* **Claiming deposit:** Users that deposited on proposals can recover their -deposits if the proposal was accepted or rejected. If the proposal was vetoed, or never entered voting period (minimum deposit not reached within deposit period), the deposit is burned. - -This module is in use on the Cosmos Hub (a.k.a [gaia](https://github.com/cosmos/gaia)). -Features that may be added in the future are described in [Future Improvements](#future-improvements). - -## Contents - -The following specification uses *ATOM* as the native staking token. The module -can be adapted to any Proof-Of-Stake blockchain by replacing *ATOM* with the native -staking token of the chain. - -* [Concepts](#concepts) - * [Proposal submission](#proposal-submission) - * [Deposit](#deposit) - * [Vote](#vote) - * [Software Upgrade](#software-upgrade) -* [State](#state) - * [Proposals](#proposals) - * [Parameters and base types](#parameters-and-base-types) - * [Deposit](#deposit-1) - * [ValidatorGovInfo](#validatorgovinfo) - * [Stores](#stores) - * [Proposal Processing Queue](#proposal-processing-queue) - * [Legacy Proposal](#legacy-proposal) -* [Messages](#messages) - * [Proposal Submission](#proposal-submission-1) - * [Deposit](#deposit-2) - * [Vote](#vote-1) -* [Events](#events) - * [EndBlocker](#endblocker) - * [Handlers](#handlers) -* [Parameters](#parameters) -* [Client](#client) - * [CLI](#cli) - * [gRPC](#grpc) - * [REST](#rest) -* [Metadata](#metadata) - * [Proposal](#proposal-3) - * [Vote](#vote-5) -* [Future Improvements](#future-improvements) - -## Concepts - -*Disclaimer: This is work in progress. Mechanisms are susceptible to change.* - -The governance process is divided in a few steps that are outlined below: - -* **Proposal submission:** Proposal is submitted to the blockchain with a - deposit. -* **Vote:** Once deposit reaches a certain value (`MinDeposit`), proposal is - confirmed and vote opens. Bonded Atom holders can then send `TxGovVote` - transactions to vote on the proposal. -* **Execution** After a period of time, the votes are tallied and depending - on the result, the messages in the proposal will be executed. - -### Proposal submission - -#### Right to submit a proposal - -Every account can submit proposals by sending a `MsgSubmitProposal` transaction. -Once a proposal is submitted, it is identified by its unique `proposalID`. - -#### Proposal Messages - -A proposal includes an array of `sdk.Msg`s which are executed automatically if the -proposal passes. The messages are executed by the governance `ModuleAccount` itself. Modules -such as `x/upgrade`, that want to allow certain messages to be executed by governance -only should add a whitelist within the respective msg server, granting the governance -module the right to execute the message once a quorum has been reached. The governance -module uses the `MsgServiceRouter` to check that these messages are correctly constructed -and have a respective path to execute on but do not perform a full validity check. - -### Deposit - -To prevent spam, proposals must be submitted with a deposit in the coins defined by -the `MinDeposit` param. - -When a proposal is submitted, it has to be accompanied with a deposit that must be -strictly positive, but can be inferior to `MinDeposit`. The submitter doesn't need -to pay for the entire deposit on their own. The newly created proposal is stored in -an *inactive proposal queue* and stays there until its deposit passes the `MinDeposit`. -Other token holders can increase the proposal's deposit by sending a `Deposit` -transaction. If a proposal doesn't pass the `MinDeposit` before the deposit end time -(the time when deposits are no longer accepted), the proposal will be destroyed: the -proposal will be removed from state and the deposit will be burned (see x/gov `EndBlocker`). -When a proposal deposit passes the `MinDeposit` threshold (even during the proposal -submission) before the deposit end time, the proposal will be moved into the -*active proposal queue* and the voting period will begin. - -The deposit is kept in escrow and held by the governance `ModuleAccount` until the -proposal is finalized (passed or rejected). - -#### Deposit refund and burn - -When a proposal is finalized, the coins from the deposit are either refunded or burned -according to the final tally of the proposal: - -* If the proposal is approved or rejected but *not* vetoed, each deposit will be - automatically refunded to its respective depositor (transferred from the governance - `ModuleAccount`). -* When the proposal is vetoed with greater than 1/3, deposits will be burned from the - governance `ModuleAccount` and the proposal information along with its deposit - information will be removed from state. -* All refunded or burned deposits are removed from the state. Events are issued when - burning or refunding a deposit. - -### Vote - -#### Participants - -*Participants* are users that have the right to vote on proposals. On the -Cosmos Hub, participants are bonded Atom holders. Unbonded Atom holders and -other users do not get the right to participate in governance. However, they -can submit and deposit on proposals. - -Note that when *participants* have bonded and unbonded Atoms, their voting power is calculated from their bonded Atom holdings only. - -#### Voting period - -Once a proposal reaches `MinDeposit`, it immediately enters `Voting period`. We -define `Voting period` as the interval between the moment the vote opens and -the moment the vote closes. The initial value of `Voting period` is 2 weeks. - -#### Option set - -The option set of a proposal refers to the set of choices a participant can -choose from when casting its vote. - -The initial option set includes the following options: - -* `Yes` -* `No` -* `NoWithVeto` -* `Abstain` - -`NoWithVeto` counts as `No` but also adds a `Veto` vote. `Abstain` option -allows voters to signal that they do not intend to vote in favor or against the -proposal but accept the result of the vote. - -*Note: from the UI, for urgent proposals we should maybe add a ‘Not Urgent’ option that casts a `NoWithVeto` vote.* - -#### Weighted Votes - -[ADR-037](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-037-gov-split-vote.md) introduces the weighted vote feature which allows a staker to split their votes into several voting options. For example, it could use 70% of its voting power to vote Yes and 30% of its voting power to vote No. - -Often times the entity owning that address might not be a single individual. For example, a company might have different stakeholders who want to vote differently, and so it makes sense to allow them to split their voting power. Currently, it is not possible for them to do "passthrough voting" and giving their users voting rights over their tokens. However, with this system, exchanges can poll their users for voting preferences, and then vote on-chain proportionally to the results of the poll. - -To represent weighted vote on chain, we use the following Protobuf message. - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/gov/v1beta1/gov.proto#L34-L47 -``` - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/gov/v1beta1/gov.proto#L181-L201 -``` - -For a weighted vote to be valid, the `options` field must not contain duplicate vote options, and the sum of weights of all options must be equal to 1. - -### Quorum - -Quorum is defined as the minimum percentage of voting power that needs to be -cast on a proposal for the result to be valid. - -### Expedited Proposals - -A proposal can be expedited, making the proposal use shorter voting duration and a higher tally threshold by its default. If an expedited proposal fails to meet the threshold within the scope of shorter voting duration, the expedited proposal is then converted to a regular proposal and restarts voting under regular voting conditions. - -#### Threshold - -Threshold is defined as the minimum proportion of `Yes` votes (excluding -`Abstain` votes) for the proposal to be accepted. - -Initially, the threshold is set at 50% of `Yes` votes, excluding `Abstain` -votes. A possibility to veto exists if more than 1/3rd of all votes are -`NoWithVeto` votes. Note, both of these values are derived from the `TallyParams` -on-chain parameter, which is modifiable by governance. -This means that proposals are accepted iff: - -* There exist bonded tokens. -* Quorum has been achieved. -* The proportion of `Abstain` votes is inferior to 1/1. -* The proportion of `NoWithVeto` votes is inferior to 1/3, including - `Abstain` votes. -* The proportion of `Yes` votes, excluding `Abstain` votes, at the end of - the voting period is superior to 1/2. - -For expedited proposals, by default, the threshold is higher than with a *normal proposal*, namely, 66.7%. - -#### Inheritance - -If a delegator does not vote, it will inherit its validator vote. - -* If the delegator votes before its validator, it will not inherit from the - validator's vote. -* If the delegator votes after its validator, it will override its validator - vote with its own. If the proposal is urgent, it is possible - that the vote will close before delegators have a chance to react and - override their validator's vote. This is not a problem, as proposals require more than 2/3rd of the total voting power to pass, when tallied at the end of the voting period. Because as little as 1/3 + 1 validation power could collude to censor transactions, non-collusion is already assumed for ranges exceeding this threshold. - -#### Validator’s punishment for non-voting - -At present, validators are not punished for failing to vote. - -#### Governance address - -Later, we may add permissioned keys that could only sign txs from certain modules. For the MVP, the `Governance address` will be the main validator address generated at account creation. This address corresponds to a different PrivKey than the CometBFT PrivKey which is responsible for signing consensus messages. Validators thus do not have to sign governance transactions with the sensitive CometBFT PrivKey. - -#### Burnable Params - -There are three parameters that define if the deposit of a proposal should be burned or returned to the depositors. - -* `BurnVoteVeto` burns the proposal deposit if the proposal gets vetoed. -* `BurnVoteQuorum` burns the proposal deposit if the proposal deposit if the vote does not reach quorum. -* `BurnProposalDepositPrevote` burns the proposal deposit if it does not enter the voting phase. - -> Note: These parameters are modifiable via governance. - -## State - -### Constitution - -`Constitution` is found in the genesis state. It is a string field intended to be used to descibe the purpose of a particular blockchain, and its expected norms. A few examples of how the constitution field can be used: - -* define the purpose of the chain, laying a foundation for its future development -* set expectations for delegators -* set expectations for validators -* define the chain's relationship to "meatspace" entities, like a foundation or corporation - -Since this is more of a social feature than a technical feature, we'll now get into some items that may have been useful to have in a genesis constitution: - -* What limitations on governance exist, if any? - * is it okay for the community to slash the wallet of a whale that they no longer feel that they want around? (viz: Juno Proposal 4 and 16) - * can governance "socially slash" a validator who is using unapproved MEV? (viz: commonwealth.im/osmosis) - * In the event of an economic emergency, what should validators do? - * Terra crash of May, 2022, saw validators choose to run a new binary with code that had not been approved by governance, because the governance token had been inflated to nothing. -* What is the purpose of the chain, specifically? - * best example of this is the Cosmos hub, where different founding groups, have different interpertations of the purpose of the network. - -This genesis entry, "constitution" hasn't been designed for existing chains, who should likely just ratify a constitution using their governance system. Instead, this is for new chains. It will allow for validators to have a much clearer idea of purpose and the expecations placed on them while operating thier nodes. Likewise, for community members, the constitution will give them some idea of what to expect from both the "chain team" and the validators, respectively. - -This constitution is designed to be immutable, and placed only in genesis, though that could change over time by a pull request to the cosmos-sdk that allows for the constitution to be changed by governance. Communities whishing to make amendments to their original constitution should use the governance mechanism and a "signaling proposal" to do exactly that. - -**Ideal use scenario for a cosmos chain constitution** - -As a chain developer, you decide that you'd like to provide clarity to your key user groups: - -* validators -* token holders -* developers (yourself) - -You use the constitution to immutably store some Markdown in genesis, so that when difficult questions come up, the constutituon can provide guidance to the community. - -### Proposals - -`Proposal` objects are used to tally votes and generally track the proposal's state. -They contain an array of arbitrary `sdk.Msg`'s which the governance module will attempt -to resolve and then execute if the proposal passes. `Proposal`'s are identified by a -unique id and contains a series of timestamps: `submit_time`, `deposit_end_time`, -`voting_start_time`, `voting_end_time` which track the lifecycle of a proposal - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/gov/v1/gov.proto#L51-L99 -``` - -A proposal will generally require more than just a set of messages to explain its -purpose but need some greater justification and allow a means for interested participants -to discuss and debate the proposal. -In most cases, **it is encouraged to have an off-chain system that supports the on-chain governance process**. -To accommodate for this, a proposal contains a special **`metadata`** field, a string, -which can be used to add context to the proposal. The `metadata` field allows custom use for networks, -however, it is expected that the field contains a URL or some form of CID using a system such as -[IPFS](https://docs.ipfs.io/concepts/content-addressing/). To support the case of -interoperability across networks, the SDK recommends that the `metadata` represents -the following `JSON` template: - -```json -{ - "title": "...", - "description": "...", - "forum": "...", // a link to the discussion platform (i.e. Discord) - "other": "..." // any extra data that doesn't correspond to the other fields -} -``` - -This makes it far easier for clients to support multiple networks. - -The metadata has a maximum length that is chosen by the app developer, and -passed into the gov keeper as a config. The default maximum length in the SDK is 255 characters. - -#### Writing a module that uses governance - -There are many aspects of a chain, or of the individual modules that you may want to -use governance to perform such as changing various parameters. This is very simple -to do. First, write out your message types and `MsgServer` implementation. Add an -`authority` field to the keeper which will be populated in the constructor with the -governance module account: `govKeeper.GetGovernanceAccount().GetAddress()`. Then for -the methods in the `msg_server.go`, perform a check on the message that the signer -matches `authority`. This will prevent any user from executing that message. - -### Parameters and base types - -`Parameters` define the rules according to which votes are run. There can only -be one active parameter set at any given time. If governance wants to change a -parameter set, either to modify a value or add/remove a parameter field, a new -parameter set has to be created and the previous one rendered inactive. - -#### DepositParams - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/gov/v1/gov.proto#L152-L162 -``` - -#### VotingParams - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/gov/v1/gov.proto#L164-L168 -``` - -#### TallyParams - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/gov/v1/gov.proto#L170-L182 -``` - -Parameters are stored in a global `GlobalParams` KVStore. - -Additionally, we introduce some basic types: - -```go -type Vote byte - -const ( - VoteYes = 0x1 - VoteNo = 0x2 - VoteNoWithVeto = 0x3 - VoteAbstain = 0x4 -) - -type ProposalType string - -const ( - ProposalTypePlainText = "Text" - ProposalTypeSoftwareUpgrade = "SoftwareUpgrade" -) - -type ProposalStatus byte - - -const ( - StatusNil ProposalStatus = 0x00 - StatusDepositPeriod ProposalStatus = 0x01 // Proposal is submitted. Participants can deposit on it but not vote - StatusVotingPeriod ProposalStatus = 0x02 // MinDeposit is reached, participants can vote - StatusPassed ProposalStatus = 0x03 // Proposal passed and successfully executed - StatusRejected ProposalStatus = 0x04 // Proposal has been rejected - StatusFailed ProposalStatus = 0x05 // Proposal passed but failed execution -) -``` - -### Deposit - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/gov/v1/gov.proto#L38-L49 -``` - -### ValidatorGovInfo - -This type is used in a temp map when tallying - -```go - type ValidatorGovInfo struct { - Minus sdk.Dec - Vote Vote - } -``` - -## Stores - -:::note -Stores are KVStores in the multi-store. The key to find the store is the first parameter in the list -::: - -We will use one KVStore `Governance` to store four mappings: - -* A mapping from `proposalID|'proposal'` to `Proposal`. -* A mapping from `proposalID|'addresses'|address` to `Vote`. This mapping allows - us to query all addresses that voted on the proposal along with their vote by - doing a range query on `proposalID:addresses`. -* A mapping from `ParamsKey|'Params'` to `Params`. This map allows to query all - x/gov params. -* A mapping from `VotingPeriodProposalKeyPrefix|proposalID` to a single byte. This allows - us to know if a proposal is in the voting period or not with very low gas cost. - -For pseudocode purposes, here are the two function we will use to read or write in stores: - -* `load(StoreKey, Key)`: Retrieve item stored at key `Key` in store found at key `StoreKey` in the multistore -* `store(StoreKey, Key, value)`: Write value `Value` at key `Key` in store found at key `StoreKey` in the multistore - -### Proposal Processing Queue - -**Store:** - -* `ProposalProcessingQueue`: A queue `queue[proposalID]` containing all the - `ProposalIDs` of proposals that reached `MinDeposit`. During each `EndBlock`, - all the proposals that have reached the end of their voting period are processed. - To process a finished proposal, the application tallies the votes, computes the - votes of each validator and checks if every validator in the validator set has - voted. If the proposal is accepted, deposits are refunded. Finally, the proposal - content `Handler` is executed. - -And the pseudocode for the `ProposalProcessingQueue`: - -```go - in EndBlock do - - for finishedProposalID in GetAllFinishedProposalIDs(block.Time) - proposal = load(Governance, ) // proposal is a const key - - validators = Keeper.getAllValidators() - tmpValMap := map(sdk.AccAddress)ValidatorGovInfo - - // Initiate mapping at 0. This is the amount of shares of the validator's vote that will be overridden by their delegator's votes - for each validator in validators - tmpValMap(validator.OperatorAddr).Minus = 0 - - // Tally - voterIterator = rangeQuery(Governance, ) //return all the addresses that voted on the proposal - for each (voterAddress, vote) in voterIterator - delegations = stakingKeeper.getDelegations(voterAddress) // get all delegations for current voter - - for each delegation in delegations - // make sure delegation.Shares does NOT include shares being unbonded - tmpValMap(delegation.ValidatorAddr).Minus += delegation.Shares - proposal.updateTally(vote, delegation.Shares) - - _, isVal = stakingKeeper.getValidator(voterAddress) - if (isVal) - tmpValMap(voterAddress).Vote = vote - - tallyingParam = load(GlobalParams, 'TallyingParam') - - // Update tally if validator voted - for each validator in validators - if tmpValMap(validator).HasVoted - proposal.updateTally(tmpValMap(validator).Vote, (validator.TotalShares - tmpValMap(validator).Minus)) - - - - // Check if proposal is accepted or rejected - totalNonAbstain := proposal.YesVotes + proposal.NoVotes + proposal.NoWithVetoVotes - if (proposal.Votes.YesVotes/totalNonAbstain > tallyingParam.Threshold AND proposal.Votes.NoWithVetoVotes/totalNonAbstain < tallyingParam.Veto) - // proposal was accepted at the end of the voting period - // refund deposits (non-voters already punished) - for each (amount, depositor) in proposal.Deposits - depositor.AtomBalance += amount - - stateWriter, err := proposal.Handler() - if err != nil - // proposal passed but failed during state execution - proposal.CurrentStatus = ProposalStatusFailed - else - // proposal pass and state is persisted - proposal.CurrentStatus = ProposalStatusAccepted - stateWriter.save() - else - // proposal was rejected - proposal.CurrentStatus = ProposalStatusRejected - - store(Governance, , proposal) -``` - -### Legacy Proposal - -:::warning -Legacy proposals are deprecated. Use the new proposal flow by granting the governance module the right to execute the message. -::: - -A legacy proposal is the old implementation of governance proposal. -Contrary to proposal that can contain any messages, a legacy proposal allows to submit a set of pre-defined proposals. -These proposals are defined by their types and handled by handlers that are registered in the gov v1beta1 router. - -More information on how to submit proposals in the [client section](#client). - -## Messages - -### Proposal Submission - -Proposals can be submitted by any account via a `MsgSubmitProposal` transaction. - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/gov/v1/tx.proto#L42-L69 -``` - -All `sdk.Msgs` passed into the `messages` field of a `MsgSubmitProposal` message -must be registered in the app's `MsgServiceRouter`. Each of these messages must -have one signer, namely the gov module account. And finally, the metadata length -must not be larger than the `maxMetadataLen` config passed into the gov keeper. -The `initialDeposit` must be strictly positive and conform to the accepted denom of the `MinDeposit` param. - -**State modifications:** - -* Generate new `proposalID` -* Create new `Proposal` -* Initialise `Proposal`'s attributes -* Decrease balance of sender by `InitialDeposit` -* If `MinDeposit` is reached: - * Push `proposalID` in `ProposalProcessingQueue` -* Transfer `InitialDeposit` from the `Proposer` to the governance `ModuleAccount` - -### Deposit - -Once a proposal is submitted, if `Proposal.TotalDeposit < ActiveParam.MinDeposit`, Atom holders can send -`MsgDeposit` transactions to increase the proposal's deposit. - -A deposit is accepted iff: - -* The proposal exists -* The proposal is not in the voting period -* The deposited coins are conform to the accepted denom from the `MinDeposit` param - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/gov/v1/tx.proto#L134-L147 -``` - -**State modifications:** - -* Decrease balance of sender by `deposit` -* Add `deposit` of sender in `proposal.Deposits` -* Increase `proposal.TotalDeposit` by sender's `deposit` -* If `MinDeposit` is reached: - * Push `proposalID` in `ProposalProcessingQueueEnd` -* Transfer `Deposit` from the `proposer` to the governance `ModuleAccount` - -### Vote - -Once `ActiveParam.MinDeposit` is reached, voting period starts. From there, -bonded Atom holders are able to send `MsgVote` transactions to cast their -vote on the proposal. - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/gov/v1/tx.proto#L92-L108 -``` - -**State modifications:** - -* Record `Vote` of sender - -:::note -Gas cost for this message has to take into account the future tallying of the vote in EndBlocker. -::: - -## Events - -The governance module emits the following events: - -### EndBlocker - -| Type | Attribute Key | Attribute Value | -|-------------------|-----------------|------------------| -| inactive_proposal | proposal_id | {proposalID} | -| inactive_proposal | proposal_result | {proposalResult} | -| active_proposal | proposal_id | {proposalID} | -| active_proposal | proposal_result | {proposalResult} | - -### Handlers - -#### MsgSubmitProposal - -| Type | Attribute Key | Attribute Value | -|---------------------|---------------------|-----------------| -| submit_proposal | proposal_id | {proposalID} | -| submit_proposal [0] | voting_period_start | {proposalID} | -| proposal_deposit | amount | {depositAmount} | -| proposal_deposit | proposal_id | {proposalID} | -| message | module | governance | -| message | action | submit_proposal | -| message | sender | {senderAddress} | - -* [0] Event only emitted if the voting period starts during the submission. - -#### MsgVote - -| Type | Attribute Key | Attribute Value | -|---------------|---------------|-----------------| -| proposal_vote | option | {voteOption} | -| proposal_vote | proposal_id | {proposalID} | -| message | module | governance | -| message | action | vote | -| message | sender | {senderAddress} | - -#### MsgVoteWeighted - -| Type | Attribute Key | Attribute Value | -|---------------|---------------|-----------------------| -| proposal_vote | option | {weightedVoteOptions} | -| proposal_vote | proposal_id | {proposalID} | -| message | module | governance | -| message | action | vote | -| message | sender | {senderAddress} | - -#### MsgDeposit - -| Type | Attribute Key | Attribute Value | -|----------------------|---------------------|-----------------| -| proposal_deposit | amount | {depositAmount} | -| proposal_deposit | proposal_id | {proposalID} | -| proposal_deposit [0] | voting_period_start | {proposalID} | -| message | module | governance | -| message | action | deposit | -| message | sender | {senderAddress} | - -* [0] Event only emitted if the voting period starts during the submission. - -## Parameters - -The governance module contains the following parameters: - -| Key | Type | Example | -|-------------------------------|------------------|-----------------------------------------| -| min_deposit | array (coins) | [{"denom":"uatom","amount":"10000000"}] | -| max_deposit_period | string (time ns) | "172800000000000" (17280s) | -| voting_period | string (time ns) | "172800000000000" (17280s) | -| quorum | string (dec) | "0.334000000000000000" | -| threshold | string (dec) | "0.500000000000000000" | -| veto | string (dec) | "0.334000000000000000" | -| expedited_threshold | string (time ns) | "0.667000000000000000" | -| expedited_voting_period | string (time ns) | "86400000000000" (8600s) | -| expedited_min_deposit | array (coins) | [{"denom":"uatom","amount":"50000000"}] | -| burn_proposal_deposit_prevote | bool | false | -| burn_vote_quorum | bool | false | -| burn_vote_veto | bool | true | -| min_initial_deposit_ratio | string | "0.1" | - - -**NOTE**: The governance module contains parameters that are objects unlike other -modules. If only a subset of parameters are desired to be changed, only they need -to be included and not the entire parameter object structure. - -## Client - -### CLI - -A user can query and interact with the `gov` module using the CLI. - -#### Query - -The `query` commands allow users to query `gov` state. - -```bash -simd query gov --help -``` - -##### deposit - -The `deposit` command allows users to query a deposit for a given proposal from a given depositor. - -```bash -simd query gov deposit [proposal-id] [depositer-addr] [flags] -``` - -Example: - -```bash -simd query gov deposit 1 cosmos1.. -``` - -Example Output: - -```bash -amount: -- amount: "100" - denom: stake -depositor: cosmos1.. -proposal_id: "1" -``` - -##### deposits - -The `deposits` command allows users to query all deposits for a given proposal. - -```bash -simd query gov deposits [proposal-id] [flags] -``` - -Example: - -```bash -simd query gov deposits 1 -``` - -Example Output: - -```bash -deposits: -- amount: - - amount: "100" - denom: stake - depositor: cosmos1.. - proposal_id: "1" -pagination: - next_key: null - total: "0" -``` - -##### param - -The `param` command allows users to query a given parameter for the `gov` module. - -```bash -simd query gov param [param-type] [flags] -``` - -Example: - -```bash -simd query gov param voting -``` - -Example Output: - -```bash -voting_period: "172800000000000" -``` - -##### params - -The `params` command allows users to query all parameters for the `gov` module. - -```bash -simd query gov params [flags] -``` - -Example: - -```bash -simd query gov params -``` - -Example Output: - -```bash -deposit_params: - max_deposit_period: 172800s - min_deposit: - - amount: "10000000" - denom: stake -params: - expedited_min_deposit: - - amount: "50000000" - denom: stake - expedited_threshold: "0.670000000000000000" - expedited_voting_period: 86400s - max_deposit_period: 172800s - min_deposit: - - amount: "10000000" - denom: stake - min_initial_deposit_ratio: "0.000000000000000000" - proposal_cancel_burn_rate: "0.500000000000000000" - quorum: "0.334000000000000000" - threshold: "0.500000000000000000" - veto_threshold: "0.334000000000000000" - voting_period: 172800s -tally_params: - quorum: "0.334000000000000000" - threshold: "0.500000000000000000" - veto_threshold: "0.334000000000000000" -voting_params: - voting_period: 172800s -``` - -##### proposal - -The `proposal` command allows users to query a given proposal. - -```bash -simd query gov proposal [proposal-id] [flags] -``` - -Example: - -```bash -simd query gov proposal 1 -``` - -Example Output: - -```bash -deposit_end_time: "2022-03-30T11:50:20.819676256Z" -final_tally_result: - abstain_count: "0" - no_count: "0" - no_with_veto_count: "0" - yes_count: "0" -id: "1" -messages: -- '@type': /cosmos.bank.v1beta1.MsgSend - amount: - - amount: "10" - denom: stake - from_address: cosmos1.. - to_address: cosmos1.. -metadata: AQ== -status: PROPOSAL_STATUS_DEPOSIT_PERIOD -submit_time: "2022-03-28T11:50:20.819676256Z" -total_deposit: -- amount: "10" - denom: stake -voting_end_time: null -voting_start_time: null -``` - -##### proposals - -The `proposals` command allows users to query all proposals with optional filters. - -```bash -simd query gov proposals [flags] -``` - -Example: - -```bash -simd query gov proposals -``` - -Example Output: - -```bash -pagination: - next_key: null - total: "0" -proposals: -- deposit_end_time: "2022-03-30T11:50:20.819676256Z" - final_tally_result: - abstain_count: "0" - no_count: "0" - no_with_veto_count: "0" - yes_count: "0" - id: "1" - messages: - - '@type': /cosmos.bank.v1beta1.MsgSend - amount: - - amount: "10" - denom: stake - from_address: cosmos1.. - to_address: cosmos1.. - metadata: AQ== - status: PROPOSAL_STATUS_DEPOSIT_PERIOD - submit_time: "2022-03-28T11:50:20.819676256Z" - total_deposit: - - amount: "10" - denom: stake - voting_end_time: null - voting_start_time: null -- deposit_end_time: "2022-03-30T14:02:41.165025015Z" - final_tally_result: - abstain_count: "0" - no_count: "0" - no_with_veto_count: "0" - yes_count: "0" - id: "2" - messages: - - '@type': /cosmos.bank.v1beta1.MsgSend - amount: - - amount: "10" - denom: stake - from_address: cosmos1.. - to_address: cosmos1.. - metadata: AQ== - status: PROPOSAL_STATUS_DEPOSIT_PERIOD - submit_time: "2022-03-28T14:02:41.165025015Z" - total_deposit: - - amount: "10" - denom: stake - voting_end_time: null - voting_start_time: null -``` - -##### proposer - -The `proposer` command allows users to query the proposer for a given proposal. - -```bash -simd query gov proposer [proposal-id] [flags] -``` - -Example: - -```bash -simd query gov proposer 1 -``` - -Example Output: - -```bash -proposal_id: "1" -proposer: cosmos1.. -``` - -##### tally - -The `tally` command allows users to query the tally of a given proposal vote. - -```bash -simd query gov tally [proposal-id] [flags] -``` - -Example: - -```bash -simd query gov tally 1 -``` - -Example Output: - -```bash -abstain: "0" -"no": "0" -no_with_veto: "0" -"yes": "1" -``` - -##### vote - -The `vote` command allows users to query a vote for a given proposal. - -```bash -simd query gov vote [proposal-id] [voter-addr] [flags] -``` - -Example: - -```bash -simd query gov vote 1 cosmos1.. -``` - -Example Output: - -```bash -option: VOTE_OPTION_YES -options: -- option: VOTE_OPTION_YES - weight: "1.000000000000000000" -proposal_id: "1" -voter: cosmos1.. -``` - -##### votes - -The `votes` command allows users to query all votes for a given proposal. - -```bash -simd query gov votes [proposal-id] [flags] -``` - -Example: - -```bash -simd query gov votes 1 -``` - -Example Output: - -```bash -pagination: - next_key: null - total: "0" -votes: -- option: VOTE_OPTION_YES - options: - - option: VOTE_OPTION_YES - weight: "1.000000000000000000" - proposal_id: "1" - voter: cosmos1.. -``` - -#### Transactions - -The `tx` commands allow users to interact with the `gov` module. - -```bash -simd tx gov --help -``` - -##### deposit - -The `deposit` command allows users to deposit tokens for a given proposal. - -```bash -simd tx gov deposit [proposal-id] [deposit] [flags] -``` - -Example: - -```bash -simd tx gov deposit 1 10000000stake --from cosmos1.. -``` - -##### draft-proposal - -The `draft-proposal` command allows users to draft any type of proposal. -The command returns a `draft_proposal.json`, to be used by `submit-proposal` after being completed. -The `draft_metadata.json` is meant to be uploaded to [IPFS](#metadata). - -```bash -simd tx gov draft-proposal -``` - -##### submit-proposal - -The `submit-proposal` command allows users to submit a governance proposal along with some messages and metadata. -Messages, metadata and deposit are defined in a JSON file. - -```bash -simd tx gov submit-proposal [path-to-proposal-json] [flags] -``` - -Example: - -```bash -simd tx gov submit-proposal /path/to/proposal.json --from cosmos1.. -``` - -where `proposal.json` contains: - -```json -{ - "messages": [ - { - "@type": "/cosmos.bank.v1beta1.MsgSend", - "from_address": "cosmos1...", // The gov module module address - "to_address": "cosmos1...", - "amount":[{"denom": "stake","amount": "10"}] - } - ], - "metadata": "AQ==", - "deposit": "10stake", - "title": "Proposal Title", - "summary": "Proposal Summary" -} -``` - -:::note -By default the metadata, summary and title are both limited by 255 characters, this can be overridden by the application developer. -::: - -:::tip -When metadata is not specified, the title is limited to 255 characters and the summary 40x the title length. -::: - -##### submit-legacy-proposal - -The `submit-legacy-proposal` command allows users to submit a governance legacy proposal along with an initial deposit. - -```bash -simd tx gov submit-legacy-proposal [command] [flags] -``` - -Example: - -```bash -simd tx gov submit-legacy-proposal --title="Test Proposal" --description="testing" --type="Text" --deposit="100000000stake" --from cosmos1.. -``` - -Example (`param-change`): - -```bash -simd tx gov submit-legacy-proposal param-change proposal.json --from cosmos1.. -``` - -```json -{ - "title": "Test Proposal", - "description": "testing, testing, 1, 2, 3", - "changes": [ - { - "subspace": "staking", - "key": "MaxValidators", - "value": 100 - } - ], - "deposit": "10000000stake" -} -``` - -#### cancel-proposal - -Once proposal is canceled, from the deposits of proposal `deposits * proposal_cancel_ratio` will be burned or sent to `ProposalCancelDest` address , if `ProposalCancelDest` is empty then deposits will be burned. The `remaining deposits` will be sent to depositers. - -```bash -simd tx gov cancel-proposal [proposal-id] [flags] -``` - -Example: - -```bash -simd tx gov cancel-proposal 1 --from cosmos1... -``` - -##### vote - -The `vote` command allows users to submit a vote for a given governance proposal. - -```bash -simd tx gov vote [command] [flags] -``` - -Example: - -```bash -simd tx gov vote 1 yes --from cosmos1.. -``` - -##### weighted-vote - -The `weighted-vote` command allows users to submit a weighted vote for a given governance proposal. - -```bash -simd tx gov weighted-vote [proposal-id] [weighted-options] [flags] -``` - -Example: - -```bash -simd tx gov weighted-vote 1 yes=0.5,no=0.5 --from cosmos1.. -``` - -### gRPC - -A user can query the `gov` module using gRPC endpoints. - -#### Proposal - -The `Proposal` endpoint allows users to query a given proposal. - -Using legacy v1beta1: - -```bash -cosmos.gov.v1beta1.Query/Proposal -``` - -Example: - -```bash -grpcurl -plaintext \ - -d '{"proposal_id":"1"}' \ - localhost:9090 \ - cosmos.gov.v1beta1.Query/Proposal -``` - -Example Output: - -```bash -{ - "proposal": { - "proposalId": "1", - "content": {"@type":"/cosmos.gov.v1beta1.TextProposal","description":"testing, testing, 1, 2, 3","title":"Test Proposal"}, - "status": "PROPOSAL_STATUS_VOTING_PERIOD", - "finalTallyResult": { - "yes": "0", - "abstain": "0", - "no": "0", - "noWithVeto": "0" - }, - "submitTime": "2021-09-16T19:40:08.712440474Z", - "depositEndTime": "2021-09-18T19:40:08.712440474Z", - "totalDeposit": [ - { - "denom": "stake", - "amount": "10000000" - } - ], - "votingStartTime": "2021-09-16T19:40:08.712440474Z", - "votingEndTime": "2021-09-18T19:40:08.712440474Z", - "title": "Test Proposal", - "summary": "testing, testing, 1, 2, 3" - } -} -``` - -Using v1: - -```bash -cosmos.gov.v1.Query/Proposal -``` - -Example: - -```bash -grpcurl -plaintext \ - -d '{"proposal_id":"1"}' \ - localhost:9090 \ - cosmos.gov.v1.Query/Proposal -``` - -Example Output: - -```bash -{ - "proposal": { - "id": "1", - "messages": [ - {"@type":"/cosmos.bank.v1beta1.MsgSend","amount":[{"denom":"stake","amount":"10"}],"fromAddress":"cosmos1..","toAddress":"cosmos1.."} - ], - "status": "PROPOSAL_STATUS_VOTING_PERIOD", - "finalTallyResult": { - "yesCount": "0", - "abstainCount": "0", - "noCount": "0", - "noWithVetoCount": "0" - }, - "submitTime": "2022-03-28T11:50:20.819676256Z", - "depositEndTime": "2022-03-30T11:50:20.819676256Z", - "totalDeposit": [ - { - "denom": "stake", - "amount": "10000000" - } - ], - "votingStartTime": "2022-03-28T14:25:26.644857113Z", - "votingEndTime": "2022-03-30T14:25:26.644857113Z", - "metadata": "AQ==", - "title": "Test Proposal", - "summary": "testing, testing, 1, 2, 3" - } -} -``` - -#### Proposals - -The `Proposals` endpoint allows users to query all proposals with optional filters. - -Using legacy v1beta1: - -```bash -cosmos.gov.v1beta1.Query/Proposals -``` - -Example: - -```bash -grpcurl -plaintext \ - localhost:9090 \ - cosmos.gov.v1beta1.Query/Proposals -``` - -Example Output: - -```bash -{ - "proposals": [ - { - "proposalId": "1", - "status": "PROPOSAL_STATUS_VOTING_PERIOD", - "finalTallyResult": { - "yes": "0", - "abstain": "0", - "no": "0", - "noWithVeto": "0" - }, - "submitTime": "2022-03-28T11:50:20.819676256Z", - "depositEndTime": "2022-03-30T11:50:20.819676256Z", - "totalDeposit": [ - { - "denom": "stake", - "amount": "10000000010" - } - ], - "votingStartTime": "2022-03-28T14:25:26.644857113Z", - "votingEndTime": "2022-03-30T14:25:26.644857113Z" - }, - { - "proposalId": "2", - "status": "PROPOSAL_STATUS_DEPOSIT_PERIOD", - "finalTallyResult": { - "yes": "0", - "abstain": "0", - "no": "0", - "noWithVeto": "0" - }, - "submitTime": "2022-03-28T14:02:41.165025015Z", - "depositEndTime": "2022-03-30T14:02:41.165025015Z", - "totalDeposit": [ - { - "denom": "stake", - "amount": "10" - } - ], - "votingStartTime": "0001-01-01T00:00:00Z", - "votingEndTime": "0001-01-01T00:00:00Z" - } - ], - "pagination": { - "total": "2" - } -} - -``` - -Using v1: - -```bash -cosmos.gov.v1.Query/Proposals -``` - -Example: - -```bash -grpcurl -plaintext \ - localhost:9090 \ - cosmos.gov.v1.Query/Proposals -``` - -Example Output: - -```bash -{ - "proposals": [ - { - "id": "1", - "messages": [ - {"@type":"/cosmos.bank.v1beta1.MsgSend","amount":[{"denom":"stake","amount":"10"}],"fromAddress":"cosmos1..","toAddress":"cosmos1.."} - ], - "status": "PROPOSAL_STATUS_VOTING_PERIOD", - "finalTallyResult": { - "yesCount": "0", - "abstainCount": "0", - "noCount": "0", - "noWithVetoCount": "0" - }, - "submitTime": "2022-03-28T11:50:20.819676256Z", - "depositEndTime": "2022-03-30T11:50:20.819676256Z", - "totalDeposit": [ - { - "denom": "stake", - "amount": "10000000010" - } - ], - "votingStartTime": "2022-03-28T14:25:26.644857113Z", - "votingEndTime": "2022-03-30T14:25:26.644857113Z", - "metadata": "AQ==", - "title": "Proposal Title", - "summary": "Proposal Summary" - }, - { - "id": "2", - "messages": [ - {"@type":"/cosmos.bank.v1beta1.MsgSend","amount":[{"denom":"stake","amount":"10"}],"fromAddress":"cosmos1..","toAddress":"cosmos1.."} - ], - "status": "PROPOSAL_STATUS_DEPOSIT_PERIOD", - "finalTallyResult": { - "yesCount": "0", - "abstainCount": "0", - "noCount": "0", - "noWithVetoCount": "0" - }, - "submitTime": "2022-03-28T14:02:41.165025015Z", - "depositEndTime": "2022-03-30T14:02:41.165025015Z", - "totalDeposit": [ - { - "denom": "stake", - "amount": "10" - } - ], - "metadata": "AQ==", - "title": "Proposal Title", - "summary": "Proposal Summary" - } - ], - "pagination": { - "total": "2" - } -} -``` - -#### Vote - -The `Vote` endpoint allows users to query a vote for a given proposal. - -Using legacy v1beta1: - -```bash -cosmos.gov.v1beta1.Query/Vote -``` - -Example: - -```bash -grpcurl -plaintext \ - -d '{"proposal_id":"1","voter":"cosmos1.."}' \ - localhost:9090 \ - cosmos.gov.v1beta1.Query/Vote -``` - -Example Output: - -```bash -{ - "vote": { - "proposalId": "1", - "voter": "cosmos1..", - "option": "VOTE_OPTION_YES", - "options": [ - { - "option": "VOTE_OPTION_YES", - "weight": "1000000000000000000" - } - ] - } -} -``` - -Using v1: - -```bash -cosmos.gov.v1.Query/Vote -``` - -Example: - -```bash -grpcurl -plaintext \ - -d '{"proposal_id":"1","voter":"cosmos1.."}' \ - localhost:9090 \ - cosmos.gov.v1.Query/Vote -``` - -Example Output: - -```bash -{ - "vote": { - "proposalId": "1", - "voter": "cosmos1..", - "option": "VOTE_OPTION_YES", - "options": [ - { - "option": "VOTE_OPTION_YES", - "weight": "1.000000000000000000" - } - ] - } -} -``` - -#### Votes - -The `Votes` endpoint allows users to query all votes for a given proposal. - -Using legacy v1beta1: - -```bash -cosmos.gov.v1beta1.Query/Votes -``` - -Example: - -```bash -grpcurl -plaintext \ - -d '{"proposal_id":"1"}' \ - localhost:9090 \ - cosmos.gov.v1beta1.Query/Votes -``` - -Example Output: - -```bash -{ - "votes": [ - { - "proposalId": "1", - "voter": "cosmos1..", - "options": [ - { - "option": "VOTE_OPTION_YES", - "weight": "1000000000000000000" - } - ] - } - ], - "pagination": { - "total": "1" - } -} -``` - -Using v1: - -```bash -cosmos.gov.v1.Query/Votes -``` - -Example: - -```bash -grpcurl -plaintext \ - -d '{"proposal_id":"1"}' \ - localhost:9090 \ - cosmos.gov.v1.Query/Votes -``` - -Example Output: - -```bash -{ - "votes": [ - { - "proposalId": "1", - "voter": "cosmos1..", - "options": [ - { - "option": "VOTE_OPTION_YES", - "weight": "1.000000000000000000" - } - ] - } - ], - "pagination": { - "total": "1" - } -} -``` - -#### Params - -The `Params` endpoint allows users to query all parameters for the `gov` module. - - - -Using legacy v1beta1: - -```bash -cosmos.gov.v1beta1.Query/Params -``` - -Example: - -```bash -grpcurl -plaintext \ - -d '{"params_type":"voting"}' \ - localhost:9090 \ - cosmos.gov.v1beta1.Query/Params -``` - -Example Output: - -```bash -{ - "votingParams": { - "votingPeriod": "172800s" - }, - "depositParams": { - "maxDepositPeriod": "0s" - }, - "tallyParams": { - "quorum": "MA==", - "threshold": "MA==", - "vetoThreshold": "MA==" - } -} -``` - -Using v1: - -```bash -cosmos.gov.v1.Query/Params -``` - -Example: - -```bash -grpcurl -plaintext \ - -d '{"params_type":"voting"}' \ - localhost:9090 \ - cosmos.gov.v1.Query/Params -``` - -Example Output: - -```bash -{ - "votingParams": { - "votingPeriod": "172800s" - } -} -``` - -#### Deposit - -The `Deposit` endpoint allows users to query a deposit for a given proposal from a given depositor. - -Using legacy v1beta1: - -```bash -cosmos.gov.v1beta1.Query/Deposit -``` - -Example: - -```bash -grpcurl -plaintext \ - '{"proposal_id":"1","depositor":"cosmos1.."}' \ - localhost:9090 \ - cosmos.gov.v1beta1.Query/Deposit -``` - -Example Output: - -```bash -{ - "deposit": { - "proposalId": "1", - "depositor": "cosmos1..", - "amount": [ - { - "denom": "stake", - "amount": "10000000" - } - ] - } -} -``` - -Using v1: - -```bash -cosmos.gov.v1.Query/Deposit -``` - -Example: - -```bash -grpcurl -plaintext \ - '{"proposal_id":"1","depositor":"cosmos1.."}' \ - localhost:9090 \ - cosmos.gov.v1.Query/Deposit -``` - -Example Output: - -```bash -{ - "deposit": { - "proposalId": "1", - "depositor": "cosmos1..", - "amount": [ - { - "denom": "stake", - "amount": "10000000" - } - ] - } -} -``` - -#### deposits - -The `Deposits` endpoint allows users to query all deposits for a given proposal. - -Using legacy v1beta1: - -```bash -cosmos.gov.v1beta1.Query/Deposits -``` - -Example: - -```bash -grpcurl -plaintext \ - -d '{"proposal_id":"1"}' \ - localhost:9090 \ - cosmos.gov.v1beta1.Query/Deposits -``` - -Example Output: - -```bash -{ - "deposits": [ - { - "proposalId": "1", - "depositor": "cosmos1..", - "amount": [ - { - "denom": "stake", - "amount": "10000000" - } - ] - } - ], - "pagination": { - "total": "1" - } -} -``` - -Using v1: - -```bash -cosmos.gov.v1.Query/Deposits -``` - -Example: - -```bash -grpcurl -plaintext \ - -d '{"proposal_id":"1"}' \ - localhost:9090 \ - cosmos.gov.v1.Query/Deposits -``` - -Example Output: - -```bash -{ - "deposits": [ - { - "proposalId": "1", - "depositor": "cosmos1..", - "amount": [ - { - "denom": "stake", - "amount": "10000000" - } - ] - } - ], - "pagination": { - "total": "1" - } -} -``` - -#### TallyResult - -The `TallyResult` endpoint allows users to query the tally of a given proposal. - -Using legacy v1beta1: - -```bash -cosmos.gov.v1beta1.Query/TallyResult -``` - -Example: - -```bash -grpcurl -plaintext \ - -d '{"proposal_id":"1"}' \ - localhost:9090 \ - cosmos.gov.v1beta1.Query/TallyResult -``` - -Example Output: - -```bash -{ - "tally": { - "yes": "1000000", - "abstain": "0", - "no": "0", - "noWithVeto": "0" - } -} -``` - -Using v1: - -```bash -cosmos.gov.v1.Query/TallyResult -``` - -Example: - -```bash -grpcurl -plaintext \ - -d '{"proposal_id":"1"}' \ - localhost:9090 \ - cosmos.gov.v1.Query/TallyResult -``` - -Example Output: - -```bash -{ - "tally": { - "yes": "1000000", - "abstain": "0", - "no": "0", - "noWithVeto": "0" - } -} -``` - -### REST - -A user can query the `gov` module using REST endpoints. - -#### proposal - -The `proposals` endpoint allows users to query a given proposal. - -Using legacy v1beta1: - -```bash -/cosmos/gov/v1beta1/proposals/{proposal_id} -``` - -Example: - -```bash -curl localhost:1317/cosmos/gov/v1beta1/proposals/1 -``` - -Example Output: - -```bash -{ - "proposal": { - "proposal_id": "1", - "content": null, - "status": "PROPOSAL_STATUS_VOTING_PERIOD", - "final_tally_result": { - "yes": "0", - "abstain": "0", - "no": "0", - "no_with_veto": "0" - }, - "submit_time": "2022-03-28T11:50:20.819676256Z", - "deposit_end_time": "2022-03-30T11:50:20.819676256Z", - "total_deposit": [ - { - "denom": "stake", - "amount": "10000000010" - } - ], - "voting_start_time": "2022-03-28T14:25:26.644857113Z", - "voting_end_time": "2022-03-30T14:25:26.644857113Z" - } -} -``` - -Using v1: - -```bash -/cosmos/gov/v1/proposals/{proposal_id} -``` - -Example: - -```bash -curl localhost:1317/cosmos/gov/v1/proposals/1 -``` - -Example Output: - -```bash -{ - "proposal": { - "id": "1", - "messages": [ - { - "@type": "/cosmos.bank.v1beta1.MsgSend", - "from_address": "cosmos1..", - "to_address": "cosmos1..", - "amount": [ - { - "denom": "stake", - "amount": "10" - } - ] - } - ], - "status": "PROPOSAL_STATUS_VOTING_PERIOD", - "final_tally_result": { - "yes_count": "0", - "abstain_count": "0", - "no_count": "0", - "no_with_veto_count": "0" - }, - "submit_time": "2022-03-28T11:50:20.819676256Z", - "deposit_end_time": "2022-03-30T11:50:20.819676256Z", - "total_deposit": [ - { - "denom": "stake", - "amount": "10000000" - } - ], - "voting_start_time": "2022-03-28T14:25:26.644857113Z", - "voting_end_time": "2022-03-30T14:25:26.644857113Z", - "metadata": "AQ==", - "title": "Proposal Title", - "summary": "Proposal Summary" - } -} -``` - -#### proposals - -The `proposals` endpoint also allows users to query all proposals with optional filters. - -Using legacy v1beta1: - -```bash -/cosmos/gov/v1beta1/proposals -``` - -Example: - -```bash -curl localhost:1317/cosmos/gov/v1beta1/proposals -``` - -Example Output: - -```bash -{ - "proposals": [ - { - "proposal_id": "1", - "content": null, - "status": "PROPOSAL_STATUS_VOTING_PERIOD", - "final_tally_result": { - "yes": "0", - "abstain": "0", - "no": "0", - "no_with_veto": "0" - }, - "submit_time": "2022-03-28T11:50:20.819676256Z", - "deposit_end_time": "2022-03-30T11:50:20.819676256Z", - "total_deposit": [ - { - "denom": "stake", - "amount": "10000000" - } - ], - "voting_start_time": "2022-03-28T14:25:26.644857113Z", - "voting_end_time": "2022-03-30T14:25:26.644857113Z" - }, - { - "proposal_id": "2", - "content": null, - "status": "PROPOSAL_STATUS_DEPOSIT_PERIOD", - "final_tally_result": { - "yes": "0", - "abstain": "0", - "no": "0", - "no_with_veto": "0" - }, - "submit_time": "2022-03-28T14:02:41.165025015Z", - "deposit_end_time": "2022-03-30T14:02:41.165025015Z", - "total_deposit": [ - { - "denom": "stake", - "amount": "10" - } - ], - "voting_start_time": "0001-01-01T00:00:00Z", - "voting_end_time": "0001-01-01T00:00:00Z" - } - ], - "pagination": { - "next_key": null, - "total": "2" - } -} -``` - -Using v1: - -```bash -/cosmos/gov/v1/proposals -``` - -Example: - -```bash -curl localhost:1317/cosmos/gov/v1/proposals -``` - -Example Output: - -```bash -{ - "proposals": [ - { - "id": "1", - "messages": [ - { - "@type": "/cosmos.bank.v1beta1.MsgSend", - "from_address": "cosmos1..", - "to_address": "cosmos1..", - "amount": [ - { - "denom": "stake", - "amount": "10" - } - ] - } - ], - "status": "PROPOSAL_STATUS_VOTING_PERIOD", - "final_tally_result": { - "yes_count": "0", - "abstain_count": "0", - "no_count": "0", - "no_with_veto_count": "0" - }, - "submit_time": "2022-03-28T11:50:20.819676256Z", - "deposit_end_time": "2022-03-30T11:50:20.819676256Z", - "total_deposit": [ - { - "denom": "stake", - "amount": "10000000010" - } - ], - "voting_start_time": "2022-03-28T14:25:26.644857113Z", - "voting_end_time": "2022-03-30T14:25:26.644857113Z", - "metadata": "AQ==", - "title": "Proposal Title", - "summary": "Proposal Summary" - }, - { - "id": "2", - "messages": [ - { - "@type": "/cosmos.bank.v1beta1.MsgSend", - "from_address": "cosmos1..", - "to_address": "cosmos1..", - "amount": [ - { - "denom": "stake", - "amount": "10" - } - ] - } - ], - "status": "PROPOSAL_STATUS_DEPOSIT_PERIOD", - "final_tally_result": { - "yes_count": "0", - "abstain_count": "0", - "no_count": "0", - "no_with_veto_count": "0" - }, - "submit_time": "2022-03-28T14:02:41.165025015Z", - "deposit_end_time": "2022-03-30T14:02:41.165025015Z", - "total_deposit": [ - { - "denom": "stake", - "amount": "10" - } - ], - "voting_start_time": null, - "voting_end_time": null, - "metadata": "AQ==", - "title": "Proposal Title", - "summary": "Proposal Summary" - } - ], - "pagination": { - "next_key": null, - "total": "2" - } -} -``` - -#### voter vote - -The `votes` endpoint allows users to query a vote for a given proposal. - -Using legacy v1beta1: - -```bash -/cosmos/gov/v1beta1/proposals/{proposal_id}/votes/{voter} -``` - -Example: - -```bash -curl localhost:1317/cosmos/gov/v1beta1/proposals/1/votes/cosmos1.. -``` - -Example Output: - -```bash -{ - "vote": { - "proposal_id": "1", - "voter": "cosmos1..", - "option": "VOTE_OPTION_YES", - "options": [ - { - "option": "VOTE_OPTION_YES", - "weight": "1.000000000000000000" - } - ] - } -} -``` - -Using v1: - -```bash -/cosmos/gov/v1/proposals/{proposal_id}/votes/{voter} -``` - -Example: - -```bash -curl localhost:1317/cosmos/gov/v1/proposals/1/votes/cosmos1.. -``` - -Example Output: - -```bash -{ - "vote": { - "proposal_id": "1", - "voter": "cosmos1..", - "options": [ - { - "option": "VOTE_OPTION_YES", - "weight": "1.000000000000000000" - } - ], - "metadata": "" - } -} -``` - -#### votes - -The `votes` endpoint allows users to query all votes for a given proposal. - -Using legacy v1beta1: - -```bash -/cosmos/gov/v1beta1/proposals/{proposal_id}/votes -``` - -Example: - -```bash -curl localhost:1317/cosmos/gov/v1beta1/proposals/1/votes -``` - -Example Output: - -```bash -{ - "votes": [ - { - "proposal_id": "1", - "voter": "cosmos1..", - "option": "VOTE_OPTION_YES", - "options": [ - { - "option": "VOTE_OPTION_YES", - "weight": "1.000000000000000000" - } - ] - } - ], - "pagination": { - "next_key": null, - "total": "1" - } -} -``` - -Using v1: - -```bash -/cosmos/gov/v1/proposals/{proposal_id}/votes -``` - -Example: - -```bash -curl localhost:1317/cosmos/gov/v1/proposals/1/votes -``` - -Example Output: - -```bash -{ - "votes": [ - { - "proposal_id": "1", - "voter": "cosmos1..", - "options": [ - { - "option": "VOTE_OPTION_YES", - "weight": "1.000000000000000000" - } - ], - "metadata": "" - } - ], - "pagination": { - "next_key": null, - "total": "1" - } -} -``` - -#### params - -The `params` endpoint allows users to query all parameters for the `gov` module. - - - -Using legacy v1beta1: - -```bash -/cosmos/gov/v1beta1/params/{params_type} -``` - -Example: - -```bash -curl localhost:1317/cosmos/gov/v1beta1/params/voting -``` - -Example Output: - -```bash -{ - "voting_params": { - "voting_period": "172800s" - }, - "deposit_params": { - "min_deposit": [ - ], - "max_deposit_period": "0s" - }, - "tally_params": { - "quorum": "0.000000000000000000", - "threshold": "0.000000000000000000", - "veto_threshold": "0.000000000000000000" - } -} -``` - -Using v1: - -```bash -/cosmos/gov/v1/params/{params_type} -``` - -Example: - -```bash -curl localhost:1317/cosmos/gov/v1/params/voting -``` - -Example Output: - -```bash -{ - "voting_params": { - "voting_period": "172800s" - }, - "deposit_params": { - "min_deposit": [ - ], - "max_deposit_period": "0s" - }, - "tally_params": { - "quorum": "0.000000000000000000", - "threshold": "0.000000000000000000", - "veto_threshold": "0.000000000000000000" - } -} -``` - -#### deposits - -The `deposits` endpoint allows users to query a deposit for a given proposal from a given depositor. - -Using legacy v1beta1: - -```bash -/cosmos/gov/v1beta1/proposals/{proposal_id}/deposits/{depositor} -``` - -Example: - -```bash -curl localhost:1317/cosmos/gov/v1beta1/proposals/1/deposits/cosmos1.. -``` - -Example Output: - -```bash -{ - "deposit": { - "proposal_id": "1", - "depositor": "cosmos1..", - "amount": [ - { - "denom": "stake", - "amount": "10000000" - } - ] - } -} -``` - -Using v1: - -```bash -/cosmos/gov/v1/proposals/{proposal_id}/deposits/{depositor} -``` - -Example: - -```bash -curl localhost:1317/cosmos/gov/v1/proposals/1/deposits/cosmos1.. -``` - -Example Output: - -```bash -{ - "deposit": { - "proposal_id": "1", - "depositor": "cosmos1..", - "amount": [ - { - "denom": "stake", - "amount": "10000000" - } - ] - } -} -``` - -#### proposal deposits - -The `deposits` endpoint allows users to query all deposits for a given proposal. - -Using legacy v1beta1: - -```bash -/cosmos/gov/v1beta1/proposals/{proposal_id}/deposits -``` - -Example: - -```bash -curl localhost:1317/cosmos/gov/v1beta1/proposals/1/deposits -``` - -Example Output: - -```bash -{ - "deposits": [ - { - "proposal_id": "1", - "depositor": "cosmos1..", - "amount": [ - { - "denom": "stake", - "amount": "10000000" - } - ] - } - ], - "pagination": { - "next_key": null, - "total": "1" - } -} -``` - -Using v1: - -```bash -/cosmos/gov/v1/proposals/{proposal_id}/deposits -``` - -Example: - -```bash -curl localhost:1317/cosmos/gov/v1/proposals/1/deposits -``` - -Example Output: - -```bash -{ - "deposits": [ - { - "proposal_id": "1", - "depositor": "cosmos1..", - "amount": [ - { - "denom": "stake", - "amount": "10000000" - } - ] - } - ], - "pagination": { - "next_key": null, - "total": "1" - } -} -``` - -#### tally - -The `tally` endpoint allows users to query the tally of a given proposal. - -Using legacy v1beta1: - -```bash -/cosmos/gov/v1beta1/proposals/{proposal_id}/tally -``` - -Example: - -```bash -curl localhost:1317/cosmos/gov/v1beta1/proposals/1/tally -``` - -Example Output: - -```bash -{ - "tally": { - "yes": "1000000", - "abstain": "0", - "no": "0", - "no_with_veto": "0" - } -} -``` - -Using v1: - -```bash -/cosmos/gov/v1/proposals/{proposal_id}/tally -``` - -Example: - -```bash -curl localhost:1317/cosmos/gov/v1/proposals/1/tally -``` - -Example Output: - -```bash -{ - "tally": { - "yes": "1000000", - "abstain": "0", - "no": "0", - "no_with_veto": "0" - } -} -``` - -## Metadata - -The gov module has two locations for metadata where users can provide further context about the on-chain actions they are taking. By default all metadata fields have a 255 character length field where metadata can be stored in json format, either on-chain or off-chain depending on the amount of data required. Here we provide a recommendation for the json structure and where the data should be stored. There are two important factors in making these recommendations. First, that the gov and group modules are consistent with one another, note the number of proposals made by all groups may be quite large. Second, that client applications such as block explorers and governance interfaces have confidence in the consistency of metadata structure accross chains. - -### Proposal - -Location: off-chain as json object stored on IPFS (mirrors [group proposal](../group/README.md#metadata)) - -```json -{ - "title": "", - "authors": [""], - "summary": "", - "details": "", - "proposal_forum_url": "", - "vote_option_context": "", -} -``` - -:::note -The `authors` field is an array of strings, this is to allow for multiple authors to be listed in the metadata. -In v0.46, the `authors` field is a comma-separated string. Frontends are encouraged to support both formats for backwards compatibility. -::: - -### Vote - -Location: on-chain as json within 255 character limit (mirrors [group vote](../group/README.md#metadata)) - -```json -{ - "justification": "", -} -``` - -## Future Improvements - -The current documentation only describes the minimum viable product for the -governance module. Future improvements may include: - -* **`BountyProposals`:** If accepted, a `BountyProposal` creates an open - bounty. The `BountyProposal` specifies how many Atoms will be given upon - completion. These Atoms will be taken from the `reserve pool`. After a - `BountyProposal` is accepted by governance, anybody can submit a - `SoftwareUpgradeProposal` with the code to claim the bounty. Note that once a - `BountyProposal` is accepted, the corresponding funds in the `reserve pool` - are locked so that payment can always be honored. In order to link a - `SoftwareUpgradeProposal` to an open bounty, the submitter of the - `SoftwareUpgradeProposal` will use the `Proposal.LinkedProposal` attribute. - If a `SoftwareUpgradeProposal` linked to an open bounty is accepted by - governance, the funds that were reserved are automatically transferred to the - submitter. -* **Complex delegation:** Delegators could choose other representatives than - their validators. Ultimately, the chain of representatives would always end - up to a validator, but delegators could inherit the vote of their chosen - representative before they inherit the vote of their validator. In other - words, they would only inherit the vote of their validator if their other - appointed representative did not vote. -* **Better process for proposal review:** There would be two parts to - `proposal.Deposit`, one for anti-spam (same as in MVP) and an other one to - reward third party auditors. diff --git a/.gitbook/developers/modules/core/group/README.md b/.gitbook/developers/modules/core/group/README.md deleted file mode 100644 index 71d91ccb..00000000 --- a/.gitbook/developers/modules/core/group/README.md +++ /dev/null @@ -1,2166 +0,0 @@ ---- -sidebar_position: 1 ---- - -# `x/group` - -## Abstract - -The following documents specify the group module. - -This module allows the creation and management of on-chain multisig accounts and enables voting for message execution based on configurable decision policies. - -## Contents - -* [Concepts](#concepts) - * [Group](#group) - * [Group Policy](#group-policy) - * [Decision Policy](#decision-policy) - * [Proposal](#proposal) - * [Pruning](#pruning) -* [State](#state) - * [Group Table](#group-table) - * [Group Member Table](#group-member-table) - * [Group Policy Table](#group-policy-table) - * [Proposal Table](#proposal-table) - * [Vote Table](#vote-table) -* [Msg Service](#msg-service) - * [Msg/CreateGroup](#msgcreategroup) - * [Msg/UpdateGroupMembers](#msgupdategroupmembers) - * [Msg/UpdateGroupAdmin](#msgupdategroupadmin) - * [Msg/UpdateGroupMetadata](#msgupdategroupmetadata) - * [Msg/CreateGroupPolicy](#msgcreategrouppolicy) - * [Msg/CreateGroupWithPolicy](#msgcreategroupwithpolicy) - * [Msg/UpdateGroupPolicyAdmin](#msgupdategrouppolicyadmin) - * [Msg/UpdateGroupPolicyDecisionPolicy](#msgupdategrouppolicydecisionpolicy) - * [Msg/UpdateGroupPolicyMetadata](#msgupdategrouppolicymetadata) - * [Msg/SubmitProposal](#msgsubmitproposal) - * [Msg/WithdrawProposal](#msgwithdrawproposal) - * [Msg/Vote](#msgvote) - * [Msg/Exec](#msgexec) - * [Msg/LeaveGroup](#msgleavegroup) -* [Events](#events) - * [EventCreateGroup](#eventcreategroup) - * [EventUpdateGroup](#eventupdategroup) - * [EventCreateGroupPolicy](#eventcreategrouppolicy) - * [EventUpdateGroupPolicy](#eventupdategrouppolicy) - * [EventCreateProposal](#eventcreateproposal) - * [EventWithdrawProposal](#eventwithdrawproposal) - * [EventVote](#eventvote) - * [EventExec](#eventexec) - * [EventLeaveGroup](#eventleavegroup) - * [EventProposalPruned](#eventproposalpruned) -* [Client](#client) - * [CLI](#cli) - * [gRPC](#grpc) - * [REST](#rest) -* [Metadata](#metadata) - -## Concepts - -### Group - -A group is simply an aggregation of accounts with associated weights. It is not -an account and doesn't have a balance. It doesn't in and of itself have any -sort of voting or decision weight. It does have an "administrator" which has -the ability to add, remove and update members in the group. Note that a -group policy account could be an administrator of a group, and that the -administrator doesn't necessarily have to be a member of the group. - -### Group Policy - -A group policy is an account associated with a group and a decision policy. -Group policies are abstracted from groups because a single group may have -multiple decision policies for different types of actions. Managing group -membership separately from decision policies results in the least overhead -and keeps membership consistent across different policies. The pattern that -is recommended is to have a single master group policy for a given group, -and then to create separate group policies with different decision policies -and delegate the desired permissions from the master account to -those "sub-accounts" using the `x/authz` module. - -### Decision Policy - -A decision policy is the mechanism by which members of a group can vote on -proposals, as well as the rules that dictate whether a proposal should pass -or not based on its tally outcome. - -All decision policies generally would have a mininum execution period and a -maximum voting window. The minimum execution period is the minimum amount of time -that must pass after submission in order for a proposal to potentially be executed, and it may -be set to 0. The maximum voting window is the maximum time after submission that a proposal may -be voted on before it is tallied. - -The chain developer also defines an app-wide maximum execution period, which is -the maximum amount of time after a proposal's voting period end where users are -allowed to execute a proposal. - -The current group module comes shipped with two decision policies: threshold -and percentage. Any chain developer can extend upon these two, by creating -custom decision policies, as long as they adhere to the `DecisionPolicy` -interface: - -```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/x/group/types.go#L27-L45 -``` - -#### Threshold decision policy - -A threshold decision policy defines a threshold of yes votes (based on a tally -of voter weights) that must be achieved in order for a proposal to pass. For -this decision policy, abstain and veto are simply treated as no's. - -This decision policy also has a VotingPeriod window and a MinExecutionPeriod -window. The former defines the duration after proposal submission where members -are allowed to vote, after which tallying is performed. The latter specifies -the minimum duration after proposal submission where the proposal can be -executed. If set to 0, then the proposal is allowed to be executed immediately -on submission (using the `TRY_EXEC` option). Obviously, MinExecutionPeriod -cannot be greater than VotingPeriod+MaxExecutionPeriod (where MaxExecution is -the app-defined duration that specifies the window after voting ended where a -proposal can be executed). - -#### Percentage decision policy - -A percentage decision policy is similar to a threshold decision policy, except -that the threshold is not defined as a constant weight, but as a percentage. -It's more suited for groups where the group members' weights can be updated, as -the percentage threshold stays the same, and doesn't depend on how those member -weights get updated. - -Same as the Threshold decision policy, the percentage decision policy has the -two VotingPeriod and MinExecutionPeriod parameters. - -### Proposal - -Any member(s) of a group can submit a proposal for a group policy account to decide upon. -A proposal consists of a set of messages that will be executed if the proposal -passes as well as any metadata associated with the proposal. - -#### Voting - -There are four choices to choose while voting - yes, no, abstain and veto. Not -all decision policies will take the four choices into account. Votes can contain some optional metadata. -In the current implementation, the voting window begins as soon as a proposal -is submitted, and the end is defined by the group policy's decision policy. - -#### Withdrawing Proposals - -Proposals can be withdrawn any time before the voting period end, either by the -admin of the group policy or by one of the proposers. Once withdrawn, it is -marked as `PROPOSAL_STATUS_WITHDRAWN`, and no more voting or execution is -allowed on it. - -#### Aborted Proposals - -If the group policy is updated during the voting period of the proposal, then -the proposal is marked as `PROPOSAL_STATUS_ABORTED`, and no more voting or -execution is allowed on it. This is because the group policy defines the rules -of proposal voting and execution, so if those rules change during the lifecycle -of a proposal, then the proposal should be marked as stale. - -#### Tallying - -Tallying is the counting of all votes on a proposal. It happens only once in -the lifecycle of a proposal, but can be triggered by two factors, whichever -happens first: - -* either someone tries to execute the proposal (see next section), which can - happen on a `Msg/Exec` transaction, or a `Msg/{SubmitProposal,Vote}` - transaction with the `Exec` field set. When a proposal execution is attempted, - a tally is done first to make sure the proposal passes. -* or on `EndBlock` when the proposal's voting period end just passed. - -If the tally result passes the decision policy's rules, then the proposal is -marked as `PROPOSAL_STATUS_ACCEPTED`, or else it is marked as -`PROPOSAL_STATUS_REJECTED`. In any case, no more voting is allowed anymore, and the tally -result is persisted to state in the proposal's `FinalTallyResult`. - -#### Executing Proposals - -Proposals are executed only when the tallying is done, and the group account's -decision policy allows the proposal to pass based on the tally outcome. They -are marked by the status `PROPOSAL_STATUS_ACCEPTED`. Execution must happen -before a duration of `MaxExecutionPeriod` (set by the chain developer) after -each proposal's voting period end. - -Proposals will not be automatically executed by the chain in this current design, -but rather a user must submit a `Msg/Exec` transaction to attempt to execute the -proposal based on the current votes and decision policy. Any user (not only the -group members) can execute proposals that have been accepted, and execution fees are -paid by the proposal executor. -It's also possible to try to execute a proposal immediately on creation or on -new votes using the `Exec` field of `Msg/SubmitProposal` and `Msg/Vote` requests. -In the former case, proposers signatures are considered as yes votes. -In these cases, if the proposal can't be executed (i.e. it didn't pass the -decision policy's rules), it will still be opened for new votes and -could be tallied and executed later on. - -A successful proposal execution will have its `ExecutorResult` marked as -`PROPOSAL_EXECUTOR_RESULT_SUCCESS`. The proposal will be automatically pruned -after execution. On the other hand, a failed proposal execution will be marked -as `PROPOSAL_EXECUTOR_RESULT_FAILURE`. Such a proposal can be re-executed -multiple times, until it expires after `MaxExecutionPeriod` after voting period -end. - -### Pruning - -Proposals and votes are automatically pruned to avoid state bloat. - -Votes are pruned: - -* either after a successful tally, i.e. a tally whose result passes the decision - policy's rules, which can be trigged by a `Msg/Exec` or a - `Msg/{SubmitProposal,Vote}` with the `Exec` field set, -* or on `EndBlock` right after the proposal's voting period end. This applies to proposals with status `aborted` or `withdrawn` too. - -whichever happens first. - -Proposals are pruned: - -* on `EndBlock` whose proposal status is `withdrawn` or `aborted` on proposal's voting period end before tallying, -* and either after a successful proposal execution, -* or on `EndBlock` right after the proposal's `voting_period_end` + - `max_execution_period` (defined as an app-wide configuration) is passed, - -whichever happens first. - -## State - -The `group` module uses the `orm` package which provides table storage with support for -primary keys and secondary indexes. `orm` also defines `Sequence` which is a persistent unique key generator based on a counter that can be used along with `Table`s. - -Here's the list of tables and associated sequences and indexes stored as part of the `group` module. - -### Group Table - -The `groupTable` stores `GroupInfo`: `0x0 | BigEndian(GroupId) -> ProtocolBuffer(GroupInfo)`. - -#### groupSeq - -The value of `groupSeq` is incremented when creating a new group and corresponds to the new `GroupId`: `0x1 | 0x1 -> BigEndian`. - -The second `0x1` corresponds to the ORM `sequenceStorageKey`. - -#### groupByAdminIndex - -`groupByAdminIndex` allows to retrieve groups by admin address: -`0x2 | len([]byte(group.Admin)) | []byte(group.Admin) | BigEndian(GroupId) -> []byte()`. - -### Group Member Table - -The `groupMemberTable` stores `GroupMember`s: `0x10 | BigEndian(GroupId) | []byte(member.Address) -> ProtocolBuffer(GroupMember)`. - -The `groupMemberTable` is a primary key table and its `PrimaryKey` is given by -`BigEndian(GroupId) | []byte(member.Address)` which is used by the following indexes. - -#### groupMemberByGroupIndex - -`groupMemberByGroupIndex` allows to retrieve group members by group id: -`0x11 | BigEndian(GroupId) | PrimaryKey -> []byte()`. - -#### groupMemberByMemberIndex - -`groupMemberByMemberIndex` allows to retrieve group members by member address: -`0x12 | len([]byte(member.Address)) | []byte(member.Address) | PrimaryKey -> []byte()`. - -### Group Policy Table - -The `groupPolicyTable` stores `GroupPolicyInfo`: `0x20 | len([]byte(Address)) | []byte(Address) -> ProtocolBuffer(GroupPolicyInfo)`. - -The `groupPolicyTable` is a primary key table and its `PrimaryKey` is given by -`len([]byte(Address)) | []byte(Address)` which is used by the following indexes. - -#### groupPolicySeq - -The value of `groupPolicySeq` is incremented when creating a new group policy and is used to generate the new group policy account `Address`: -`0x21 | 0x1 -> BigEndian`. - -The second `0x1` corresponds to the ORM `sequenceStorageKey`. - -#### groupPolicyByGroupIndex - -`groupPolicyByGroupIndex` allows to retrieve group policies by group id: -`0x22 | BigEndian(GroupId) | PrimaryKey -> []byte()`. - -#### groupPolicyByAdminIndex - -`groupPolicyByAdminIndex` allows to retrieve group policies by admin address: -`0x23 | len([]byte(Address)) | []byte(Address) | PrimaryKey -> []byte()`. - -### Proposal Table - -The `proposalTable` stores `Proposal`s: `0x30 | BigEndian(ProposalId) -> ProtocolBuffer(Proposal)`. - -#### proposalSeq - -The value of `proposalSeq` is incremented when creating a new proposal and corresponds to the new `ProposalId`: `0x31 | 0x1 -> BigEndian`. - -The second `0x1` corresponds to the ORM `sequenceStorageKey`. - -#### proposalByGroupPolicyIndex - -`proposalByGroupPolicyIndex` allows to retrieve proposals by group policy account address: -`0x32 | len([]byte(account.Address)) | []byte(account.Address) | BigEndian(ProposalId) -> []byte()`. - -#### ProposalsByVotingPeriodEndIndex - -`proposalsByVotingPeriodEndIndex` allows to retrieve proposals sorted by chronological `voting_period_end`: -`0x33 | sdk.FormatTimeBytes(proposal.VotingPeriodEnd) | BigEndian(ProposalId) -> []byte()`. - -This index is used when tallying the proposal votes at the end of the voting period, and for pruning proposals at `VotingPeriodEnd + MaxExecutionPeriod`. - -### Vote Table - -The `voteTable` stores `Vote`s: `0x40 | BigEndian(ProposalId) | []byte(voter.Address) -> ProtocolBuffer(Vote)`. - -The `voteTable` is a primary key table and its `PrimaryKey` is given by -`BigEndian(ProposalId) | []byte(voter.Address)` which is used by the following indexes. - -#### voteByProposalIndex - -`voteByProposalIndex` allows to retrieve votes by proposal id: -`0x41 | BigEndian(ProposalId) | PrimaryKey -> []byte()`. - -#### voteByVoterIndex - -`voteByVoterIndex` allows to retrieve votes by voter address: -`0x42 | len([]byte(voter.Address)) | []byte(voter.Address) | PrimaryKey -> []byte()`. - -## Msg Service - -### Msg/CreateGroup - -A new group can be created with the `MsgCreateGroup`, which has an admin address, a list of members and some optional metadata. - -The metadata has a maximum length that is chosen by the app developer, and -passed into the group keeper as a config. - -```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/group/v1/tx.proto#L67-L80 -``` - -It's expected to fail if - -* metadata length is greater than `MaxMetadataLen` config -* members are not correctly set (e.g. wrong address format, duplicates, or with 0 weight). - -### Msg/UpdateGroupMembers - -Group members can be updated with the `UpdateGroupMembers`. - -```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/group/v1/tx.proto#L88-L102 -``` - -In the list of `MemberUpdates`, an existing member can be removed by setting its weight to 0. - -It's expected to fail if: - -* the signer is not the admin of the group. -* for any one of the associated group policies, if its decision policy's `Validate()` method fails against the updated group. - -### Msg/UpdateGroupAdmin - -The `UpdateGroupAdmin` can be used to update a group admin. - -```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/group/v1/tx.proto#L107-L120 -``` - -It's expected to fail if the signer is not the admin of the group. - -### Msg/UpdateGroupMetadata - -The `UpdateGroupMetadata` can be used to update a group metadata. - -```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/group/v1/tx.proto#L125-L138 -``` - -It's expected to fail if: - -* new metadata length is greater than `MaxMetadataLen` config. -* the signer is not the admin of the group. - -### Msg/CreateGroupPolicy - -A new group policy can be created with the `MsgCreateGroupPolicy`, which has an admin address, a group id, a decision policy and some optional metadata. - -```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/group/v1/tx.proto#L147-L165 -``` - -It's expected to fail if: - -* the signer is not the admin of the group. -* metadata length is greater than `MaxMetadataLen` config. -* the decision policy's `Validate()` method doesn't pass against the group. - -### Msg/CreateGroupWithPolicy - -A new group with policy can be created with the `MsgCreateGroupWithPolicy`, which has an admin address, a list of members, a decision policy, a `group_policy_as_admin` field to optionally set group and group policy admin with group policy address and some optional metadata for group and group policy. - -```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/group/v1/tx.proto#L191-L215 -``` - -It's expected to fail for the same reasons as `Msg/CreateGroup` and `Msg/CreateGroupPolicy`. - -### Msg/UpdateGroupPolicyAdmin - -The `UpdateGroupPolicyAdmin` can be used to update a group policy admin. - -```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/group/v1/tx.proto#L173-L186 -``` - -It's expected to fail if the signer is not the admin of the group policy. - -### Msg/UpdateGroupPolicyDecisionPolicy - -The `UpdateGroupPolicyDecisionPolicy` can be used to update a decision policy. - -```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/group/v1/tx.proto#L226-L241 -``` - -It's expected to fail if: - -* the signer is not the admin of the group policy. -* the new decision policy's `Validate()` method doesn't pass against the group. - -### Msg/UpdateGroupPolicyMetadata - -The `UpdateGroupPolicyMetadata` can be used to update a group policy metadata. - -```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/group/v1/tx.proto#L246-L259 -``` - -It's expected to fail if: - -* new metadata length is greater than `MaxMetadataLen` config. -* the signer is not the admin of the group. - -### Msg/SubmitProposal - -A new proposal can be created with the `MsgSubmitProposal`, which has a group policy account address, a list of proposers addresses, a list of messages to execute if the proposal is accepted and some optional metadata. -An optional `Exec` value can be provided to try to execute the proposal immediately after proposal creation. Proposers signatures are considered as yes votes in this case. - -```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/group/v1/tx.proto#L281-L315 -``` - -It's expected to fail if: - -* metadata, title, or summary length is greater than `MaxMetadataLen` config. -* if any of the proposers is not a group member. - -### Msg/WithdrawProposal - -A proposal can be withdrawn using `MsgWithdrawProposal` which has an `address` (can be either a proposer or the group policy admin) and a `proposal_id` (which has to be withdrawn). - -```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/group/v1/tx.proto#L323-L333 -``` - -It's expected to fail if: - -* the signer is neither the group policy admin nor proposer of the proposal. -* the proposal is already closed or aborted. - -### Msg/Vote - -A new vote can be created with the `MsgVote`, given a proposal id, a voter address, a choice (yes, no, veto or abstain) and some optional metadata. -An optional `Exec` value can be provided to try to execute the proposal immediately after voting. - -```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/group/v1/tx.proto#L338-L358 -``` - -It's expected to fail if: - -* metadata length is greater than `MaxMetadataLen` config. -* the proposal is not in voting period anymore. - -### Msg/Exec - -A proposal can be executed with the `MsgExec`. - -```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/group/v1/tx.proto#L363-L373 -``` - -The messages that are part of this proposal won't be executed if: - -* the proposal has not been accepted by the group policy. -* the proposal has already been successfully executed. - -### Msg/LeaveGroup - -The `MsgLeaveGroup` allows group member to leave a group. - -```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/group/v1/tx.proto#L381-L391 -``` - -It's expected to fail if: - -* the group member is not part of the group. -* for any one of the associated group policies, if its decision policy's `Validate()` method fails against the updated group. - -## Events - -The group module emits the following events: - -### EventCreateGroup - -| Type | Attribute Key | Attribute Value | -| -------------------------------- | ------------- | -------------------------------- | -| message | action | /cosmos.group.v1.Msg/CreateGroup | -| cosmos.group.v1.EventCreateGroup | group_id | {groupId} | - -### EventUpdateGroup - -| Type | Attribute Key | Attribute Value | -| -------------------------------- | ------------- | ---------------------------------------------------------- | -| message | action | /cosmos.group.v1.Msg/UpdateGroup{Admin\|Metadata\|Members} | -| cosmos.group.v1.EventUpdateGroup | group_id | {groupId} | - -### EventCreateGroupPolicy - -| Type | Attribute Key | Attribute Value | -| -------------------------------------- | ------------- | -------------------------------------- | -| message | action | /cosmos.group.v1.Msg/CreateGroupPolicy | -| cosmos.group.v1.EventCreateGroupPolicy | address | {groupPolicyAddress} | - -### EventUpdateGroupPolicy - -| Type | Attribute Key | Attribute Value | -| -------------------------------------- | ------------- | ----------------------------------------------------------------------- | -| message | action | /cosmos.group.v1.Msg/UpdateGroupPolicy{Admin\|Metadata\|DecisionPolicy} | -| cosmos.group.v1.EventUpdateGroupPolicy | address | {groupPolicyAddress} | - -### EventCreateProposal - -| Type | Attribute Key | Attribute Value | -| ----------------------------------- | ------------- | ----------------------------------- | -| message | action | /cosmos.group.v1.Msg/CreateProposal | -| cosmos.group.v1.EventCreateProposal | proposal_id | {proposalId} | - -### EventWithdrawProposal - -| Type | Attribute Key | Attribute Value | -| ------------------------------------- | ------------- | ------------------------------------- | -| message | action | /cosmos.group.v1.Msg/WithdrawProposal | -| cosmos.group.v1.EventWithdrawProposal | proposal_id | {proposalId} | - -### EventVote - -| Type | Attribute Key | Attribute Value | -| ------------------------- | ------------- | ------------------------- | -| message | action | /cosmos.group.v1.Msg/Vote | -| cosmos.group.v1.EventVote | proposal_id | {proposalId} | - -## EventExec - -| Type | Attribute Key | Attribute Value | -| ------------------------- | ------------- | ------------------------- | -| message | action | /cosmos.group.v1.Msg/Exec | -| cosmos.group.v1.EventExec | proposal_id | {proposalId} | -| cosmos.group.v1.EventExec | logs | {logs_string} | - -### EventLeaveGroup - -| Type | Attribute Key | Attribute Value | -| ------------------------------- | ------------- | ------------------------------- | -| message | action | /cosmos.group.v1.Msg/LeaveGroup | -| cosmos.group.v1.EventLeaveGroup | proposal_id | {proposalId} | -| cosmos.group.v1.EventLeaveGroup | address | {address} | - -### EventProposalPruned - -| Type | Attribute Key | Attribute Value | -|-------------------------------------|---------------|---------------------------------| -| message | action | /cosmos.group.v1.Msg/LeaveGroup | -| cosmos.group.v1.EventProposalPruned | proposal_id | {proposalId} | -| cosmos.group.v1.EventProposalPruned | status | {ProposalStatus} | -| cosmos.group.v1.EventProposalPruned | tally_result | {TallyResult} | - - -## Client - -### CLI - -A user can query and interact with the `group` module using the CLI. - -#### Query - -The `query` commands allow users to query `group` state. - -```bash -simd query group --help -``` - -##### group-info - -The `group-info` command allows users to query for group info by given group id. - -```bash -simd query group group-info [id] [flags] -``` - -Example: - -```bash -simd query group group-info 1 -``` - -Example Output: - -```bash -admin: cosmos1.. -group_id: "1" -metadata: AQ== -total_weight: "3" -version: "1" -``` - -##### group-policy-info - -The `group-policy-info` command allows users to query for group policy info by account address of group policy . - -```bash -simd query group group-policy-info [group-policy-account] [flags] -``` - -Example: - -```bash -simd query group group-policy-info cosmos1.. -``` - -Example Output: - -```bash -address: cosmos1.. -admin: cosmos1.. -decision_policy: - '@type': /cosmos.group.v1.ThresholdDecisionPolicy - threshold: "1" - windows: - min_execution_period: 0s - voting_period: 432000s -group_id: "1" -metadata: AQ== -version: "1" -``` - -##### group-members - -The `group-members` command allows users to query for group members by group id with pagination flags. - -```bash -simd query group group-members [id] [flags] -``` - -Example: - -```bash -simd query group group-members 1 -``` - -Example Output: - -```bash -members: -- group_id: "1" - member: - address: cosmos1.. - metadata: AQ== - weight: "2" -- group_id: "1" - member: - address: cosmos1.. - metadata: AQ== - weight: "1" -pagination: - next_key: null - total: "2" -``` - -##### groups-by-admin - -The `groups-by-admin` command allows users to query for groups by admin account address with pagination flags. - -```bash -simd query group groups-by-admin [admin] [flags] -``` - -Example: - -```bash -simd query group groups-by-admin cosmos1.. -``` - -Example Output: - -```bash -groups: -- admin: cosmos1.. - group_id: "1" - metadata: AQ== - total_weight: "3" - version: "1" -- admin: cosmos1.. - group_id: "2" - metadata: AQ== - total_weight: "3" - version: "1" -pagination: - next_key: null - total: "2" -``` - -##### group-policies-by-group - -The `group-policies-by-group` command allows users to query for group policies by group id with pagination flags. - -```bash -simd query group group-policies-by-group [group-id] [flags] -``` - -Example: - -```bash -simd query group group-policies-by-group 1 -``` - -Example Output: - -```bash -group_policies: -- address: cosmos1.. - admin: cosmos1.. - decision_policy: - '@type': /cosmos.group.v1.ThresholdDecisionPolicy - threshold: "1" - windows: - min_execution_period: 0s - voting_period: 432000s - group_id: "1" - metadata: AQ== - version: "1" -- address: cosmos1.. - admin: cosmos1.. - decision_policy: - '@type': /cosmos.group.v1.ThresholdDecisionPolicy - threshold: "1" - windows: - min_execution_period: 0s - voting_period: 432000s - group_id: "1" - metadata: AQ== - version: "1" -pagination: - next_key: null - total: "2" -``` - -##### group-policies-by-admin - -The `group-policies-by-admin` command allows users to query for group policies by admin account address with pagination flags. - -```bash -simd query group group-policies-by-admin [admin] [flags] -``` - -Example: - -```bash -simd query group group-policies-by-admin cosmos1.. -``` - -Example Output: - -```bash -group_policies: -- address: cosmos1.. - admin: cosmos1.. - decision_policy: - '@type': /cosmos.group.v1.ThresholdDecisionPolicy - threshold: "1" - windows: - min_execution_period: 0s - voting_period: 432000s - group_id: "1" - metadata: AQ== - version: "1" -- address: cosmos1.. - admin: cosmos1.. - decision_policy: - '@type': /cosmos.group.v1.ThresholdDecisionPolicy - threshold: "1" - windows: - min_execution_period: 0s - voting_period: 432000s - group_id: "1" - metadata: AQ== - version: "1" -pagination: - next_key: null - total: "2" -``` - -##### proposal - -The `proposal` command allows users to query for proposal by id. - -```bash -simd query group proposal [id] [flags] -``` - -Example: - -```bash -simd query group proposal 1 -``` - -Example Output: - -```bash -proposal: - address: cosmos1.. - executor_result: EXECUTOR_RESULT_NOT_RUN - group_policy_version: "1" - group_version: "1" - metadata: AQ== - msgs: - - '@type': /cosmos.bank.v1beta1.MsgSend - amount: - - amount: "100000000" - denom: stake - from_address: cosmos1.. - to_address: cosmos1.. - proposal_id: "1" - proposers: - - cosmos1.. - result: RESULT_UNFINALIZED - status: STATUS_SUBMITTED - submitted_at: "2021-12-17T07:06:26.310638964Z" - windows: - min_execution_period: 0s - voting_period: 432000s - vote_state: - abstain_count: "0" - no_count: "0" - veto_count: "0" - yes_count: "0" - summary: "Summary" - title: "Title" -``` - -##### proposals-by-group-policy - -The `proposals-by-group-policy` command allows users to query for proposals by account address of group policy with pagination flags. - -```bash -simd query group proposals-by-group-policy [group-policy-account] [flags] -``` - -Example: - -```bash -simd query group proposals-by-group-policy cosmos1.. -``` - -Example Output: - -```bash -pagination: - next_key: null - total: "1" -proposals: -- address: cosmos1.. - executor_result: EXECUTOR_RESULT_NOT_RUN - group_policy_version: "1" - group_version: "1" - metadata: AQ== - msgs: - - '@type': /cosmos.bank.v1beta1.MsgSend - amount: - - amount: "100000000" - denom: stake - from_address: cosmos1.. - to_address: cosmos1.. - proposal_id: "1" - proposers: - - cosmos1.. - result: RESULT_UNFINALIZED - status: STATUS_SUBMITTED - submitted_at: "2021-12-17T07:06:26.310638964Z" - windows: - min_execution_period: 0s - voting_period: 432000s - vote_state: - abstain_count: "0" - no_count: "0" - veto_count: "0" - yes_count: "0" - summary: "Summary" - title: "Title" -``` - -##### vote - -The `vote` command allows users to query for vote by proposal id and voter account address. - -```bash -simd query group vote [proposal-id] [voter] [flags] -``` - -Example: - -```bash -simd query group vote 1 cosmos1.. -``` - -Example Output: - -```bash -vote: - choice: CHOICE_YES - metadata: AQ== - proposal_id: "1" - submitted_at: "2021-12-17T08:05:02.490164009Z" - voter: cosmos1.. -``` - -##### votes-by-proposal - -The `votes-by-proposal` command allows users to query for votes by proposal id with pagination flags. - -```bash -simd query group votes-by-proposal [proposal-id] [flags] -``` - -Example: - -```bash -simd query group votes-by-proposal 1 -``` - -Example Output: - -```bash -pagination: - next_key: null - total: "1" -votes: -- choice: CHOICE_YES - metadata: AQ== - proposal_id: "1" - submitted_at: "2021-12-17T08:05:02.490164009Z" - voter: cosmos1.. -``` - -##### votes-by-voter - -The `votes-by-voter` command allows users to query for votes by voter account address with pagination flags. - -```bash -simd query group votes-by-voter [voter] [flags] -``` - -Example: - -```bash -simd query group votes-by-voter cosmos1.. -``` - -Example Output: - -```bash -pagination: - next_key: null - total: "1" -votes: -- choice: CHOICE_YES - metadata: AQ== - proposal_id: "1" - submitted_at: "2021-12-17T08:05:02.490164009Z" - voter: cosmos1.. -``` - -### Transactions - -The `tx` commands allow users to interact with the `group` module. - -```bash -simd tx group --help -``` - -#### create-group - -The `create-group` command allows users to create a group which is an aggregation of member accounts with associated weights and -an administrator account. - -```bash -simd tx group create-group [admin] [metadata] [members-json-file] -``` - -Example: - -```bash -simd tx group create-group cosmos1.. "AQ==" members.json -``` - -#### update-group-admin - -The `update-group-admin` command allows users to update a group's admin. - -```bash -simd tx group update-group-admin [admin] [group-id] [new-admin] [flags] -``` - -Example: - -```bash -simd tx group update-group-admin cosmos1.. 1 cosmos1.. -``` - -#### update-group-members - -The `update-group-members` command allows users to update a group's members. - -```bash -simd tx group update-group-members [admin] [group-id] [members-json-file] [flags] -``` - -Example: - -```bash -simd tx group update-group-members cosmos1.. 1 members.json -``` - -#### update-group-metadata - -The `update-group-metadata` command allows users to update a group's metadata. - -```bash -simd tx group update-group-metadata [admin] [group-id] [metadata] [flags] -``` - -Example: - -```bash -simd tx group update-group-metadata cosmos1.. 1 "AQ==" -``` - -#### create-group-policy - -The `create-group-policy` command allows users to create a group policy which is an account associated with a group and a decision policy. - -```bash -simd tx group create-group-policy [admin] [group-id] [metadata] [decision-policy] [flags] -``` - -Example: - -```bash -simd tx group create-group-policy cosmos1.. 1 "AQ==" '{"@type":"/cosmos.group.v1.ThresholdDecisionPolicy", "threshold":"1", "windows": {"voting_period": "120h", "min_execution_period": "0s"}}' -``` - -#### create-group-with-policy - -The `create-group-with-policy` command allows users to create a group which is an aggregation of member accounts with associated weights and an administrator account with decision policy. If the `--group-policy-as-admin` flag is set to `true`, the group policy address becomes the group and group policy admin. - -```bash -simd tx group create-group-with-policy [admin] [group-metadata] [group-policy-metadata] [members-json-file] [decision-policy] [flags] -``` - -Example: - -```bash -simd tx group create-group-with-policy cosmos1.. "AQ==" "AQ==" members.json '{"@type":"/cosmos.group.v1.ThresholdDecisionPolicy", "threshold":"1", "windows": {"voting_period": "120h", "min_execution_period": "0s"}}' -``` - -#### update-group-policy-admin - -The `update-group-policy-admin` command allows users to update a group policy admin. - -```bash -simd tx group update-group-policy-admin [admin] [group-policy-account] [new-admin] [flags] -``` - -Example: - -```bash -simd tx group update-group-policy-admin cosmos1.. cosmos1.. cosmos1.. -``` - -#### update-group-policy-metadata - -The `update-group-policy-metadata` command allows users to update a group policy metadata. - -```bash -simd tx group update-group-policy-metadata [admin] [group-policy-account] [new-metadata] [flags] -``` - -Example: - -```bash -simd tx group update-group-policy-metadata cosmos1.. cosmos1.. "AQ==" -``` - -#### update-group-policy-decision-policy - -The `update-group-policy-decision-policy` command allows users to update a group policy's decision policy. - -```bash -simd tx group update-group-policy-decision-policy [admin] [group-policy-account] [decision-policy] [flags] -``` - -Example: - -```bash -simd tx group update-group-policy-decision-policy cosmos1.. cosmos1.. '{"@type":"/cosmos.group.v1.ThresholdDecisionPolicy", "threshold":"2", "windows": {"voting_period": "120h", "min_execution_period": "0s"}}' -``` - -#### submit-proposal - -The `submit-proposal` command allows users to submit a new proposal. - -```bash -simd tx group submit-proposal [group-policy-account] [proposer[,proposer]*] [msg_tx_json_file] [metadata] [flags] -``` - -Example: - -```bash -simd tx group submit-proposal cosmos1.. cosmos1.. msg_tx.json "AQ==" -``` - -#### withdraw-proposal - -The `withdraw-proposal` command allows users to withdraw a proposal. - -```bash -simd tx group withdraw-proposal [proposal-id] [group-policy-admin-or-proposer] -``` - -Example: - -```bash -simd tx group withdraw-proposal 1 cosmos1.. -``` - -#### vote - -The `vote` command allows users to vote on a proposal. - -```bash -simd tx group vote proposal-id] [voter] [choice] [metadata] [flags] -``` - -Example: - -```bash -simd tx group vote 1 cosmos1.. CHOICE_YES "AQ==" -``` - -#### exec - -The `exec` command allows users to execute a proposal. - -```bash -simd tx group exec [proposal-id] [flags] -``` - -Example: - -```bash -simd tx group exec 1 -``` - -#### leave-group - -The `leave-group` command allows group member to leave the group. - -```bash -simd tx group leave-group [member-address] [group-id] -``` - -Example: - -```bash -simd tx group leave-group cosmos1... 1 -``` - -### gRPC - -A user can query the `group` module using gRPC endpoints. - -#### GroupInfo - -The `GroupInfo` endpoint allows users to query for group info by given group id. - -```bash -cosmos.group.v1.Query/GroupInfo -``` - -Example: - -```bash -grpcurl -plaintext \ - -d '{"group_id":1}' localhost:9090 cosmos.group.v1.Query/GroupInfo -``` - -Example Output: - -```bash -{ - "info": { - "groupId": "1", - "admin": "cosmos1..", - "metadata": "AQ==", - "version": "1", - "totalWeight": "3" - } -} -``` - -#### GroupPolicyInfo - -The `GroupPolicyInfo` endpoint allows users to query for group policy info by account address of group policy. - -```bash -cosmos.group.v1.Query/GroupPolicyInfo -``` - -Example: - -```bash -grpcurl -plaintext \ - -d '{"address":"cosmos1.."}' localhost:9090 cosmos.group.v1.Query/GroupPolicyInfo -``` - -Example Output: - -```bash -{ - "info": { - "address": "cosmos1..", - "groupId": "1", - "admin": "cosmos1..", - "version": "1", - "decisionPolicy": {"@type":"/cosmos.group.v1.ThresholdDecisionPolicy","threshold":"1","windows": {"voting_period": "120h", "min_execution_period": "0s"}}, - } -} -``` - -#### GroupMembers - -The `GroupMembers` endpoint allows users to query for group members by group id with pagination flags. - -```bash -cosmos.group.v1.Query/GroupMembers -``` - -Example: - -```bash -grpcurl -plaintext \ - -d '{"group_id":"1"}' localhost:9090 cosmos.group.v1.Query/GroupMembers -``` - -Example Output: - -```bash -{ - "members": [ - { - "groupId": "1", - "member": { - "address": "cosmos1..", - "weight": "1" - } - }, - { - "groupId": "1", - "member": { - "address": "cosmos1..", - "weight": "2" - } - } - ], - "pagination": { - "total": "2" - } -} -``` - -#### GroupsByAdmin - -The `GroupsByAdmin` endpoint allows users to query for groups by admin account address with pagination flags. - -```bash -cosmos.group.v1.Query/GroupsByAdmin -``` - -Example: - -```bash -grpcurl -plaintext \ - -d '{"admin":"cosmos1.."}' localhost:9090 cosmos.group.v1.Query/GroupsByAdmin -``` - -Example Output: - -```bash -{ - "groups": [ - { - "groupId": "1", - "admin": "cosmos1..", - "metadata": "AQ==", - "version": "1", - "totalWeight": "3" - }, - { - "groupId": "2", - "admin": "cosmos1..", - "metadata": "AQ==", - "version": "1", - "totalWeight": "3" - } - ], - "pagination": { - "total": "2" - } -} -``` - -#### GroupPoliciesByGroup - -The `GroupPoliciesByGroup` endpoint allows users to query for group policies by group id with pagination flags. - -```bash -cosmos.group.v1.Query/GroupPoliciesByGroup -``` - -Example: - -```bash -grpcurl -plaintext \ - -d '{"group_id":"1"}' localhost:9090 cosmos.group.v1.Query/GroupPoliciesByGroup -``` - -Example Output: - -```bash -{ - "GroupPolicies": [ - { - "address": "cosmos1..", - "groupId": "1", - "admin": "cosmos1..", - "version": "1", - "decisionPolicy": {"@type":"/cosmos.group.v1.ThresholdDecisionPolicy","threshold":"1","windows":{"voting_period": "120h", "min_execution_period": "0s"}}, - }, - { - "address": "cosmos1..", - "groupId": "1", - "admin": "cosmos1..", - "version": "1", - "decisionPolicy": {"@type":"/cosmos.group.v1.ThresholdDecisionPolicy","threshold":"1","windows":{"voting_period": "120h", "min_execution_period": "0s"}}, - } - ], - "pagination": { - "total": "2" - } -} -``` - -#### GroupPoliciesByAdmin - -The `GroupPoliciesByAdmin` endpoint allows users to query for group policies by admin account address with pagination flags. - -```bash -cosmos.group.v1.Query/GroupPoliciesByAdmin -``` - -Example: - -```bash -grpcurl -plaintext \ - -d '{"admin":"cosmos1.."}' localhost:9090 cosmos.group.v1.Query/GroupPoliciesByAdmin -``` - -Example Output: - -```bash -{ - "GroupPolicies": [ - { - "address": "cosmos1..", - "groupId": "1", - "admin": "cosmos1..", - "version": "1", - "decisionPolicy": {"@type":"/cosmos.group.v1.ThresholdDecisionPolicy","threshold":"1","windows":{"voting_period": "120h", "min_execution_period": "0s"}}, - }, - { - "address": "cosmos1..", - "groupId": "1", - "admin": "cosmos1..", - "version": "1", - "decisionPolicy": {"@type":"/cosmos.group.v1.ThresholdDecisionPolicy","threshold":"1","windows":{"voting_period": "120h", "min_execution_period": "0s"}}, - } - ], - "pagination": { - "total": "2" - } -} -``` - -#### Proposal - -The `Proposal` endpoint allows users to query for proposal by id. - -```bash -cosmos.group.v1.Query/Proposal -``` - -Example: - -```bash -grpcurl -plaintext \ - -d '{"proposal_id":"1"}' localhost:9090 cosmos.group.v1.Query/Proposal -``` - -Example Output: - -```bash -{ - "proposal": { - "proposalId": "1", - "address": "cosmos1..", - "proposers": [ - "cosmos1.." - ], - "submittedAt": "2021-12-17T07:06:26.310638964Z", - "groupVersion": "1", - "GroupPolicyVersion": "1", - "status": "STATUS_SUBMITTED", - "result": "RESULT_UNFINALIZED", - "voteState": { - "yesCount": "0", - "noCount": "0", - "abstainCount": "0", - "vetoCount": "0" - }, - "windows": { - "min_execution_period": "0s", - "voting_period": "432000s" - }, - "executorResult": "EXECUTOR_RESULT_NOT_RUN", - "messages": [ - {"@type":"/cosmos.bank.v1beta1.MsgSend","amount":[{"denom":"stake","amount":"100000000"}],"fromAddress":"cosmos1..","toAddress":"cosmos1.."} - ], - "title": "Title", - "summary": "Summary", - } -} -``` - -#### ProposalsByGroupPolicy - -The `ProposalsByGroupPolicy` endpoint allows users to query for proposals by account address of group policy with pagination flags. - -```bash -cosmos.group.v1.Query/ProposalsByGroupPolicy -``` - -Example: - -```bash -grpcurl -plaintext \ - -d '{"address":"cosmos1.."}' localhost:9090 cosmos.group.v1.Query/ProposalsByGroupPolicy -``` - -Example Output: - -```bash -{ - "proposals": [ - { - "proposalId": "1", - "address": "cosmos1..", - "proposers": [ - "cosmos1.." - ], - "submittedAt": "2021-12-17T08:03:27.099649352Z", - "groupVersion": "1", - "GroupPolicyVersion": "1", - "status": "STATUS_CLOSED", - "result": "RESULT_ACCEPTED", - "voteState": { - "yesCount": "1", - "noCount": "0", - "abstainCount": "0", - "vetoCount": "0" - }, - "windows": { - "min_execution_period": "0s", - "voting_period": "432000s" - }, - "executorResult": "EXECUTOR_RESULT_NOT_RUN", - "messages": [ - {"@type":"/cosmos.bank.v1beta1.MsgSend","amount":[{"denom":"stake","amount":"100000000"}],"fromAddress":"cosmos1..","toAddress":"cosmos1.."} - ], - "title": "Title", - "summary": "Summary", - } - ], - "pagination": { - "total": "1" - } -} -``` - -#### VoteByProposalVoter - -The `VoteByProposalVoter` endpoint allows users to query for vote by proposal id and voter account address. - -```bash -cosmos.group.v1.Query/VoteByProposalVoter -``` - -Example: - -```bash -grpcurl -plaintext \ - -d '{"proposal_id":"1","voter":"cosmos1.."}' localhost:9090 cosmos.group.v1.Query/VoteByProposalVoter -``` - -Example Output: - -```bash -{ - "vote": { - "proposalId": "1", - "voter": "cosmos1..", - "choice": "CHOICE_YES", - "submittedAt": "2021-12-17T08:05:02.490164009Z" - } -} -``` - -#### VotesByProposal - -The `VotesByProposal` endpoint allows users to query for votes by proposal id with pagination flags. - -```bash -cosmos.group.v1.Query/VotesByProposal -``` - -Example: - -```bash -grpcurl -plaintext \ - -d '{"proposal_id":"1"}' localhost:9090 cosmos.group.v1.Query/VotesByProposal -``` - -Example Output: - -```bash -{ - "votes": [ - { - "proposalId": "1", - "voter": "cosmos1..", - "choice": "CHOICE_YES", - "submittedAt": "2021-12-17T08:05:02.490164009Z" - } - ], - "pagination": { - "total": "1" - } -} -``` - -#### VotesByVoter - -The `VotesByVoter` endpoint allows users to query for votes by voter account address with pagination flags. - -```bash -cosmos.group.v1.Query/VotesByVoter -``` - -Example: - -```bash -grpcurl -plaintext \ - -d '{"voter":"cosmos1.."}' localhost:9090 cosmos.group.v1.Query/VotesByVoter -``` - -Example Output: - -```bash -{ - "votes": [ - { - "proposalId": "1", - "voter": "cosmos1..", - "choice": "CHOICE_YES", - "submittedAt": "2021-12-17T08:05:02.490164009Z" - } - ], - "pagination": { - "total": "1" - } -} -``` - -### REST - -A user can query the `group` module using REST endpoints. - -#### GroupInfo - -The `GroupInfo` endpoint allows users to query for group info by given group id. - -```bash -/cosmos/group/v1/group_info/{group_id} -``` - -Example: - -```bash -curl localhost:1317/cosmos/group/v1/group_info/1 -``` - -Example Output: - -```bash -{ - "info": { - "id": "1", - "admin": "cosmos1..", - "metadata": "AQ==", - "version": "1", - "total_weight": "3" - } -} -``` - -#### GroupPolicyInfo - -The `GroupPolicyInfo` endpoint allows users to query for group policy info by account address of group policy. - -```bash -/cosmos/group/v1/group_policy_info/{address} -``` - -Example: - -```bash -curl localhost:1317/cosmos/group/v1/group_policy_info/cosmos1.. -``` - -Example Output: - -```bash -{ - "info": { - "address": "cosmos1..", - "group_id": "1", - "admin": "cosmos1..", - "metadata": "AQ==", - "version": "1", - "decision_policy": { - "@type": "/cosmos.group.v1.ThresholdDecisionPolicy", - "threshold": "1", - "windows": { - "voting_period": "120h", - "min_execution_period": "0s" - } - }, - } -} -``` - -#### GroupMembers - -The `GroupMembers` endpoint allows users to query for group members by group id with pagination flags. - -```bash -/cosmos/group/v1/group_members/{group_id} -``` - -Example: - -```bash -curl localhost:1317/cosmos/group/v1/group_members/1 -``` - -Example Output: - -```bash -{ - "members": [ - { - "group_id": "1", - "member": { - "address": "cosmos1..", - "weight": "1", - "metadata": "AQ==" - } - }, - { - "group_id": "1", - "member": { - "address": "cosmos1..", - "weight": "2", - "metadata": "AQ==" - } - ], - "pagination": { - "next_key": null, - "total": "2" - } -} -``` - -#### GroupsByAdmin - -The `GroupsByAdmin` endpoint allows users to query for groups by admin account address with pagination flags. - -```bash -/cosmos/group/v1/groups_by_admin/{admin} -``` - -Example: - -```bash -curl localhost:1317/cosmos/group/v1/groups_by_admin/cosmos1.. -``` - -Example Output: - -```bash -{ - "groups": [ - { - "id": "1", - "admin": "cosmos1..", - "metadata": "AQ==", - "version": "1", - "total_weight": "3" - }, - { - "id": "2", - "admin": "cosmos1..", - "metadata": "AQ==", - "version": "1", - "total_weight": "3" - } - ], - "pagination": { - "next_key": null, - "total": "2" - } -} -``` - -#### GroupPoliciesByGroup - -The `GroupPoliciesByGroup` endpoint allows users to query for group policies by group id with pagination flags. - -```bash -/cosmos/group/v1/group_policies_by_group/{group_id} -``` - -Example: - -```bash -curl localhost:1317/cosmos/group/v1/group_policies_by_group/1 -``` - -Example Output: - -```bash -{ - "group_policies": [ - { - "address": "cosmos1..", - "group_id": "1", - "admin": "cosmos1..", - "metadata": "AQ==", - "version": "1", - "decision_policy": { - "@type": "/cosmos.group.v1.ThresholdDecisionPolicy", - "threshold": "1", - "windows": { - "voting_period": "120h", - "min_execution_period": "0s" - } - }, - }, - { - "address": "cosmos1..", - "group_id": "1", - "admin": "cosmos1..", - "metadata": "AQ==", - "version": "1", - "decision_policy": { - "@type": "/cosmos.group.v1.ThresholdDecisionPolicy", - "threshold": "1", - "windows": { - "voting_period": "120h", - "min_execution_period": "0s" - } - }, - } - ], - "pagination": { - "next_key": null, - "total": "2" - } -} -``` - -#### GroupPoliciesByAdmin - -The `GroupPoliciesByAdmin` endpoint allows users to query for group policies by admin account address with pagination flags. - -```bash -/cosmos/group/v1/group_policies_by_admin/{admin} -``` - -Example: - -```bash -curl localhost:1317/cosmos/group/v1/group_policies_by_admin/cosmos1.. -``` - -Example Output: - -```bash -{ - "group_policies": [ - { - "address": "cosmos1..", - "group_id": "1", - "admin": "cosmos1..", - "metadata": "AQ==", - "version": "1", - "decision_policy": { - "@type": "/cosmos.group.v1.ThresholdDecisionPolicy", - "threshold": "1", - "windows": { - "voting_period": "120h", - "min_execution_period": "0s" - } - }, - }, - { - "address": "cosmos1..", - "group_id": "1", - "admin": "cosmos1..", - "metadata": "AQ==", - "version": "1", - "decision_policy": { - "@type": "/cosmos.group.v1.ThresholdDecisionPolicy", - "threshold": "1", - "windows": { - "voting_period": "120h", - "min_execution_period": "0s" - } - }, - } - ], - "pagination": { - "next_key": null, - "total": "2" - } -``` - -#### Proposal - -The `Proposal` endpoint allows users to query for proposal by id. - -```bash -/cosmos/group/v1/proposal/{proposal_id} -``` - -Example: - -```bash -curl localhost:1317/cosmos/group/v1/proposal/1 -``` - -Example Output: - -```bash -{ - "proposal": { - "proposal_id": "1", - "address": "cosmos1..", - "metadata": "AQ==", - "proposers": [ - "cosmos1.." - ], - "submitted_at": "2021-12-17T07:06:26.310638964Z", - "group_version": "1", - "group_policy_version": "1", - "status": "STATUS_SUBMITTED", - "result": "RESULT_UNFINALIZED", - "vote_state": { - "yes_count": "0", - "no_count": "0", - "abstain_count": "0", - "veto_count": "0" - }, - "windows": { - "min_execution_period": "0s", - "voting_period": "432000s" - }, - "executor_result": "EXECUTOR_RESULT_NOT_RUN", - "messages": [ - { - "@type": "/cosmos.bank.v1beta1.MsgSend", - "from_address": "cosmos1..", - "to_address": "cosmos1..", - "amount": [ - { - "denom": "stake", - "amount": "100000000" - } - ] - } - ], - "title": "Title", - "summary": "Summary", - } -} -``` - -#### ProposalsByGroupPolicy - -The `ProposalsByGroupPolicy` endpoint allows users to query for proposals by account address of group policy with pagination flags. - -```bash -/cosmos/group/v1/proposals_by_group_policy/{address} -``` - -Example: - -```bash -curl localhost:1317/cosmos/group/v1/proposals_by_group_policy/cosmos1.. -``` - -Example Output: - -```bash -{ - "proposals": [ - { - "id": "1", - "group_policy_address": "cosmos1..", - "metadata": "AQ==", - "proposers": [ - "cosmos1.." - ], - "submit_time": "2021-12-17T08:03:27.099649352Z", - "group_version": "1", - "group_policy_version": "1", - "status": "STATUS_CLOSED", - "result": "RESULT_ACCEPTED", - "vote_state": { - "yes_count": "1", - "no_count": "0", - "abstain_count": "0", - "veto_count": "0" - }, - "windows": { - "min_execution_period": "0s", - "voting_period": "432000s" - }, - "executor_result": "EXECUTOR_RESULT_NOT_RUN", - "messages": [ - { - "@type": "/cosmos.bank.v1beta1.MsgSend", - "from_address": "cosmos1..", - "to_address": "cosmos1..", - "amount": [ - { - "denom": "stake", - "amount": "100000000" - } - ] - } - ] - } - ], - "pagination": { - "next_key": null, - "total": "1" - } -} -``` - -#### VoteByProposalVoter - -The `VoteByProposalVoter` endpoint allows users to query for vote by proposal id and voter account address. - -```bash -/cosmos/group/v1/vote_by_proposal_voter/{proposal_id}/{voter} -``` - -Example: - -```bash -curl localhost:1317/cosmos/group/v1beta1/vote_by_proposal_voter/1/cosmos1.. -``` - -Example Output: - -```bash -{ - "vote": { - "proposal_id": "1", - "voter": "cosmos1..", - "choice": "CHOICE_YES", - "metadata": "AQ==", - "submitted_at": "2021-12-17T08:05:02.490164009Z" - } -} -``` - -#### VotesByProposal - -The `VotesByProposal` endpoint allows users to query for votes by proposal id with pagination flags. - -```bash -/cosmos/group/v1/votes_by_proposal/{proposal_id} -``` - -Example: - -```bash -curl localhost:1317/cosmos/group/v1/votes_by_proposal/1 -``` - -Example Output: - -```bash -{ - "votes": [ - { - "proposal_id": "1", - "voter": "cosmos1..", - "option": "CHOICE_YES", - "metadata": "AQ==", - "submit_time": "2021-12-17T08:05:02.490164009Z" - } - ], - "pagination": { - "next_key": null, - "total": "1" - } -} -``` - -#### VotesByVoter - -The `VotesByVoter` endpoint allows users to query for votes by voter account address with pagination flags. - -```bash -/cosmos/group/v1/votes_by_voter/{voter} -``` - -Example: - -```bash -curl localhost:1317/cosmos/group/v1/votes_by_voter/cosmos1.. -``` - -Example Output: - -```bash -{ - "votes": [ - { - "proposal_id": "1", - "voter": "cosmos1..", - "choice": "CHOICE_YES", - "metadata": "AQ==", - "submitted_at": "2021-12-17T08:05:02.490164009Z" - } - ], - "pagination": { - "next_key": null, - "total": "1" - } -} -``` - -## Metadata - -The group module has four locations for metadata where users can provide further context about the on-chain actions they are taking. By default all metadata fields have a 255 character length field where metadata can be stored in json format, either on-chain or off-chain depending on the amount of data required. Here we provide a recommendation for the json structure and where the data should be stored. There are two important factors in making these recommendations. First, that the group and gov modules are consistent with one another, note the number of proposals made by all groups may be quite large. Second, that client applications such as block explorers and governance interfaces have confidence in the consistency of metadata structure across chains. - -### Proposal - -Location: off-chain as json object stored on IPFS (mirrors [gov proposal](../gov/README.md#metadata)) - -```json -{ - "title": "", - "authors": [""], - "summary": "", - "details": "", - "proposal_forum_url": "", - "vote_option_context": "", -} -``` - -:::note -The `authors` field is an array of strings, this is to allow for multiple authors to be listed in the metadata. -In v0.46, the `authors` field is a comma-separated string. Frontends are encouraged to support both formats for backwards compatibility. -::: - -### Vote - -Location: on-chain as json within 255 character limit (mirrors [gov vote](../gov/README.md#metadata)) - -```json -{ - "justification": "", -} -``` - -### Group - -Location: off-chain as json object stored on IPFS - -```json -{ - "name": "", - "description": "", - "group_website_url": "", - "group_forum_url": "", -} -``` - -### Decision policy - -Location: on-chain as json within 255 character limit - -```json -{ - "name": "", - "description": "", -} -``` diff --git a/.gitbook/developers/modules/core/mint/README.md b/.gitbook/developers/modules/core/mint/README.md deleted file mode 100644 index 80198010..00000000 --- a/.gitbook/developers/modules/core/mint/README.md +++ /dev/null @@ -1,383 +0,0 @@ ---- -sidebar_position: 1 ---- - -# `x/mint` - -## Contents - -* [State](#state) - * [Minter](#minter) - * [Params](#params) -* [Begin-Block](#begin-block) - * [NextInflationRate](#nextinflationrate) - * [NextAnnualProvisions](#nextannualprovisions) - * [BlockProvision](#blockprovision) -* [Parameters](#parameters) -* [Events](#events) - * [BeginBlocker](#beginblocker) -* [Client](#client) - * [CLI](#cli) - * [gRPC](#grpc) - * [REST](#rest) - -## Concepts - -### The Minting Mechanism - -The minting mechanism was designed to: - -* allow for a flexible inflation rate determined by market demand targeting a particular bonded-stake ratio -* effect a balance between market liquidity and staked supply - -In order to best determine the appropriate market rate for inflation rewards, a -moving change rate is used. The moving change rate mechanism ensures that if -the % bonded is either over or under the goal %-bonded, the inflation rate will -adjust to further incentivize or disincentivize being bonded, respectively. Setting the goal -%-bonded at less than 100% encourages the network to maintain some non-staked tokens -which should help provide some liquidity. - -It can be broken down in the following way: - -* If the actual percentage of bonded tokens is below the goal %-bonded the inflation rate will - increase until a maximum value is reached -* If the goal % bonded (67% in Cosmos-Hub) is maintained, then the inflation - rate will stay constant -* If the actual percentage of bonded tokens is above the goal %-bonded the inflation rate will - decrease until a minimum value is reached - - -## State - -### Minter - -The minter is a space for holding current inflation information. - -* Minter: `0x00 -> ProtocolBuffer(minter)` - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/mint/v1beta1/mint.proto#L10-L24 -``` - -### Params - -The mint module stores its params in state with the prefix of `0x01`, -it can be updated with governance or the address with authority. - -* Params: `mint/params -> legacy_amino(params)` - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/mint/v1beta1/mint.proto#L26-L59 -``` - -## Begin-Block - -Minting parameters are recalculated and inflation paid at the beginning of each block. - -### Inflation rate calculation - -Inflation rate is calculated using an "inflation calculation function" that's -passed to the `NewAppModule` function. If no function is passed, then the SDK's -default inflation function will be used (`NextInflationRate`). In case a custom -inflation calculation logic is needed, this can be achieved by defining and -passing a function that matches `InflationCalculationFn`'s signature. - -```go -type InflationCalculationFn func(ctx sdk.Context, minter Minter, params Params, bondedRatio math.LegacyDec) math.LegacyDec -``` - -#### NextInflationRate - -The target annual inflation rate is recalculated each block. -The inflation is also subject to a rate change (positive or negative) -depending on the distance from the desired ratio (67%). The maximum rate change -possible is defined to be 13% per year, however, the annual inflation is capped -as between 7% and 20%. - -```go -NextInflationRate(params Params, bondedRatio math.LegacyDec) (inflation math.LegacyDec) { - inflationRateChangePerYear = (1 - bondedRatio/params.GoalBonded) * params.InflationRateChange - inflationRateChange = inflationRateChangePerYear/blocksPerYr - - // increase the new annual inflation for this next block - inflation += inflationRateChange - if inflation > params.InflationMax { - inflation = params.InflationMax - } - if inflation < params.InflationMin { - inflation = params.InflationMin - } - - return inflation -} -``` - -### NextAnnualProvisions - -Calculate the annual provisions based on current total supply and inflation -rate. This parameter is calculated once per block. - -```go -NextAnnualProvisions(params Params, totalSupply math.LegacyDec) (provisions math.LegacyDec) { - return Inflation * totalSupply -``` - -### BlockProvision - -Calculate the provisions generated for each block based on current annual provisions. The provisions are then minted by the `mint` module's `ModuleMinterAccount` and then transferred to the `auth`'s `FeeCollector` `ModuleAccount`. - -```go -BlockProvision(params Params) sdk.Coin { - provisionAmt = AnnualProvisions/ params.BlocksPerYear - return sdk.NewCoin(params.MintDenom, provisionAmt.Truncate()) -``` - - -## Parameters - -The minting module contains the following parameters: - -| Key | Type | Example | -|---------------------|-----------------|------------------------| -| MintDenom | string | "uatom" | -| InflationRateChange | string (dec) | "0.130000000000000000" | -| InflationMax | string (dec) | "0.200000000000000000" | -| InflationMin | string (dec) | "0.070000000000000000" | -| GoalBonded | string (dec) | "0.670000000000000000" | -| BlocksPerYear | string (uint64) | "6311520" | - - -## Events - -The minting module emits the following events: - -### BeginBlocker - -| Type | Attribute Key | Attribute Value | -|------|-------------------|--------------------| -| mint | bonded_ratio | {bondedRatio} | -| mint | inflation | {inflation} | -| mint | annual_provisions | {annualProvisions} | -| mint | amount | {amount} | - - -## Client - -### CLI - -A user can query and interact with the `mint` module using the CLI. - -#### Query - -The `query` commands allows users to query `mint` state. - -```shell -simd query mint --help -``` - -##### annual-provisions - -The `annual-provisions` command allows users to query the current minting annual provisions value - -```shell -simd query mint annual-provisions [flags] -``` - -Example: - -```shell -simd query mint annual-provisions -``` - -Example Output: - -```shell -22268504368893.612100895088410693 -``` - -##### inflation - -The `inflation` command allows users to query the current minting inflation value - -```shell -simd query mint inflation [flags] -``` - -Example: - -```shell -simd query mint inflation -``` - -Example Output: - -```shell -0.199200302563256955 -``` - -##### params - -The `params` command allows users to query the current minting parameters - -```shell -simd query mint params [flags] -``` - -Example: - -```yml -blocks_per_year: "4360000" -goal_bonded: "0.670000000000000000" -inflation_max: "0.200000000000000000" -inflation_min: "0.070000000000000000" -inflation_rate_change: "0.130000000000000000" -mint_denom: stake -``` - -### gRPC - -A user can query the `mint` module using gRPC endpoints. - -#### AnnualProvisions - -The `AnnualProvisions` endpoint allows users to query the current minting annual provisions value - -```shell -/cosmos.mint.v1beta1.Query/AnnualProvisions -``` - -Example: - -```shell -grpcurl -plaintext localhost:9090 cosmos.mint.v1beta1.Query/AnnualProvisions -``` - -Example Output: - -```json -{ - "annualProvisions": "1432452520532626265712995618" -} -``` - -#### Inflation - -The `Inflation` endpoint allows users to query the current minting inflation value - -```shell -/cosmos.mint.v1beta1.Query/Inflation -``` - -Example: - -```shell -grpcurl -plaintext localhost:9090 cosmos.mint.v1beta1.Query/Inflation -``` - -Example Output: - -```json -{ - "inflation": "130197115720711261" -} -``` - -#### Params - -The `Params` endpoint allows users to query the current minting parameters - -```shell -/cosmos.mint.v1beta1.Query/Params -``` - -Example: - -```shell -grpcurl -plaintext localhost:9090 cosmos.mint.v1beta1.Query/Params -``` - -Example Output: - -```json -{ - "params": { - "mintDenom": "stake", - "inflationRateChange": "130000000000000000", - "inflationMax": "200000000000000000", - "inflationMin": "70000000000000000", - "goalBonded": "670000000000000000", - "blocksPerYear": "6311520" - } -} -``` - -### REST - -A user can query the `mint` module using REST endpoints. - -#### annual-provisions - -```shell -/cosmos/mint/v1beta1/annual_provisions -``` - -Example: - -```shell -curl "localhost:1317/cosmos/mint/v1beta1/annual_provisions" -``` - -Example Output: - -```json -{ - "annualProvisions": "1432452520532626265712995618" -} -``` - -#### inflation - -```shell -/cosmos/mint/v1beta1/inflation -``` - -Example: - -```shell -curl "localhost:1317/cosmos/mint/v1beta1/inflation" -``` - -Example Output: - -```json -{ - "inflation": "130197115720711261" -} -``` - -#### params - -```shell -/cosmos/mint/v1beta1/params -``` - -Example: - -```shell -curl "localhost:1317/cosmos/mint/v1beta1/params" -``` - -Example Output: - -```json -{ - "params": { - "mintDenom": "stake", - "inflationRateChange": "130000000000000000", - "inflationMax": "200000000000000000", - "inflationMin": "70000000000000000", - "goalBonded": "670000000000000000", - "blocksPerYear": "6311520" - } -} -``` diff --git a/.gitbook/developers/modules/core/nft/README.md b/.gitbook/developers/modules/core/nft/README.md deleted file mode 100644 index 34c1d406..00000000 --- a/.gitbook/developers/modules/core/nft/README.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -sidebar_position: 1 ---- - -# `x/nft` - -## Contents - -## Abstract - -`x/nft` is an implementation of a Cosmos SDK module, per [ADR 43](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-043-nft-module.md), that allows you to create nft classification, create nft, transfer nft, update nft, and support various queries by integrating the module. It is fully compatible with the ERC721 specification. - -* [Concepts](#concepts) - * [Class](#class) - * [NFT](#nft) -* [State](#state) - * [Class](#class-1) - * [NFT](#nft-1) - * [NFTOfClassByOwner](#nftofclassbyowner) - * [Owner](#owner) - * [TotalSupply](#totalsupply) -* [Messages](#messages) - * [MsgSend](#msgsend) -* [Events](#events) - -## Concepts - -### Class - -`x/nft` module defines a struct `Class` to describe the common characteristics of a class of nft, under this class, you can create a variety of nft, which is equivalent to an erc721 contract for Ethereum. The design is defined in the [ADR 043](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-043-nft-module.md). - -### NFT - -The full name of NFT is Non-Fungible Tokens. Because of the irreplaceable nature of NFT, it means that it can be used to represent unique things. The nft implemented by this module is fully compatible with Ethereum ERC721 standard. - -## State - -### Class - -Class is mainly composed of `id`, `name`, `symbol`, `description`, `uri`, `uri_hash`,`data` where `id` is the unique identifier of the class, similar to the Ethereum ERC721 contract address, the others are optional. - -* Class: `0x01 | classID | -> ProtocolBuffer(Class)` - -### NFT - -NFT is mainly composed of `class_id`, `id`, `uri`, `uri_hash` and `data`. Among them, `class_id` and `id` are two-tuples that identify the uniqueness of nft, `uri` and `uri_hash` is optional, which identifies the off-chain storage location of the nft, and `data` is an Any type. Use Any chain of `x/nft` modules can be customized by extending this field - -* NFT: `0x02 | classID | 0x00 | nftID |-> ProtocolBuffer(NFT)` - -### NFTOfClassByOwner - -NFTOfClassByOwner is mainly to realize the function of querying all nfts using classID and owner, without other redundant functions. - -* NFTOfClassByOwner: `0x03 | owner | 0x00 | classID | 0x00 | nftID |-> 0x01` - -### Owner - -Since there is no extra field in NFT to indicate the owner of nft, an additional key-value pair is used to save the ownership of nft. With the transfer of nft, the key-value pair is updated synchronously. - -* OwnerKey: `0x04 | classID | 0x00 | nftID |-> owner` - -### TotalSupply - -TotalSupply is responsible for tracking the number of all nfts under a certain class. Mint operation is performed under the changed class, supply increases by one, burn operation, and supply decreases by one. - -* OwnerKey: `0x05 | classID |-> totalSupply` - -## Messages - -In this section we describe the processing of messages for the NFT module. - -:::warning -The validation of `ClassID` and `NftID` is left to the app developer. -The SDK does not provide any validation for these fields. -::: - -### MsgSend - -You can use the `MsgSend` message to transfer the ownership of nft. This is a function provided by the `x/nft` module. Of course, you can use the `Transfer` method to implement your own transfer logic, but you need to pay extra attention to the transfer permissions. - -The message handling should fail if: - -* provided `ClassID` does not exist. -* provided `Id` does not exist. -* provided `Sender` does not the owner of nft. - -## Events - -The nft module emits proto events defined in [the Protobuf reference](https://buf.build/cosmos/cosmos-sdk/docs/main:cosmos.nft.v1beta1). diff --git a/.gitbook/developers/modules/core/params/README.md b/.gitbook/developers/modules/core/params/README.md deleted file mode 100644 index f8d374d0..00000000 --- a/.gitbook/developers/modules/core/params/README.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -sidebar_position: 1 ---- - -# `x/params` - -> Note: The Params module has been depreacted in favour of each module housing its own parameters. - -## Abstract - -Package params provides a globally available parameter store. - -There are two main types, Keeper and Subspace. Subspace is an isolated namespace for a -paramstore, where keys are prefixed by preconfigured spacename. Keeper has a -permission to access all existing spaces. - -Subspace can be used by the individual keepers, which need a private parameter store -that the other keepers cannot modify. The params Keeper can be used to add a route to `x/gov` router in order to modify any parameter in case a proposal passes. - -The following contents explains how to use params module for master and user modules. - -## Contents - -* [Keeper](#keeper) -* [Subspace](#subspace) - * [Key](#key) - * [KeyTable](#keytable) - * [ParamSet](#paramset) - -## Keeper - -In the app initialization stage, [subspaces](#subspace) can be allocated for other modules' keeper using `Keeper.Subspace` and are stored in `Keeper.spaces`. Then, those modules can have a reference to their specific parameter store through `Keeper.GetSubspace`. - -Example: - -```go -type ExampleKeeper struct { - paramSpace paramtypes.Subspace -} - -func (k ExampleKeeper) SetParams(ctx sdk.Context, params types.Params) { - k.paramSpace.SetParamSet(ctx, ¶ms) -} -``` - -## Subspace - -`Subspace` is a prefixed subspace of the parameter store. Each module which uses the -parameter store will take a `Subspace` to isolate permission to access. - -### Key - -Parameter keys are human readable alphanumeric strings. A parameter for the key -`"ExampleParameter"` is stored under `[]byte("SubspaceName" + "/" + "ExampleParameter")`, - where `"SubspaceName"` is the name of the subspace. - -Subkeys are secondary parameter keys those are used along with a primary parameter key. -Subkeys can be used for grouping or dynamic parameter key generation during runtime. - -### KeyTable - -All of the parameter keys that will be used should be registered at the compile -time. `KeyTable` is essentially a `map[string]attribute`, where the `string` is a parameter key. - -Currently, `attribute` consists of a `reflect.Type`, which indicates the parameter -type to check that provided key and value are compatible and registered, as well as a function `ValueValidatorFn` to validate values. - -Only primary keys have to be registered on the `KeyTable`. Subkeys inherit the -attribute of the primary key. - -### ParamSet - -Modules often define parameters as a proto message. The generated struct can implement -`ParamSet` interface to be used with the following methods: - -* `KeyTable.RegisterParamSet()`: registers all parameters in the struct -* `Subspace.{Get, Set}ParamSet()`: Get to & Set from the struct - -The implementor should be a pointer in order to use `GetParamSet()`. diff --git a/.gitbook/developers/modules/core/slashing/README.md b/.gitbook/developers/modules/core/slashing/README.md deleted file mode 100644 index 591a9a73..00000000 --- a/.gitbook/developers/modules/core/slashing/README.md +++ /dev/null @@ -1,813 +0,0 @@ ---- -sidebar_position: 1 ---- - -# `x/slashing` - -## Abstract - -This section specifies the slashing module of the Cosmos SDK, which implements functionality -first outlined in the [Cosmos Whitepaper](https://cosmos.network/about/whitepaper) in June 2016. - -The slashing module enables Cosmos SDK-based blockchains to disincentivize any attributable action -by a protocol-recognized actor with value at stake by penalizing them ("slashing"). - -Penalties may include, but are not limited to: - -* Burning some amount of their stake -* Removing their ability to vote on future blocks for a period of time. - -This module will be used by the Cosmos Hub, the first hub in the Cosmos ecosystem. - -## Contents - -* [Concepts](#concepts) - * [States](#states) - * [Tombstone Caps](#tombstone-caps) - * [Infraction Timelines](#infraction-timelines) -* [State](#state) - * [Signing Info (Liveness)](#signing-info-liveness) - * [Params](#params) -* [Messages](#messages) - * [Unjail](#unjail) -* [BeginBlock](#beginblock) - * [Liveness Tracking](#liveness-tracking) -* [Hooks](#hooks) -* [Events](#events) -* [Staking Tombstone](#staking-tombstone) -* [Parameters](#parameters) -* [CLI](#cli) - * [Query](#query) - * [Transactions](#transactions) - * [gRPC](#grpc) - * [REST](#rest) - -## Concepts - -### States - -At any given time, there are any number of validators registered in the state -machine. Each block, the top `MaxValidators` (defined by `x/staking`) validators -who are not jailed become _bonded_, meaning that they may propose and vote on -blocks. Validators who are _bonded_ are _at stake_, meaning that part or all of -their stake and their delegators' stake is at risk if they commit a protocol fault. - -For each of these validators we keep a `ValidatorSigningInfo` record that contains -information partaining to validator's liveness and other infraction related -attributes. - -### Tombstone Caps - -In order to mitigate the impact of initially likely categories of non-malicious -protocol faults, the Cosmos Hub implements for each validator -a _tombstone_ cap, which only allows a validator to be slashed once for a double -sign fault. For example, if you misconfigure your HSM and double-sign a bunch of -old blocks, you'll only be punished for the first double-sign (and then immediately tombstombed). This will still be quite expensive and desirable to avoid, but tombstone caps -somewhat blunt the economic impact of unintentional misconfiguration. - -Liveness faults do not have caps, as they can't stack upon each other. Liveness bugs are "detected" as soon as the infraction occurs, and the validators are immediately put in jail, so it is not possible for them to commit multiple liveness faults without unjailing in between. - -### Infraction Timelines - -To illustrate how the `x/slashing` module handles submitted evidence through -CometBFT consensus, consider the following examples: - -**Definitions**: - -_[_ : timeline start -_]_ : timeline end -_Cn_ : infraction `n` committed -_Dn_ : infraction `n` discovered -_Vb_ : validator bonded -_Vu_ : validator unbonded - -#### Single Double Sign Infraction - -\[----------C1----D1,Vu-----\] - -A single infraction is committed then later discovered, at which point the -validator is unbonded and slashed at the full amount for the infraction. - -#### Multiple Double Sign Infractions - -\[----------C1--C2---C3---D1,D2,D3Vu-----\] - -Multiple infractions are committed and then later discovered, at which point the -validator is jailed and slashed for only one infraction. Because the validator -is also tombstoned, they can not rejoin the validator set. - -## State - -### Signing Info (Liveness) - -Every block includes a set of precommits by the validators for the previous block, -known as the `LastCommitInfo` provided by CometBFT. A `LastCommitInfo` is valid so -long as it contains precommits from +2/3 of total voting power. - -Proposers are incentivized to include precommits from all validators in the CometBFT `LastCommitInfo` -by receiving additional fees proportional to the difference between the voting -power included in the `LastCommitInfo` and +2/3 (see [fee distribution](../distribution/README.md#begin-block)). - -```go -type LastCommitInfo struct { - Round int32 - Votes []VoteInfo -} -``` - -Validators are penalized for failing to be included in the `LastCommitInfo` for some -number of blocks by being automatically jailed, potentially slashed, and unbonded. - -Information about validator's liveness activity is tracked through `ValidatorSigningInfo`. -It is indexed in the store as follows: - -* ValidatorSigningInfo: `0x01 | ConsAddrLen (1 byte) | ConsAddress -> ProtocolBuffer(ValSigningInfo)` -* MissedBlocksBitArray: `0x02 | ConsAddrLen (1 byte) | ConsAddress | LittleEndianUint64(signArrayIndex) -> VarInt(didMiss)` (varint is a number encoding format) - -The first mapping allows us to easily lookup the recent signing info for a -validator based on the validator's consensus address. - -The second mapping (`MissedBlocksBitArray`) acts -as a bit-array of size `SignedBlocksWindow` that tells us if the validator missed -the block for a given index in the bit-array. The index in the bit-array is given -as little endian uint64. -The result is a `varint` that takes on `0` or `1`, where `0` indicates the -validator did not miss (did sign) the corresponding block, and `1` indicates -they missed the block (did not sign). - -Note that the `MissedBlocksBitArray` is not explicitly initialized up-front. Keys -are added as we progress through the first `SignedBlocksWindow` blocks for a newly -bonded validator. The `SignedBlocksWindow` parameter defines the size -(number of blocks) of the sliding window used to track validator liveness. - -The information stored for tracking validator liveness is as follows: - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/slashing/v1beta1/slashing.proto#L13-L35 -``` - -### Params - -The slashing module stores it's params in state with the prefix of `0x00`, -it can be updated with governance or the address with authority. - -* Params: `0x00 | ProtocolBuffer(Params)` - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/slashing/v1beta1/slashing.proto#L37-L59 -``` - -## Messages - -In this section we describe the processing of messages for the `slashing` module. - -### Unjail - -If a validator was automatically unbonded due to downtime and wishes to come back online & -possibly rejoin the bonded set, it must send `MsgUnjail`: - -```protobuf -// MsgUnjail is an sdk.Msg used for unjailing a jailed validator, thus returning -// them into the bonded validator set, so they can begin receiving provisions -// and rewards again. -message MsgUnjail { - string validator_addr = 1; -} -``` - -Below is a pseudocode of the `MsgSrv/Unjail` RPC: - -```go -unjail(tx MsgUnjail) - validator = getValidator(tx.ValidatorAddr) - if validator == nil - fail with "No validator found" - - if getSelfDelegation(validator) == 0 - fail with "validator must self delegate before unjailing" - - if !validator.Jailed - fail with "Validator not jailed, cannot unjail" - - info = GetValidatorSigningInfo(operator) - if info.Tombstoned - fail with "Tombstoned validator cannot be unjailed" - if block time < info.JailedUntil - fail with "Validator still jailed, cannot unjail until period has expired" - - validator.Jailed = false - setValidator(validator) - - return -``` - -If the validator has enough stake to be in the top `n = MaximumBondedValidators`, it will be automatically rebonded, -and all delegators still delegated to the validator will be rebonded and begin to again collect -provisions and rewards. - -## BeginBlock - -### Liveness Tracking - -At the beginning of each block, we update the `ValidatorSigningInfo` for each -validator and check if they've crossed below the liveness threshold over a -sliding window. This sliding window is defined by `SignedBlocksWindow` and the -index in this window is determined by `IndexOffset` found in the validator's -`ValidatorSigningInfo`. For each block processed, the `IndexOffset` is incremented -regardless if the validator signed or not. Once the index is determined, the -`MissedBlocksBitArray` and `MissedBlocksCounter` are updated accordingly. - -Finally, in order to determine if a validator crosses below the liveness threshold, -we fetch the maximum number of blocks missed, `maxMissed`, which is -`SignedBlocksWindow - (MinSignedPerWindow * SignedBlocksWindow)` and the minimum -height at which we can determine liveness, `minHeight`. If the current block is -greater than `minHeight` and the validator's `MissedBlocksCounter` is greater than -`maxMissed`, they will be slashed by `SlashFractionDowntime`, will be jailed -for `DowntimeJailDuration`, and have the following values reset: -`MissedBlocksBitArray`, `MissedBlocksCounter`, and `IndexOffset`. - -**Note**: Liveness slashes do **NOT** lead to a tombstombing. - -```go -height := block.Height - -for vote in block.LastCommitInfo.Votes { - signInfo := GetValidatorSigningInfo(vote.Validator.Address) - - // This is a relative index, so we counts blocks the validator SHOULD have - // signed. We use the 0-value default signing info if not present, except for - // start height. - index := signInfo.IndexOffset % SignedBlocksWindow() - signInfo.IndexOffset++ - - // Update MissedBlocksBitArray and MissedBlocksCounter. The MissedBlocksCounter - // just tracks the sum of MissedBlocksBitArray. That way we avoid needing to - // read/write the whole array each time. - missedPrevious := GetValidatorMissedBlockBitArray(vote.Validator.Address, index) - missed := !signed - - switch { - case !missedPrevious && missed: - // array index has changed from not missed to missed, increment counter - SetValidatorMissedBlockBitArray(vote.Validator.Address, index, true) - signInfo.MissedBlocksCounter++ - - case missedPrevious && !missed: - // array index has changed from missed to not missed, decrement counter - SetValidatorMissedBlockBitArray(vote.Validator.Address, index, false) - signInfo.MissedBlocksCounter-- - - default: - // array index at this index has not changed; no need to update counter - } - - if missed { - // emit events... - } - - minHeight := signInfo.StartHeight + SignedBlocksWindow() - maxMissed := SignedBlocksWindow() - MinSignedPerWindow() - - // If we are past the minimum height and the validator has missed too many - // jail and slash them. - if height > minHeight && signInfo.MissedBlocksCounter > maxMissed { - validator := ValidatorByConsAddr(vote.Validator.Address) - - // emit events... - - // We need to retrieve the stake distribution which signed the block, so we - // subtract ValidatorUpdateDelay from the block height, and subtract an - // additional 1 since this is the LastCommit. - // - // Note, that this CAN result in a negative "distributionHeight" up to - // -ValidatorUpdateDelay-1, i.e. at the end of the pre-genesis block (none) = at the beginning of the genesis block. - // That's fine since this is just used to filter unbonding delegations & redelegations. - distributionHeight := height - sdk.ValidatorUpdateDelay - 1 - - SlashWithInfractionReason(vote.Validator.Address, distributionHeight, vote.Validator.Power, SlashFractionDowntime(), stakingtypes.Downtime) - Jail(vote.Validator.Address) - - signInfo.JailedUntil = block.Time.Add(DowntimeJailDuration()) - - // We need to reset the counter & array so that the validator won't be - // immediately slashed for downtime upon rebonding. - signInfo.MissedBlocksCounter = 0 - signInfo.IndexOffset = 0 - ClearValidatorMissedBlockBitArray(vote.Validator.Address) - } - - SetValidatorSigningInfo(vote.Validator.Address, signInfo) -} -``` - -## Hooks - -This section contains a description of the module's `hooks`. Hooks are operations that are executed automatically when events are raised. - -### Staking hooks - -The slashing module implements the `StakingHooks` defined in `x/staking` and are used as record-keeping of validators information. During the app initialization, these hooks should be registered in the staking module struct. - -The following hooks impact the slashing state: - -* `AfterValidatorBonded` creates a `ValidatorSigningInfo` instance as described in the following section. -* `AfterValidatorCreated` stores a validator's consensus key. -* `AfterValidatorRemoved` removes a validator's consensus key. - -### Validator Bonded - -Upon successful first-time bonding of a new validator, we create a new `ValidatorSigningInfo` structure for the -now-bonded validator, which `StartHeight` of the current block. - -If the validator was out of the validator set and gets bonded again, its new bonded height is set. - -```go -onValidatorBonded(address sdk.ValAddress) - - signingInfo, found = GetValidatorSigningInfo(address) - if !found { - signingInfo = ValidatorSigningInfo { - StartHeight : CurrentHeight, - IndexOffset : 0, - JailedUntil : time.Unix(0, 0), - Tombstone : false, - MissedBloskCounter : 0 - } else { - signingInfo.StartHeight = CurrentHeight - } - - setValidatorSigningInfo(signingInfo) - } - - return -``` - -## Events - -The slashing module emits the following events: - -### MsgServer - -#### MsgUnjail - -| Type | Attribute Key | Attribute Value | -| ------- | ------------- | ------------------ | -| message | module | slashing | -| message | sender | {validatorAddress} | - -### Keeper - -### BeginBlocker: HandleValidatorSignature - -| Type | Attribute Key | Attribute Value | -| ----- | ------------- | --------------------------- | -| slash | address | {validatorConsensusAddress} | -| slash | power | {validatorPower} | -| slash | reason | {slashReason} | -| slash | jailed [0] | {validatorConsensusAddress} | -| slash | burned coins | {math.Int} | - -* [0] Only included if the validator is jailed. - -| Type | Attribute Key | Attribute Value | -| -------- | ------------- | --------------------------- | -| liveness | address | {validatorConsensusAddress} | -| liveness | missed_blocks | {missedBlocksCounter} | -| liveness | height | {blockHeight} | - -#### Slash - -* same as `"slash"` event from `HandleValidatorSignature`, but without the `jailed` attribute. - -#### Jail - -| Type | Attribute Key | Attribute Value | -| ----- | ------------- | ------------------ | -| slash | jailed | {validatorAddress} | - -## Staking Tombstone - -### Abstract - -In the current implementation of the `slashing` module, when the consensus engine -informs the state machine of a validator's consensus fault, the validator is -partially slashed, and put into a "jail period", a period of time in which they -are not allowed to rejoin the validator set. However, because of the nature of -consensus faults and ABCI, there can be a delay between an infraction occurring, -and evidence of the infraction reaching the state machine (this is one of the -primary reasons for the existence of the unbonding period). - -> Note: The tombstone concept, only applies to faults that have a delay between -> the infraction occurring and evidence reaching the state machine. For example, -> evidence of a validator double signing may take a while to reach the state machine -> due to unpredictable evidence gossip layer delays and the ability of validators to -> selectively reveal double-signatures (e.g. to infrequently-online light clients). -> Liveness slashing, on the other hand, is detected immediately as soon as the -> infraction occurs, and therefore no slashing period is needed. A validator is -> immediately put into jail period, and they cannot commit another liveness fault -> until they unjail. In the future, there may be other types of byzantine faults -> that have delays (for example, submitting evidence of an invalid proposal as a transaction). -> When implemented, it will have to be decided whether these future types of -> byzantine faults will result in a tombstoning (and if not, the slash amounts -> will not be capped by a slashing period). - -In the current system design, once a validator is put in the jail for a consensus -fault, after the `JailPeriod` they are allowed to send a transaction to `unjail` -themselves, and thus rejoin the validator set. - -One of the "design desires" of the `slashing` module is that if multiple -infractions occur before evidence is executed (and a validator is put in jail), -they should only be punished for single worst infraction, but not cumulatively. -For example, if the sequence of events is: - -1. Validator A commits Infraction 1 (worth 30% slash) -2. Validator A commits Infraction 2 (worth 40% slash) -3. Validator A commits Infraction 3 (worth 35% slash) -4. Evidence for Infraction 1 reaches state machine (and validator is put in jail) -5. Evidence for Infraction 2 reaches state machine -6. Evidence for Infraction 3 reaches state machine - -Only Infraction 2 should have its slash take effect, as it is the highest. This -is done, so that in the case of the compromise of a validator's consensus key, -they will only be punished once, even if the hacker double-signs many blocks. -Because, the unjailing has to be done with the validator's operator key, they -have a chance to re-secure their consensus key, and then signal that they are -ready using their operator key. We call this period during which we track only -the max infraction, the "slashing period". - -Once, a validator rejoins by unjailing themselves, we begin a new slashing period; -if they commit a new infraction after unjailing, it gets slashed cumulatively on -top of the worst infraction from the previous slashing period. - -However, while infractions are grouped based off of the slashing periods, because -evidence can be submitted up to an `unbondingPeriod` after the infraction, we -still have to allow for evidence to be submitted for previous slashing periods. -For example, if the sequence of events is: - -1. Validator A commits Infraction 1 (worth 30% slash) -2. Validator A commits Infraction 2 (worth 40% slash) -3. Evidence for Infraction 1 reaches state machine (and Validator A is put in jail) -4. Validator A unjails - -We are now in a new slashing period, however we still have to keep the door open -for the previous infraction, as the evidence for Infraction 2 may still come in. -As the number of slashing periods increase, it creates more complexity as we have -to keep track of the highest infraction amount for every single slashing period. - -> Note: Currently, according to the `slashing` module spec, a new slashing period -> is created every time a validator is unbonded then rebonded. This should probably -> be changed to jailed/unjailed. See issue [#3205](https://github.com/cosmos/cosmos-sdk/issues/3205) -> for further details. For the remainder of this, I will assume that we only start -> a new slashing period when a validator gets unjailed. - -The maximum number of slashing periods is the `len(UnbondingPeriod) / len(JailPeriod)`. -The current defaults in Gaia for the `UnbondingPeriod` and `JailPeriod` are 3 weeks -and 2 days, respectively. This means there could potentially be up to 11 slashing -periods concurrently being tracked per validator. If we set the `JailPeriod >= UnbondingPeriod`, -we only have to track 1 slashing period (i.e not have to track slashing periods). - -Currently, in the jail period implementation, once a validator unjails, all of -their delegators who are delegated to them (haven't unbonded / redelegated away), -stay with them. Given that consensus safety faults are so egregious -(way more so than liveness faults), it is probably prudent to have delegators not -"auto-rebond" to the validator. - -#### Proposal: infinite jail - -We propose setting the "jail time" for a -validator who commits a consensus safety fault, to `infinite` (i.e. a tombstone state). -This essentially kicks the validator out of the validator set and does not allow -them to re-enter the validator set. All of their delegators (including the operator themselves) -have to either unbond or redelegate away. The validator operator can create a new -validator if they would like, with a new operator key and consensus key, but they -have to "re-earn" their delegations back. - -Implementing the tombstone system and getting rid of the slashing period tracking -will make the `slashing` module way simpler, especially because we can remove all -of the hooks defined in the `slashing` module consumed by the `staking` module -(the `slashing` module still consumes hooks defined in `staking`). - -#### Single slashing amount - -Another optimization that can be made is that if we assume that all ABCI faults -for CometBFT consensus are slashed at the same level, we don't have to keep -track of "max slash". Once an ABCI fault happens, we don't have to worry about -comparing potential future ones to find the max. - -Currently the only CometBFT ABCI fault is: - -* Unjustified precommits (double signs) - -It is currently planned to include the following fault in the near future: - -* Signing a precommit when you're in unbonding phase (needed to make light client bisection safe) - -Given that these faults are both attributable byzantine faults, we will likely -want to slash them equally, and thus we can enact the above change. - -> Note: This change may make sense for current CometBFT consensus, but maybe -> not for a different consensus algorithm or future versions of CometBFT that -> may want to punish at different levels (for example, partial slashing). - -## Parameters - -The slashing module contains the following parameters: - -| Key | Type | Example | -| ----------------------- | -------------- | ---------------------- | -| SignedBlocksWindow | string (int64) | "100" | -| MinSignedPerWindow | string (dec) | "0.500000000000000000" | -| DowntimeJailDuration | string (ns) | "600000000000" | -| SlashFractionDoubleSign | string (dec) | "0.050000000000000000" | -| SlashFractionDowntime | string (dec) | "0.010000000000000000" | - -## CLI - -A user can query and interact with the `slashing` module using the CLI. - -### Query - -The `query` commands allow users to query `slashing` state. - -```shell -simd query slashing --help -``` - -#### params - -The `params` command allows users to query genesis parameters for the slashing module. - -```shell -simd query slashing params [flags] -``` - -Example: - -```shell -simd query slashing params -``` - -Example Output: - -```yml -downtime_jail_duration: 600s -min_signed_per_window: "0.500000000000000000" -signed_blocks_window: "100" -slash_fraction_double_sign: "0.050000000000000000" -slash_fraction_downtime: "0.010000000000000000" -``` - -#### signing-info - -The `signing-info` command allows users to query signing-info of the validator using consensus public key. - -```shell -simd query slashing signing-infos [flags] -``` - -Example: - -```shell -simd query slashing signing-info '{"@type":"/cosmos.crypto.ed25519.PubKey","key":"Auxs3865HpB/EfssYOzfqNhEJjzys6jD5B6tPgC8="}' - -``` - -Example Output: - -```yml -address: cosmosvalcons1nrqsld3aw6lh6t082frdqc84uwxn0t958c -index_offset: "2068" -jailed_until: "1970-01-01T00:00:00Z" -missed_blocks_counter: "0" -start_height: "0" -tombstoned: false -``` - -#### signing-infos - -The `signing-infos` command allows users to query signing infos of all validators. - -```shell -simd query slashing signing-infos [flags] -``` - -Example: - -```shell -simd query slashing signing-infos -``` - -Example Output: - -```yml -info: -- address: cosmosvalcons1nrqsld3aw6lh6t082frdqc84uwxn0t958c - index_offset: "2075" - jailed_until: "1970-01-01T00:00:00Z" - missed_blocks_counter: "0" - start_height: "0" - tombstoned: false -pagination: - next_key: null - total: "0" -``` - -### Transactions - -The `tx` commands allow users to interact with the `slashing` module. - -```bash -simd tx slashing --help -``` - -#### unjail - -The `unjail` command allows users to unjail a validator previously jailed for downtime. - -```bash -simd tx slashing unjail --from mykey [flags] -``` - -Example: - -```bash -simd tx slashing unjail --from mykey -``` - -### gRPC - -A user can query the `slashing` module using gRPC endpoints. - -#### Params - -The `Params` endpoint allows users to query the parameters of slashing module. - -```shell -cosmos.slashing.v1beta1.Query/Params -``` - -Example: - -```shell -grpcurl -plaintext localhost:9090 cosmos.slashing.v1beta1.Query/Params -``` - -Example Output: - -```json -{ - "params": { - "signedBlocksWindow": "100", - "minSignedPerWindow": "NTAwMDAwMDAwMDAwMDAwMDAw", - "downtimeJailDuration": "600s", - "slashFractionDoubleSign": "NTAwMDAwMDAwMDAwMDAwMDA=", - "slashFractionDowntime": "MTAwMDAwMDAwMDAwMDAwMDA=" - } -} -``` - -#### SigningInfo - -The SigningInfo queries the signing info of given cons address. - -```shell -cosmos.slashing.v1beta1.Query/SigningInfo -``` - -Example: - -```shell -grpcurl -plaintext -d '{"cons_address":"cosmosvalcons1nrqsld3aw6lh6t082frdqc84uwxn0t958c"}' localhost:9090 cosmos.slashing.v1beta1.Query/SigningInfo -``` - -Example Output: - -```json -{ - "valSigningInfo": { - "address": "cosmosvalcons1nrqsld3aw6lh6t082frdqc84uwxn0t958c", - "indexOffset": "3493", - "jailedUntil": "1970-01-01T00:00:00Z" - } -} -``` - -#### SigningInfos - -The SigningInfos queries signing info of all validators. - -```shell -cosmos.slashing.v1beta1.Query/SigningInfos -``` - -Example: - -```shell -grpcurl -plaintext localhost:9090 cosmos.slashing.v1beta1.Query/SigningInfos -``` - -Example Output: - -```json -{ - "info": [ - { - "address": "cosmosvalcons1nrqslkwd3pz096lh6t082frdqc84uwxn0t958c", - "indexOffset": "2467", - "jailedUntil": "1970-01-01T00:00:00Z" - } - ], - "pagination": { - "total": "1" - } -} -``` - -### REST - -A user can query the `slashing` module using REST endpoints. - -#### Params - -```shell -/cosmos/slashing/v1beta1/params -``` - -Example: - -```shell -curl "localhost:1317/cosmos/slashing/v1beta1/params" -``` - -Example Output: - -```json -{ - "params": { - "signed_blocks_window": "100", - "min_signed_per_window": "0.500000000000000000", - "downtime_jail_duration": "600s", - "slash_fraction_double_sign": "0.050000000000000000", - "slash_fraction_downtime": "0.010000000000000000" -} -``` - -#### signing_info - -```shell -/cosmos/slashing/v1beta1/signing_infos/%s -``` - -Example: - -```shell -curl "localhost:1317/cosmos/slashing/v1beta1/signing_infos/cosmosvalcons1nrqslkwd3pz096lh6t082frdqc84uwxn0t958c" -``` - -Example Output: - -```json -{ - "val_signing_info": { - "address": "cosmosvalcons1nrqslkwd3pz096lh6t082frdqc84uwxn0t958c", - "start_height": "0", - "index_offset": "4184", - "jailed_until": "1970-01-01T00:00:00Z", - "tombstoned": false, - "missed_blocks_counter": "0" - } -} -``` - -#### signing_infos - -```shell -/cosmos/slashing/v1beta1/signing_infos -``` - -Example: - -```shell -curl "localhost:1317/cosmos/slashing/v1beta1/signing_infos -``` - -Example Output: - -```json -{ - "info": [ - { - "address": "cosmosvalcons1nrqslkwd3pz096lh6t082frdqc84uwxn0t958c", - "start_height": "0", - "index_offset": "4169", - "jailed_until": "1970-01-01T00:00:00Z", - "tombstoned": false, - "missed_blocks_counter": "0" - } - ], - "pagination": { - "next_key": null, - "total": "1" - } -} -``` diff --git a/.gitbook/developers/modules/core/staking/README.md b/.gitbook/developers/modules/core/staking/README.md deleted file mode 100644 index c011a593..00000000 --- a/.gitbook/developers/modules/core/staking/README.md +++ /dev/null @@ -1,3058 +0,0 @@ ---- -sidebar_position: 1 ---- - -# `x/staking` - -## Abstract - -This paper specifies the Staking module of the Cosmos SDK that was first -described in the [Cosmos Whitepaper](https://cosmos.network/about/whitepaper) -in June 2016. - -The module enables Cosmos SDK-based blockchain to support an advanced -Proof-of-Stake (PoS) system. In this system, holders of the native staking token of -the chain can become validators and can delegate tokens to validators, -ultimately determining the effective validator set for the system. - -This module is used in the Cosmos Hub, the first Hub in the Cosmos -network. - -## Contents - -* [State](#state) - * [Pool](#pool) - * [LastTotalPower](#lasttotalpower) - * [ValidatorUpdates](#validatorupdates) - * [UnbondingID](#unbondingid) - * [Params](#params) - * [Validator](#validator) - * [Delegation](#delegation) - * [UnbondingDelegation](#unbondingdelegation) - * [Redelegation](#redelegation) - * [Queues](#queues) - * [HistoricalInfo](#historicalinfo) -* [State Transitions](#state-transitions) - * [Validators](#validators) - * [Delegations](#delegations) - * [Slashing](#slashing) - * [How Shares are calculated](#how-shares-are-calculated) -* [Messages](#messages) - * [MsgCreateValidator](#msgcreatevalidator) - * [MsgEditValidator](#msgeditvalidator) - * [MsgDelegate](#msgdelegate) - * [MsgUndelegate](#msgundelegate) - * [MsgCancelUnbondingDelegation](#msgcancelunbondingdelegation) - * [MsgBeginRedelegate](#msgbeginredelegate) - * [MsgUpdateParams](#msgupdateparams) -* [Begin-Block](#begin-block) - * [Historical Info Tracking](#historical-info-tracking) -* [End-Block](#end-block) - * [Validator Set Changes](#validator-set-changes) - * [Queues](#queues-1) -* [Hooks](#hooks) -* [Events](#events) - * [EndBlocker](#endblocker) - * [Msg's](#msgs) -* [Parameters](#parameters) -* [Client](#client) - * [CLI](#cli) - * [gRPC](#grpc) - * [REST](#rest) - -## State - -### Pool - -Pool is used for tracking bonded and not-bonded token supply of the bond denomination. - -### LastTotalPower - -LastTotalPower tracks the total amounts of bonded tokens recorded during the previous end block. -Store entries prefixed with "Last" must remain unchanged until EndBlock. - -* LastTotalPower: `0x12 -> ProtocolBuffer(math.Int)` - -### ValidatorUpdates - -ValidatorUpdates contains the validator updates returned to ABCI at the end of every block. -The values are overwritten in every block. - -* ValidatorUpdates `0x61 -> []abci.ValidatorUpdate` - -### UnbondingID - -UnbondingID stores the ID of the latest unbonding operation. It enables creating unique IDs for unbonding operations, i.e., UnbondingID is incremented every time a new unbonding operation (validator unbonding, unbonding delegation, redelegation) is initiated. - -* UnbondingID: `0x37 -> uint64` - -### Params - -The staking module stores its params in state with the prefix of `0x51`, -it can be updated with governance or the address with authority. - -* Params: `0x51 | ProtocolBuffer(Params)` - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/staking/v1beta1/staking.proto#L310-L333 -``` - -### Validator - -Validators can have one of three statuses - -* `Unbonded`: The validator is not in the active set. They cannot sign blocks and do not earn - rewards. They can receive delegations. -* `Bonded`: Once the validator receives sufficient bonded tokens they automatically join the - active set during [`EndBlock`](#validator-set-changes) and their status is updated to `Bonded`. - They are signing blocks and receiving rewards. They can receive further delegations. - They can be slashed for misbehavior. Delegators to this validator who unbond their delegation - must wait the duration of the UnbondingTime, a chain-specific param, during which time - they are still slashable for offences of the source validator if those offences were committed - during the period of time that the tokens were bonded. -* `Unbonding`: When a validator leaves the active set, either by choice or due to slashing, jailing or - tombstoning, an unbonding of all their delegations begins. All delegations must then wait the UnbondingTime - before their tokens are moved to their accounts from the `BondedPool`. - -:::warning -Tombstoning is permanent, once tombstoned a validator's consensus key can not be reused within the chain where the tombstoning happened. -::: - -Validators objects should be primarily stored and accessed by the -`OperatorAddr`, an SDK validator address for the operator of the validator. Two -additional indices are maintained per validator object in order to fulfill -required lookups for slashing and validator-set updates. A third special index -(`LastValidatorPower`) is also maintained which however remains constant -throughout each block, unlike the first two indices which mirror the validator -records within a block. - -* Validators: `0x21 | OperatorAddrLen (1 byte) | OperatorAddr -> ProtocolBuffer(validator)` -* ValidatorsByConsAddr: `0x22 | ConsAddrLen (1 byte) | ConsAddr -> OperatorAddr` -* ValidatorsByPower: `0x23 | BigEndian(ConsensusPower) | OperatorAddrLen (1 byte) | OperatorAddr -> OperatorAddr` -* LastValidatorsPower: `0x11 | OperatorAddrLen (1 byte) | OperatorAddr -> ProtocolBuffer(ConsensusPower)` -* ValidatorsByUnbondingID: `0x38 | UnbondingID -> 0x21 | OperatorAddrLen (1 byte) | OperatorAddr` - -`Validators` is the primary index - it ensures that each operator can have only one -associated validator, where the public key of that validator can change in the -future. Delegators can refer to the immutable operator of the validator, without -concern for the changing public key. - -`ValidatorsByUnbondingID` is an additional index that enables lookups for - validators by the unbonding IDs corresponding to their current unbonding. - -`ValidatorByConsAddr` is an additional index that enables lookups for slashing. -When CometBFT reports evidence, it provides the validator address, so this -map is needed to find the operator. Note that the `ConsAddr` corresponds to the -address which can be derived from the validator's `ConsPubKey`. - -`ValidatorsByPower` is an additional index that provides a sorted list of -potential validators to quickly determine the current active set. Here -ConsensusPower is validator.Tokens/10^6 by default. Note that all validators -where `Jailed` is true are not stored within this index. - -`LastValidatorsPower` is a special index that provides a historical list of the -last-block's bonded validators. This index remains constant during a block but -is updated during the validator set update process which takes place in [`EndBlock`](#end-block). - -Each validator's state is stored in a `Validator` struct: - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/staking/v1beta1/staking.proto#L82-L138 -``` - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/staking/v1beta1/staking.proto#L26-L80 -``` - -### Delegation - -Delegations are identified by combining `DelegatorAddr` (the address of the delegator) -with the `ValidatorAddr` Delegators are indexed in the store as follows: - -* Delegation: `0x31 | DelegatorAddrLen (1 byte) | DelegatorAddr | ValidatorAddrLen (1 byte) | ValidatorAddr -> ProtocolBuffer(delegation)` - -Stake holders may delegate coins to validators; under this circumstance their -funds are held in a `Delegation` data structure. It is owned by one -delegator, and is associated with the shares for one validator. The sender of -the transaction is the owner of the bond. - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/staking/v1beta1/staking.proto#L198-L216 -``` - -#### Delegator Shares - -When one delegates tokens to a Validator, they are issued a number of delegator shares based on a -dynamic exchange rate, calculated as follows from the total number of tokens delegated to the -validator and the number of shares issued so far: - -`Shares per Token = validator.TotalShares() / validator.Tokens()` - -Only the number of shares received is stored on the DelegationEntry. When a delegator then -Undelegates, the token amount they receive is calculated from the number of shares they currently -hold and the inverse exchange rate: - -`Tokens per Share = validator.Tokens() / validatorShares()` - -These `Shares` are simply an accounting mechanism. They are not a fungible asset. The reason for -this mechanism is to simplify the accounting around slashing. Rather than iteratively slashing the -tokens of every delegation entry, instead the Validator's total bonded tokens can be slashed, -effectively reducing the value of each issued delegator share. - -### UnbondingDelegation - -Shares in a `Delegation` can be unbonded, but they must for some time exist as -an `UnbondingDelegation`, where shares can be reduced if Byzantine behavior is -detected. - -`UnbondingDelegation` are indexed in the store as: - -* UnbondingDelegation: `0x32 | DelegatorAddrLen (1 byte) | DelegatorAddr | ValidatorAddrLen (1 byte) | ValidatorAddr -> ProtocolBuffer(unbondingDelegation)` -* UnbondingDelegationsFromValidator: `0x33 | ValidatorAddrLen (1 byte) | ValidatorAddr | DelegatorAddrLen (1 byte) | DelegatorAddr -> nil` -* UnbondingDelegationByUnbondingId: `0x38 | UnbondingId -> 0x32 | DelegatorAddrLen (1 byte) | DelegatorAddr | ValidatorAddrLen (1 byte) | ValidatorAddr` - `UnbondingDelegation` is used in queries, to lookup all unbonding delegations for - a given delegator. - -`UnbondingDelegationsFromValidator` is used in slashing, to lookup all - unbonding delegations associated with a given validator that need to be - slashed. - - `UnbondingDelegationByUnbondingId` is an additional index that enables - lookups for unbonding delegations by the unbonding IDs of the containing - unbonding delegation entries. - - -A UnbondingDelegation object is created every time an unbonding is initiated. - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/staking/v1beta1/staking.proto#L218-L261 -``` - -### Redelegation - -The bonded tokens worth of a `Delegation` may be instantly redelegated from a -source validator to a different validator (destination validator). However when -this occurs they must be tracked in a `Redelegation` object, whereby their -shares can be slashed if their tokens have contributed to a Byzantine fault -committed by the source validator. - -`Redelegation` are indexed in the store as: - -* Redelegations: `0x34 | DelegatorAddrLen (1 byte) | DelegatorAddr | ValidatorAddrLen (1 byte) | ValidatorSrcAddr | ValidatorDstAddr -> ProtocolBuffer(redelegation)` -* RedelegationsBySrc: `0x35 | ValidatorSrcAddrLen (1 byte) | ValidatorSrcAddr | ValidatorDstAddrLen (1 byte) | ValidatorDstAddr | DelegatorAddrLen (1 byte) | DelegatorAddr -> nil` -* RedelegationsByDst: `0x36 | ValidatorDstAddrLen (1 byte) | ValidatorDstAddr | ValidatorSrcAddrLen (1 byte) | ValidatorSrcAddr | DelegatorAddrLen (1 byte) | DelegatorAddr -> nil` -* RedelegationByUnbondingId: `0x38 | UnbondingId -> 0x34 | DelegatorAddrLen (1 byte) | DelegatorAddr | ValidatorAddrLen (1 byte) | ValidatorSrcAddr | ValidatorDstAddr` - - `Redelegations` is used for queries, to lookup all redelegations for a given - delegator. - - `RedelegationsBySrc` is used for slashing based on the `ValidatorSrcAddr`. - - `RedelegationsByDst` is used for slashing based on the `ValidatorDstAddr` - -The first map here is used for queries, to lookup all redelegations for a given -delegator. The second map is used for slashing based on the `ValidatorSrcAddr`, -while the third map is for slashing based on the `ValidatorDstAddr`. - -`RedelegationByUnbondingId` is an additional index that enables - lookups for redelegations by the unbonding IDs of the containing - redelegation entries. - -A redelegation object is created every time a redelegation occurs. To prevent -"redelegation hopping" redelegations may not occur under the situation that: - -* the (re)delegator already has another immature redelegation in progress - with a destination to a validator (let's call it `Validator X`) -* and, the (re)delegator is attempting to create a _new_ redelegation - where the source validator for this new redelegation is `Validator X`. - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/staking/v1beta1/staking.proto#L263-L308 -``` - -### Queues - -All queue objects are sorted by timestamp. The time used within any queue is -firstly converted to UTC, rounded to the nearest nanosecond then sorted. The sortable time format -used is a slight modification of the RFC3339Nano and uses the format string -`"2006-01-02T15:04:05.000000000"`. Notably this format: - -* right pads all zeros -* drops the time zone info (we already use UTC) - -In all cases, the stored timestamp represents the maturation time of the queue -element. - -#### UnbondingDelegationQueue - -For the purpose of tracking progress of unbonding delegations the unbonding -delegations queue is kept. - -* UnbondingDelegation: `0x41 | format(time) -> []DVPair` - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/staking/v1beta1/staking.proto#L162-L172 -``` - -#### RedelegationQueue - -For the purpose of tracking progress of redelegations the redelegation queue is -kept. - -* RedelegationQueue: `0x42 | format(time) -> []DVVTriplet` - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/staking/v1beta1/staking.proto#L179-L191 -``` - -#### ValidatorQueue - -For the purpose of tracking progress of unbonding validators the validator -queue is kept. - -* ValidatorQueueTime: `0x43 | format(time) -> []sdk.ValAddress` - -The stored object by each key is an array of validator operator addresses from -which the validator object can be accessed. Typically it is expected that only -a single validator record will be associated with a given timestamp however it is possible -that multiple validators exist in the queue at the same location. - -### HistoricalInfo - -HistoricalInfo objects are stored and pruned at each block such that the staking keeper persists -the `n` most recent historical info defined by staking module parameter: `HistoricalEntries`. - -```go reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/staking/v1beta1/staking.proto#L17-L24 -``` - -At each BeginBlock, the staking keeper will persist the current Header and the Validators that committed -the current block in a `HistoricalInfo` object. The Validators are sorted on their address to ensure that -they are in a deterministic order. -The oldest HistoricalEntries will be pruned to ensure that there only exist the parameter-defined number of -historical entries. - -## State Transitions - -### Validators - -State transitions in validators are performed on every [`EndBlock`](#validator-set-changes) -in order to check for changes in the active `ValidatorSet`. - -A validator can be `Unbonded`, `Unbonding` or `Bonded`. `Unbonded` -and `Unbonding` are collectively called `Not Bonded`. A validator can move -directly between all the states, except for from `Bonded` to `Unbonded`. - -#### Not bonded to Bonded - -The following transition occurs when a validator's ranking in the `ValidatorPowerIndex` surpasses -that of the `LastValidator`. - -* set `validator.Status` to `Bonded` -* send the `validator.Tokens` from the `NotBondedTokens` to the `BondedPool` `ModuleAccount` -* delete the existing record from `ValidatorByPowerIndex` -* add a new updated record to the `ValidatorByPowerIndex` -* update the `Validator` object for this validator -* if it exists, delete any `ValidatorQueue` record for this validator - -#### Bonded to Unbonding - -When a validator begins the unbonding process the following operations occur: - -* send the `validator.Tokens` from the `BondedPool` to the `NotBondedTokens` `ModuleAccount` -* set `validator.Status` to `Unbonding` -* delete the existing record from `ValidatorByPowerIndex` -* add a new updated record to the `ValidatorByPowerIndex` -* update the `Validator` object for this validator -* insert a new record into the `ValidatorQueue` for this validator - -#### Unbonding to Unbonded - -A validator moves from unbonding to unbonded when the `ValidatorQueue` object -moves from bonded to unbonded - -* update the `Validator` object for this validator -* set `validator.Status` to `Unbonded` - -#### Jail/Unjail - -when a validator is jailed it is effectively removed from the CometBFT set. -this process may be also be reversed. the following operations occur: - -* set `Validator.Jailed` and update object -* if jailed delete record from `ValidatorByPowerIndex` -* if unjailed add record to `ValidatorByPowerIndex` - -Jailed validators are not present in any of the following stores: - -* the power store (from consensus power to address) - -### Delegations - -#### Delegate - -When a delegation occurs both the validator and the delegation objects are affected - -* determine the delegators shares based on tokens delegated and the validator's exchange rate -* remove tokens from the sending account -* add shares the delegation object or add them to a created validator object -* add new delegator shares and update the `Validator` object -* transfer the `delegation.Amount` from the delegator's account to the `BondedPool` or the `NotBondedPool` `ModuleAccount` depending if the `validator.Status` is `Bonded` or not -* delete the existing record from `ValidatorByPowerIndex` -* add an new updated record to the `ValidatorByPowerIndex` - -#### Begin Unbonding - -As a part of the Undelegate and Complete Unbonding state transitions Unbond -Delegation may be called. - -* subtract the unbonded shares from delegator -* add the unbonded tokens to an `UnbondingDelegationEntry` -* update the delegation or remove the delegation if there are no more shares -* if the delegation is the operator of the validator and no more shares exist then trigger a jail validator -* update the validator with removed the delegator shares and associated coins -* if the validator state is `Bonded`, transfer the `Coins` worth of the unbonded - shares from the `BondedPool` to the `NotBondedPool` `ModuleAccount` -* remove the validator if it is unbonded and there are no more delegation shares. -* remove the validator if it is unbonded and there are no more delegation shares -* get a unique `unbondingId` and map it to the `UnbondingDelegationEntry` in `UnbondingDelegationByUnbondingId` -* call the `AfterUnbondingInitiated(unbondingId)` hook -* add the unbonding delegation to `UnbondingDelegationQueue` with the completion time set to `UnbondingTime` - -#### Cancel an `UnbondingDelegation` Entry - -When a `cancel unbond delegation` occurs both the `validator`, the `delegation` and an `UnbondingDelegationQueue` state will be updated. - -* if cancel unbonding delegation amount equals to the `UnbondingDelegation` entry `balance`, then the `UnbondingDelegation` entry deleted from `UnbondingDelegationQueue`. -* if the `cancel unbonding delegation amount is less than the `UnbondingDelegation` entry balance, then the `UnbondingDelegation` entry will be updated with new balance in the `UnbondingDelegationQueue`. -* cancel `amount` is [Delegated](#delegations) back to the original `validator`. - -#### Complete Unbonding - -For undelegations which do not complete immediately, the following operations -occur when the unbonding delegation queue element matures: - -* remove the entry from the `UnbondingDelegation` object -* transfer the tokens from the `NotBondedPool` `ModuleAccount` to the delegator `Account` - -#### Begin Redelegation - -Redelegations affect the delegation, source and destination validators. - -* perform an `unbond` delegation from the source validator to retrieve the tokens worth of the unbonded shares -* using the unbonded tokens, `Delegate` them to the destination validator -* if the `sourceValidator.Status` is `Bonded`, and the `destinationValidator` is not, - transfer the newly delegated tokens from the `BondedPool` to the `NotBondedPool` `ModuleAccount` -* otherwise, if the `sourceValidator.Status` is not `Bonded`, and the `destinationValidator` - is `Bonded`, transfer the newly delegated tokens from the `NotBondedPool` to the `BondedPool` `ModuleAccount` -* record the token amount in an new entry in the relevant `Redelegation` - -From when a redelegation begins until it completes, the delegator is in a state of "pseudo-unbonding", and can still be -slashed for infractions that occurred before the redelegation began. - -#### Complete Redelegation - -When a redelegations complete the following occurs: - -* remove the entry from the `Redelegation` object - -### Slashing - -#### Slash Validator - -When a Validator is slashed, the following occurs: - -* The total `slashAmount` is calculated as the `slashFactor` (a chain parameter) \* `TokensFromConsensusPower`, - the total number of tokens bonded to the validator at the time of the infraction. -* Every unbonding delegation and pseudo-unbonding redelegation such that the infraction occured before the unbonding or - redelegation began from the validator are slashed by the `slashFactor` percentage of the initialBalance. -* Each amount slashed from redelegations and unbonding delegations is subtracted from the - total slash amount. -* The `remaingSlashAmount` is then slashed from the validator's tokens in the `BondedPool` or - `NonBondedPool` depending on the validator's status. This reduces the total supply of tokens. - -In the case of a slash due to any infraction that requires evidence to submitted (for example double-sign), the slash -occurs at the block where the evidence is included, not at the block where the infraction occured. -Put otherwise, validators are not slashed retroactively, only when they are caught. - -#### Slash Unbonding Delegation - -When a validator is slashed, so are those unbonding delegations from the validator that began unbonding -after the time of the infraction. Every entry in every unbonding delegation from the validator -is slashed by `slashFactor`. The amount slashed is calculated from the `InitialBalance` of the -delegation and is capped to prevent a resulting negative balance. Completed (or mature) unbondings are not slashed. - -#### Slash Redelegation - -When a validator is slashed, so are all redelegations from the validator that began after the -infraction. Redelegations are slashed by `slashFactor`. -Redelegations that began before the infraction are not slashed. -The amount slashed is calculated from the `InitialBalance` of the delegation and is capped to -prevent a resulting negative balance. -Mature redelegations (that have completed pseudo-unbonding) are not slashed. - -### How Shares are calculated - -At any given point in time, each validator has a number of tokens, `T`, and has a number of shares issued, `S`. -Each delegator, `i`, holds a number of shares, `S_i`. -The number of tokens is the sum of all tokens delegated to the validator, plus the rewards, minus the slashes. - -The delegator is entitled to a portion of the underlying tokens proportional to their proportion of shares. -So delegator `i` is entitled to `T * S_i / S` of the validator's tokens. - -When a delegator delegates new tokens to the validator, they receive a number of shares proportional to their contribution. -So when delegator `j` delegates `T_j` tokens, they receive `S_j = S * T_j / T` shares. -The total number of tokens is now `T + T_j`, and the total number of shares is `S + S_j`. -`j`s proportion of the shares is the same as their proportion of the total tokens contributed: `(S + S_j) / S = (T + T_j) / T`. - -A special case is the initial delegation, when `T = 0` and `S = 0`, so `T_j / T` is undefined. -For the initial delegation, delegator `j` who delegates `T_j` tokens receive `S_j = T_j` shares. -So a validator that hasn't received any rewards and has not been slashed will have `T = S`. - -## Messages - -In this section we describe the processing of the staking messages and the corresponding updates to the state. All created/modified state objects specified by each message are defined within the [state](#state) section. - -### MsgCreateValidator - -A validator is created using the `MsgCreateValidator` message. -The validator must be created with an initial delegation from the operator. - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/staking/v1beta1/tx.proto#L20-L21 -``` - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/staking/v1beta1/tx.proto#L50-L73 -``` - -This message is expected to fail if: - -* another validator with this operator address is already registered -* another validator with this pubkey is already registered -* the initial self-delegation tokens are of a denom not specified as the bonding denom -* the commission parameters are faulty, namely: - * `MaxRate` is either > 1 or < 0 - * the initial `Rate` is either negative or > `MaxRate` - * the initial `MaxChangeRate` is either negative or > `MaxRate` -* the description fields are too large - -This message creates and stores the `Validator` object at appropriate indexes. -Additionally a self-delegation is made with the initial tokens delegation -tokens `Delegation`. The validator always starts as unbonded but may be bonded -in the first end-block. - -### MsgEditValidator - -The `Description`, `CommissionRate` of a validator can be updated using the -`MsgEditValidator` message. - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/staking/v1beta1/tx.proto#L23-L24 -``` - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/staking/v1beta1/tx.proto#L78-L97 -``` - -This message is expected to fail if: - -* the initial `CommissionRate` is either negative or > `MaxRate` -* the `CommissionRate` has already been updated within the previous 24 hours -* the `CommissionRate` is > `MaxChangeRate` -* the description fields are too large - -This message stores the updated `Validator` object. - -### MsgDelegate - -Within this message the delegator provides coins, and in return receives -some amount of their validator's (newly created) delegator-shares that are -assigned to `Delegation.Shares`. - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/staking/v1beta1/tx.proto#L26-L28 -``` - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/staking/v1beta1/tx.proto#L102-L114 -``` - -This message is expected to fail if: - -* the validator does not exist -* the `Amount` `Coin` has a denomination different than one defined by `params.BondDenom` -* the exchange rate is invalid, meaning the validator has no tokens (due to slashing) but there are outstanding shares -* the amount delegated is less than the minimum allowed delegation - -If an existing `Delegation` object for provided addresses does not already -exist then it is created as part of this message otherwise the existing -`Delegation` is updated to include the newly received shares. - -The delegator receives newly minted shares at the current exchange rate. -The exchange rate is the number of existing shares in the validator divided by -the number of currently delegated tokens. - -The validator is updated in the `ValidatorByPower` index, and the delegation is -tracked in validator object in the `Validators` index. - -It is possible to delegate to a jailed validator, the only difference being it -will not be added to the power index until it is unjailed. - -![Delegation sequence](https://raw.githubusercontent.com/cosmos/cosmos-sdk/release/v0.46.x/docs/uml/svg/delegation_sequence.svg) - -### MsgUndelegate - -The `MsgUndelegate` message allows delegators to undelegate their tokens from -validator. - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/staking/v1beta1/tx.proto#L34-L36 -``` - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/staking/v1beta1/tx.proto#L140-L152 -``` - -This message returns a response containing the completion time of the undelegation: - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/staking/v1beta1/tx.proto#L154-L158 -``` - -This message is expected to fail if: - -* the delegation doesn't exist -* the validator doesn't exist -* the delegation has less shares than the ones worth of `Amount` -* existing `UnbondingDelegation` has maximum entries as defined by `params.MaxEntries` -* the `Amount` has a denomination different than one defined by `params.BondDenom` - -When this message is processed the following actions occur: - -* validator's `DelegatorShares` and the delegation's `Shares` are both reduced by the message `SharesAmount` -* calculate the token worth of the shares remove that amount tokens held within the validator -* with those removed tokens, if the validator is: - * `Bonded` - add them to an entry in `UnbondingDelegation` (create `UnbondingDelegation` if it doesn't exist) with a completion time a full unbonding period from the current time. Update pool shares to reduce BondedTokens and increase NotBondedTokens by token worth of the shares. - * `Unbonding` - add them to an entry in `UnbondingDelegation` (create `UnbondingDelegation` if it doesn't exist) with the same completion time as the validator (`UnbondingMinTime`). - * `Unbonded` - then send the coins the message `DelegatorAddr` -* if there are no more `Shares` in the delegation, then the delegation object is removed from the store - * under this situation if the delegation is the validator's self-delegation then also jail the validator. - -![Unbond sequence](https://raw.githubusercontent.com/cosmos/cosmos-sdk/release/v0.46.x/docs/uml/svg/unbond_sequence.svg) - -### MsgCancelUnbondingDelegation - -The `MsgCancelUnbondingDelegation` message allows delegators to cancel the `unbondingDelegation` entry and delegate back to a previous validator. - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/staking/v1beta1/tx.proto#L38-L42 -``` - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/staking/v1beta1/tx.proto#L160-L175 -``` - -This message is expected to fail if: - -* the `unbondingDelegation` entry is already processed. -* the `cancel unbonding delegation` amount is greater than the `unbondingDelegation` entry balance. -* the `cancel unbonding delegation` height doesn't exist in the `unbondingDelegationQueue` of the delegator. - -When this message is processed the following actions occur: - -* if the `unbondingDelegation` Entry balance is zero - * in this condition `unbondingDelegation` entry will be removed from `unbondingDelegationQueue`. - * otherwise `unbondingDelegationQueue` will be updated with new `unbondingDelegation` entry balance and initial balance -* the validator's `DelegatorShares` and the delegation's `Shares` are both increased by the message `Amount`. - -### MsgBeginRedelegate - -The redelegation command allows delegators to instantly switch validators. Once -the unbonding period has passed, the redelegation is automatically completed in -the EndBlocker. - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/staking/v1beta1/tx.proto#L30-L32 -``` - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/staking/v1beta1/tx.proto#L119-L132 -``` - -This message returns a response containing the completion time of the redelegation: - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/staking/v1beta1/tx.proto#L133-L138 -``` - -This message is expected to fail if: - -* the delegation doesn't exist -* the source or destination validators don't exist -* the delegation has less shares than the ones worth of `Amount` -* the source validator has a receiving redelegation which is not matured (aka. the redelegation may be transitive) -* existing `Redelegation` has maximum entries as defined by `params.MaxEntries` -* the `Amount` `Coin` has a denomination different than one defined by `params.BondDenom` - -When this message is processed the following actions occur: - -* the source validator's `DelegatorShares` and the delegations `Shares` are both reduced by the message `SharesAmount` -* calculate the token worth of the shares remove that amount tokens held within the source validator. -* if the source validator is: - * `Bonded` - add an entry to the `Redelegation` (create `Redelegation` if it doesn't exist) with a completion time a full unbonding period from the current time. Update pool shares to reduce BondedTokens and increase NotBondedTokens by token worth of the shares (this may be effectively reversed in the next step however). - * `Unbonding` - add an entry to the `Redelegation` (create `Redelegation` if it doesn't exist) with the same completion time as the validator (`UnbondingMinTime`). - * `Unbonded` - no action required in this step -* Delegate the token worth to the destination validator, possibly moving tokens back to the bonded state. -* if there are no more `Shares` in the source delegation, then the source delegation object is removed from the store - * under this situation if the delegation is the validator's self-delegation then also jail the validator. - -![Begin redelegation sequence](https://raw.githubusercontent.com/cosmos/cosmos-sdk/release/v0.46.x/docs/uml/svg/begin_redelegation_sequence.svg) - - -### MsgUpdateParams - -The `MsgUpdateParams` update the staking module parameters. -The params are updated through a governance proposal where the signer is the gov module account address. - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/staking/v1beta1/tx.proto#L182-L195 -``` - -The message handling can fail if: - -* signer is not the authority defined in the staking keeper (usually the gov module account). - -## Begin-Block - -Each abci begin block call, the historical info will get stored and pruned -according to the `HistoricalEntries` parameter. - -### Historical Info Tracking - -If the `HistoricalEntries` parameter is 0, then the `BeginBlock` performs a no-op. - -Otherwise, the latest historical info is stored under the key `historicalInfoKey|height`, while any entries older than `height - HistoricalEntries` is deleted. -In most cases, this results in a single entry being pruned per block. -However, if the parameter `HistoricalEntries` has changed to a lower value there will be multiple entries in the store that must be pruned. - -## End-Block - -Each abci end block call, the operations to update queues and validator set -changes are specified to execute. - -### Validator Set Changes - -The staking validator set is updated during this process by state transitions -that run at the end of every block. As a part of this process any updated -validators are also returned back to CometBFT for inclusion in the CometBFT -validator set which is responsible for validating CometBFT messages at the -consensus layer. Operations are as following: - -* the new validator set is taken as the top `params.MaxValidators` number of - validators retrieved from the `ValidatorsByPower` index -* the previous validator set is compared with the new validator set: - * missing validators begin unbonding and their `Tokens` are transferred from the - `BondedPool` to the `NotBondedPool` `ModuleAccount` - * new validators are instantly bonded and their `Tokens` are transferred from the - `NotBondedPool` to the `BondedPool` `ModuleAccount` - -In all cases, any validators leaving or entering the bonded validator set or -changing balances and staying within the bonded validator set incur an update -message reporting their new consensus power which is passed back to CometBFT. - -The `LastTotalPower` and `LastValidatorsPower` hold the state of the total power -and validator power from the end of the last block, and are used to check for -changes that have occurred in `ValidatorsByPower` and the total new power, which -is calculated during `EndBlock`. - -### Queues - -Within staking, certain state-transitions are not instantaneous but take place -over a duration of time (typically the unbonding period). When these -transitions are mature certain operations must take place in order to complete -the state operation. This is achieved through the use of queues which are -checked/processed at the end of each block. - -#### Unbonding Validators - -When a validator is kicked out of the bonded validator set (either through -being jailed, or not having sufficient bonded tokens) it begins the unbonding -process along with all its delegations begin unbonding (while still being -delegated to this validator). At this point the validator is said to be an -"unbonding validator", whereby it will mature to become an "unbonded validator" -after the unbonding period has passed. - -Each block the validator queue is to be checked for mature unbonding validators -(namely with a completion time <= current time and completion height <= current -block height). At this point any mature validators which do not have any -delegations remaining are deleted from state. For all other mature unbonding -validators that still have remaining delegations, the `validator.Status` is -switched from `types.Unbonding` to -`types.Unbonded`. - -Unbonding operations can be put on hold by external modules via the `PutUnbondingOnHold(unbondingId)` method. - As a result, an unbonding operation (e.g., an unbonding delegation) that is on hold, cannot complete - even if it reaches maturity. For an unbonding operation with `unbondingId` to eventually complete - (after it reaches maturity), every call to `PutUnbondingOnHold(unbondingId)` must be matched - by a call to `UnbondingCanComplete(unbondingId)`. - -#### Unbonding Delegations - -Complete the unbonding of all mature `UnbondingDelegations.Entries` within the -`UnbondingDelegations` queue with the following procedure: - -* transfer the balance coins to the delegator's wallet address -* remove the mature entry from `UnbondingDelegation.Entries` -* remove the `UnbondingDelegation` object from the store if there are no - remaining entries. - -#### Redelegations - -Complete the unbonding of all mature `Redelegation.Entries` within the -`Redelegations` queue with the following procedure: - -* remove the mature entry from `Redelegation.Entries` -* remove the `Redelegation` object from the store if there are no - remaining entries. - -## Hooks - -Other modules may register operations to execute when a certain event has -occurred within staking. These events can be registered to execute either -right `Before` or `After` the staking event (as per the hook name). The -following hooks can registered with staking: - -* `AfterValidatorCreated(Context, ValAddress) error` - * called when a validator is created -* `BeforeValidatorModified(Context, ValAddress) error` - * called when a validator's state is changed -* `AfterValidatorRemoved(Context, ConsAddress, ValAddress) error` - * called when a validator is deleted -* `AfterValidatorBonded(Context, ConsAddress, ValAddress) error` - * called when a validator is bonded -* `AfterValidatorBeginUnbonding(Context, ConsAddress, ValAddress) error` - * called when a validator begins unbonding -* `BeforeDelegationCreated(Context, AccAddress, ValAddress) error` - * called when a delegation is created -* `BeforeDelegationSharesModified(Context, AccAddress, ValAddress) error` - * called when a delegation's shares are modified -* `AfterDelegationModified(Context, AccAddress, ValAddress) error` - * called when a delegation is created or modified -* `BeforeDelegationRemoved(Context, AccAddress, ValAddress) error` - * called when a delegation is removed -* `AfterUnbondingInitiated(Context, UnbondingID)` - * called when an unbonding operation (validator unbonding, unbonding delegation, redelegation) was initiated - - -## Events - -The staking module emits the following events: - -### EndBlocker - -| Type | Attribute Key | Attribute Value | -| --------------------- | --------------------- | ------------------------- | -| complete_unbonding | amount | {totalUnbondingAmount} | -| complete_unbonding | validator | {validatorAddress} | -| complete_unbonding | delegator | {delegatorAddress} | -| complete_redelegation | amount | {totalRedelegationAmount} | -| complete_redelegation | source_validator | {srcValidatorAddress} | -| complete_redelegation | destination_validator | {dstValidatorAddress} | -| complete_redelegation | delegator | {delegatorAddress} | - -## Msg's - -### MsgCreateValidator - -| Type | Attribute Key | Attribute Value | -| ---------------- | ------------- | ------------------ | -| create_validator | validator | {validatorAddress} | -| create_validator | amount | {delegationAmount} | -| message | module | staking | -| message | action | create_validator | -| message | sender | {senderAddress} | - -### MsgEditValidator - -| Type | Attribute Key | Attribute Value | -| -------------- | ------------------- | ------------------- | -| edit_validator | commission_rate | {commissionRate} | -| edit_validator | min_self_delegation | {minSelfDelegation} | -| message | module | staking | -| message | action | edit_validator | -| message | sender | {senderAddress} | - -### MsgDelegate - -| Type | Attribute Key | Attribute Value | -| -------- | ------------- | ------------------ | -| delegate | validator | {validatorAddress} | -| delegate | amount | {delegationAmount} | -| message | module | staking | -| message | action | delegate | -| message | sender | {senderAddress} | - -### MsgUndelegate - -| Type | Attribute Key | Attribute Value | -| ------- | ------------------- | ------------------ | -| unbond | validator | {validatorAddress} | -| unbond | amount | {unbondAmount} | -| unbond | completion_time [0] | {completionTime} | -| message | module | staking | -| message | action | begin_unbonding | -| message | sender | {senderAddress} | - -* [0] Time is formatted in the RFC3339 standard - -### MsgCancelUnbondingDelegation - -| Type | Attribute Key | Attribute Value | -| ----------------------------- | ------------------ | ------------------------------------| -| cancel_unbonding_delegation | validator | {validatorAddress} | -| cancel_unbonding_delegation | delegator | {delegatorAddress} | -| cancel_unbonding_delegation | amount | {cancelUnbondingDelegationAmount} | -| cancel_unbonding_delegation | creation_height | {unbondingCreationHeight} | -| message | module | staking | -| message | action | cancel_unbond | -| message | sender | {senderAddress} | - -### MsgBeginRedelegate - -| Type | Attribute Key | Attribute Value | -| ---------- | --------------------- | --------------------- | -| redelegate | source_validator | {srcValidatorAddress} | -| redelegate | destination_validator | {dstValidatorAddress} | -| redelegate | amount | {unbondAmount} | -| redelegate | completion_time [0] | {completionTime} | -| message | module | staking | -| message | action | begin_redelegate | -| message | sender | {senderAddress} | - -* [0] Time is formatted in the RFC3339 standard - -## Parameters - -The staking module contains the following parameters: - -| Key | Type | Example | -|-------------------|------------------|------------------------| -| UnbondingTime | string (time ns) | "259200000000000" | -| MaxValidators | uint16 | 100 | -| KeyMaxEntries | uint16 | 7 | -| HistoricalEntries | uint16 | 3 | -| BondDenom | string | "stake" | -| MinCommissionRate | string | "0.000000000000000000" | - -## Client - -### CLI - -A user can query and interact with the `staking` module using the CLI. - -#### Query - -The `query` commands allows users to query `staking` state. - -```bash -simd query staking --help -``` - -##### delegation - -The `delegation` command allows users to query delegations for an individual delegator on an individual validator. - -Usage: - -```bash -simd query staking delegation [delegator-addr] [validator-addr] [flags] -``` - -Example: - -```bash -simd query staking delegation cosmos1gghjut3ccd8ay0zduzj64hwre2fxs9ld75ru9p cosmosvaloper1gghjut3ccd8ay0zduzj64hwre2fxs9ldmqhffj -``` - -Example Output: - -```bash -balance: - amount: "10000000000" - denom: stake -delegation: - delegator_address: cosmos1gghjut3ccd8ay0zduzj64hwre2fxs9ld75ru9p - shares: "10000000000.000000000000000000" - validator_address: cosmosvaloper1gghjut3ccd8ay0zduzj64hwre2fxs9ldmqhffj -``` - -##### delegations - -The `delegations` command allows users to query delegations for an individual delegator on all validators. - -Usage: - -```bash -simd query staking delegations [delegator-addr] [flags] -``` - -Example: - -```bash -simd query staking delegations cosmos1gghjut3ccd8ay0zduzj64hwre2fxs9ld75ru9p -``` - -Example Output: - -```bash -delegation_responses: -- balance: - amount: "10000000000" - denom: stake - delegation: - delegator_address: cosmos1gghjut3ccd8ay0zduzj64hwre2fxs9ld75ru9p - shares: "10000000000.000000000000000000" - validator_address: cosmosvaloper1gghjut3ccd8ay0zduzj64hwre2fxs9ldmqhffj -- balance: - amount: "10000000000" - denom: stake - delegation: - delegator_address: cosmos1gghjut3ccd8ay0zduzj64hwre2fxs9ld75ru9p - shares: "10000000000.000000000000000000" - validator_address: cosmosvaloper1x20lytyf6zkcrv5edpkfkn8sz578qg5sqfyqnp -pagination: - next_key: null - total: "0" -``` - -##### delegations-to - -The `delegations-to` command allows users to query delegations on an individual validator. - -Usage: - -```bash -simd query staking delegations-to [validator-addr] [flags] -``` - -Example: - -```bash -simd query staking delegations-to cosmosvaloper1gghjut3ccd8ay0zduzj64hwre2fxs9ldmqhffj -``` - -Example Output: - -```bash -- balance: - amount: "504000000" - denom: stake - delegation: - delegator_address: cosmos1q2qwwynhv8kh3lu5fkeex4awau9x8fwt45f5cp - shares: "504000000.000000000000000000" - validator_address: cosmosvaloper1gghjut3ccd8ay0zduzj64hwre2fxs9ldmqhffj -- balance: - amount: "78125000000" - denom: uixo - delegation: - delegator_address: cosmos1qvppl3479hw4clahe0kwdlfvf8uvjtcd99m2ca - shares: "78125000000.000000000000000000" - validator_address: cosmosvaloper1gghjut3ccd8ay0zduzj64hwre2fxs9ldmqhffj -pagination: - next_key: null - total: "0" -``` - -##### historical-info - -The `historical-info` command allows users to query historical information at given height. - -Usage: - -```bash -simd query staking historical-info [height] [flags] -``` - -Example: - -```bash -simd query staking historical-info 10 -``` - -Example Output: - -```bash -header: - app_hash: Lbx8cXpI868wz8sgp4qPYVrlaKjevR5WP/IjUxwp3oo= - chain_id: testnet - consensus_hash: BICRvH3cKD93v7+R1zxE2ljD34qcvIZ0Bdi389qtoi8= - data_hash: 47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU= - evidence_hash: 47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU= - height: "10" - last_block_id: - hash: RFbkpu6pWfSThXxKKl6EZVDnBSm16+U0l0xVjTX08Fk= - part_set_header: - hash: vpIvXD4rxD5GM4MXGz0Sad9I7//iVYLzZsEU4BVgWIU= - total: 1 - last_commit_hash: Ne4uXyx4QtNp4Zx89kf9UK7oG9QVbdB6e7ZwZkhy8K0= - last_results_hash: 47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU= - next_validators_hash: nGBgKeWBjoxeKFti00CxHsnULORgKY4LiuQwBuUrhCs= - proposer_address: mMEP2c2IRPLr99LedSRtBg9eONM= - time: "2021-10-01T06:00:49.785790894Z" - validators_hash: nGBgKeWBjoxeKFti00CxHsnULORgKY4LiuQwBuUrhCs= - version: - app: "0" - block: "11" -valset: -- commission: - commission_rates: - max_change_rate: "0.010000000000000000" - max_rate: "0.200000000000000000" - rate: "0.100000000000000000" - update_time: "2021-10-01T05:52:50.380144238Z" - consensus_pubkey: - '@type': /cosmos.crypto.ed25519.PubKey - key: Auxs3865HpB/EfssYOzfqNhEJjzys2Fo6jD5B8tPgC8= - delegator_shares: "10000000.000000000000000000" - description: - details: "" - identity: "" - moniker: myvalidator - security_contact: "" - website: "" - jailed: false - min_self_delegation: "1" - operator_address: cosmosvaloper1rne8lgs98p0jqe82sgt0qr4rdn4hgvmgp9ggcc - status: BOND_STATUS_BONDED - tokens: "10000000" - unbonding_height: "0" - unbonding_time: "1970-01-01T00:00:00Z" -``` - -##### params - -The `params` command allows users to query values set as staking parameters. - -Usage: - -```bash -simd query staking params [flags] -``` - -Example: - -```bash -simd query staking params -``` - -Example Output: - -```bash -bond_denom: stake -historical_entries: 10000 -max_entries: 7 -max_validators: 50 -unbonding_time: 1814400s -``` - -##### pool - -The `pool` command allows users to query values for amounts stored in the staking pool. - -Usage: - -```bash -simd q staking pool [flags] -``` - -Example: - -```bash -simd q staking pool -``` - -Example Output: - -```bash -bonded_tokens: "10000000" -not_bonded_tokens: "0" -``` - -##### redelegation - -The `redelegation` command allows users to query a redelegation record based on delegator and a source and destination validator address. - -Usage: - -```bash -simd query staking redelegation [delegator-addr] [src-validator-addr] [dst-validator-addr] [flags] -``` - -Example: - -```bash -simd query staking redelegation cosmos1gghjut3ccd8ay0zduzj64hwre2fxs9ld75ru9p cosmosvaloper1l2rsakp388kuv9k8qzq6lrm9taddae7fpx59wm cosmosvaloper1gghjut3ccd8ay0zduzj64hwre2fxs9ldmqhffj -``` - -Example Output: - -```bash -pagination: null -redelegation_responses: -- entries: - - balance: "50000000" - redelegation_entry: - completion_time: "2021-10-24T20:33:21.960084845Z" - creation_height: 2.382847e+06 - initial_balance: "50000000" - shares_dst: "50000000.000000000000000000" - - balance: "5000000000" - redelegation_entry: - completion_time: "2021-10-25T21:33:54.446846862Z" - creation_height: 2.397271e+06 - initial_balance: "5000000000" - shares_dst: "5000000000.000000000000000000" - redelegation: - delegator_address: cosmos1gghjut3ccd8ay0zduzj64hwre2fxs9ld75ru9p - entries: null - validator_dst_address: cosmosvaloper1l2rsakp388kuv9k8qzq6lrm9taddae7fpx59wm - validator_src_address: cosmosvaloper1l2rsakp388kuv9k8qzq6lrm9taddae7fpx59wm -``` - -##### redelegations - -The `redelegations` command allows users to query all redelegation records for an individual delegator. - -Usage: - -```bash -simd query staking redelegations [delegator-addr] [flags] -``` - -Example: - -```bash -simd query staking redelegation cosmos1gghjut3ccd8ay0zduzj64hwre2fxs9ld75ru9p -``` - -Example Output: - -```bash -pagination: - next_key: null - total: "0" -redelegation_responses: -- entries: - - balance: "50000000" - redelegation_entry: - completion_time: "2021-10-24T20:33:21.960084845Z" - creation_height: 2.382847e+06 - initial_balance: "50000000" - shares_dst: "50000000.000000000000000000" - - balance: "5000000000" - redelegation_entry: - completion_time: "2021-10-25T21:33:54.446846862Z" - creation_height: 2.397271e+06 - initial_balance: "5000000000" - shares_dst: "5000000000.000000000000000000" - redelegation: - delegator_address: cosmos1gghjut3ccd8ay0zduzj64hwre2fxs9ld75ru9p - entries: null - validator_dst_address: cosmosvaloper1uccl5ugxrm7vqlzwqr04pjd320d2fz0z3hc6vm - validator_src_address: cosmosvaloper1zppjyal5emta5cquje8ndkpz0rs046m7zqxrpp -- entries: - - balance: "562770000000" - redelegation_entry: - completion_time: "2021-10-25T21:42:07.336911677Z" - creation_height: 2.39735e+06 - initial_balance: "562770000000" - shares_dst: "562770000000.000000000000000000" - redelegation: - delegator_address: cosmos1gghjut3ccd8ay0zduzj64hwre2fxs9ld75ru9p - entries: null - validator_dst_address: cosmosvaloper1uccl5ugxrm7vqlzwqr04pjd320d2fz0z3hc6vm - validator_src_address: cosmosvaloper1zppjyal5emta5cquje8ndkpz0rs046m7zqxrpp -``` - -##### redelegations-from - -The `redelegations-from` command allows users to query delegations that are redelegating _from_ a validator. - -Usage: - -```bash -simd query staking redelegations-from [validator-addr] [flags] -``` - -Example: - -```bash -simd query staking redelegations-from cosmosvaloper1y4rzzrgl66eyhzt6gse2k7ej3zgwmngeleucjy -``` - -Example Output: - -```bash -pagination: - next_key: null - total: "0" -redelegation_responses: -- entries: - - balance: "50000000" - redelegation_entry: - completion_time: "2021-10-24T20:33:21.960084845Z" - creation_height: 2.382847e+06 - initial_balance: "50000000" - shares_dst: "50000000.000000000000000000" - - balance: "5000000000" - redelegation_entry: - completion_time: "2021-10-25T21:33:54.446846862Z" - creation_height: 2.397271e+06 - initial_balance: "5000000000" - shares_dst: "5000000000.000000000000000000" - redelegation: - delegator_address: cosmos1pm6e78p4pgn0da365plzl4t56pxy8hwtqp2mph - entries: null - validator_dst_address: cosmosvaloper1uccl5ugxrm7vqlzwqr04pjd320d2fz0z3hc6vm - validator_src_address: cosmosvaloper1y4rzzrgl66eyhzt6gse2k7ej3zgwmngeleucjy -- entries: - - balance: "221000000" - redelegation_entry: - completion_time: "2021-10-05T21:05:45.669420544Z" - creation_height: 2.120693e+06 - initial_balance: "221000000" - shares_dst: "221000000.000000000000000000" - redelegation: - delegator_address: cosmos1zqv8qxy2zgn4c58fz8jt8jmhs3d0attcussrf6 - entries: null - validator_dst_address: cosmosvaloper10mseqwnwtjaqfrwwp2nyrruwmjp6u5jhah4c3y - validator_src_address: cosmosvaloper1y4rzzrgl66eyhzt6gse2k7ej3zgwmngeleucjy -``` - -##### unbonding-delegation - -The `unbonding-delegation` command allows users to query unbonding delegations for an individual delegator on an individual validator. - -Usage: - -```bash -simd query staking unbonding-delegation [delegator-addr] [validator-addr] [flags] -``` - -Example: - -```bash -simd query staking unbonding-delegation cosmos1gghjut3ccd8ay0zduzj64hwre2fxs9ld75ru9p cosmosvaloper1gghjut3ccd8ay0zduzj64hwre2fxs9ldmqhffj -``` - -Example Output: - -```bash -delegator_address: cosmos1gghjut3ccd8ay0zduzj64hwre2fxs9ld75ru9p -entries: -- balance: "52000000" - completion_time: "2021-11-02T11:35:55.391594709Z" - creation_height: "55078" - initial_balance: "52000000" -validator_address: cosmosvaloper1gghjut3ccd8ay0zduzj64hwre2fxs9ldmqhffj -``` - -##### unbonding-delegations - -The `unbonding-delegations` command allows users to query all unbonding-delegations records for one delegator. - -Usage: - -```bash -simd query staking unbonding-delegations [delegator-addr] [flags] -``` - -Example: - -```bash -simd query staking unbonding-delegations cosmos1gghjut3ccd8ay0zduzj64hwre2fxs9ld75ru9p -``` - -Example Output: - -```bash -pagination: - next_key: null - total: "0" -unbonding_responses: -- delegator_address: cosmos1gghjut3ccd8ay0zduzj64hwre2fxs9ld75ru9p - entries: - - balance: "52000000" - completion_time: "2021-11-02T11:35:55.391594709Z" - creation_height: "55078" - initial_balance: "52000000" - validator_address: cosmosvaloper1t8ehvswxjfn3ejzkjtntcyrqwvmvuknzmvtaaa - -``` - -##### unbonding-delegations-from - -The `unbonding-delegations-from` command allows users to query delegations that are unbonding _from_ a validator. - -Usage: - -```bash -simd query staking unbonding-delegations-from [validator-addr] [flags] -``` - -Example: - -```bash -simd query staking unbonding-delegations-from cosmosvaloper1gghjut3ccd8ay0zduzj64hwre2fxs9ldmqhffj -``` - -Example Output: - -```bash -pagination: - next_key: null - total: "0" -unbonding_responses: -- delegator_address: cosmos1qqq9txnw4c77sdvzx0tkedsafl5s3vk7hn53fn - entries: - - balance: "150000000" - completion_time: "2021-11-01T21:41:13.098141574Z" - creation_height: "46823" - initial_balance: "150000000" - validator_address: cosmosvaloper1gghjut3ccd8ay0zduzj64hwre2fxs9ldmqhffj -- delegator_address: cosmos1peteje73eklqau66mr7h7rmewmt2vt99y24f5z - entries: - - balance: "24000000" - completion_time: "2021-10-31T02:57:18.192280361Z" - creation_height: "21516" - initial_balance: "24000000" - validator_address: cosmosvaloper1gghjut3ccd8ay0zduzj64hwre2fxs9ldmqhffj -``` - -##### validator - -The `validator` command allows users to query details about an individual validator. - -Usage: - -```bash -simd query staking validator [validator-addr] [flags] -``` - -Example: - -```bash -simd query staking validator cosmosvaloper1gghjut3ccd8ay0zduzj64hwre2fxs9ldmqhffj -``` - -Example Output: - -```bash -commission: - commission_rates: - max_change_rate: "0.020000000000000000" - max_rate: "0.200000000000000000" - rate: "0.050000000000000000" - update_time: "2021-10-01T19:24:52.663191049Z" -consensus_pubkey: - '@type': /cosmos.crypto.ed25519.PubKey - key: sIiexdJdYWn27+7iUHQJDnkp63gq/rzUq1Y+fxoGjXc= -delegator_shares: "32948270000.000000000000000000" -description: - details: Witval is the validator arm from Vitwit. Vitwit is into software consulting - and services business since 2015. We are working closely with Cosmos ecosystem - since 2018. We are also building tools for the ecosystem, Aneka is our explorer - for the cosmos ecosystem. - identity: 51468B615127273A - moniker: Witval - security_contact: "" - website: "" -jailed: false -min_self_delegation: "1" -operator_address: cosmosvaloper1gghjut3ccd8ay0zduzj64hwre2fxs9ldmqhffj -status: BOND_STATUS_BONDED -tokens: "32948270000" -unbonding_height: "0" -unbonding_time: "1970-01-01T00:00:00Z" -``` - -##### validators - -The `validators` command allows users to query details about all validators on a network. - -Usage: - -```bash -simd query staking validators [flags] -``` - -Example: - -```bash -simd query staking validators -``` - -Example Output: - -```bash -pagination: - next_key: FPTi7TKAjN63QqZh+BaXn6gBmD5/ - total: "0" -validators: -commission: - commission_rates: - max_change_rate: "0.020000000000000000" - max_rate: "0.200000000000000000" - rate: "0.050000000000000000" - update_time: "2021-10-01T19:24:52.663191049Z" -consensus_pubkey: - '@type': /cosmos.crypto.ed25519.PubKey - key: sIiexdJdYWn27+7iUHQJDnkp63gq/rzUq1Y+fxoGjXc= -delegator_shares: "32948270000.000000000000000000" -description: - details: Witval is the validator arm from Vitwit. Vitwit is into software consulting - and services business since 2015. We are working closely with Cosmos ecosystem - since 2018. We are also building tools for the ecosystem, Aneka is our explorer - for the cosmos ecosystem. - identity: 51468B615127273A - moniker: Witval - security_contact: "" - website: "" - jailed: false - min_self_delegation: "1" - operator_address: cosmosvaloper1gghjut3ccd8ay0zduzj64hwre2fxs9ldmqhffj - status: BOND_STATUS_BONDED - tokens: "32948270000" - unbonding_height: "0" - unbonding_time: "1970-01-01T00:00:00Z" -- commission: - commission_rates: - max_change_rate: "0.100000000000000000" - max_rate: "0.200000000000000000" - rate: "0.050000000000000000" - update_time: "2021-10-04T18:02:21.446645619Z" - consensus_pubkey: - '@type': /cosmos.crypto.ed25519.PubKey - key: GDNpuKDmCg9GnhnsiU4fCWktuGUemjNfvpCZiqoRIYA= - delegator_shares: "559343421.000000000000000000" - description: - details: Noderunners is a professional validator in POS networks. We have a huge - node running experience, reliable soft and hardware. Our commissions are always - low, our support to delegators is always full. Stake with us and start receiving - your Cosmos rewards now! - identity: 812E82D12FEA3493 - moniker: Noderunners - security_contact: info@noderunners.biz - website: http://noderunners.biz - jailed: false - min_self_delegation: "1" - operator_address: cosmosvaloper1q5ku90atkhktze83j9xjaks2p7uruag5zp6wt7 - status: BOND_STATUS_BONDED - tokens: "559343421" - unbonding_height: "0" - unbonding_time: "1970-01-01T00:00:00Z" -``` - -#### Transactions - -The `tx` commands allows users to interact with the `staking` module. - -```bash -simd tx staking --help -``` - -##### create-validator - -The command `create-validator` allows users to create new validator initialized with a self-delegation to it. - -Usage: - -```bash -simd tx staking create-validator [path/to/validator.json] [flags] -``` - -Example: - -```bash -simd tx staking create-validator /path/to/validator.json \ - --chain-id="name_of_chain_id" \ - --gas="auto" \ - --gas-adjustment="1.2" \ - --gas-prices="0.025stake" \ - --from=mykey -``` - -where `validator.json` contains: - -```json -{ - "pubkey": {"@type":"/cosmos.crypto.ed25519.PubKey","key":"BnbwFpeONLqvWqJb3qaUbL5aoIcW3fSuAp9nT3z5f20="}, - "amount": "1000000stake", - "moniker": "my-moniker", - "website": "https://myweb.site", - "security": "security-contact@gmail.com", - "details": "description of your validator", - "commission-rate": "0.10", - "commission-max-rate": "0.20", - "commission-max-change-rate": "0.01", - "min-self-delegation": "1" -} -``` - -and pubkey can be obtained by using `simd tendermint show-validator` command. - -##### delegate - -The command `delegate` allows users to delegate liquid tokens to a validator. - -Usage: - -```bash -simd tx staking delegate [validator-addr] [amount] [flags] -``` - -Example: - -```bash -simd tx staking delegate cosmosvaloper1l2rsakp388kuv9k8qzq6lrm9taddae7fpx59wm 1000stake --from mykey -``` - -##### edit-validator - -The command `edit-validator` allows users to edit an existing validator account. - -Usage: - -```bash -simd tx staking edit-validator [flags] -``` - -Example: - -```bash -simd tx staking edit-validator --moniker "new_moniker_name" --website "new_webiste_url" --from mykey -``` - -##### redelegate - -The command `redelegate` allows users to redelegate illiquid tokens from one validator to another. - -Usage: - -```bash -simd tx staking redelegate [src-validator-addr] [dst-validator-addr] [amount] [flags] -``` - -Example: - -```bash -simd tx staking redelegate cosmosvaloper1gghjut3ccd8ay0zduzj64hwre2fxs9ldmqhffj cosmosvaloper1l2rsakp388kuv9k8qzq6lrm9taddae7fpx59wm 100stake --from mykey -``` - -##### unbond - -The command `unbond` allows users to unbond shares from a validator. - -Usage: - -```bash -simd tx staking unbond [validator-addr] [amount] [flags] -``` - -Example: - -```bash -simd tx staking unbond cosmosvaloper1gghjut3ccd8ay0zduzj64hwre2fxs9ldmqhffj 100stake --from mykey -``` - -##### cancel unbond - -The command `cancel-unbond` allow users to cancel the unbonding delegation entry and delegate back to the original validator. - -Usage: - -```bash -simd tx staking cancel-unbond [validator-addr] [amount] [creation-height] -``` - -Example: - -```bash -simd tx staking cancel-unbond cosmosvaloper1gghjut3ccd8ay0zduzj64hwre2fxs9ldmqhffj 100stake 123123 --from mykey -``` - - -### gRPC - -A user can query the `staking` module using gRPC endpoints. - -#### Validators - -The `Validators` endpoint queries all validators that match the given status. - -```bash -cosmos.staking.v1beta1.Query/Validators -``` - -Example: - -```bash -grpcurl -plaintext localhost:9090 cosmos.staking.v1beta1.Query/Validators -``` - -Example Output: - -```bash -{ - "validators": [ - { - "operatorAddress": "cosmosvaloper1rne8lgs98p0jqe82sgt0qr4rdn4hgvmgp9ggcc", - "consensusPubkey": {"@type":"/cosmos.crypto.ed25519.PubKey","key":"Auxs3865HpB/EfssYOzfqNhEJjzys2Fo6jD5B8tPgC8="}, - "status": "BOND_STATUS_BONDED", - "tokens": "10000000", - "delegatorShares": "10000000000000000000000000", - "description": { - "moniker": "myvalidator" - }, - "unbondingTime": "1970-01-01T00:00:00Z", - "commission": { - "commissionRates": { - "rate": "100000000000000000", - "maxRate": "200000000000000000", - "maxChangeRate": "10000000000000000" - }, - "updateTime": "2021-10-01T05:52:50.380144238Z" - }, - "minSelfDelegation": "1" - } - ], - "pagination": { - "total": "1" - } -} -``` - -#### Validator - -The `Validator` endpoint queries validator information for given validator address. - -```bash -cosmos.staking.v1beta1.Query/Validator -``` - -Example: - -```bash -grpcurl -plaintext -d '{"validator_addr":"cosmosvaloper1rne8lgs98p0jqe82sgt0qr4rdn4hgvmgp9ggcc"}' \ -localhost:9090 cosmos.staking.v1beta1.Query/Validator -``` - -Example Output: - -```bash -{ - "validator": { - "operatorAddress": "cosmosvaloper1rne8lgs98p0jqe82sgt0qr4rdn4hgvmgp9ggcc", - "consensusPubkey": {"@type":"/cosmos.crypto.ed25519.PubKey","key":"Auxs3865HpB/EfssYOzfqNhEJjzys2Fo6jD5B8tPgC8="}, - "status": "BOND_STATUS_BONDED", - "tokens": "10000000", - "delegatorShares": "10000000000000000000000000", - "description": { - "moniker": "myvalidator" - }, - "unbondingTime": "1970-01-01T00:00:00Z", - "commission": { - "commissionRates": { - "rate": "100000000000000000", - "maxRate": "200000000000000000", - "maxChangeRate": "10000000000000000" - }, - "updateTime": "2021-10-01T05:52:50.380144238Z" - }, - "minSelfDelegation": "1" - } -} -``` - -#### ValidatorDelegations - -The `ValidatorDelegations` endpoint queries delegate information for given validator. - -```bash -cosmos.staking.v1beta1.Query/ValidatorDelegations -``` - -Example: - -```bash -grpcurl -plaintext -d '{"validator_addr":"cosmosvaloper1rne8lgs98p0jqe82sgt0qr4rdn4hgvmgp9ggcc"}' \ -localhost:9090 cosmos.staking.v1beta1.Query/ValidatorDelegations -``` - -Example Output: - -```bash -{ - "delegationResponses": [ - { - "delegation": { - "delegatorAddress": "cosmos1rne8lgs98p0jqe82sgt0qr4rdn4hgvmgy3ua5t", - "validatorAddress": "cosmosvaloper1rne8lgs98p0jqe82sgt0qr4rdn4hgvmgp9ggcc", - "shares": "10000000000000000000000000" - }, - "balance": { - "denom": "stake", - "amount": "10000000" - } - } - ], - "pagination": { - "total": "1" - } -} -``` - -#### ValidatorUnbondingDelegations - -The `ValidatorUnbondingDelegations` endpoint queries delegate information for given validator. - -```bash -cosmos.staking.v1beta1.Query/ValidatorUnbondingDelegations -``` - -Example: - -```bash -grpcurl -plaintext -d '{"validator_addr":"cosmosvaloper1rne8lgs98p0jqe82sgt0qr4rdn4hgvmgp9ggcc"}' \ -localhost:9090 cosmos.staking.v1beta1.Query/ValidatorUnbondingDelegations -``` - -Example Output: - -```bash -{ - "unbonding_responses": [ - { - "delegator_address": "cosmos1z3pzzw84d6xn00pw9dy3yapqypfde7vg6965fy", - "validator_address": "cosmosvaloper1rne8lgs98p0jqe82sgt0qr4rdn4hgvmgp9ggcc", - "entries": [ - { - "creation_height": "25325", - "completion_time": "2021-10-31T09:24:36.797320636Z", - "initial_balance": "20000000", - "balance": "20000000" - } - ] - }, - { - "delegator_address": "cosmos1y8nyfvmqh50p6ldpzljk3yrglppdv3t8phju77", - "validator_address": "cosmosvaloper1rne8lgs98p0jqe82sgt0qr4rdn4hgvmgp9ggcc", - "entries": [ - { - "creation_height": "13100", - "completion_time": "2021-10-30T12:53:02.272266791Z", - "initial_balance": "1000000", - "balance": "1000000" - } - ] - }, - ], - "pagination": { - "next_key": null, - "total": "8" - } -} -``` - -#### Delegation - -The `Delegation` endpoint queries delegate information for given validator delegator pair. - -```bash -cosmos.staking.v1beta1.Query/Delegation -``` - -Example: - -```bash -grpcurl -plaintext \ --d '{"delegator_addr": "cosmos1y8nyfvmqh50p6ldpzljk3yrglppdv3t8phju77", validator_addr":"cosmosvaloper1rne8lgs98p0jqe82sgt0qr4rdn4hgvmgp9ggcc"}' \ -localhost:9090 cosmos.staking.v1beta1.Query/Delegation -``` - -Example Output: - -```bash -{ - "delegation_response": - { - "delegation": - { - "delegator_address":"cosmos1y8nyfvmqh50p6ldpzljk3yrglppdv3t8phju77", - "validator_address":"cosmosvaloper1rne8lgs98p0jqe82sgt0qr4rdn4hgvmgp9ggcc", - "shares":"25083119936.000000000000000000" - }, - "balance": - { - "denom":"stake", - "amount":"25083119936" - } - } -} -``` - -#### UnbondingDelegation - -The `UnbondingDelegation` endpoint queries unbonding information for given validator delegator. - -```bash -cosmos.staking.v1beta1.Query/UnbondingDelegation -``` - -Example: - -```bash -grpcurl -plaintext \ --d '{"delegator_addr": "cosmos1y8nyfvmqh50p6ldpzljk3yrglppdv3t8phju77", validator_addr":"cosmosvaloper1rne8lgs98p0jqe82sgt0qr4rdn4hgvmgp9ggcc"}' \ -localhost:9090 cosmos.staking.v1beta1.Query/UnbondingDelegation -``` - -Example Output: - -```bash -{ - "unbond": { - "delegator_address": "cosmos1y8nyfvmqh50p6ldpzljk3yrglppdv3t8phju77", - "validator_address": "cosmosvaloper1rne8lgs98p0jqe82sgt0qr4rdn4hgvmgp9ggcc", - "entries": [ - { - "creation_height": "136984", - "completion_time": "2021-11-08T05:38:47.505593891Z", - "initial_balance": "400000000", - "balance": "400000000" - }, - { - "creation_height": "137005", - "completion_time": "2021-11-08T05:40:53.526196312Z", - "initial_balance": "385000000", - "balance": "385000000" - } - ] - } -} -``` - -#### DelegatorDelegations - -The `DelegatorDelegations` endpoint queries all delegations of a given delegator address. - -```bash -cosmos.staking.v1beta1.Query/DelegatorDelegations -``` - -Example: - -```bash -grpcurl -plaintext \ --d '{"delegator_addr": "cosmos1y8nyfvmqh50p6ldpzljk3yrglppdv3t8phju77"}' \ -localhost:9090 cosmos.staking.v1beta1.Query/DelegatorDelegations -``` - -Example Output: - -```bash -{ - "delegation_responses": [ - {"delegation":{"delegator_address":"cosmos1y8nyfvmqh50p6ldpzljk3yrglppdv3t8phju77","validator_address":"cosmosvaloper1eh5mwu044gd5ntkkc2xgfg8247mgc56fww3vc8","shares":"25083339023.000000000000000000"},"balance":{"denom":"stake","amount":"25083339023"}} - ], - "pagination": { - "next_key": null, - "total": "1" - } -} -``` - -#### DelegatorUnbondingDelegations - -The `DelegatorUnbondingDelegations` endpoint queries all unbonding delegations of a given delegator address. - -```bash -cosmos.staking.v1beta1.Query/DelegatorUnbondingDelegations -``` - -Example: - -```bash -grpcurl -plaintext \ --d '{"delegator_addr": "cosmos1y8nyfvmqh50p6ldpzljk3yrglppdv3t8phju77"}' \ -localhost:9090 cosmos.staking.v1beta1.Query/DelegatorUnbondingDelegations -``` - -Example Output: - -```bash -{ - "unbonding_responses": [ - { - "delegator_address": "cosmos1y8nyfvmqh50p6ldpzljk3yrglppdv3t8phju77", - "validator_address": "cosmosvaloper1sjllsnramtg3ewxqwwrwjxfgc4n4ef9uxyejze", - "entries": [ - { - "creation_height": "136984", - "completion_time": "2021-11-08T05:38:47.505593891Z", - "initial_balance": "400000000", - "balance": "400000000" - }, - { - "creation_height": "137005", - "completion_time": "2021-11-08T05:40:53.526196312Z", - "initial_balance": "385000000", - "balance": "385000000" - } - ] - } - ], - "pagination": { - "next_key": null, - "total": "1" - } -} -``` - -#### Redelegations - -The `Redelegations` endpoint queries redelegations of given address. - -```bash -cosmos.staking.v1beta1.Query/Redelegations -``` - -Example: - -```bash -grpcurl -plaintext \ --d '{"delegator_addr": "cosmos1ld5p7hn43yuh8ht28gm9pfjgj2fctujp2tgwvf", "src_validator_addr" : "cosmosvaloper1j7euyj85fv2jugejrktj540emh9353ltgppc3g", "dst_validator_addr" : "cosmosvaloper1yy3tnegzmkdcm7czzcy3flw5z0zyr9vkkxrfse"}' \ -localhost:9090 cosmos.staking.v1beta1.Query/Redelegations -``` - -Example Output: - -```bash -{ - "redelegation_responses": [ - { - "redelegation": { - "delegator_address": "cosmos1ld5p7hn43yuh8ht28gm9pfjgj2fctujp2tgwvf", - "validator_src_address": "cosmosvaloper1j7euyj85fv2jugejrktj540emh9353ltgppc3g", - "validator_dst_address": "cosmosvaloper1yy3tnegzmkdcm7czzcy3flw5z0zyr9vkkxrfse", - "entries": null - }, - "entries": [ - { - "redelegation_entry": { - "creation_height": 135932, - "completion_time": "2021-11-08T03:52:55.299147901Z", - "initial_balance": "2900000", - "shares_dst": "2900000.000000000000000000" - }, - "balance": "2900000" - } - ] - } - ], - "pagination": null -} -``` - -#### DelegatorValidators - -The `DelegatorValidators` endpoint queries all validators information for given delegator. - -```bash -cosmos.staking.v1beta1.Query/DelegatorValidators -``` - -Example: - -```bash -grpcurl -plaintext \ --d '{"delegator_addr": "cosmos1ld5p7hn43yuh8ht28gm9pfjgj2fctujp2tgwvf"}' \ -localhost:9090 cosmos.staking.v1beta1.Query/DelegatorValidators -``` - -Example Output: - -```bash -{ - "validators": [ - { - "operator_address": "cosmosvaloper1eh5mwu044gd5ntkkc2xgfg8247mgc56fww3vc8", - "consensus_pubkey": { - "@type": "/cosmos.crypto.ed25519.PubKey", - "key": "UPwHWxH1zHJWGOa/m6JB3f5YjHMvPQPkVbDqqi+U7Uw=" - }, - "jailed": false, - "status": "BOND_STATUS_BONDED", - "tokens": "347260647559", - "delegator_shares": "347260647559.000000000000000000", - "description": { - "moniker": "BouBouNode", - "identity": "", - "website": "https://boubounode.com", - "security_contact": "", - "details": "AI-based Validator. #1 AI Validator on Game of Stakes. Fairly priced. Don't trust (humans), verify. Made with BouBou love." - }, - "unbonding_height": "0", - "unbonding_time": "1970-01-01T00:00:00Z", - "commission": { - "commission_rates": { - "rate": "0.061000000000000000", - "max_rate": "0.300000000000000000", - "max_change_rate": "0.150000000000000000" - }, - "update_time": "2021-10-01T15:00:00Z" - }, - "min_self_delegation": "1" - } - ], - "pagination": { - "next_key": null, - "total": "1" - } -} -``` - -#### DelegatorValidator - -The `DelegatorValidator` endpoint queries validator information for given delegator validator - -```bash -cosmos.staking.v1beta1.Query/DelegatorValidator -``` - -Example: - -```bash -grpcurl -plaintext \ --d '{"delegator_addr": "cosmos1eh5mwu044gd5ntkkc2xgfg8247mgc56f3n8rr7", "validator_addr": "cosmosvaloper1eh5mwu044gd5ntkkc2xgfg8247mgc56fww3vc8"}' \ -localhost:9090 cosmos.staking.v1beta1.Query/DelegatorValidator -``` - -Example Output: - -```bash -{ - "validator": { - "operator_address": "cosmosvaloper1eh5mwu044gd5ntkkc2xgfg8247mgc56fww3vc8", - "consensus_pubkey": { - "@type": "/cosmos.crypto.ed25519.PubKey", - "key": "UPwHWxH1zHJWGOa/m6JB3f5YjHMvPQPkVbDqqi+U7Uw=" - }, - "jailed": false, - "status": "BOND_STATUS_BONDED", - "tokens": "347262754841", - "delegator_shares": "347262754841.000000000000000000", - "description": { - "moniker": "BouBouNode", - "identity": "", - "website": "https://boubounode.com", - "security_contact": "", - "details": "AI-based Validator. #1 AI Validator on Game of Stakes. Fairly priced. Don't trust (humans), verify. Made with BouBou love." - }, - "unbonding_height": "0", - "unbonding_time": "1970-01-01T00:00:00Z", - "commission": { - "commission_rates": { - "rate": "0.061000000000000000", - "max_rate": "0.300000000000000000", - "max_change_rate": "0.150000000000000000" - }, - "update_time": "2021-10-01T15:00:00Z" - }, - "min_self_delegation": "1" - } -} -``` - -#### HistoricalInfo - -```bash -cosmos.staking.v1beta1.Query/HistoricalInfo -``` - -Example: - -```bash -grpcurl -plaintext -d '{"height" : 1}' localhost:9090 cosmos.staking.v1beta1.Query/HistoricalInfo -``` - -Example Output: - -```bash -{ - "hist": { - "header": { - "version": { - "block": "11", - "app": "0" - }, - "chain_id": "simd-1", - "height": "140142", - "time": "2021-10-11T10:56:29.720079569Z", - "last_block_id": { - "hash": "9gri/4LLJUBFqioQ3NzZIP9/7YHR9QqaM6B2aJNQA7o=", - "part_set_header": { - "total": 1, - "hash": "Hk1+C864uQkl9+I6Zn7IurBZBKUevqlVtU7VqaZl1tc=" - } - }, - "last_commit_hash": "VxrcS27GtvGruS3I9+AlpT7udxIT1F0OrRklrVFSSKc=", - "data_hash": "80BjOrqNYUOkTnmgWyz9AQ8n7SoEmPVi4QmAe8RbQBY=", - "validators_hash": "95W49n2hw8RWpr1GPTAO5MSPi6w6Wjr3JjjS7AjpBho=", - "next_validators_hash": "95W49n2hw8RWpr1GPTAO5MSPi6w6Wjr3JjjS7AjpBho=", - "consensus_hash": "BICRvH3cKD93v7+R1zxE2ljD34qcvIZ0Bdi389qtoi8=", - "app_hash": "ZZaxnSY3E6Ex5Bvkm+RigYCK82g8SSUL53NymPITeOE=", - "last_results_hash": "47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=", - "evidence_hash": "47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=", - "proposer_address": "aH6dO428B+ItuoqPq70efFHrSMY=" - }, - "valset": [ - { - "operator_address": "cosmosvaloper196ax4vc0lwpxndu9dyhvca7jhxp70rmcqcnylw", - "consensus_pubkey": { - "@type": "/cosmos.crypto.ed25519.PubKey", - "key": "/O7BtNW0pafwfvomgR4ZnfldwPXiFfJs9mHg3gwfv5Q=" - }, - "jailed": false, - "status": "BOND_STATUS_BONDED", - "tokens": "1426045203613", - "delegator_shares": "1426045203613.000000000000000000", - "description": { - "moniker": "SG-1", - "identity": "48608633F99D1B60", - "website": "https://sg-1.online", - "security_contact": "", - "details": "SG-1 - your favorite validator on Witval. We offer 100% Soft Slash protection." - }, - "unbonding_height": "0", - "unbonding_time": "1970-01-01T00:00:00Z", - "commission": { - "commission_rates": { - "rate": "0.037500000000000000", - "max_rate": "0.200000000000000000", - "max_change_rate": "0.030000000000000000" - }, - "update_time": "2021-10-01T15:00:00Z" - }, - "min_self_delegation": "1" - } - ] - } -} - -``` - -#### Pool - -The `Pool` endpoint queries the pool information. - -```bash -cosmos.staking.v1beta1.Query/Pool -``` - -Example: - -```bash -grpcurl -plaintext -d localhost:9090 cosmos.staking.v1beta1.Query/Pool -``` - -Example Output: - -```bash -{ - "pool": { - "not_bonded_tokens": "369054400189", - "bonded_tokens": "15657192425623" - } -} -``` - -#### Params - -The `Params` endpoint queries the pool information. - -```bash -cosmos.staking.v1beta1.Query/Params -``` - -Example: - -```bash -grpcurl -plaintext localhost:9090 cosmos.staking.v1beta1.Query/Params -``` - -Example Output: - -```bash -{ - "params": { - "unbondingTime": "1814400s", - "maxValidators": 100, - "maxEntries": 7, - "historicalEntries": 10000, - "bondDenom": "stake" - } -} -``` - -### REST - -A user can query the `staking` module using REST endpoints. - -#### DelegatorDelegations - -The `DelegtaorDelegations` REST endpoint queries all delegations of a given delegator address. - -```bash -/cosmos/staking/v1beta1/delegations/{delegatorAddr} -``` - -Example: - -```bash -curl -X GET "http://localhost:1317/cosmos/staking/v1beta1/delegations/cosmos1vcs68xf2tnqes5tg0khr0vyevm40ff6zdxatp5" -H "accept: application/json" -``` - -Example Output: - -```bash -{ - "delegation_responses": [ - { - "delegation": { - "delegator_address": "cosmos1vcs68xf2tnqes5tg0khr0vyevm40ff6zdxatp5", - "validator_address": "cosmosvaloper1quqxfrxkycr0uzt4yk0d57tcq3zk7srm7sm6r8", - "shares": "256250000.000000000000000000" - }, - "balance": { - "denom": "stake", - "amount": "256250000" - } - }, - { - "delegation": { - "delegator_address": "cosmos1vcs68xf2tnqes5tg0khr0vyevm40ff6zdxatp5", - "validator_address": "cosmosvaloper194v8uwee2fvs2s8fa5k7j03ktwc87h5ym39jfv", - "shares": "255150000.000000000000000000" - }, - "balance": { - "denom": "stake", - "amount": "255150000" - } - } - ], - "pagination": { - "next_key": null, - "total": "2" - } -} -``` - -#### Redelegations - -The `Redelegations` REST endpoint queries redelegations of given address. - -```bash -/cosmos/staking/v1beta1/delegators/{delegatorAddr}/redelegations -``` - -Example: - -```bash -curl -X GET \ -"http://localhost:1317/cosmos/staking/v1beta1/delegators/cosmos1thfntksw0d35n2tkr0k8v54fr8wxtxwxl2c56e/redelegations?srcValidatorAddr=cosmosvaloper1lzhlnpahvznwfv4jmay2tgaha5kmz5qx4cuznf&dstValidatorAddr=cosmosvaloper1vq8tw77kp8lvxq9u3c8eeln9zymn68rng8pgt4" \ --H "accept: application/json" -``` - -Example Output: - -```bash -{ - "redelegation_responses": [ - { - "redelegation": { - "delegator_address": "cosmos1thfntksw0d35n2tkr0k8v54fr8wxtxwxl2c56e", - "validator_src_address": "cosmosvaloper1lzhlnpahvznwfv4jmay2tgaha5kmz5qx4cuznf", - "validator_dst_address": "cosmosvaloper1vq8tw77kp8lvxq9u3c8eeln9zymn68rng8pgt4", - "entries": null - }, - "entries": [ - { - "redelegation_entry": { - "creation_height": 151523, - "completion_time": "2021-11-09T06:03:25.640682116Z", - "initial_balance": "200000000", - "shares_dst": "200000000.000000000000000000" - }, - "balance": "200000000" - } - ] - } - ], - "pagination": null -} -``` - -#### DelegatorUnbondingDelegations - -The `DelegatorUnbondingDelegations` REST endpoint queries all unbonding delegations of a given delegator address. - -```bash -/cosmos/staking/v1beta1/delegators/{delegatorAddr}/unbonding_delegations -``` - -Example: - -```bash -curl -X GET \ -"http://localhost:1317/cosmos/staking/v1beta1/delegators/cosmos1nxv42u3lv642q0fuzu2qmrku27zgut3n3z7lll/unbonding_delegations" \ --H "accept: application/json" -``` - -Example Output: - -```bash -{ - "unbonding_responses": [ - { - "delegator_address": "cosmos1nxv42u3lv642q0fuzu2qmrku27zgut3n3z7lll", - "validator_address": "cosmosvaloper1e7mvqlz50ch6gw4yjfemsc069wfre4qwmw53kq", - "entries": [ - { - "creation_height": "2442278", - "completion_time": "2021-10-12T10:59:03.797335857Z", - "initial_balance": "50000000000", - "balance": "50000000000" - } - ] - } - ], - "pagination": { - "next_key": null, - "total": "1" - } -} -``` - -#### DelegatorValidators - -The `DelegatorValidators` REST endpoint queries all validators information for given delegator address. - -```bash -/cosmos/staking/v1beta1/delegators/{delegatorAddr}/validators -``` - -Example: - -```bash -curl -X GET \ -"http://localhost:1317/cosmos/staking/v1beta1/delegators/cosmos1xwazl8ftks4gn00y5x3c47auquc62ssune9ppv/validators" \ --H "accept: application/json" -``` - -Example Output: - -```bash -{ - "validators": [ - { - "operator_address": "cosmosvaloper1xwazl8ftks4gn00y5x3c47auquc62ssuvynw64", - "consensus_pubkey": { - "@type": "/cosmos.crypto.ed25519.PubKey", - "key": "5v4n3px3PkfNnKflSgepDnsMQR1hiNXnqOC11Y72/PQ=" - }, - "jailed": false, - "status": "BOND_STATUS_BONDED", - "tokens": "21592843799", - "delegator_shares": "21592843799.000000000000000000", - "description": { - "moniker": "jabbey", - "identity": "", - "website": "https://twitter.com/JoeAbbey", - "security_contact": "", - "details": "just another dad in the cosmos" - }, - "unbonding_height": "0", - "unbonding_time": "1970-01-01T00:00:00Z", - "commission": { - "commission_rates": { - "rate": "0.100000000000000000", - "max_rate": "0.200000000000000000", - "max_change_rate": "0.100000000000000000" - }, - "update_time": "2021-10-09T19:03:54.984821705Z" - }, - "min_self_delegation": "1" - } - ], - "pagination": { - "next_key": null, - "total": "1" - } -} -``` - -#### DelegatorValidator - -The `DelegatorValidator` REST endpoint queries validator information for given delegator validator pair. - -```bash -/cosmos/staking/v1beta1/delegators/{delegatorAddr}/validators/{validatorAddr} -``` - -Example: - -```bash -curl -X GET \ -"http://localhost:1317/cosmos/staking/v1beta1/delegators/cosmos1xwazl8ftks4gn00y5x3c47auquc62ssune9ppv/validators/cosmosvaloper1xwazl8ftks4gn00y5x3c47auquc62ssuvynw64" \ --H "accept: application/json" -``` - -Example Output: - -```bash -{ - "validator": { - "operator_address": "cosmosvaloper1xwazl8ftks4gn00y5x3c47auquc62ssuvynw64", - "consensus_pubkey": { - "@type": "/cosmos.crypto.ed25519.PubKey", - "key": "5v4n3px3PkfNnKflSgepDnsMQR1hiNXnqOC11Y72/PQ=" - }, - "jailed": false, - "status": "BOND_STATUS_BONDED", - "tokens": "21592843799", - "delegator_shares": "21592843799.000000000000000000", - "description": { - "moniker": "jabbey", - "identity": "", - "website": "https://twitter.com/JoeAbbey", - "security_contact": "", - "details": "just another dad in the cosmos" - }, - "unbonding_height": "0", - "unbonding_time": "1970-01-01T00:00:00Z", - "commission": { - "commission_rates": { - "rate": "0.100000000000000000", - "max_rate": "0.200000000000000000", - "max_change_rate": "0.100000000000000000" - }, - "update_time": "2021-10-09T19:03:54.984821705Z" - }, - "min_self_delegation": "1" - } -} -``` - -#### HistoricalInfo - -The `HistoricalInfo` REST endpoint queries the historical information for given height. - -```bash -/cosmos/staking/v1beta1/historical_info/{height} -``` - -Example: - -```bash -curl -X GET "http://localhost:1317/cosmos/staking/v1beta1/historical_info/153332" -H "accept: application/json" -``` - -Example Output: - -```bash -{ - "hist": { - "header": { - "version": { - "block": "11", - "app": "0" - }, - "chain_id": "cosmos-1", - "height": "153332", - "time": "2021-10-12T09:05:35.062230221Z", - "last_block_id": { - "hash": "NX8HevR5khb7H6NGKva+jVz7cyf0skF1CrcY9A0s+d8=", - "part_set_header": { - "total": 1, - "hash": "zLQ2FiKM5tooL3BInt+VVfgzjlBXfq0Hc8Iux/xrhdg=" - } - }, - "last_commit_hash": "P6IJrK8vSqU3dGEyRHnAFocoDGja0bn9euLuy09s350=", - "data_hash": "eUd+6acHWrNXYju8Js449RJ99lOYOs16KpqQl4SMrEM=", - "validators_hash": "mB4pravvMsJKgi+g8aYdSeNlt0kPjnRFyvtAQtaxcfw=", - "next_validators_hash": "mB4pravvMsJKgi+g8aYdSeNlt0kPjnRFyvtAQtaxcfw=", - "consensus_hash": "BICRvH3cKD93v7+R1zxE2ljD34qcvIZ0Bdi389qtoi8=", - "app_hash": "fuELArKRK+CptnZ8tu54h6xEleSWenHNmqC84W866fU=", - "last_results_hash": "p/BPexV4LxAzlVcPRvW+lomgXb6Yze8YLIQUo/4Kdgc=", - "evidence_hash": "47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=", - "proposer_address": "G0MeY8xQx7ooOsni8KE/3R/Ib3Q=" - }, - "valset": [ - { - "operator_address": "cosmosvaloper196ax4vc0lwpxndu9dyhvca7jhxp70rmcqcnylw", - "consensus_pubkey": { - "@type": "/cosmos.crypto.ed25519.PubKey", - "key": "/O7BtNW0pafwfvomgR4ZnfldwPXiFfJs9mHg3gwfv5Q=" - }, - "jailed": false, - "status": "BOND_STATUS_BONDED", - "tokens": "1416521659632", - "delegator_shares": "1416521659632.000000000000000000", - "description": { - "moniker": "SG-1", - "identity": "48608633F99D1B60", - "website": "https://sg-1.online", - "security_contact": "", - "details": "SG-1 - your favorite validator on cosmos. We offer 100% Soft Slash protection." - }, - "unbonding_height": "0", - "unbonding_time": "1970-01-01T00:00:00Z", - "commission": { - "commission_rates": { - "rate": "0.037500000000000000", - "max_rate": "0.200000000000000000", - "max_change_rate": "0.030000000000000000" - }, - "update_time": "2021-10-01T15:00:00Z" - }, - "min_self_delegation": "1" - }, - { - "operator_address": "cosmosvaloper1t8ehvswxjfn3ejzkjtntcyrqwvmvuknzmvtaaa", - "consensus_pubkey": { - "@type": "/cosmos.crypto.ed25519.PubKey", - "key": "uExZyjNLtr2+FFIhNDAMcQ8+yTrqE7ygYTsI7khkA5Y=" - }, - "jailed": false, - "status": "BOND_STATUS_BONDED", - "tokens": "1348298958808", - "delegator_shares": "1348298958808.000000000000000000", - "description": { - "moniker": "Cosmostation", - "identity": "AE4C403A6E7AA1AC", - "website": "https://www.cosmostation.io", - "security_contact": "admin@stamper.network", - "details": "Cosmostation validator node. Delegate your tokens and Start Earning Staking Rewards" - }, - "unbonding_height": "0", - "unbonding_time": "1970-01-01T00:00:00Z", - "commission": { - "commission_rates": { - "rate": "0.050000000000000000", - "max_rate": "1.000000000000000000", - "max_change_rate": "0.200000000000000000" - }, - "update_time": "2021-10-01T15:06:38.821314287Z" - }, - "min_self_delegation": "1" - } - ] - } -} -``` - -#### Parameters - -The `Parameters` REST endpoint queries the staking parameters. - -```bash -/cosmos/staking/v1beta1/params -``` - -Example: - -```bash -curl -X GET "http://localhost:1317/cosmos/staking/v1beta1/params" -H "accept: application/json" -``` - -Example Output: - -```bash -{ - "params": { - "unbonding_time": "2419200s", - "max_validators": 100, - "max_entries": 7, - "historical_entries": 10000, - "bond_denom": "stake" - } -} -``` - -#### Pool - -The `Pool` REST endpoint queries the pool information. - -```bash -/cosmos/staking/v1beta1/pool -``` - -Example: - -```bash -curl -X GET "http://localhost:1317/cosmos/staking/v1beta1/pool" -H "accept: application/json" -``` - -Example Output: - -```bash -{ - "pool": { - "not_bonded_tokens": "432805737458", - "bonded_tokens": "15783637712645" - } -} -``` - -#### Validators - -The `Validators` REST endpoint queries all validators that match the given status. - -```bash -/cosmos/staking/v1beta1/validators -``` - -Example: - -```bash -curl -X GET "http://localhost:1317/cosmos/staking/v1beta1/validators" -H "accept: application/json" -``` - -Example Output: - -```bash -{ - "validators": [ - { - "operator_address": "cosmosvaloper1q3jsx9dpfhtyqqgetwpe5tmk8f0ms5qywje8tw", - "consensus_pubkey": { - "@type": "/cosmos.crypto.ed25519.PubKey", - "key": "N7BPyek2aKuNZ0N/8YsrqSDhGZmgVaYUBuddY8pwKaE=" - }, - "jailed": false, - "status": "BOND_STATUS_BONDED", - "tokens": "383301887799", - "delegator_shares": "383301887799.000000000000000000", - "description": { - "moniker": "SmartNodes", - "identity": "D372724899D1EDC8", - "website": "https://smartnodes.co", - "security_contact": "", - "details": "Earn Rewards with Crypto Staking & Node Deployment" - }, - "unbonding_height": "0", - "unbonding_time": "1970-01-01T00:00:00Z", - "commission": { - "commission_rates": { - "rate": "0.050000000000000000", - "max_rate": "0.200000000000000000", - "max_change_rate": "0.100000000000000000" - }, - "update_time": "2021-10-01T15:51:31.596618510Z" - }, - "min_self_delegation": "1" - }, - { - "operator_address": "cosmosvaloper1q5ku90atkhktze83j9xjaks2p7uruag5zp6wt7", - "consensus_pubkey": { - "@type": "/cosmos.crypto.ed25519.PubKey", - "key": "GDNpuKDmCg9GnhnsiU4fCWktuGUemjNfvpCZiqoRIYA=" - }, - "jailed": false, - "status": "BOND_STATUS_UNBONDING", - "tokens": "1017819654", - "delegator_shares": "1017819654.000000000000000000", - "description": { - "moniker": "Noderunners", - "identity": "812E82D12FEA3493", - "website": "http://noderunners.biz", - "security_contact": "info@noderunners.biz", - "details": "Noderunners is a professional validator in POS networks. We have a huge node running experience, reliable soft and hardware. Our commissions are always low, our support to delegators is always full. Stake with us and start receiving your cosmos rewards now!" - }, - "unbonding_height": "147302", - "unbonding_time": "2021-11-08T22:58:53.718662452Z", - "commission": { - "commission_rates": { - "rate": "0.050000000000000000", - "max_rate": "0.200000000000000000", - "max_change_rate": "0.100000000000000000" - }, - "update_time": "2021-10-04T18:02:21.446645619Z" - }, - "min_self_delegation": "1" - } - ], - "pagination": { - "next_key": "FONDBFkE4tEEf7yxWWKOD49jC2NK", - "total": "2" - } -} -``` - -#### Validator - -The `Validator` REST endpoint queries validator information for given validator address. - -```bash -/cosmos/staking/v1beta1/validators/{validatorAddr} -``` - -Example: - -```bash -curl -X GET \ -"http://localhost:1317/cosmos/staking/v1beta1/validators/cosmosvaloper16msryt3fqlxtvsy8u5ay7wv2p8mglfg9g70e3q" \ --H "accept: application/json" -``` - -Example Output: - -```bash -{ - "validator": { - "operator_address": "cosmosvaloper16msryt3fqlxtvsy8u5ay7wv2p8mglfg9g70e3q", - "consensus_pubkey": { - "@type": "/cosmos.crypto.ed25519.PubKey", - "key": "sIiexdJdYWn27+7iUHQJDnkp63gq/rzUq1Y+fxoGjXc=" - }, - "jailed": false, - "status": "BOND_STATUS_BONDED", - "tokens": "33027900000", - "delegator_shares": "33027900000.000000000000000000", - "description": { - "moniker": "Witval", - "identity": "51468B615127273A", - "website": "", - "security_contact": "", - "details": "Witval is the validator arm from Vitwit. Vitwit is into software consulting and services business since 2015. We are working closely with Cosmos ecosystem since 2018. We are also building tools for the ecosystem, Aneka is our explorer for the cosmos ecosystem." - }, - "unbonding_height": "0", - "unbonding_time": "1970-01-01T00:00:00Z", - "commission": { - "commission_rates": { - "rate": "0.050000000000000000", - "max_rate": "0.200000000000000000", - "max_change_rate": "0.020000000000000000" - }, - "update_time": "2021-10-01T19:24:52.663191049Z" - }, - "min_self_delegation": "1" - } -} -``` - -#### ValidatorDelegations - -The `ValidatorDelegations` REST endpoint queries delegate information for given validator. - -```bash -/cosmos/staking/v1beta1/validators/{validatorAddr}/delegations -``` - -Example: - -```bash -curl -X GET "http://localhost:1317/cosmos/staking/v1beta1/validators/cosmosvaloper16msryt3fqlxtvsy8u5ay7wv2p8mglfg9g70e3q/delegations" -H "accept: application/json" -``` - -Example Output: - -```bash -{ - "delegation_responses": [ - { - "delegation": { - "delegator_address": "cosmos190g5j8aszqhvtg7cprmev8xcxs6csra7xnk3n3", - "validator_address": "cosmosvaloper16msryt3fqlxtvsy8u5ay7wv2p8mglfg9g70e3q", - "shares": "31000000000.000000000000000000" - }, - "balance": { - "denom": "stake", - "amount": "31000000000" - } - }, - { - "delegation": { - "delegator_address": "cosmos1ddle9tczl87gsvmeva3c48nenyng4n56qwq4ee", - "validator_address": "cosmosvaloper16msryt3fqlxtvsy8u5ay7wv2p8mglfg9g70e3q", - "shares": "628470000.000000000000000000" - }, - "balance": { - "denom": "stake", - "amount": "628470000" - } - }, - { - "delegation": { - "delegator_address": "cosmos10fdvkczl76m040smd33lh9xn9j0cf26kk4s2nw", - "validator_address": "cosmosvaloper16msryt3fqlxtvsy8u5ay7wv2p8mglfg9g70e3q", - "shares": "838120000.000000000000000000" - }, - "balance": { - "denom": "stake", - "amount": "838120000" - } - }, - { - "delegation": { - "delegator_address": "cosmos1n8f5fknsv2yt7a8u6nrx30zqy7lu9jfm0t5lq8", - "validator_address": "cosmosvaloper16msryt3fqlxtvsy8u5ay7wv2p8mglfg9g70e3q", - "shares": "500000000.000000000000000000" - }, - "balance": { - "denom": "stake", - "amount": "500000000" - } - }, - { - "delegation": { - "delegator_address": "cosmos16msryt3fqlxtvsy8u5ay7wv2p8mglfg9hrek2e", - "validator_address": "cosmosvaloper16msryt3fqlxtvsy8u5ay7wv2p8mglfg9g70e3q", - "shares": "61310000.000000000000000000" - }, - "balance": { - "denom": "stake", - "amount": "61310000" - } - } - ], - "pagination": { - "next_key": null, - "total": "5" - } -} -``` - -#### Delegation - -The `Delegation` REST endpoint queries delegate information for given validator delegator pair. - -```bash -/cosmos/staking/v1beta1/validators/{validatorAddr}/delegations/{delegatorAddr} -``` - -Example: - -```bash -curl -X GET \ -"http://localhost:1317/cosmos/staking/v1beta1/validators/cosmosvaloper16msryt3fqlxtvsy8u5ay7wv2p8mglfg9g70e3q/delegations/cosmos1n8f5fknsv2yt7a8u6nrx30zqy7lu9jfm0t5lq8" \ --H "accept: application/json" -``` - -Example Output: - -```bash -{ - "delegation_response": { - "delegation": { - "delegator_address": "cosmos1n8f5fknsv2yt7a8u6nrx30zqy7lu9jfm0t5lq8", - "validator_address": "cosmosvaloper16msryt3fqlxtvsy8u5ay7wv2p8mglfg9g70e3q", - "shares": "500000000.000000000000000000" - }, - "balance": { - "denom": "stake", - "amount": "500000000" - } - } -} -``` - -#### UnbondingDelegation - -The `UnbondingDelegation` REST endpoint queries unbonding information for given validator delegator pair. - -```bash -/cosmos/staking/v1beta1/validators/{validatorAddr}/delegations/{delegatorAddr}/unbonding_delegation -``` - -Example: - -```bash -curl -X GET \ -"http://localhost:1317/cosmos/staking/v1beta1/validators/cosmosvaloper13v4spsah85ps4vtrw07vzea37gq5la5gktlkeu/delegations/cosmos1ze2ye5u5k3qdlexvt2e0nn0508p04094ya0qpm/unbonding_delegation" \ --H "accept: application/json" -``` - -Example Output: - -```bash -{ - "unbond": { - "delegator_address": "cosmos1ze2ye5u5k3qdlexvt2e0nn0508p04094ya0qpm", - "validator_address": "cosmosvaloper13v4spsah85ps4vtrw07vzea37gq5la5gktlkeu", - "entries": [ - { - "creation_height": "153687", - "completion_time": "2021-11-09T09:41:18.352401903Z", - "initial_balance": "525111", - "balance": "525111" - } - ] - } -} -``` - -#### ValidatorUnbondingDelegations - -The `ValidatorUnbondingDelegations` REST endpoint queries unbonding delegations of a validator. - -```bash -/cosmos/staking/v1beta1/validators/{validatorAddr}/unbonding_delegations -``` - -Example: - -```bash -curl -X GET \ -"http://localhost:1317/cosmos/staking/v1beta1/validators/cosmosvaloper13v4spsah85ps4vtrw07vzea37gq5la5gktlkeu/unbonding_delegations" \ --H "accept: application/json" -``` - -Example Output: - -```bash -{ - "unbonding_responses": [ - { - "delegator_address": "cosmos1q9snn84jfrd9ge8t46kdcggpe58dua82vnj7uy", - "validator_address": "cosmosvaloper13v4spsah85ps4vtrw07vzea37gq5la5gktlkeu", - "entries": [ - { - "creation_height": "90998", - "completion_time": "2021-11-05T00:14:37.005841058Z", - "initial_balance": "24000000", - "balance": "24000000" - } - ] - }, - { - "delegator_address": "cosmos1qf36e6wmq9h4twhdvs6pyq9qcaeu7ye0s3dqq2", - "validator_address": "cosmosvaloper13v4spsah85ps4vtrw07vzea37gq5la5gktlkeu", - "entries": [ - { - "creation_height": "47478", - "completion_time": "2021-11-01T22:47:26.714116854Z", - "initial_balance": "8000000", - "balance": "8000000" - } - ] - } - ], - "pagination": { - "next_key": null, - "total": "2" - } -} -``` diff --git a/.gitbook/developers/modules/core/upgrade/README.md b/.gitbook/developers/modules/core/upgrade/README.md deleted file mode 100644 index 0d98c160..00000000 --- a/.gitbook/developers/modules/core/upgrade/README.md +++ /dev/null @@ -1,619 +0,0 @@ ---- -sidebar_position: 1 ---- - -# `x/upgrade` - -## Abstract - -`x/upgrade` is an implementation of a Cosmos SDK module that facilitates smoothly -upgrading a live Cosmos chain to a new (breaking) software version. It accomplishes this by -providing a `PreBlocker` hook that prevents the blockchain state machine from -proceeding once a pre-defined upgrade block height has been reached. - -The module does not prescribe anything regarding how governance decides to do an -upgrade, but just the mechanism for coordinating the upgrade safely. Without software -support for upgrades, upgrading a live chain is risky because all of the validators -need to pause their state machines at exactly the same point in the process. If -this is not done correctly, there can be state inconsistencies which are hard to -recover from. - -* [Concepts](#concepts) -* [State](#state) -* [Events](#events) -* [Client](#client) - * [CLI](#cli) - * [REST](#rest) - * [gRPC](#grpc) -* [Resources](#resources) - -## Concepts - -### Plan - -The `x/upgrade` module defines a `Plan` type in which a live upgrade is scheduled -to occur. A `Plan` can be scheduled at a specific block height. -A `Plan` is created once a (frozen) release candidate along with an appropriate upgrade -`Handler` (see below) is agreed upon, where the `Name` of a `Plan` corresponds to a -specific `Handler`. Typically, a `Plan` is created through a governance proposal -process, where if voted upon and passed, will be scheduled. The `Info` of a `Plan` -may contain various metadata about the upgrade, typically application specific -upgrade info to be included on-chain such as a git commit that validators could -automatically upgrade to. - -```go -type Plan struct { - Name string - Height int64 - Info string -} -``` - -#### Sidecar Process - -If an operator running the application binary also runs a sidecar process to assist -in the automatic download and upgrade of a binary, the `Info` allows this process to -be seamless. This tool is [Cosmovisor](https://github.com/cosmos/cosmos-sdk/tree/main/tools/cosmovisor#readme). - -### Handler - -The `x/upgrade` module facilitates upgrading from major version X to major version Y. To -accomplish this, node operators must first upgrade their current binary to a new -binary that has a corresponding `Handler` for the new version Y. It is assumed that -this version has fully been tested and approved by the community at large. This -`Handler` defines what state migrations need to occur before the new binary Y -can successfully run the chain. Naturally, this `Handler` is application specific -and not defined on a per-module basis. Registering a `Handler` is done via -`Keeper#SetUpgradeHandler` in the application. - -```go -type UpgradeHandler func(Context, Plan, VersionMap) (VersionMap, error) -``` - -During each `EndBlock` execution, the `x/upgrade` module checks if there exists a -`Plan` that should execute (is scheduled at that height). If so, the corresponding -`Handler` is executed. If the `Plan` is expected to execute but no `Handler` is registered -or if the binary was upgraded too early, the node will gracefully panic and exit. - -### StoreLoader - -The `x/upgrade` module also facilitates store migrations as part of the upgrade. The -`StoreLoader` sets the migrations that need to occur before the new binary can -successfully run the chain. This `StoreLoader` is also application specific and -not defined on a per-module basis. Registering this `StoreLoader` is done via -`app#SetStoreLoader` in the application. - -```go -func UpgradeStoreLoader (upgradeHeight int64, storeUpgrades *store.StoreUpgrades) baseapp.StoreLoader -``` - -If there's a planned upgrade and the upgrade height is reached, the old binary writes `Plan` to the disk before panicking. - -This information is critical to ensure the `StoreUpgrades` happens smoothly at correct height and -expected upgrade. It eliminiates the chances for the new binary to execute `StoreUpgrades` multiple -times everytime on restart. Also if there are multiple upgrades planned on same height, the `Name` -will ensure these `StoreUpgrades` takes place only in planned upgrade handler. - -### Proposal - -Typically, a `Plan` is proposed and submitted through governance via a proposal -containing a `MsgSoftwareUpgrade` message. -This proposal prescribes to the standard governance process. If the proposal passes, -the `Plan`, which targets a specific `Handler`, is persisted and scheduled. The -upgrade can be delayed or hastened by updating the `Plan.Height` in a new proposal. - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/upgrade/v1beta1/tx.proto#L29-L41 -``` - -#### Cancelling Upgrade Proposals - -Upgrade proposals can be cancelled. There exists a gov-enabled `MsgCancelUpgrade` -message type, which can be embedded in a proposal, voted on and, if passed, will -remove the scheduled upgrade `Plan`. -Of course this requires that the upgrade was known to be a bad idea well before the -upgrade itself, to allow time for a vote. - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/upgrade/v1beta1/tx.proto#L48-L57 -``` - -If such a possibility is desired, the upgrade height is to be -`2 * (VotingPeriod + DepositPeriod) + (SafetyDelta)` from the beginning of the -upgrade proposal. The `SafetyDelta` is the time available from the success of an -upgrade proposal and the realization it was a bad idea (due to external social consensus). - -A `MsgCancelUpgrade` proposal can also be made while the original -`MsgSoftwareUpgrade` proposal is still being voted upon, as long as the `VotingPeriod` -ends after the `MsgSoftwareUpgrade` proposal. - -## State - -The internal state of the `x/upgrade` module is relatively minimal and simple. The -state contains the currently active upgrade `Plan` (if one exists) by key -`0x0` and if a `Plan` is marked as "done" by key `0x1`. The state -contains the consensus versions of all app modules in the application. The versions -are stored as big endian `uint64`, and can be accessed with prefix `0x2` appended -by the corresponding module name of type `string`. The state maintains a -`Protocol Version` which can be accessed by key `0x3`. - -* Plan: `0x0 -> Plan` -* Done: `0x1 | byte(plan name) -> BigEndian(Block Height)` -* ConsensusVersion: `0x2 | byte(module name) -> BigEndian(Module Consensus Version)` -* ProtocolVersion: `0x3 -> BigEndian(Protocol Version)` - -The `x/upgrade` module contains no genesis state. - -## Events - -The `x/upgrade` does not emit any events by itself. Any and all proposal related -events are emitted through the `x/gov` module. - -## Client - -### CLI - -A user can query and interact with the `upgrade` module using the CLI. - -#### Query - -The `query` commands allow users to query `upgrade` state. - -```bash -simd query upgrade --help -``` - -##### applied - -The `applied` command allows users to query the block header for height at which a completed upgrade was applied. - -```bash -simd query upgrade applied [upgrade-name] [flags] -``` - -If upgrade-name was previously executed on the chain, this returns the header for the block at which it was applied. -This helps a client determine which binary was valid over a given range of blocks, as well as more context to understand past migrations. - -Example: - -```bash -simd query upgrade applied "test-upgrade" -``` - -Example Output: - -```bash -"block_id": { - "hash": "A769136351786B9034A5F196DC53F7E50FCEB53B48FA0786E1BFC45A0BB646B5", - "parts": { - "total": 1, - "hash": "B13CBD23011C7480E6F11BE4594EE316548648E6A666B3575409F8F16EC6939E" - } - }, - "block_size": "7213", - "header": { - "version": { - "block": "11" - }, - "chain_id": "testnet-2", - "height": "455200", - "time": "2021-04-10T04:37:57.085493838Z", - "last_block_id": { - "hash": "0E8AD9309C2DC411DF98217AF59E044A0E1CCEAE7C0338417A70338DF50F4783", - "parts": { - "total": 1, - "hash": "8FE572A48CD10BC2CBB02653CA04CA247A0F6830FF19DC972F64D339A355E77D" - } - }, - "last_commit_hash": "DE890239416A19E6164C2076B837CC1D7F7822FC214F305616725F11D2533140", - "data_hash": "E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855", - "validators_hash": "A31047ADE54AE9072EE2A12FF260A8990BA4C39F903EAF5636B50D58DBA72582", - "next_validators_hash": "A31047ADE54AE9072EE2A12FF260A8990BA4C39F903EAF5636B50D58DBA72582", - "consensus_hash": "048091BC7DDC283F77BFBF91D73C44DA58C3DF8A9CBC867405D8B7F3DAADA22F", - "app_hash": "28ECC486AFC332BA6CC976706DBDE87E7D32441375E3F10FD084CD4BAF0DA021", - "last_results_hash": "E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855", - "evidence_hash": "E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855", - "proposer_address": "2ABC4854B1A1C5AA8403C4EA853A81ACA901CC76" - }, - "num_txs": "0" -} -``` - -##### module versions - -The `module_versions` command gets a list of module names and their respective consensus versions. - -Following the command with a specific module name will return only -that module's information. - -```bash -simd query upgrade module_versions [optional module_name] [flags] -``` - -Example: - -```bash -simd query upgrade module_versions -``` - -Example Output: - -```bash -module_versions: -- name: auth - version: "2" -- name: authz - version: "1" -- name: bank - version: "2" -- name: crisis - version: "1" -- name: distribution - version: "2" -- name: evidence - version: "1" -- name: feegrant - version: "1" -- name: genutil - version: "1" -- name: gov - version: "2" -- name: ibc - version: "2" -- name: mint - version: "1" -- name: params - version: "1" -- name: slashing - version: "2" -- name: staking - version: "2" -- name: transfer - version: "1" -- name: upgrade - version: "1" -- name: vesting - version: "1" -``` - -Example: - -```bash -regen query upgrade module_versions ibc -``` - -Example Output: - -```bash -module_versions: -- name: ibc - version: "2" -``` - -##### plan - -The `plan` command gets the currently scheduled upgrade plan, if one exists. - -```bash -regen query upgrade plan [flags] -``` - -Example: - -```bash -simd query upgrade plan -``` - -Example Output: - -```bash -height: "130" -info: "" -name: test-upgrade -time: "0001-01-01T00:00:00Z" -upgraded_client_state: null -``` - -#### Transactions - -The upgrade module supports the following transactions: - -* `software-proposal` - submits an upgrade proposal: - -```bash -simd tx upgrade software-upgrade v2 --title="Test Proposal" --summary="testing" --deposit="100000000stake" --upgrade-height 1000000 \ ---upgrade-info '{ "binaries": { "linux/amd64":"https://example.com/simd.zip?checksum=sha256:aec070645fe53ee3b3763059376134f058cc337247c978add178b6ccdfb0019f" } }' --from cosmos1.. -``` - -* `cancel-software-upgrade` - cancels a previously submitted upgrade proposal: - -```bash -simd tx upgrade cancel-software-upgrade --title="Test Proposal" --summary="testing" --deposit="100000000stake" --from cosmos1.. -``` - -### REST - -A user can query the `upgrade` module using REST endpoints. - -#### Applied Plan - -`AppliedPlan` queries a previously applied upgrade plan by its name. - -```bash -/cosmos/upgrade/v1beta1/applied_plan/{name} -``` - -Example: - -```bash -curl -X GET "http://localhost:1317/cosmos/upgrade/v1beta1/applied_plan/v2.0-upgrade" -H "accept: application/json" -``` - -Example Output: - -```bash -{ - "height": "30" -} -``` - -#### Current Plan - -`CurrentPlan` queries the current upgrade plan. - -```bash -/cosmos/upgrade/v1beta1/current_plan -``` - -Example: - -```bash -curl -X GET "http://localhost:1317/cosmos/upgrade/v1beta1/current_plan" -H "accept: application/json" -``` - -Example Output: - -```bash -{ - "plan": "v2.1-upgrade" -} -``` - -#### Module versions - -`ModuleVersions` queries the list of module versions from state. - -```bash -/cosmos/upgrade/v1beta1/module_versions -``` - -Example: - -```bash -curl -X GET "http://localhost:1317/cosmos/upgrade/v1beta1/module_versions" -H "accept: application/json" -``` - -Example Output: - -```bash -{ - "module_versions": [ - { - "name": "auth", - "version": "2" - }, - { - "name": "authz", - "version": "1" - }, - { - "name": "bank", - "version": "2" - }, - { - "name": "crisis", - "version": "1" - }, - { - "name": "distribution", - "version": "2" - }, - { - "name": "evidence", - "version": "1" - }, - { - "name": "feegrant", - "version": "1" - }, - { - "name": "genutil", - "version": "1" - }, - { - "name": "gov", - "version": "2" - }, - { - "name": "ibc", - "version": "2" - }, - { - "name": "mint", - "version": "1" - }, - { - "name": "params", - "version": "1" - }, - { - "name": "slashing", - "version": "2" - }, - { - "name": "staking", - "version": "2" - }, - { - "name": "transfer", - "version": "1" - }, - { - "name": "upgrade", - "version": "1" - }, - { - "name": "vesting", - "version": "1" - } - ] -} -``` - -### gRPC - -A user can query the `upgrade` module using gRPC endpoints. - -#### Applied Plan - -`AppliedPlan` queries a previously applied upgrade plan by its name. - -```bash -cosmos.upgrade.v1beta1.Query/AppliedPlan -``` - -Example: - -```bash -grpcurl -plaintext \ - -d '{"name":"v2.0-upgrade"}' \ - localhost:9090 \ - cosmos.upgrade.v1beta1.Query/AppliedPlan -``` - -Example Output: - -```bash -{ - "height": "30" -} -``` - -#### Current Plan - -`CurrentPlan` queries the current upgrade plan. - -```bash -cosmos.upgrade.v1beta1.Query/CurrentPlan -``` - -Example: - -```bash -grpcurl -plaintext localhost:9090 cosmos.slashing.v1beta1.Query/CurrentPlan -``` - -Example Output: - -```bash -{ - "plan": "v2.1-upgrade" -} -``` - -#### Module versions - -`ModuleVersions` queries the list of module versions from state. - -```bash -cosmos.upgrade.v1beta1.Query/ModuleVersions -``` - -Example: - -```bash -grpcurl -plaintext localhost:9090 cosmos.slashing.v1beta1.Query/ModuleVersions -``` - -Example Output: - -```bash -{ - "module_versions": [ - { - "name": "auth", - "version": "2" - }, - { - "name": "authz", - "version": "1" - }, - { - "name": "bank", - "version": "2" - }, - { - "name": "crisis", - "version": "1" - }, - { - "name": "distribution", - "version": "2" - }, - { - "name": "evidence", - "version": "1" - }, - { - "name": "feegrant", - "version": "1" - }, - { - "name": "genutil", - "version": "1" - }, - { - "name": "gov", - "version": "2" - }, - { - "name": "ibc", - "version": "2" - }, - { - "name": "mint", - "version": "1" - }, - { - "name": "params", - "version": "1" - }, - { - "name": "slashing", - "version": "2" - }, - { - "name": "staking", - "version": "2" - }, - { - "name": "transfer", - "version": "1" - }, - { - "name": "upgrade", - "version": "1" - }, - { - "name": "vesting", - "version": "1" - } - ] -} -``` - -## Resources - -A list of (external) resources to learn more about the `x/upgrade` module. - -* [Cosmos Dev Series: Cosmos Blockchain Upgrade](https://medium.com/web3-surfers/cosmos-dev-series-cosmos-sdk-based-blockchain-upgrade-b5e99181554c) - The blog post that explains how software upgrades work in detail. diff --git a/.gitbook/developers/modules/injective/README.md b/.gitbook/developers/modules/injective/README.md deleted file mode 100644 index 8a5fa20d..00000000 --- a/.gitbook/developers/modules/injective/README.md +++ /dev/null @@ -1,14 +0,0 @@ -import { - HomepageSection as Section -} from "../../../../src/components/HomepageComponents"; -import ComponentsGrid from "@theme/DocCardList"; - -# Injective Modules - -
- -
diff --git a/.gitbook/developers/modules/injective/auction/01_state.md b/.gitbook/developers/modules/injective/auction/01_state.md deleted file mode 100644 index ecb09d89..00000000 --- a/.gitbook/developers/modules/injective/auction/01_state.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -sidebar_position: 1 -title: State ---- - -# State - -## Params - -Params is a module-wide configuration structure that stores system parameters and defines overall functioning of the auction module. - -- Params: `Paramsspace("auction") -> legacy_amino(params)` - -```go -type Params struct { - // auction_period_duration defines the auction period duration - AuctionPeriod int64 - // min_next_bid_increment_rate defines the minimum increment rate for new bids - MinNextBidIncrementRate math.LegacyDec -} -``` - -### **LastBid** - -Keeps track of the current highest bid - -* LastBid: `0x01 -> ProtocolBuffer(Bid)` - -```go -type Bid struct { - Bidder string - Amount sdk.Coin -} -``` - -### **AuctionRound** - -The current auction round. - -* AuctionRound: `0x03 -> BigEndian(AuctionRound)` - -### **EndingTimeStamp** - -This value is compared against current block time to decide an auction round settlement. When the exported chain is imported again, the EndingTimeStamp will be updated to the next value in future. - -* `EndingTimeStamp`: `0x04 -> BigEndian(EndingTimestamp)` - -### **LastAuctionResult** - -Keeps track of the last auction result. - -* LastAuctionResult: `0x05 -> ProtocolBuffer(LastAuctionResult)` - -```go -type LastAuctionResult struct { - Winner string - Amount sdk.Coin - Round uint64 -} -``` diff --git a/.gitbook/developers/modules/injective/auction/02_messages.md b/.gitbook/developers/modules/injective/auction/02_messages.md deleted file mode 100644 index 97f7253f..00000000 --- a/.gitbook/developers/modules/injective/auction/02_messages.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -sidebar_position: 2 -title: Messages ---- - -# Messages - -In this section we describe the processing of the auction messages and the corresponding updates to the state. - -## Msg/Bid - -An auction basket from a given round is bid upon by using the `Msg/Bid` service message. - -```protobuf -// Bid defines a SDK message for placing a bid for an auction -message MsgBid { - option (gogoproto.equal) = false; - option (gogoproto.goproto_getters) = false; - string sender = 1; - // amount of the bid in INJ tokens - cosmos.base.v1beta1.Coin bid_amount = 2 [(gogoproto.nullable) = false]; - // the current auction round being bid on - uint64 round = 3; -} -``` - -This service message is expected to fail if: - -- `Round` does not equal the current auction round -- `BidAmount` does not exceed the previous highest bid amount by at least `min_next_increment_rate` percent. - -This service message transfers the `BidAmount` of INJ from the `Sender` to the auction module, stores the bid, and refunds the last bidder's bid amount. diff --git a/.gitbook/developers/modules/injective/auction/03_end_block.md b/.gitbook/developers/modules/injective/auction/03_end_block.md deleted file mode 100644 index 88018bc3..00000000 --- a/.gitbook/developers/modules/injective/auction/03_end_block.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -sidebar_position: 3 -title: End-Block ---- - -# End-Block - -### Auction Settlement - -The settlement of a given auction round occurs when `blockTime ≥ EndingTimeStamp.` If a non-zero INJ bid was placed during this period (i.e. there exists a `LastBid`), the following procedure will take place: - -- The winning INJ bid amount is burned. -- The basket of coins held by the auction module is transferred to the winning bidder. -- `LastAuctionResult` is written to state and `EventAuctionResult` is emitted. -- The `LastBid` is cleared. -- The AuctionRound is incremented by 1 and the EndingTimestamp is incremented by `AuctionPeriod`. -- The accumulated exchange fees are transferred from the `exchange` module to the `auction` module for the new upcoming auction. - -If the round closed without any successful bids, the existing coin basket will be rolled over into the next auction and combined with the new accumulated fee basket. - -![img.png](./img.png) \ No newline at end of file diff --git a/.gitbook/developers/modules/injective/auction/04_events.md b/.gitbook/developers/modules/injective/auction/04_events.md deleted file mode 100644 index ed87d2d7..00000000 --- a/.gitbook/developers/modules/injective/auction/04_events.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -sidebar_position: 4 -title: Events ---- - -# Events - -The auction module emits the following events: - -## Handlers - -### Msg/Bid - -| Type | Attribute Key | Attribute Value | -| ---------------- | ------------- | ------------------ | -| EventBid | Bidder | | -| EventBid | Amount | | -| EventBid | Round | | - - -## EndBlocker - -| Type | Attribute Key | Attribute Value | -| --------------------- | --------------------- | ------------------------- | -| EventAuctionResult | Winner | -| EventAuctionResult | Amount | -| EventAuctionResult | Round | - diff --git a/.gitbook/developers/modules/injective/auction/05_params.md b/.gitbook/developers/modules/injective/auction/05_params.md deleted file mode 100644 index 2f56a4a4..00000000 --- a/.gitbook/developers/modules/injective/auction/05_params.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -sidebar_position: 5 -title: Parameters ---- - -# Parameters - -The auction module contains the following parameters: - -| Key | Type | Example | -|-------------------|------------------|-------------------| -| AuctionPeriod | int64 | 604800 | -| MinNextBidIncrementRate | math.LegacyDec | "0.0025" | - diff --git a/.gitbook/developers/modules/injective/auction/README.md b/.gitbook/developers/modules/injective/auction/README.md deleted file mode 100644 index 55f22fdc..00000000 --- a/.gitbook/developers/modules/injective/auction/README.md +++ /dev/null @@ -1,15 +0,0 @@ -# `Auction` - -## Abstract - -The `auction` module periodically obtains a basket of tokens accumulated from trading fees from the `exchange` module and auctions the basket to the highest bidder in an open English auction for INJ. The winner of this auction receives the basket of tokens and the winning INJ bid amount from this auction is burned. - -## Contents - -1. **[State](./01_state.md)** -2. **[Messages](./02_messages.md)** -3. **[End Block](./03_end_block.md)** -4. **[Events](./04_events.md)** -5. **[Params](./05_params.md)** - - diff --git a/.gitbook/developers/modules/injective/auction/img.png b/.gitbook/developers/modules/injective/auction/img.png deleted file mode 100644 index 10dad042..00000000 Binary files a/.gitbook/developers/modules/injective/auction/img.png and /dev/null differ diff --git a/.gitbook/developers/modules/injective/exchange/00_derivative_market_concepts.md b/.gitbook/developers/modules/injective/exchange/00_derivative_market_concepts.md deleted file mode 100644 index f1227953..00000000 --- a/.gitbook/developers/modules/injective/exchange/00_derivative_market_concepts.md +++ /dev/null @@ -1,244 +0,0 @@ ---- -sidebar_position: 1 -title: Derivative Market Concept ---- - -# Derivative Market Concepts - -## Definitions - -In a derivative market using linear contracts (as opposed to inverse contracts), a contract with ticker **AAA/BBB** -offers exposure to the underlying AAA using the quote currency BBB for margin and settlement. For each contract, the -quotation unit is the BBB price of one unit of AAA, e.g. the USDT price of one unit of ETH. - -**Notional** - the notional value of a position is: `notional = quantity * price`. - -**Refunds -** In our clearing system, a refund refers to the action of incrementing the **available balance** of an -account. This liberation of funds occurs as the result of an encumbrance being lifted from the account (e.g. cancelling -a limit order, reducing an order's payable fee to a maker fee, using less margin to fund a market order, etc.). - -## Perpetual Market Trading Lifecycle - -### Perpetual Market Creation - -A market is first created either by the instant launch functionality through `MsgInstantPerpetualMarketLaunch` or `MsgInstantExpiryFuturesMarketLaunch` which creates a market by paying an extra fee which doesn't require governance to approve it. Or it is created in the normal way through governance through `MsgPerpetualMarketLaunchProposal` or `MsgExpiryFuturesMarketLaunchProposal`. - -### Balance Management - -#### Depositing Funds into Exchange - -A trader can deposit funds, e.g., USDT, into the exchange by sending a `MsgDeposit` which transfers coins from the -Cosmos-SDK bank module to the trader's subaccount deposits on the exchange module. - -Depositing a given `Amount` of coin will increment both the trader's subaccount deposit `AvailableBalance` -and `TotalBalance` by `Amount`. - -#### Withdrawing Funds from Exchange - -A trader can withdraw funds from the exchange by sending a `MsgWithdraw` which transfers coins from the trader's subaccount -on the exchange module. - -**Withdrawal Requirement:** Withdrawing a given `Amount` of coin will decrement both the trader's subaccount -deposit `AvailableBalance` and `TotalBalance` by `Amount`. Note: `Amount` must be less than or equal -to `AvailableBalance`. - -#### Transferring Funds between Subaccounts - -A trader can transfer funds between his own subaccounts sending a `MsgSubaccountTransfer` which transfer coins from one of -the trader's subaccount deposits to another subaccount also owned by the trader. - -Subaccount transfers have the same Withdrawal Requirement as normal withdrawals. - -#### Transferring Funds to another Exchange Account - -A trader can transfer funds to an external account by sending a `MsgExternalTransfer` which transfers funds from the -trader's subaccount to another third-party account. - -External Funds transfers have the same Withdrawal Requirement as normal withdrawals. - -### Order Management - -#### Placing Limit Orders - -A trader can post a limit buy or sell order by sending a `MsgCreateDerivativeLimitOrder`. Upon submission, the order can -be: - -1. Immediately (fully or partially) matched against other opposing resting orders on the orderbook in the Endblocker - batch auction, thus establishing a position for the user. -2. Added to the orderbook. - -Note that it is possible for an order to be partially matched and for the remaining unmatched portion to be added to the -orderbook. - -#### Placing Market Orders - -A trader can post a market buy or sell order by sending a `MsgCreateDerivativeMarketOrder`. Upon submission, the market -order will be executed against other opposing resting orders on the orderbook in the Endblocker batch auction, thus -establishing a position for the user. - -#### Cancelling Limit Orders - -User cancels a limit buy or sell order by sending a `MsgCancelDerivativeOrder` which removes the user's limit order from -the orderbook. - -### Increasing Position Margin - -A user can increase the margin of a position by sending a `MsgIncreasePositionMargin`. - -### Liquidating Insolvent Positions - -A third party can liquidate any user's position if the position's maintenance margin ratio is breached by sending a -`MsgLiquidatePosition`. - -**Initial Margin Requirement** - -This is the requirement for the ratio of margin to the order's notional as well as the mark price when creating a new position. -The idea behind the additional mark price requirement is to minimize the liquidation risk when traded prices and mark prices -temporally diverge too far from each other. Given the initial margin ratio, an order must fulfill two requirements: - -- The margin must fulfill: `Margin ≥ InitialMarginRatio * Price * Quantity`, e.g., in a market with maximally 20x leverage, - the initial margin ratio would be 0.05. Any new position will have a margin which is at least 0.05 of its notional. -- The margin must fulfill the mark price requirement: - -- `Margin >= Quantity * (InitialMarginRatio * MarkPrice - PNL)` - -PNL is the expected profit and loss of the position if it was closed at the current MarkPrice. Solved for MarkPrice this results in: - -- For Buys: $\mathrm{MarkPrice}$ ≥ $\mathrm{\frac{Margin - Price * Quantity}{(InitialMarginRatio - 1) * Quantity}}$ -- For Sells: $\mathrm{MarkPrice}$ ≤ $\mathrm{\frac{Margin + Price * Quantity}{(InitialMarginRatio + 1) * Quantity}}$ - -**Maintenance Margin Requirement** - -Throughout the lifecycle of an active position, if the following margin requirement is not met, the position is subject -to liquidation. (Note: for simplicity of notation but without loss of generality, we assume the position considered does -not have any funding). - -- For Longs: `Margin >= Quantity * MaintenanceMarginRatio * MarkPrice - (MarkPrice - EntryPrice)` -- For Shorts: `Margin >= Quantity * MaintenanceMarginRatio * MarkPrice - (EntryPrice - MarkPrice)` - -**Liquidation Payouts** - -When your position falls below the maintenance margin ratio, the position can be liquidated by anyone. What happens on-chain is that automatically a reduce-only market order of the same size as the position is created. The market order will have a worst price defined as _Infinity_ or _0_, implying it will be matched at whatever prices are available in the order book. - -The payout from executing the reduce-only market order will not go towards the position owner. Instead, a part of the remaining funds are transferred to the liquidator bot and the other part is transferred to the insurance fund. The split is defined in the exchange params by `LiquidatorRewardShareRate`. If the payout in the position was negative, i.e., the position's negative PNL was greater than its margin, then the insurance fund will cover the missing funds. - -Also note that liquidations are executed immediately in a block before any other order matching occurs. - -### Funding Payments - -Funding exists only for perpetual markets as a mechanism to align trading prices with the mark price. It refers to the -periodic payments exchanged between the traders that are long or short of a contract at the end of every funding epoch, -e.g. every hour. When the funding rate is positive, longs pay shorts. When it is negative, shorts pay longs. - -- `Position Size = Position Quantity * MarkPrice` -- `Funding Payment = Position Size * Hourly Funding Rate (HFR)` -- `HFR = Cap((TWAP((SyntheticVWAPExecutionPrice - MarkPrice)/MarkPrice) + DailyInterestRate) * 1/24)` -- `SyntheticVWAPExecutionPrice = (Price_A*Volume_A +Price_B*Volume_B +Price_C*Volume_C)/(Volume_A + Volume_B + Volume_C)` - - `A` is the market buy batch execution - - `B` is the market sell batch execution - - `C` is the limit matching batch execution - -Funding payments are applied to the whole market by modifying the `CumulativeFunding` value. Each position stores the current `CumulativeFunding` as `CumulativeFundingEntry`. Subsequent funding payments are only applied upon position changes and can be calculated as: - -- FundingPayment - - For Longs: `FundingPayment ← PositionQuantity * (CumulativeFunding - CumulativeFundingEntry)` - - For Shorts: `FundingPayment ← PositionQuantity * (CumulativeFundingEntry - CumulativeFunding)` -- `Margin' ← Margin + FundingPayment` -- `CumulativeFundingEntry' ← CumulativeFunding` - -## Perpetual Market Trading Specification - -### Positions - -A trader's position records the conditions under which the trader has entered into the derivative contract and is -defined as follows - -- Position Definition: - - `Quantity` - - `EntryPrice` - - `Margin` - - `HoldQuantity` - - `CumulativeFundingEntry` - -As an example, consider the following position in the ETH/USDT market: - -- `Quantity` = -2 -- `EntryPrice` = 2200 -- `Margin` = 800 -- `HoldQuantity` = 1 -- `CumulativeFundingEntry` = 4838123 - -This position represents short exposure for 2 contracts of the ETH/USDT market collateralized with 800 USDT, with an -entry price of 2200. The `HoldQuantity` represents the quantity of the position that the trader has opposing orders for. -`CumulativeFundingEntry` represents the cumulative funding value that the position was last updated at. - -Position Netting: - -When a new vanilla order is matched for a subaccount with an existing position, the new position will be the result from -netting the existing position with the new vanilla order. A matched vanilla order produces a position delta defined by -`FillQuantity`, `FillMargin` and `ClearingPrice`. - -- Applying Position Delta to a position in the same direction: - - `Entry Price' ← (Quantity \* EntryPrice + FillQuantity \* ClearingPrice) / (Quantity + FillQuantity)` - - `Quantity' ← Quantity + FillQuantity` - - `Margin' ← Margin + FillMargin` -- Apply Position Delta to a position in the opposing direction: - - `Entry Price - no change` - - `Quantity' ← Quantity - FillQuantity` - - `Margin' ← Margin \* (Quantity - FillQuantity) / Quantity` - -### Limit Buy Order - -A limit buy order seeks to purchase a specified Quantity of a derivative contract at a specified Price by providing a -specified amount of margin as collateral. - -### Limit Sell Order - -A limit sell order seeks to sell a specified Quantity of a derivative contract at a specified Price by providing a -specified amount of margin as collateral. - -A matched position will have **subtracted fees** which depend on whether the limit order becomes executed as a -maker order or a taker order. - -### Market Buy Order - -A market buy order seeks to purchase a specified Quantity of a derivative contract at a specified worst price using -the subaccount's available balance as margin collateral. - -Handler and EndBlocker Execution of the market order are conceptually identical to the Limit Buy Order -(Immediately Matched case), since the trader passes the margin which implicitly sets a maximum price limit due to the -initial min margin requirements. - -### Market Sell Order - -A market sell order seeks to sell a specified Quantity of a derivative contract at a specified worst price using the -subaccount's available balance as margin collateral. - -Handler and EndBlocker Execution of the market order are conceptually identical to the Limit Sell Order -(Immediately Matched case), since the trader passes the margin which implicitly sets a minimum price limit due to the -initial min margin requirements. - -### Order Types - -- BUY (1): A standard buy order to purchase an asset at either the current market price or a set limit price. -- SELL (2): A standard sell order to sell an asset at either the current market price or a set limit price. -- STOP_BUY (3): A stop-buy order converts into a regular buy order once the oracle price reaches or surpasses a specified trigger price. -- STOP_SELL (4): A stop-sell order becomes a regular sell order once the oracle price drops to or below a specified trigger price. -- TAKE_BUY (5): A take-buy order converts into a regular buy order once the oracle price reaches or drops below a specified trigger price. -- TAKE_SELL (6):A stop-sell order becomes a regular sell order once the oracle price reaches or surpasses a specified trigger price. -- BUY_PO (7): Post-Only Buy. This order type ensures that the order will only be added to the order book and not match with a pre-existing order. It guarantees that you will be the market "maker" and not the "taker". -- SELL_PO (8): Post-Only Sell. Similar to BUY_PO, this ensures that your sell order will only add liquidity to the order book and not match with a pre-existing order. -- BUY_ATOMIC (9): An atomic buy order is a market order that gets executed instantly, bypassing the Frequent Batch Auctions (FBA). It's intended for smart contracts that need to execute a trade instantly. A higher fee is paid defined in the global exchange parameters. -- SELL_ATOMIC (10): An atomic sell order is similar to a BUY_ATOMIC, and it gets executed instantly at the current market price, bypassing the FBA. - -### Reduce-Only Orders (Selling Positions) - -### Limit Buy Reduce-Only Order - -A limit buy reduce-only order seeks to reduce existing long exposure by a specified `Quantity` ETH (**base currency**). -The payout for closing a position will have **subtracted fees**. - -### Limit Sell Reduce-Only Order - -A limit sell reduce-only order seeks to reduce existing short exposure by a specified `Quantity` ETH (**base currency**). -The payout for closing a position will have **subtracted fees**. diff --git a/.gitbook/developers/modules/injective/exchange/01_spot_market_concepts.md b/.gitbook/developers/modules/injective/exchange/01_spot_market_concepts.md deleted file mode 100644 index 6d413d33..00000000 --- a/.gitbook/developers/modules/injective/exchange/01_spot_market_concepts.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -sidebar_position: 2 -title: Spot Market Concepts ---- - -# Spot Market Concepts - -## Definitions - -In a Spot Market with ticker **AAA/BBB, AAA is the base asset, BBB is the quote asset.** - -For example, in the ETH/USDT market - -- ETH is base asset -- USDT is the quote asset - -The spot market's **price** refers to how much USDT (the quote asset) is required for one unit of ETH (the base -asset). For all spot markets, **fees are always paid in the quote asset**, e.g., USDT. - -**Debit vs Credit** - -- **Debit Amount** refers to the amount of asset that is withdrawn from an account. -- **Credit Amount** refers to the amount of asset that is deposited to an account. - -**Refunds** - -In our system, a refund refers to the action of incrementing the **available balance** of an account. This liberation of -funds occurs as the result of an encumbrance being lifted from the account (e.g. cancelling a limit order, reducing an -order's payable fee to a maker fee, using less margin to fund a market order, etc.). - -### Limit Buy Order - -A limit buy order seeks to buy a specified `Quantity` ETH (**base asset**) in exchange for `Quantity * Price` amount of -USDT (**quote asset**) **plus fees** which depend on whether the limit order becomes executed as a maker order or a -taker order. - -### Limit Sell Order - -A limit sell order seeks to sell a specified `Quantity` ETH (**base asset**) in exchange for `Quantity * Price` amount -of USDT (**quote asset**) **minus fees** which depend on whether the limit order becomes executed as a maker order or a -taker order. - -### Market Buy Order - -A market buy order seeks to buy a specified `Quantity` ETH (**base asset**) at a specified worst price which is at or near -the current ask using the respective account quote asset balance (USDT) as collateral\*\* (inclusive of fees). - -As a result, each market buy order implicitly has a maximum acceptable price associated with it, as filling the market -order beyond that price would simply fail due to a lack of funds. - -### Market Sell Order - -A market sell order seeks to sell a specified `Quantity` ETH (**base asset**) at a specified worst price which is at or -near the current bid in exchange for any amount of the quote asset (USDT) available in the market. - -As a result, each market sell order implicitly has a zero price associated with it. - -### Order Types - -- BUY (1): A standard buy order to purchase an asset at either the current market price or a set limit price. -- SELL (2): A standard sell order to sell an asset at either the current market price or a set limit price. -- STOP_BUY (3): This order type is not supported for spot markets. -- STOP_SELL (4): This order type is not supported for spot markets. -- TAKE_BUY (5): This order type is not supported for spot markets. -- TAKE_SELL (6): This order type is not supported for spot markets. -- BUY_PO (7): Post-Only Buy. This order type ensures that the order will only be added to the order book and not match with a pre-existing order. It guarantees that you will be the market "maker" and not the "taker". -- SELL_PO (8): Post-Only Sell. Similar to BUY_PO, this ensures that your sell order will only add liquidity to the order book and not match with a pre-existing order. -- BUY_ATOMIC (9): An atomic buy order is a market order that gets executed instantly, bypassing the Frequent Batch Auctions (FBA). It's intended for smart contracts that need to execute a trade instantly. A higher fee is paid defined in the global exchange parameters. -- SELL_ATOMIC (10): An atomic sell order is similar to a BUY_ATOMIC, and it gets executed instantly at the current market price, bypassing the FBA. - -### Market Data Requirements - -Orderbook data aside, so long as our Chain supports the **base capability** to obtain Tick by Tick trading data, -aggregations can be applied to obtain most of the necessary higher order data, including - -- OHLCV data -- Account Trading History -- Market Statistics - -## Spot Market Lifecycle - -### Governance based Spot Market Creation - -A market is first created either by the instant launch functionality through `MsgInstantSpotMarketLaunch` which creates a market by paying an extra fee which doesn't require governance to approve it. Or it is created in the normal way through governance through `MsgSpotMarketLaunchProposal`. - -### Listing Fee based Spot Market Creation - -Allow anyone to create an active spot market of their choice without requiring governance approval by burning a pre-set -SpotMarketInstantListingFee of INJ. - -We should still check that the denom is valid though. - -### Spot Market Status Update - -A Spot Market can exist in four different states: - -1. Active -2. Paused -3. Suspended -4. Demolished - -#### **Active State** - -If a spot market is an active state, it can accept orders and trades. - -#### Paused State - -If a spot market is a paused state, it will no longer accept orders and trades and will also not allow any users to take -actions on that market (no order cancellations). - -#### Suspended State - -If a spot market is a suspended state, it will no longer accept orders and trades, and will only allow traders to cancel -their orders. - -## Demolished State - -When a market becomes demolished, all outstanding orders are cancelled. - -#### Market Status State Transitions - -There are three state transitions that correspond to the following status changes - -- Activate Action - **Paused or Suspended Status → Active Status** -- Pause Action - **Active or Suspended Status → Paused Status** -- Suspend Action - **Active or Paused Status → Suspended Status** -- Demolish Action - **Paused or Suspended Status → Demolished Status** - -### Spot Market Parameter Update - -The following parameters exist for Spot Markets - -- SpotMarketInstantListingFee -- DefaultSpotMakerFeeRate -- DefaultSpotTakerFeeRate diff --git a/.gitbook/developers/modules/injective/exchange/02_binary_options_markets.md b/.gitbook/developers/modules/injective/exchange/02_binary_options_markets.md deleted file mode 100644 index 8e9dc11f..00000000 --- a/.gitbook/developers/modules/injective/exchange/02_binary_options_markets.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -sidebar_position: 2 -title: Binary Options Markets ---- - -# Binary Options Markets - -## Concept - -Binary options markets don't have base asset as other markets do, and they are quoted in **USDT** (there is a possibility other quote assets will be added later). Tickers for binary options markets usually follow the scheme of **UFC-KHABIB-TKO-09082022** or similar. Typically, binary options markets are used for betting on sport events, but can also be used for betting on any outcome. All markets have possible price bands between $0.00 and $1.00 with users able to put in orders from $0.01 to $0.99. ($0.00 and $1.00 respectively show an end condition that the outcome did not occur or did). The price submitted in the order is essentially an assumed probability of the given event (market) occurring. - -For all binary options markets, **fees are always paid in the quote asset**, e.g., USDT. - -There is no leverage in these type of markets, as users trade against each other in a zero-sum market. From this the other requirement is implied: if one side of a bet believes the event will occur (YES side), and current market probability for this exact event is *P* (which means the current market price is *P*), opposing side of the bet should be certain that the event will not happen with *(1-P)* probability. Thus, if the person on YES side buys *Q* number of contracts with the price *P*, he locks *Q\*P* of his balance as his margin, while opposing NO side (seller side) should lock *Q\*(1-P)* of his quote balance as margin. - -**Example:** - -Alice buys 1 contract at $0.20 (margined with $0.20) against Bob who sells 1 contract at $0.20 (margined with $0.80), creating positions for both of them. - -- Alice wins $0.80 if the market settles at $1 and Bob wins $0.2 if the market settles at $0. - -## Oracle - -Binary options markets are tightly coupled to the Provider Oracle type, which allows a governance-registered provider to relay price feed data for arbitrary new price feeds under the provider's subtype without the need for extra governance for adding successively new price feeds. Each binary options market is comprised of the following oracle parameters: -* Oracle symbol (e.g. UFC-KHABIB-TKO-09082022) -* Oracle provider (e.g. frontrunner) -* Oracle type (required to be provider) -* Oracle scale factor (e.g. 6 if the quote denom is USDT) - -The main goal of the oracle is to post the final outcome of the event. This final price settles the market at that exact price. This price is expected to be equal to be 0 or 1 most of the time, reflective of the binary outcome. - -Moreover, the market could be settled at any price within the (0, 1) price band. In case the *settlement_price* posted by oracle is between 0 or 1, all positions will be closed at the *settlement_price* (e.g. 0.42). If the oracle price exceeds 1, the settlement price will be rounded down to 1. - -Oracle can also post the final price of **-1**, which is the flag price than triggers refunding of all positions in the current market and demolishes the market. If there is no oracle update ever prior to settlement, then an oracle price of -1 will be used by default to trigger the refunds of all positions. - -Further documentation on the oracle provider type can be found in the Oracle module documentation. - -### Registering an oracle provider - -To register your oracle provider, you need to submit a `GrantProviderPrivilegeProposal` governance proposal. This proposal will register your provider and will allow your address to relay price feeds. - -```go -type GrantProviderPrivilegeProposal struct { - Title string - Description string - Provider string // the name of the provider, should be specific to you - Relayers []string // addresses which will be able to relay prices -} -``` - -Once the proposal passes, your provider will be registered and you'll be able to relay your price feeds (example below). - -## Market Lifecycle - -### Market Creation -A binary options market can be created through an instant launch (through a `MsgInstantBinaryOptionsMarketLaunch`) or through governance (through a `BinaryOptionsMarketLaunchProposal`). - -The market may be optionally configured with a market admin which has the ability to trigger settlement, change the market status as well as modify the expiration and settlement timestamp of the given market. If the market does not specify an admin, then the market parameters can only be modified through governance and that the settlement procedure will be fully based on the associated oracle provider price feed. - -### Market State Transitions -Binary options markets can take one of three statuses on Injective: Active, Expired or Demolished. After the market is created, the market has an `Active` status, which signifies that individuals can begin trading. - -Pertinently, binary options markets also have a characteristic `ExpirationTimestamp` which specifies the deadline at which trading activity for the market ceases as well as a `SettlementTimestamp` which specifies the deadline at which settlement will occur by (which must be after expiration). - -* **Active** = trading is open -* **Expired** = trading is closed, open orders are cancelled, no change to positions. -* **Demolished** = positions are settled / refunded (depending on the settlement), market is demolished - -The nature of the status transitions for binary options markets are as follows: - -| Status Change | Workflow | -| --- | --- | -| Active → Expired | Expiration is part of the standard workflow for a market. Trading is halted immediately for the market and all open orders are cancelled. The market can now be settled immediately (forcefully) by the admin or oracle or be settled naturally using the latest oracle price when we reach SettlementTimestamp. -| Expired → Demolished (Settlement) | All positions are settled at either the price set by forceful settlement or natural settlement. The market can never be traded on or reactivated again. For natural settlement, upon the SettlementTimestamp time, the last oracle price is recorded and used for settlement. For ‘force-settle’, Admin should post the MarketUpdate msg with SettlementPrice in it being set in a price band of [0, 1]. -| Active/Expired → Demolished (Refund) | All positions get refunded. The market can never be traded on or reactivated again. Admin should post the MarketUpdate msg with SettlementPrice in it being set to -1. | - - -### Market Settlement - -The settlement price options are explained above in the [oracle](#oracle) section. - -Settling a market can be achieved using one of these two options: -1. Using the registered provider oracle for the particular market. Once the provider oracle is granted privileges to relay prices (explained above), the address with the privileges can relay prices for a particular price feed using the `MsgRelayProviderPrices` message. -```go -// MsgRelayProviderPrices defines a SDK message for setting a price through the provider oracle. -type MsgRelayProviderPrices struct { - Sender string - Provider string - Symbols []string - Prices []cosmossdk_io_math.LegacyDec -} -``` - -2. Using the `MsgAdminUpdateBinaryOptionsMarket` which allows the market's admin (creator) to submit a settlement price directly to the market. -```go -type MsgAdminUpdateBinaryOptionsMarket struct { - // new price at which market will be settled - SettlementPrice *Dec - // expiration timestamp - ExpirationTimestamp int64 - // expiration timestamp - SettlementTimestamp int64 - // Status of the market - Status MarketStatus -} - -// Where Status can be one of these options -enum MarketStatus { - Unspecified = 0; - Active = 1; - Paused = 2; - Demolished = 3; - Expired = 4; -} -``` diff --git a/.gitbook/developers/modules/injective/exchange/02_other_concepts.md b/.gitbook/developers/modules/injective/exchange/02_other_concepts.md deleted file mode 100644 index e971f931..00000000 --- a/.gitbook/developers/modules/injective/exchange/02_other_concepts.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -sidebar_position: 3 -title: Other Concepts ---- - -# Other Concepts - -## Concurrency-Friendly Market Order Clearing Price Algorithm - -We apply the [split-apply-combine](https://stackoverflow.com/tags/split-apply-combine/info) paradigm to leverage -concurrency for efficient data processing. - -1. Match all matchable orders (see order matching for details) concurrently in all markets. - -- The intermediate result is a clearing price and a list of matched orders with their fill quantities. -- The final result is a temporary cache of all new events and all changes to positions, orders, subaccount deposits, - trading reward points and fees paid. - -2. Wait for execution on all markets and persist all data. - -Note: beyond just executing settlement, the design must also take into account market data dissemination requirements -for off-chain consumption. - -## Atomic Market Order Execution - -A common request from new applications built on Cosmwasm is for the ability to be notified upon the execution of an order. In the regular order execution flow, this would not be possible, since the Frequent Batch Auctions (FBA) are executed inside the EndBlocker. To circumvent the FBA, the new type of atomic market orders is introduced. For the privilege of executing such an atomic market order instantly, an additional trading fee is imposed. To calculate the fee of an atomic market order, the market's taker fee is multiplied by the market types's `AtomicMarketOrderFeeMultiplier`. - -- `SpotAtomicMarketOrderFeeMultiplier` -- `DerivativeAtomicMarketOrderFeeMultiplier` -- `BinaryOptionsAtomicMarketOrderFeeMultiplier` - -These multipliers are defined the global exchange parameters. In addition, the exchange parameters also define the `AtomicMarketOrderAccessLevel` which specifies the minimum access level required to execute an atomic market order. - -```golang -const ( - AtomicMarketOrderAccessLevel_Nobody AtomicMarketOrderAccessLevel = 0 - AtomicMarketOrderAccessLevel_BeginBlockerSmartContractsOnly AtomicMarketOrderAccessLevel = 1 - AtomicMarketOrderAccessLevel_SmartContractsOnly AtomicMarketOrderAccessLevel = 2 - AtomicMarketOrderAccessLevel_Everyone AtomicMarketOrderAccessLevel = 3 -) -``` - -## Trading Rewards - -Governance approves a **TradingRewardCampaignLaunchProposal** which specifies: - -- The first campaign's starting timestamp -- The **TradingRewardCampaignInfo** which specifies - - The campaign duration in seconds - - The accepted trading fee quote currency denoms - - The optional market-specific **boost** info - - The disqualified marketIDs for markets in which trades will not earn rewards -- The **CampaignRewardPools** which specifies the maximum epoch rewards that constitute the trading rewards pool for each successive campaign - -During a given campaign, the exchange will record each trader's cumulative trading reward points obtained from trading volume (with boosts applied, if applicable) from all eligible markets, i.e., markets with a matching quote currency that are not in the disqualified list. - -At the end of each campaign, i.e., after the `campaign starting timestamp + campaign duration` has elapsed, each trader will receive a pro-rata percentage of the trading rewards pool based off their trading rewards points from that campaign epoch. - -Campaigns will not auto-rollover. If there are no additional campaigns defined inside **CampaignRewardPools**, the trading reward campaigns will finish. - -## Fee Discounts - -Governance approves a **FeeDiscountProposal** which defines a fee discount **schedule** which specifies fee discount **tiers** which each specify the maker and taker discounts rates a trader will receive if they satisfy the specified minimum INJ staked amount AND have had at least the specified trading volume (based on the specified **quote denoms**) over the specified time period (`bucket count * bucket duration seconds`, which should equal 30 days). The schedule also specifies a list of disqualified marketIDs for markets whose trading volume will not count towards the volume contribution. - -- Spot markets where the base and quote are both in the accepted quote currencies list will not be rewarded (e.g. the USDC/USDT spot market). -- Maker fills in markets with negative maker fees will NOT give the trader any fee discounts. -- If the fee discount proposal was passed less than 30 days ago, i.e. `BucketCount * BucketDuration` hasn't passed yet since the creation of the proposal, the fee volume requirement is ignored so we don't unfairly penalize market makers who onboard immediately. - -Internally the trading volumes are stored in buckets, typically 30 buckets each lasting 24 hours. When a bucket is older than 30 days, it gets removed. Additionally for performance reasons there is a cache for retrieving the fee discount tier for an account. This cache is updated every 24 hours. diff --git a/.gitbook/developers/modules/injective/exchange/03_state.md b/.gitbook/developers/modules/injective/exchange/03_state.md deleted file mode 100644 index 719cc7b2..00000000 --- a/.gitbook/developers/modules/injective/exchange/03_state.md +++ /dev/null @@ -1,594 +0,0 @@ ---- -sidebar_position: 4 -title: State ---- - -# State - -Genesis state defines the initial state of the module to be used to setup the module. - -```go -// GenesisState defines the exchange module's genesis state. -type GenesisState struct { - // params defines all the parameters of related to exchange. - Params Params - // accounts is an array containing the genesis trade pairs - SpotMarkets []*SpotMarket - // accounts is an array containing the genesis derivative markets - DerivativeMarkets []*DerivativeMarket - // spot_orderbook defines the spot exchange limit orderbook active at genesis. - SpotOrderbook []SpotOrderBook - // derivative_orderbook defines the derivative exchange limit orderbook active at genesis. - DerivativeOrderbook []DerivativeOrderBook - // balances defines the exchange users balances active at genesis. - Balances []Balance - // positions defines the exchange derivative positions at genesis - Positions []DerivativePosition - // subaccount_trade_nonces defines the subaccount trade nonces for the subaccounts at genesis - SubaccountTradeNonces []SubaccountNonce - // expiry_futures_market_info defines the market info for the expiry futures markets at genesis - ExpiryFuturesMarketInfoState []ExpiryFuturesMarketInfoState - // perpetual_market_info defines the market info for the perpetual derivative markets at genesis - PerpetualMarketInfo []PerpetualMarketInfo - // perpetual_market_funding_state defines the funding state for the perpetual derivative markets at genesis - PerpetualMarketFundingState []PerpetualMarketFundingState - // derivative_market_settlement_scheduled defines the scheduled markets for settlement at genesis - DerivativeMarketSettlementScheduled []DerivativeMarketSettlementInfo - // sets spot markets as enabled - IsSpotExchangeEnabled bool - // sets derivative markets as enabled - IsDerivativesExchangeEnabled bool - // the current trading reward campaign info - TradingRewardCampaignInfo *TradingRewardCampaignInfo - // the current and upcoming trading reward campaign pools - TradingRewardPoolCampaignSchedule []*CampaignRewardPool - // the current and upcoming trading reward account points - TradingRewardCampaignAccountPoints []*TradingRewardCampaignAccountPoints - // the current and upcoming trading reward campaign pending pools - PendingTradingRewardPoolCampaignSchedule []*CampaignRewardPool - // the pending trading reward account points - PendingTradingRewardCampaignAccountPoints []*TradingRewardCampaignAccountPendingPoints - // the fee discount schedule - FeeDiscountSchedule *FeeDiscountSchedule - // the cached fee discount account tiers with TTL - FeeDiscountAccountTierTtl []*FeeDiscountAccountTierTTL - // the fee discount paid by accounts in all buckets - FeeDiscountBucketFeesPaidAccounts []*FeeDiscountBucketFeesPaidAccounts - // sets the first fee cycle as finished - IsFirstFeeCycleFinished bool -} -``` - -## Params - -`Params` is a module-wide configuration that stores system parameters and defines overall functioning of the exchange module. -This configuration is modifiable by governance using params update proposal natively supported by `gov` module. - -It defines default fee objects to be used for spot and derivative markets and funding parameters for derivative markets and instant listing fees. - -Protobuf interface for the `exchange` module params store. - -```go -type Params struct { - // spot_market_instant_listing_fee defines the expedited fee in INJ required to create a spot market by bypassing governance - SpotMarketInstantListingFee types.Coin - // derivative_market_instant_listing_fee defines the expedited fee in INJ required to create a derivative market by bypassing governance - DerivativeMarketInstantListingFee types.Coin - // default_spot_maker_fee defines the default exchange trade fee for makers on a spot market - DefaultSpotMakerFeeRate math.LegacyDec - // default_spot_taker_fee_rate defines the default exchange trade fee rate for takers on a new spot market - DefaultSpotTakerFeeRate math.LegacyDec - // default_derivative_maker_fee defines the default exchange trade fee for makers on a new derivative market - DefaultDerivativeMakerFeeRate math.LegacyDec - // default_derivative_taker_fee defines the default exchange trade fee for takers on a new derivative market - DefaultDerivativeTakerFeeRate math.LegacyDec - // default_initial_margin_ratio defines the default initial margin ratio on a new derivative market - DefaultInitialMarginRatio math.LegacyDec - // default_maintenance_margin_ratio defines the default maintenance margin ratio on a new derivative market - DefaultMaintenanceMarginRatio math.LegacyDec - // default_funding_interval defines the default funding interval on a derivative market - DefaultFundingInterval int64 - // funding_multiple defines the timestamp multiple that the funding timestamp should be a multiple of - FundingMultiple int64 - // relayer_fee_share_rate defines the trade fee share percentage that goes to relayers - RelayerFeeShareRate math.LegacyDec - // default_hourly_funding_rate_cap defines the default maximum absolute value of the hourly funding rate - DefaultHourlyFundingRateCap math.LegacyDec - // hourly_interest_rate defines the hourly interest rate - DefaultHourlyInterestRate math.LegacyDec - // max_derivative_order_side_count defines the maximum number of derivative active orders a subaccount can have for a given orderbook side - MaxDerivativeOrderSideCount uint32 - // inj_reward_staked_requirement_threshold defines the threshold on INJ rewards after which one also needs staked INJ to receive more - InjRewardStakedRequirementThreshold github_com_cosmos_cosmos_sdk_types.Int - // the trading_rewards_vesting_duration defines the vesting times for trading rewards - TradingRewardsVestingDuration int64 -} -``` - -## Balance - -`Balance` is to manage balances of accounts. The module is storing the whole balance in the module account, while the balance of each account is managed just as a record. - -The `Balance` object is stored by `subaccount_id` and `denom`. - -```go -message Balance { - SubaccountId string - Denom string - Deposits *Deposit -} - -// An subaccount's deposit for a given base currency -type Deposit struct { - AvailableBalance math.LegacyDec - TotalBalance math.LegacyDec -} - -type SubaccountDeposit { - SubaccountId []byte - Deposit *Deposit -} -``` - -## SubaccountNonce - -`SubaccountNonce` is used to express unique order hashes. - -```go -type SubaccountNonce struct { - SubaccountId string - SubaccountTradeNonce SubaccountTradeNonce -} -``` - -## Order - -There are a number of structures used to store the orders into the store. - -```go -type OrderInfo struct { - // bytes32 subaccount ID that created the order - SubaccountId string - // address fee_recipient address that will receive fees for the order - FeeRecipient string - // price of the order - Price math.LegacyDec - // quantity of the order - Quantity math.LegacyDec -} - -type SubaccountOrderbookMetadata struct { - VanillaLimitOrderCount uint32 - ReduceOnlyLimitOrderCount uint32 - // AggregateReduceOnlyQuantity is the aggregate fillable quantity of the subaccount's reduce-only limit orders in the given direction. - AggregateReduceOnlyQuantity math.LegacyDec - // AggregateVanillaQuantity is the aggregate fillable quantity of the subaccount's vanilla limit orders in the given direction. - AggregateVanillaQuantity math.LegacyDec -} - -type SubaccountOrder struct { - // price of the order - Price math.LegacyDec - // the amount of the quantity remaining fillable - Quantity math.LegacyDec - IsReduceOnly bool - Cid string -} - -type MarketOrderIndicator struct { - // market_id represents the unique ID of the market - MarketId string - IsBuy bool -} -``` - -## SpotMarket - -`SpotMarket` is the structure to store all the required information and state for a spot market. -Spot markets are stored by hash of the market to query the market efficiently. - -```go -// An object describing trade pair of two assets. -type SpotMarket struct { - // A name of the pair in format AAA/BBB, where AAA is base asset, BBB is quote asset. - Ticker string - // Coin denom used for the base asset - BaseDenom string - // Coin used for the quote asset - QuoteDenom string - // maker_fee_rate defines the fee percentage makers pay when trading - MakerFeeRate math.LegacyDec - // taker_fee_rate defines the fee percentage takers pay when trading - TakerFeeRate math.LegacyDec - // relayer_fee_share_rate defines the percentage of the transaction fee shared with the relayer in a derivative market - RelayerFeeShareRate math.LegacyDec - // Unique market ID. - MarketId string - // Status of the market - Status MarketStatus - // min_price_tick_size defines the minimum tick size that the price required for orders in the market - MinPriceTickSize math.LegacyDec - // min_quantity_tick_size defines the minimum tick size of the quantity required for orders in the market - MinQuantityTickSize math.LegacyDec -} -``` - -## SpotOrderBook - -`SpotOrderBook` is a structure to store spot limit orders for a specific market. -Two objects are created, one for buy orders and one for sell orders. - -```go -// Spot Exchange Limit Orderbook -type SpotOrderBook struct { - MarketId string - IsBuySide bool - Orders []*SpotLimitOrder -} - -type SpotOrder struct { - // market_id represents the unique ID of the market - MarketId string - // order_info contains the information of the order - OrderInfo OrderInfo - // order types - OrderType OrderType - // trigger_price is the trigger price used by stop/take orders - TriggerPrice *math.LegacyDec -} - -// A valid Spot limit order with Metadata. -type SpotLimitOrder struct { - // order_info contains the information of the order - OrderInfo OrderInfo - // order types - OrderType OrderType - // the amount of the quantity remaining fillable - Fillable math.LegacyDec - // trigger_price is the trigger price used by stop/take orders - TriggerPrice *math.LegacyDec - OrderHash []byte -} - -// A valid Spot market order with Metadata. -type SpotMarketOrder struct { - // order_info contains the information of the order - OrderInfo OrderInfo - BalanceHold math.LegacyDec - OrderHash []byte -} -``` - -## DerivativeMarket - -`DerivativeMarket` is the structure to store all the required information and state for a derivative market. -Derivative markets are stored by hash of the market to query the market efficiently. - -```go -// An object describing a derivative market in the Injective Futures Protocol. -type DerivativeMarket struct { - // Ticker for the derivative contract. - Ticker string - // Oracle base currency - OracleBase string - // Oracle quote currency - OracleQuote string - // Oracle type - OracleType types1.OracleType - // Scale factor for oracle prices. - OracleScaleFactor uint32 - // Address of the quote currency denomination for the derivative contract - QuoteDenom string - // Unique market ID. - MarketId string - // initial_margin_ratio defines the initial margin ratio of a derivative market - InitialMarginRatio math.LegacyDec - // maintenance_margin_ratio defines the maintenance margin ratio of a derivative market - MaintenanceMarginRatio math.LegacyDec - // maker_fee_rate defines the maker fee rate of a derivative market - MakerFeeRate math.LegacyDec - // taker_fee_rate defines the taker fee rate of a derivative market - TakerFeeRate math.LegacyDec - // relayer_fee_share_rate defines the percentage of the transaction fee shared with the relayer in a derivative market - RelayerFeeShareRate math.LegacyDec - // true if the market is a perpetual market. false if the market is an expiry futures market - IsPerpetual bool - // Status of the market - Status MarketStatus - // min_price_tick_size defines the minimum tick size that the price and margin required for orders in the market - MinPriceTickSize math.LegacyDec - // min_quantity_tick_size defines the minimum tick size of the quantity required for orders in the market - MinQuantityTickSize math.LegacyDec -} -``` - -## DerivativeOrderBook - -`DerivativeOrderBook` is a structure to store derivative limit orders for a specific market. -Two objects are created, one for buy orders and one for sell orders. - -```go -// Spot Exchange Limit Orderbook -type DerivativeOrderBook struct { - MarketId string - IsBuySide bool - Orders []*DerivativeLimitOrder -} - -type DerivativeOrder struct { - // market_id represents the unique ID of the market - MarketId string - // order_info contains the information of the order - OrderInfo OrderInfo - // order types - OrderType OrderType - // margin is the margin used by the limit order - Margin math.LegacyDec - // trigger_price is the trigger price used by stop/take orders - TriggerPrice *math.LegacyDec -} - -// A valid Derivative limit order with Metadata. -type DerivativeLimitOrder struct { - // order_info contains the information of the order - OrderInfo OrderInfo - // order types - OrderType OrderType - // margin is the margin used by the limit order - Margin math.LegacyDec - // the amount of the quantity remaining fillable - Fillable math.LegacyDec - // trigger_price is the trigger price used by stop/take orders - TriggerPrice *math.LegacyDec - OrderHash []byte -} - -// A valid Derivative market order with Metadata. -type DerivativeMarketOrder struct { - // order_info contains the information of the order - OrderInfo OrderInfo - // order types - OrderType OrderType - Margin math.LegacyDec - MarginHold math.LegacyDec - // trigger_price is the trigger price used by stop/take orders - TriggerPrice *math.LegacyDec - OrderHash []byte -} - -type DerivativeMarketOrderCancel struct { - MarketOrder *DerivativeMarketOrder - CancelQuantity math.LegacyDec -} -``` - -## DerivativePosition - -`DerivativePosition` is a structure to store derivative positions for a subaccount on a specific market. - -**Note:** Derivative orders represent intent while positions represent possession. - -```go -type Position struct { - IsLong bool - Quantity math.LegacyDec - EntryPrice math.LegacyDec - Margin math.LegacyDec - CumulativeFundingEntry math.LegacyDec -} - -type PositionDelta struct { - IsLong bool - ExecutionQuantity math.LegacyDec - ExecutionMargin math.LegacyDec - ExecutionPrice math.LegacyDec -} - -type DerivativePosition struct { - SubaccountId string - MarketId string - Position *Position -} - -type SubaccountPosition struct { - Position *Position - SubaccountId []byte -} -``` - -## ExpiryFuturesMarketInfo - -`ExpiryFuturesMarketInfo` is a structure to keep the information of expiry futures market. -It is stored by the id of the market. - -```go -type ExpiryFuturesMarketInfo struct { - // market ID. - MarketId string - // expiration_timestamp defines the expiration time for a time expiry futures market. - ExpirationTimestamp int64 - // expiration_twap_start_timestamp defines the start time of the TWAP calculation window - TwapStartTimestamp int64 - // expiration_twap_start_price_cumulative defines the cumulative price for the start of the TWAP window - ExpirationTwapStartPriceCumulative math.LegacyDec - // settlement_price defines the settlement price for a time expiry futures market. - SettlementPrice math.LegacyDec -} -``` - -## PerpetualMarketInfo - -`PerpetualMarketInfo` is a structure to keep the information of perpetual market. - -```go -type PerpetualMarketInfo struct { - // market ID. - MarketId string - // hourly_funding_rate_cap defines the maximum absolute value of the hourly funding rate - HourlyFundingRateCap math.LegacyDec - // hourly_interest_rate defines the hourly interest rate - HourlyInterestRate math.LegacyDec - // next_funding_timestamp defines the next funding timestamp in seconds of a perpetual market - NextFundingTimestamp int64 - // funding_interval defines the next funding interval in seconds of a perpetual market. - FundingInterval int64 -} -``` - -## PerpetualMarketFunding - -`PerpetualMarketFunding` is a structure to manage perpetual market fundings info. - -```go -type PerpetualMarketFunding struct { - // cumulative_funding defines the cumulative funding of a perpetual market. - CumulativeFunding math.LegacyDec - // cumulative_price defines the cumulative price for the current hour up to the last timestamp - CumulativePrice math.LegacyDec - LastTimestamp int64 -} -``` - -## Trading Rewards - -### CampaignRewardPool - -`CampaignRewardPool` is a structure to be used for getting the upcoming trading reward pools. - -```go -type CampaignRewardPool struct { - StartTimestamp int64 - // max_campaign_rewards are the maximum reward amounts to be disbursed at the end of the campaign - MaxCampaignRewards sdk.Coins -} -``` - -### TradingRewardCampaignInfo - -`TradingRewardCampaignInfo` is a structure to be used for getting the trading reward campaign info. - -```go -type TradingRewardCampaignInfo struct { - // number of seconds of the duration of each campaign - CampaignDurationSeconds int64 - // the trading fee quote denoms which will be counted for the rewards - QuoteDenoms []string - // the optional boost info for markets - TradingRewardBoostInfo *TradingRewardCampaignBoostInfo - // the marketIDs which are disqualified from being rewarded - DisqualifiedMarketIds []string -} - -type TradingRewardCampaignBoostInfo struct { - BoostedSpotMarketIds []string - SpotMarketMultipliers []PointsMultiplier - BoostedDerivativeMarketIds []string - DerivativeMarketMultipliers []PointsMultiplier -} - -type PointsMultiplier struct { - MakerPointsMultiplier math.LegacyDec - TakerPointsMultiplier math.LegacyDec -} -``` - -## FeeDiscountProposal - -`FeeDiscountProposal` is a structure to be used for proposing a new fee discount schedule and durations. - -```go -type FeeDiscountSchedule struct { - // the bucket count, e.g., 30 - BucketCount uint64 - // the bucket duration, e.g., 1 day - BucketDuration int64 - // the trading fee quote denoms which will be counted for the fee paid contribution - QuoteDenoms []string - // the fee discount tiers - TierInfos []*FeeDiscountTierInfo - // the marketIDs which are disqualified from contributing to the fee paid amount - DisqualifiedMarketIds []string -} - -type FeeDiscountTierInfo struct { - MakerDiscountRate math.LegacyDec - TakerDiscountRate math.LegacyDec - StakedAmount math.Int - FeePaidAmount math.LegacyDec -} -``` - -## DerivativeMarketSettlementInfo - -`DerivativeMarketSettlementInfo` is a structure to be used for the scheduled markets for settlement. - -```go -type DerivativeMarketSettlementInfo struct { - // market ID. - MarketId string - // settlement_price defines the settlement price - SettlementPrice math.LegacyDec - // starting_deficit defines starting deficit - StartingDeficit math.LegacyDec -} -``` - -## TradeLog - -Trade logs are emitted in events to track the trading history. - -```go -type TradeLog struct { - Quantity math.LegacyDec - Price math.LegacyDec - // bytes32 subaccount ID that executed the trade - SubaccountId []byte - Fee math.LegacyDec - OrderHash []byte -} - -type DerivativeTradeLog struct { - SubaccountId []byte - PositionDelta *PositionDelta - Payout math.LegacyDec - Fee math.LegacyDec - OrderHash []byte -} -``` - -## Enums - -Enums are used to describe the order types, execution types and market status. - -```protobuf -enum OrderType { - UNSPECIFIED = 0 [(gogoproto.enumvalue_customname) = "UNSPECIFIED"]; - BUY = 1 [(gogoproto.enumvalue_customname) = "BUY"]; - SELL = 2 [(gogoproto.enumvalue_customname) = "SELL"]; - STOP_BUY = 3 [(gogoproto.enumvalue_customname) = "STOP_BUY"]; - STOP_SELL = 4 [(gogoproto.enumvalue_customname) = "STOP_SELL"]; - TAKE_BUY = 5 [(gogoproto.enumvalue_customname) = "TAKE_BUY"]; - TAKE_SELL = 6 [(gogoproto.enumvalue_customname) = "TAKE_SELL"]; - BUY_PO = 7 [(gogoproto.enumvalue_customname) = "BUY_PO"]; - SELL_PO = 8 [(gogoproto.enumvalue_customname) = "SELL_PO"]; - BUY_ATOMIC = 9 [ (gogoproto.enumvalue_customname) = "BUY_ATOMIC" ]; - SELL_ATOMIC = 10 [ (gogoproto.enumvalue_customname) = "SELL_ATOMIC" ]; -} - -enum MarketStatus { - Unspecified = 0; - Active = 1; - Paused = 2; - Suspended = 3; - Demolished = 4; - Expired = 5; -} - -enum ExecutionType { - UnspecifiedExecutionType = 0; - Market = 1; - LimitFill = 2; - LimitMatchRestingOrder = 3; - LimitMatchNewOrder = 4; -} -``` diff --git a/.gitbook/developers/modules/injective/exchange/04_state_transitions.md b/.gitbook/developers/modules/injective/exchange/04_state_transitions.md deleted file mode 100644 index 99b858ee..00000000 --- a/.gitbook/developers/modules/injective/exchange/04_state_transitions.md +++ /dev/null @@ -1,447 +0,0 @@ ---- -sidebar_position: 5 -title: State Transitions ---- - -# State Transitions - -This document describes the state transition operations pertaining to: - -- Deposit into exchange module account -- Withdraw from exchange module account -- Instant spot market launch -- Instant perpetual market launch -- Instant expiry futures market launch -- Spot limit order creation -- Batch creation of spot limit orders -- Spot market order creation -- Cancel spot order -- Batch cancellation of spot order -- Derivative limit order creation -- Batch derivative limit order creation -- Derivative market order creation -- Cancel derivative order -- Batch cancellation of derivative orders -- Transfer between subaccounts -- Transfer to external account -- Liquidating a position -- Increasing position margin -- Spot market param update proposal -- Exchange enable proposal -- Spot market launch proposal -- Perpetual market launch proposal -- Expiry futures market launch proposal -- Derivative market param update proposal -- Trading rewards launch proposal -- Trading rewards update proposal -- Begin-blocker -- End-blocker - -## Deposit into exchange module account - -Deposit action is carried out by `MsgDeposit` which consists of `Sender`, `SubaccountId` and `Amount` fields. - -**Note:** `SubaccountId` is optional and if it's not available, it's calculated dynamically from `Sender` address. - -**Steps** - -- Check that the denom specified in `msg.Amount` is a valid denom which exists in bank supply -- Send coins from individual account to `exchange` module account and if fail, just revert -- Get hash type of `subaccountID` from `msg.SubaccountId`, if it's zero subaccount, calculate dynamically from `msg.Sender` by using `SdkAddressToSubaccountID` -- Increment deposit amount for the `subaccountID` by `msg.Amount` -- Emit event for `EventSubaccountDeposit` with `msg.Sender`, `subaccountID` and `msg.Amount` - -## Withdraw from exchange module account - -Withdraw action is carried out by `MsgWithdraw` which consists of `Sender`, `SubaccountId` and `Amount` fields. - -**Note:** The ownership of `msg.SubaccountId` by `msg.Sender` is validated on `msg.ValidateBasic` function. - -**Steps** - -- Get hash type of `subaccountID` from `msg.SubaccountId` -- Check the denom specified in `msg.Amount` is a valid denom which exists in bank supply -- Decrement withdraw amount from `subaccountID` by `msg.Amount`, if fail, revert -- Send coins from `exchange` module to `msg.Sender` -- Emit event for `EventSubaccountWithdraw` with `subaccountID`, `msg.Sender`, and `msg.Amount` - -## Instant spot market launch - -Instant spot market launch action is carried out by `MsgInstantSpotMarketLaunch` which consists of `Sender`, `Ticker`, `BaseDenom`, `QuoteDenom`, `MinPriceTickSize` and `MinQuantityTickSize` fields. - -**Steps** - -- Calculate `marketID` from `msg.BaseDenom` and `msg.QuoteDenom` -- Check if same market launch proposal exists by `marketID` and revert if already exists -- Launch spot market with `msg.Ticker`, `msg.BaseDenom`, `msg.QuoteDenom`, `msg.MinPriceTickSize`, `msg.MinQuantityTickSize` and revert if fail -- Send instant listing fee(params.SpotMarketInstantListingFee) from `msg.Sender` to `exchange` module account -- Lastly send the instant listing fee to the community spend pool - -## Instant perpetual market launch - -Instant perpetual market launch action is carried out by `MsgInstantPerpetualMarketLaunch` which consists of `Sender`, `Ticker`, `QuoteDenom`, `OracleBase`, `OracleQuote`, `OracleScaleFactor`, `OracleType`, `MakerFeeRate`, `TakerFeeRate`, `InitialMarginRatio`, `MaintenanceMarginRatio`, `MinPriceTickSize` and `MinQuantityTickSize` fields. - -**Steps** - -- Calculate `marketID` from `msg.Ticker`, `msg.QuoteDenom`, `msg.OracleBase`, `msg.OracleQuote` and `msg.OracleType`. -- Check if same market launch proposal exists by `marketID` and revert if already exists -- Send instant listing fee(params.DerivativeMarketInstantListingFee) from `msg.Sender` to `exchange` module account -- Launch perpetual market with required params on `msg` object and revert if fail -- Lastly send the instant listing fee to the community spend pool - -## Instant expiry futures market launch - -Instant expiry futures market launch action is carried out by `MsgInstantExpiryFuturesMarketLaunch` which consists of `Sender`, `Ticker`, `QuoteDenom`, `OracleBase`, `OracleQuote`, `OracleScaleFactor`, `OracleType`, `Expiry`, `MakerFeeRate`, `TakerFeeRate`, `InitialMarginRatio`, `MaintenanceMarginRatio`, `MinPriceTickSize` and `MinQuantityTickSize` fields. - -**Steps** - -- Calculate `marketID` from `msg.Ticker`, `msg.QuoteDenom`, `msg.OracleBase`, `msg.OracleQuote`, `msg.OracleType` and `msg.Expiry`. -- Check if same market launch proposal exists by `marketID` and revert if already exists -- Send instant listing fee(params.DerivativeMarketInstantListingFee) from `msg.Sender` to `exchange` module account -- Launch expiry futures market with required params on `msg` object and revert if fail -- Trigger `EventExpiryFuturesMarketUpdate` event with market info -- Lastly send the instant listing fee to the community spend pool - -## Spot limit order creation - -Spot limit order creation is carried out by `MsgCreateSpotLimitOrder` which consists of `Sender` and `Order`. - -**Steps** - -- Check spot exchange is enabled to make an order on spot market and if not revert -- Check order's price and quantity tick sizes fits market's min quantity and price tick size -- Increment subaccount's `TradeNonce` -- Reject if spot market id does not reference an active spot market -- Calculate unique order hash with `TradeNonce` -- Reject if the subaccount's available deposits does not have at least the required funds for the trade -- Decrement the available balance by the funds amount needed to fund the order -- Store the order in the transient limit order store and transient market indicator store - -**Note:** The order in transient store is executed on endblocker or if not, put on long-live store. - -## Batch creation of spot limit orders - -Batch creation of spot limit orders is carried out by `MsgBatchCreateSpotLimitOrders` which consists of `Sender` and `Orders`. - -**Steps** - -- Loop over the `msg.Orders` and create spot limit order as in `MsgCreateSpotLimitOrder` - -## Spot market order creation - -Spot market order creation is carried out by `MsgCreateSpotMarketOrder` which consists of `Sender` and `Order`. - -**Steps** - -- Check spot exchange is enabled to make an order on spot market and if not revert -- Check order's price and quantity tick sizes fits market's min quantity and price tick size -- Increment subaccount's `TradeNonce` -- Reject if spot market id does not reference an active spot market -- Calculate unique order hash with `TradeNonce` -- Check available balance to fund the market order -- Calculate the worst acceptable price for the market order -- Decrement deposit's AvailableBalance by the balance hold -- Store the order in the transient spot market order store and transient market indicator store - -## Cancel spot order - -Spot order cancellation is carried out by `MsgCancelSpotOrder` which consists of `Sender` and `MarketId`, `SubaccountId` and `OrderHash`. - -**Steps** - -- Check spot exchange is enabled to execute the action and if not revert -- Reject if spot market id does not reference an active, suspended or demolished spot market -- Check spot limit order exists by `marketID`, `subaccountID` and `orderHash` -- Add back the margin hold to available balance -- Increment the available balance margin hold -- Delete the order state from ordersStore and ordersIndexStore -- Emit `EventCancelSpotOrder` event with marketID and order info - -## Batch cancellation of spot orders - -Batch cancellation of spot orders is carried out by `MsgBatchCancelSpotOrders` which consists of `Sender` and `Data`. - -**Steps** - -- Loop over the `msg.Data` and cancel spot order as in `MsgCancelSpotOrder` - -## Derivative limit order creation - -Derivative limit order creation is carried out by `MsgCreateDerivativeLimitOrder` which consists of `Sender` and `Order`. - -**Steps** - -- Check derivative exchange is enabled to make an order on derivative market and if not revert -- Reject if market order is already placed on the market by `subaccountID` (**Note:** Can't the market order and limit order core exist?) -- Get derivative market and markPrice by `marketID` -- Get orderbook metadata (`SubaccountOrderbookMetadata`) the for specified `marketID` and `subaccountID` -- Ensure limit order is valid: - - Market config (market id and tick sizes) - - Subaccount trade nonce - - Subaccount max order count - - If reduce-only order: - - Position with valid quantity and opposite direction exists - - If order would result in other reduce-only orders becoming stale, reject it - - If limit order: - - Enough subaccount deposits for margin hold - - If order is in opposite direction of existing position and results in other reduce-only orders becoming stale, cancel the stale reduce-only orders -- Store the order in the transient limit order store and transient market indicator store -- Update orderbook metadata for subaccount - -## Batch creation of derivative limit orders - -Batch creation of derivative limit orders is carried out by `MsgBatchCreateDerivativeLimitOrders` which consists of `Sender` and `Orders`. - -**Steps** - -- Loop over the `msg.Orders` and create derivative limit order as in `MsgCreateDerivativeLimitOrder` - -## Derivative market order creation - -Derivative market order creation is carried out by `MsgCreateDerivativeMarketOrder` which consists of `Sender` and `Order`. - -**Steps** - -- Check derivative exchange is enabled to make an order on derivative market and if not revert -- Check if `SubaccountID` that is going to make new order has limit derivative order or market order and reject. **Note:** Perpetual market can't place two market orders or both limit / market orders at the same time? -- Check order's price and quantity tick sizes fits market's min quantity and price tick size -- Increment Subaccount's `TradeNonce` -- Reject if derivative market id does not reference an active derivative market -- Calculate unique order hash with `TradeNonce` -- Check that the market order worst price reaches the best opposing resting orderbook price -- Check Order/Position Margin amount -- 1. If it's reduce only order -- A. Check if position for `subaccountID` on the market is not nil -- B. Check that the order can close the position -- C. Reject if position.quantity - AggregateReduceOnlyQuantity - order.quantity < 0 -- D. Set MarginHold as zero for no margin hold for selling positions -- 2. If it's not reduce only order -- A. Check available balance to fund the market order -- B. Reject if the subaccount's available deposits does not have at least the required funds for the trade -- C. Decrement deposit's AvailableBalance by the balance hold -- For an opposing position, if AggregateVanillaQuantity > position.quantity - AggregateReduceOnlyQuantity - order.FillableQuantity, the new reduce-only order might invalidate some existing reduce-only orders or itself be invalid, and do operations for that. -- Store the order in the transient derivative market order store and transient market indicator store - -## Cancel derivative order - -Derivative order cancellation is carried out by `MsgCancelDerivativeOrder` which consists of `Sender`, `MarketId`, `SubaccountId` and `OrderHash`. - -**Steps** - -- Check derivative exchange is enabled to execute the operation and if not revert -- Reject if derivative market id does not reference an active derivative market -- Check resting derivative limit order exists by `marketID`, `subaccountID` and `orderHash` -- Add back the margin hold to available balance -- Skip cancelling limit orders if their type shouldn't be cancelled -- Delete the order state from ordersStore, ordersIndexStore and subaccountOrderStore -- Update orderbook metadata for subaccount -- Emit `EventCancelDerivativeOrder` event with marketID and order info - -## Batch cancellation of derivative orders - -Batch cancellation of derivative orders is carried out by `MsgBatchCancelDerivativeOrders` which consists of `Sender` and `Data`. - -**Steps** - -- Loop over the `msg.Data` and cancel spot order as in `MsgCancelDerivativeOrder` - -## Batch order updates - -Batch updating orders is carried out by `MsgBatchUpdateOrders` which consists of `Sender` and `Orders`. - -**Steps** - -- Cancel all orders in all market id specified by `SpotMarketIdsToCancelAll` and `DerivativeMarketIdsToCancelAll` for specified subaccount id -- Loop over the `msg.SpotOrdersToCancel` and cancel spot limit order as in `MsgCancelSpotOrder`. If the cancel fails, continue to next order. The success of cancellations is reflected in the `MsgBatchUpdateOrdersResponse` as `SpotCancelSuccess`. -- Loop over the `msg.DerivativeOrdersToCancel` and cancel derivative limit order as in `MsgCancelDerivativeOrder`. If the cancel fails, continue to next order. The success of cancellations is reflected in the `MsgBatchUpdateOrdersResponse` as `DerivativeCancelSuccess`. -- Loop over the `msg.SpotOrdersToCreate` and create spot limit order as in `MsgCreateSpotOrder`. If the creation fails, continue to next order. Successful creations are reflected in the `MsgBatchUpdateOrdersResponse` as `SpotOrderHashes`. -- Loop over the `msg.DerivativeOrdersToCreate` and create derivative limit order as in `MsgCreateDerivativeOrder`. If the creation fails, continue to next order. Successful creations are reflected in the `MsgBatchUpdateOrdersResponse` as `DerivativeOrderHashes`. - -## Transfer between subaccounts - -Transfer between subaccounts is executed by `MsgSubaccountTransfer` which consists of `Sender`, `SourceSubaccountId`, `DestinationSubaccountId` and `Amount`. - -**Steps** - -- Withdraw deposit from `msg.SourceSubaccountId` for `msg.Amount`, if fail revert transaction -- Increment deposit of `msg.DestinationSubaccountId` by `msg.Amount` -- Emit event for `EventSubaccountBalanceTransfer` with `SrcSubaccountId`, `DstSubaccountId` and `msg.Amount` - -**Note:** With subaccount transfer, no need to transfer actual coins from bank module but changing the records are enough. - -## Transfer to external account - -Transfer to external account is executed by `MsgExternalTransfer` which consists of `Sender`, `SourceSubaccountId`, `DestinationSubaccountId` and `Amount`. - -**Steps** - -- Withdraw deposit from `msg.SourceSubaccountId` for `msg.Amount`, if fail revert transaction -- Increment deposit of `msg.DestinationSubaccountId` by `msg.Amount` -- Emit event for `EventSubaccountBalanceTransfer` with `SrcSubaccountId`, `DstSubaccountId` and `msg.Amount` - -**Note:** With subaccount transfer, no need to transfer actual coins from bank module but changing the records are enough. - -1. Event should be different for subaccount transfer and external transfer. -2. There's no difference in subaccount transfer and external transfer, still need to keep different messages? - -## Liquidating a position - -Liquidating a position is executed by `MsgLiquidatePosition` which consists of `Sender`, `SubaccountId`, `MarketId` and `Order`. - -**Steps** - -- Check derivative exchange is enabled to liquidate a position on derivative market and if not revert -- Reject if derivative market id does not reference an active derivative market -- Get derivative market and markPrice by `marketID` -- Get position for `marketID` and `subaccountID` -- Calculate `liquidationPrice` and `bankruptcyPrice` from the position info -- Determine vaporize or liquidate and if not all of them, revert -- Cancel all reduce-only limit orders created by the position holder in the given market -- Apply funding and update position -- Cancel all market orders created by the position holder in the given market -- Check and increment subaccount nonce, compute order hash -- Calculate `liquidationOrder` hash -- Set the liquidation order into the storage -- Execute liquidation by matching position and liquidation order -- Handle differently based on the payout is positive or negative (insurance fund is involved here in calculation) - - Positive Payout: - 1. Send half of the payout to liquidator (incentive for running liquidator bots) - 2. Send the other half to the insurance fund (incentive for participating in insurance funds) - - Negative Payout - Four levels of escalation to retrieve the funds: - 1. From trader's available balance - 2. From trader's locked balance by cancelling his vanilla limit orders - 3. From the insurance fund - 4. Not enough funds available. Pause the market and add markets to the storage to be settled in next block, see `BeginBlocker` specs. -- If market is a perpetual market, upgrade VWAP data based on liquidation price and quantity -- If there's remaining in liquidation order, return back remains by cancelling order - -## Increasing position margin - -Increasing position margin is executed by `MsgIncreasePositionMargin` which consists of `Sender`, `SourceSubaccountId`, `DestinationSubaccountId`, `MarketId` and `Amount`. - -**Steps** - -- Check derivative exchange is enabled to increase position margin on derivative market and if not revert -- Reject if derivative market id does not reference an active derivative market -- Get deposit of `sourceSubaccountID` -- If `deposit.AvailableBalance` is lower than `msg.Amount`, revert -- Get position by `marketID` and `destinationSubaccountID` and if not exist, revert -- Reduce deposit amount of `sourceSubaccountID` by `msg.Amount` -- Increase position margin by `msg.Amount` and update position in the store - -## Exchange enable proposal - -The enable of market type is done by `ExchangeEnableProposal` which consists of `Title`, `Description` and `ExchangeType`. - -**Steps** - -- `ValidateBasic` for proposal -- If `p.ExchangeType` is spot market, enable spot exchange -- If `p.ExchangeType` is derivative market, enable derivative market - -## Spot market launch proposal - -Launch of spot market is handled by `SpotMarketLaunchProposal` which consists of `Title`, `Description`, `Ticker`, `BaseDenom`, `QuoteDenom`, `MinPriceTickSize` and `MinQuantityTickSize` fields. - -**Steps** - -- `ValidateBasic` for proposal -- Validate `BaseDenom` and `QuoteDenom` are valid -- Validate if same market does not exist by `msg.BaseDenom` and `msg.QuoteDenom` -- Calculate RelayerFeeShareRate based on exchange module params. **Note:** for INJ currency, relayer share rate is set to 100% -- Save spot market with calculated `ticker`, `baseDenom`, `quoteDenom`, `exchangeParams.DefaultSpotMakerFeeRate`, `exchangeParams.DefaultSpotTakerFeeRate`, `relayerFeeShareRate`, `minPriceTickSize`, `minQuantityTickSize`, `marketID`, and `MarketStatus_Active`. - -## Perpetual market launch proposal - -Perpetual market launch is handled by `PerpetualMarketLaunchProposal` which consists of `Title`, `Description`, `Ticker`, `QuoteDenom`, `OracleBase`, `OracleQuote`, `OracleScaleFactor`, `OracleType`, `MakerFeeRate`, `TakerFeeRate`, `InitialMarginRatio`, `MaintenanceMarginRatio`, `MinPriceTickSize` and `MinQuantityTickSize` fields. - -**Steps** - -- `ValidateBasic` for proposal -- Validate `quoteDenom`. -- Calculate `marketID` from `ticker`, `quoteDenom`, `oracleBase`, `oracleQuote`, `oracleType` -- Validate active or inactive perpetual market for `marketID` does not exist -- Try getting derivative market price to check price oracle by `oracleBase`, `oracleQuote`, `oracleScaleFactor`, `oracleType` -- Validate insurance fund exist for `marketID` -- Calculate `defaultFundingInterval`, `nextFundingTimestamp`, `relayerFeeShareRate` from `exchange` module params -- Execute `SetDerivativeMarketWithInfo` to set market info into the storage with `market`, `marketInfo` and `funding` objects - -## Expiry futures market launch proposal - -Expiry futures market launch is handled by `ExpiryFuturesMarketLaunchProposal` which consists of `Title`, `Description`, `Ticker`, `QuoteDenom`, `OracleBase`, `OracleQuote`, `OracleScaleFactor`, `OracleType`, `Expiry`, `MakerFeeRate`, `TakerFeeRate`, `InitialMarginRatio`, `MaintenanceMarginRatio`, `MinPriceTickSize` and `MinQuantityTickSize` fields. - -**Steps** - -- `ValidateBasic` for proposal -- Validate `quoteDenom` -- Calculate `marketID` from `p.Ticker`, `p.QuoteDenom`, `p.OracleBase`, `p.OracleQuote`, `p.OracleType` and `p.Expiry` -- Validate active or inactive expiry futures market for `marketID` does not exist -- If expiry time passed `ctx.BlockTime()` already, revert -- Try getting derivative market price to check price oracle by `oracleBase`, `oracleQuote`, `oracleScaleFactor`, `oracleType` -- Validate insurance fund exist for `marketID` -- Calculate RelayerFeeShareRate based on exchange module params. **Note:** for INJ currency, relayer share rate is set to 100% -- Execute `SetDerivativeMarketWithInfo` to set market info into the storage with `market`, `marketInfo` objects **Note:** TwapStartTimestamp is set to `expiry - thirtyMinutesInSeconds`. - -## Spot market param update proposal - -The update of spot market param is handled by `SpotMarketParamUpdateProposal` which consists of `Title`, `Description`, `MarketId`, `MakerFeeRate`, `TakerFeeRate`, `RelayerFeeShareRate`, `MinPriceTickSize`, `MinQuantityTickSize` and `Status`. - -**Steps** - -- `ValidateBasic` for proposal -- Get spot market by `p.MarketId` and if not exist, revert -- Reset the params for `MakerFeeRate`, `TakerFeeRate`, `RelayerFeeShareRate`, `MinPriceTickSize`, `MinQuantityTickSize` and `Status` if not empty, if empty keep as it is. -- Validate `MakerFeeRate` is bigger than `TakerFeeRate`. - -## Derivative market param update proposal - -Derivative market param update is handled by `DerivativeMarketParamUpdateProposal` which consists of `Title`, `Description`, `MarketId`, `InitialMarginRatio`, `MaintenanceMarginRatio`, `MakerFeeRate`, `TakerFeeRate`, `RelayerFeeShareRate`, `MinPriceTickSize`, `MinQuantityTickSize` and `Status`. - -**Steps** - -- `ValidateBasic` for proposal -- Validate Derivative market exists by `p.MarketId` and if not exist, revert -- Reset the params for `InitialMarginRatio`, `MaintenanceMarginRatio`, `MakerFeeRate`, `TakerFeeRate`, `RelayerFeeShareRate`, `MinPriceTickSize`, `MinQuantityTickSize` and `Status` if not empty, if empty keep as it is. -- Validate `MakerFeeRate` is bigger than `TakerFeeRate`. -- Validate `InitialMarginRatio` is bigger than `MaintenanceMarginRatio`. -- Schedule Derivative market param update and update finalization on Endblocker - **Note:** this is due to the orders update for derivative market param update - should make sure nothing panics here. - -## Trading Rewards Campaign Launch Proposal - -**Steps** - -- `ValidateBasic` for proposal -- No existing campaign may exist. -- Campaign start timestamps must be in the future. -- Campaign quote denoms must exist. -- All start timestamps must match the duration. -- Set Campaign Data (Reward Pools, Info, Market Qualifications and Market Point Multipliers) -- Emit `EventTradingRewardCampaignUpdate` - -## Trading Rewards Campaign Update Proposal - -**Steps** - -- `ValidateBasic` for proposal -- All `StartTimestamp` inside `CampaignRewardPoolsUpdates` must equal an existing campaign. -- `CampaignDurationSeconds` cannot be modified, but must match the current campaign. -- `CampaignRewardPoolsUpdates` cannot modify the current campaign and may contain nil values to delete a reward pool. -- Campaign start timestamps from `CampaignRewardPoolsAdditions` must be in the future. -- Any campaign quote denoms must exist. -- Delete Current Campaign Data (Info, Market Qualifications and Market Point Multipliers) -- Set Campaign Data (Info, Market Qualifications and Market Point Multipliers) -- Set Reward Pool Updates -- Set Reward Pool Additions -- Emit `EventTradingRewardCampaignUpdate` - -## Fee Discount Schedule Proposal - -**Steps** - -- `ValidateBasic` for proposal -- If Current Fee Discount Schedule exists, delete it along with Market Qualifications -- Defined quote denoms must exist. -- If a restart of the fee cycle is required (bucket count, bucket duration or quote denoms changed), delete all account fee buckets and restart cycle. -- Set the first fee paid bucket timestamp as the current block time -- Set New Fee Discount Schedule, delete it along with Market Qualifications -- Set New Market Qualifications diff --git a/.gitbook/developers/modules/injective/exchange/05_messages.md b/.gitbook/developers/modules/injective/exchange/05_messages.md deleted file mode 100644 index 75ad01c5..00000000 --- a/.gitbook/developers/modules/injective/exchange/05_messages.md +++ /dev/null @@ -1,443 +0,0 @@ ---- -sidebar_position: 6 -title: Messages ---- - -# Messages - -In this section we describe the processing of the exchange messages and the corresponding updates to the state. All -created/modified state objects specified by each message are defined within the [State Transitions](./04_state_transitions.md) -section. - -## Msg/Deposit - -`MsgDeposit` defines a SDK message for transferring coins from the sender's bank balance into the subaccount's exchange deposits. - -```go -type MsgDeposit struct { - Sender string - // (Optional) bytes32 subaccount ID to deposit funds into. If empty, the coin will be deposited to the sender's default - // subaccount address. - SubaccountId string - Amount types.Coin -} -``` - -**Fields description** - -- `Sender` field describes the address who deposits. -- `SubaccountId` describes the ID of a sub-account to receive a deposit. -- `Amount` specifies the deposit amount. - -## Msg/Withdraw - -`MsgWithdraw` defines a SDK message for withdrawing coins from a subaccount's deposits to the user's bank balance. - -```go -type MsgWithdraw struct { - Sender string - // bytes32 subaccount ID to withdraw funds from - SubaccountId string - Amount types.Coin -} -``` - -**Fields description** - -- `Sender` field describes the address to receive withdrawal. -- `SubaccountId` describes the ID of a sub-account to withdraw from. -- `Amount` specifies the withdrawal amount. - -## Msg/InstantSpotMarketLaunch - -`MsgInstantSpotMarketLaunch` defines a SDK message for creating a new spot market by paying listing fee without governance. The fee is sent to the community spend pool. - -```go -type MsgInstantSpotMarketLaunch struct { - Sender string - Ticker string - BaseDenom string - QuoteDenom string - MinPriceTickSize math.LegacyDec - MinQuantityTickSize math.LegacyDec - MinNotional math.LegacyDec -} -``` - -**Fields description** - -- `Sender` field describes the creator of this msg. -- `Ticker` describes the ticker for the spot market. -- `BaseDenom` specifies the type of coin to use as the base currency. -- `QuoteDenom` specifies the type of coin to use as the quote currency. -- `MinPriceTickSize` defines the minimum tick size of the order's price. -- `MinQuantityTickSize` defines the minimum tick size of the order's quantity. - -## Msg/InstantPerpetualMarketLaunch - -`MsgInstantPerpetualMarketLaunch` defines a SDK message for creating a new perpetual futures market by paying listing fee without governance. The fee is sent to the community spend pool. - -```go -type MsgInstantPerpetualMarketLaunch struct { - Sender string - Ticker string - QuoteDenom string - OracleBase string - OracleQuote string - OracleScaleFactor uint32 - OracleType types1.OracleType - MakerFeeRate math.LegacyDec - TakerFeeRate math.LegacyDec - InitialMarginRatio math.LegacyDec - MaintenanceMarginRatio math.LegacyDec - MinPriceTickSize math.LegacyDec - MinQuantityTickSize math.LegacyDec - MinNotional math.LegacyDec -} -``` - -**Fields description** - -- `Sender` field describes the creator of this msg. -- `Ticker` field describes the ticker for the derivative market. -- `QuoteDenom` field describes the type of coin to use as the base currency. -- `OracleBase` field describes the oracle base currency. -- `OracleQuote` field describes the oracle quote currency. -- `OracleScaleFactor` field describes the scale factor for oracle prices. -- `OracleType` field describes the oracle type. -- `MakerFeeRate` field describes the trade fee rate for makers on the derivative market. -- `TakerFeeRate` field describes the trade fee rate for takers on the derivative market. -- `InitialMarginRatio` field describes the initial margin ratio for the derivative market. -- `MaintenanceMarginRatio` field describes the maintenance margin ratio for the derivative market. -- `MinPriceTickSize` field describes the minimum tick size of the order's price and margin. -- `MinQuantityTickSize` field describes the minimum tick size of the order's quantity. - -## Msg/InstantExpiryFuturesMarketLaunch - -`MsgInstantExpiryFuturesMarketLaunch` defines a SDK message for creating a new expiry futures market by paying listing fee without governance. The fee is sent to the community spend pool. - -```go -type MsgInstantExpiryFuturesMarketLaunch struct { - Sender string - Ticker string - QuoteDenom string - OracleBase string - OracleQuote string - OracleType types1.OracleType - OracleScaleFactor uint32 - Expiry int64 - MakerFeeRate math.LegacyDec - TakerFeeRate math.LegacyDec - InitialMarginRatio math.LegacyDec - MaintenanceMarginRatio math.LegacyDec - MinPriceTickSize math.LegacyDec - MinQuantityTickSize math.LegacyDec - MinNotional math.LegacyDec -} -``` - -**Fields description** - -- `Sender` field describes the creator of this msg. -- `Ticker` field describes the ticker for the derivative market. -- `QuoteDenom` field describes the type of coin to use as the quote currency. -- `OracleBase` field describes the oracle base currency. -- `OracleQuote` field describes the oracle quote currency. -- `OracleScaleFactor` field describes the scale factor for oracle prices. -- `OracleType` field describes the oracle type. -- `Expiry` field describes the expiration time of the market. -- `MakerFeeRate` field describes the trade fee rate for makers on the derivative market. -- `TakerFeeRate` field describes the trade fee rate for takers on the derivative market. -- `InitialMarginRatio` field describes the initial margin ratio for the derivative market. -- `MaintenanceMarginRatio` field describes the maintenance margin ratio for the derivative market. -- `MinPriceTickSize` field describes the minimum tick size of the order's price and margin. -- `MinQuantityTickSize` field describes the minimum tick size of the order's quantity. - -## Msg/CreateSpotLimitOrder - -`MsgCreateSpotLimitOrder` defines a SDK message for creating a new spot limit order. - -```go -type MsgCreateSpotLimitOrder struct { - Sender string - Order SpotOrder -} -``` - -**Fields description** - -- `Sender` field describes the creator of this msg. -- `Order` field describes the order info. - -## Msg/BatchCreateSpotLimitOrders - -`MsgBatchCreateSpotLimitOrders` defines a SDK message for creating a new batch of spot limit orders. - -```go -type MsgBatchCreateSpotLimitOrders struct { - Sender string - Orders []SpotOrder -} -``` - -**Fields description** - -- `Sender` field describes the creator of this msg. -- `Orders` field describes the orders info. - -## Msg/CreateSpotMarketOrder - -`MsgCreateSpotMarketOrder` defines a SDK message for creating a new spot market order. - -```go -type MsgCreateSpotMarketOrder struct { - Sender string - Order SpotOrder -} -``` - -**Fields description** - -- `Sender` field describes the creator of this msg. -- `Order` field describes the order info. - -## Msg/CancelSpotOrder - -`MsgCancelSpotOrder` defines the message to cancel a spot order. - -```go -type MsgCancelSpotOrder struct { - Sender string - MarketId string - SubaccountId string - OrderHash string - Cid string -} -``` - -**Fields description** - -- `Sender` field describes the creator of this msg. -- `MarketId` field describes the id of the market where the order is placed. -- `SubaccountId` field describes the subaccount id that placed the order. -- `OrderHash` field describes the hash of the order. - -## Msg/BatchCancelSpotOrders - -`MsgBatchCancelSpotOrders` defines the message to cancel the spot orders in batch. - -```go -type MsgBatchCancelSpotOrders struct { - Sender string - Data []OrderData -} -``` - -**Fields description** - -- `Sender` field describes the creator of this msg. -- `Data` field describes the orders to cancel. - -## Msg/CreateDerivativeLimitOrder - -`MsgCreateDerivativeLimitOrder` defines the message to create a derivative limit order. - -```go -type MsgCreateDerivativeLimitOrder struct { - Sender string - Order DerivativeOrder -} -``` - -**Fields description** - -- `Sender` field describes the creator of this msg. -- `Order` field describes the order info. - -## Batch creation of derivative limit orders - -`MsgBatchCreateDerivativeLimitOrders` describes the batch creation of derivative limit orders. - -```go -type MsgBatchCreateDerivativeLimitOrders struct { - Sender string - Orders []DerivativeOrder -} -``` - -**Fields description** - -- `Sender` field describes the creator of this msg. -- `Orders` field describes the orders info. - -## Msg/CreateDerivativeMarketOrder - -`MsgCreateDerivativeMarketOrder` is a message to create a derivative market order. - -```go -// A Cosmos-SDK MsgCreateDerivativeMarketOrder -type MsgCreateDerivativeMarketOrder struct { - Sender string - Order DerivativeOrder -} -``` - -**Fields description** - -- `Sender` field describes the creator of this msg. -- `Order` field describes the order info. - -## Msg/CancelDerivativeOrder - -`MsgCancelDerivativeOrder` is a message to cancel a derivative order. - -```go -type MsgCancelDerivativeOrder struct { - Sender string - MarketId string - SubaccountId string - OrderHash string - OrderMask int32 - Cid string -} -``` - -**Fields description** - -- `Sender` field describes the creator of this msg. -- `MarketId` field describes the id of the market where the order is placed. -- `SubaccountId` field describes the subaccount id that placed the order. -- `OrderHash` field describes the hash of the order. - -## Msg/BatchCancelDerivativeOrders - -`MsgBatchCancelDerivativeOrders` is a message to cancel derivative orders in batch. - -```go -type MsgBatchCancelDerivativeOrders struct { - Sender string - Data []OrderData -} -``` - -**Fields description** - -- `Sender` field describes the creator of this msg. -- `Data` field describes the orders to cancel. - -## Msg/SubaccountTransfer - -`MsgSubaccountTransfer` is a message to transfer balance between sub-accounts. - -```go -type MsgSubaccountTransfer struct { - Sender string - SourceSubaccountId string - DestinationSubaccountId string - Amount types.Coin -} -``` - -**Fields description** - -- `Sender` field describes the creator of this msg. -- `SourceSubaccountId` field describes a source subaccount to send coins from. -- `DestinationSubaccountId` field describes a destination subaccount to send coins to. -- `Amount` field describes the amount of coin to send. - -## Msg/ExternalTransfer - -`MsgExternalTransfer` is a message to transfer balance from one of source account to external sub-account. - -```go -type MsgExternalTransfer struct { - Sender string - SourceSubaccountId string - DestinationSubaccountId string - Amount types.Coin -} -``` - -**Fields description** - -- `Sender` field describes the creator of this msg. -- `SourceSubaccountId` field describes a source subaccount to send coins from. -- `DestinationSubaccountId` field describes a destination subaccount to send coins to. -- `Amount` field describes the amount of coin to send. - -## Msg/LiquidatePosition - -`MsgLiquidatePosition` describes a message to liquidate an account's position - -```go -type MsgLiquidatePosition struct { - Sender string - SubaccountId string - MarketId string - // optional order to provide for liquidation - Order *DerivativeOrder -} -``` - -**Fields description** - -- `Sender` field describes the creator of this msg. -- `SubaccountId` field describes a subaccount to receive liquidation amount. -- `MarketId` field describes a market where the position is in. -- `Order` field describes the order info. - -## Msg/IncreasePositionMargin - -`MsgIncreasePositionMargin` describes a message to increase margin of an account. - -```go -// A Cosmos-SDK MsgIncreasePositionMargin -type MsgIncreasePositionMargin struct { - Sender string - SourceSubaccountId string - DestinationSubaccountId string - MarketId string - // amount defines the amount of margin to add to the position - Amount math.LegacyDec -} -``` - -**Fields description** - -- `Sender` field describes the creator of this msg. -- `SourceSubaccountId` field describes a source subaccount to send balance from. -- `DestinationSubaccountId` field describes a destination subaccount to receive balance. -- `MarketId` field describes a market where positions are in. -- `Amount` field describes amount to increase. - - - -## Msg/BatchUpdateOrders - -`MsgBatchUpdateOrders` allows for the atomic cancellation and creation of spot and derivative limit orders, along with a new order cancellation mode. Upon execution, order cancellations (if any) occur first, followed by order creations (if any). - -```go -// A Cosmos-SDK MsgBatchUpdateOrders -// SubaccountId only used for the spot_market_ids_to_cancel_all and derivative_market_ids_to_cancel_all. -type MsgBatchUpdateOrders struct { - Sender string - SubaccountId string - SpotMarketIdsToCancelAll []string - DerivativeMarketIdsToCancelAll []string - SpotOrdersToCancel []OrderData - DerivativeOrdersToCancel []OrderData - SpotOrdersToCreate []SpotOrder - DerivativeOrdersToCreate []DerivativeOrder -} -``` - -**Fields description** - -- `Sender` field describes the creator of this msg. -- `SubaccountId` field describes the sender's sub-account ID. -- `SpotMarketIdsToCancelAll` field describes a list of spot market IDs for which the sender wants to cancel all open orders. -- `DerivativeMarketIdsToCancelAll` field describes a list of derivative market IDs for which the sender wants to cancel all open orders. -- `SpotOrdersToCancel` field describes specific spot orders the sender wants to cancel. -- `DerivativeOrdersToCancel` field describes specific derivative orders the sender wants to cancel. -- `SpotOrdersToCreate` field describes spot orders the sender wants to create. -- `DerivativeOrdersToCreate` field describes derivative orders the sender wants to create. diff --git a/.gitbook/developers/modules/injective/exchange/06_proposals.md b/.gitbook/developers/modules/injective/exchange/06_proposals.md deleted file mode 100644 index b0e1a33a..00000000 --- a/.gitbook/developers/modules/injective/exchange/06_proposals.md +++ /dev/null @@ -1,404 +0,0 @@ ---- -sidebar_position: 7 -title: Governance Proposals ---- - -# Governance Proposals - -## Proposal/SpotMarketParamUpdate - -`SpotMarketParamUpdateProposal` defines an SDK message to propose an update of spot market params. - -```go -type SpotMarketParamUpdateProposal struct { - Title string - Description string - MarketId string - MakerFeeRate *math.LegacyDec - TakerFeeRate *math.LegacyDec - RelayerFeeShareRate *math.LegacyDec - MinPriceTickSize *math.LegacyDec - MinQuantityTickSize *math.LegacyDec - MinNotional *math.LegacyDec - Status MarketStatus -} -``` - -**Fields description** - -- `Title` describes the title of the proposal. -- `Description` describes the description of the proposal. -- `MarketId` describes the id of the market to change params. -- `MakerFeeRate` describes the target fee rate for makers. -- `TakerFeeRate` describes the target fee rate for takers. -- `RelayerFeeShareRate` describes the relayer fee share rate. -- `MinPriceTickSize` defines the minimum tick size of the order's price. -- `MinQuantityTickSize` defines the minimum tick size of the order's quantity. -- `Status` describes the target status of the market. - -## Proposal/ExchangeEnable - -`ExchangeEnableProposal` defines a message to propose enable of specific exchange type. - -```go -type ExchangeEnableProposal struct { - Title string - Description string - ExchangeType ExchangeType -} -``` - -**Fields description** - -- `Title` describes the title of the proposal. -- `Description` describes the description of the proposal. -- `ExchangeType` describes the type of exchange, spot or derivatives. - - -## Proposal/BatchExchangeModification - -`BatchExchangeModificationProposal` defines a message to batch multiple proposals in the exchange module. - -```go -type BatchExchangeModificationProposal struct { - Title string - Description string - SpotMarketParamUpdateProposal []*SpotMarketParamUpdateProposal - DerivativeMarketParamUpdateProposal []*DerivativeMarketParamUpdateProposal - SpotMarketLaunchProposal []*SpotMarketLaunchProposal - PerpetualMarketLaunchProposal []*PerpetualMarketLaunchProposal - ExpiryFuturesMarketLaunchProposal []*ExpiryFuturesMarketLaunchProposal - TradingRewardCampaignUpdateProposal *TradingRewardCampaignUpdateProposal -} -``` - -**Fields description** - -- `Title` describes the title of the proposal. -- `Description` describes the description of the proposal. -- `SpotMarketParamUpdateProposal` describes the SpotMarketParamUpdateProposal. -- `DerivativeMarketParamUpdateProposal` describes the DerivativeMarketParamUpdateProposal. -- `SpotMarketLaunchProposal` describes the SpotMarketLaunchProposal. -- `PerpetualMarketLaunchProposal` describes the PerpetualMarketLaunchProposal. -- `ExpiryFuturesMarketLaunchProposal` describes the ExpiryFuturesMarketLaunchProposal. -- `TradingRewardCampaignUpdateProposal` describes the TradingRewardCampaignUpdateProposal. - - -## Proposal/SpotMarketLaunch - -`SpotMarketLaunchProposal` defines an SDK message for proposing a new spot market through governance. - -```go -type SpotMarketLaunchProposal struct { - Title string - Description string - Ticker string - BaseDenom string - QuoteDenom string - MinPriceTickSize math.LegacyDec - MinQuantityTickSize math.LegacyDec - MinNotional math.LegacyDec - MakerFeeRate math.LegacyDec - TakerFeeRate math.LegacyDec -} -``` - -**Fields description** - -- `Title` describes the title of the proposal. -- `Description` describes the description of the proposal. -- `Ticker` describes the ticker for the spot market. -- `BaseDenom` specifies the type of coin to use as the base currency. -- `QuoteDenom` specifies the type of coin to use as the quote currency. -- `MinPriceTickSize` defines the minimum tick size of the order's price. -- `MinQuantityTickSize` defines the minimum tick size of the order's quantity. -- `MakerFeeRate` field describes the trade fee rate for makers on the derivative market. -- `TakerFeeRate` field describes the trade fee rate for takers on the derivative market. - -## Proposal/PerpetualMarketLaunch - -`PerpetualMarketLaunchProposal` defines an SDK message for proposing a new perpetual futures market through governance. - -```go -type PerpetualMarketLaunchProposal struct { - Title string - Description string - Ticker string - QuoteDenom string - OracleBase string - OracleQuote string - OracleScaleFactor uint32 - OracleType types1.OracleType - InitialMarginRatio math.LegacyDec - MaintenanceMarginRatio math.LegacyDec - MakerFeeRate math.LegacyDec - TakerFeeRate math.LegacyDec - MinPriceTickSize math.LegacyDec - MinQuantityTickSize math.LegacyDec -} -``` - -**Fields description** - -- `Title` describes the title of the proposal. -- `Description` describes the description of the proposal. -- `Ticker` field describes the ticker for the derivative market. -- `QuoteDenom` field describes the type of coin to use as the base currency. -- `OracleBase` field describes the oracle base currency. -- `OracleQuote` field describes the oracle quote currency. -- `OracleScaleFactor` field describes the scale factor for oracle prices. -- `OracleType` field describes the oracle type. -- `MakerFeeRate` field describes the trade fee rate for makers on the derivative market. -- `TakerFeeRate` field describes the trade fee rate for takers on the derivative market. -- `InitialMarginRatio` field describes the initial margin ratio for the derivative market. -- `MaintenanceMarginRatio` field describes the maintenance margin ratio for the derivative market. -- `MinPriceTickSize` field describes the minimum tick size of the order's price and margin. -- `MinQuantityTickSize` field describes the minimum tick size of the order's quantity. - -## Expiry futures market launch proposal - -```go -// ExpiryFuturesMarketLaunchProposal defines an SDK message for proposing a new expiry futures market through governance -type ExpiryFuturesMarketLaunchProposal struct { - Title string - Description string - // Ticker for the derivative market. - Ticker string - // type of coin to use as the quote currency - QuoteDenom string - // Oracle base currency - OracleBase string - // Oracle quote currency - OracleQuote string - // Scale factor for oracle prices. - OracleScaleFactor uint32 - // Oracle type - OracleType types1.OracleType - // Expiration time of the market - Expiry int64 - // initial_margin_ratio defines the initial margin ratio for the derivative market - InitialMarginRatio math.LegacyDec - // maintenance_margin_ratio defines the maintenance margin ratio for the derivative market - MaintenanceMarginRatio math.LegacyDec - // maker_fee_rate defines the exchange trade fee for makers for the derivative market - MakerFeeRate math.LegacyDec - // taker_fee_rate defines the exchange trade fee for takers for the derivative market - TakerFeeRate math.LegacyDec - // min_price_tick_size defines the minimum tick size of the order's price and margin - MinPriceTickSize math.LegacyDec - // min_quantity_tick_size defines the minimum tick size of the order's quantity - MinQuantityTickSize math.LegacyDec - // min_notional defines the minimum notional (in quote asset) required for orders in the market - MinNotional math.LegacyDec -} -``` - -**Fields description** - -- `Title` describes the title of the proposal. -- `Description` describes the description of the proposal. -- `Ticker` field describes the ticker for the derivative market. -- `QuoteDenom` field describes the type of coin to use as the quote currency. -- `OracleBase` field describes the oracle base currency. -- `OracleQuote` field describes the oracle quote currency. -- `OracleScaleFactor` field describes the scale factor for oracle prices. -- `OracleType` field describes the oracle type. -- `Expiry` field describes the expiration time of the market. -- `MakerFeeRate` field describes the trade fee rate for makers on the derivative market. -- `TakerFeeRate` field describes the trade fee rate for takers on the derivative market. -- `InitialMarginRatio` field describes the initial margin ratio for the derivative market. -- `MaintenanceMarginRatio` field describes the maintenance margin ratio for the derivative market. -- `MinPriceTickSize` field describes the minimum tick size of the order's price and margin. -- `MinQuantityTickSize` field describes the minimum tick size of the order's quantity. - -## Binary options market launch proposal - -```go -type BinaryOptionsMarketLaunchProposal struct { - Title string - Description string - // Ticker for the derivative contract. - Ticker string - // Oracle symbol - OracleSymbol string - // Oracle Provider - OracleProvider string - // Oracle type - OracleType types1.OracleType - // Scale factor for oracle prices. - OracleScaleFactor uint32 - // expiration timestamp - ExpirationTimestamp int64 - // expiration timestamp - SettlementTimestamp int64 - // admin of the market - Admin string - // Address of the quote currency denomination for the binary options contract - QuoteDenom string - // maker_fee_rate defines the maker fee rate of a binary options market - MakerFeeRate math.LegacyDec - // taker_fee_rate defines the taker fee rate of a derivative market - TakerFeeRate math.LegacyDec - // min_price_tick_size defines the minimum tick size that the price and margin required for orders in the market - MinPriceTickSize math.LegacyDec - // min_quantity_tick_size defines the minimum tick size of the quantity required for orders in the market - MinQuantityTickSize math.LegacyDec -} -``` - -## Binary options market param update - -```go -type BinaryOptionsMarketParamUpdateProposal struct { - Title string - Description string - MarketId string - // maker_fee_rate defines the exchange trade fee for makers for the derivative market - MakerFeeRate *math.LegacyDec - // taker_fee_rate defines the exchange trade fee for takers for the derivative market - TakerFeeRate *math.LegacyDec - // relayer_fee_share_rate defines the relayer fee share rate for the derivative market - RelayerFeeShareRate *math.LegacyDec - // min_price_tick_size defines the minimum tick size of the order's price and margin - MinPriceTickSize *math.LegacyDec - // min_quantity_tick_size defines the minimum tick size of the order's quantity - MinQuantityTickSize *math.LegacyDec - // min_notional defines the minimum notional for orders - MinNotional *math.LegacyDec - // expiration timestamp - ExpirationTimestamp int64 - // expiration timestamp - SettlementTimestamp int64 - // new price at which market will be settled - SettlementPrice *math.LegacyDec - // admin of the market - Admin string - Status MarketStatus - OracleParams *ProviderOracleParams -} -``` - -## Proposal/DerivativeMarketParamUpdate - -```go -type OracleParams struct { - // Oracle base currency - OracleBase string - // Oracle quote currency - OracleQuote string - // Scale factor for oracle prices. - OracleScaleFactor uint32 - // Oracle type - OracleType types1.OracleType -} - -type DerivativeMarketParamUpdateProposal struct { - Title string - Description string - MarketId string - InitialMarginRatio *math.LegacyDec - MaintenanceMarginRatio *math.LegacyDec - MakerFeeRate *math.LegacyDec - TakerFeeRate *math.LegacyDec - RelayerFeeShareRate *math.LegacyDec - MinPriceTickSize *math.LegacyDec - MinQuantityTickSize *math.LegacyDec - MinNotional *math.LegacyDec - HourlyInterestRate *math.LegacyDec - HourlyFundingRateCap *math.LegacyDec - Status MarketStatus - OracleParams *OracleParams -} -``` - -**Fields description** - -- `Title` describes the title of the proposal. -- `Description` describes the description of the proposal. -- `MarketId` describes the id of the market to change params. -- `InitialMarginRatio` describes the target initial margin ratio. -- `MaintenanceMarginRatio` describes the target maintenance margin ratio. -- `MakerFeeRate` describes the target fee rate for makers. -- `TakerFeeRate` describes the target fee rate for takers. -- `RelayerFeeShareRate` describes the relayer fee share rate. -- `MinPriceTickSize` defines the minimum tick size of the order's price. -- `MinQuantityTickSize` defines the minimum tick size of the order's quantity. -- `Status` describes the target status of the market. -- `OracleParams` describes the new oracle parameters. - -## Proposal/TradingRewardCampaignLaunch - -`TradingRewardCampaignLaunchProposal` defines an SDK message for proposing to launch a new trading reward campaign. - -```go -type TradingRewardCampaignLaunchProposal struct { - Title string - Description string - CampaignInfo *TradingRewardCampaignInfo - CampaignRewardPools []*CampaignRewardPool -} -``` - -**Fields description** - -- `Title` describes the title of the proposal. -- `Description` describes the description of the proposal. -- `CampaignInfo` describes the CampaignInfo. -- `CampaignRewardPools` describes the CampaignRewardPools. - -## Proposal/TradingRewardCampaignUpdate - -`TradingRewardCampaignUpdateProposal` defines an SDK message for proposing to update an existing trading reward campaign. - -```go -type TradingRewardCampaignUpdateProposal struct { - Title string - Description string - CampaignInfo *TradingRewardCampaignInfo - CampaignRewardPoolsAdditions []*CampaignRewardPool - CampaignRewardPoolsUpdates []*CampaignRewardPool -} -``` - -- `Title` describes the title of the proposal. -- `Description` describes the description of the proposal. -- `CampaignRewardPoolsAdditions` describes the CampaignRewardPoolsAdditions. -- `CampaignRewardPoolsUpdates` describes the CampaignRewardPoolsUpdates. - -## Proposal/FeeDiscount - -`FeeDiscountProposal` defines an SDK message for proposing to launch or update a fee discount schedule. - -```go -type FeeDiscountProposal struct { - Title string - Description string - Schedule *FeeDiscountSchedule -} -``` - -- `Title` describes the title of the proposal. -- `Description` describes the description of the proposal. -- `Schedule` describes the Fee discount schedule. - -## Proposal/TradingRewardPendingPointsUpdate - -`TradingRewardPendingPointsUpdateProposal` defines an SDK message to update reward points for certain addresses during the vesting period. - -```go -type TradingRewardPendingPointsUpdateProposal struct { - Title string - Description string - PendingPoolTimestamp int64 - RewardPointUpdates *[]RewardPointUpdate -} -``` - -**Fields description** - -- `Title` describes the title of the proposal. -- `Description` describes the description of the proposal. -- `PendingPoolTimestamp` describes timestamp of the pending pool. -- `RewardPointUpdates` describes the RewardPointUpdate. - - diff --git a/.gitbook/developers/modules/injective/exchange/07_begin_block.md b/.gitbook/developers/modules/injective/exchange/07_begin_block.md deleted file mode 100644 index 6d0f1bf8..00000000 --- a/.gitbook/developers/modules/injective/exchange/07_begin_block.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -sidebar_position: 8 -title: BeginBlocker ---- - -# BeginBlocker - -The exchange [BeginBlocker](https://docs.cosmos.network/master/building-modules/beginblock-endblock.html) runs at the start of every block in our defined order as the last module. - -### 1. Process Hourly Fundings - -1. Check the first to receive funding payments market. If the first market is not yet due to receive fundings (funding timestamp not reached), skip all fundings. -2. Otherwise go through each market one by one: - 1. Skip market if funding timestamp is not yet reached. - 2. Compute funding as `twap + hourlyInterestRate` where $\mathrm{twap = \frac{cumulativePrice}{timeInterval * 24}}$ with $\mathrm{timeInterval = lastTimestamp - startingTimestamp}$. The `cumulativePrice` is previously calculated with every trade as the time weighted difference between VWAP and mark price: $\mathrm{\frac{VWAP - markPrice}{markPrice} * timeElapsed}$. - 3. Cap funding if required to the maximum defined by `HourlyFundingRateCap`. - 4. Set next funding timestamp. - 5. Emit `EventPerpetualMarketFundingUpdate`. - -### 2. Process Markets Scheduled to Settle - -For each market in the list of markets to settle: - -1. Settle market with zero closing fee and current mark price. - 1. Run socialized loss. This will calculate the total amount of funds missing in all of the market and then reduce the payout proportionally for each profitable position. For example a market with a total amount of 100 USDT missing funds and 10 profitable positions with identical quantity would result in a payout reduction of 10 USDT for each of the positions. - 2. All positions are forcibly closed. -2. Delete from storage. - -### 3. Process Matured Expiry Future Markets - -For each time expiry market, iterate through starting with first to expire: - -1. If market is premature, stop iteration. -2. If market is disabled, delete market from storage and go to next market. -3. Get cumulative price for the market from oracle. -4. If market is starting maturation, store `startingCumulativePrice` for market. -5. If market is matured, calculate the settlement price as $\mathrm{twap = (currentCumulativePrice - startingCumulativePrice) / twapWindow}$ and add to list of markets to be settled. -6. Settle all matured markets with defined closing fee and settlement price. The procedure is identical to the previous process of settling (see above). Note that the socialized loss is an optional step. In the regular case a market will not require any socialized loss. -7. Delete any settled markets from storage. - -### 4. Process Trading Rewards - -1. Check if the current trading rewards campaign is finished. -2. If the campaign is finished, distribute reward tokens to eligible traders. - - 1. Compute the available reward for each reward denom as `min(campaignRewardTokens, communityPoolRewardTokens)` - 2. Get the trader rewards based on the trading share from the respective trader calculated as `accountPoints * totalReward / totalTradingRewards`. - 3. Send reward tokens from community pool to trader. - 4. Reset total and all account trading reward points. - 5. Delete the current campaign ending timestamp. - -3. If a new campaign is launched, set the next current campaign ending timestamp as `CurrentCampaignStartTimestamp + CampaignDurationSeconds`. -4. If no current campaign is ongoing and no new campaigns are launched, delete campaign info, market qualifications and market multipliers from storage. - -### 5. Process Fee Discount Buckets - -- If the oldest bucket's end timestamp is older than the `block.timestamp - bucketCount * bucketDuration`: - - Prune the oldest bucket - - Iterate over all `bucketStartTimestamp + account → FeesPaidAmount`: - - Subtract the `FeesPaidAmount` from each account's `totalPastBucketFeesPaidAmount` - - Delete the account's `account → {tier, TTL timestamp}`. Note that this technically isn't necessary for correctness since we check the TTL timestamps in the Endblocker but is a state pruning strategy. - - Update the `CurrBucketStartTimestamp ← CurrBucketStartTimestamp + BucketDuration`. - -``` -bucket count 5 and with 100 sec duration - -120 220 320 420 520 220 320 420 520 620 - | | | | | | --> | | | | | | - 1 2 3 4 5 1 2 3 4 5 - -Current block.timestamp of 621: -621 - 5*100 = 121 -120 is older than 121, so prune the last bucket and create a new bucket. -``` diff --git a/.gitbook/developers/modules/injective/exchange/08_end_block.md b/.gitbook/developers/modules/injective/exchange/08_end_block.md deleted file mode 100644 index b536c118..00000000 --- a/.gitbook/developers/modules/injective/exchange/08_end_block.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -sidebar_position: 9 -title: EndBlocker ---- - -# EndBlocker - -The exchange [EndBlocker](https://docs.cosmos.network/master/building-modules/beginblock-endblock.html) runs at the end of every block in our defined order after governance and staking modules, and before the peggy, auction and insurance modules. It is particularly important that the governance module's EndBlocker runs before the exchange module's. - -- Stage 0: Determine the fee discounts for all the accounts that have placed an order in a fee-discount supported market in the current block. -- Stage 1: Process all market orders in parallel - spot market and derivative market orders - - Markets orders are executed against the resting orderbook at the time of the beginning of the block. - - Note that market orders may be invalidated in the EndBlocker due to subsequently incoming oracle updates or limit order cancels. -- Stage 2: Persist market order execution to store - - - Spot Markets - - Persist Spot market order execution data - - Emit relevant events - - `EventBatchSpotExecution` - - Derivative Markets - - Persist Derivative market order execution data - - Emit relevant events - - `EventBatchDerivativeExecution` - - `EventCancelDerivativeOrder` - -- Stage 3: Process all limit orders in parallel - spot and derivative limit orders that are matching - - Limit orders are executed in a frequent batch auction mode to ensure fair matching prices, see below for details. - - Note that vanilla limit orders may be invalidated in the EndBlocker due to subsequently incoming oracle updates and reduce-only limit orders may be invalidated in the EndBlocker due to subsequently incoming orders which flip a position. -- Stage 4: Persist limit order matching execution + new limit orders to store - - - Spot Markets - - Persist Spot Matching execution data - - Emit relevant events - - `EventNewSpotOrders` - - `EventBatchSpotExecution` - - Derivative Markets - - Persist Derivative Matching execution data - - Emit relevant events - - `EventNewDerivativeOrders` - - `EventBatchDerivativeExecution` - - `EventCancelDerivativeOrder` - -- Stage 5: Persist perpetual market funding info -- Stage 6: Persist trading rewards total and account points. -- Stage 7: Persist new fee discount data, i.e., new fees paid additions and new account tiers. -- Stage 8: Process Spot Market Param Updates if any -- Stage 9: Process Derivative Market Param Updates if any -- Stage 10: Emit Deposit and Position Update Events - -## Order Matching: Frequent Batch Auction (FBA) - -The goal of FBA is to prevent any [Front-Running](https://www.investopedia.com/terms/f/frontrunning.asp). This is achieved by calculating a single clearing price for all matched orders in a given block. - -1. Market orders are filled first against the resting orderbook at the time of the beginning of the block. While the resting orders are filled at their respective order prices, the market orders are all filled at a uniform clearing price with the same mechanism as limit orders. For an example for the market order matching in FBA fashion, look at the API docs [here](https://api.injective.exchange/#examples-market-order-matching). -2. Likewise limit orders are filled at a uniform clearing price. New limit orders are combined with the resting orderbook and orders are matched as long as there is still negative spread. The clearing price is either - -a. the best buy/sell order in case the last matched order crosses the spread in that direction, the, -b. the mark price in case of derivative markets and the mark price is between the last matched orders or -c. the mid price. - -For an example for the limit order matching in FBA fashion, look at the API docs [here](https://api.injective.exchange/#examples-limit-order-matching). - -## Single Trade Calculations - -- For a qualifying market compute the fee discounts: - - Fee discounts are applied as refunds and the fee paid contribution is recorded. - - Relayer fees are applied AFTER the fee discount is taken. -- For a qualifying market compute the trade reward point contribution: - - Obtain the FeePaidMultiplier for maker and taker. - - Compute the trade reward point contribution. - - Trade reward points are based on the discounted trading fee. -- Calculate fee refunds (or charges). There are several reasons why an order might get a fee refund after matching: - 1. It's a limit order which is not matched or only partially matched which means it will become a resting limit order and switch from a taker to maker fee. The refund is `UnmatchedQuantity * (TakerFeeRate - MakerFeeRate)`. Note that for negative maker fees, we refund the `UnmatchedQuantity * TakerFeeRate` instead. - 2. Fee discounts are applied. We refund the difference between the original fee paid and the fee paid after the discount. - 3. The order is matched at a better price resulting in a different fee. - - For buy orders a better price means a lower price and thus a lower fee. We refund the fee price delta. - - For sell orders a better price means a higher price and thus a higher fee. We charge the fee price delta. - - You can find the respective code with an example [here](https://github.com/InjectiveLabs/injective-core/blob/80dbc4e9558847ff0354be5d19a4d8b0bba7da96/injective-chain/modules/exchange/keeper/derivative_orders_processor.go#L502). Please check the master branch for the latest chain code. diff --git a/.gitbook/developers/modules/injective/exchange/09_events.md b/.gitbook/developers/modules/injective/exchange/09_events.md deleted file mode 100644 index 09008054..00000000 --- a/.gitbook/developers/modules/injective/exchange/09_events.md +++ /dev/null @@ -1,169 +0,0 @@ ---- -sidebar_position: 10 -title: Events ---- - -# Events - -The exchange module emits the following events: - -```proto -message EventBatchSpotExecution { - string market_id = 1; - bool is_buy = 2; - ExecutionType executionType = 3; - repeated TradeLog trades = 4; -} - -message EventBatchDerivativeExecution { - string market_id = 1; - bool is_buy = 2; - bool is_liquidation = 3; - // nil for time expiry futures - string cumulative_funding = 4 [ - (gogoproto.customtype) = "cosmossdk.io/math.LegacyDec", - (gogoproto.nullable) = true - ]; - ExecutionType executionType = 5; - repeated DerivativeTradeLog trades = 6; -} - -message EventLostFundsFromLiquidation { - string market_id = 1; - bytes subaccount_id = 2; - string lost_funds_from_available_during_payout = 3 [ - (gogoproto.customtype) = "cosmossdk.io/math.LegacyDec", - (gogoproto.nullable) = false - ]; - string lost_funds_from_order_cancels = 4 [ - (gogoproto.customtype) = "cosmossdk.io/math.LegacyDec", - (gogoproto.nullable) = false - ]; -} - -message EventBatchDerivativePosition { - string market_id = 1; - repeated SubaccountPosition positions = 2; -} - -message EventDerivativeMarketPaused { - string market_id = 1; - string settle_price = 2; - string total_missing_funds = 3; - string missing_funds_rate = 4; -} - -message EventBinaryOptionsMarketUpdate { - BinaryOptionsMarket market = 1 [ - (gogoproto.nullable) = false - ]; -} - -message EventNewSpotOrders { - string market_id = 1; - repeated SpotLimitOrder buy_orders = 2; - repeated SpotLimitOrder sell_orders = 3; -} - -message EventNewDerivativeOrders { - string market_id = 1; - repeated DerivativeLimitOrder buy_orders = 2; - repeated DerivativeLimitOrder sell_orders = 3; -} - -message EventCancelSpotOrder { - string market_id = 1; - SpotLimitOrder order = 2 [ - (gogoproto.nullable) = false - ]; -} - -message EventSpotMarketUpdate { - SpotMarket market = 1 [ - (gogoproto.nullable) = false - ]; -} - -message EventPerpetualMarketUpdate { - DerivativeMarket market = 1 [ - (gogoproto.nullable) = false - ]; - PerpetualMarketInfo perpetual_market_info = 2[ - (gogoproto.nullable) = true - ]; - PerpetualMarketFunding funding = 3[ - (gogoproto.nullable) = true - ]; -} - -message EventExpiryFuturesMarketUpdate { - DerivativeMarket market = 1 [ - (gogoproto.nullable) = false - ]; - ExpiryFuturesMarketInfo expiry_futures_market_info = 3[ - (gogoproto.nullable) = true - ]; -} - -message EventPerpetualMarketFundingUpdate { - string market_id = 1; - PerpetualMarketFunding funding = 2[ - (gogoproto.nullable) = false - ]; - bool is_hourly_funding = 3; - string funding_rate = 4 [ - (gogoproto.customtype) = "cosmossdk.io/math.LegacyDec", - (gogoproto.nullable) = true - ]; - string mark_price = 5 [ - (gogoproto.customtype) = "cosmossdk.io/math.LegacyDec", - (gogoproto.nullable) = true - ]; -} - -message EventSubaccountDeposit { - string src_address = 1; - bytes subaccount_id = 2; - cosmos.base.v1beta1.Coin amount = 3 [(gogoproto.nullable) = false]; -} - -message EventSubaccountWithdraw { - bytes subaccount_id = 1; - string dst_address = 2; - cosmos.base.v1beta1.Coin amount = 3 [(gogoproto.nullable) = false]; -} - -message EventSubaccountBalanceTransfer { - string src_subaccount_id = 1; - string dst_subaccount_id = 2; - cosmos.base.v1beta1.Coin amount = 3 [(gogoproto.nullable) = false]; -} - -message EventBatchDepositUpdate { - repeated DepositUpdate deposit_updates = 1; -} - -message EventCancelDerivativeOrder { - string market_id = 1; - bool isLimitCancel = 2; - DerivativeLimitOrder limit_order = 3 [ - (gogoproto.nullable) = true - ]; - DerivativeMarketOrderCancel market_order_cancel = 4 [ - (gogoproto.nullable) = true - ]; -} - -message EventFeeDiscountSchedule { - FeeDiscountSchedule schedule = 1; -} - -message EventTradingRewardCampaignUpdate { - TradingRewardCampaignInfo campaign_info = 1; - repeated CampaignRewardPool campaign_reward_pools = 2; -} - -message EventTradingRewardDistribution { - repeated AccountRewards account_rewards = 1; -} -``` diff --git a/.gitbook/developers/modules/injective/exchange/10_params.md b/.gitbook/developers/modules/injective/exchange/10_params.md deleted file mode 100644 index 8dcdf5d1..00000000 --- a/.gitbook/developers/modules/injective/exchange/10_params.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -sidebar_position: 11 -title: Parameters ---- - -# Parameters - -The exchange module contains the following parameters: - -| Key | Type | Example | -| ------------------------------------------- | -------- | ------------------ | -| SpotMarketInstantListingFee | sdk.Coin | 100inj | -| DerivativeMarketInstantListingFee | sdk.Coin | 1000inj | -| DefaultSpotMakerFeeRate | math.LegacyDec | 0.1% | -| DefaultSpotTakerFeeRate | math.LegacyDec | 0.2% | -| DefaultDerivativeMakerFeeRate | math.LegacyDec | 0.1% | -| DefaultDerivativeTakerFeeRate | math.LegacyDec | 0.2% | -| DefaultInitialMarginRatio | math.LegacyDec | 5% | -| DefaultMaintenanceMarginRatio | math.LegacyDec | 2% | -| DefaultFundingInterval | int64 | 3600 | -| FundingMultiple | int64 | 3600 | -| RelayerFeeShareRate | math.LegacyDec | 40% | -| DefaultHourlyFundingRateCap | math.LegacyDec | 0.0625% | -| DefaultHourlyInterestRate | math.LegacyDec | 0.000416666% | -| MaxDerivativeOrderSideCount | int64 | 20 | -| InjRewardStakedRequirementThreshold | sdk.Coin | 25inj | -| TradingRewardsVestingDuration | int64 | 1209600 | -| LiquidatorRewardShareRate | math.LegacyDec | 0.05% | -| BinaryOptionsMarketInstantListingFee | sdk.Coin | 10inj | -| AtomicMarketOrderAccessLevel | string | SmartContractsOnly | -| SpotAtomicMarketOrderFeeMultiplier | math.LegacyDec | 2x | -| DerivativeAtomicMarketOrderFeeMultiplier | math.LegacyDec | 2x | -| BinaryOptionsAtomicMarketOrderFeeMultiplier | math.LegacyDec | 2x | -| MinimalProtocolFeeRate | math.LegacyDec | 0.00001% | -| IsInstantDerivativeMarketLaunchEnabled | bool | false | diff --git a/.gitbook/developers/modules/injective/exchange/11_msg_privileged_execute_contract.md b/.gitbook/developers/modules/injective/exchange/11_msg_privileged_execute_contract.md deleted file mode 100644 index 16995856..00000000 --- a/.gitbook/developers/modules/injective/exchange/11_msg_privileged_execute_contract.md +++ /dev/null @@ -1,127 +0,0 @@ ---- -sidebar_position: 12 -title: MsgPrivilegedExecuteContract ---- - -# MsgPrivilegedExecuteContract - -MsgPrivilegedExecuteContract defines a method for executing a Cosmwasm contract from the exchange module with privileged capabilities. - -```go -type MsgPrivilegedExecuteContract struct { - Sender string - // funds defines the user's bank coins used to fund the execution (e.g. 100inj). - Funds github_com_cosmos_cosmos_sdk_types.Coins - // contract_address defines the contract address to execute - ContractAddress string - // data defines the call data used when executing the contract - Data string -} - -``` - -**Fields description** - -- `Sender` describes the creator of this msg. -- `Funds` defines the user's bank coins used to fund the execution (e.g. 100inj). -- `ContractAddress` defines the contract address to execute. -- `Data` defines the call data used when executing the contract, see further details below. - -**Contract Interface** - -If you want to enable privileged actions on your contract, you must implement the following execute method: - -```rust -InjectiveExec { - origin: String, - name: String, - args: MyArgs, -} -``` - -- The `origin` field is the address of the user who sent the privileged action. You don't have to set this field yourself, it will be set by the exchange module. -- The `name` field is the name of the privileged action. You can define these to be whatever you want. -- The `args` field is the arguments of the privileged action. You can define these to be whatever you want. - -A complete definition of the Data string in Golang is: - -```go -type ExecutionData struct { - Origin string `json:"origin"` - Name string `json:"name"` - MyArgs interface{} `json:"args"` -} -``` - -A user can then call the privileged action by sending a `MsgPrivilegedExecuteContract` with the following data: - -```json -{ - sender: "inj...", - funds: "1000000000000000000inj", - contract_address: "inj...", - data: { - origin: "inj...", - name: "my_privileged_action", - args: { - ... - } - } -} -``` - -**Supported Privileged Actions** - -There are currently two supported privileged actions: - -```go -type PrivilegedAction struct { - SyntheticTrade *SyntheticTradeAction `json:"synthetic_trade"` - PositionTransfer *PositionTransfer `json:"position_transfer"` -} -``` - -These privileged actions must be set inside the Cosmwasm response data field, e.g.: - -```rust -let privileged_action = PrivilegedAction { - synthetic_trade: None, - position_transfer: position_transfer_action, -}; -response = response.set_data(to_binary(&privileged_action)?); -``` - -**PositionTransfer** - -The position transfer allows a contract to transfer a derivative position from its own subaccount to a user's subaccount. The position may not be liquidable. Solely the receiver pays a taker trading fee deducted from his balances. - -Currently only transfers from the contract's subaccount to a user's subaccount are supported. - -```go -type PositionTransfer struct { - MarketID common.Hash `json:"market_id"` - SourceSubaccountID common.Hash `json:"source_subaccount_id"` - DestinationSubaccountID common.Hash `json:"destination_subaccount_id"` - Quantity math.LegacyDec `json:"quantity"` -} -``` - -**SyntheticTrade** - -The synthetic trade allows a contract to execute a synthetic trade on behalf of a user for derivative markets. This is not touching the orderbook and is purely a synthetic trade. Taker trading fees still apply. The subaccount ids must be set to the contract's subaccount id and the user's subaccount id. - -```go -type SyntheticTradeAction struct { - UserTrades []*SyntheticTrade `json:"user_trades"` - ContractTrades []*SyntheticTrade `json:"contract_trades"` -} - -type SyntheticTrade struct { - MarketID common.Hash `json:"market_id"` - SubaccountID common.Hash `json:"subaccount_id"` - IsBuy bool `json:"is_buy"` - Quantity math.LegacyDec `json:"quantity"` - Price math.LegacyDec `json:"price"` - Margin math.LegacyDec `json:"margin"` -} -``` diff --git a/.gitbook/developers/modules/injective/exchange/README.md b/.gitbook/developers/modules/injective/exchange/README.md deleted file mode 100644 index d9c8423d..00000000 --- a/.gitbook/developers/modules/injective/exchange/README.md +++ /dev/null @@ -1,29 +0,0 @@ -# `Exchange` - -## Abstract - -The `exchange` module is the heart of the Injective Chain which enables fully decentralized spot and derivative exchange. -It is the _sine qua non_ module of the chain and integrates tightly with the `auction`, `insurance`, `oracle`, and `peggy` modules. - -The exchange protocol enables traders to create and trade on arbitrary spot and derivative markets. -The entire process of orderbook management, trade execution, order matching and settlement occurs on chain through the logic codified by the exchange module. - -The `exchange` module enables the exchange of tokens on two types of markets: - -1. `Derivative Market`: Either a `Perpetual Swap Market` or a `Futures Market`. -2. `Spot Market` - -## Contents - -1. **[Derivative Market Concepts](00_derivative_market_concepts.md)** -2. **[Spot Market Concepts](01_spot_market_concepts.md)** -3. **[Other Concepts](02_other_concepts.md)** -4. **[State](03_state.md)** -5. **[State Transitions](04_state_transitions.md)** -6. **[Messages](05_messages.md)** -7. **[Proposals](06_proposals.md)** -8. **[Begin Block](07_begin_block.md)** -9. **[End Block](08_end_block.md)** -10. **[Events](09_events.md)** -11. **[Params](10_params.md)** -12. **[MsgPrivilegedExecuteContract](11_msg_privileged_execute_contract.md)** diff --git a/.gitbook/developers/modules/injective/insurance/01_state.md b/.gitbook/developers/modules/injective/insurance/01_state.md deleted file mode 100644 index b7c3402c..00000000 --- a/.gitbook/developers/modules/injective/insurance/01_state.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -sidebar_position: 1 -title: State ---- - -# State - -## Params - -`Params` is a module-wide configuration structure that stores system parameters and defines overall functioning of the insurance module. - -- Params: `Paramsspace("insurance") -> legacy_amino(params)` - -```go - -type Params struct { - // default_redemption_notice_period_duration defines the default minimum notice period duration that must pass after an underwriter sends - // a redemption request before the underwriter can claim his tokens - DefaultRedemptionNoticePeriodDuration time.Duration -} -``` - -## Insurance Types - -`InsuranceFund` defines all the information of the `Insurance Funds` by market. - -```go - -type InsuranceFund struct { - // deposit denomination for the given insurance fund - DepositDenom string - // insurance fund pool token denomination for the given insurance fund - InsurancePoolTokenDenom string - // redemption_notice_period_duration defines the minimum notice period duration that must pass after an underwriter sends - // a redemption request before the underwriter can claim his tokens - RedemptionNoticePeriodDuration time.Duration - // balance of fund - Balance math.Int - // total share tokens minted - TotalShare math.Int - // marketID of the derivative market - MarketId string - // ticker of the derivative market - MarketTicker string - // Oracle base currency of the derivative market - OracleBase string - // Oracle quote currency of the derivative market - OracleQuote string - // Oracle type of the derivative market - OracleType types.OracleType - // Expiration time of the derivative market. Should be -1 for perpetual markets. - Expiry int64 -} -``` - -`RedemptionSchedule` defines redemption schedules from users - redemption is not executed instantly but there's `redemption_notice_period_duration` specified per market. - -```go -type RedemptionSchedule struct { - // id of redemption schedule - Id uint64 - // marketId of redemption schedule - MarketId string - // address of the redeemer - Redeemer string - // the time after which the redemption can be claimed - ClaimableRedemptionTime time.Time - // the insurance_pool_token amount to redeem - RedemptionAmount sdk.Coin -} -``` - -Additionally, we introduce `next_share_denom_id` and `next_redemption_schedule_id` to manage insurance fund share token -denom and redemption schedules from various users. - -```go -// GenesisState defines the insurance module's genesis state. -type GenesisState struct { - // params defines all the parameters of related to insurance. - Params Params - InsuranceFunds []InsuranceFund - RedemptionSchedule []RedemptionSchedule - NextShareDenomId uint64 - NextRedemptionScheduleId uint64 -} -``` - -## Pending Redemptions - -Pending Redemptions Objects are kept to store all the information about redemption requests and to auto-withdraw when -the duration pass. - diff --git a/.gitbook/developers/modules/injective/insurance/02_state_transitions.md b/.gitbook/developers/modules/injective/insurance/02_state_transitions.md deleted file mode 100644 index 08b66df4..00000000 --- a/.gitbook/developers/modules/injective/insurance/02_state_transitions.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -sidebar_position: 2 -title: State Transitions ---- - -# State Transitions - -This document describes the state transition operations pertaining to: - -- Creating an insurance fund -- Underwriting an insurance fund -- Request a redemption from the insurance fund -- Automatic processing of matured redemption requests - -## Creating insurance fund - -**Params description** -`Sender` field describes the creator of an insurance fund . -`Ticker`, `QuoteDenom`, `OracleBase`, `OracleQuote`, `OracleType`, `Expiry` fields describe the derivative market info -that the insurance fund associated to. -`InitialDeposit` field describes the initial deposit amount to be put on the insurance fund. - -**Steps** - -- Get `MarketId` for the insurance fund - **Note**, market could be not available yet on `exchange` and it's not an - issue -- Ensure if insurance fund associated to the `MarketId` does not exist -- Ensure if initial deposit amount is not zero -- Get `shareDenom` that is unique - it's incremented when share denom is requested for insurance fund creation or when - underwriting insurance fund that has zero balance and non-zero total share denom supply. -- Send coins from creator's account to insurance fund module account -- Create insurance fund object with `DefaultRedemptionNoticePeriodDuration` and with the params provided -- Set `Balance` of fund object to initial deposit amount -- Mint `InsuranceFundInitialSupply` (10^18) `shareDenom` tokens to creator account -- Save insurance fund object to store -- Register newly created insurance fund `shareDenom` metadata inside BankKeeper - -## Underwriting an insurance fund - -**Params description** -`Sender` field describes the underwriter of an insurance fund . -`MarketId` field describes the derivative market id to the insurance fund. -`Deposit` field describes the deposit amount to be added on the insurance fund. - -**Steps** - -- Ensure if insurance fund associated to the `MarketId` does exist -- Send underwriting tokens from sender's account to module account -- Make actions based on the status of insurance fund associated to the `MarketId`. - * A. when `Balance` and `ShareDenomSupply` are zero - 1. mint `InsuranceFundInitialSupply` (10^18) to the sender. - 2. set `Balance` to deposit amount - 3. set `ShareDenomSupply` to `InsuranceFundInitialSupply` - * B. when `Balance` is zero and `ShareDenomSupply` is not zero - 1. change `ShareDenom` of the the insurance fund to start new insurance fund from beginning. - 2. register newly created `ShareDenom` in bank keeper - 3. mint `InsuranceFundInitialSupply` (10^18) to the sender. - 4. set `Balance` to deposit amount - 5. set `ShareDenomSupply` to `InsuranceFundInitialSupply` - * C. when `Balance` is not zero and `ShareDenomSupply` is zero - 1. mint `InsuranceFundInitialSupply` (10^18) to the sender. - 2. increase `Balance` by deposit amount - 3. set `ShareDenomSupply` to `InsuranceFundInitialSupply` - * D. when both `Balance` and `ShareDenomSupply` are not zero - normal case - 1. increase `Balance` by deposit amount - 2. mint `prev_ShareDenomSupply * deposit_amount / prev_Balance` amount of `ShareDenom` to sender - 3. increase `ShareDenomSupply` with mint amount -- Save insurance fund object to store - -## Requesting a redemption from an insurance fund - -**Params description** -`Sender` field describes the redemption requester of an insurance fund . -`MarketId` field describes the derivative market id associated to the insurance fund. -`Amount` field describes the share token amount to be redeemed. - -**Steps** - -- Ensure insurance fund associated to the `MarketId` does exist -- Send `ShareDenom` to module account -- Get new redemption schedule ID -- Calculate `ClaimTime` from insurance fund's redemption notice period duration and current block time -- Calculate key to store pending redemption (redemption schedule) -- Create redemption schedule object with details -- Store redemption schedule object to store - -## Insurance fund actions on liquidation events in derivative market - -**Steps** - -- `exchange` module finds relative insurance fund from the insurance keeper. -- if `missingFund` is positive, it withdraws the amount from the insurance fund through `WithdrawFromInsuranceFund`. -- if `missingFund` is negative, it deposits the amount into the insurance fund through `DepositIntoInsuranceFund`. - -## Automatic processing of pending redemptions - -**Steps** - -Iterate all matured redemptions by sorted order by `ClaimTime` and perform the following actions: - -- If `ClaimTime` is after current block time, break early -- Ensure the insurance fund exist for matured redemption schedule -- Calculate redeem amount from share amount - `shareAmt * fund.Balance * fund.TotalShare` -- Send calculate redeem amount from module account to redeemer account -- Burn share tokens sent to the module account at the time of redemption schedule -- Delete redemption schedule object -- Reduce insurance fund's `Balance` by redeem amount -- Store updated insurance object to store - -# Hooks - -Other modules may register operations to execute when a certain event has occurred within insurance fund. These events -can be registered to execute either right `Before` or `After` the exchange event (as per the hook name). The following -hooks can registered with the exchange: - -**Note**: Hooks are not available and exchange module calls insurance keeper function directly. - -**Steps** -When liquidation event happen in derivative market - -- `exchange` module finds relative insurance fund from the insurance keeper. -- if `missingFund` is positive, it withdraws the amount from the insurance fund through `WithdrawFromInsuranceFund`. -- if `missingFund` is negative, it deposits the amount into the insurance fund through `DepositIntoInsuranceFund`. - diff --git a/.gitbook/developers/modules/injective/insurance/03_messages.md b/.gitbook/developers/modules/injective/insurance/03_messages.md deleted file mode 100644 index 416b1a03..00000000 --- a/.gitbook/developers/modules/injective/insurance/03_messages.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -sidebar_position: 3 -title: Messages ---- - -# Messages - -In this section we describe the processing of the exchange messages and the corresponding updates to the state. All created/modified state objects specified by each message are defined within the [state](02_state_transitions.md) section. - -## Msg/CreateInsuranceFund - -`MsgCreateInsuranceFund` defines a message to create an insurance fund for a derivative market. - -```protobuf -// MsgCreateInsuranceFund a message to create an insurance fund for a derivative market. -message MsgCreateInsuranceFund { - option (gogoproto.equal) = false; - option (gogoproto.goproto_getters) = false; - // Creator of the insurance fund. - string sender = 1; - // Ticker for the derivative market. - string ticker = 2; - // Coin denom to use for the market quote denom - string quote_denom = 3; - // Oracle base currency - string oracle_base = 4; - // Oracle quote currency - string oracle_quote = 5; - // Oracle type - injective.oracle.v1beta1.OracleType oracle_type = 6; - // Expiration time of the market. Should be -1 for perpetual markets. - int64 expiry = 7; - // Initial deposit of the insurance fund - cosmos.base.v1beta1.Coin initial_deposit = 8 [(gogoproto.nullable) = false]; -} -``` - -**Fields description** - -- `Sender` field describes the creator of an insurance fund . -- `Ticker`, `QuoteDenom`, `OracleBase`, `OracleQuote`, `OracleType`, `Expiry` fields describe the derivative market info - that the insurance fund corresponds to. -- `InitialDeposit` specifies the initial deposit amount used to underwrite the insurance fund. - -Disclaimer: When creating an insurance fund a small portion of shares (1%) will be reserved by the fund itself (protocol owned liquidity). A value of 1 USD is recommended as first subscription. - -Motivation behind this feature is to avoid potential rounding issues when underwriting to a fund. For example, without having protocol owned liquidity, if the original fund creator would take out most of their shares leaving but a small amount, the value of the share token could diverge drastically from the original value. The next underwriter would then have to provide a much larger deposit despite gaining the same amount of shares. - -## Msg/Underwrite - -`MsgUnderwrite` defines a message to underwrite an insurance fund - -```protobuf -// MsgUnderwrite defines a message for depositing coins to underwrite an insurance fund -message MsgUnderwrite { - option (gogoproto.equal) = false; - option (gogoproto.goproto_getters) = false; - // Address of the underwriter. - string sender = 1; - // MarketID of the insurance fund. - string market_id = 2; - // Amount of quote_denom to underwrite the insurance fund. - cosmos.base.v1beta1.Coin deposit = 3 [(gogoproto.nullable) = false]; -} -``` - -**Fields description** - -- `Sender` field describes the underwriter of an insurance fund . -- `MarketId` field describes the derivative market id to the insurance fund. -- `Deposit` field describes the deposit amount to be added on the insurance fund. - -## Msg/RequestRedemption - -`MsgRequestRedemption` defines a message to request redemption from the insurance fund. - -```protobuf -// MsgRequestRedemption defines a message for requesting a redemption of the sender's insurance fund tokens -message MsgRequestRedemption { - option (gogoproto.equal) = false; - option (gogoproto.goproto_getters) = false; - // Address of the underwriter requesting a redemption. - string sender = 1; - // MarketID of the insurance fund. - string market_id = 2; - // Insurance fund share token amount to be redeemed. - cosmos.base.v1beta1.Coin amount = 3 [(gogoproto.nullable) = false]; -} -``` - -**Fields description** - -- `Sender` field describes the redemption requester of an insurance fund . -- `MarketId` field describes the derivative market id associated to the insurance fund. -- `Amount` field describes the share token amount to be redeemed. diff --git a/.gitbook/developers/modules/injective/insurance/04_end_block.md b/.gitbook/developers/modules/injective/insurance/04_end_block.md deleted file mode 100644 index 8fece042..00000000 --- a/.gitbook/developers/modules/injective/insurance/04_end_block.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -sidebar_position: 4 -title: End-Block ---- - -# End-Block - -At each EndBlock, redemption requests that have matured are automatically processed, resulting in the insurance pool token for the redemption being burned and the pro-rata quote currency amount corresponding to the redemption being withdrawn from the insurance module to the underwriter's balances. More details can be found in the in Automatic withdrawal of pending redemptions in the [state transitions](./02_state_transitions.md) section. diff --git a/.gitbook/developers/modules/injective/insurance/05_events.md b/.gitbook/developers/modules/injective/insurance/05_events.md deleted file mode 100644 index 5add6de2..00000000 --- a/.gitbook/developers/modules/injective/insurance/05_events.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -sidebar_position: 5 -title: Events ---- - -# Events - -The insurance module emits the following events: - -## Handlers - -### MsgCreateInsuranceFund - -| Type | Attribute Key | Attribute Value | -| ---------------------------------------------------- | ------------- | --------------- | -| injective.insurance.v1beta1.EventInsuranceFundUpdate | fund | {fundJSON} | - -### MsgUnderwrite - -| Type | Attribute Key | Attribute Value | -| ---------------------------------------------------- | ------------- | --------------- | -| injective.insurance.v1beta1.EventInsuranceFundUpdate | fund | {fundJSON} | - -### MsgRequestRedemption - -| Type | Attribute Key | Attribute Value | -| -------------------------------------------------- | ------------- | --------------- | -| injective.insurance.v1beta1.EventRequestRedemption | schedule | {scheduleJSON} | - - - -## EndBlocker - -| Type | Attribute Key | Attribute Value | -| ---------------------------------------------------- | ------------- | --------------- | -| injective.insurance.v1beta1.EventInsuranceFundUpdate | fund | {fundJSON} | -| injective.insurance.v1beta1.EventWithdrawRedemption | schedule | {scheduleJSON} | -| injective.insurance.v1beta1.EventWithdrawRedemption | redeem_coin | {redeemCoin} | - diff --git a/.gitbook/developers/modules/injective/insurance/06_params.md b/.gitbook/developers/modules/injective/insurance/06_params.md deleted file mode 100644 index 2f042a3a..00000000 --- a/.gitbook/developers/modules/injective/insurance/06_params.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -sidebar_position: 6 -title: Parameters ---- - -# Parameters - -The insurance module contains the following parameter: - -| Key | Type | Example | -| ----------------------------------------- | ------------- | --------------------- | -| default_redemption_notice_period_duration | time.Duration | `time.Hour * 24 * 14` | - diff --git a/.gitbook/developers/modules/injective/insurance/07_future_improvements.md b/.gitbook/developers/modules/injective/insurance/07_future_improvements.md deleted file mode 100644 index 44c84d94..00000000 --- a/.gitbook/developers/modules/injective/insurance/07_future_improvements.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -sidebar_position: 7 -title: Future Improvements ---- - -# Future improvements - -## Precision Loss Edge Case Handling - -Insurance Fund share tokens currently have a decimal scale of `10^18`. There could be potential problems using this as user deposits amount could be various and in the future, share token's price could be very higher or lower. - diff --git a/.gitbook/developers/modules/injective/insurance/README.md b/.gitbook/developers/modules/injective/insurance/README.md deleted file mode 100644 index 172cdb49..00000000 --- a/.gitbook/developers/modules/injective/insurance/README.md +++ /dev/null @@ -1,19 +0,0 @@ -# `Insurance` - -## Abstract - -This paper specifies the insurance module of the Injective Chain. - -This module provides insurance funds for derivative markets in the `exchange` module of the Injective Chain to use in order to support higher leverage trading. On a high level, insurance funds for each derivative market are funded by a permissionless group of underwriters who each own a proportional claim (represented through insurance fund share tokens) over the underlying assets in the insurance fund. - -Each insurance fund grows when positions in its corresponding derivative market are liquidated with positive equity, as half of the positive equity is sent to the insurance fund upon liquidation. When a position with negative equity is liquidated (i.e. the position has surpassed bankruptcy), the insurance fund is utilized to cover the missing equity. - -## Contents - -1. **[State](01_state.md)** -2. **[State Transitions](02_state_transitions.md)** -3. **[Messages](03_messages.md)** -4. **[End Block](04_end_block.md)** -5. **[Events](05_events.md)** -6. **[Params](06_params.md)** -7. **[Future Improvements](07_future_improvements.md)** \ No newline at end of file diff --git a/.gitbook/developers/modules/injective/ocr/01_concepts.md b/.gitbook/developers/modules/injective/ocr/01_concepts.md deleted file mode 100644 index c42047f4..00000000 --- a/.gitbook/developers/modules/injective/ocr/01_concepts.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -sidebar_position: 1 -title: Concepts ---- - -# Concepts - -The `ocr` module is to store chainlink's OCR information into on-chain by verified members. - -Off-chain reporting consists of N nodes (oracles), gathering data from external sources. Reports are being exchanged in a p2p fashion between oracles to get signatures of approval. A subset of nodes (transmitters) is identified by the `ocr` module on-chain, they must submit the reports to module, the first transmitter who hits the chain gets an extra reward to cover gas costs. Other transmitters are not. All oracles participating in the round are getting paid. `ocr` module stores median value from the reports. - -## OCR Terminology - -The protocol periodically sends **oracle reports** to the OCR module. The reporting protocol is comprised of three components: **pacemaker**, **report generation** and **transmission**. - -**Pacemaker** - -The pacemaker drives the report generation process which is structured in **epochs**. Each epoch has a designatd leader who the pacemaker then tasks with starting the report generation protocol. If the leader does not produce a valid report in time, the pacemaker also aborts the current report generation and starts a new epoch. - -**Report Generation** - -For a given epoch, the report generation protocol enters into **rounds** where **observations** are gathered and (given conditions are met such as heartbeat and deviation) a signed oracle **report** is generated. The rounds are controlled by a leader node who controls the frequency of rounds, gathers the observations and generates the report. - -**Transmission** - -The transmission protocol then transmits the generated report to the OCR module. - -## Off-chain OCR integration - -- Provide means to communicate with Injective using sdk-go -- Read data from the module, such as a list of approved oracles -- Submit reports as Msgs (Implement `ContractTransmitter`) -- Implement `OffchainConfigDigester` -- Implement `OnchainKeyring` for producing signatures that will work on the target chain module -- Implement `ContractConfigTracker` for tracking changes of the chain module config (gov approved) - -Notes: - -- Reports are timestamped in Epoch-Round fashion -- `ocr` module verifies the signatures of oracles on the report -- `ocr` module records oracles who contributed to a report, for the payout -- `ocr` module stores the median of the observations -- `ocr` module provides extra reward for the first submitter of a Msg - -### Integration Overview - -Chainlink has several [price data feeds](https://data.chain.link/ethereum/mainnet/stablecoins) including: - -- 80 Crypto/USD pairs (e.g. ETH/USD, BTC/USD) -- 17 Stablecoin pairs (e.g. USDT/USD, USDC/USD) -- 73 ETH pairs (e.g. LINK/ETH) -- 17 Forex pairs (e.g. GBP/USD, CNY/USD) - -A derivative market on Injective specifies the following oracle parameters: - -- An oracleBase (e.g. BTC) -- An oracleQuote (e.g. USDT) -- An oracleType (e.g. Chainlink) - -Thus for a BTC/USDT derivative market on Injective, the oracleBase would be BTC/USD, the oracleQuote would be USDT/USD and the oracleType would be Chainlink. The price for the market would then be obtained by dividing the BTC/USD price with the USDT/USD price, leaving the BTC/USDT price. diff --git a/.gitbook/developers/modules/injective/ocr/02_state.md b/.gitbook/developers/modules/injective/ocr/02_state.md deleted file mode 100644 index 5ab39bbd..00000000 --- a/.gitbook/developers/modules/injective/ocr/02_state.md +++ /dev/null @@ -1,218 +0,0 @@ ---- -sidebar_position: 2 -title: State ---- - -# State - -Genesis state defines the initial state of the module to be used to setup the module. - -```go -// GenesisState defines the OCR module's genesis state. -type GenesisState struct { - // params defines all the parameters of related to OCR. - Params Params - // feed_configs stores all of the supported OCR feeds - FeedConfigs []*FeedConfig - // latest_epoch_and_rounds stores the latest epoch and round for each feedId - LatestEpochAndRounds []*FeedEpochAndRound - // feed_transmissions stores the last transmission for each feed - FeedTransmissions []*FeedTransmission - // latest_aggregator_round_ids stores the latest aggregator round ID for each feedId - LatestAggregatorRoundIds []*FeedLatestAggregatorRoundIDs - // reward_pools stores the reward pools - RewardPools []*RewardPool - // feed_observation_counts stores the feed observation counts - FeedObservationCounts []*FeedCounts - // feed_transmission_counts stores the feed transmission counts - FeedTransmissionCounts []*FeedCounts - // pending_payeeships stores the pending payeeships - PendingPayeeships []*PendingPayeeship -} -``` -## Params - -`Params` is a module-wide configuration that stores system parameters and defines overall functioning of the ocr module. -This module is modifiable by governance using params update proposal natively supported by `gov` module. - -Struct for the `ocr` module params store. -```go -type Params struct { - // Native denom for LINK coin in the bank keeper - LinkDenom string - // The block number interval at which payouts are made - PayoutBlockInterval uint64 - // The admin for the OCR module - ModuleAdmin string -} -``` - -## FeedConfig - -`FeedConfig` is to manage the configurations of feed and it exists one per feed. - -```go -type FeedConfig struct { - // signers ith element is address ith oracle uses to sign a report - Signers []string - // transmitters ith element is address ith oracle uses to transmit a report via the transmit method - Transmitters []string - // f maximum number of faulty/dishonest oracles the protocol can tolerate while still working correctly - F uint32 - // onchain_config contains properties relevant only for the Cosmos module. - OnchainConfig *OnchainConfig - // offchain_config_version version of the serialization format used for "offchain_config" parameter - OffchainConfigVersion uint64 - // offchain_config serialized data used by oracles to configure their offchain operation - OffchainConfig []byte -} -``` - -### FeedConfigInfo - -`FeedConfigInfo` is storing the information that needs to be updated more often for each transmission event. - -```go -type FeedConfigInfo struct { - LatestConfigDigest []byte - F uint32 - N uint32 - // config_count ordinal number of this config setting among all config settings - ConfigCount uint64 - LatestConfigBlockNumber int64 -} -``` - -### Transmission - -`Transmission` is the unit to save transition information on the store. - -```go -// Transmission records the median answer from the transmit transaction at -// time timestamp -type Transmission struct { - Answer math.LegacyDec - ObservationsTimestamp int64 - TransmissionTimestamp int64 -} -``` - -### Report - -`Report` is the unit to save report information on the store. - -```go -type Report struct { - ObservationsTimestamp int64 - Observers []byte - Observations []math.LegacyDec -} -``` - -`ReportToSign` saves the information that needs to be signed by observers. - -```go -type ReportToSign struct { - ConfigDigest []byte - Epoch uint64 - Round uint64 - ExtraHash []byte - // Opaque report - Report []byte -} -``` - -### OnchainConfig - -`OnchainConfig` saves the configuration that needs to be managed on-chain for feed config. - -```go -type OnchainConfig struct { - // chain_id the ID of the Cosmos chain itself. - ChainId string - // feed_id is an unique ID for the target of this config - FeedId string - // lowest answer the median of a report is allowed to be - MinAnswer math.LegacyDec - // highest answer the median of a report is allowed to be - MaxAnswer math.LegacyDec - // Fixed LINK reward for each observer - LinkPerObservation math.Int - // Fixed LINK reward for transmitter - LinkPerTransmission math.Int - // Native denom for LINK coin in the bank keeper - LinkDenom string - // Enables unique reports - UniqueReports bool - // short human-readable description of observable this feed's answers pertain to - Description string - // feed administrator - FeedAdmin string - // feed billing administrator - BillingAdmin string -} -``` - -### ContractConfig - -`ContractConfig` saves the configuration that is related to contract to store OCR. - -```go -type ContractConfig struct { - // config_count ordinal number of this config setting among all config settings - ConfigCount uint64 - // signers ith element is address ith oracle uses to sign a report - Signers []string - // transmitters ith element is address ith oracle uses to transmit a report via the transmit method - Transmitters []string - // f maximum number of faulty/dishonest oracles the protocol can tolerate while still working correctly - F uint32 - // onchain_config serialized config that is relevant only for the module. - OnchainConfig []byte - // offchain_config_version version of the serialization format used for "offchain_config" parameter - OffchainConfigVersion uint64 - // offchain_config serialized data used by oracles to configure their offchain operation - OffchainConfig []byte -} -``` -### FeedProperties - -`FeedProperties` is a unit to store the properties of feed by id. - -```go -type FeedProperties struct { - // feed_id is an unique ID for the target of this config - FeedId string - // f maximum number of faulty/dishonest oracles the protocol can tolerate while still working correctly - F uint32 - // offchain_config_version version of the serialization format used for "offchain_config" parameter - OffchainConfigVersion uint64 - // offchain_config serialized data used by oracles to configure their offchain operation - OffchainConfig []byte - // lowest answer the median of a report is allowed to be - MinAnswer math.LegacyDec - // highest answer the median of a report is allowed to be - MaxAnswer math.LegacyDec - // Fixed LINK reward for each observer - LinkPerObservation math.Int - // Fixed LINK reward for transmitter - LinkPerTransmission math.Int - // Enables unique reports - UniqueReports bool - // short human-readable description of observable this feed's answers pertain to - Description string -} -``` - -### PendingPayeeship - -`PendingPayeeship` is a record that is stored when a person is delegating payeeship to another address. -When proposed payee accept this, this record is removed. - -```go -type PendingPayeeship struct { - FeedId string - Transmitter string - ProposedPayee string -} -``` \ No newline at end of file diff --git a/.gitbook/developers/modules/injective/ocr/03_messages.md b/.gitbook/developers/modules/injective/ocr/03_messages.md deleted file mode 100644 index ee0823ff..00000000 --- a/.gitbook/developers/modules/injective/ocr/03_messages.md +++ /dev/null @@ -1,227 +0,0 @@ ---- -sidebar_position: 3 -title: Messages ---- - -# Messages - -In this section we describe the processing of the ocr messages and the corresponding updates to the state. - -## Msg/CreateFeed - -`MsgCreateFeed` is a message to create feed config and it is restricted message that is executable by module admin. - -```protobuf -message MsgCreateFeed { - option (gogoproto.equal) = false; - option (gogoproto.goproto_getters) = false; - string sender = 1; - FeedConfig config = 2; -} -``` - -**Steps** - -- Ensure `Sender` is module admin -- Ensure `msg.Config.OnchainConfig.LinkDenom` is module param's `LinkDenom` -- Set `OnchainConfig.ChainId` from `ctx.ChainID` -- Ensure `FeedConfig` with same `FeedId` does not exist -- Set latest `EpochAndRound` to `(0, 0)` -- Set feed config for `feedId` -- Set feed trasmissions count and observations count to 1 - -## Msg/UpdateFeed - -`MsgCreateFeed` is a message to update feed config and it is restricted message that is executable by feed admin or feed billing admin. - -```protobuf -message MsgUpdateFeed { - option (gogoproto.equal) = false; - option (gogoproto.goproto_getters) = false; - string sender = 1; - // feed_id is an unique ID for the target of this config - string feed_id = 2; - // signers ith element is address ith oracle uses to sign a report - repeated string signers = 3; - // transmitters ith element is address ith oracle uses to transmit a report via the transmit method - repeated string transmitters = 4; - // Fixed LINK reward for each observer - string link_per_observation = 5[ - (gogoproto.customtype) = "cosmossdk.io/math.Int", - (gogoproto.nullable) = true - ]; - // Fixed LINK reward for transmitter - string link_per_transmission = 6[ - (gogoproto.customtype) = "cosmossdk.io/math.Int", - (gogoproto.nullable) = true - ]; - // Native denom for LINK coin in the bank keeper - string link_denom = 7; - // feed administrator - string feed_admin = 8; - // feed billing administrator - string billing_admin = 9; -} -``` - -**Steps** - -- Get previous feed config by `feedId` and ensure it exists -- Ensure `Sender` is feed admin or feed billing admin -- Ensure billing admin is not changing Signers, Transmitters and feed admin -- Process rewards payout for previous feed config -- Delete previous feed transmission and observation counts -- Set latest `EpochAndRound` to `(0, 0)` -- Update signers, transmitters, `LinkPerObservation`, `LinkPerTransmission`, `LinkDenom`, `FeedAdmin`, `BillingAdmin` if set. - -## Msg/Transmit - -`MsgTransmit` is a message to transmit a report for specific feed. When broadcasting the message, there should be enough amount of signatures from observers to be accepted. - -```protobuf -message MsgTransmit { - option (gogoproto.equal) = false; - option (gogoproto.goproto_getters) = false; - // Address of the transmitter - string transmitter = 1; - bytes config_digest = 2; - string feed_id = 3; - uint64 epoch = 4; - uint64 round = 5; - bytes extra_hash = 6; - Report report = 7; - repeated bytes signatures = 8; -} -``` - -**Steps** - -- Get epoch and round for `feedId` -- Ensure that the report is not staled one by checking `msg.Epoch` and `msg.Round` -- Get feed config and config info from `feedId` -- Check msg.ConfigDigest equals to feed config info's latest config digest -- Check if transmitter is valid transmitter configured in `feedConfig` -- Save transmitter report -- Emit event for trasmission -- Validate signatures and the number of signatures -- Increment feed observation and transmission counts - -## Msg/FundFeedRewardPool - -`MsgFundFeedRewardPool` is a message to add funds to feed reward pool to be given to transmitters and observers. - -```protobuf -message MsgFundFeedRewardPool { - option (gogoproto.equal) = false; - option (gogoproto.goproto_getters) = false; - - string sender = 1; - string feed_id = 2; - cosmos.base.v1beta1.Coin amount = 3 [(gogoproto.nullable) = false]; -} -``` - -**Steps** - -- Get previous reward pool amount from `feedId` -- If previous amount is empty, initiate the pool amount with zero integer -- Ensure previous amount denom is not different from deposit denom if exist -- Send coins from account to the module account (`ocr` module) -- Update reward pool amount with `amount` field addition -- Call `AfterFundFeedRewardPool` hook if hooks is set - -## Msg/WithdrawFeedRewardPool - -`MsgFundFeedRewardPool` is a message to withdraw funds from feed reward pool and is restricted to feed admin or billing admin. - -```protobuf -message MsgWithdrawFeedRewardPool { - option (gogoproto.equal) = false; - option (gogoproto.goproto_getters) = false; - - string sender = 1; - string feed_id = 2; - cosmos.base.v1beta1.Coin amount = 3 [(gogoproto.nullable) = false]; -} -``` - -**Steps** - -- Get feed config from `feedId` -- Ensure `msg.Sender` is `feedAdmin` or `billingAdmin` -- Process reward for the feed -- Withdraw specified amount `msg.Amount` from module account - -## Msg/SetPayees - -`MsgSetPayees` is a message to set payee for transmitters - it is restricted to feed admin. Once it's set, it should be changed only by payee. - -```protobuf -message MsgSetPayees { - option (gogoproto.equal) = false; - option (gogoproto.goproto_getters) = false; - - string sender = 1; - string feed_id = 2; - // addresses oracles use to transmit the reports - repeated string transmitters = 3; - // addresses of payees corresponding to list of transmitters - repeated string payees = 4; -} -``` - -**Steps** - -- Get feed config from `feedId` and ensure that feed config exists -- Ensure `msg.Sender` is feed admin -- Iterating `msg.Transmitters`, -- 1. Ensure payee is set already for the transmitter -- 2. Set payee for the transmitter - -## Msg/TransferPayeeship - -`MsgTransferPayeeship` is a message to transfer payeeship for a specific transmitter of feed. After execution, pending payeeship object is created. - -```protobuf -message MsgTransferPayeeship { - option (gogoproto.equal) = false; - option (gogoproto.goproto_getters) = false; - - // transmitter address of oracle whose payee is changing - string sender = 1; - string transmitter = 2; - string feed_id = 3; - // new payee address - string proposed = 4; -} -``` - -**Steps** - -- Get feed config from `feedId` and ensure that feed config exists -- Ensure msg.Sender is current payee -- Check previous pending payeeship transfer record and ensure previous payeeship transfer does not conflict -- Set payeeship transfer record - -## Msg/AcceptPayeeship - -`MsgTransferPayeeship` is a message to accept payeeship for a specific transmitter of feed. - -```protobuf -message MsgAcceptPayeeship { - option (gogoproto.equal) = false; - option (gogoproto.goproto_getters) = false; - // new payee address - string payee = 1; - // transmitter address of oracle whose payee is changing - string transmitter = 2; - string feed_id = 3; -} -``` - -**Steps** - -- Get feed config from `feedId` and ensure that feed config exists -- Get pending payeeship transfer record for `msg.Transmitter` and `feedId` -- Reset payee for `feedId` and `transmitter` -- Delete pending payeeship transfer for `transmitter` of `feedId` diff --git a/.gitbook/developers/modules/injective/ocr/04_proposals.md b/.gitbook/developers/modules/injective/ocr/04_proposals.md deleted file mode 100644 index 787e24ae..00000000 --- a/.gitbook/developers/modules/injective/ocr/04_proposals.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -sidebar_position: 4 -title: Governance Proposals ---- - -# Governance Proposals - -## SetConfigProposal - -`SetConfigProposal` is a proposal to set feed config by governance. - -```protobuf -message SetConfigProposal { - option (gogoproto.equal) = false; - option (gogoproto.goproto_getters) = false; - - string title = 1; - string description = 2; - FeedConfig config = 3; -} -``` - -**Steps** - -- Validate basics for the proposal -- Ensure module's `LinkDenom` is same as proposal's `LinkDenom` -- set `p.Config.OnchainConfig.ChainId` from `ctx.ChainID` -- Set feed config for `feedId` -- Set feed transmissions and observations count for `Config.Transmitters` - -## SetBatchConfigProposal - -`SetBatchConfigProposal` is a proposal to set multiple feed configs at once by governance. - -```protobuf -message SetBatchConfigProposal { - option (gogoproto.equal) = false; - option (gogoproto.goproto_getters) = false; - - string title = 1; - string description = 2; - // signers ith element is address ith oracle uses to sign a report - repeated string signers = 3; - // transmitters ith element is address ith oracle uses to transmit a report via the transmit method - repeated string transmitters = 4; - // Native denom for LINK coin in the bank keeper - string link_denom = 5; - repeated FeedProperties feed_properties = 6; -} -``` diff --git a/.gitbook/developers/modules/injective/ocr/05_begin_block.md b/.gitbook/developers/modules/injective/ocr/05_begin_block.md deleted file mode 100644 index 6c2ed6a8..00000000 --- a/.gitbook/developers/modules/injective/ocr/05_begin_block.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -sidebar_position: 5 -title: Begin-Block ---- - -# Begin-Block - -At each BeginBlock, it checks if it's time for payout interval and if it's time, it process payout for all feeds. - -**Steps** - -- Ensure it's the begin block of payout interval -- While iterating all feed configs, process reward payouts diff --git a/.gitbook/developers/modules/injective/ocr/06_hooks.md b/.gitbook/developers/modules/injective/ocr/06_hooks.md deleted file mode 100644 index c50e2acf..00000000 --- a/.gitbook/developers/modules/injective/ocr/06_hooks.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -sidebar_position: 6 ---- - -# Hooks - -Other modules may register operations to execute when a certain event has occurred within ocr module. The following hooks can registered with ocr: - -- `AfterSetFeedConfig(ctx sdk.Context, feedConfig *FeedConfig)` - - called after feed config is created or updated -- `AfterTransmit(ctx sdk.Context, feedId string, answer math.LegacyDec, timestamp int64)` - - called when info is transmitted -- `AfterFundFeedRewardPool(ctx sdk.Context, feedId string, newPoolAmount sdk.Coin)` - - called when feed reward pool is updated - -Note: -`oracle` module is accepting `AfterTransmit` hook to store cumulative price when transmission is made. \ No newline at end of file diff --git a/.gitbook/developers/modules/injective/ocr/07_events.md b/.gitbook/developers/modules/injective/ocr/07_events.md deleted file mode 100644 index 257d2c97..00000000 --- a/.gitbook/developers/modules/injective/ocr/07_events.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -sidebar_position: 7 -title: Events ---- - -# Events - -The ocr module emits the following events: - -## Handlers - -### MsgCreateFeed - -| Type | Attribute Key | Attribute Value | -| ------- | ------------- | --------------- | -| message | action | MsgCreateFeed | -| message | sender | {sender} | - -### MsgUpdateFeed - -| Type | Attribute Key | Attribute Value | -| ------- | ------------- | --------------- | -| message | action | MsgUpdateFeed | -| message | sender | {sender} | - -### MsgTransmit - -| Type | Attribute Key | Attribute Value | -| -------------------- | --------------------- | ----------------------- | -| EventNewTransmission | FeedId | {FeedId} | -| EventNewTransmission | AggregatorRoundId | {AggregatorRoundId} | -| EventNewTransmission | Answer | {Answer} | -| EventNewTransmission | Transmitter | {Transmitter} | -| EventNewTransmission | ObservationsTimestamp | {ObservationsTimestamp} | -| EventNewTransmission | Observations | {Observations} | -| EventNewTransmission | Observers | {Observers} | -| EventNewTransmission | ConfigDigest | {ConfigDigest} | -| EventNewTransmission | EpochAndRound | {EpochAndRound} | -| EventTransmitted | ConfigDigest | {ConfigDigest} | -| EventTransmitted | Epoch | {Epoch} | -| message | action | MsgTransmit | -| message | sender | {sender} | - -### MsgFundFeedRewardPool - -| Type | Attribute Key | Attribute Value | -| ------- | ------------- | --------------------- | -| message | action | MsgFundFeedRewardPool | -| message | sender | {sender} | - -### MsgWithdrawFeedRewardPool - -| Type | Attribute Key | Attribute Value | -| ------- | ------------- | ------------------------- | -| message | action | MsgWithdrawFeedRewardPool | -| message | sender | {sender} | - -### MsgSetPayees - -| Type | Attribute Key | Attribute Value | -| ------- | ------------- | --------------- | -| message | action | MsgSetPayees | -| message | sender | {sender} | - -### MsgTransferPayeeship - -| Type | Attribute Key | Attribute Value | -| ------- | ------------- | -------------------- | -| message | action | MsgTransferPayeeship | -| message | sender | {sender} | - -### MsgAcceptPayeeship - -| Type | Attribute Key | Attribute Value | -| ------- | ------------- | ------------------ | -| message | action | MsgAcceptPayeeship | -| message | sender | {sender} | - -## Proposals - -### SetConfigProposal - -| Type | Attribute Key | Attribute Value | -| -------------- | ------------------------- | --------------------------- | -| EventConfigSet | ConfigDigest | {ConfigDigest} | -| EventConfigSet | PreviousConfigBlockNumber | {PreviousConfigBlockNumber} | -| EventConfigSet | Config | {Config} | -| EventConfigSet | ConfigInfo | {ConfigInfo} | - -### SetBatchConfigProposal - -| Type | Attribute Key | Attribute Value | -| ---------------- | ------------------------- | --------------------------- | -| EventConfigSet[] | ConfigDigest | {ConfigDigest} | -| EventConfigSet[] | PreviousConfigBlockNumber | {PreviousConfigBlockNumber} | -| EventConfigSet[] | Config | {Config} | -| EventConfigSet[] | ConfigInfo | {ConfigInfo} | - -## BeginBlocker - -| Type | Attribute Key | Attribute Value | -| ---- | ------------- | --------------- | diff --git a/.gitbook/developers/modules/injective/ocr/08_params.md b/.gitbook/developers/modules/injective/ocr/08_params.md deleted file mode 100644 index f78af34e..00000000 --- a/.gitbook/developers/modules/injective/ocr/08_params.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -order: 8 -title: Params ---- - -# Parameters - -The ocr module contains the following parameters: - -| Key | Type | Example | -| ------------------- | ------ | --------- | -| LinkDenom | string | link | -| PayoutBlockInterval | uint64 | 100 | -| ModuleAdmin | string | {address} | diff --git a/.gitbook/developers/modules/injective/ocr/README.md b/.gitbook/developers/modules/injective/ocr/README.md deleted file mode 100644 index 41e1e177..00000000 --- a/.gitbook/developers/modules/injective/ocr/README.md +++ /dev/null @@ -1,21 +0,0 @@ -# Ocr - -## Abstract - -OCR module is to store chainlink's OCR(Off-Chain Report) info into the chain storage. - -Feed configuration is managed by module admin and report move to on-chain by transmitters and observers. -Transmitters and observers are rewarded in LINK token on the chain configured by governance. - -While storing feed information, module provide hooks where oracle module can use for the calculation of cumulative price for futures market. - -## Contents - -1. **[Concepts](01_concepts.md)** -2. **[State](02_state.md)** -3. **[Messages](03_messages.md)** -4. **[Proposals](04_proposals.md)** -5. **[Begin-Block](05_begin_block.md)** -6. **[Hooks](06_hooks.md)** -7. **[Events](07_events.md)** -8. **[Parameters](08_params.md)** diff --git a/.gitbook/developers/modules/injective/oracle/01_state.md b/.gitbook/developers/modules/injective/oracle/01_state.md deleted file mode 100644 index 5a5ed19e..00000000 --- a/.gitbook/developers/modules/injective/oracle/01_state.md +++ /dev/null @@ -1,275 +0,0 @@ ---- -sidebar_position: 1 -title: State ---- - -# State - -## Params -The oracle module parameters. -```protobuf -message Params { - option (gogoproto.equal) = true; - - string pyth_contract = 1; -} -``` - - -## PriceState - -PriceState is common type to manage cumulative price and latest price along with timestamp for all oracle types. - -```protobuf -message PriceState { - string price = 1 [(gogoproto.customtype) = "cosmossdk.io/math.LegacyDec", (gogoproto.nullable) = false]; - - string cumulative_price = 2 [(gogoproto.customtype) = "cosmossdk.io/math.LegacyDec", (gogoproto.nullable) = false]; - - int64 timestamp = 3; -} -``` - -where - -- `Price` represents the normalized decimal price -- `CumulativePrice` represents the cumulative price for a given oracle price feed since the start of the oracle price feed's creation. -- `Timestamp` represents the time at which the blocktime at which the price state was relayed. - -Note that the `CumulativePrice` value follows the convention set by the [Uniswap V2 Oracle](https://uniswap.org/docs/v2/core-concepts/oracles/) and is used to allows modules to calculate Time-Weighted Average Price (TWAP) between 2 arbitrary block time intervals (t1, t2). - -$\mathrm{TWAP = \frac{CumulativePrice_2 - CumulativePrice_1}{Timestamp_2 - Timestamp_1}}$ - -## Band - -Band price data for a given symbol are represented and stored as follows: - -- BandPriceState: `0x01 | []byte(symbol) -> ProtocolBuffer(BandPriceState)` - -```protobuf -message BandPriceState { - string symbol = 1; - string rate = 2 [(gogoproto.customtype) = "cosmossdk.io/math.Int", (gogoproto.nullable) = false]; - uint64 resolve_time = 3; - uint64 request_ID = 4; - PriceState price_state = 5 [(gogoproto.nullable) = false]; -} -``` - -Note that the `Rate` is the raw USD rate for the `Symbol` obtained from the Band chain which has is scaled by 1e9 (e.g. a price of 1.42 is 1420000000) while the PriceState has the normalized decimal price (e.g. 1.42). - -Band relayers are stored by their address as follows. - -- BandRelayer: `0x02 | RelayerAddr -> []byte{}` - -## Band IBC - -This section describes all the state management to maintain the price by connecting to Band chain via IBC. - -- LatestClientID is maintained to manage unique clientID for band IBC packets. It is increased by 1 when sending price request packet into bandchain. - -* LatestClientID: `0x32 -> Formated(LatestClientID)` - -- LatestRequestID is maintained to manage unique `BandIBCOracleRequests`. Incremented by 1 when creating a new `BandIBCOracleRequest`. - -* LatestRequestID: `0x36 -> Formated(LatestRequestID)` - -- Band IBC price data for a given symbol is stored as follows: - -* BandPriceState: `0x31 | []byte(symbol) -> ProtocolBuffer(BandPriceState)` - -```protobuf -message BandPriceState { - string symbol = 1; - string rate = 2 [(gogoproto.customtype) = "cosmossdk.io/math.Int", (gogoproto.nullable) = false]; - uint64 resolve_time = 3; - uint64 request_ID = 4; - PriceState price_state = 5 [(gogoproto.nullable) = false]; -} -``` - -- BandIBCCallDataRecord is stored as follows when sending price request packet into bandchain: - -* CalldataRecord: `0x33 | []byte(ClientId) -> ProtocolBuffer(CalldataRecord)` - -```protobuf -message CalldataRecord { - uint64 client_id = 1; - bytes calldata = 2; -} -``` - -- BandIBCOracleRequest is stored as follows when the governance configure oracle requests to send: - -* BandOracleRequest: `0x34 | []byte(RequestId) -> ProtocolBuffer(BandOracleRequest)` - -```protobuf -message BandOracleRequest { - // Unique Identifier for band ibc oracle request - uint64 request_id = 1; - - // OracleScriptID is the unique identifier of the oracle script to be executed. - int64 oracle_script_id = 2; - - // Symbols is the list of symbols to prepare in the calldata - repeated string symbols = 3; - - // AskCount is the number of validators that are requested to respond to this - // oracle request. Higher value means more security, at a higher gas cost. - uint64 ask_count = 4; - - // MinCount is the minimum number of validators necessary for the request to - // proceed to the execution phase. Higher value means more security, at the - // cost of liveness. - uint64 min_count = 5; - - // FeeLimit is the maximum tokens that will be paid to all data source providers. - repeated cosmos.base.v1beta1.Coin fee_limit = 6 [(gogoproto.nullable) = false, (gogoproto.castrepeated) = "github.com/cosmos/cosmos-sdk/types.Coins"]; - - // PrepareGas is amount of gas to pay to prepare raw requests - uint64 prepare_gas = 7; - // ExecuteGas is amount of gas to reserve for executing - uint64 execute_gas = 8; -} -``` - -- BandIBCParams is stored as follows and configured by governance: - -* BandIBCParams: `0x35 -> ProtocolBuffer(BandIBCParams)` - -`BandIBCParams` contains the information for IBC connection with band chain. - -```protobuf -message BandIBCParams { - // true if Band IBC should be enabled - bool band_ibc_enabled = 1; - // block request interval to send Band IBC prices - int64 ibc_request_interval = 2; - // band IBC source channel - string ibc_source_channel = 3; - // band IBC version - string ibc_version = 4; - // band IBC portID - string ibc_port_id = 5; -} -``` - -Note: - -1. `BandIbcEnabled` describes the status of band ibc connection -2. `IbcSourceChannel`, `IbcVersion`, `IbcPortId` are common parameters required for IBC connection. -3. `IbcRequestInterval` describes the automatic price fetch request interval that is automatically triggered on injective chain on beginblocker. - -## Coinbase - -Coinbase price data for a given symbol ("key") are represented and stored as follows: - -- CoinbasePriceState: `0x21 | []byte(key) -> CoinbasePriceState` - -```protobuf -message CoinbasePriceState { - // kind should always be "prices" - string kind = 1; - // timestamp of the when the price was signed by coinbase - uint64 timestamp = 2; - // the symbol of the price, e.g. BTC - string key = 3; - // the value of the price scaled by 1e6 - uint64 value = 4; - // the price state - PriceState price_state = 5 [(gogoproto.nullable) = false]; -} -``` - -More details about the Coinbase price oracle can be found in the [Coinbase API docs](https://docs.pro.coinbase.com/#oracle) as well as this explanatory [blog post](https://blog.coinbase.com/introducing-the-coinbase-price-oracle-6d1ee22c7068). - -Note that the `Value` is the raw USD price data obtained from Coinbase which has is scaled by 1e6 (e.g. a price of 1.42 is 1420000) while the PriceState has the normalized decimal price (e.g. 1.42). - -## Pricefeed - -Pricefeed price data for a given base quote pair are represented and stored as follows: - -- PriceFeedInfo: `0x11 + Keccak256Hash(base + quote) -> PriceFeedInfo` - -```protobuf -message PriceFeedInfo { - string base = 1; - string quote = 2; -} -``` - -- PriceFeedPriceState: `0x12 + Keccak256Hash(base + quote) -> PriceFeedPriceState` - -```protobuf -message PriceFeedState { - string base = 1; - string quote = 2; - PriceState price_state = 3; - repeated string relayers = 4; -} -``` - -- PriceFeedRelayer: `0x13 + Keccak256Hash(base + quote) + relayerAddr -> relayerAddr` - -## Provider -Provider price feeds are represented and stored as follows: - -- ProviderInfo: `0x61 + provider + @@@ -> ProviderInfo` -```protobuf -message ProviderInfo { - string provider = 1; - repeated string relayers = 2; -} -``` - -- ProviderIndex: `0x62 + relayerAddress -> provider` - -- ProviderPrices: `0x63 + provider + @@@ + symbol -> ProviderPriceState` -```protobuf -message ProviderPriceState { - string symbol = 1; - PriceState state = 2; -} -``` - -## Pyth - -Pyth prices are represented and stored as follows: -- PythPriceState: `0x71 + priceID -> PythPriceState` -```protobuf -message PythPriceState { - bytes price_id = 1; - string ema_price = 2 [(gogoproto.customtype) = "cosmossdk.io/math.LegacyDec", (gogoproto.nullable) = false]; - string ema_conf = 3 [(gogoproto.customtype) = "cosmossdk.io/math.LegacyDec", (gogoproto.nullable) = false]; - string conf = 4 [(gogoproto.customtype) = "cosmossdk.io/math.LegacyDec", (gogoproto.nullable) = false]; - uint64 publish_time = 5; - PriceState price_state = 6 [(gogoproto.nullable) = false]; -} -``` - -## Stork - -Stork prices are represented and stored as follows: -- StorkPriceState: `0x81 + symbol -> PythPriceState` -```protobuf -message StorkPriceState { - // timestamp of the when the price was signed by stork - uint64 timestamp = 1; - // the symbol of the price, e.g. BTC - string symbol = 2; - // the value of the price scaled by 1e18 - string value = 3 [ - (gogoproto.customtype) = "cosmossdk.io/math.LegacyDec", - (gogoproto.nullable) = false - ]; - // the price state - PriceState price_state = 5 [ (gogoproto.nullable) = false ]; -} -``` - -Stork publishers are represented and stored as follows: -- Publisher: `0x82 + stork_publisher -> publisher` - -```protobuf -string stork_publisher -``` \ No newline at end of file diff --git a/.gitbook/developers/modules/injective/oracle/02_keeper.md b/.gitbook/developers/modules/injective/oracle/02_keeper.md deleted file mode 100644 index 32509c5f..00000000 --- a/.gitbook/developers/modules/injective/oracle/02_keeper.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -sidebar_position: 2 -title: Keepers ---- - -# Keepers - -The oracle module currently provides three different exported keeper interfaces which can be passed to other modules -which need to read price feeds. Modules should use the least-permissive interface which provides the functionality they -require. - -## Oracle Module ViewKeeper - -The oracle module ViewKeeper provides the ability to obtain price data as well as cumulative price data for any -supported oracle type and oracle pair. - -```go -type ViewKeeper interface { - GetPrice(ctx sdk.Context, oracletype types.OracleType, base string, quote string) *math.LegacyDec // Returns the price for a given pair for a given oracle type. - GetCumulativePrice(ctx sdk.Context, oracleType types.OracleType, base string, quote string) *math.LegacyDec // Returns the cumulative price for a given pair for a given oracle type. -} -``` - -Note that the `GetPrice` for Coinbase oracles returns the 5 minute TWAP price. - -## Band - -The BandKeeper provides the ability to create/modify/read/delete BandPricefeed and BandRelayer. - -```go -type BandKeeper interface { - GetBandPriceState(ctx sdk.Context, symbol string) *types.BandPriceState - SetBandPriceState(ctx sdk.Context, symbol string, priceState types.BandPriceState) - GetAllBandPriceStates(ctx sdk.Context) []types.BandPriceState - GetBandReferencePrice(ctx sdk.Context, base string, quote string) *math.LegacyDec - IsBandRelayer(ctx sdk.Context, relayer sdk.AccAddress) bool - GetAllBandRelayers(ctx sdk.Context) []string - SetBandRelayer(ctx sdk.Context, relayer sdk.AccAddress) - DeleteBandRelayer(ctx sdk.Context, relayer sdk.AccAddress) -} -``` - -## Band IBC - -The BandIBCKeeper provides the ability to create/modify/read/delete BandIBCOracleRequest, BandIBCPriceState, BandIBCLatestClientID and BandIBCCallDataRecord. - -```go -type BandIBCKeeper interface { - SetBandIBCOracleRequest(ctx sdk.Context, req types.BandOracleRequest) - GetBandIBCOracleRequest(ctx sdk.Context) *types.BandOracleRequest - DeleteBandIBCOracleRequest(ctx sdk.Context, requestID uint64) - GetAllBandIBCOracleRequests(ctx sdk.Context) []*types.BandOracleRequest - - GetBandIBCPriceState(ctx sdk.Context, symbol string) *types.BandPriceState - SetBandIBCPriceState(ctx sdk.Context, symbol string, priceState types.BandPriceState) - GetAllBandIBCPriceStates(ctx sdk.Context) []types.BandPriceState - GetBandIBCReferencePrice(ctx sdk.Context, base string, quote string) *math.LegacyDec - - GetBandIBCLatestClientID(ctx sdk.Context) uint64 - SetBandIBCLatestClientID(ctx sdk.Context, clientID uint64) - SetBandIBCCallDataRecord(ctx sdk.Context, clientID uint64, bandIBCCallDataRecord []byte) - GetBandIBCCallDataRecord(ctx sdk.Context, clientID uint64) *types.CalldataRecord -} -``` - -## Coinbase - -The CoinbaseKeeper provides the ability to create, modify and read CoinbasePricefeed data. - -```go -type CoinbaseKeeper interface { - GetCoinbasePrice(ctx sdk.Context, base string, quote string) *math.LegacyDec - HasCoinbasePriceState(ctx sdk.Context, key string) bool - GetCoinbasePriceState(ctx sdk.Context, key string) *types.CoinbasePriceState - SetCoinbasePriceState(ctx sdk.Context, priceData *types.CoinbasePriceState) error - GetAllCoinbasePriceStates(ctx sdk.Context) []*types.CoinbasePriceState -} -``` - -The `GetCoinbasePrice` returns the 5 minute TWAP price of the CoinbasePriceState based off the `CoinbasePriceState.Timestamp` values provided by Coinbase. - -## PriceFeeder - -The PriceFeederKeeper provides the ability to create/modify/read/delete PriceFeedPrice and PriceFeedRelayer. - -```go -type PriceFeederKeeper interface { - IsPriceFeedRelayer(ctx sdk.Context, oracleBase, oracleQuote string, relayer sdk.AccAddress) bool - GetAllPriceFeedStates(ctx sdk.Context) []*types.PriceFeedState - GetAllPriceFeedRelayers(ctx sdk.Context, baseQuoteHash common.Hash) []string - SetPriceFeedRelayer(ctx sdk.Context, oracleBase, oracleQuote string, relayer sdk.AccAddress) - SetPriceFeedRelayerFromBaseQuoteHash(ctx sdk.Context, baseQuoteHash common.Hash, relayer sdk.AccAddress) - DeletePriceFeedRelayer(ctx sdk.Context, oracleBase, oracleQuote string, relayer sdk.AccAddress) - HasPriceFeedInfo(ctx sdk.Context, priceFeedInfo *types.PriceFeedInfo) bool - GetPriceFeedInfo(ctx sdk.Context, baseQuoteHash common.Hash) *types.PriceFeedInfo - SetPriceFeedInfo(ctx sdk.Context, priceFeedInfo *types.PriceFeedInfo) - GetPriceFeedPriceState(ctx sdk.Context, base string, quote string) *types.PriceState - SetPriceFeedPriceState(ctx sdk.Context, oracleBase, oracleQuote string, priceState *types.PriceState) - GetPriceFeedPrice(ctx sdk.Context, base string, quote string) *math.LegacyDec -} -``` - -## Stork - -The StorkKeeper provides the ability to create/modify/read StorkPricefeed and StorkPublishers data. - -```go -type StorkKeeper interface { - GetStorkPrice(ctx sdk.Context, base string, quote string) *math.LegacyDec - IsStorkPublisher(ctx sdk.Context, address string) bool - SetStorkPublisher(ctx sdk.Context, address string) - DeleteStorkPublisher(ctx sdk.Context, address string) - GetAllStorkPublishers(ctx sdk.Context) []string - - SetStorkPriceState(ctx sdk.Context, priceData *types.StorkPriceState) - GetStorkPriceState(ctx sdk.Context, symbol string) types.StorkPriceState - GetAllStorkPriceStates(ctx sdk.Context) []*types.StorkPriceState -} -``` -The GetStorkPrice returns the price(`value`) of the StorkPriceState. \ No newline at end of file diff --git a/.gitbook/developers/modules/injective/oracle/03_messages.md b/.gitbook/developers/modules/injective/oracle/03_messages.md deleted file mode 100644 index 599e47a3..00000000 --- a/.gitbook/developers/modules/injective/oracle/03_messages.md +++ /dev/null @@ -1,190 +0,0 @@ ---- -sidebar_position: 3 -title: Messages ---- - -# Messages - -## MsgRelayBandRates - -Authorized Band relayers can relay price feed data for multiple symbols with the `MsgRelayBandRates` message. -The registered handler iterates over all the symbols present in the `MsgRelayBandRates` and creates/updates the -`BandPriceState` for each symbol. - -```protobuf -message MsgRelayBandRates { - string relayer = 1; - repeated string symbols = 2; - repeated uint64 rates = 3; - repeated uint64 resolve_times = 4; - repeated uint64 requestIDs = 5; -} -``` - -This message is expected to fail if the Relayer is not an authorized Band relayer. - -## MsgRelayCoinbaseMessages - -Relayers of Coinbase provider can send price data using `MsgRelayCoinbaseMessages` message. - -Each Coinbase `Messages` is authenticated by the `Signatures` provided by the Coinbase oracle address `0xfCEAdAFab14d46e20144F48824d0C09B1a03F2BC`, thus allowing anyone to submit the `MsgRelayCoinbaseMessages`. - -```protobuf -message MsgRelayCoinbaseMessages { - option (gogoproto.equal) = false; - option (gogoproto.goproto_getters) = false; - string sender = 1; - - repeated bytes messages = 2; - repeated bytes signatures = 3; -} -``` - -This message is expected to fail if signature verification fails or if the Timestamp submitted is not more recent than the last previously submitted Coinbase price. - -## MsgRelayPriceFeedPrice - -Relayers of PriceFeed provider can send the price feed using `MsgRelayPriceFeedPrice` message. - -```protobuf -// MsgRelayPriceFeedPrice defines a SDK message for setting a price through the pricefeed oracle. -message MsgRelayPriceFeedPrice { - option (gogoproto.equal) = false; - option (gogoproto.goproto_getters) = false; - string sender = 1; - - repeated string base = 2; - repeated string quote = 3; - - // price defines the price of the oracle base and quote - repeated string price = 4 [ - (gogoproto.customtype) = "cosmossdk.io/math.LegacyDec", - (gogoproto.nullable) = false - ]; -} -``` - -This message is expected to fail if the Relayer (`Sender`) is not an authorized pricefeed relayer for the given Base Quote pair or if the price is greater than 10000000. - -## MsgRequestBandIBCRates - -`MsgRequestBandIBCRates` is a message to instantly broadcast a request to bandchain. - -```protobuf -// MsgRequestBandIBCRates defines a SDK message for requesting data from BandChain using IBC. -message MsgRequestBandIBCRates { - option (gogoproto.equal) = false; - option (gogoproto.goproto_getters) = false; - - string sender = 1; - uint64 request_id = 2; - -} -``` - -Anyone can broadcast this message and no specific authorization is needed. -The handler checks if `BandIbcEnabled` flag is true and go ahead sending a request. - -## MsgRelayPythPrices - -`MsgRelayPythPrices` is a message for the Pyth contract relay prices to the oracle module. - -```protobuf -// MsgRelayPythPrices defines a SDK message for updating Pyth prices -message MsgRelayPythPrices { - option (gogoproto.equal) = false; - option (gogoproto.goproto_getters) = false; - - string sender = 1; - repeated PriceAttestation price_attestations = 2; -} - -message PriceAttestation { - string product_id = 1; - bytes price_id = 2; - int64 price = 3; - uint64 conf = 4; - int32 expo = 5; - int64 ema_price = 6; - uint64 ema_conf = 7; - PythStatus status = 8; - uint32 num_publishers = 9; - uint32 max_num_publishers = 10; - int64 attestation_time = 11; - int64 publish_time = 12; -} - -enum PythStatus { - // The price feed is not currently updating for an unknown reason. - Unknown = 0; - // The price feed is updating as expected. - Trading = 1; - // The price feed is not currently updating because trading in the product has been halted. - Halted = 2; - // The price feed is not currently updating because an auction is setting the price. - Auction = 3; -} -``` - -This message is expected to fail if the Relayer (`sender`) does not equal the Pyth contract address as defined in the -oracle module Params. - -## MsgRelayStorkPrices - -`MsgRelayStorkPrices` is a message for the Stork contract relay prices to the oracle module. - -```protobuf -// MsgRelayStorkPrices defines a SDK message for relaying price message from Stork API. -message MsgRelayStorkPrices { - option (gogoproto.equal) = false; - option (gogoproto.goproto_getters) = false; - option (cosmos.msg.v1.signer) = "sender"; - - string sender = 1; - repeated AssetPair asset_pairs = 2; -} - -message AssetPair { - string asset_id = 1; - repeated SignedPriceOfAssetPair signed_prices = 2; -} - -message SignedPriceOfAssetPair { - string publisher_key = 1; - uint64 timestamp = 2; - string price = 3 [ - (gogoproto.customtype) = "cosmossdk.io/math.LegacyDec", - (gogoproto.nullable) = false - ]; - bytes signature = 4; -} -``` - -This message is expected to fail if: -- the Relayer (`sender`) is not an authorized oracle publisher or if `assetId` is not unique amongst the provided asset pairs -- ECDSA signature verification fails for the `SignedPriceOfAssetPair` -- the difference between timestamps exceeds the `MaxStorkTimestampIntervalNano` (500 milliseconds). - -## MsgRelayProviderPrices - -Relayers of a particular Provider can send the price feed using `MsgRelayProviderPrices` message. - -```protobuf -// MsgRelayProviderPrice defines a SDK message for setting a price through the provider oracle. -message MsgRelayProviderPrices { - option (amino.name) = "oracle/MsgRelayProviderPrices"; - option (gogoproto.equal) = false; - option (gogoproto.goproto_getters) = false; - option (cosmos.msg.v1.signer) = "sender"; - - string sender = 1; - string provider = 2; - repeated string symbols = 3; - repeated string prices = 4 [ - (gogoproto.customtype) = "cosmossdk.io/math.LegacyDec", - (gogoproto.nullable) = false - ]; -} -``` - -This message is expected to fail if the Relayer (`Sender`) is not an authorized pricefeed relayer for the given Base Quote pair or if the price is greater than 10000000. diff --git a/.gitbook/developers/modules/injective/oracle/04_proposals.md b/.gitbook/developers/modules/injective/oracle/04_proposals.md deleted file mode 100644 index 82488e8c..00000000 --- a/.gitbook/developers/modules/injective/oracle/04_proposals.md +++ /dev/null @@ -1,227 +0,0 @@ ---- -sidebar_position: 4 -title: Governance Proposals ---- - -# Governance Proposals - -## GrantProviderPrivilegeProposal - -Oracle provider privileges can be granted to your account through a `GrantBandOraclePrivilegeProposal`. After the governance proposal is passed, you will be able to relay price feeds using your provider. - - -```protobuf -// Grant Privileges -message GrantProviderPrivilegeProposal { - option (amino.name) = "oracle/GrantProviderPrivilegeProposal"; - option (gogoproto.equal) = false; - option (gogoproto.goproto_getters) = false; - - option (cosmos_proto.implements_interface) = "cosmos.gov.v1beta1.Content"; - - string title = 1; - string description = 2; - string provider = 3; - repeated string relayers = 4; -} -``` - -You can submit your proposal according to the example: - -```bash -injectived tx oracle grant-provider-privilege-proposal YOUR_PROVIDER \ - YOUR_ADDRESS_HERE \ - --title="TITLE OF THE PROPOSAL" \ - --description="Registering PROVIDER as an oracle provider" \ - --chain-id=injective-888 \ - --from=local_key \ - --node=https://testnet.sentry.tm.injective.network:443 \ - --gas-prices=160000000inj \ - --gas=20000000 \ - --deposit="40000000000000000000inj" -``` - - -To successfully pass the proposal for **testnet**, `YOUR_DEPOSIT` should be slightly less than `min_deposit` -value (for example, `40000000000000000000inj`). After that you should contact the Injective dev team. Dev team will -top up your deposit to `min_deposit` and vote for your proposal. - -## RevokeProviderPrivilegeProposal - -Oracle provider privileges can be revoked from your account through a `RevokeProviderPrivilegeProposal`. - -```protobuf -// Revoke Privileges -message RevokeProviderPrivilegeProposal { - option (amino.name) = "oracle/RevokeProviderPrivilegeProposal"; - option (gogoproto.equal) = false; - option (gogoproto.goproto_getters) = false; - - option (cosmos_proto.implements_interface) = "cosmos.gov.v1beta1.Content"; - - string title = 1; - string description = 2; - string provider = 3; - repeated string relayers = 5; -} -``` - -## GrantBandOraclePrivilegeProposal - -Band Oracle privileges can be granted to Relayer accounts of Band provider through a `GrantBandOraclePrivilegeProposal`. - -```protobuf -// Grant Privileges -message GrantBandOraclePrivilegeProposal { - option (gogoproto.equal) = false; - option (gogoproto.goproto_getters) = false; - - string title = 1; - string description = 2; - repeated string relayers = 3; -} -``` - -## RevokeBandOraclePrivilegeProposal - -Band Oracle privileges can be revoked from Relayer accounts of Band provider through a `RevokeBandOraclePrivilegeProposal`. - -```protobuf -// Revoke Privileges -message RevokeBandOraclePrivilegeProposal { - option (gogoproto.equal) = false; - option (gogoproto.goproto_getters) = false; - - string title = 1; - string description = 2; - repeated string relayers = 3; -} -``` - -## GrantPriceFeederPrivilegeProposal - -Price feeder privileges for a given base quote pair can be issued to relayers through a `GrantPriceFeederPrivilegeProposal`. - -```protobuf -// Grant Privileges -message GrantPriceFeederPrivilegeProposal { - option (gogoproto.equal) = false; - option (gogoproto.goproto_getters) = false; - - string title = 1; - string description = 2; - string base = 3; - string quote = 4; - repeated string relayers = 5; -} -``` - -## RevokePriceFeederPrivilegeProposal - -Price feeder privileges can be revoked from Relayer accounts through a `RevokePriceFeederPrivilegeProposal`. - -```protobuf -// Revoke Privileges -message RevokePriceFeederPrivilegeProposal { - option (gogoproto.equal) = false; - option (gogoproto.goproto_getters) = false; - - string title = 1; - string description = 2; - string base = 3; - string quote = 4; - repeated string relayers = 5; -} -``` - -## AuthorizeBandOracleRequestProposal - -This proposal is to add a band oracle request into the list. When this is accepted, injective chain fetches one more price info from bandchain. - -```protobuf -message AuthorizeBandOracleRequestProposal { - option (gogoproto.equal) = false; - option (gogoproto.goproto_getters) = false; - - string title = 1; - string description = 2; - BandOracleRequest request = 3 [(gogoproto.nullable) = false]; -} -``` - -## UpdateBandOracleRequestProposal - -This proposal is used for deleting a request or updating the request. -When `DeleteRequestId` is not zero, it deletes the request with the id and finish its execution. -When `DeleteRequestId` is zero, it update the request with id `UpdateOracleRequest.RequestId` to UpdateOracleRequest. - -```protobuf -message UpdateBandOracleRequestProposal { - option (gogoproto.equal) = false; - option (gogoproto.goproto_getters) = false; - - string title = 1; - string description = 2; - uint64 delete_request_id = 3; - BandOracleRequest update_oracle_request = 4; -} -``` - -## EnableBandIBCProposal - -This proposal is to enable IBC connection between Band chain and Injective chain. -When the proposal is approved, it updates the BandIBCParams into newer one configured on the proposal. - -```protobuf -message EnableBandIBCProposal { - option (gogoproto.equal) = false; - option (gogoproto.goproto_getters) = false; - - string title = 1; - string description = 2; - - BandIBCParams band_ibc_params = 3 [(gogoproto.nullable) = false]; -} -``` - -The details of `BandIBCParams`, can be checked at **[State](./01_state.md)** - -## GrantStorkPublisherPrivilegeProposal - -Stork Publisher privileges can be granted from Publishers through a `GrantStorkPublisherPrivilegeProposal`. - -```protobuf -// Grant Privileges -message GrantStorkPublisherPrivilegeProposal { - option (amino.name) = "oracle/GrantStorkPublisherPrivilegeProposal"; - option (gogoproto.equal) = false; - option (gogoproto.goproto_getters) = false; - - option (cosmos_proto.implements_interface) = "cosmos.gov.v1beta1.Content"; - - string title = 1; - string description = 2; - - repeated string stork_publishers = 3; -} -``` - -## RevokeStorkPublisherPrivilegeProposal - -Stork Publisher privileges can be revoked from Publishers through a `RevokeStorkPublisherPrivilegeProposal`. - -```protobuf -// Revoke Privileges -message RevokeStorkPublisherPrivilegeProposal { - option (amino.name) = "oracle/RevokeStorkPublisherPrivilegeProposal"; - option (gogoproto.equal) = false; - option (gogoproto.goproto_getters) = false; - - option (cosmos_proto.implements_interface) = "cosmos.gov.v1beta1.Content"; - - string title = 1; - string description = 2; - - repeated string stork_publishers = 3; -} -``` \ No newline at end of file diff --git a/.gitbook/developers/modules/injective/oracle/05_events.md b/.gitbook/developers/modules/injective/oracle/05_events.md deleted file mode 100644 index ea883770..00000000 --- a/.gitbook/developers/modules/injective/oracle/05_events.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -sidebar_position: 5 -title: Events ---- -# Events - -The oracle module emits the following events: -## Band -```protobuf -message SetBandPriceEvent { - string relayer = 1; - string symbol = 2; - string price = 3 [(gogoproto.customtype) = "cosmossdk.io/math.LegacyDec", (gogoproto.nullable) = false]; - uint64 resolve_time = 4; - uint64 request_id = 5; -} - -message SetBandIBCPriceEvent { - string relayer = 1; - repeated string symbols = 2; - repeated string prices = 3 [(gogoproto.customtype) = "cosmossdk.io/math.LegacyDec", (gogoproto.nullable) = false]; - uint64 resolve_time = 4; - uint64 request_id = 5; - int64 client_id = 6; -} - -message EventBandIBCAckSuccess { - string ack_result = 1; - int64 client_id = 2; -} - -message EventBandIBCAckError { - string ack_error = 1; - int64 client_id = 2; -} - -message EventBandIBCResponseTimeout { - int64 client_id = 1; -} -``` - -## Chainlink -```protobuf -message SetChainlinkPriceEvent { - string feed_id = 1; - string answer = 2 [(gogoproto.customtype) = "cosmossdk.io/math.LegacyDec", (gogoproto.nullable) = false]; - uint64 timestamp = 3; -} -``` - -## Coinbase - -```protobuf -message SetCoinbasePriceEvent { - string symbol = 1; - string price = 2 [(gogoproto.customtype) = "cosmossdk.io/math.LegacyDec", (gogoproto.nullable) = false]; - uint64 timestamp = 3; -} -``` - -## Provider -```protobuf -message SetProviderPriceEvent { - string provider = 1; - string relayer = 2; - string symbol = 3; - string price = 4 [(gogoproto.customtype) = "cosmossdk.io/math.LegacyDec", (gogoproto.nullable) = false]; -} -``` - -## Pricefeed -```protobuf -message SetPriceFeedPriceEvent { - string relayer = 1; - - string base = 2; - string quote = 3; - - // price defines the price of the oracle base and quote - string price = 4 [(gogoproto.customtype) = "cosmossdk.io/math.LegacyDec", (gogoproto.nullable) = false]; -} -``` - -## Pyth -```protobuf -message EventSetPythPrices { - repeated PythPriceState prices = 1; -} -``` - -## Stork -```protobuf -message EventSetStorkPrices { - repeated StorkPriceState prices = 1; -} -``` \ No newline at end of file diff --git a/.gitbook/developers/modules/injective/oracle/06_future_improvements.md b/.gitbook/developers/modules/injective/oracle/06_future_improvements.md deleted file mode 100644 index 60b92334..00000000 --- a/.gitbook/developers/modules/injective/oracle/06_future_improvements.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -sidebar_position: 6 -title: Future Improvements ---- - -# Future Improvements - -Extend support for other oracle providers including Chainlink, Razor, DIA, API3, UMA, Pyth as well as Band oracle data through IBC. - -Of the following above, development is ongoing to integrate Band and Pyth oracle data through IBC, as well as Chainlink oracle data through the OCR (off-chain reporting) mechanism. diff --git a/.gitbook/developers/modules/injective/oracle/README.md b/.gitbook/developers/modules/injective/oracle/README.md deleted file mode 100644 index f30bd028..00000000 --- a/.gitbook/developers/modules/injective/oracle/README.md +++ /dev/null @@ -1,39 +0,0 @@ -# `Oracle` - -## Abstract - -This specification specifies the oracle module, which is primarily used by the `exchange` modules to obtain external price data. - -## Workflow - -1. New price feed providers must first obtain oracle privileges through a governance proposal which grants privileges to a list of relayers. The exception to this is for the Coinbase price oracle, as anyone can send Coinbase price updates since they are already exclusively signed by the Coinbase oracle private key.
- **Example Grant Proposals**: `GrantBandOraclePrivilegeProposal`, `GrantPriceFeederPrivilegeProposal` -2. Once the governance proposal is approved, the specified relayers can publish oracle data by sending relay messages specific to their oracle type.
- **Example Relay Messages**:`MsgRelayBandRates`, `MsgRelayPriceFeedPrice`, `MsgRelayCoinbaseMessages` etc -3. Upon receiving the relay message, the oracle module checks if the relayer account has grant privileges and persists the latest price data in the state. -4. Other Cosmos-SDK modules can then fetch the latest price data for a specific provider by querying the oracle module. - -**Note**: In case of any discrepancy, the price feed privileges can be revoked through governance
-**Example Revoke Proposals**: `RevokeBandOraclePrivilegeProposal`, `RevokePriceFeederPrivilegeProposal` etc - -## Band IBC integration flow - -Cosmos SDK blockchains are able to interact with each other using IBC and Injective support the feature to fetch price feed from bandchain via IBC. - -1. To communicate with BandChain's oracle using IBC, Injective Chain must first initialize a communication channel with the oracle module on the BandChain using relayers. - -2. Once the connection has been established, a pair of channel identifiers is generated -- one for the Injective Chain and one for Band. The channel identifier is used by Injective Chain to route outgoing oracle request packets to Band. Similarly, Band's oracle module uses the channel identifier when sending back the oracle response. - -3. To enable band IBC integration after setting up communication channel, the governance proposal for `EnableBandIBCProposal` should pass. - -4. And then, the list of prices to be fetched via IBC should be determined by `AuthorizeBandOracleRequestProposal` and `UpdateBandOracleRequestProposal`. - -5. Once BandIBC is enabled, chain periodically sends price request IBC packets (`OracleRequestPacketData`) to bandchain and bandchain responds with the price via IBC packet (`OracleResponsePacketData`). Band chain is providing prices when there are threshold number of data providers confirm and it takes time to get the price after sending requests. To request price before the configured interval, any user can broadcast `MsgRequestBandIBCRates` message which is instantly executed. - -## Contents - -1. **[State](./01_state.md)** -2. **[Keeper](./02_keeper.md)** -3. **[Messages](./03_messages.md)** -4. **[Proposals](./04_proposals.md)** -5. **[Events](./05_events.md)** diff --git a/.gitbook/developers/modules/injective/peggy/01_definitions.md b/.gitbook/developers/modules/injective/peggy/01_definitions.md deleted file mode 100644 index 037c1da0..00000000 --- a/.gitbook/developers/modules/injective/peggy/01_definitions.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -sidebar_position: 1 -title: Definitions ---- - -# Intro - -This doc aims to provide an overview of `Peggy` (Injective's Ethereum bridge) from a technical perspective and dive deep into its operational logic. -Peggy is the name of the custom Cosmos SDK module built on Injective as well as the Ethereum contract (Peggy.sol) which make up both sides of the bridge. -Connected via a middle-man process called `Peggo` users can securely move token assets between networks. - -To suggest improvements, please open a GitHub issue. - -### Key definitions - -Words matter and we seek clarity in the terminology so we can have clarity in our thinking and communication. -To help better understand, some key definitions are: - -- `Operator` - this is a person (or people) who control and operate `Validator` and `Orchestrator` processes -- `Validator` - this is an Injective Chain validating node (eg. `injectived` process) -- `Validator Set` - the (active) set of Injective Chain `Validators` (Valset) along with their respective voting power as determined by their stake weight. Each validator is associated with an Ethereum address to be represented on the Ethereum network -- `Orchestrator (Peggo)` - the off-chain process (`peggo`) that plays the middleman role between Injective and Ethereum. Orchestrators are responsible for keeping the bridge online and require active endpoints to fully synced Injective (Ethereum) nodes -- `Peggy module` - the counterparty Cosmos module for `Peggy contract`. Besides providing services to bridge token assets, it automatically reflects on the active `Validator Set` as it changes over time. The update is later applied on Ethereum via `Peggo` -- `Peggy Contract` - The Ethereum contract that holds all the ERC-20 tokens. It also maintains a compressed checkpointed representation of the Injective Chain `Validator Set` using `Delegate Keys` and normalized powers -- `Delegate Keys` - when an `Operator` sets up their `Orchestrator` for the first time they register (on Injective) their `Validator`'s address with an Ethereum address. The corresponding key is used to sign messages and represent that validator on Ethereum. - Optionally, one delegate Injective Chain account key can be provided to sign Injective messages (eg `Claims`) on behalf of the `Validator` -- `Peggy Tx pool (withdrawals)` - when a user wishes to move their asset from Injective to Ethereum their individual tx gets pooled with others with the same asset -- `Peggy Batch pool` - pooled withdrawals are batched together (by an `Orchestrator`) to be signed off and eventually relayed to Ethereum. These batches are kept within this pool -- `Claim` - a signed proof (by an `Orchestrator`) that an event occurred in the `Peggy contract` -- `Attestation` - an aggregate of claims for a particular event nonce emitted from `Peggy contract`. After a majority of `Orchestrators` attests to a claim, the event is acknowledged and executed on Injective -- `Majority` - the majority of Injective network, 2/3 + 1 validators -- `Deposit` - an asset transfer initiated from Ethereum to Injective -- `Withdrawal` - an asset transfer initiated from Injective to Ethereum (present in `Peggy Tx pool`) -- `Batch` - a batch of withdrawals with the same token type (present in `Peggy Batch pool`) - - diff --git a/.gitbook/developers/modules/injective/peggy/02_workflow.md b/.gitbook/developers/modules/injective/peggy/02_workflow.md deleted file mode 100644 index 2a7b4742..00000000 --- a/.gitbook/developers/modules/injective/peggy/02_workflow.md +++ /dev/null @@ -1,164 +0,0 @@ ---- -sidebar_position: 2 -title: Workflow ---- - -# Workflow - -## Conceptual Overview - -To recap, each `Operator` is responsible for maintaining 2 secure processes: - -1. A fully synced Injective Chain `Validator` node (`injectived` process) -2. The `Orchestrator` service (`peggo orchestrator` process) which interacts with both networks. Implicitly, an RPC endpoint to a fully synced Ethereum node is required as well (see peggo .env example) - -Combined, these 2 entities accomplish 3 things: -- Move token assets from Ethereum to Injective -- Move token assets from Injective to Ethereum -- Keep the `Peggy.sol` contract in sync with the active `Validator Set` on Injective - -It is possible to run `peggo` without ever being a `Validator`. Peggo automatically runs in "relayer mode" when configured to run with an address **not associated** with a `Validator`. -In this mode, only 2 things can happen: -* new token batches can be created on Injective -* confirmed valsets/batches can be relayed to Ethereum - -## Types of Assets - -### Native Ethereum assets - -Any asset originating from Ethereum which implements the ERC-20 standard can be transferred from Ethereum to Injective by calling the `sendToInjective` function on the [Peggy.sol](https://github.com/InjectiveLabs/peggo/blob/master/solidity/contracts/Peggy.sol) contract which transfers tokens from the sender's balance to the Peggy contract. - -The `Operators` all run their `peggo` processes which submit `MsgDepositClaim` messages describing the deposit they have observed. Once more than 66% of all voting power has submitted a claim for this specific deposit representative tokens are minted and issued to the Injective Chain address that the sender requested. - -These representative tokens have a denomination prefix of `peggy` concatenated with the ERC-20 token hex address, e.g. `peggy0xdac17f958d2ee523a2206206994597c13d831ec7`. - -### Native Cosmos SDK assets - -An asset native to a Cosmos SDK chain (e.g. `ATOM`) first must be represented on Ethereum before it's possible to bridge it. To do so, the [Peggy contract](https://github.com/InjectiveLabs/peggo/blob/master/solidity/contracts/Peggy.sol) allows anyone to create a new ERC-20 token representing a Cosmos asset by calling the `deployERC20` function. - -This endpoint is not permissioned, so it is up to the validators and the users of the Peggy bridge to declare any given ERC-20 token as the representation of a given asset. - -When a user on Ethereum calls `deployERC20` they pass arguments describing the desired asset. [Peggy.sol](https://github.com/InjectiveLabs/peggo/blob/master/solidity/contracts/Peggy.sol) uses an ERC-20 factory to deploy the actual ERC-20 contract and assigns ownership of the entire balance of the new token to the Peggy contract itself before emitting an `ERC20DeployedEvent`. - -The peggo orchestrators observe this event and decide if a Cosmos asset has been accurately represented (correct decimals, correct name, no pre-existing representation). If this is the case, the ERC-20 contract address is adopted and stored as the definitive representation of that Cosmos asset on Ethereum. - -## `Orchestrator` (Peggo) subprocesses - -The `peggo orchestrator` process consists of 4 subprocesses running concurrently at exact intervals (loops). These are: -* `Signer` which signs new `Validator Set` updates and `Token Batches` with the `Operator`'s Ethereum keys and submits using [messages](./04_messages.md#Ethereum-Signer-messages). -* `Oracle` which observes Ethereum events and sends them as [claims](./04_messages.md#Oracle-messages) to Injective. -* `Relayer` which submits confirmed `Validator Set` updates and `Token Batches` to the `Peggy Contract` on Ethereum -* `Batch Creator` which observes (new) withdrawals on Injective and decides which of these to batch according to their type and the configured `PEGGO_MIN_BATCH_FEE_USD` value - -### Batch Creator - -The purpose of the `Batch Creator` is only in creating token batches on the Injective side. The relevant `Peggy module` RPC is not permissioned so anyone can create a batch. - -When a user wants to withdraw assets from Injective to Ethereum they send a special message to Injective (`MsgSendToEth`) which adds their withdrawal to `Peggy Tx Pool`. -`Batch Creator` continually queries the pool for withdrawals (by token type) and issues a `MsgRequestBatch` to Injective when a potential batch satisfies the configured `PEGGO_MIN_BATCH_FEE_USD` value (see .env example). - -On the receiving end, all pooled withdrawals matching the token type in the request are moved from the `Outgoing Tx Pool` as a single batch and placed in the `Outgoing Batch Pool`. - -### Signer - -The responsibility of Signer is to provide confirmations that an `Operator (Orchestrator)` is partaking in bridge activity. Failure to provide these confirmations results in slashing penalties for the orchestrator's `Validator`. -In other words, this process **must be running at all times** for a `Validator` node. - -Any payload moving in the Injective->Ethereum pipeline (`Validator Set` updates/`Token Batches`) requires `Validator` signatures to be successfully relayed to Ethereum. Certain calls on `Peggy Contract` accept an array of signatures to be checked against the `Validator Set` in the contract itself. -`Orchestrators` make these signatures with their `Delegate Ethereum address`: this is an Ethereum address decided by the `Operator` upon initial setup ([SetOrchestratorAddress](./04_messages.md#setorchestratoraddresses)). This address then represents that validator on the Ethereum blockchain and will be added as a signing member of the multisig with a weighted voting power as close as possible to the Injective Chain voting power. - -Whenever `Signer` finds that there is a unconfirmed valset update (token batch) present within the `Peggy Module` it issues a `MsgConfirmValset` (`MsgConfirmBatch`) as proof that the operating `Validator` is active in bridge activity. - -### Oracle - -Monitors the Ethereum network for new events involving the `Peggy Contract`. - -Every event emitted by the contract has a unique event nonce. This nonce value is crucial in coordinating `Orchestrators` to properly observe contract activity and make sure Injective acknowledges them via `Claims`. -Multiple claims of the same nonce make up an `Attestation` and when the majority (2/3) of orchestrators have observed an event its particular logic gets executed on Injective. - -If 2/3 of the validators can not agree on a single `Attestation`, the oracle is halted. This means no new events will be relayed from Ethereum until some of the validators change their votes. There is no slashing condition for this, with reasoning outlined in the [slashing spec](./05_slashing.md) - -There are 4 types of events emitted from Peggy.sol: -1. `TransactionBatchExecutedEvent` - event indicating that a token batch (withdrawals) has been successfully relayed to Ethereum -2. `ValsetUpdatedEvent` - event indicating that a `Validator Set` update has been successfully relayed to Ethereum -3. `SendToInjectiveEvent` - event indicating that a new deposit to Injective has been initiated -4. `ERC20DeployedEvent` - event indicating a new Cosmos token has been registered on Ethereum - -Injective's `Oracle` implementation ignores the last 12 blocks on Ethereum to ensure block finality. In reality, this means latest events are observed 2-3 minutes after they occurred. - -### Relayer - -`Relayer` bundles valset updates (or token batches) along with their confirmations into an Ethereum transaction and sends it to the `Peggy contract`. - -Keep in mind that these messages cost a variable amount of money based on wildly changing Ethereum gas prices, so it's not unreasonable for a single batch to cost over a million gas. -A major design decision for our relayer rewards was to always issue them on the Ethereum chain. This has downsides, namely some strange behavior in the case of validator set update rewards. - -But the upsides are undeniable, because the Ethereum messages pay `msg.sender` any existing bot in the Ethereum ecosystem will pick them up and try to submit them. This makes the relaying market much more competitive and less prone to cabal like behavior. - -## End-to-end Lifecycle - -This document describes the end to end lifecycle of the Peggy bridge. - -### Peggy Smart Contract Deployment - -In order to deploy the Peggy contract, the validator set of the native chain (Injective Chain) must be known. Upon deploying the Peggy contract suite (Peggy Implementation, Proxy contract, and ProxyAdmin contracts), the Peggy contract (the Proxy contract) must be initialized with the validator set. -Upon initialization a `ValsetUpdatedEvent` is emitted from the contract. - -The proxy contract is used to upgrade Peggy Implementation contract which is needed for bug fixing and potential improvements during initial phase. It is a simple wrapper or "proxy" which users interact with directly and is in charge of forwarding transactions to the Peggy implementation contract, which contains the logic. The key concept to understand is that the implementation contract can be replaced but the proxy (the access point) is never changed. - -The ProxyAdmin is a central admin for the Peggy proxy, which simplifies management. It controls upgradability and ownership transfers. The ProxyAdmin contract itself has a built-in expiration time which, once expired, prevents the Peggy implementation contract from being upgraded in the future. - -Then the following peggy genesis params should be updated: -1. `bridge_ethereum_address` with Peggy proxy contract address -2. `bridge_contract_start_height` with the height at which the Peggy proxy contract was deployed - -This completes the bootstrap of the Peggy bridge and the chain can be started. Afterward, `Operators` should start their `peggo` processes and eventually observe that the initial `ValsetUpdatedEvent` is attested on Injective. - -### **Updating Injective Chain validator set on Ethereum** - -![img.png](./images/valsetupdate.png) - -A validator set is a series of Ethereum addresses with attached normalized powers used to represent the Injective validator set (Valset) in the Peggy contract on Ethereum. The Peggy contract stays in sync with the Injective Chain validator set through the following mechanism: -1. **Creating a new Valset on Injective:** A new Valset is automatically created on the Injective Chain when either: - * the cumulative difference of the current validator set powers compared to the last recorded Valset exceeds 5% - * a validator begins unbonding from the set -2. **Confirming a Valset on Injective:** Each `Operator` is responsible for confirming Valset updates that are created on Injective. The `Signer` process sends these confirmations via `MsgConfirmValset` by having the validator's delegated Ethereum key sign over a compressed representation of the Valset data. The `Peggy module` verifies the validity of the signature and persists it to its state. -3. **Updating the Valset on the Peggy contract:** After a 2/3+ 1 majority of validators have submitted their confirmations for a given Valset, `Relayer` submits the new Valset data to the Peggy contract by calling `updateValset`. -The Peggy contract then validates the data, updates the valset checkpoint, transfers valset rewards to sender and emits a `ValsetUpdatedEvent`. -4. **Acknowledging the `ValsetUpdatedEvent` on Injective:** `Oracle` witnesses the `ValsetUpdatedEvent` on Ethereum, and sends a `MsgValsetUpdatedClaim` which informs the `Peggy module` that the Valset has been updated on Ethereum. -5. **Pruning Valsets on Injective:** Once a 2/3 majority of validators send their claim for a given `ValsetUpdateEvent`, all the previous valsets are pruned from the `Peggy module` state. -6. **Validator Slashing:** Validators are subject to slashing after a configured window of time (`SignedValsetsWindow`) for not providing confirmations. Read more [valset slashing](./05_slashing.md) - ----- - -### **Transferring ERC-20 tokens from Ethereum to Injective** - -![img.png](./images/SendToCosmos.png) - -ERC-20 tokens are transferred from Ethereum to Injective through the following mechanism: - 1. **Depositing ERC-20 tokens on the Peggy Contract:** A user initiates a transfer of ERC-20 tokens from Ethereum to Injective by calling the `sendToInjective` function on the Peggy contract which deposits tokens on the Peggy contract and emits a `SendToInjectiveEvent`. - The deposited tokens will remain locked until withdrawn at some undetermined point in the future. This event contains the amount and type of tokens, as well as a destination address on the Injective Chain to receive the funds. - - 2. **Confirming the deposit:** Each `Oracle` witnesses the `SendToInjectiveEvent` and sends a `MsgDepositClaim` which contains the deposit information to the Peggy module. - - 3. **Minting tokens on the Injective:** Once a majority of validators confirm the deposit claim, the deposit is processed. - - If the asset is Ethereum originated, the tokens are minted and transferred to the intended recipient's address on the Injective Chain. - - If the asset is Cosmos-SDK originated, the coins are unlocked and transferred to the intended recipient's address on the Injective Chain. - ------ -### **Withdrawing tokens from Injective to Ethereum** - -![img.png](./images/SendToEth.png) - -1. **Request Withdrawal from Injective:** A user can initiate the transfer of assets from the Injective Chain to Ethereum by sending a `MsgSendToEth` transaction to the peggy module. - * If the asset is Ethereum native, the represented tokens are burnt. - * If the asset is Cosmos SDK native, coins are locked in the module. The withdrawal is then added to `Outgoing Tx Pool`. -2. **Batch Creation:** A `Batch Creator` observes the pool of pending withdrawals. The batch creator (or any external third party) then requests a batch of to be created for given token by sending `MsgRequestBatch` to the Injective Chain. The `Peggy module` collects withdrawals matching the token type into a batch and puts it in `Outgoing Batch Pool`. -3. **Batch Confirmation:** Upon detecting the existence of an Outgoing Batch, the `Signer` signs over the batch with its Ethereum key and submits a `MsgConfirmBatch` tx to the Peggy module. -4. **Submit Batch to Peggy Contract:** Once a majority of validators confirm the batch, the `Relayer` calls `submitBatch` on the Peggy contract with the batch and its confirmations. The Peggy contract validates the signatures, updates the batch checkpoint, processes the batch ERC-20 withdrawals, transfers the batch fee to the tx sender and emits a `TransactionBatchExecutedEvent`. -5. **Send Withdrawal Claim to Injective:** `Oracles` witness the `TransactionBatchExecutedEvent` and send a `MsgWithdrawClaim` containing the withdrawal information to the Peggy module. -6. **Prune Batches** Once a majority of validators submit their `MsgWithdrawClaim` , the batch is deleted along and all previous batches are cancelled on the Peggy module. Withdrawals in cancelled batches get moved back into `Outgoing Tx Pool`. -7. **Batch Slashing:** Validators are responsible for confirming batches and are subject to slashing if they fail to do so. Read more on [batch slashing](./05_slashing.md). - -Note while that batching reduces individual withdrawal costs dramatically, this comes at the cost of latency and implementation complexity. If a user wishes to withdraw quickly they will have to pay a much higher fee. However this fee will be about the same as the fee every withdrawal from the bridge would require in a non-batching system. - diff --git a/.gitbook/developers/modules/injective/peggy/03_state.md b/.gitbook/developers/modules/injective/peggy/03_state.md deleted file mode 100644 index e589efe6..00000000 --- a/.gitbook/developers/modules/injective/peggy/03_state.md +++ /dev/null @@ -1,265 +0,0 @@ ---- -sidebar_position: 3 -title: State ---- - -# State - -This doc lists all the data Peggy module reads/writes to its state as KV pairs - -### Module Params - -Params is a module-wide configuration structure that stores parameters and defines overall functioning of the peggy module. Detailed specification for each parameter can be found in the [Parameters section](08_params.md). - -| key | Value | Type | Encoding | -|---------------|---------------|----------------|------------------| -| `[]byte{0x4}` | Module params | `types.Params` | Protobuf encoded | - - -### Validator Info - -#### Ethereum Address by Validator - -Stores `Delegate Ethereum address` indexed by the `Validator`'s account address - -| key | Value | Type | Encoding | -|---------------------------------------|------------------|------------------|------------------| -| `[]byte{0x1} + []byte(validatorAddr)` | Ethereum address | `common.Address` | Protobuf encoded | - -#### Validator by Ethereum Address - -Stores `Validator` account address indexed by the `Delegate Ethereum address` - -| key | Value | Type | Encoding | -|-------------------------------------|-------------------|------------------|------------------| -| `[]byte{0xfb} + []byte(ethAddress)` | Validator address | `sdk.ValAddress` | Protobuf encoded | - - -#### OrchestratorValidator - -When a validator would like to delegate their voting power to another key. The value is stored using the orchestrator address as the key - -| Key | Value | Type | Encoding | -|-------------------------------------|----------------------------------------------|----------|------------------| -| `[]byte{0xe8} + []byte(AccAddress)` | Orchestrator address assigned by a validator | `[]byte` | Protobuf encoded | - - -### Valset - -This is the validator set of the bridge. Created automatically by `Peggy module` during EndBlocker. - -Stored in two possible ways, first with a height and second without (unsafe). Unsafe is used for testing and export and import of state. - -```go -type Valset struct { - Nonce uint64 - Members []*BridgeValidator - Height uint64 - RewardAmount math.Int - RewardToken string -} - -``` - -| key | Value | Type | Encoding | -|--------------------------------------------|---------------|----------------|------------------| -| `[]byte{0x2} + nonce (big endian encoded)` | Validator set | `types.Valset` | Protobuf encoded | - -### SlashedValsetNonce - -The latest validator set slash nonce. This is used to track which validator set needs to be slashed and which already has been. - -| Key | Value | Type | Encoding | -|----------------|-------|--------|------------------------| -| `[]byte{0xf5}` | Nonce | uint64 | encoded via big endian | - -### ValsetNonce - -Nonce of the latest validator set. Updated on each new validator set. - -| key | Value | Type | Encoding | -|----------------|-------|----------|------------------------| -| `[]byte{0xf6}` | Nonce | `uint64` | encoded via big endian | - - -### Valset Confirmation - -`Singer` confirmation for a particular validator set. See [oracle messages](./04_messages.md#ValsetConfirm) - -| Key | Value | Type | Encoding | -|---------------------------------------------|------------------------|--------------------------|------------------| -| `[]byte{0x3} + (nonce + []byte(AccAddress)` | Validator Confirmation | `types.MsgValsetConfirm` | Protobuf encoded | - -### Batch Confirmation - -`Singer` confirmation for a particular token batch. See [oracle messages](./04_messages.md#ConfirmBatch) - -| Key | Value | Type | Encoding | -|---------------------------------------------------------------------|------------------------------|-------------------------|------------------| -| `[]byte{0xe1} + []byte(tokenContract) + nonce + []byte(AccAddress)` | Validator Batch Confirmation | `types.MsgConfirmBatch` | Protobuf encoded | - - -### OutgoingTransferTx - -User withdrawals are pooled together in `Peggy Tx Pool` ready to be batched later by a `Batch Creator`. - -Each withdrawal is indexed by a unique nonce set by the `Peggy module` when the withdrawal was received. - -```go -type OutgoingTransferTx struct { - Id uint64 - Sender string - DestAddress string - Erc20Token *ERC20Token - Erc20Fee *ERC20Token -} -``` - -| Key | Value | Type | Encoding | -|----------------------------------------|------------------------------|----------|--------------------| -| `[]byte{0x7} + []byte("lastTxPoolId")` | nonce of outgoing withdrawal | `uint64` | Big endian encoded | - - -### LastTXPoolID - -Monotonically increasing value for each withdrawal received by Injective - -| Key | Value | Type | Encoding | -|----------------------------------------|-------------------------|----------|--------------------| -| `[]byte{0x6} + []byte("lastTxPoolId")` | Last used withdrawal ID | `uint64` | Big endian encoded | - - -### OutgoingTxBatch - -`OutgoingTxBatch` represents a collection of withdrawals of the same token type. Created on every successful `MsgRequestBatch`. - -Stored in two possible ways, first with a height and second without (unsafe). Unsafe is used for testing and export and import of state. -Currently [Peggy.sol](https://github.com/InjectiveLabs/peggo/blob/master/solidity/contracts/Peggy.sol) is hardcoded to only accept batches with a single token type and only pay rewards in that same token type. - -```go -type OutgoingTxBatch struct { - BatchNonce uint64 - BatchTimeout uint64 - Transactions []*OutgoingTransferTx - TokenContract string - Block uint64 -} -``` - -| key | Value | Type | Encoding | -|--------------------------------------------------------------------|----------------------------------|-------------------------|------------------| -| `[]byte{0xa} + []byte(tokenContract) + nonce (big endian encoded)` | A batch of outgoing transactions | `types.OutgoingTxBatch` | Protobuf encoded | -| `[]byte{0xb} + block (big endian encoded)` | A batch of outgoing transactions | `types.OutgoingTxBatch` | Protobuf encoded | - - -### LastOutgoingBatchID - -Monotonically increasing value for each batch created on Injective by some `Batch Creator` - -| Key | Value | Type | Encoding | -|---------------------------------------|--------------------|----------|--------------------| -| `[]byte{0x7} + []byte("lastBatchId")` | Last used batch ID | `uint64` | Big endian encoded | - -### SlashedBlockHeight - -Represents the latest slashed block height. There is always only a singe value stored. - -| Key | Value | Type | Encoding | -|----------------|-----------------------------------------|----------|--------------------| -| `[]byte{0xf7}` | Latest height a batch slashing occurred | `uint64` | Big endian encoded | - -### LastUnbondingBlockHeight - -Represents the latest bloch height at which a `Validator` started unbonding from the `Validator Set`. Used to determine slashing conditions. - -| Key | Value | Type | Encoding | -|----------------|------------------------------------------------------|----------|--------------------| -| `[]byte{0xf8}` | Latest height at which a Validator started unbonding | `uint64` | Big endian encoded | - -### TokenContract & Denom - -A denom that is originally from a counter chain will be from a contract. The token contract and denom are stored in two ways. First, the denom is used as the key and the value is the token contract. Second, the contract is used as the key, the value is the denom the token contract represents. - -| Key | Value | Type | Encoding | -|----------------------------------------|------------------------|----------|-----------------------| -| `[]byte{0xf3} + []byte(denom)` | Token contract address | `[]byte` | stored in byte format | -| `[]byte{0xf4} + []byte(tokenContract)` | Token denom | `[]byte` | stored in byte format | - -### LastObservedValset - -This entry represents the last observed Valset that was successfully relayed to Ethereum. Updates after an attestation of `ValsetUpdatedEvent` has been processed on Injective. - -| Key | Value | Type | Encoding | -|----------------|----------------------------------|----------------|------------------| -| `[]byte{0xfa}` | Last observed Valset on Ethereum | `types.Valset` | Protobuf encoded | - - -### LastEventNonce - -The nonce of the last observed event on Ethereum. This is set when `TryAttestation()` is called. There is always only a single value held in this store. - -| Key | Value | Type | Encoding | -|----------------|---------------------------|----------|--------------------| -| `[]byte{0xf2}` | Last observed event nonce | `uint64` | Big endian encoded | - -### LastObservedEthereumHeight - -This block height of the last observed event on Ethereum. There will always only be a single value stored in this store. - -| Key | Value | Type | Encoding | -|----------------|-------------------------------|----------|------------------| -| `[]byte{0xf9}` | Last observed Ethereum Height | `uint64` | Protobuf encoded | - - -### LastEventByValidator - -This is the last observed event on Ethereum from a particular `Validator`. Updated every time the asssociated `Orchestrator` sends an event claim. - -```go -type LastClaimEvent struct { - EthereumEventNonce uint64 - EthereumEventHeight uint64 -} -``` - -| Key | Value | Type | Encoding | -|--------------------------------------------|---------------------------------------|------------------------|------------------| -| `[]byte{0xf1} + []byte(validator address)` | Last observed event by some Validator | `types.LastClaimEvent` | Protobuf encoded | - - -### Attestation - -Attestation is an aggregate of claims that eventually becomes observed by all orchestrators as more votes (claims) are coming in. Once observed the claim's particular logic gets executed. - -Each attestation is bound to a unique event nonce (generated by `Peggy contract`) and they must be processed in order. This is a correctness issue, if relaying out of order transaction replay attacks become possible. - -```go -type Attestation struct { - Observed bool - Votes []string - Height uint64 - Claim *types.Any -} -``` -| Key | Value | Type | Encoding | -|----------------------------------------------------------------------|---------------------------------------|---------------------|------------------| -| `[]byte{0x5} + event nonce (big endian encoded) + []byte(claimHash)` | Attestation of occurred events/claims | `types.Attestation` | Protobuf encoded | - -### PastEthSignatureCheckpoint - -A computed hash indicating that a validator set/token batch in fact existed on Injective. This checkpoint also exists in `Peggy contract`. -Updated on each new valset update and token batch creation. - - -| Key | Value | Type | Encoding | -|----------------|-------------------------------------------|-------------------|----------------------| -| `[]byte{0x1b}` | Last created checkpoint hash on Injective | `gethcommon.Hash` | store in byte format | - -### EthereumBlacklist - -A list of known malicious Ethereum addresses that are prevented from using the bridge. - -| Key | Value | Type | Encoding | -|-------------------------------------------|--------------------|-------------------|------------------------| -| `[]byte{0x1c} + []byte(ethereum address)` | Empty []byte slice | `gethcommon.Hash` | stored in byte format] | - diff --git a/.gitbook/developers/modules/injective/peggy/04_messages.md b/.gitbook/developers/modules/injective/peggy/04_messages.md deleted file mode 100644 index d2f14516..00000000 --- a/.gitbook/developers/modules/injective/peggy/04_messages.md +++ /dev/null @@ -1,199 +0,0 @@ ---- -sidebar_position: 4 -title: Messages ---- - -# Messages - -This is a reference document for Peggy message types. For code reference and exact arguments see the [proto definitions](https://github.com/InjectiveLabs/injective-core/blob/master/proto/injective/peggy/v1/msgs.proto). - -## User messages - -These are messages sent on the Injective Chain peggy module by the end user. See [workflow](./02_workflow.md) for a more detailed summary of the entire deposit and withdraw process. - -### SendToEth - -Sent to Injective whenever a user wishes to make a withdrawal back to Ethereum. Submitted amount is removed from the user's balance immediately. -The withdrawal is added to the outgoing tx pool as a `types.OutgoingTransferTx` where it will remain until it is included in a batch. - -```go -type MsgSendToEth struct { - Sender string // sender's Injective address - EthDest string // receiver's Ethereum address - Amount types.Coin // amount of tokens to bridge - BridgeFee types.Coin // additional fee for bridge relayers. Must be of same token type as Amount -} - -``` - -### CancelSendToEth - -This message allows the user to cancel a specific withdrawal that is not yet batched. User balance is refunded (`Amount` + `BridgeFee`). - -```go -type MsgCancelSendToEth struct { - TransactionId uint64 // unique tx nonce of the withdrawal - Sender string // original sender of the withdrawal -} - -``` - -### SubmitBadSignatureEvidence - -This call allows anyone to submit evidence that a validator has signed a valset or batch that never existed. Subject contains the batch or valset. - -```go -type MsgSubmitBadSignatureEvidence struct { - Subject *types1.Any - Signature string - Sender string -} -``` - -## Batch Creator Messages - -These messages are sent by the `Batch Creator` subprocess of `peggo` - -### RequestBatch - -This message is sent whenever some `Batch Creator` finds pooled withdrawals that when batched would satisfy their minimum batch fee (`PEGGO_MIN_BATCH_FEE_USD`). -After receiving this message the `Peggy module` collects all withdrawals of the requested token denom, creates a unique token batch (`types.OutgoingTxBatch`) and places it in the `Outgoing Batch pool`. -Withdrawals that are batched cannot be cancelled with `MsgCancelSendToEth`. - - -```go -type MsgRequestBatch struct { - Orchestrator string // orchestrator address interested in creating the batch. Not permissioned. - Denom string // the specific token whose withdrawals will be batched together -} -``` - - -## Oracle Messages - -These messages are sent by the `Oracle` subprocess of `peggo` - -### DepositClaim - -Sent to Injective when a `SendToInjectiveEvent` is emitted from the `Peggy contract`. -This occurs whenever a user is making an individual deposit from Ethereum to Injective. - -```go -type MsgDepositClaim struct { - EventNonce uint64 // unique nonce of the event - BlockHeight uint64 // Ethereum block height at which the event was emitted - TokenContract string // contract address of the ERC20 token - Amount sdkmath.Int // amount of deposited tokens - EthereumSender string // sender's Ethereum address - CosmosReceiver string // receiver's Injective address - Orchestrator string // address of the Orchestrator which observed the event -} -``` - -### WithdrawClaim - -Sent to Injective when a `TransactionBatchExecutedEvent` is emitted from the `Peggy contract`. -This occurs when a `Relayer` has successfully called `submitBatch` on the contract to complete a batch of withdrawals. - -```go -type MsgWithdrawClaim struct { - EventNonce uint64 // unique nonce of the event - BlockHeight uint64 // Ethereum block height at which the event was emitted - BatchNonce uint64 // nonce of the batch executed on Ethereum - TokenContract string // contract address of the ERC20 token - Orchestrator string // address of the Orchestrator which observed the event -} -``` - -### ValsetUpdatedClaim - -Sent to Injective when a `ValsetUpdatedEvent` is emitted from the `Peggy contract`. -This occurs when a `Relayer` has successfully called `updateValset` on the contract to update the `Validator Set` on Ethereum. - -```go - -type MsgValsetUpdatedClaim struct { - EventNonce uint64 // unique nonce of the event - ValsetNonce uint64 // nonce of the valset - BlockHeight uint64 // Ethereum block height at which the event was emitted - Members []*BridgeValidator // members of the Validator Set - RewardAmount sdkmath.Int // Reward for relaying the valset update - RewardToken string // reward token contract address - Orchestrator string // address of the Orchestrator which observed the event -} -``` - -### ERC20DeployedClaim - -Sent to Injective when a `ERC20DeployedEvent` is emitted from the `Peggy contract`. -This occurs whenever the `deployERC20` method is called on the contract to issue a new token asset eligible for bridging. - -```go -type MsgERC20DeployedClaim struct { - EventNonce uint64 // unique nonce of the event - BlockHeight uint64 // Ethereum block height at which the event was emitted - CosmosDenom string // denom of the token - TokenContract string // contract address of the token - Name string // name of the token - Symbol string // symbol of the token - Decimals uint64 // number of decimals the token has - Orchestrator string // address of the Orchestrator which observed the event -} -``` - - -## Signer Messages - -These messages are sent by the `Signer` subprocess of `peggo` - -### ConfirmBatch - -When `Signer` finds a batch that the `Orchestrator` (`Validator`) has not signed off, it constructs a signature with its `Delegated Ethereum Key` and sends the confirmation to Injective. -It's crucial that a `Validator` eventually provides their confirmation for a created batch as they will be slashed otherwise. - -```go -type MsgConfirmBatch struct { - Nonce uint64 // nonce of the batch - TokenContract string // contract address of batch token - EthSigner string // Validator's delegated Ethereum address (previously registered) - Orchestrator string // address of the Orchestrator confirming the batch - Signature string // Validator's signature of the batch -} -``` - -### ValsetConfirm - -When `Signer` finds a valset update that the `Orchestrator` (`Validator`) has not signed off, it constructs a signature with its `Delegated Ethereum Key` and sends the confirmation to Injective. -It's crucial that a `Validator` eventually provides their confirmation for a created valset update as they will be slashed otherwise. - -```go -type MsgValsetConfirm struct { - Nonce uint64 // nonce of the valset - Orchestrator string // address of the Orchestrator confirming the valset - EthAddress string // Validator's delegated Ethereum address (previously registered) - Signature string // Validator's signature of the valset -} -``` - -## Relayer Messages - -The `Relayer` does not send any message to Injective, rather it constructs Ethereum transactions with Injective data to update the `Peggy contract` via `submitBatch` and `updateValset` methods. - -## Validator Messages - -These are messages sent directly using the validator's message key. - -### SetOrchestratorAddresses - -Sent to Injective by an `Operator` managing a `Validator` node. Before being able to start their `Orchestrator` (`peggo`) process, they must register a chosen Ethereum address to represent their `Validator` on Ethereum. -Optionally, an additional Injective address can be provided (`Orchestrator` field) to represent that `Validator` in the bridging process (`peggo`). Defaults to `Validator`'s own address if omitted. - -```go -type MsgSetOrchestratorAddresses struct { - Sender string // address of the Injective validator - Orchestrator string // optional Injective address to represent the Validator in the bridging process (Defaults to Sender if left empty) - EthAddress string // the Sender's (Validator) delegated Ethereum address -} -``` -This message sets the Orchestrator's delegate keys. - diff --git a/.gitbook/developers/modules/injective/peggy/05_slashing.md b/.gitbook/developers/modules/injective/peggy/05_slashing.md deleted file mode 100644 index 41d2fa40..00000000 --- a/.gitbook/developers/modules/injective/peggy/05_slashing.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -sidebar_position: 5 -title: Slashing ---- - -# Slashing -### Security Concerns - -The **Validator Set** is the actual set of keys with stake behind them, which are slashed for double-signs or other -misbehavior. We typically consider the security of a chain to be the security of a _Validator Set_. This varies on -each chain, but is our gold standard. Even IBC offers no more security than the minimum of both involved Validator Sets. - -The **Eth bridge relayer** is a binary run alongside the main `injectived` daemon by the validator set. It exists purely as a matter of code organization and is in charge of signing Ethereum transactions, as well as observing events on Ethereum and bringing them into the Injective Chain state. It signs transactions bound for Ethereum with an Ethereum key, and signs over events coming from Ethereum with an Injective Chain account key. We can add slashing conditions to any mis-signed message by any _Eth Signer_ run by the _Validator Set_ and be able to provide the same security as the _Validator Set_, just a different module detecting evidence of malice and deciding how much to slash. If we can prove a transaction signed by any _Eth Signer_ of the _Validator Set_ was illegal or malicious, then we can slash on the Injective Chain side and potentially provide 100% of the security of the _Validator Set_. Note that this also has access to the 3 week unbonding period to allow evidence to slash even if they immediately unbond. - -Below are various slashing conditions we use in Peggy. - -## PEGGYSLASH-01: Signing fake validator set or tx batch evidence - -This slashing condition is intended to stop validators from signing over a validator set and nonce that has never existed on the Injective Chain. It works via an evidence mechanism, where anyone can submit a message containing the signature of a validator over a fake validator set. This is intended to produce the effect that if a cartel of validators is formed with the intention of submitting a fake validator set, one defector can cause them all to be slashed. -```go -// This call allows anyone to submit evidence that a -// validator has signed a valset, batch, or logic call that never -// existed. Subject contains the batch, valset, or logic call. -type MsgSubmitBadSignatureEvidence struct { - Subject *types1.Any - Signature string - Sender string -} -``` -**Implementation considerations:** - -The trickiest part of this slashing condition is determining that a validator set has never existed on Injective. To save space, we will need to clean up old validator sets. We could keep a mapping of validator set hash to true in the KV store, and use that to check if a validator set has ever existed. This is more efficient than storing the whole validator set, but its growth is still unbounded. It might be possible to use other cryptographic methods to cut down on the size of this mapping. It might be OK to prune very old entries from this mapping, but any pruning reduces the deterrence of this slashing condition. - -The implemented version of this slashing condition stores a map of hashes for all past events, this is smaller than storing entire batches or validator sets and doesn't have to be accessed as frequently. A possible but not currently implemented efficiency optimization would be to remove hashes from this list after a given period. But this would require storing more metadata about each hash. - -Currently automatic evidence submission is not implemented in the relayer. By the time a signature is visible on Ethereum it's already too late for slashing to prevent bridge highjacking or theft of funds. Furthermore since 66% of the validator set is required to perform this action anyways that same controlling majority could simply refuse the evidence. The most common case envisioned for this slashing condition is to break up a cabal of validators trying to take over the bridge by making it more difficult for them to trust one another and actually coordinate such a theft. - -The theft would involve exchanging of slashable Ethereum signatures and open up the possibility of a manual submission of this message by any defector in the group. - -Currently this is implemented as an ever growing array of hashes in state. - -## PEGGYSLASH-02: Failure to sign tx batch - -This slashing condition is triggered when a validator does not sign a transaction batch within `SignedBatchesWindow` upon it's creation by the Peggy module. This prevents two bad scenarios- - -1. A validator simply does not bother to keep the correct binaries running on their system, -2. A cartel of >1/3 validators unbond and then refuse to sign updates, preventing any batches from getting enough signatures to be submitted to the Peggy Ethereum contract. - -## PEGGYSLASH-03: Failure to sign validator set update - -This slashing condition is triggered when a validator does not sign a validator set update which is produced by the Peggy module. This prevents two bad scenarios- - -1. A validator simply does not bother to keep the correct binaries running on their system, -2. A cartel of >1/3 validators unbond and then refuse to sign updates, preventing any validator set updates from getting enough signatures to be submitted to the Peggy Ethereum contract. If they prevent validator set updates for longer than the Injective Chain unbonding period, they can no longer be punished for submitting fake validator set updates and tx batches (PEGGYSLASH-01 and PEGGYSLASH-03). - -To deal with scenario 2, PEGGYSLASH-03 will also need to slash validators who are no longer validating, but are still in the unbonding period for up to `UnbondSlashingValsetsWindow` blocks. This means that when a validator leaves the validator set, they will need to keep running their equipment for at least `UnbondSlashingValsetsWindow` blocks. This is unusual for the Injective Chain, and may not be accepted by the validators. - -The current value of `UnbondSlashingValsetsWindow` is 25,000 blocks, or about 12-14 hours. We have determined this to be a safe value based on the following logic. So long as every validator leaving the validator set signs at least one validator set update that they are not contained in then it is guaranteed to be possible for a relayer to produce a chain of validator set updates to transform the current state on the chain into the present state. - -It should be noted that both PEGGYSLASH-02 and PEGGYSLASH-03 could be eliminated with no loss of security if it where possible to perform the Ethereum signatures inside the consensus code. This is a pretty limited feature addition to Tendermint that would make Peggy far less prone to slashing. - -## PEGGYSLASH-04: Submitting incorrect Eth oracle claim (Disabled for now) - -The Ethereum oracle code (currently mostly contained in attestation.go), is a key part of Peggy. It allows the Peggy module to have knowledge of events that have occurred on Ethereum, such as deposits and executed batches. PEGGYSLASH-03 is intended to punish validators who submit a claim for an event that never happened on Ethereum. - -**Implementation considerations** - -The only way we know whether an event has happened on Ethereum is through the Ethereum event oracle itself. So to implement this slashing condition, we slash validators who have submitted claims for a different event at the same nonce as an event that was observed by >2/3s of validators. - -Although well-intentioned, this slashing condition is likely not advisable for most applications of Peggy. This is because it ties the functioning of the Injective Chain which it is installed on to the correct functioning of the Ethereum chain. If there is a serious fork of the Ethereum chain, different validators behaving honestly may see different events at the same event nonce and be slashed through no fault of their own. Widespread unfair slashing would be very disruptive to the social structure of the Injective Chain. - -Maybe PEGGYSLASH-04 is not necessary at all: - -The real utility of this slashing condition is to make it so that, if >2/3 of the validators form a cartel to all submit a fake event at a certain nonce, some number of them can defect from the cartel and submit the real event at that nonce. If there are enough defecting cartel members that the real event becomes observed, then the remaining cartel members will be slashed by this condition. However, this would require >1/2 of the cartel members to defect in most conditions. - -If not enough of the cartel defects, then neither event will be observed, and the Ethereum oracle will just halt. This is a much more likely scenario than one in which PEGGYSLASH-04 is actually triggered. - -Also, PEGGYSLASH-04 will be triggered against the honest validators in the case of a successful cartel. This could act to make it easier for a forming cartel to threaten validators who do not want to join. - -## PEGGYSLASH-05: Failure to submit Eth oracle claims (Disabled for now) - -This is similar to PEGGYSLASH-04, but it is triggered against validators who do not submit an oracle claim that has been observed. In contrast to PEGGYSLASH-04, PEGGYSLASH-05 is intended to punish validators who stop participating in the oracle completely. - -**Implementation considerations** - -Unfortunately, PEGGYSLASH-05 has the same downsides as PEGGYSLASH-04 in that it ties the correct operation of the Injective Chain to the Ethereum chain. Also, it likely does not incentivize much in the way of correct behavior. To avoid triggering PEGGYSLASH-05, a validator simply needs to copy claims which are close to becoming observed. This copying of claims could be prevented by a commit-reveal scheme, but it would still be easy for a "lazy validator" to simply use a public Ethereum full node or block explorer, with similar effects on security. Therefore, the real usefulness of PEGGYSLASH-05 is likely minimal - -PEGGYSLASH-05 also introduces significant risks. Mostly around forks on the Ethereum chain. For example recently OpenEthereum failed to properly handle the Berlin hardfork, the resulting node 'failure' was totally undetectable to automated tools. It didn't crash so there was no restart to perform, blocks where still being produced although extremely slowly. If this had occurred while Peggy was running with PEGGYSLASH-05 active it would have caused those validators to be removed from the set. Possibly resulting in a very chaotic moment for the chain as dozens of validators where removed for little to no fault of their own. - -Without PEGGYSLASH-04 and PEGGYSLASH-05, the Ethereum event oracle only continues to function if >2/3 of the validators voluntarily submit correct claims. Although the arguments against PEGGYSLASH-04 and PEGGYSLASH-05 are convincing, we must decide whether we are comfortable with this fact. Alternatively we must be comfortable with the Injective Chain potentially halting entirely due to Ethereum generated factors. - diff --git a/.gitbook/developers/modules/injective/peggy/06_end_block.md b/.gitbook/developers/modules/injective/peggy/06_end_block.md deleted file mode 100644 index 40bcae02..00000000 --- a/.gitbook/developers/modules/injective/peggy/06_end_block.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -sidebar_position: 5 -title: End-Block ---- - -# EndBlocker - -Upon the end of each block the following operations are performed to the state of the module - -## 1. Slashing - -### Validator slashing - -A validator is slashed for not signing over a valset update which passed the `SignedValsetsWindow`. -In other words, if a validator fails to provide the confirmation for a valset update within a preconfigured amount of time, they will be slashed for `SlashFractionValset` portion of their stake and get jailed immediately. - -### Batch Slashing - -A validator is slashed for not signing over a batch which passed the `SignedBatchesWindow`. -In other words, if a validator fails to provide the confirmation for a batch within a preconfigured amount of time, they will be slashed for `SlashFractionBatch` portion of their stake and get jailed immediately. - -## 2. Cancelling timed out batches - -Any batch still present in the `Outgoing Batch pool` whose `BatchTimeout` (a designated Ethereum height by which the batch should have executed) is exceeded gets removed from the pool and the withdrawals are reinserted back into the `Outgoing Tx pool`. - -## 3. Creating new Valset updates - -A new `Validator Set` update will be created automatically when: -* there is a power diff greater than 5% between the latest and current validator set -* a validator begins unbonding - -The new validator set is eventually relayed to `Peggy contract` on Ethereum. - -## 4. Pruning old validator sets - -Previously observed valsets that passed the `SignedValsetsWindow` are removed from the state - -## 5. Attestation processing - -Processes all attestations (an aggregate of claims for a particular event) currently being voted on. Each attestation is processed one by one to ensure each `Peggy contract` event is processed. -After each processed attestation the module's `lastObservedEventNonce` and `lastObservedEthereumBlockHeight` are updated. - -Depending on the type of claim in the attestation, the following is executed: -* `MsgDepositClaim`: deposited tokens are minted/unlocked for the receiver address -* `MsgWithdrawClaim`: corresponding batch is removed from the outgoing pool and any previous batch is cancelled -* `MsgValsetUpdatedClaim`: the module's `LastObservedValset` is updated -* `MsgERC20DeployedClaim`: new token metadata is validated and registered within the module's state (`denom <-> token_contract`) - -## 6. Cleaning up processed attestations - -Previously processed attestations (height earlier that `lastObservedEthereumBlockHeight`) are removed from the module state diff --git a/.gitbook/developers/modules/injective/peggy/07_events.md b/.gitbook/developers/modules/injective/peggy/07_events.md deleted file mode 100644 index 68ea6656..00000000 --- a/.gitbook/developers/modules/injective/peggy/07_events.md +++ /dev/null @@ -1,143 +0,0 @@ ---- -sidebar_position: 7 -title: Events ---- - -# Events - -The peggy module emits the following events: - -## EndBlocker - -### EventAttestationObserved -| Type | Attribute Key | Attribute Value | -|--------|------------------|---------------------------| -| int32 | attestation_type | {attestation_type} | -| string | bridge_contract | {bridge_contract_address} | -| uint64 | bridge_chain_id | {bridge_chain_id} | -| []byte | attestation_id | {attestation_id} | -| uint64 | nonce | {event_nonce} | - -### EventValidatorSlash -| Type | Attribute Key | Attribute Value | -|--------|-------------------|-----------------------| -| string | reason | {reason_for_slashing} | -| int64 | power | {validator_power} | -| string | consensus_address | {consensus_addr} | -| string | operator_address | {operator_addr} | -| string | moniker | {validator_moniker} | - - -## Handler - -### EventSetOrchestratorAddresses - -| Type | Attribute Key | Attribute Value | -|--------|----------------------|---------------------| -| string | validator_address | {validator_addr} | -| string | orchestrator_address | {orchestrator_addr} | -| string | operator_eth_address | {eth_addr} | - -### EventSendToEth - -| Type | Attribute Key | Attribute Value | -|----------|----------------|-----------------| -| message | outgoing_tx_id | {tx_id} | -| string | sender | {sender_addr} | -| string | receiver | {dest_addr} | -| sdk.Coin | amount | {token_amount} | -| sdk.Coin | bridge_fee | {token_amount} | - - -### EventBridgeWithdrawCanceled -| Type | Attribute Key | Attribute Value | -|----------------------|-----------------|-------------------| -| withdrawal_cancelled | bridge_contract | {bridge_contract} | -| withdrawal_cancelled | bridge_chain_id | {bridge_chain_id} | - - -### EventOutgoingBatch - -| Type | Attribute Key | Attribute Value | -|----------|----------------------|-----------------| -| string | denom | {token_denom} | -| string | orchestrator_address | {orch_addr} | -| uint64 | batch_nonce | {batch_nonce} | -| uint64 | batch_timeout | {block_height} | -| []uint64 | batch_tx_ids | {ids} | - -### EventOutgoingBatchCanceled -| Type | Attribute Key | Attribute Value | -|--------|-----------------|-------------------| -| string | bridge_contract | {bridge_contract} | -| uint64 | bridge_chain_id | {bridge_chain_id} | -| uint64 | batch_id | {id} | -| uint64 | nonce | {nonce} | - -### EventValsetConfirm - -| Type | Attribute Key | Attribute Value | -|--------|----------------------|-----------------| -| uint64 | valset_nonce | {nonce} | -| string | orchestrator_address | {prch_addr} | - - -### EventConfirmBatch - -| Type | Attribute Key | Attribute Value | -|--------|----------------------|-----------------| -| uint64 | batch_nonce | {nonce} | -| string | orchestrator_address | {orch_addr} | - -### EventDepositClaim - -| Type | Attribute Key | Attribute Value | -|---------|----------------------|-------------------| -| uint64 | event_nonce | {event_nonce} | -| uint64 | event_height | {event_height} | -| []byte | attestation_id | {attestation_key} | -| string | ethereum_sender | {sender_addr} | -| string | cosmos_receiver | {receiver_addr} | -| string | token_contract | {contract_addr} | -| sdk.Int | amount | {token_amount} | -| string | orchestrator_address | {orch_addr} | -| string | data | {custom_data} | - - -### EventWithdrawClaim - -| Type | Attribute Key | Attribute Value | -|--------|----------------------|-------------------| -| uint64 | event_nonce | {event_nonce{ | -| uint64 | event_height | {event_height} | -| []byte | attestation_id | {attestation_key} | -| uint64 | batch_nonce | {batch_nonce} | -| string | token_contract | {contract_addr} | -| string | orchestrator_address | {orch_addr} | - -### EventERC20DeployedClaim -| Type | Attribute Key | Attribute Value | -|--------|----------------------|------------------------| -| uint64 | event_nonce | {event_nonce} | -| uint64 | event_height | {event_height} | -| []byte | attestation_id | {attestation_key} | -| string | cosmos_denom | {token_denom} | -| string | token_contract | {token_conntract_addr} | -| string | name | {token_name} | -| string | symbol | {token_symbol} | -| uint64 | decimals | {token_decimals} | -| string | orchestrator_address | {orch_addr} | - -### EventValsetUpdateClaim -| Type | Attribute Key | Attribute Value | -|--------------------|----------------------|-----------------------| -| uint64 | event_nonce | {event_nonce} | -| uint64 | event_height | {event_height} | -| []byte | attestation_id | {attestation_key} | -| uint64 | valset_nonce | {valset_nonce} | -| []*BridgeValidator | valset_members | {array_of_validators} | -| sdk.Int | reward_amount | {amount} | -| string | reward_token | {contract_addr} | -| string | orchestrator_address | {orch_addr} | - - diff --git a/.gitbook/developers/modules/injective/peggy/08_params.md b/.gitbook/developers/modules/injective/peggy/08_params.md deleted file mode 100644 index d76128cc..00000000 --- a/.gitbook/developers/modules/injective/peggy/08_params.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -sidebar_position: 8 -title: Parameters ---- - -# Params - -This document describes and advises configuration of the Peggy module's parameters. The default parameters can be found in the genesis.go of the peggy module. - -```go -type Params struct { - PeggyId string - ContractSourceHash string - BridgeEthereumAddress string - BridgeChainId uint64 - SignedValsetsWindow uint64 - SignedBatchesWindow uint64 - SignedClaimsWindow uint64 - TargetBatchTimeout uint64 - AverageBlockTime uint64 - AverageEthereumBlockTime uint64 - SlashFractionValset math.LegacyDec - SlashFractionBatch math.LegacyDec - SlashFractionClaim math.LegacyDec - SlashFractionConflictingClaim math.LegacyDec - UnbondSlashingValsetsWindow uint64 - SlashFractionBadEthSignature math.LegacyDec - CosmosCoinDenom string - CosmosCoinErc20Contract string - ClaimSlashingEnabled bool - BridgeContractStartHeight uint64 - ValsetReward types.Coin -} -``` - -## `peggy_id` - -A random 32 byte value to prevent signature reuse, for example if the -Injective Chain validators decided to use the same Ethereum keys for another chain -also running Peggy we would not want it to be possible to play a deposit -from chain A back on chain B's Peggy. This value IS USED ON ETHEREUM so -it must be set in your genesis.json before launch and not changed after -deploying Peggy. Changing this value after deploying Peggy will result -in the bridge being non-functional. To recover just set it back to the original -value the contract was deployed with. - -## `contract_source_hash` - -The code hash of a known good version of the Peggy contract -solidity code. This can be used to verify the correct version -of the contract has been deployed. This is a reference value for -governance action only it is never read by any Peggy code - -## `bridge_ethereum_address` - -is address of the bridge contract on the Ethereum side, this is a -reference value for governance only and is not actually used by any -Peggy module code. - -The Ethereum bridge relayer use this value to interact with Peggy contract for querying events and submitting valset/batches to Peggy contract. - -## `bridge_chain_id` - -The bridge chain ID is the unique identifier of the Ethereum chain. This is a reference value only and is not actually used by any Peggy code - -These reference values may be used by future Peggy client implementations to allow for consistency checks. - -## Signing windows - -* `signed_valsets_window` -* `signed_batches_window` -* `signed_claims_window` - -These values represent the time in blocks that a validator has to submit -a signature for a batch or valset, or to submit a claim for a particular -attestation nonce. - -In the case of attestations this clock starts when the -attestation is created, but only allows for slashing once the event has passed. -Note that that claims slashing is not currently enabled see [slashing spec](./05_slashing.md) - -## `target_batch_timeout` - -This is the 'target' value for when batches time out, this is a target because -Ethereum is a probabilistic chain and you can't say for sure what the block -frequency is ahead of time. - -## Ethereum timing - -* `average_block_time` -* `average_ethereum_block_time` - -These values are the average Injective Chain block time and Ethereum block time respectively -and they are used to compute what the target batch timeout is. It is important that -governance updates these in case of any major, prolonged change in the time it takes -to produce a block - -## Slash fractions - -* `slash_fraction_valset` -* `slash_fraction_batch` -* `slash_fraction_claim` -* `slash_fraction_conflicting_claim` - -The slashing fractions for the various peggy related slashing conditions. The first three -refer to not submitting a particular message, the third for failing to submit a claim and the last for submitting a different claim than other validators. - -Note that claim slashing is currently disabled as outlined in the [slashing spec](./05_slashing.md) - -## `valset_reward` - -Valset reward is the reward amount paid to a relayer when they relay a valset to the Peggy contract on Ethereum. \ No newline at end of file diff --git a/.gitbook/developers/modules/injective/peggy/09_relay_semantics.md b/.gitbook/developers/modules/injective/peggy/09_relay_semantics.md deleted file mode 100644 index 8dbcad36..00000000 --- a/.gitbook/developers/modules/injective/peggy/09_relay_semantics.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -sidebar_position: 9 -title: Relay Semantics ---- - -# Relay Semantics - -This document is designed to assist developers in implementing alternate Peggy relayers. The two major components of the Orchestrator which interact with Ethereum. The Peggy bridge has been designed for increased efficiency, not for ease of use. This means there are many implicit requirements of these external binaries which this document does it's best to make explicit. - -The Peggy `orchestrator` combines three distinct roles that need to be performed by external binaries in the Peggy bridge. This document highlights the requirements of the `relayer` which is one of those roles included in the `orchestrator`. - -## Semantics for Validator set update relaying - -### Sorting and Ordering of the Validator set and signatures - -When updating the validator set in the Peggy contract you must provide a copy of the old validator set. This _MUST_ only be taken from the last ValsetUpdated event on the Ethereum chain. - -Providing the old validator set is part of a storage optimization, instead of storing the entire validator set in Ethereum storage it is instead provided by each caller and stored in the much cheaper Ethereum event queue. No sorting of any kind is performed in the Peggy contract, meaning the list of validators and their new signatures must be submitted in exactly the same order as the last call. - -For the purpose of normal operation this requirement can be shortened to 'sort the validators by descending power, and by Eth address bytes where power is equal'. Since the peggy module produces the validator sets they should always come in order. It is not possible for the relayer to change this order since it is part of the signature. But a change in this sorting method on the Peggy module side would halt valset updates and essentially decouple the bridge unless your implementation is smart enough to take a look at the last submitted order rather than blindly following sorting. - -### Deciding what Validator set to relay - -The Injective Chain simply produces a stream of validator sets, it does not make any judgement on how they are relayed. It's up to the relayer implementation to determine how to optimize the gas costs of this relaying operation. - -For example lets say we had validator sets `A, B, C, and D` each is created when there is a 5% power difference between the last Peggy validator set snapshot in the store and the currently active validator set. - -5% is an arbitrary constant. The specific value chosen here is a tradeoff made by the chain between how up to date the Ethereum validator set is and the cost to keep it updated. The higher this value is the lower the portion of the voting validator set is needed to highjack the bridge in the worst case. If we made a new validator set update every block 66% would need to collude, the 5% change threshold means 61% of the total voting power colluding in a given validator set may be able to steal the funds in the bridge. - -``` -A -> B -> C -> D - 5% 10% 15% -``` - -The relayer should iterate over the event history for the Peggy Ethereum contract, it will determine that validator set A is currently in the Peggy bridge. It can choose to either relay validator sets B, C and then D or simply submit validator set D. Provided all validators have signed D it has more than 66% voting power and can pass on it's own. Without paying potentially several hundred dollars more in Ethereum to relay the intermediate sets. - -Performing this check locally somehow, before submitting transactions, is essential to a cost effective relayer implementation. You can either use a local Ethereum signing implementation and sum the powers and signatures yourself, or you can simply use the `eth_call()` Ethereum RPC to simulate the call on your Ethereum node. - -Note that `eth_call()` often has funny gotchas. All calls fail on Geth based implementations if you don't have any Ethereum to pay for gas, while on Parity based implementations your gas inputs are mostly ignored and an accurate gas usage is returned. - -## Semantics for transaction batch relaying - -In order to submit a transaction batch you also need to submit the last set of validators and their staking powers. This is to facilitate the same storage optimization mentioned there. - -### Deciding what batch to relay - -Making a decision about which batch to relay is very different from deciding which validator set to relay. Batch relaying is primarily motivated by fees, not by a desire to maintain the integrity of the bridge. So the decision mostly comes down to fee computation, this is further complicated by the concept of 'batch requests'. Which is an unpermissioned transaction that requests the Peggy module generate a new batch for a specific token type. - -Batch requests are designed to allow the user to withdraw their tokens from the send to Ethereum tx pool at any time up until a relayer shows interest in actually relaying them. While transactions are in the pool there's no risk of a double spend if the user is allowed to withdraw them by sending a MsgCancelSendToEth. Once the transaction enters a batch due to a 'request batch' that is no longer the case and the users funds must remain locked until the Oracle informs the Peggy module that the batch containing the users tokens has become somehow invalid to submit or has been executed on Ethereum. - -A relayer uses the query endpoint `BatchFees` to iterate over the send to Eth tx pool for each token type, the relayer can then observe the price for the ERC-20 tokens being relayed on a dex and compute the gas cost of executing the batch (via `eth_call()`) as well as the gas cost of liquidating the earnings on a dex if desired. Once a relayer determines that a batch is good and profitable it can send a `MsgRequestBatch` and the batch will be created for the relayer to relay. - -There are also existing batches, which the relayer should also judge for profitability and make an attempt at relaying using much the same method. diff --git a/.gitbook/developers/modules/injective/peggy/10_future_improvements.md b/.gitbook/developers/modules/injective/peggy/10_future_improvements.md deleted file mode 100644 index 76771318..00000000 --- a/.gitbook/developers/modules/injective/peggy/10_future_improvements.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -sidebar_position: 10 -title: Future Improvements ---- - -# Future Improvements - -### Native Ethereum Signing - -Validators run a required `Eth Signer` in the peggo orchestrator because we can not yet insert this sort of simple signature logic into Cosmos SDK based chains without significant modification to Tendermint. This may be possible in the future with [modifications to Tendermint](https://github.com/tendermint/tendermint/issues/6066). - -It should be noted that both [PEGGYSLASH-02](./05_slashing.md) and [PEGGYSLASH-03](./05_slashing.md) could be eliminated with no loss of security if it where possible to perform the Ethereum signatures inside the consensus code. This is a pretty limited feature addition to Tendermint that would make Peggy far less prone to slashing. - -### Improved Validator Incentives - -Currently validators in Peggy have only one carrot - the extra activity brought to the chain by a functioning bridge. - -There are on the other hand a lot of negative incentives (sticks) that the validators must watch out for. These are outlined in the [slashing spec](./05_slashing.md). - -One negative incentive that is not covered under slashing is the cost of submitting oracle submissions and signatures. Currently these operations are not incentivized, but still cost the validators fees to submit. This isn't a severe issue considering the relatively cheap transaction fees on the Injective Chain currently, but of course is an important factor to consider as transaction fees rise. - -Some positive incentives for correctly participating in the operation of the bridge should be under consideration. In addition to eliminating the fees for mandatory submissions. \ No newline at end of file diff --git a/.gitbook/developers/modules/injective/peggy/README.md b/.gitbook/developers/modules/injective/peggy/README.md deleted file mode 100644 index 87c78767..00000000 --- a/.gitbook/developers/modules/injective/peggy/README.md +++ /dev/null @@ -1,39 +0,0 @@ -# `Peggy` - -## Abstract - -The peggy module enables the Injective Chain to support a trustless, on-chain bidirectional ERC-20 token bridge to Ethereum. In this system, -holders of ERC-20 tokens on Ethereum can convert their ERC-20 tokens to Cosmos-native coins on -the Injective Chain and vice-versa. - -This decentralized bridge is secured and operated by the validators of the Injective Chain. - -## Contents - -1. **[Definitions](./01_definitions.md)** -2. **[Workflow](./02_workflow.md)** -3. **[State](./03_state.md)** -4. **[Messages](./04_messages.md)** -5. **[Slashing](./05_slashing.md)** -6. **[End-Block](./06_end_block.md)** -7. **[Events](./07_events.md)** -8. **[Parameters](./08_params.md)** - -### Components - -1. **[Peggy](https://etherscan.io/address/0xF955C57f9EA9Dc8781965FEaE0b6A2acE2BAD6f3) smart contract on Ethereum** -2. **Peggy module on the Injective Chain** -3. **[Peggo](https://github.com/InjectiveLabs/peggo) (off-chain relayer aka orchestrator)** - - **Oracle** (Observes events of Peggy contract and send claims to the Peggy module) - - **EthSigner** (Signs Valset and Batch confirmations to the Peggy module) - - **Batch Requester** (Sends batch token withdrawal requests to the Peggy module) - - **Valset Relayer** (Submits Validator set updates to the Peggy contract) - - **Batch Relayer** (Submits batches of token withdrawals to the Peggy contract) - -In addition to running an `injectived` node to sign blocks, Injective Chain validators must also run the `peggo` orchestrator to relay data from the Peggy smart contract on Ethereum and the Peggy module on the Injective Chain. - -### Peggo Functionalities - -1. **Maintaining an up-to-date checkpoint of the Injective Chain validator set on Ethereum** -2. **Transferring ERC-20 tokens from Ethereum to the Injective Chain** -3. **Transferring pegged tokens from the Injective Chain to Ethereum** diff --git a/.gitbook/developers/modules/injective/peggy/images/SendToCosmos.png b/.gitbook/developers/modules/injective/peggy/images/SendToCosmos.png deleted file mode 100644 index c66908f6..00000000 Binary files a/.gitbook/developers/modules/injective/peggy/images/SendToCosmos.png and /dev/null differ diff --git a/.gitbook/developers/modules/injective/peggy/images/SendToEth.png b/.gitbook/developers/modules/injective/peggy/images/SendToEth.png deleted file mode 100644 index 914787ed..00000000 Binary files a/.gitbook/developers/modules/injective/peggy/images/SendToEth.png and /dev/null differ diff --git a/.gitbook/developers/modules/injective/peggy/images/valsetupdate.png b/.gitbook/developers/modules/injective/peggy/images/valsetupdate.png deleted file mode 100644 index 5592111f..00000000 Binary files a/.gitbook/developers/modules/injective/peggy/images/valsetupdate.png and /dev/null differ diff --git a/.gitbook/developers/modules/injective/permissions/01_concepts.md b/.gitbook/developers/modules/injective/permissions/01_concepts.md deleted file mode 100644 index 9b166cbf..00000000 --- a/.gitbook/developers/modules/injective/permissions/01_concepts.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -sidebar_position: 1 -title: Concepts ---- - - -## Key Concepts - -### Denoms -Tokens on Injective are referred to as denoms which are tracked and managed by the bank module on Injective. The permissions -module creates and manages assets by representing them as denoms and attaching specific permissions to them, which are then -managed by different roles. - -Note that the permissions module itself does not create new denoms, but rather attaches permissions to existing denoms -created by the tokenfactory module. The denom admin specified in the authority metadata of the denom created by the -tokenfactory module is the only address that can set and update permissions to the denom. - -### Namespace - -A token can be associated with a specific namespace which defines the set of roles and permissions associated with the -token, including e.g. the set of addresses (roles) allowed to mint, burn, and receive the token. The namespace also can -specify a Cosmwasm smart contract which can define custom logic to be invoked when a token is transferred, if more complex -control over transfers is desired. - -### Roles - -Roles group permissions together under a single human readable label. An address can be assigned multiple roles within a -namespace, and each role can have multiple actions allowed by them. Currently, there are three different actions supported: - -- Mint: Allows for minting/issuance of new tokens of this denom -- Burn: Allows for burning tokens of this denom -- Receive: Allows for receiving tokens of this denom - -### Actions - -`Minting`: Since mints can only be done from the denom admin address in Cosmos SDK, we assume that all mints are -performed by the denom admin and then transferred to the minter address. Therefore, any send from the denom admin -address can be considered a mint performed by the minter address (even though it is technically done by the denom admin). - -`Burning`: Similarly, burns can only be performed from the denom admin address, so transfers to the denom admin address -are considered burns. - -`Receiving`: Everything else is just a Receive. - -### Permissions - -Permissions define what actions an address can perform within a namespace. Default permissions for addresses not assigned -any role can be applied through `EVERYONE` role when creating or updating a namespace. Permissions can be used to control -actions like minting tokens, recieving tokens, or burning tokens. - -### Vouchers - -Whenever a transfer from a predefined set of module addresses (exchange, auction, insurance) to a user address fails due -to restrictions, the destination address of the transefer is rewritten to the permissions module address, where the tokens -are held. The original receiver of the funds is be assigned a voucher for the amount of tokens held inside the module. -The user will be able to claim the voucher only if they got assigned the respective permissions (RECEIVE action should -be allowed), which they didn't have previously and was the cause of the initial transfer failure. diff --git a/.gitbook/developers/modules/injective/permissions/02_state.md b/.gitbook/developers/modules/injective/permissions/02_state.md deleted file mode 100644 index f026f149..00000000 --- a/.gitbook/developers/modules/injective/permissions/02_state.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -sidebar_position: 2 -title: State ---- - -# State - -Genesis state defines the initial state of the module to be used to setup the module. - -```go -// GenesisState defines the permissions module's genesis state. -type GenesisState struct { - // params defines the parameters of the module. - Params Params `protobuf:"bytes,1,opt,name=params,proto3" json:"params"` - Namespaces []Namespace `protobuf:"bytes,2,rep,name=namespaces,proto3" json:"namespaces"` -} -``` - -## Params - -The permissions module doesn't use any params. -```go -// Params defines the parameters for the permissions module. -type Params struct { - WasmHookQueryMaxGas uint64 `protobuf:"varint,1,opt,name=wasm_hook_query_max_gas,json=wasmHookQueryMaxGas,proto3" json:"wasm_hook_query_max_gas,omitempty"` -} -``` - -## Namespaces - -Addresses can create permissioned namespaces with new denoms. Namespaces define roles and actions that users in the namespace are allowed or disallowed to perform or be. - -```go -// Namespace defines a permissions namespace -type Namespace struct { - Denom string `protobuf:"bytes,1,opt,name=denom,proto3" json:"denom,omitempty"` - WasmHook string `protobuf:"bytes,2,opt,name=wasm_hook,json=wasmHook,proto3" json:"wasm_hook,omitempty"` - MintsPaused bool `protobuf:"varint,3,opt,name=mints_paused,json=mintsPaused,proto3" json:"mints_paused,omitempty"` - SendsPaused bool `protobuf:"varint,4,opt,name=sends_paused,json=sendsPaused,proto3" json:"sends_paused,omitempty"` - BurnsPaused bool `protobuf:"varint,5,opt,name=burns_paused,json=burnsPaused,proto3" json:"burns_paused,omitempty"` - RolePermissions map[string]uint32 `protobuf:"bytes,6,rep,name=role_permissions,json=rolePermissions,proto3" json:"role_permissions,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"varint,2,opt,name=value,proto3"` - AddressRoles map[string]*Roles `protobuf:"bytes,7,rep,name=address_roles,json=addressRoles,proto3" json:"address_roles,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"` -} -``` - -Within a namespace, `MintsPaused`, `SendsPaused` and `BurnsPaused` determine whether new tokens can minted, sent or burnt. They can be updated only by the Denom admin. - -## Roles - -`Roles` are strings in a namespace where each role has specific permissions. - -```go -type Roles struct { - Roles []string `protobuf:"bytes,1,rep,name=roles,proto3" json:"roles,omitempty"` -} -``` - -## Actions - -Actions are powers of two used to denote different types of actions, `Action_UNSPECIFIED` = 0, `Action_MINT` = 1, `Action_RECEIVE` = 2 and `Action_BURN` = 4. - -```go -// each Action enum value should be a power of two -type Action int32 -``` - -## Role - -`Role` stores the name of the role and actions allowed to the role. - -```go -// Role is only used for storage -type Role struct { - Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"` - Permissions uint32 `protobuf:"varint,2,opt,name=permissions,proto3" json:"permissions,omitempty"` -} -``` - -## RoleIDs - -`RoleIDs` stores IDs for the roles. - -```go -// used in storage -type RoleIDs struct { - RoleIds []uint32 `protobuf:"varint,1,rep,packed,name=role_ids,json=roleIds,proto3" json:"role_ids,omitempty"` -} -``` - -## Voucher - -A `Voucher` holds tokens from all failed transactions until the original receiver has `RECEIVE` permissions. -* Vouchers: `0x06 | Address | denom -> ProtocolBuffer(Coin)` diff --git a/.gitbook/developers/modules/injective/permissions/03_state_transitions.md b/.gitbook/developers/modules/injective/permissions/03_state_transitions.md deleted file mode 100644 index fe0a11bf..00000000 --- a/.gitbook/developers/modules/injective/permissions/03_state_transitions.md +++ /dev/null @@ -1,188 +0,0 @@ ---- -sidebar_position: 3 -title: State Transitions ---- - -# State Transitions - -This document describes the state transition operations pertaining to: - -- Create namespace -- Delete namespace -- Update namespace -- Update namespace roles -- Revoke namespace roles -- Claim Voucher -- Update params - -## Create Namespace - -Namespaces can be created for implementing different roles and actions. - -```protobuf -message MsgCreateNamespace { - option (cosmos.msg.v1.signer) = "sender"; - string sender = 1 [ (gogoproto.moretags) = "yaml:\"sender\"" ]; - - Namespace namespace = 2 [ (gogoproto.nullable) = false ]; -} - -// Namespace defines a permissions namespace -message Namespace { - string denom = 1; // tokenfactory denom to which this namespace applies to - string wasm_hook = - 2; // address of smart contract to apply code-based restrictions - - bool mints_paused = 3; - bool sends_paused = 4; - bool burns_paused = 5; - - repeated Role role_permissions = 6; // permissions for each role - - repeated AddressRoles address_roles = 7; -} - -message AddressRoles { - string address = 1; - repeated string roles = 2; -} - -message Role { - string role = 1; - uint32 permissions = 2; -} -``` - -**Steps** - -- Create a new denom -- Create a `MsgCreateNamespace` message with `Denom`, `RolePermissions` and `AddressRoles`. -- Validate the `MsgCreateNamespace` object. -- Send the create namespace message. - -## Delete Namespace - -Deleting a namespace removes it and its associated roles and permissions. -```protobuf -message MsgDeleteNamespace { - option (cosmos.msg.v1.signer) = "sender"; - string sender = 1 [ (gogoproto.moretags) = "yaml:\"sender\"" ]; - - string namespace_denom = 2; -} -``` - -**Steps** - -- Create a `MsgDeleteNamespace` message with the namespace denom `NamespaceDenom` to be deleted. -- Validate the `MsgDeleteNamespace` object. -- Send the delete namespace message. - -## Update Namespace - -Updating a namespace allows modifying its associated roles and permissions. -```protobuf -message MsgUpdateNamespace { - option (cosmos.msg.v1.signer) = "sender"; - string sender = 1 [ (gogoproto.moretags) = "yaml:\"sender\"" ]; - - string namespace_denom = - 2; // namespace denom to which this updates are applied - - message MsgSetWasmHook { string new_value = 1; } - MsgSetWasmHook wasm_hook = - 3; // address of smart contract to apply code-based restrictions - - message MsgSetMintsPaused { bool new_value = 1; } - MsgSetMintsPaused mints_paused = 4; - - message MsgSetSendsPaused { bool new_value = 1; } - MsgSetSendsPaused sends_paused = 5; - - message MsgSetBurnsPaused { bool new_value = 1; } - MsgSetBurnsPaused burns_paused = 6; -} -``` -**Steps** - -- Create a `MsgUpdateNamespace` message with `NamespaceDenom`, and the new values for `MintsPaused`, `BurnsPaused` and `SendsPaused`. -- Validate the `MsgUpdateNamespace` object. -- Send the update namespace message. - -## Update Namespace Roles - -Updating namespace roles allows modifying the roles and their permissions within a namespace. -```protobuf -message MsgUpdateNamespaceRoles { - option (cosmos.msg.v1.signer) = "sender"; - string sender = 1 [ (gogoproto.moretags) = "yaml:\"sender\"" ]; - - string namespace_denom = - 2; // namespace denom to which this updates are applied - - repeated Role role_permissions = - 3; // new role definitions or updated permissions for existing roles - repeated AddressRoles address_roles = - 4; // new addresses to add or new roles for existing addresses to - // overwrite current roles -} -``` -**Steps** - -- Create a `MsgUpdateNamespaceRoles` message with the `NamespaceDenom`, the new `RolePermissions` and `AddressRoles`. -- Validate the `MsgUpdateNamespaceRoles` object. -- Send the update namespace roles message. - -## Revoke Namespace Roles - -Revoking namespace roles removes certain roles from an address within a namespace. -```protobuf -message MsgRevokeNamespaceRoles { - option (cosmos.msg.v1.signer) = "sender"; - string sender = 1 [ (gogoproto.moretags) = "yaml:\"sender\"" ]; - - string namespace_denom = - 2; // namespace denom to which this updates are applied - repeated AddressRoles address_roles_to_revoke = - 3; // {"address" => array of roles to revoke from this address} -} -``` -**Steps** - -- Create a `MsgRevokeNamespaceRoles` message with the `NamespaceDenom` and `AddressRolesToRevoke`. -- Validate the `MsgRevokeNamespaceRoles` object. -- Send the revoke namespace roles message. - -## Claim Voucher - -```protobuf -message MsgClaimVoucher { - option (amino.name) = "permissions/MsgClaimVoucher"; - option (cosmos.msg.v1.signer) = "sender"; - string sender = 1 [ (gogoproto.moretags) = "yaml:\"sender\"" ]; - - string denom = 2; -} -``` - -## Update Params - -```protobuf -message MsgUpdateParams { - option (cosmos.msg.v1.signer) = "authority"; - - // authority is the address of the governance account. - string authority = 1 [ (cosmos_proto.scalar) = "cosmos.AddressString" ]; - - // params defines the permissions parameters to update. - // - // NOTE: All parameters must be supplied. - Params params = 2 [ (gogoproto.nullable) = false ]; -} - -message Params { - option (gogoproto.equal) = true; - - uint64 wasm_hook_query_max_gas = 1; -} -``` \ No newline at end of file diff --git a/.gitbook/developers/modules/injective/permissions/README.md b/.gitbook/developers/modules/injective/permissions/README.md deleted file mode 100644 index c92ce1de..00000000 --- a/.gitbook/developers/modules/injective/permissions/README.md +++ /dev/null @@ -1,13 +0,0 @@ -# `Permissions` - -## Abstract - -Bringing real world permissioned assets (e.g. tokenized treasury yield products) on-chain require certain levels of control over asset actions/properties such as transfers, holders (whitelists), and more. - -The `permissions` module allows managing certain prefixed actions and roles for real world assets and permissioned denoms created within a namespace on the chain-level. It provides a flexible and extensible way to define and enforce permissions and roles and serves as the entry point through which real world assets can be natively issued and managed on Injective. - -## Contents - -1. **[Concepts](./01_concepts.md)** -2. **[State](./02_state.md)** -3. **[State Transitions](./03_state_transitions.md)** diff --git a/.gitbook/developers/modules/injective/tokenfactory/01_concepts.md b/.gitbook/developers/modules/injective/tokenfactory/01_concepts.md deleted file mode 100644 index 730c65cb..00000000 --- a/.gitbook/developers/modules/injective/tokenfactory/01_concepts.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -sidebar_position: 1 -title: Concepts ---- - -# Concepts - -The `tokenfactory` module allows any account to create a new token with -the name `factory/{creator address}/{subdenom}`. Because tokens are -namespaced by creator address, this allows token minting to be -permissionless, due to not needing to resolve name collisions. A single -account can create multiple denoms, by providing a unique subdenom for each -created denom. Once a denom is created, the original creator is given -"admin" privileges over the asset. This allows them to: - -- Mint their denom to any account -- Burn their denom from any account -- Create a transfer of their denom between any two accounts -- Change the admin. In the future, more admin capabilities may be added. Admins - can choose to share admin privileges with other accounts using the authz - module. The `ChangeAdmin` functionality, allows changing the master admin - account, or even setting it to `""`, meaning no account has admin privileges - of the asset. diff --git a/.gitbook/developers/modules/injective/tokenfactory/02_state.md b/.gitbook/developers/modules/injective/tokenfactory/02_state.md deleted file mode 100644 index dfaefb62..00000000 --- a/.gitbook/developers/modules/injective/tokenfactory/02_state.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -sidebar_position: 2 -title: State ---- - -# State - -The tokenfactory module keeps state of the following primary objects: - -## Denom Authority Metadata - -- 0x02 + | + denom + | + 0x01 ⇒ `DenomAuthorityMetadata` - -## Denom Creators - -- 0x03 + | + creator + | denom ⇒ denom - - -```protobuf -// DenomAuthorityMetadata specifies metadata for addresses that have specific -// capabilities over a token factory denom. Right now there is only one Admin -// permission, but is planned to be extended to the future. -message DenomAuthorityMetadata { - option (gogoproto.equal) = true; - - // Can be empty for no admin, or a valid injective address - string admin = 1 [ (gogoproto.moretags) = "yaml:\"admin\"" ]; -} -``` - -Genesis state defines the initial state of the module to be used to setup the module. - -```protobuf -// GenesisState defines the tokenfactory module's genesis state. -message GenesisState { - // params defines the parameters of the module. - Params params = 1 [ (gogoproto.nullable) = false ]; - - repeated GenesisDenom factory_denoms = 2 [ - (gogoproto.moretags) = "yaml:\"factory_denoms\"", - (gogoproto.nullable) = false - ]; -} - -// GenesisDenom defines a tokenfactory denom that is defined within genesis -// state. The structure contains DenomAuthorityMetadata which defines the -// denom's admin. -message GenesisDenom { - option (gogoproto.equal) = true; - - string denom = 1 [ (gogoproto.moretags) = "yaml:\"denom\"" ]; - DenomAuthorityMetadata authority_metadata = 2 [ - (gogoproto.moretags) = "yaml:\"authority_metadata\"", - (gogoproto.nullable) = false - ]; -} -``` -## Params - -`Params` is a module-wide configuration that stores system parameters and defines overall functioning of the tokenfactory module. -This module is modifiable by governance using params update proposal natively supported by `gov` module. - -Struct for the `ocr` module params store. -```protobuf -// Params defines the parameters for the tokenfactory module. -message Params { - repeated cosmos.base.v1beta1.Coin denom_creation_fee = 1 [ - (gogoproto.castrepeated) = "github.com/cosmos/cosmos-sdk/types.Coins", - (gogoproto.moretags) = "yaml:\"denom_creation_fee\"", - (gogoproto.nullable) = false - ]; -} - -``` diff --git a/.gitbook/developers/modules/injective/tokenfactory/03_messages.md b/.gitbook/developers/modules/injective/tokenfactory/03_messages.md deleted file mode 100644 index 9869b19a..00000000 --- a/.gitbook/developers/modules/injective/tokenfactory/03_messages.md +++ /dev/null @@ -1,145 +0,0 @@ ---- -sidebar_position: 3 ---- - -# Messages - -In this section we describe the processing of the tokenfactory messages and the corresponding updates to the state. - -## Messages - -### CreateDenom - -Creates a denom of `factory/{creator address}/{subdenom}` given the denom creator -address and the subdenom. Subdenoms can contain `[a-zA-Z0-9./]`. - -```go -message MsgCreateDenom { - string sender = 1 [ (gogoproto.moretags) = "yaml:\"sender\"" ]; - string subdenom = 2 [ (gogoproto.moretags) = "yaml:\"subdenom\"" ]; -} -``` - -**State Modifications:** - -- Fund community pool with the denom creation fee from the creator address, set - in `Params`. -- Set `DenomMetaData` via bank keeper. -- Set `AuthorityMetadata` for the given denom to store the admin for the created - denom `factory/{creator address}/{subdenom}`. Admin is automatically set as the - Msg sender. -- Add denom to the `CreatorPrefixStore`, where a state of denoms created per - creator is kept. - -### Mint - -Minting of a specific denom is only allowed for the current admin. -Note, the current admin is defaulted to the creator of the denom. - -```go -message MsgMint { - string sender = 1 [ (gogoproto.moretags) = "yaml:\"sender\"" ]; - cosmos.base.v1beta1.Coin amount = 2 [ - (gogoproto.moretags) = "yaml:\"amount\"", - (gogoproto.nullable) = false - ]; -} -``` - -**State Modifications:** - -- Safety check the following - - Check that the denom minting is created via `tokenfactory` module - - Check that the sender of the message is the admin of the denom -- Mint designated amount of tokens for the denom via `bank` module - -### Burn - -Burning of a specific denom is only allowed for the current admin. -Note, the current admin is defaulted to the creator of the denom. - -```go -message MsgBurn { - string sender = 1 [ (gogoproto.moretags) = "yaml:\"sender\"" ]; - cosmos.base.v1beta1.Coin amount = 2 [ - (gogoproto.moretags) = "yaml:\"amount\"", - (gogoproto.nullable) = false - ]; -} -``` - -**State Modifications:** - -- Safety check the following - - Check that the denom minting is created via `tokenfactory` module - - Check that the sender of the message is the admin of the denom -- Burn designated amount of tokens for the denom via `bank` module - -### ChangeAdmin - -Change the admin of a denom. Note, this is only allowed to be called by the current admin of the denom. - -```go -message MsgChangeAdmin { - string sender = 1 [ (gogoproto.moretags) = "yaml:\"sender\"" ]; - string denom = 2 [ (gogoproto.moretags) = "yaml:\"denom\"" ]; - string newAdmin = 3 [ (gogoproto.moretags) = "yaml:\"new_admin\"" ]; -} -``` - -### SetDenomMetadata - -Setting of metadata for a specific denom is only allowed for the admin of the denom. -It allows the overwriting of the denom metadata in the bank module. - -```go -message MsgChangeAdmin { - string sender = 1 [ (gogoproto.moretags) = "yaml:\"sender\"" ]; - cosmos.bank.v1beta1.Metadata metadata = 2 [ (gogoproto.moretags) = "yaml:\"metadata\"", (gogoproto.nullable) = false ]; -} -``` - -**State Modifications:** - -- Check that sender of the message is the admin of denom -- Modify `AuthorityMetadata` state entry to change the admin of the denom - - -## Expectations from the chain - -The chain's bech32 prefix for addresses can be at most 16 characters long. - -This comes from denoms having a 128 byte maximum length, enforced from the SDK, -and us setting longest_subdenom to be 44 bytes. - -A token factory token's denom is: `factory/{creator address}/{subdenom}` - -Splitting up into sub-components, this has: - -- `len(factory) = 7` -- `2 * len("/") = 2` -- `len(longest_subdenom)` -- `len(creator_address) = len(bech32(longest_addr_length, chain_addr_prefix))`. - -Longest addr length at the moment is `32 bytes`. Due to SDK error correction -settings, this means `len(bech32(32, chain_addr_prefix)) = len(chain_addr_prefix) + 1 + 58`. -Adding this all, we have a total length constraint of `128 = 7 + 2 + len(longest_subdenom) + len(longest_chain_addr_prefix) + 1 + 58`. -Therefore `len(longest_subdenom) + len(longest_chain_addr_prefix) = 128 - (7 + 2 + 1 + 58) = 60`. - -The choice between how we standardized the split these 60 bytes between maxes -from longest_subdenom and longest_chain_addr_prefix is somewhat arbitrary. -Considerations going into this: - -- Per [BIP-0173](https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki#bech32) - the technically longest HRP for a 32 byte address ('data field') is 31 bytes. - (Comes from encode(data) = 59 bytes, and max length = 90 bytes) -- subdenom should be at least 32 bytes so hashes can go into it -- longer subdenoms are very helpful for creating human readable denoms -- chain addresses should prefer being smaller. The longest HRP in cosmos to date is 11 bytes. (`persistence`) - -For explicitness, its currently set to `len(longest_subdenom) = 44` and `len(longest_chain_addr_prefix) = 16`. - -Please note, if the SDK increases the maximum length of a denom from 128 bytes, -these caps should increase. - -So please don't make code rely on these max lengths for parsing. diff --git a/.gitbook/developers/modules/injective/tokenfactory/04_events.md b/.gitbook/developers/modules/injective/tokenfactory/04_events.md deleted file mode 100644 index ac7a3185..00000000 --- a/.gitbook/developers/modules/injective/tokenfactory/04_events.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -sidebar_position: 4 -title: Events ---- - -# Events - -The tokenfactory module emits the following events: - -An EventCreateTFDenom is emitted upon MsgCreateDenom execution, which creates a new token factory denom. - -```protobuf -message EventCreateTFDenom { - string account = 1; - string denom = 2; -} -``` - -An EventMintTFDenom is emitted upon MsgMint execution, which mints a new token factory denom for a recipient. - -```protobuf -message EventMintTFDenom { - string recipient_address = 1; - cosmos.base.v1beta1.Coin amount = 2 [(gogoproto.nullable) = false]; -} -``` - -An EventBurnDenom is emitted upon MsgBurn execution, which burns a specified amount for any denom for a user. - -```protobuf -message EventBurnDenom { - string burner_address = 1; - cosmos.base.v1beta1.Coin amount = 2 [(gogoproto.nullable) = false]; -} -``` - -An EventChangeTFAdmin is emitted upon MsgChangeAdmin execution, which changes the admin address for a new token factory denom. - -```protobuf -message EventChangeTFAdmin { - string denom = 1; - string new_admin_address = 2; -} - -``` - -An EventSetTFDenomMetadata is emitted upon MsgSetDenomMetadata execution, which sets the token factory denom metadata for a given token factory denom. - -```protobuf -message EventSetTFDenomMetadata { - string denom = 1; - cosmos.bank.v1beta1.Metadata metadata = 2[(gogoproto.nullable) = false]; -} -``` \ No newline at end of file diff --git a/.gitbook/developers/modules/injective/tokenfactory/05_params.md b/.gitbook/developers/modules/injective/tokenfactory/05_params.md deleted file mode 100644 index a2bd83cd..00000000 --- a/.gitbook/developers/modules/injective/tokenfactory/05_params.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -sidebar_position: 5 -title: Params ---- - -# Parameters - -The tokenfactory module contains the following parameters: - -```protobuf -// Params defines the parameters for the tokenfactory module. -message Params { - repeated cosmos.base.v1beta1.Coin denom_creation_fee = 1 [ - (gogoproto.castrepeated) = "github.com/cosmos/cosmos-sdk/types.Coins", - (gogoproto.moretags) = "yaml:\"denom_creation_fee\"", - (gogoproto.nullable) = false - ]; -} -``` diff --git a/.gitbook/developers/modules/injective/tokenfactory/README.md b/.gitbook/developers/modules/injective/tokenfactory/README.md deleted file mode 100644 index d1b0a39b..00000000 --- a/.gitbook/developers/modules/injective/tokenfactory/README.md +++ /dev/null @@ -1,14 +0,0 @@ -# Tokenfactory - -## Abstract - -The tokenfactory module allows for the permissionless creation of new bank denom tokens. - - -## Contents - -1. **[Concepts](01_concepts.md)** -2. **[State](02_state.md)** -3. **[Messages](03_messages.md)** -4. **[Events](04_events.md)** -5. **[Parameters](05_params.md)** diff --git a/.gitbook/developers/modules/injective/wasmx/01_concepts.md b/.gitbook/developers/modules/injective/wasmx/01_concepts.md deleted file mode 100644 index 50da6d18..00000000 --- a/.gitbook/developers/modules/injective/wasmx/01_concepts.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -sidebar_position: 1 -title: Concepts ---- - -## Concepts - -### Begin blocker execution - -Smart contracts can only respond to incoming messages and do not have the ability to execute actions on their own schedule. The Wasmx module allows contracts to be registered and called in the begin blockers section of each block. -To be eligible for this, each registered contract must respond to the sudo message called `begin_blocker` which can only be called by the chain itself and not directly by any user or other contract. This ensures that the "begin_blocker" message can be trusted. - -### Registration - -Upon registering a contract, the user must declare a gas price, which is the amount they are willing to pay for contract execution, as well as a gas limit, which is the maximum amount of gas that can be consumed during the execution of the contract. - -Currently, contract registration can only be done through a governance proposal. This proposal, if approved, will add the contract at a specific address to the list of contracts that are run during each "begin blockers" period. - -For security reasons, the proposer must specify a code_id for the contract, which will be verified upon registration and each time the contract is executed. This is to prevent an attacker from registering a benign contract but later upgrading it to a malicious one. The proposer can request to be exempt from this check when registering the contract to avoid delays when a new version of the contract is released, but this may affect the voting results depending on the trustworthiness of the proposer. - -The proposer can also request for the contract to be "pinned," meaning it is loaded and kept in memory, which can greatly improve the performance of the contract. - -### Deregistration - -A contract can be deregistered through a governance proposal, which can be initiated by anyone, including the contract owner if they no longer require the contract or by any other individual if the contract is found to be malicious. - -If contract fails to execute due to insufficient gas it will be automatically deregistered. - -When contract is deregistered, wasmx will call special `deregister{}` callback (if present) as a sudo message in the contract. - -### Deactivation - -A contract can be deactivated automatically if it runs out of gas, or manually by the contract owner. When a contract is deactivated, wasmx will call a special `deactivate{}` callback (if present) as a sudo message in the contract. The contract can be reactivated by the contract owner. - -### Fee Grant - -The Wasmx module allows other addresses (contracts, EOAs) to pay for the Begin blocker execution of other contracts through the [`x/feegrant`](https://docs.cosmos.network/main/modules/feegrant) module. - -When a contract is being registered for the first time, users specify the `FundingMode` which indicates how the contract's execution will be funded. Three modes are supported: - -- `SelfFunded` - contract will pay for its own execution (default) -- `GrantOnly` - contract will execute if its associated allowance covers for it (provided by the `GranterAddress` in the `ContractRegistrationRequest`) -- `Dual` - contract will prioritize spending its allowance's funds. In case the allowance cannot cover for execution, it will use its own funds instead - -Given there are 3 kinds of allowances provided by the `x/feegrant` module (Basic, Periodic and AllowedMsg), the wasmx module supports only Basic and Periodic. Granting an `AllowedMsgAllowance` to a contract is discouraged as any contract attempting to use this kind of allowance will error by default. - -### Pausing, params update - -The owner of a contract has the ability to deactivate or activate the contract at any time without requiring a governance vote. They can also update the parameters for contract execution, such as the gas price or gas limit, at any time. - -### Batch methods - -For convenience, the Wasmx module provides batch versions of some of the previously mentioned proposals, such as batch registration and deregistration, as well as a batch version of the StoreCodeProposal. These batch versions allow multiple proposals to be processed at the same time, rather than individually. diff --git a/.gitbook/developers/modules/injective/wasmx/02_data.md b/.gitbook/developers/modules/injective/wasmx/02_data.md deleted file mode 100644 index 822bb8fb..00000000 --- a/.gitbook/developers/modules/injective/wasmx/02_data.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -sidebar_position: 2 -title: Data ---- - -## Data - -### RegisteredContract - -Data stored about each contract - -```go -type RegisteredContract struct { - // limit of gas per BB execution - GasLimit uint64 json:"gas_limit,omitempty" - // gas price that contract is willing to pay for execution in BeginBlocker - GasPrice uint64 json:"gas_price,omitempty" - // is contract currently active - IsExecutable bool json:"is_executable,omitempty" - // code_id that is allowed to be executed (to prevent malicious updates) - if nil/0 any code_id can be executed - CodeId uint64 json:"code_id,omitempty"ł - // optional - admin addr that is allowed to update contract data - AdminAddress string json:"admin_address,omitempty" - // address of an account providing grant for execution - GranterAddress string - // enum indicating how contract's execution is funded - FundMode FundingMode -} - -type FundingMode int32 - -const ( - FundingMode_Unspecified FundingMode = 0 - FundingMode_SelfFunded FundingMode = 1 - FundingMode_GrantOnly FundingMode = 2 - FundingMode_Dual FundingMode = 3 -) -``` \ No newline at end of file diff --git a/.gitbook/developers/modules/injective/wasmx/03_proposals.md b/.gitbook/developers/modules/injective/wasmx/03_proposals.md deleted file mode 100644 index c815ddd5..00000000 --- a/.gitbook/developers/modules/injective/wasmx/03_proposals.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -sidebar_position: 3 -title: Governance Proposals ---- - -## Governance Proposals - -### ContractRegistrationRequest - -`ContractRegistrationRequest` is a base message for registering new contracts (shouldn't be used directly but as a part of proposal) - -```go -type ContractRegistrationRequest struct { - ContractAddress string - GasLimit uint64 - GasPrice uint64 - PinContract bool - AllowUpdating bool - CodeId uint64 - ContractAdmin string - GranterAddress string - FundMode FundingMode -} -``` - -**Fields description** - -- `ContractAddress` - unique Identifier for contract instance to be registered. -- `GasLimit` - Maximum gas to be used for the smart contract execution. -- `GasPrice` - Gas price to be used for the smart contract execution. -- `PinContract` - should contract be pinned. -- `AllowUpdating`- defines wether contract owner can migrate it without need to register again (if false only current code_id will be allowed to be executed) -- `CodeId` - code_id of the contract being registered - will be verified on execution to allow last minute change (after votes were cast) -- `AdminAddress` - optional address of admin account (that will be allowed to pause or update contract params) -- `GranterAddress` - address of an account which granted funds for execution. Must be set if `FundMode` is other than `SelfFunded` (see below for an explanation) - -`FundingMode` indicates how the contract will fund its own execution. - -```go -enum FundingMode { - Unspecified = 0; - SelfFunded = 1; - GrantOnly = 2; - Dual = 3; -} -``` - -- `SelfFunded` - contract will use its own funds to execute. -- `GrantOnly` - contract wil only use funds provided by the grant. -- `Dual` - contract will first deplete grant's funds before using its own. - -### ContractRegistrationRequestProposal - -`ContractRegistrationRequestProposal` defines an SDK message to register a single contract in wasmx contract registry. - -```go -type ContractRegistrationRequestProposal struct { - Title string - Description string - ContractRegistrationRequest ContractRegistrationRequest -} -``` - -**Fields description** - -- `Title` describes the title of the proposal. -- `Description` describes the description of the proposal. -- `ContractRegistrationRequest` contains contract registration request (as described above) - - - - -### BatchContractRegistrationRequestProposal - -`BatchContractRegistrationRequestProposal` defines an SDK message to register a batch of contracts in wasmx contract registry. - -```go -type BatchContractRegistrationRequestProposal struct { - Title string - Description string - ContractRegistrationRequests []ContractRegistrationRequest -} -``` - -**Fields description** - -- `Title` describes the title of the proposal. -- `Description` describes the description of the proposal. -- `ContractRegistrationRequests` contains a list of contracts registration requests (as described above) - - -### BatchStoreCodeProposal - -`BatchStoreCodeProposal` defines an SDK message to store a batch of contracts in wasm. - -```go -type BatchStoreCodeProposal struct { - Title string - Description string - Proposals []types.StoreCodeProposal -} -``` - -**Fields description** - -- `Title` describes the title of the proposal. -- `Description` describes the description of the proposal. -- `Proposals` contains a list of store code proposals (as defined by Cosmos wasm module) - - -### BatchContractDeregistrationProposal - -`BatchContractDeregistrationProposal` defines an SDK message to deregister a batch of contracts in wasm. - -```go -type BatchContractDeregistrationProposal struct { - Title string - Description string - Contracts []string -} -``` - -**Fields description** - -- `Title` describes the title of the proposal. -- `Description` describes the description of the proposal. -- `Contracts` contains a list of addresses of contracts to be deregistered - - - diff --git a/.gitbook/developers/modules/injective/wasmx/04_messages.md b/.gitbook/developers/modules/injective/wasmx/04_messages.md deleted file mode 100644 index a1b1699c..00000000 --- a/.gitbook/developers/modules/injective/wasmx/04_messages.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -sidebar_position: 4 -title: Messages ---- - -## Messages - -### MsgUpdateContract - -Updates registered contract execution params (gas price, limit). Can also define a new admin account. -Can be called only by admin (if defined) or contract itself. - -```go - -type MsgUpdateContract struct { - Sender string `json:"sender,omitempty"` - // Unique Identifier for contract instance to be registered. - ContractAddress string `json:"contract_address,omitempty"` - // Maximum gas to be used for the smart contract execution. - GasLimit uint64 `json:"gas_limit,omitempty"` - // gas price to be used for the smart contract execution. - GasPrice uint64 `json:"gas_price,omitempty"` - // optional - admin account that will be allowed to perform any changes - AdminAddress string `json:"admin_address,omitempty"` -} -``` - -### MsgDeactivateContract - -Deactivates a registered contract (it will no longer be executed in begin blocker) - -```go - -type MsgDeactivateContract struct { - Sender string `json:"sender,omitempty"` - // Unique Identifier for contract instance to be activated. - ContractAddress string `json:"contract_address,omitempty"` -} -``` - -### MsgActivateContract - -Reactivates a registered contract (it will be executed in begin blocker from now on again) - -```go - -type MsgActivateContract struct { - Sender string `json:"sender,omitempty"` - // Unique Identifier for contract instance to be activated. - ContractAddress string `json:"contract_address,omitempty"` -} -``` - -### MsgExecuteContract - -Invokes a function defined within the smart contract. Function and parameters are encoded in `ExecuteMsg`, which is a JSON message encoded in Base64. - -```go -type MsgExecuteContract struct { - Sender sdk.AccAddress `json:"sender" yaml:"sender"` - Contract sdk.AccAddress `json:"contract" yaml:"contract"` - ExecuteMsg core.Base64Bytes `json:"execute_msg" yaml:"execute_msg"` - Coins sdk.Coins `json:"coins" yaml:"coins"` -} -``` - -### MsgMigrateContract - -Can be issued by the owner of a migratable smart contract to reset its code ID to another one. `MigrateMsg` is a JSON message encoded in Base64. - -```go -type MsgMigrateContract struct { - Owner sdk.AccAddress `json:"owner" yaml:"owner"` - Contract sdk.AccAddress `json:"contract" yaml:"contract"` - NewCodeID uint64 `json:"new_code_id" yaml:"new_code_id"` - MigrateMsg core.Base64Bytes `json:"migrate_msg" yaml:"migrate_msg"` -} -``` - -### MsgUpdateContractOwner - -Can be issued by the smart contract's owner to transfer ownership. - -```go -type MsgUpdateContractOwner struct { - Owner sdk.AccAddress `json:"owner" yaml:"owner"` - NewOwner sdk.AccAddress `json:"new_owner" yaml:"new_owner"` - Contract sdk.AccAddress `json:"contract" yaml:"contract"` -} -``` \ No newline at end of file diff --git a/.gitbook/developers/modules/injective/wasmx/05_params.md b/.gitbook/developers/modules/injective/wasmx/05_params.md deleted file mode 100644 index 2663c1f3..00000000 --- a/.gitbook/developers/modules/injective/wasmx/05_params.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -sidebar_position: 5 -title: Params ---- - -## Params - -The subspace for the wasmx module is `wasmx`. - -```go -type Params struct { - // Set the status to active to indicate that contracts can be executed in begin blocker. - IsExecutionEnabled bool ` json:"is_execution_enabled,omitempty"` - // Maximum aggregate total gas to be used for the contract executions in the BeginBlocker. - MaxBeginBlockTotalGas uint64 `json:"max_begin_block_total_gas,omitempty"` - // the maximum gas limit each individual contract can consume in the BeginBlocker. - MaxContractGasLimit uint64 `json:"max_contract_gas_limit,omitempty"` - // min_gas_price defines the minimum gas price the contracts must pay to be executed in the BeginBlocker. - MinGasPrice uint64 `json:"min_gas_price,omitempty"` -} -``` \ No newline at end of file diff --git a/.gitbook/developers/modules/injective/wasmx/README.md b/.gitbook/developers/modules/injective/wasmx/README.md deleted file mode 100644 index 71cdd4f7..00000000 --- a/.gitbook/developers/modules/injective/wasmx/README.md +++ /dev/null @@ -1,17 +0,0 @@ -# `Wasmx` - -## Abstract - -The `wasmx` module handles integration of [CosmWasm](https://cosmwasm.com) smart contracts with Injective Chain. -Its main function is to provide a method for contracts to be executed in the begin blocker section of each block. -A contract may be automatically deactivated if it runs out of gas but can be reactivated by the contract owner. - -It also includes helper methods for managing contracts, such as a batch code storage proposal. These functions allow for seamless integration of CosmWasm contracts with the Injective Chain and provide useful tools for managing and maintaining those contracts. - -## Contents - -1. **[Concepts](./01_concepts.md)** -2. **[Data](./02_data.md)** -3. **[State](./03_proposals.md)** -4. **[Messages](./04_messages.md)** -5. **[Params](./05_params.md)** diff --git a/.gitbook/getting-started/README.md b/.gitbook/getting-started/README.md deleted file mode 100644 index 6330a5a7..00000000 --- a/.gitbook/getting-started/README.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -description: Brief overview of Injective and it's unique features for the general audience. ---- - -# Getting Started - -Welcome to your journey of exploring Injective. Before asking questions, try to use the search functionality on the docs. Our goal is to make the documentation self-sufficient so onboarding is easy and everyone can learn more about Injective easily. - -Should you have some questions or feedback, you can reach out to Discord or Telegram: - -1. Join the [Injective Discord server](https://discord.gg/injective) and find the relevant channel. -2. Join the [Injective Developer Telegram channel](https://t.me/+8Y\_0HOFLhnRlZDU9). - -### Quickstart Guide to Injective - -
WalletLearn how to create a wallet on Injective and see the supported wallets on Injective wallet-hero (1).pngcreate-a-wallet.md
Token StandardsLearn about different Token Standards on Injectivetoken-hero.pngtoken-standards
TransactionsLearn how to prepare, sign and submit transactions on Injectivetxs-hero.pngtransactions
- diff --git a/.gitbook/getting-started/token-standards/README.md b/.gitbook/getting-started/token-standards/README.md deleted file mode 100644 index e66f1514..00000000 --- a/.gitbook/getting-started/token-standards/README.md +++ /dev/null @@ -1,35 +0,0 @@ -# Token Standards - -Injective provides a variety of different token standards one can use when creating a dApp. In this document, we will cover the different types of tokens, as well as recommendations and guidance for using each. - -## Denom - -A denom is how assets are represented within the Bank module of Injective. These assets can be used for trading, creating new markets on the exchange module, participating in auctions, transferring to another address, etc. - -Depending on the origin of the denom and how it was created on Injective we have different types of denoms: - -* **Native denoms** - there is only one denom of this type, the `inj` denom which represented the native coin of Injective, -* **Peggy denoms** - these denoms represent assets bridged over from Ethereum to Injective using the Peggy bridge. They have the following format `peggy{ERC20_CONTRACT_ADDRESS}` -* **IBC denoms** - these denoms represent assets bridged over from other Cosmos chains through IBC. They have the following format `ibc/{hash}`. -* **Insurance Fund Denoms** - these denoms represent token shares of the insurance funds created on Injective. They have the following format `share{id}` -* **Factory Denoms** - these `tokenfactory` denoms allows any account to create a new token with the name `factory/{creator address}/{subdenom}`. Because tokens are namespaced by creator address, this allows token minting to be permissionless, due to not needing to resolve name collisions. Special usecase for these denoms is representing a CW20 token from Cosmwasm on the Injective native bank module. They have the following format `factory/{CW20_ADAPTER_CONTRACT}/{CW20_CONTRACT_ADDRESS}` where the `CW20_ADAPTER_CONTRACT` is the adapter contract address that converts CW20 and the native Bank module. - -We'll share more details about these denom types later on in this document. - -### **Token** - -Token is simply a denom on the Injective chain with some meta information. The metadata includes information like symbol, name, decimals, logo for the particular denom, etc. The metadata of the denom is quite important for a dApp developer as information on the chain is stored in its raw form (for example `1inj` on the chain is represented as `1*10^18inj`) so we need to have a way to show the user human-readable information (numbers, logo, symbol, etc). - -### Token Metadata - -Assets on Injective are represented as denoms. Denoms (and the amounts) are not human readable and this is why we need to have a way to "attach" token metadata information for a particular denom. - -Let's recap the types of denoms we have in the Getting Started section: - -* **Native denoms** - there is only one denom of this type, the `inj` denom which represented the native coin of Injective, -* **Peggy denoms** - these denoms represent assets bridged over from Ethereum to Injective using the Peggy bridge. They have the following format `peggy{ERC20_CONTRACT_ADDRESS}` -* **IBC denoms** - these denoms represent assets bridged over from other Cosmos chains through IBC. They have the following format `ibc/{hash}`. -* **Insurance Fund Denoms** - these denoms represent token shares of the insurance funds created on Injective. The have the following format `share{id}` -* **Factory Denoms** - - -We maintain our token metadata list off-chain for faster access to the[ injective-lists](https://github.com/InjectiveLabs/injective-lists/tree/master/tokens) repository. diff --git a/.gitbook/getting-started/token-standards/cw20-standard.md b/.gitbook/getting-started/token-standards/cw20-standard.md deleted file mode 100644 index 1aae2ee3..00000000 --- a/.gitbook/getting-started/token-standards/cw20-standard.md +++ /dev/null @@ -1,3 +0,0 @@ -# CW20 Standard - -The CW20 token standard provides a framework for the permissionless creation and management of fungible tokens that more closely resembles the [ERC20 standard](https://ethereum.org/en/developers/docs/standards/tokens/erc-20/). As stated above, the TokenFactory is encouraged due to its native integration with the Cosmos SDK, but should you wish to use the CW20 standard for any reason, you can convert CW20 tokens to TokenFactory tokens and vice versa using the [CW20 Adapter](https://github.com/CosmWasm/cw-plus/blob/main/packages/cw20/README.md). For more information regarding the CW20 standard, see its formal specification [here](https://github.com/CosmWasm/cw-plus/blob/main/packages/cw20/README.md). diff --git a/.gitbook/getting-started/token-standards/inj-coin.md b/.gitbook/getting-started/token-standards/inj-coin.md deleted file mode 100644 index 1c545dee..00000000 --- a/.gitbook/getting-started/token-standards/inj-coin.md +++ /dev/null @@ -1,68 +0,0 @@ -# INJ coin - -INJ is the native asset powering Injective and its broader ecosystem. Each component of INJ is deliberately engineered to cultivate a thriving Web3 ecosystem. As the native asset of the blockchain, INJ plays a central role in facilitating various operations on Injective. Integral to Injective’s custom implementation of the Tendermint Proof-of-Stake (PoS) consensus framework, INJ is crucial for securing the network through staking. Additionally, INJ functions as Injective’s governance token and serves as a means of exchange within the broader Injective ecosystem. Notably, INJ distinguishes itself from other native assets on PoS chains by leveraging core Injective modules to engineer deflationary characteristics through an innovative burn and a dynamic supply mechanism. - -### Base Denomination - -INJ uses [Atto](https://en.wikipedia.org/wiki/Atto-) as the base denomination to maintain parity with Ethereum. - -``` -1 inj = 1×10⁻¹⁸ INJ -``` - -This matches Ethereum's denomination: - -``` -1 wei = 1x10⁻¹⁸ ETH -``` - -### Injective Tokenomics and Utility - -#### 1. Security and Staking - -Injective is secured via staking, which is an essential use case for INJ. Validators and delegators can freely participate in the Injective network via staking. Validators operate nodes on Injective, and delegators can assign INJ to a particular node of choice. Staked INJ enables a robust decentralized environment in which security is ensured via penalty and reward systems. - -A validator’s staked INJ is subject to slashing in the event of malicious behavior or failure to effectively fulfill responsibilities. Additionally, INJ is used to reward validators for participation in transaction validation and block creation. Rewards for validators comprise newly minted INJ (block rewards) and a portion of the associated transaction fees. - -Holders of INJ may also participate in staking without necessarily having to operate a node to earn a share of validator rewards. To do so, users delegate INJ to validator(s), which can be done through supported browser wallets, or directly through the Injective Hub. In return for locking up INJ, users earn a share of the validator’s INJ rewards, less the fee charged by the selected validator (commission), distributed pro rata. A user’s staked INJ is also subject to slashing in the event the validator delegated to incurs a slashing event. This ensures that both validators and delegators are aligned in contributing to the overall security of the network. - -Beyond securing the Injective chain, INJ also extends its security serviceability to the broader ecosystem through Electro Chains. These Injective-based rollups offer a myriad of technical advantages, such as supporting multiple virtual ma- chines as seen with inEVM.5 Since these rollups settle to Injective, INJ powers the foundational security layer for these networks. This interconnected security framework underscores the pivotal role of INJ in maintaining the integrity and robustness of not only the Injective network, but also the diverse ecosystem of Electro Chains. - -#### 2. Governance - -INJ is utilized for community led governance across all parameters of the chain. Injective uniquely has a permissioning layer for smart contract uploads as well, meaning that the community of stakers must vote in order to instantiate a smart contract on mainnet. This empowers the community to directly govern all parameters of Injective as a whole. - -For governance, INJ is used for proposal creation and token-weighted voting on active proposals. As a spam deterrent, Injective requires a minimum deposit, made in INJ, for the proposal to move on to the voting stage. This deposit threshold can either be met entirely by the proposer, or cumulatively by other users contributing INJ to the proposal deposit. If the minimum deposit amount is not reached by the time the maximum deposit period elapses, the proposal will be automatically rejected, and the deposit(s) burned. Additionally, if the proposal does not pass upon voting period expiry, the proposal deposit is burned. - -Proposal voting occurs during a preset voting period, which is set via gover- nance and invariably applied to all governance votes. During the voting process, only staked INJ is eligible to participate in voting. Hence, only validators and delegators can vote on active proposals. Voting power is token-weighted, meaning that 1 INJ equals 1 vote. Delegators are not required to actively participate in governance to maintain their status. However, they have the option to vote directly on proposals. If a delegator does not vote, their voting power will automatically be inherited by the validator to whom they have delegated, for that specific voting event. - -INJ is used to govern all aspects of the chain, including: - -* Auction Module Parameters -* Exchange Module Custom proposals and Parameters -* Insurance Module Parameters -* Oracle Module Custom proposals -* Peggy Module Parameters -* Wasmx Module Parameters -* Software upgrades -* Cosmos-SDK module parameters for the [auth](https://docs.cosmos.network/main/modules/auth#parameters), [bank](https://docs.cosmos.network/main/modules/bank), [crisis](https://docs.cosmos.network/main/modules/crisis), [distribution](https://docs.cosmos.network/main/modules/distribution), [gov](https://docs.cosmos.network/main/modules/gov), [mint](https://docs.cosmos.network/main/modules/mint), [slashing](https://docs.cosmos.network/main/modules/slashing), and [staking](https://docs.cosmos.network/main/modules/staking) modules. - -Full details on the governance process can be found [here](https://blog.injectiveprotocol.com/injective-governance-proposal-procedure). - -#### 3. Medium of Exchange - -INJ is used as the default asset to facilitate the purchase and sale of goods and services between parties on the blockchain. Common examples of this are paying for transaction fees (gas), buying/selling NFTs, paying for trading fees, or depositing the asset as collateral. While most goods and services can be denominated in any asset, all transaction fees incurred on Injective are paid in INJ. Additionally, all protocol revenue generated by applications leveraging Injective’s shared liquidity layer via the exchange module is accumulated in INJ. - -#### 4. Exchange dApps Incentives - -The exchange protocol implements a global minimum trading fee of $r\_m=0.1%$ for makers and $r\_t=0.2%$ for takers. As an incentive mechanism to encourage exchange dApps to source trading activity on the exchange protocol, exchange dApps that originate orders into the shared orderbook are rewarded with $\beta = 40%$ of the trading fees arising from all orders that they source. - -#### 5. Exchange Fee Value Accrual - -The remaining $60%$ of the exchange fee will undergo an on-chain buy-back-and-burn event where the aggregate exchange fee basket is auctioned off to the highest bidder in exchange for INJ. The INJ proceeds of this auction are then burned, thus deflating the total INJ supply. - -More details on the auction mechanism can be found here. - -#### 6. Backing Collateral for Derivatives - -INJ can be utilized as an alternative to stablecoins as margin and collateral for Injective's derivatives markets. In some derivative markets, INJ can also be used as backing collateral for insurance pool staking, where stakers can earn interest on their locked tokens. diff --git a/.gitbook/getting-started/token-standards/token-factory.md b/.gitbook/getting-started/token-standards/token-factory.md deleted file mode 100644 index e731c1d1..00000000 --- a/.gitbook/getting-started/token-standards/token-factory.md +++ /dev/null @@ -1,7 +0,0 @@ -# Token Factory - -TokenFactory tokens are tokens that are natively integrated into the bank module of the Cosmos SDK. Their name takes on the format `factory/{creatorAddress}/{subdenom}`. Because tokens are namespaced by the creator address, this allows for permissionless token minting, due to not needing to resolve name collisions. - -This integration provides support for tracking and querying the total supply of all assets, unlike the CW20 standard, which requires querying the smart contract directly. For this reason, using the TokenFactory standard is recommended. Products such as Helix or Mito, for example, are built on the Injective exchange module, which exclusively uses bank tokens. TokenFactory tokens can be created via the injectived CLI, as well as via smart contract. Tokens bridged into Injective via Wormhole are also TokenFactory tokens. - -To learn more about creating your token on Injective, see [here](https://docs.injective.network/develop/guides/token-launch/). To read more about the TokenFactory standard, see [here](https://docs.injective.network/develop/modules/injective/tokenfactory/). diff --git a/.gitbook/getting-started/transactions/README.md b/.gitbook/getting-started/transactions/README.md deleted file mode 100644 index ef57fc49..00000000 --- a/.gitbook/getting-started/transactions/README.md +++ /dev/null @@ -1,19 +0,0 @@ -# Transactions - -When users want to interact with Injective and make state changes, they create transactions. Once the transaction is created, it requires a signature from the private key linked to the account initiating the particular state change. Following the signature, the transaction is broadcasted to Injective. - -After being broadcasted and passing all validations (including signature validation, values validations, etc.), the transaction is included in a block that undergoes network approval via the consensus process. - -### Messages - -In simpler terms, messages are the instructions given to Injective about the desired state change. Messages are module-specific objects that trigger state transitions within the scope of the module they belong to. Every transaction must have at least one message. - -**Additionally, multiple messages can be packed within the same transaction.** Available Messages from each module can be found in the [modules](../../developers/modules/ "mention")section. - -### Transaction Context - -Besides Messages, every transaction has a context. The context includes `fees`, `accountDetails`, `memo`, `signatures`, etc. - -### Transaction Flow - -Every transaction we want to broadcast to Injective has the same flow. The flow consists of three steps: preparing, signing, and broadcasting the transaction. When the transaction is included in a block, the state change that was specified using the Message is applied on Injective. diff --git a/.gitbook/getting-started/transactions/gas-and-fees.md b/.gitbook/getting-started/transactions/gas-and-fees.md deleted file mode 100644 index 6a7a4adb..00000000 --- a/.gitbook/getting-started/transactions/gas-and-fees.md +++ /dev/null @@ -1,44 +0,0 @@ -# Gas and Fees - -## Gas and Fees - -{% hint style="info" %} -Learn about the differences between `Gas` and `Fees` on Injective. - -Pre-requisite Readings -> [Cosmos SDK Gas](https://docs.cosmos.network/main/build/modules/auth#gas--fees) -{% endhint %} - -Gas represents the amount of computational effort required to execute specific operations on the state machine. - -Injective utilizes the concept of gas to track the resource usage of operations during execution. Operations on the Cosmos SDK (which the Injective Protocol is built on) are represented as read or writes done to the chain's store. - -A fee is calculated and charged to the user during a message execution. This fee is calculated from the sum of all gas consumed in a message execution: - -``` -fee = gas * gas price -``` - -Gas is used to make sure that operations do not require an excess amount of computational power to complete and to deter bad-acting users from spamming the network. - -:::tip minimum gas price The minimum gas price set by validators is currently 160,000,000inj. To find the amount paid in INJ, multiply the gas price by the gas amount and divide by 1e18 (INJ has 18 decimals). - -For example: if gas wanted is 104,519, then gas fees = 160,000,000 \* 104,519 / 1e18 = 0.000016723 INJ ::: - -### Cosmos SDK `Gas` - -In the Cosmos SDK, gas is tracked in the main `GasMeter` and the `BlockGasMeter`: - -* `GasMeter`: keeps track of the gas consumed during executions that lead to state transitions. It is reset on every transaction execution. -* `BlockGasMeter`: keeps track of the gas consumed in a block and enforces that the gas does not go over a predefined limit. This limit is defined in the Tendermint consensus parameters and can be changed via governance parameter change proposals. - -More information regarding gas in Cosmos SDK can be found [here](https://docs.cosmos.network/main/basics/gas-fees.html). - -In Cosmos, there are types of operations that are not triggered by transactions that can also result in state transitions. Concrete examples are the `BeginBlock` and `EndBlock` operations and the `AnteHandler` checks, which might also read and write to the store before running the state transition from a transaction. - -#### `BeginBlock` and `EndBlock` - -These operations are defined by the Tendermint Core's Application Blockchain Interface (ABCI) and are defined by each Cosmos SDK module. As their name suggest, they are executed at the beginning and at the end of each block processing respectively (i.e pre and post transaction execution). - -#### `AnteHandler` - -The Cosmos SDK [`AnteHandler`](https://docs.cosmos.network/main/basics/gas-fees.html#antehandler) performs basic checks prior to transaction execution. These checks are usually signature verification, transaction field validation, transaction fees, etc. diff --git a/.gitbook/getting-started/wallet/README.md b/.gitbook/getting-started/wallet/README.md deleted file mode 100644 index 36e41f0f..00000000 --- a/.gitbook/getting-started/wallet/README.md +++ /dev/null @@ -1,46 +0,0 @@ -# Wallet - -The Injective Wallet allows you to monitor your assets on Injective. Assets can be native tokens on Injective, as well as bridged assets from Ethereum, Solana, Polygon and various IBC-enabled chains.[\ -](https://docs.injective.network/learn/injective-hub/) - -There are a variety of different wallets that are supported on Injective. Users can choose to submit transactions on Injective using either their Ethereum native wallets or their Cosmos native wallets. - -### Overview - -Injective's `Account` type uses Ethereum's ECDSA secp256k1 curve for keys. Simply put, Injective's Account is native (compatible) with Ethereum accounts, allowing Ethereum native wallets such as MetaMask to interact with Injective. Popular Cosmos wallets have also integrated with Injective. See below for a list of available Cosmos wallets. - -#### Ethereum-Based Wallets - -As explained above, Ethereum based wallets can be used to interact with Injective. Right now, the most popular Ethereum based wallets are supported on Injective. These include: - -1. [Metamask](https://metamask.io/) -2. [Ledger](https://www.ledger.com/) -3. [Trezor](https://trezor.io/) -4. [Torus](https://toruswallet.io/) - -The process of signing transactions on Injective using an Ethereum native wallet consists of: - -1. Converting the transaction into EIP712 TypedData, -2. Signing the EIP712 TypedData using an Ethereum native wallet, -3. Packing the transaction into a native Cosmos transaction (including the signature), and broadcasting the transaction to the chain. - -This process is abstracted away from the end-user. If you've previously used an Ethereum native wallet, the user experience will be the same. - -#### Cosmos-Based Wallets - -Injective supports the leading wallets compatible with Cosmos and IBC, including: - -1. [Cosmostation](https://www.cosmostation.io/) -2. [Leap](https://www.leapwallet.io/) -3. [Keplr](https://www.keplr.app/) - -#### Injective-Native Wallets - -Currently, [Ninji Wallet](https://ninji.xyz/) is the only Injective-native wallet. Such a wallet is built to synergize specifically with the greater Injective ecosystem. - -#### CEX-Based Wallets - -There are also several wallets developed by centralized exchanges (CEXs) that now support Injective. If you are an active user of these CEXs, using their wallets can provide a more seamless web3 experience. Currently, CEX-based wallets that support Injective are: - -1. [Bitget](https://web3.bitget.com/) -2. [OKX](https://www.okx.com/web3) diff --git a/.gitbook/getting-started/wallet/accounts.md b/.gitbook/getting-started/wallet/accounts.md deleted file mode 100644 index ce25ce08..00000000 --- a/.gitbook/getting-started/wallet/accounts.md +++ /dev/null @@ -1,101 +0,0 @@ -# Accounts - -This section describes the built-in accounts system of Injective. - -{% hint style="info" %} -This document describes the built-in accounts system of Injective. - -Pre-requisite Readings: - -* [Cosmos SDK Accounts](https://docs.cosmos.network/main/basics/accounts) -* [Ethereum Accounts](https://ethereum.org/en/whitepaper/#ethereum-accounts) -{% endhint %} - -Injective defines its custom `Account` type that uses Ethereum's ECDSA secp256k1 curve for keys. This satisfies the [EIP84](https://github.com/ethereum/EIPs/issues/84) for full [BIP44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki) paths. The root HD path for Injective-based accounts is `m/44'/60'/0'/0`. - -### Addresses and Public Keys - -There are 3 main types of `Addresses`/`PubKeys` available by default on Injective: - -* Addresses and Keys for **accounts**, that identify users (e.g. the sender of a `message`). They are derived using the **`eth_secp256k1`** curve. -* Addresses and Keys for **validator operators**, which identify the operators of validators. They are derived using the **`eth_secp256k1`** curve. -* Addresses and Keys for **consensus nodes**, which identify the validator nodes participating in consensus. They are derived using the **`ed25519`** curve. - -| | Address bech32 Prefix | Pubkey bech32 Prefix | Curve | Address byte length | Pubkey byte length | -| ------------------ | --------------------- | -------------------- | --------------- | ------------------- | ------------------ | -| Accounts | `inj` | `injpub` | `eth_secp256k1` | `20` | `33` (compressed) | -| Validator Operator | `injvaloper` | `injvaloperpub` | `eth_secp256k1` | `20` | `33` (compressed) | -| Consensus Nodes | `injvalcons` | `injvalconspub` | `ed25519` | `20` | `32` | - -### Address formats for clients - -`EthAccount`s can be represented in both [Bech32](https://en.bitcoin.it/wiki/Bech32) and hex format for Ethereum's Web3 tooling compatibility. - -The Bech32 format is the default format for Cosmos-SDK queries and transactions through CLI and REST clients. The hex format is the Ethereum `common.Address` representation of a Cosmos `sdk.AccAddress`. - -* Address (Bech32): `inj14au322k9munkmx5wrchz9q30juf5wjgz2cfqku` -* Address ([EIP55](https://eips.ethereum.org/EIPS/eip-55) Hex): `0xAF79152AC5dF276D9A8e1E2E22822f9713474902` -* Compressed Public Key: `{"@type":"/injective.crypto.v1beta1.ethsecp256k1.PubKey","key":"ApNNebT58zlZxO2yjHiRTJ7a7ufjIzeq5HhLrbmtg9Y/"}` - -You can query an account address using the Cosmos CLI or REST clients: - -```bash -# NOTE: the --output (-o) flag will define the output format in JSON or YAML (text) -injectived q auth account $(injectived keys show -a) -o text -| - '@type': /injective.types.v1beta1.EthAccount - base_account: - account_number: "3" - address: inj14au322k9munkmx5wrchz9q30juf5wjgz2cfqku - pub_key: null - sequence: "0" - code_hash: xdJGAYb3IzySfn2y3McDwOUAtlPKgic7e/rYBF2FpHA= -``` - -```bash -# GET /cosmos/auth/v1beta1/accounts/{address} -curl -X GET "http://localhost:10337/cosmos/auth/v1beta1/accounts/inj14au322k9munkmx5wrchz9q30juf5wjgz2cfqku" -H "accept: application/json" -``` - -See the [Swagger API](https://lcd.injective.network/swagger/) reference for the full docs on the accounts API. - -{% hint style="info" %} -The Cosmos SDK Keyring output (i.e `injectived keys`) only supports addresses in Bech32 format. -{% endhint %} - -### Derive Injective Account from a private key/mnemonic - -Below is an example of how to derive an Injective Account from a private key and/or a mnemonic phrase: - -```js -import { Wallet } from 'ethers' -import { Address as EthereumUtilsAddress } from 'ethereumjs-util' - -const mnemonic = "indoor dish desk flag debris potato excuse depart ticket judge file exit" -const privateKey = "afdfd9c3d2095ef696594f6cedcae59e72dcd697e2a7521b1578140422a4f890" -const defaultDerivationPath = "m/44'/60'/0'/0/0" -const defaultBech32Prefix = 'inj' -const isPrivateKey: boolean = true /* just for the example */ - -const wallet = isPrivateKey ? Wallet.fromMnemonic(mnemonic, defaultDerivationPath) : new Wallet(privateKey) -const ethereumAddress = wallet.address -const addressBuffer = EthereumUtilsAddress.fromString(ethereumAddress.toString()).toBuffer() -const injectiveAddress = bech32.encode(defaultBech32Prefix, bech32.toWords(addressBuffer)) -``` - -Below is an example of how to derive a public key from a private key: - -```js -import secp256k1 from 'secp256k1' - -const privateKey = "afdfd9c3d2095ef696594f6cedcae59e72dcd697e2a7521b1578140422a4f890" -const privateKeyHex = Buffer.from(privateKey.toString(), 'hex') -const publicKeyByte = secp256k1.publicKeyCreate(privateKeyHex) - -const buf1 = Buffer.from([10]) -const buf2 = Buffer.from([publicKeyByte.length]) -const buf3 = Buffer.from(publicKeyByte) - -const publicKey = Buffer.concat([buf1, buf2, buf3]).toString('base64') -const type = '/injective.crypto.v1beta1.ethsecp256k1.PubKey' -``` diff --git a/.gitbook/getting-started/wallet/auction.md b/.gitbook/getting-started/wallet/auction.md deleted file mode 100644 index 2cb4527d..00000000 --- a/.gitbook/getting-started/wallet/auction.md +++ /dev/null @@ -1,25 +0,0 @@ -# Auction - -## Burn Auction - -INJ 2.0, released in 2023, made it possible for any application to contribute to the Auction Fund, not just those using the exchange module. - -Additionally, Injective’s April 2024 INJ Burn Upgrade expanded access to this feature, allowing for individual users to make contributions. As a result, any project or user can directly contribute to the Injective Burn Auction, which in turn can boost the overall value and effectiveness of the Burn Auction. - -As of May 2024, over 5,920,000 INJ (∼$154,000,000) has been removed from the total token supply through the Burn Auction. The Burn Auction occurs weekly, ending at 9:00 UTC-4:00. Participation can be conducted via the Injective Hub or direct interaction with the chain itself. - -The complete versatility of INJ is realized through a combination of mechanisms that operate in tandem. Building on Injective’s innovative approach to supply dynamics, the asset is positioned to exhibit deflationary properties through a well-engineered system designed to remove INJ from circulation. This process is facilitated by Injective’s novel Burn Auction system, which effectively reduces the total supply. - -Held regularly, the Burn Auction invites participants to bid on a basket of tokens accumulated from a portion of the revenue generated by participating applications and direct contributions from individual users. The auction operates as an English Auction, where bids are placed using INJ. The highest bidder receives the entire basket of assets at the auction’s expiry. The winning INJ bid is then burned, removing it from the total token supply. - -The Burn Auction is made possible by two modules that are native to Injective, `exchange` and `auction`. These modules are available out-of-the-box for anyone building on Injective, as part of Injective’s core offering of plug-and-play financial primitives. - -### Exchange Module - -The exchange module is one of Injective’s central differentiators from other blockchains. This technical instrument is what powers the shared liquidity environment on Injective and fuels the Burn Auction. The entire process of orderbook management, trade execution, order matching, and settlement occurs on-chain through the logic codified by the module. - -The design feature that is key to the Burn Auction is the built-in revenue-sharing structure for applications employing the exchange module. Herein, a portion of the accrued revenue is allocated to the auction module for inclusion in the current Burn Auction event, while the remaining portion is retained by the application utilizing the module to power its exchange services. - -### Auction Module - -The auction module provides two essential services for the operation of the Burn Auction: token collection and auction orchestration. For token collection, the module periodically gathers tokens from the exchange module, pooling them into an Auction Fund. Importantly, the Auction Fund also receives tokens from applications that do not utilize the exchange module but have opted into participation, as well as from individual user contributions. The auction process itself involves several tasks managed by the auction module, including coordination of the bidding process, determining the winner, delivering the won assets, and burning the winning INJ bid. diff --git a/.gitbook/getting-started/wallet/create-a-wallet.md b/.gitbook/getting-started/wallet/create-a-wallet.md deleted file mode 100644 index 9a712ab9..00000000 --- a/.gitbook/getting-started/wallet/create-a-wallet.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -description: Learn how to create a wallet on Injective using different approaches. ---- - -# Create a wallet - -Creating a wallet on Injective is as simply as sending some funds to your Injective address. In this document we'll outline how to create a wallet using some popular wallet solutions (Metamask, Ledger, etc), but also how to create and fund a wallet using `injectived` in a local CLI environment. - -### Browser Wallets - -You can create an Injective wallet using your preferred wallet by following the [tutorial on our blog](https://blog.injective.com/en/how-to-create-an-injective-wallet-2/). - -### Local Wallets - -You can create an Injective wallet for your development purposes using [injectived](../../toolkits/injectived/ "mention") in a CLI environment. You can do that using the `injectived keys` [command](../../toolkits/injectived/advanced.md#keys). - -You can also learn more about keyring management using `injectived` on this page [1.-setting-up-the-keyring.md](../../nodes/getting-started/running-a-node/1.-setting-up-the-keyring.md "mention") diff --git a/.gitbook/getting-started/wallet/governance.md b/.gitbook/getting-started/wallet/governance.md deleted file mode 100644 index 5ce7e366..00000000 --- a/.gitbook/getting-started/wallet/governance.md +++ /dev/null @@ -1,25 +0,0 @@ -# Governance - -## Governance - -Injective is a community-run blockchain and users who have staked INJ can participate in governance as it relates to the blockchain. Proposals can be submitted to make revisions to Injective programs, tech upgrades, or any other Injective related changes that impact the entire Injective ecosystem. - -Within Injective Hub, new proposals are submitted through the governance portal and voted on by the entire community. - -### Submitting a request - -To submit a new request, you must create a proposal that outlines what you would like to change, what areas within Injective this change may impact, and why you are requesting this change. - -Upon creating a proposal, you must deposit at least 10 INJ (10e19 inj) to submit it for governance. This is to ensure that you are an active participant of the Injective community, and thus eligible to make proposal requests. - -For the proposal to pass to the voting stage, 100 INJ (10e20 inj) must also be deposited. This can be deposited directly by you or in collaboration with other community members. - -### Voting Period - -Once the proposal and deposit is submitted, the proposal will go through a four-day voting period. - -33.4% of INJ holders must vote on a proposal for the vote to be considered, and 50% of those votes must be “yes” for the proposal to pass. - -### Voting Outcome - -If a proposal passes, Injective contributors will begin to work together to put into effect the new request. If 33.4% of the total vote is `NoWithVeto`, quorum is not met, or the minimum deposit isn't reached, the deposit will be burned. All other vote outcomes get their deposits refunded. diff --git a/.gitbook/getting-started/wallet/staking.md b/.gitbook/getting-started/wallet/staking.md deleted file mode 100644 index 6f2be082..00000000 --- a/.gitbook/getting-started/wallet/staking.md +++ /dev/null @@ -1,21 +0,0 @@ -# Staking - -Staking is the process of locking up your assets (in this case INJ) in order to validate transactions on the blockchain. Users who stake their assets are usually eligible for staking rewards. - -Injective follows a proof-of-stake mechanism, in which users can stake their INJ tokens with certain Injective nodes that validate transactions (validators). In return, the user can obtain staking rewards in INJ. - -### Stake INJ - -Stake your INJ to a validator to start earning rewards. - -### Withdraw staking rewards - -Rewards start accruing the moment you stake INJ. Monitor your rewards in the staking section of Injective Hub. Once you have earned a sufficient amount of rewards, you may withdraw them at any time. - -### Redelegate - -Redelegating lets you instantly transfer staked INJ from one validator to another without undergoing the 21-day unstaking period. - -### Undelegate - -Undelegating INJ is the process of unstaking your assets from a validator, which takes 21 days to complete. diff --git a/.gitbook/glossary.md b/.gitbook/glossary.md deleted file mode 100644 index 03d16504..00000000 --- a/.gitbook/glossary.md +++ /dev/null @@ -1,249 +0,0 @@ ---- -description: >- - Pocket size cheat sheet for Injective. Use this glossary to learn about terms - specific to Injective. ---- - -# Glossary - -Active set - -The validators that participate in consensus and receive rewards. - -### Airdrops - -Additional rewards given to delegators through certain validators that are separate from staking rewards. Airdrops are generally given by applications in the Injective ecosystem to increase visibility. - -### Arbitrage - -A process by which users seek to capitalize on a price difference across markets. Arbitrageurs typically purchase assets in one market and sell them in another market for a higher price. - -### Blockchain - -An unchangeable ledger of transactions copied among a network of independent computer systems. - -### Blocks - -Groups of information stored on a blockchain. Each block contains transactions that are grouped, verified, and signed by validators. - -### Bonded validator - -A validator in the active set participating in consensus. Bonded validators are able to earn rewards. - -### Bonding - -When a user delegates or bonds INJ to a validator to receive staking rewards. Validators never have ownership of a delegator's INJ, even when bonded. Delegating, bonding, and staking generally refer to the same process. - -### Burn - -The permanent destruction of assets. Injective burns INJ after each burn auction. - -### Burn Auction - -A weekly event in which community members can use INJ to bid for 60% of all exchange fees collected by Injective. The INJ used by the winning bidder will be burnt. - -### Commission - -The percentage of staking rewards a validator keeps before distributing the rest of the rewards to delegators. A validator’s income relies solely on this commission. Validators set their own commission rates. - -### Community pool - -A special fund designated for funding community projects. Any community member can create a governance proposal to spend the tokens in the community pool. If the proposal passes, the funds are spent as specified in the proposal. - -### Consensus - -A system used by validators or miners to agree that each block of transactions in a blockchain is correct. Injective uses the Tendermint consensus framework. Validators earn rewards for participating in consensus. Visit the [Tendermint official documentation site](https://docs.tendermint.com/) for more information. - -### Cosmos-SDK - -The open-source framework the Injective blockchain is built on. For more information, check out the [Cosmos SDK Documentation](https://docs.cosmos.network/). - -### CosmWasm - -The library utilized by Injective to power on-chain smart contracts. For more information, check out the CosmWasm Documentation. - -### dApp - -Decentralized application. An application built on a decentralized platform. - -### DDoS - -Distributed denial of service attack. When an attacker floods a network with traffic or requests in order to disrupt service. - -### DeFi - -Decentralized finance. A movement away from traditional finance and toward systems that do not require financial intermediaries. - -### Delegate - -When users or delegators add their INJ to a validator's stake in exchange for rewards. Delegated INJ is bonded to a validator. Validators never have ownership of a delegator's INJ. Delegating, bonding, and staking generally refer to the same process. - -### Delegator - -A user who delegates, bonds, or stakes INJ to a validator to earn rewards. Delegating, bonding, and staking generally refer to the same process. - -### Devnet - -Development network. A network that operates independently of the mainnet, allowing users to test new features or products without disrupting the primary network. - -### Frequent Batch Auction (FBA) - -The model used by Injective for on-chain order matching. This model uses capital more efficiently compared to Continuous Double Auction (CDA), which is utilized by most of the Centralized exchanges offering crypto derivatives and traditional financial markets. The Frequent Batch Auction model also eliminates front-running possibilities. - -### Full node - -A computer connected to the \[Injective mainnet that can validate transactions and interact with Injective. All active validators run full nodes. - -### Gas Fees - -Compute fees added on to all transactions to avoid spamming. Validators set minimum gas prices and reject transactions that have implied gas prices below this threshold. - -### Governance - -Governance is the democratic process that allows users and validators to make changes to Injective. Community members submit, vote, and implement proposals. One staked INJ is equal to one vote. - -### Governance proposal - -A written submission for a change or addition to the Injective protocol. Topics of proposals can vary from community pool spending, software changes, parameter changes, or any change pertaining to Injective. - -### IBC - -Inter-Blockchain Communication. The technology that enables different blockchains to interact with each other. IBC allows for assets to be traded and transacted across different blockchains. - -### INJ - -The native token of Injective. - -### injectived - -The command-line interface for interacting with an Injective node. - -For more information on injectived, see `injectived` guides. - -### Injective core - -The official source code for Injective. - -For more information on the Injective core, see Injective core modules. - -### Injective Hub - -Inejctive's platform for wallets, governance, staking and INJ burn auctions. - -To learn about the features of Injective Hub, visit the Injective Hub guide. - -### Inactive set - -Validators that are not in the active set. These validators do not participate in consensus and do not earn rewards. - -### Jailed - -Validators who misbehave are jailed or excluded from the active set for a period of time. - -### Maximum Extractable Value (MEV) - -The maximum value that can be extracted from block production in excess of the standard block reward and gas fees by including, excluding, and changing the order of transactions in a block. - -Injective is MEV-resistant. - -### Module - -A section of the Injective core that represents a particular function of Injective. Visit the Injective core module specifications for more information. - -### Oracle - -A 3rd party service enabling Injective to access external, real-world data. Typically, this is the price feed. - -### Pools - -Groups of tokens. Supply pools represent the total supply of tokens in a market. - -### Proof of Stake - -A validation method utilized by blockchains in which validators are chosen to propose blocks according to the number of coins they hold. - -### Quorum - -The minimum amount of votes needed to make an election viable. 33% of all staked INJ must vote to meet quorum. If quorum is not met before the voting period ends, the proposal fails, and the proposer's deposit is burned. - -### Redelegate - -When a delegator wants to transfer their bonded INJ to a different validator. Redelegating INJ is instant and does not require a 21-day unbonding period. - -### Rewards - -Revenue generated from fees given to validators and disbursed to delegators. - -### Self-delegation - -The amount of INJ a validator bonds to themselves. Also referred to as self-bond. - -### Slashing - -Punishment for validators that misbehave. Validators lose part of their stake when they get slashed. - -### Slippage - -The difference in an asset’s price between the start and end of a transaction. - -### Stake - -The amount of INJ bonded to a validator. - -### Staking - -When a user delegates or bonds their INJ to an active validator to receive rewards. Bonded INJ adds to a validator's stake. Validators provide their stakes as collateral to participate in the consensus process. Validators with larger stakes are chosen to participate more often. Validators receive staking rewards for their participation. A validator's stake can be slashed if the validator misbehaves. Validators never have ownership of a delegator's INJ, even when staking. - -For more information on staking, visit the concepts page. - -### Tendermint consensus - -The consensus framework used by Injective. First, a validator proposes a new block. Other validators vote on the block in two rounds. If a block receives a two-thirds majority or greater of yes votes in both rounds, it gets added to the blockchain. Validators get rewarded with the block's transaction fees. Proposers get rewarded extra. Each validator is chosen to propose based on their weight. Check out the [Tendermint official documentation](https://docs.tendermint.com/) for more information. - -### Mainnet - -Injective's blockchain network where all transactions take place. - -### Testnet - -A version of the mainnet used for testing. The testnet does not use real assets. You can use the testnet to get familiar with transactions and the overall network. - -### Total stake - -The total amount of INJ bonded to a delegator, including self-bonded INJ. - -### Unbonded validator - -A validator that is not in the active set and does not participate in consensus or receive rewards. Some unbonded validators may be jailed. - -### Unbonding validator - -A validator transitioning from the active set to the inactive set. An unbonding validator does not participate in consensus or earn rewards. The unbonding process takes 21 days. - -### Unbonded INJ - -INJ that can be freely traded and is not staked to a validator. - -### Unbonding - -When a delegator decides to undelegate their INJ from a validator. This process takes 21 days. No rewards accrue during this period. This action cannot be stopped once executed. - -### Unbonding INJ - -INJ that is transitioning from bonded to unbonded. INJ that is unbonding cannot be traded freely. The unbonding process takes 21 days. No rewards accrue during this period. This action cannot be stopped once executed. - -### Undelegate - -When a delegator no longer wants to have their INJ bonded to a validator. This process takes 21 days. No rewards accrue during this period. This action cannot be stopped once executed. - -### Uptime - -The amount of time a validator is active in a given timeframe. Validators with low up time may be slashed. - -### Validator - -An Injective blockchain miner that is responsible for verifying transactions on the blockchain. Validators run programs called full nodes that allow them to participate in consensus, verify blocks, participate in governance, and receive rewards. Only the active set of validators can participate in consensus. - -### Weight - -The measure of a validator's total stake. Validators with higher weights get selected more often to propose blocks. A validator's weight is also a measure of their voting power in governance. diff --git a/.gitbook/guides/README.md b/.gitbook/guides/README.md deleted file mode 100644 index d0e9e1dd..00000000 --- a/.gitbook/guides/README.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -description: >- - This section contains user-facing (general) guides. Basically guides for the - most commonly asked questions on Injective. ---- - -# Guides - -## List of existing guides - -
Create a walletLearn how to create Injective walletwallet-hero (1).pnghttps://blog.injective.com/en/how-to-create-an-injective-wallet-2/
BridgingLearn how to bridge your assets to Injectivebridge-hero.pngbridge
Launch a tokenLearn how to launch your own tokenlaunch-token-hero.pnglaunch-a-token.md
Launch a marketLearn how to launch a trading pair on Injectivelaunch-market-hero.pnglaunch-a-market.md
Get INJLearn how to get INJinj-hero.pnghttps://injective.com/getinj
BlogVisit our blog for more guidesblog-hero.pnghttps://blog.injective.com/
- diff --git a/.gitbook/guides/bridge/README.md b/.gitbook/guides/bridge/README.md deleted file mode 100644 index 6b7a386e..00000000 --- a/.gitbook/guides/bridge/README.md +++ /dev/null @@ -1,2 +0,0 @@ -# Bridge - diff --git a/.gitbook/guides/launch-a-market.md b/.gitbook/guides/launch-a-market.md deleted file mode 100644 index 92f43ca5..00000000 --- a/.gitbook/guides/launch-a-market.md +++ /dev/null @@ -1,43 +0,0 @@ -# Launch a market - -{% hint style="info" %} -The prerequisite for launching a market is to [launch-a-token.md](launch-a-token.md "mention") -{% endhint %} - -Launching a trading pair on Injective is quick, easy, and best of all it's permissionless! - -The following tutorial assumes the pair is listed with an ERC-20 token bridged from Ethereum as the base asset, paired with INJ as the quote asset. - -For an Injective-native token, skip the bridging portion and head straight to step 6. - -1. Navigate to the [Injective Bridge](http://bridge.injective.network/) to begin the process of bridging your chosen ERC-20 token from Ethereum to Injective using the Peggy bridge. - -![Injective Bridge](https://docs.injective.network/assets/images/ltp1-c1209664f44de66d2d290c78215a52db.png) - -2. Click the dropdown, scroll to the bottom, and click "add" next to the advanced tool to add a custom ERC-20 token using the token address, which you may want to verify on a trusted source like CoinGecko. - -![Launch trading Pair](https://docs.injective.network/assets/images/ltp2-2cf6d9420ceec3e5a88fd4de94f6229b.png) - -3. Copy and paste the correct contract address, and click "add." - -![Launch trading Pair](https://docs.injective.network/assets/images/ltp3-26764cf278d2d93dcc46433762c7e594.png) - -4. Now enter the desired amount of the ERC-20 token you wish to bridge, click "approve," confirm the transaction, then click "review," confirm the transaction, and wait. - -![Launch trading Pair](https://docs.injective.network/assets/images/ltp4-f8f97c3328c04389962ac3deb9b137a9.png) ![Launch trading Pair](https://docs.injective.network/assets/images/ltp6-7812b6fe19b088c68b8d2a9bda8df05c.png) ![Launch trading Pair](https://docs.injective.network/assets/images/ltp7-d83a52c9fc794a2934ea8f2a5371595a.png) ![Launch trading Pair](https://docs.injective.network/assets/images/ltp8-da76aaaa5ee9f233ea47bbcb1f5b53bf.png) - -5. Once the approve spend and deposit transactions are confirmed on the Ethereum blockchain, you will see the progress of the bridging transaction. Once the transaction is confirmed on Injective, your bridged ERC-20 token will be available in your Injective wallet. (Note, if you used MetaMask with the source chain, by default your bridged tokens will be sent to the inj address linked to your MetaMask. This can be changed by clicking the lock icon next to the recipient address at the beginning of step 4.) - -![Launch trading Pair](https://docs.injective.network/assets/images/ltp9-28e71eabdedb5ca3cf4fb995e1a25af8.png) - -6. After the bridging transaction is complete, you're able to list the token permissionlessly on Injective by navigating to the [Injective Hub](http://hub.injective.network/proposal/create). - -![Launch trading Pair](https://docs.injective.network/assets/images/ltp10-aa2a95266e47c43e095ad88926a07db3.png) - -7. Choose "instant spot market launch" from the first dropdown, and specify a ticker. In this example, let's use PEPE/INJ. Now choose the base token from the dropdown. However, beware, several tokens might exist under the same ticker. Always match the correct token address. In this case, as the token was bridged using the Peggy bridge, the address will be peggy followed by the ERC-20 contract address. - -![Launch trading Pair](https://docs.injective.network/assets/images/ltp11-690a7c29af0ed5b64d282bb0da8cb0cd.png) - -8. Now choose the correct quote denom, in this case, inj. (Note, if you wish to pair the token with USDT, make sure to select the "correct" USDT address, which is peggy followed by the ERC-20 contract address for USDT.) Finally, specify a minimum price tick size and minimum quantity tick size. Because PEPE/INJ would trade at a fraction of a penny, the minimum ticks are set accordingly. - -![Launch trading Pair](https://docs.injective.network/assets/images/ltp11-690a7c29af0ed5b64d282bb0da8cb0cd.png) diff --git a/.gitbook/guides/launch-a-token.md b/.gitbook/guides/launch-a-token.md deleted file mode 100644 index 2ce52ccb..00000000 --- a/.gitbook/guides/launch-a-token.md +++ /dev/null @@ -1,237 +0,0 @@ -# Launch a token - -Within this document, we'll explain how to launch a token on Injective. - -There are two options on how to launch a token on Injective - -## Bridging - -The easiest way to launch a token on Injective is by bridging your existing assets from one of the supported networks that Injective is interoperable with. There are guides in the [bridge](bridge/ "mention")sections that you can reference to bridge assets from other networks to Injective. - -Once the briding process is completed, a token will be created on Injective which you can then use to [launch-a-market.md](launch-a-market.md "mention"). - -## Creating new token - -You can also create a new token on Injective using the `tokenFactory` module. There are multiple ways on how to achieve this. - -### Using the InjectiveHub - -The [InjectiveHub](https://hub.injective.network/token-factory/) web app provides you the ability to create and manage tokens seamlessly, creating a market on Injective's [native orderbook](https://docs.injective.network/develop/modules/injective/exchange), etc. - -### Using the TokenStation[​](https://docs.injective.network/develop/guides/token-launch/#3-via-tokenstation) - -The [TokenStation](https://www.tokenstation.app/) web app provides you the ability to create and manage tokens seamlessly, creating a market on Injective's [native orderbook](https://docs.injective.network/develop/modules/injective/exchange), launching an airdrop, and much more. - -### Using the DojoSwap[​](https://docs.injective.network/develop/guides/token-launch/#4-via-dojoswap) - -Similar to above, you can utilize [DojoSwap's Market Creation module](https://docs.dojo.trading/introduction/market-creation) to create, manage, and list your token, along with several other useful features. - -### Programmatically - -#### Using TypeScript - -You can learn more about Launching a token on the [TypeScript Documentation](https://docs.ts.injective.network/readme/assets/creating-tokens). - -#### Using Injective CLI - -{% hint style="info" %} -You have to have `injectived` installed locally before proceeding with this tutorial. You cal learn more about it on the [getting-started](../getting-started/ "mention")page in the Nodes section. -{% endhint %} - -Once you have `injectived` installed and a key added, you can use the CLI to launch your token: - -1. **Create a tokenfactory denom** - -The fee for creating a factory denom is `0.1 INJ`. - -```bash -injectived tx tokenfactory create-denom ak --from=YOUR_KEY --chain-id=injective-888 --node=https://testnet.tm.injective.network:443 --gas-prices=500000000inj --gas 1000000 -``` - -Tokens are namespaced by the creator address to be permissionless and avoid name collision. In the example above, the subdenom is `ak` but the denom naming will be `factory/{creator address}/{subdenom}`. - -2. **Submit token metadata** - -To get your token visible on Injective dApps, you have to submit it's metadata. - -```bash -injectived tx tokenfactory set-denom-metadata "My Token Description" 'factory/inj17vytdwqczqz72j65saukplrktd4gyfme5agf6c/ak' AKK AKCoin AK '' '' '[ -{"denom":"factory/inj17vytdwqczqz72j65saukplrktd4gyfme5agf6c/ak","exponent":0,"aliases":[]}, -{"denom":"AKK","exponent":6,"aliases":[]} -]' 6 --from=YOUR_KEY --chain-id=injective-888 --node=https://sentry.testnet.tm.injective.network:443 --gas-prices=500000000inj --gas 1000000 -``` - -This command expects the following arguments: - -
injectived tx tokenfactory set-denom-metadata [description] [base] [display] [name] [symbol] [uri] [uri-hash] [denom-unit (json)] [decimals]
-
- -3. #### Mint tokens - -Once you have created your token and submitted the token metadata, it's time to mint your tokens. - -```bash -injectived tx tokenfactory mint 1000000factory/inj17vytdwqczqz72j65saukplrktd4gyfme5agf6c/ak --from=gov --chain-id=injective-888 --node=https://sentry.testnet.tm.injective.network:443 --gas-prices=500000000inj --gas 1000000 -``` - -This command will mint 1 token, assuming your token has 6 decimals. - -4. **Burn tokens** - -The admin of the token, can also burn the tokens. - -```bash -injectived tx tokenfactory burn 1000000factory/inj17vytdwqczqz72j65saukplrktd4gyfme5agf6c/ak --from=gov --chain-id=injective-888 --node=https://sentry.testnet.tm.injective.network:443 --gas-prices=500000000inj --gas 1000000 -``` - -5. **Change admin** - -It's recommended once you have minted the initial supply to change admin to the `null` address to make sure that the supply of the token cannot be manipulated. Once again, the admin of the token can mint and burn supply anytime. The `NEW_ADDRESS`, as explained above in most of the cases should be set to `inj1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqe2hm49`. - -```bash -injectived tx tokenfactory change-admin factory/inj17vytdwqczqz72j65saukplrktd4gyfme5agf6c/ak NEW_ADDRESS --from=gov --chain-id=injective-888 --node=https://sentry.testnet.tm.injective.network:443 --gas-prices=500000000inj --gas 1000000 -``` - -{% hint style="info" %} -The examples above are for testnet. If you want to run them on mainnet, do the following changes: - -`injective-888` > `injective-1` - -`https://sentry.testnet.tm.injective.network:443` > `http://sentry.tm.injective.network:443` -{% endhint %} - -#### Using Cosmwasm - -To create and manage a bank token programmatically via a smart contract, one can use the following messages found in the [`injective-cosmwasm`](https://github.com/InjectiveLabs/cw-injective/blob/6b2d549ff99912b9b16dbf91a06c83db99b5dace/packages/injective-cosmwasm/src/msg.rs#L399-L434) package: - -\ -`create_new_denom_msg` - -```rust -pub fn create_new_denom_msg(sender: String, subdenom: String) -> CosmosMsg { - InjectiveMsgWrapper { - route: InjectiveRoute::Tokenfactory, - msg_data: InjectiveMsg::CreateDenom { sender, subdenom }, - } - .into() -} -``` - -Purpose: Creates a message to create a new token denomination using the tokenfactory module. - -Parameters: - -* `sender`: The address of the account initiating the creation. -* `subdenom`: The sub-denomination identifier for the new token. - -Returns: A `CosmosMsg` wrapped in an `InjectiveMsgWrapper`, ready to be sent to the Injective blockchain. - -Example: - -```rust -let new_denom_message = create_new_denom_msg( - env.contract.address, // Sender's address - "mytoken".to_string(), // Sub-denomination identifier -); -``` - -#### `create_set_token_metadata_msg` - -```rust -pub fn create_set_token_metadata_msg(denom: String, name: String, symbol: String, decimals: u8) -> CosmosMsg { - InjectiveMsgWrapper { - route: InjectiveRoute::Tokenfactory, - msg_data: InjectiveMsg::SetTokenMetadata { - denom, - name, - symbol, - decimals, - }, - } - .into() -} -``` - -Purpose: Creates a message to set or update metadata for a token. - -Parameters: - -* `denom`: The denomination identifier of the token. -* `name`: The full name of the token. -* `symbol`: The symbol of the token. -* `decimals`: The number of decimal places the token uses. - -Returns: A `CosmosMsg` wrapped in an `InjectiveMsgWrapper`, ready to be sent to the Injective blockchain. - -Example: - -```rust -let metadata_message = create_set_token_metadata_msg( - "mytoken".to_string(), // Denomination identifier - "My Custom Token".to_string(), // Full name - "MYT".to_string(), // Symbol - 18, // Number of decimals -); -``` - -#### `create_mint_tokens_msg` - -```rust -pub fn create_mint_tokens_msg(sender: Addr, amount: Coin, mint_to: String) -> CosmosMsg { - InjectiveMsgWrapper { - route: InjectiveRoute::Tokenfactory, - msg_data: InjectiveMsg::Mint { sender, amount, mint_to }, - } - .into() -} -``` - -Purpose: Creates a message to mint new tokens. The token must be a tokenfactory token and the sender must be the token admin. - -Parameters: - -* `sender`: The address of the account initiating the mint operation. -* `amount`: The amount of tokens to mint. -* `mint_to`: The recipient address where the newly minted tokens should be sent. - -Returns: A `CosmosMsg` wrapped in an `InjectiveMsgWrapper`, ready to be sent to the Injective blockchain. - -Example: - -```rust -let mint_message = create_mint_tokens_msg( - env.contract.address, // Sender's address - Coin::new(1000, "factory//mytoken"), // Amount to mint - "inj1...".to_string(), // Recipient's address -); -``` - -#### `create_burn_tokens_msg` - -```rust -pub fn create_burn_tokens_msg(sender: Addr, amount: Coin) -> CosmosMsg { - InjectiveMsgWrapper { - route: InjectiveRoute::Tokenfactory, - msg_data: InjectiveMsg::Burn { sender, amount }, - } - .into() -} -``` - -Purpose: Creates a message to burn tokens. The token must be a tokenfactory token and the sender must be the token admin. - -Parameters: - -* `sender`: The address of the account initiating the burn operation. -* `amount`: The amount of tokens to burn. - -Returns: A `CosmosMsg` wrapped in an `InjectiveMsgWrapper`, ready to be sent to the Injective blockchain. - -Example: - -```rust -let burn_message = create_burn_tokens_msg( - env.contract.address, // Sender's address - Coin::new(500, "factory//mytoken"), // Amount to burn -); -``` diff --git a/.gitbook/nodes/getting-started/README.md b/.gitbook/nodes/getting-started/README.md deleted file mode 100644 index 406e94e8..00000000 --- a/.gitbook/nodes/getting-started/README.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -description: >- - This section helps node operators and validators to run, upgrade and maintain - their sentry/validator nodes. ---- - -# Getting Started - -🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 - -This page is currently under work in progress. - -🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 diff --git a/.gitbook/nodes/getting-started/interact-with-a-node.md b/.gitbook/nodes/getting-started/interact-with-a-node.md deleted file mode 100644 index ec63666f..00000000 --- a/.gitbook/nodes/getting-started/interact-with-a-node.md +++ /dev/null @@ -1,194 +0,0 @@ -# Interact with a node - -There are multiple ways to interact with a node: the CLI, gRPC, or the REST endpoints. - -## Using the CLI - -You can use the `injectived` CLI to interact with a node. If you are interacting with a node in your local private network, make sure the node is running in the terminal before you use the CLI. - -For more details on how to use `injectived`, go to Using `injectived`. - -## Using gRPC - -The Protobuf ecosystem developed tools for different use cases, including code-generation from `*.proto` files into various languages. These tools allow clients to be built easily. Often, the client connection (i.e. the transport) can be plugged and replaced very easily. Let's explore a popular transport method, gRPC. - -Since the code generation library largely depends on your own tech stack, we will only present two alternatives: - -* `grpcurl` for generic debugging and testing -* programmatically via Go, Python, or TS - -### grpcurl - -[grpcurl](https://github.com/fullstorydev/grpcurl) is like `curl` but for gRPC. It is also available as a Go library, but we will use it only as a CLI command for debugging and testing purposes. Follow the instructions in the previous link to install it. - -Assuming you have a local node running (either a localnet, or connected a live network), you should be able to run the following command to list the Protobuf services available (you can replace `localhost:9000` by the gRPC server endpoint of another node, which is configured under the `grpc.address` field inside `app.toml`: - -```bash -grpcurl -plaintext localhost:9090 list -``` - -You should see a list of gRPC services, like `cosmos.bank.v1beta1.Query`. This is called reflection, which is a Protobuf endpoint returning a description of all available endpoints. Each of these represents a different Protobuf service, and each service exposes multiple RPC methods you can query against. - -In order to get a description of the service you can run the following command: - -```bash -# Service we want to inspect -grpcurl \ - localhost:9090 \ - describe cosmos.bank.v1beta1.Query -``` - -It's also possible to execute an RPC call to query the node for information: - -```bash -grpcurl \ - -plaintext - -d '{"address":"$MY_VALIDATOR"}' \ - localhost:9090 \ - cosmos.bank.v1beta1.Query/AllBalances -``` - -#### **Query for historical state using grpcurl** - -You may also query for historical data by passing some [gRPC metadata](https://github.com/grpc/grpc-go/blob/master/Documentation/grpc-metadata.md) to the query: the `x-cosmos-block-height` metadata should contain the block to query. Using grpcurl as above, the command looks like: - -```bash -grpcurl \ - -plaintext \ - -H "x-cosmos-block-height: 279256" \ - -d '{"address":"$MY_VALIDATOR"}' \ - localhost:9090 \ - cosmos.bank.v1beta1.Query/AllBalances -``` - -Assuming the state at that block has not yet been pruned by the node, this query should return a non-empty response. - -### Programmatically - -{% hint style="info" %} -The following examples are in Go, but the Python and TS SDKs can also be used to programatically interact with a node/Injective. - -* [TypeScript Examples](https://docs.ts.injective.network/core-modules) -* [Python Examples](https://github.com/InjectiveLabs/sdk-python/tree/master/examples) -{% endhint %} - -The following snippet shows how to query the state using gRPC inside a Go program. The idea is to create a gRPC connection, and use the Protobuf-generated client code to query the gRPC server. - -```go -import ( - "context" - "fmt" - - "google.golang.org/grpc" - - sdk "github.com/cosmos/cosmos-sdk/types" - "github.com/cosmos/cosmos-sdk/types/tx" -) - -func queryState() error { - myAddress, err := sdk.AccAddressFromBech32("inj...") - if err != nil { - return err - } - - // Create a connection to the gRPC server. - grpcConn := grpc.Dial( - "127.0.0.1:9090", // your gRPC server address. - grpc.WithInsecure(), // The SDK doesn't support any transport security mechanism. - ) - defer grpcConn.Close() - - // This creates a gRPC client to query the x/bank service. - bankClient := banktypes.NewQueryClient(grpcConn) - bankRes, err := bankClient.Balance( - context.Background(), - &banktypes.QueryBalanceRequest{Address: myAddress, Denom: "inj"}, - ) - if err != nil { - return err - } - - fmt.Println(bankRes.GetBalance()) // Prints the account balance - - return nil -} -``` - -#### **Query for historical state using Go** - -Querying for historical blocks is done by adding the block height metadata in the gRPC request. - -```go -import ( - "context" - "fmt" - - "google.golang.org/grpc" - "google.golang.org/grpc/metadata" - - grpctypes "github.com/cosmos/cosmos-sdk/types/grpc" - "github.com/cosmos/cosmos-sdk/types/tx" -) - -func queryState() error { - // --snip-- - - var header metadata.MD - bankRes, err = bankClient.Balance( - metadata.AppendToOutgoingContext(context.Background(), grpctypes.GRPCBlockHeightHeader, "12"), // Add metadata to request - &banktypes.QueryBalanceRequest{Address: myAddress, Denom: denom}, - grpc.Header(&header), // Retrieve header from response - ) - if err != nil { - return err - } - blockHeight = header.Get(grpctypes.GRPCBlockHeightHeader) - - fmt.Println(blockHeight) // Prints the block height (12) - - return nil -} -``` - -## Using the REST Endpoints - -All gRPC services on the Cosmos SDK are made available for more convenient REST-based queries through gRPC-gateway. The format of the URL path is based on the Protobuf service method's full-qualified name, but may contain small customizations so that final URLs look more idiomatic. For example, the REST endpoint for the `cosmos.bank.v1beta1.Query/AllBalances` method is `GET /cosmos/bank/v1beta1/balances/{address}`. Request arguments are passed as query parameters. - -The following examples assume you are using REST Endpoints to interact with your node in your local private network. You can change the domain to public networks. - -As a concrete example, the `curl` command to make balances request is: - -```bash -curl \ - -X GET \ - -H "Content-Type: application/json" \ - http://localhost:1317/cosmos/bank/v1beta1/balances/$MY_VALIDATOR -``` - -Make sure to replace `localhost:1317` with the REST endpoint of your node, configured under the `api.address` field. - -The list of all available REST endpoints is available as a Swagger specification file, it can be viewed at `localhost:1317/swagger`. Make sure that the `api.swagger` field is set to true in your `app.toml` file. - -#### Query for historical state using REST - -Querying for historical state is done using the HTTP header `x-cosmos-block-height`. For example, a curl command would look like: - -```bash -curl \ - -X GET \ - -H "Content-Type: application/json" \ - -H "x-cosmos-block-height: 279256" - http://localhost:1317/cosmos/bank/v1beta1/balances/$MY_VALIDATOR -``` - -Assuming the state at that block has not yet been pruned by the node, this query should return a non-empty response. - -## Cross-Origin Resource Sharing (CORS) - -[CORS policies](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) are not enabled by default to help with security. If you would like to use the rest-server in a public environment we recommend you provide a reverse proxy, this can be done with [nginx](https://www.nginx.com/). For testing and development purposes there is an `enabled-unsafe-cors` field inside `app.toml`. - -## Sending Transactions - -Sending transactions using gRPC and REST requires some additional steps: generating the transaction, signing it, and finally broadcasting it. - -You can learn more in [transactions](../../getting-started/transactions/ "mention"). diff --git a/.gitbook/nodes/getting-started/running-a-node/1.-setting-up-the-keyring.md b/.gitbook/nodes/getting-started/running-a-node/1.-setting-up-the-keyring.md deleted file mode 100644 index caa45f68..00000000 --- a/.gitbook/nodes/getting-started/running-a-node/1.-setting-up-the-keyring.md +++ /dev/null @@ -1,90 +0,0 @@ -# 1. Setting up the keyring - -{% hint style="info" %} -This document describes how to configure and use the keyring and its various backends for an Injective node. `injectived` should be installed prior to setting up the keyring. See the [Install `injectived` page](../../../toolkits/injectived/install-injectived.md) for more information. -{% endhint %} - -The keyring holds the private/public keypairs used to interact with the node. For instance, a validator key needs to be set up before running the Injective node, so that blocks can be correctly signed. The private key can be stored in different locations, called "backends", such as a file or the operating system's own key storage. - -### Available backends for the keyring - -#### The `os` backend - -The `os` backend relies on operating system-specific defaults to handle key storage securely. Typically, an operating system's credential sub-system handles password prompts, private keys storage, and user sessions according to the user's password policies. Here is a list of the most popular operating systems and their respective passwords manager: - -* macOS (since Mac OS 8.6): [Keychain](https://support.apple.com/en-gb/guide/keychain-access/welcome/mac) -* Windows: [Credentials Management API](https://docs.microsoft.com/en-us/windows/win32/secauthn/credentials-management) -* GNU/Linux: - * [libsecret](https://gitlab.gnome.org/GNOME/libsecret) - * [kwallet](https://api.kde.org/frameworks/kwallet/html/index.html) - -GNU/Linux distributions that use GNOME as default desktop environment typically come with [Seahorse](https://wiki.gnome.org/Apps/Seahorse). Users of KDE based distributions are commonly provided with [KDE Wallet Manager](https://userbase.kde.org/KDE\_Wallet\_Manager). Whilst the former is in fact a `libsecret` convenient frontend, the latter is a `kwallet` client. - -`os` is the default option since operating system's default credentials managers are designed to meet users' most common needs and provide them with a comfortable experience without compromising on security. - -The recommended backends for headless environments are `file` and `pass`. - -#### The `file` backend - -The `file` stores the keyring encrypted within the app's configuration directory. This keyring will request a password each time it is accessed, which may occur multiple times in a single command resulting in repeated password prompts. If using bash scripts to execute commands using the `file` option you may want to utilize the following format for multiple prompts: - -```bash -# assuming that KEYPASSWD is set in the environment -yes $KEYPASSWD | injectived keys add me -yes $KEYPASSWD | injectived keys show me -# start injectived with keyring-backend flag -injectived --keyring-backend=file start -``` - -{% hint style="info" %} -The first time you add a key to an empty keyring, you will be prompted to type the password twice. -{% endhint %} - -#### The `pass` backend - -The `pass` backend uses the [pass](https://www.passwordstore.org/) utility to manage on-disk encryption of keys' sensitive data and metadata. Keys are stored inside `gpg` encrypted files within app-specific directories. `pass` is available for the most popular UNIX operating systems as well as GNU/Linux distributions. Please refer to its manual page for information on how to download and install it. - -:::tip **pass** uses [GnuPG](https://gnupg.org/) for encryption. `gpg` automatically invokes the `gpg-agent` daemon upon execution, which handles the caching of GnuPG credentials. Please refer to `gpg-agent` man page for more information on how to configure cache parameters such as credentials TTL and passphrase expiration. ::: - -The password store must be set up prior to first use: - -```sh -pass init -``` - -Replace `` with your GPG key ID. You can use your personal GPG key or an alternative one you may want to use specifically to encrypt the password store. - -#### The `kwallet` backend - -The `kwallet` backend uses `KDE Wallet Manager`, which comes installed by default on the GNU/Linux distributions that ships KDE as default desktop environment. Please refer to [KWallet Handbook](https://docs.kde.org/stable5/en/kdeutils/kwallet5/index.html) for more information. - -#### The `test` backend - -The `test` backend is a password-less variation of the `file` backend. Keys are stored unencrypted on disk. - -**Provided for testing purposes only. The `test` backend is not recommended for use in production environments**. - -#### The `memory` backend - -The `memory` backend stores keys in memory. The keys are immediately deleted after the program has exited. - -**Provided for testing purposes only. The `memory` backend is not recommended for use in production environments**. - -### Adding keys to the keyring - -You can use `injectived keys` for help about the keys command and `injectived keys [command] --help` for more information about a particular subcommand. - -:::tip You can also enable auto-completion with the `injectived completion` command. For example, at the start of a bash session, run `. <(injectived completion)`, and all `injectived` subcommands will be auto-completed. ::: - -To create a new key in the keyring, run the `add` subcommand with a `` argument. For the purpose of this tutorial, we will solely use the `test` backend, and call our new key `my_validator`. This key will be used in the next section. - -```bash -$ injectived keys add my_validator --keyring-backend test - -# Put the generated address in a variable for later use. -MY_VALIDATOR_ADDRESS=$(injectived keys show my_validator -a --keyring-backend test) -``` - -This command generates a new 24-word mnemonic phrase, persists it to the relevant backend, and outputs information about the keypair. If this keypair will be used to hold value-bearing tokens, be sure to write down the mnemonic phrase somewhere safe! - -By default, the keyring generates a `eth_secp256k1` keypair. The keyring also supports `ed25519` keys, which may be created by passing the `--algo ed25519` flag. A keyring can of course hold both types of keys simultaneously. diff --git a/.gitbook/nodes/getting-started/running-a-node/README.md b/.gitbook/nodes/getting-started/running-a-node/README.md deleted file mode 100644 index d52fd91e..00000000 --- a/.gitbook/nodes/getting-started/running-a-node/README.md +++ /dev/null @@ -1,26 +0,0 @@ -# Running a node - -It is highly recommended that you set up a local private network before joining a public network. This will help you get familiar with the setup process and provide an environment for testing. - -### **Private Network** - -* Join by setting up a standalone network locally - -### **Public Network** - -* Use the network via public endpoints; or -* Join by running a node - -Anyone can set up their node with endpoints to communicate with the Injective blockchain. For convenience, there are also some public endpoints available to querying the chain. These are recommended for development and testing purposes. For maximum control and reliability, running your node is recommended. - -## Preparation For Running a Node - -If you choose to run a node (either to set up a private network or join the public network), you must set up the keyring. You can also choose to install Cosmovisor, which assists with chain upgrades for minimal downtime. - -## Interacting With The Node - -Once the node is up and running, there are a few ways to interact with a node, namely using the gPRC endpoints, REST endpoints, or `injectived` CLI. You can learn more here[#interacting-with-the-node](./#interacting-with-the-node "mention") - -## Guides on Running Your Node - -
Setup KeyringLearn how to setup your keyring1.-setting-up-the-keyring.mduser-hero.png
Join a NetworkLearn how to join a networkjoin-a-network.mdbridge-hero.png
Upgrade your nodeLearn how to upgrade your nodeupgrade-your-node.mdvalidator-hero.png
diff --git a/.gitbook/nodes/getting-started/running-a-node/join-a-network.md b/.gitbook/nodes/getting-started/running-a-node/join-a-network.md deleted file mode 100644 index eea02c4e..00000000 --- a/.gitbook/nodes/getting-started/running-a-node/join-a-network.md +++ /dev/null @@ -1,420 +0,0 @@ -# Join a network - -This guide will walk you through the process of setting up a standalone network locally as well as running a node on Mainnet or Testnet. - -You can also find the hardware requirements for each network in the respective tabs. - -{% tabs %} -{% tab title="Local Network" %} -To easily set up a local node, download and run the `setup.sh` script. This will initialize your local Injective network. - -```bash -wget https://raw.githubusercontent.com/InjectiveLabs/injective-chain-releases/master/scripts/setup.sh -chmod +x ./setup.sh # Make the script executable -./setup.sh -``` - -Start the node by running: - -```bash -injectived start # Blocks should start coming in after running this -``` - -For further explanation on what the script is doing and more fine-grained control over the setup process, continue reading below. - -### Initialize the Chain - -Before running Injective node, we need to initialize the chain as well as the node's genesis file: - -```bash -# The argument is the custom username of your node. It should be human-readable. -injectived init --chain-id=injective-1 -``` - -The command above creates all the configuration files needed for your node to run as well as a default genesis file, which defines the initial state of the network. All these configuration files are in `~/.injectived` by default, but you can overwrite the location of this folder by passing the `--home` flag. Note that if you choose to use a different directory other than `~/.injectived`, you must specify the location with the `--home` flag each time an `injectived` command is run. If you already have a genesis file, you can overwrite it with the `--overwrite` or `-o` flag. - -The `~/.injectived` folder has the following structure: - -```bash -. # ~/.injectived - |- data # Contains the databases used by the node. - |- config/ - |- app.toml # Application-related configuration file. - |- config.toml # Tendermint-related configuration file. - |- genesis.json # The genesis file. - |- node_key.json # Private key to use for node authentication in the p2p protocol. - |- priv_validator_key.json # Private key to use as a validator in the consensus protocol. -``` - -### Modify the `genesis.json` File - -At this point, a modification is required in the `genesis.json` file: - -* Change the staking `bond_denom`, crisis `denom`, gov `denom`, and mint `denom` values to `"inj"`, since that is the native token of Injective. - -This can easily be done by running the following commands: - -```bash -cat $HOME/.injectived/config/genesis.json | jq '.app_state["staking"]["params"]["bond_denom"]="inj"' > $HOME/.injectived/config/tmp_genesis.json && mv $HOME/.injectived/config/tmp_genesis.json $HOME/.injectived/config/genesis.json -cat $HOME/.injectived/config/genesis.json | jq '.app_state["crisis"]["constant_fee"]["denom"]="inj"' > $HOME/.injectived/config/tmp_genesis.json && mv $HOME/.injectived/config/tmp_genesis.json $HOME/.injectived/config/genesis.json -cat $HOME/.injectived/config/genesis.json | jq '.app_state["gov"]["deposit_params"]["min_deposit"][0]["denom"]="inj"' > $HOME/.injectived/config/tmp_genesis.json && mv $HOME/.injectived/config/tmp_genesis.json $HOME/.injectived/config/genesis.json -cat $HOME/.injectived/config/genesis.json | jq '.app_state["mint"]["params"]["mint_denom"]="inj"' > $HOME/.injectived/config/tmp_genesis.json && mv $HOME/.injectived/config/tmp_genesis.json $HOME/.injectived/config/genesis.json -``` - -{% hint style="info" %} -The commands above will only work if the default `.injectived` directory is used. For a specific directory, either modify the commands above or manually edit the `genesis.json` file to reflect the changes. -{% endhint %} - -### Create Keys for the Validator Account - -Before starting the chain, you need to populate the state with at least one account. To do so, first create a new account in the keyring named `my_validator` under the `test` keyring backend (feel free to choose another name and another backend): - -```bash -injectived keys add my_validator --keyring-backend=test - -# Put the generated address in a variable for later use. -MY_VALIDATOR_ADDRESS=$(injectived keys show my_validator -a --keyring-backend=test) -``` - -Now that you have created a local account, go ahead and grant it some `inj` tokens in your chain's genesis file. Doing so will also make sure your chain is aware of this account's existence from the genesis of the chain: - -```bash -injectived add-genesis-account $MY_VALIDATOR_ADDRESS 100000000000000000000000000inj --chain-id=injective-1 -``` - -`$MY_VALIDATOR_ADDRESS` is the variable that holds the address of the `my_validator` key in the keyring. Tokens in Injective have the `{amount}{denom}` format: `amount` is an 18-digit-precision decimal number, and `denom` is the unique token identifier with its denomination key (e.g. `inj`). Here, we are granting `inj` tokens, as `inj` is the token identifier used for staking in `injectived`. - -### Add the Validator to the Chain - -Now that your account has some tokens, you need to add a validator to your chain. Validators are special full-nodes that participate in the consensus process in order to add new blocks to the chain. Any account can declare its intention to become a validator operator, but only those with sufficient delegation get to enter the active set. For this guide, you will add your local node (created via the `init` command above) as a validator of your chain. Validators can be declared before a chain is first started via a special transaction included in the genesis file called a `gentx`: - -```bash -# Create a gentx. -injectived gentx my_validator 1000000000000000000000inj --chain-id=injective-1 --keyring-backend=test - -# Add the gentx to the genesis file. -injectived collect-gentxs -``` - -A `gentx` does three things: - -1. Registers the `validator` account you created as a validator operator account (i.e. the account that controls the validator). -2. Self-delegates the provided `amount` of staking tokens. -3. Link the operator account with a Tendermint node pubkey that will be used for signing blocks. If no `--pubkey` flag is provided, it defaults to the local node pubkey created via the `injectived init` command above. - -For more information on `gentx`, use the following command: - -```bash -injectived gentx --help -``` - -### Configuring the Node Using `app.toml` and `config.toml` - -Two configuration files are automatically generated inside `~/.injectived/config`: - -* `config.toml`: used to configure Tendermint (learn more on [Tendermint's documentation](https://docs.tendermint.com/v0.34/tendermint-core/configuration.html)), and -* `app.toml`: generated by the Cosmos SDK (which Injective is built on), and used for configurations such as state pruning strategies, telemetry, gRPC and REST server configurations, state sync, and more. - -Both files are heavily commented—please refer to them directly to tweak your node. - -One example config to tweak is the `minimum-gas-prices` field inside `app.toml`, which defines the minimum gas prices the validator node is willing to accept for processing a transaction. If it's empty, make sure to edit the field with some value, for example `10inj`, or else the node will halt on startup. For this tutorial, let's set the minimum gas price to 0: - -```toml - # The minimum gas prices a validator is willing to accept for processing a - # transaction. A transaction's fees must meet the minimum of any denomination - # specified in this config (e.g. 0.25token1;0.0001token2). - minimum-gas-prices = "0inj" -``` - -### Run a Localnet - -Now that everything is set up, you can finally start your node: - -```bash -injectived start # Blocks should start coming in after running this -``` - -This command allows you to run a single node, which is is enough to interact with the chain through the node, but you may wish to run multiple nodes at the same time to see how consensus occurs between them. -{% endtab %} - -{% tab title="Testnet Network" %} -### Hardware Specification - -Node operators should expect to provision one or more data center locations with redundant power, networking, firewalls, HSMs and servers. - -The minimum hardware specifications are as follows, though they might rise as network usage increases: - -``` -6+ vCPU x64 -32+ GB RAM -500 GB+ SSD -``` - -### Install `injectived` and `peggo` - -See the [Injective releases repo](https://github.com/InjectiveLabs/testnet/releases) for the most recent releases. Non-validator node operators do not need to install `peggo`. - -```bash -wget https://github.com/InjectiveLabs/testnet/releases/download/v1.12.9-testnet-1703762556/linux-amd64.zip -unzip linux-amd64.zip -sudo mv peggo /usr/bin -sudo mv injectived /usr/bin -sudo mv libwasmvm.x86_64.so /usr/lib -``` - -### Initialize a New Injective Chain Node - -Before running Injective node, we need to initialize the chain as well as the node's genesis file: - -```bash -# The argument is the custom username of your node, it should be human-readable. -export MONIKER= -# Injective Testnet has a chain-id of "injective-888" -injectived init $MONIKER --chain-id injective-888 -``` - -Running the `init` command will create `injectived` default configuration files at `~/.injectived`. - -### Prepare Configuration to Join Testnet - -You should now update the default configuration with the Testnet's genesis file and application config file, as well as configure your persistent peers with seed nodes. - -```bash -git clone https://github.com/InjectiveLabs/testnet.git - -# copy genesis file to config directory -aws s3 cp --no-sign-request s3://injective-snapshots/testnet/genesis.json . -mv genesis.json ~/.injectived/config/ - -# copy config file to config directory -cp testnet/corfu/70001/app.toml ~/.injectived/config/app.toml -cp testnet/corfu/70001/config.toml ~/.injectived/config/config.toml -``` - -You can also run verify the checksum of the genesis checksum - a4abe4e1f5511d4c2f821c1c05ecb44b493eec185c0eec13b1dcd03d36e1a779 - -```bash -sha256sum ~/.injectived/config/genesis.json -``` - -### Configure `systemd` Service for `injectived` - -Edit the config at `/etc/systemd/system/injectived.service`: - -```bash -[Unit] - Description=injectived - -[Service] - WorkingDirectory=/usr/bin - ExecStart=/bin/bash -c '/usr/bin/injectived --log-level=error start' - Type=simple - Restart=always - RestartSec=5 - User=root - -[Install] - WantedBy=multi-user.target -``` - -Starting and restarting the systemd service - -```bash -sudo systemctl daemon-reload -sudo systemctl restart injectived -sudo systemctl status injectived - -# enable start on system boot -sudo systemctl enable injectived - -# To check Logs -journalctl -u injectived -f -``` - -### Sync with the network - -Refer to the Polkachu guide [here](https://polkachu.com/testnets/injective/snapshots) to download a snapshot and sync with the network. - -#### Support - -For any further questions, you can always connect with the Injective Team via [Discord](https://discord.gg/injective), [Telegram](https://t.me/joininjective), or [email](mailto:contact@injectivelabs.org). -{% endtab %} - -{% tab title="Mainnet Network" %} -### Hardware Specification - -Node operators should expect to provision one or more data center locations with redundant power, networking, firewalls, HSMs and servers. - -The minimum hardware specifications are as follows, though they might rise as network usage increases: - -``` -(AWS r6i.2xlarge Instance) -8+ vCPU x64 -64+ GB RAM -1+ TB SSD storage -1+ Gbps Network Bandwidth -``` - -For a more performant node, the following configuration is recommended: - -``` -(AWS r6i.4xlarge Instance or higher) -16+ vCPU -128+ GB RAM -2+ TB SSD storage -5+ Gbps Network Bandwidth -``` - -The more storage allocated, the less frequently data must be pruned from the node. - -### Install `injectived` and `peggo` - -See the [Injective chain releases repo](https://github.com/InjectiveLabs/injective-chain-releases/releases/) for the most recent releases. Non-validator node operators do not need to install `peggo`. - -```bash -wget https://github.com/InjectiveLabs/injective-chain-releases/releases/download/v1.13.0-1722157491/linux-amd64.zip -unzip linux-amd64.zip -sudo mv peggo /usr/bin -sudo mv injectived /usr/bin -sudo mv libwasmvm.x86_64.so /usr/lib -``` - -### Initialize a New Injective Node - -Before running Injective node, we need to initialize the chain as well as the node's genesis file: - -```bash -# The argument is the custom username of your node. It should be human-readable. -export MONIKER= -# Injective Mainnet has a chain-id of "injective-1" -injectived init $MONIKER --chain-id injective-1 -``` - -Running the `init` command will create `injectived` default configuration files at `~/.injectived`. - -### Prepare Configuration to Join Mainnet - -You should now update the default configuration with the Mainnet's genesis file and application config file, as well as configure your persistent peers with seed nodes. - -```bash -git clone https://github.com/InjectiveLabs/mainnet-config - -# copy genesis file to config directory -cp mainnet-config/10001/genesis.json ~/.injectived/config/genesis.json - -# copy config file to config directory -cp mainnet-config/10001/app.toml ~/.injectived/config/app.toml -``` - -You can also run verify the checksum of the genesis checksum - 573b89727e42b41d43156cd6605c0c8ad4a1ce16d9aad1e1604b02864015d528 - -```bash -sha256sum ~/.injectived/config/genesis.json -``` - -Then update the `seeds` field in `~/.injectived/config/config.toml` with the contents of `mainnet-config/10001/seeds.txt` and update the `timeout_commit` to `300ms`. - -```bash -cat mainnet-config/10001/seeds.txt -nano ~/.injectived/config/config.toml -``` - -### Configure `systemd` Service for `injectived` - -Edit the config at `/etc/systemd/system/injectived.service`: - -```bash -[Unit] - Description=injectived - -[Service] - WorkingDirectory=/usr/bin - ExecStart=/bin/bash -c '/usr/bin/injectived --log-level=error start' - Type=simple - Restart=always - RestartSec=5 - User=root - -[Install] - WantedBy=multi-user.target -``` - -Starting and restarting the systemd service: - -```bash -sudo systemctl daemon-reload -sudo systemctl restart injectived -sudo systemctl status injectived - -# enable start on system boot -sudo systemctl enable injectived - -# To check Logs -journalctl -u injectived -f -``` - -The service should be stopped before and started after the snapshot data has been loaded into the correct directory. - -```bash -# to stop the node -sudo systemctl stop injectived - -# to start the node -sudo systemctl start injectived -``` - -### Sync with the network - -#### Option 1. State-Sync - -_To be added soon_ - -#### Option 2. Snapshots - -**Pruned** - -1. [Polkachu](https://polkachu.com/tendermint\_snapshots/injective). -2. [HighStakes](https://tools.highstakes.ch/files/injective.tar.gz). -3. [AutoStake](http://snapshots.autostake.net/injective-1/). -4. [Imperator](https://www.imperator.co/services/chain-services/mainnets/injective). -5. [Bware Labs](https://bwarelabs.com/snapshots). - -Alternatively, you can use the pruned snapshots from Injective Labs on AWS S3. - -```bash -systemctl stop injectived -injectived tendermint unsafe-reset-all --home $HOME/.injectived -SNAP=$(aws s3 ls --no-sign-request s3://injective-snapshots/mainnet/pruned/ | grep ".tar.lz4" | sort | tail -n 1 | awk '{print $4}') -aws s3 cp --no-sign-request s3://injective-snapshots/mainnet/pruned/$SNAP . -lz4 -c -d $SNAP | tar -x -C $HOME/.injectived/ -rm $SNAP -systemctl start injectived -``` - -Should the Injective `mainnet-config seeds.txt` list not work (the node fails to sync blocks), ChainLayer, Polkachu, and Autostake maintain peer lists (can be used in the `persistent_peers` field in `config.toml`) or addressbooks (for faster peer discovery). - -**Archival** (>20TB) - -```bash -systemctl stop injectived -injectived tendermint unsafe-reset-all --home $HOME/.injectived -aws s3 sync --no-sign-request --delete s3://injective-snapshots/mainnet/injectived/data $HOME/.injectived/data -aws s3 sync --no-sign-request --delete s3://injective-snapshots/mainnet/injectived/wasm $HOME/.injectived/wasm -systemctl start injectived -``` - -At this point, [GEX](https://github.com/cosmos/gex) can be used to monitor the node's sync status. If the snapshot has been correcly loaded, the number of connected peers should increase from 0 and the latest block should steadily increase, signalling the node syncing with its peers. Note that it may take a few or several hours for the node to catch up to the network's block height depending on the age of the snapshot. - -In the case where the latest block does not increase and the number of connected peers is 0 or remains low, the seed list in `seeds.txt` may be outdated, and the `seeds` or `persistent_peers` fields can be updated using a validator's seed or peer list respectively, before the node is started again. - -```bash -go install github.com/cosmos/gex@latest -gex -``` - -#### Support - -For any further questions, you can always connect with the Injective Team via [Discord](https://discord.gg/injective), [Telegram](https://t.me/joininjective), or [email](mailto:contact@injectivelabs.org) -{% endtab %} -{% endtabs %} - diff --git a/.gitbook/nodes/getting-started/running-a-node/upgrade-your-node.md b/.gitbook/nodes/getting-started/running-a-node/upgrade-your-node.md deleted file mode 100644 index fb5c3eed..00000000 --- a/.gitbook/nodes/getting-started/running-a-node/upgrade-your-node.md +++ /dev/null @@ -1,22 +0,0 @@ -# Upgrade your node - -### Chain Upgrades - -Injective periodically undergoes software upgrades. When a chain upgrade governance proposal is passed, a block height will be specified at which all nodes will automatically panic and stop running. At this point, the upgraded `injectived` binaries can be installed, and the node can be restarted. - -See [here](https://github.com/InjectiveLabs/injective-chain-releases/releases) for the most recent and prior chain releases. - -### Node Upgrade Directions - -To summarize, follow these steps to upgrade your node: - -1. Sync your node to the block height predetermined by the upgrade governance proposal. -2. The node will automatically panic/stop at the predetermined upgrade height. -3. Remove the old binaries and install the new release binaries. -4. Restart the node. - -### Node Maintenance (Managing Storage) - -As Injective state grows, your disk space may fill up. It’s recommended you periodically prune the chain data by downloading new snapshots. Beyond the overhead on the disk, the node is more performant when the chain state is smaller. - -Injective validators take daily light snapshots that you can use to clean the chain state which grows at about 10-15GB daily. These snapshots are normally only around 2-3GB. We recommend pruning the chain data every 300-400GB. For links to snapshots as well as directions for applying the snapshot/syncing the node, see Join Mainnet. diff --git a/.gitbook/nodes/private-nodes.md b/.gitbook/nodes/private-nodes.md deleted file mode 100644 index f82bf604..00000000 --- a/.gitbook/nodes/private-nodes.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -description: >- - As a developer, you may be interested in having a private/dedicated node or - indexing solutions powering your dApp. ---- - -# Private Nodes - -Here is a list of external providers offering private Injective infrastructure services. For more information, click on their websites below - -* [AllNodes](https://www.allnodes.com/inj) -* [NewMetric](https://app.newmetric.xyz/) -* [NowNodes](https://nownodes.io/injective-inj) -* [RockX](https://access.rockx.com/product/injective-blockchain-api-for-web3-builders) - diff --git a/.gitbook/nodes/public-endpoints.md b/.gitbook/nodes/public-endpoints.md deleted file mode 100644 index 7328cafa..00000000 --- a/.gitbook/nodes/public-endpoints.md +++ /dev/null @@ -1,46 +0,0 @@ -# Public Endpoints - -{% hint style="info" %} -We **do not recommend** using these in production for applications having high usage/traffic. There are thousands of developers using the public infrastructure and we cannot promise 100% uptime and reliability. -{% endhint %} - -## Mainnet - -#### Find the [real-time status](https://status.injective.network/) of the endpoints and of the Injective network. - -| Service | Address | -| ---------------- | ------------------------------------------------------------- | -| RPC | https://sentry.tm.injective.network:443 | -| LCD | https://sentry.lcd.injective.network:443 | -| WebSocket | wss://sentry.tm.injective.network:443/websocket | -| Chain Stream | sentry.chain.stream.injective.network:443 | -| gRPC | sentry.chain.grpc.injective.network:443 | -| gRPC-Web | https://sentry.chain.grpc-web.injective.network:443 | -| Indexer gRPC | sentry.exchange.grpc.injective.network:443 | -| Indexer gRPC-Web | https://sentry.exchange.grpc-web.injective.network:443 | -| Indexer Swagger | https://sentry.exchange.grpc-web.injective.network/swagger/#/ | -| External API | https://external.api.injective.network | -| Swagger | https://sentry.lcd.injective.network/swagger/#/ | -| Hub | https://hub.injective.network/ | -| Explorer | https://explorer.injective.network/ | -| Faucet | https://inj.supply/ | - -## Testnet - -#### Find the [real-time status](https://testnet.status.injective.network) of the endpoints and the Injective testnet network. - -| Service | Address | -| ---------------- | --------------------------------------------------------------------- | -| RPC | https://testnet.sentry.tm.injective.network:443 | -| LCD | https://testnet.sentry.lcd.injective.network:443 | -| WebSocket | wss://testnet.sentry.tm.injective.network:443/websocket | -| Chain Stream | testnet.sentry.chain.stream.injective.network:443 | -| gRPC | testnet.sentry.chain.grpc.injective.network:443 | -| gRPC-Web | https://testnet.sentry.chain.grpc-web.injective.network:443 | -| Indexer gRPC | testnet.sentry.exchange.grpc.injective.network:443 | -| Indexer gRPC-Web | https://testnet.sentry.exchange.grpc-web.injective.network:443 | -| Swagger | https://testnet.sentry.lcd.injective.network/swagger/ | -| Indexer Swagger | https://testnet.sentry.exchange.grpc-web.injective.network/swagger/#/ | -| Hub | https://testnet.hub.injective.network/ | -| Explorer | https://testnet.explorer.injective.network/ | -| Faucet | https://testnet.faucet.injective.network/ | diff --git a/.gitbook/nodes/validators/README.md b/.gitbook/nodes/validators/README.md deleted file mode 100644 index 4b3e36b5..00000000 --- a/.gitbook/nodes/validators/README.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -description: In this page we'll ---- - -# Validators - diff --git a/.gitbook/nodes/validators/cosmosvisor.md b/.gitbook/nodes/validators/cosmosvisor.md deleted file mode 100644 index a91b4d56..00000000 --- a/.gitbook/nodes/validators/cosmosvisor.md +++ /dev/null @@ -1,156 +0,0 @@ ---- -hidden: true ---- - -# Cosmosvisor - -`Cosmovisor` is a small process manager around Cosmos SDK binaries that monitors the governance module via `stdout` to see if there's a chain upgrade proposal coming in. If it sees a proposal that gets approved, it can be run manually or automatically to download the new code, stop the node, run the migration script, replace the node binary, and start with the new genesis file. - -### Installation - -Run: - -`go get github.com/cosmos/cosmos-sdk/cosmovisor/cmd/cosmovisor` - -### Command Line Arguments And Environment Variables - -All arguments passed to the `cosmovisor` program will be passed to the current daemon binary (as a subprocess). It will return `/dev/stdout` and `/dev/stderr` of the subprocess as its own. Because of that, it cannot accept any command line arguments, nor print anything to output (unless it terminates unexpectedly before executing a binary). - -`cosmovisor` reads its configuration from environment variables: - -* `DAEMON_HOME` is the location where upgrade binaries should be kept (e.g. `$HOME/.injectived`). -* `DAEMON_NAME` is the name of the binary itself (eg. `injectived`). -* `DAEMON_ALLOW_DOWNLOAD_BINARIES` (_optional_) if set to `true` will enable auto-downloading of new binaries (for security reasons, this is intended for full nodes rather than validators). -* `DAEMON_RESTART_AFTER_UPGRADE` (_optional_) if set to `true` it will restart the sub-process with the same command line arguments and flags (but new binary) after a successful upgrade. By default, `cosmovisor` dies afterwards and allows the supervisor to restart it if needed. Note that this will not auto-restart the child if there was an error. -* `DAEMON_LOG_BUFFER_SIZE` (_optional_) is the buffer size for cosmovisor to scan log. If not set, it will use the default [64](https://github.com/golang/go/blob/2217e89ba326875470a856cd0da79f3ec9a896b8/src/bufio/scan.go#L80). (e.g. set to `256` or `512`) It is to avoid scanning stuck in case of long line of the log. - -### Data Folder Layout - -`$DAEMON_HOME/cosmovisor` is expected to belong completely to `cosmovisor` and subprocesses that are controlled by it. The folder content is organised as follows: - -``` -. -├── current -> genesis or upgrades/ -├── genesis -│   └── bin -│   └── $DAEMON_NAME -└── upgrades - └── - └── bin - └── $DAEMON_NAME -``` - -Each version of the Cosmos SDK application is stored under either `genesis` or `upgrades/`, which holds `bin/$DAEMON_NAME` along with any other needed files such as auxiliary client programs or libraries. `current` is a symbolic link to the currently active folder (so `current/bin/$DAEMON_NAME` is the currently active binary). - -_Note: the `name` variable in `upgrades/` holds the URI-encoded name of the upgrade as specified in the upgrade module plan._ - -Please note that `$DAEMON_HOME/cosmovisor` just stores the _binaries_ and associated _program code_. The `cosmovisor` binary can be stored in any typical location (eg `/usr/local/bin`). The actual blockchain program will store it's data under their default data directory (e.g. `$HOME/.injectived`) which is independent of the `$DAEMON_HOME`. You can choose to set `$DAEMON_HOME` to the actual binary's home directory and then end up with a configuation like the following, but this is left as a choice to the system admininstrator for best directory layout: - -``` -.injectived -├── config -├── data -└── cosmovisor -``` - -### Usage - -The system administrator admin is responsible for: - -* installing the `cosmovisor` binary and configure the host's init system (e.g. `systemd`, `launchd`, etc) along with the environmental variables appropriately; -* installing the `genesis` folder manually; -* installing the `upgrades/` folders manually. - -`cosmovisor` will set the `current` link to point to `genesis` at first start (when no `current` link exists) and handles binaries switch overs at the correct points in time, so that the system administrator can prepare days in advance and relax at upgrade time. - -Note that blockchain applications that wish to support upgrades may package up a genesis `cosmovisor` tarball with this information, just as they prepare the genesis binary tarball. In fact, they may offer a tarball will all upgrades up to current point for easy download for those who wish to sync a fullnode from start. - -The `DAEMON` specific code and operations (e.g. tendermint config, the application db, syncing blocks, etc) are performed as normal. Application binaries' directives such as command-line flags and environment variables work normally. - -### Auto-Download - -Generally, the system requires that the system administrator place all relevant binaries on the disk before the upgrade happens. However, for people who don't need such control and want an easier setup (maybe they are syncing a non-validating fullnode and want to do little maintenance), there is another option. - -If you set `DAEMON_ALLOW_DOWNLOAD_BINARIES=on` then when an upgrade is triggered and no local binary can be found, the `cosmovisor` will attempt to download and install the binary itself. The plan stored in the upgrade module has an info field for arbitrary json. This info is expected to be outputed on the halt log message. There are two valid format to specify a download in such a message: - -1. Store an os/architecture -> binary URI map in the upgrade plan info field as JSON under the `"binaries"` key, eg: - -```json -{ - "binaries": { - "linux/amd64":"https://example.com/gaia.zip?checksum=sha256:aec070645fe53ee3b3763059376134f058cc337247c978add178b6ccdfb0019f" - } -} -``` - -2. Store a link to a file that contains all information in the above format (eg. if you want to specify lots of binaries, changelog info, etc without filling up the blockchain). - -e.g. `https://example.com/testnet-1001-info.json?checksum=sha256:deaaa99fda9407c4dbe1d04bd49bab0cc3c1dd76fa392cd55a9425be074af01e` - -This file contained in the link will be retrieved by [go-getter](https://github.com/hashicorp/go-getter) and the `"binaries"` field will be parsed as above. - -If there is no local binary, `DAEMON_ALLOW_DOWNLOAD_BINARIES=on`, and we can access a canonical url for the new binary, then the `cosmovisor` will download it with [go-getter](https://github.com/hashicorp/go-getter) and unpack it into the `upgrades/` folder to be run as if we installed it manually. - -Note that for this mechanism to provide strong security guarantees, all URLS should include a sha{256,512} checksum. This ensures that no false binary is run, even if someone hacks the server or hijacks the DNS. go-getter will always ensure the downloaded file matches the checksum if it is provided. go-getter will also handle unpacking archives into directories (so these download links should be a zip of all data in the `bin` directory). - -To properly create a checksum on linux, you can use the `sha256sum` utility. e.g. `sha256sum ./testdata/repo/zip_directory/autod.zip` which should return `29139e1381b8177aec909fab9a75d11381cab5adf7d3af0c05ff1c9c117743a7`. You can also use `sha512sum` if you like longer hashes, or `md5sum` if you like to use broken hashes. Make sure to set the hash algorithm properly in the checksum argument to the url. - -### Example: injectived - -The following instructions provide a demonstration of `cosmovisor`'s integration with the `injectived` application shipped along the Cosmos SDK's source code. - -First compile `injectived`: - -``` -cd injective-core/ -make build -``` - -Create a new key and setup the `injectived` node: - -``` -rm -rf $HOME/.injectived -./build/injectived keys --keyring-backend=file add validator -./build/injectived init testing --chain-id=injective-1 -./build/injectived add-genesis-account --keyring-backend=file $(./build/injectived keys --keyring-backend=file show validator -a) 1000000000inj -./build/injectived gentx --keyring-backend=file --chain-id=injective-1 validator 100000inj -./build/injectived collect-gentxs -``` - -Set the required environment variables: - -``` -export DAEMON_NAME=injectived # binary name -export DAEMON_HOME=$HOME/.injectived # daemon's home directory -``` - -Create the `cosmovisor`’s genesis folders and deploy the binary: - -``` -mkdir -p $DAEMON_HOME/cosmovisor/genesis/bin -cp ./build/injectived $DAEMON_HOME/cosmovisor/genesis/bin -``` - -For the sake of this demonstration, we would amend `voting_params.voting_period` in `.injectived/config/genesis.json` to a reduced time \~5 minutes (300s) and eventually launch `cosmosvisor`: - -``` -cosmovisor start -``` - -Submit a software upgrade proposal: - -``` -./build/injectived tx gov submit-proposal software-upgrade test1 --title="upgrade-demo" --description="upgrade" --from=validator --upgrade-height=100 --deposit=10000000inj --chain-id=injective-1 --keyring-backend=test -y -``` - -Query the proposal to ensure it was correctly broadcast and added to a block: - -``` -./build/injectived query gov proposal 1 -``` - -Submit a `Yes` vote for the upgrade proposal: - -``` -./build/injectived tx gov vote 1 yes --from=validator --keyring-backend=file --chain-id=injective-1 -y -``` diff --git a/.gitbook/nodes/validators/mainnet/README.md b/.gitbook/nodes/validators/mainnet/README.md deleted file mode 100644 index ccb74f3f..00000000 --- a/.gitbook/nodes/validators/mainnet/README.md +++ /dev/null @@ -1,149 +0,0 @@ -# Mainnet - -#### Hardware Requirements - -| _Minimum_ | _Recommendation_ | -| :-------------: | :--------------: | -| RAM Memory 64GB | RAM Memory 128GB | -| CPU 8 cores | CPU 12 cores | -| Storage 1TB | Storage 2TB | -| Network 1Gbps+ | Network 5Gbps+ | - -### Step 1: Create a Validator Account - -First, run the keygen command with your desired validator key name. - -```bash -export VALIDATOR_KEY_NAME=[my-validator-key] -injectived keys add $VALIDATOR_KEY_NAME -``` - -This will derive a new private key and encrypt it to disk. Make sure to remember the password you used. - -```bash -# EXAMPLE OUTPUT -- name: myvalidatorkey - type: local - address: inj1queq795wx8gzqc8706uz80whp07mcgg5nmpj6h - pubkey: injpub1r0mckeepqwzmrzt5af00hgc7fhve05rr0q3q6wvx4xn6k46zguzykdszg6cnu0zca4q - mnemonic: "" - threshold: 0 - pubkeys: [] - - -**Important** write this mnemonic phrase in a safe place. -It is the only way to recover your account if you ever forget your password. -``` - -{% hint style="warning" %} -**The output will contain a mnemonic phrase that represents your key in plain text. Make sure to save this phrase as a backup of your key, since without a key you will not be able to control your validator. The phrase is better be backed up on physical paper, storing it in cloud storage may compromise your validator later.** - -Remember the address starting from `inj`, this is going to be your Injective Validator Account address. -{% endhint %} - -### Step 2: Obtain Mainnet INJ - -To proceed with the next step, you will need to obtain some real INJ on Mainnet Ethereum (ERC-20 token address [`0xe28b3b32b6c345a34ff64674606124dd5aceca30`](https://etherscan.io/token/0xe28b3b32b6c345a34ff64674606124dd5aceca30)). - -### Step 3: "Transfer" INJ to your validator account on Injective - -Deposit your Mainnet INJ tokens into your validator's account on Injective by using the staking dashboard. You will have to [connect your wallet](https://medium.com/injective-labs/injective-hub-guide-9a14f09f6a7d)on our [Hub](https://hub.injective.network/bridge) and then deposit INJ from Ethereum Mainnet network. This will trigger an automated bridge that maps tokens from Ethereum network to Injective. - -After a few minutes, you should be able to verify that your deposit was successful on the UI. Alternatively, you can query your account balance using the `injectived` CLI with the following command: - -```bash -injectived q bank balances -``` - -### Step 4: Create your validator account - -Obtain your node's tendermint validator Bech32 encoded PubKey consensus address. - -```bash -VALIDATOR_PUBKEY=$(injectived tendermint show-validator) -echo $VALIDATOR_PUBKEY - -# Example: {"@type": "/cosmos.crypto.ed25519.PubKey", "key": "GWEJv/KSFhUUcKBWuf9TTT3Ful+3xV/1lFhchyW1TZ8="} -``` - -Then create your new validator initialized with a self-delegation with your INJ tokens. Most critically, you will need to decide on the values of your validator's staking parameters. - -* `--moniker` - Your validator's name -* `--amount` - Your validator's initial amount of INJ to bond -* `--commission-max-change-rate` - Your validator's maximum commission change rate percentage (per day) -* `--commission-max-rate` - Your validator's maximum commission rate percentage -* `--commission-rate` - Your validator's initial commission rate percentage -* `--min-self-delegation` - Your validator's minimum required self delegation - -Once you decide on your desired values, set them as follows. - -```bash -MONIKER= -AMOUNT=100000000000000000000inj # to delegate 100 INJ, as INJ is represented with 18 decimals. -COMMISSION_MAX_CHANGE_RATE=0.1 # e.g. for a 10% maximum change rate percentage per day -COMMISSION_MAX_RATE=0.1 # e.g. for a 10% maximum commission rate percentage -COMMISSION_RATE=0.1 # e.g. for a 10% initial commission rate percentage -MIN_SELF_DELEGATION_AMOUNT=50000000000000000000 # e.g. for a minimum 50 INJ self delegation required on the validator -``` - -Then run the following command to create your validator. - -```bash -injectived tx staking create-validator \ ---moniker=$MONIKER \ ---amount=$AMOUNT \ ---gas-prices=500000000inj \ ---pubkey=$VALIDATOR_PUBKEY \ ---from=$VALIDATOR_KEY_NAME \ ---keyring-backend=file \ ---yes \ ---node=tcp://localhost:26657 \ ---chain-id=injective-1 ---commission-max-change-rate=$COMMISSION_MAX_CHANGE_RATE \ ---commission-max-rate=$COMMISSION_MAX_RATE \ ---commission-rate=$COMMISSION_RATE \ ---min-self-delegation=$MIN_SELF_DELEGATION_AMOUNT -``` - -Extra `create-validator` options to consider: - -``` ---identity= The optional identity signature (ex. UPort or Keybase) ---pubkey= The Bech32 encoded PubKey of the validator ---security-contact= The validator's (optional) security contact email ---website= The validator's (optional) website -``` - -You can check that your validator was successfully created by checking the [staking dashboard](https://staking.injective.network/validators) or by entering the following CLI command. - -```bash -injectived q staking validators -``` - -If you see your validator in the list of validators, then congratulations, you've officially joined as an Injective Mainnet validator! 🎉 - -### Step 5: (Optional) Delegate Additional INJ to your Validator - -To gain a deeper empirical understanding of user experience that your future delegators will experience, you can try delegation through [Staking Guide](https://medium.com/injective-labs/injective-hub-guide-9a14f09f6a7d). - -These steps will allow you to experience the delegation flow using MetaMask Transactions. 🦊 - -Alternatively, you can always use the Injective CLI to send a delegation transaction. - -```bash -injectived tx staking delegate [validator-addr] [amount] --from $VALIDATOR_KEY_NAME --keyring-backend=file --yes --node=tcp://localhost:26657 -``` - -### Step 6: (Recommended) Connecting Your Validator Identity with Keybase - -By adding your Keybase pubkey to your validator identity information in Injective, you can automatically pull in your Keybase public profile information in client applications like the Injective Hub and Explorer. Here's how to connect your validator identity with your Keybase pubkey: - -1. Create a validator profile on Keybase at [https://keybase.io/](https://keybase.io/) and make sure it's complete. -2. Add your validator identity pubkey to Injective: - * Send a `MsgEditValidator` to update your `Identity` validator identity with your Keybase pubkey. You can also use this message to change your website, contact email, and other details. - -That's it! Once you've connected your validator identity with Keybase, the Injective Explorer and Hub can automatically pull in your brand identity, and other public profile information. - -#### Next Steps - -Next, proceed to setup your [Ethereum Bridge Relayer](peggo.md). This is a necessary step to prevent your validator from being slashed. You should do this immediately after setting up your validator. diff --git a/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/README.md b/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/README.md deleted file mode 100644 index f7657079..00000000 --- a/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/README.md +++ /dev/null @@ -1,87 +0,0 @@ -# Canonical Chain Upgrades - -Nov 8th, 2021 - -The following document describes the necessary steps involved that validators and full node operators must take in order to upgrade from the Injective Canary Chain to the Canonical Chain. The upgrade will take place via an on-chain software upgrade proposal passed by Injective governance. If passed, this proposal would commit the Injective Mainnet to halting the Canary Chain injectived application binary at approximately 14:00 UTC on Nov 8th and starting the application binary for the Injective Canonical Chain. - -Injective Canary Chain to the Canonical Chain upgrade follows [proposal #65](https://hub.injective.network/proposals/65) - -Following a chain upgrade timeline, as a first step proccedd to Canonical chain release [10002-rc1](canonical-10002-rc1.md) upgrade. - - -## The History of Canonical Chain Upgrades - ---- -### Version 10002-rc1 -Nov 8th 2021 14:00 UTC - -Block number: [4,352,000](https://explorer.injective.network/block/4352000) - -Released Artifacts: [Injective Chain 10002-rc1 release](https://github.com/InjectiveLabs/injective-chain-releases/releases/tag/v1.1.0-1636178708) - -Following [proposal #65](https://hub.injective.network/proposals/65) - ---- -### Version 10002-rc2 -November 15th 2021 - -Block number: [4,594,100](https://explorer.injective.network/block/4594100) - -Released Artifacts: [Injective Chain 10002-rc2 release](https://github.com/InjectiveLabs/injective-chain-releases/releases/tag/v1.1.1-1636733798) - -Following [proposal #70](https://hub.injective.network/proposals/70) - ---- -### Version 10003-rc1 -Thursday Dec 30th 2021 - -Block number: [6,159,200](https://explorer.injective.network/block/6159200) - -Released Artifacts: [Mainnet-10003-rc1-1640627705](https://github.com/InjectiveLabs/injective-chain-releases/releases/tag/v1.1.1-1640627705) - -Following [proposal #93](https://hub.injective.network/proposals/93) - ---- -### Version 10004-rc1 -Tuesday Jan 25th 2022 - -Block number: [7067700](https://explorer.injective.network/block/7067700) - -Released Artifacts: [Mainnet-10004-rc1-v1.4.0-1642928125](https://github.com/InjectiveLabs/injective-chain-releases/releases/tag/v1.4.0-1642928125) - -Following [proposal #106](https://hub.injective.network/proposals/106) - -### Version 10004-rc1-patch -Sunday Feb 20th 2022 - -Block number: [7941974](https://explorer.injective.network/block/7941974) - -Released Artifacts: [Mainnet-10004-rc1-v1.4.0-1645352045](https://github.com/InjectiveLabs/injective-chain-releases/releases/tag/v1.4.0-1645352045) - -### Version 10005-rc1 -Monday April 11th 2022 - -Block number: [9614200](https://explorer.injective.network/block/9614200) - -Released Artifacts: [Mainnet-v1.5.0-1649280277](https://github.com/InjectiveLabs/injective-chain-releases/releases/tag/v1.5.0-1649280277) - -### Version 10006-rc1 -Tuesday July 5th 2022 - -Block number: [12569420](https://explorer.injective.network/block/12569420) - -Released Artifacts: [Mainnet-v1.6.0-1656650662](https://github.com/InjectiveLabs/injective-chain-releases/releases/tag/v1.6.0-1656650662) - -### Version 10007-rc1 -Thursday September 1th 2022 - -Block number: [14731000](https://explorer.injective.network/block/14731000) - -Released Artifacts: [Mainnet-v1.7.0-1661881062](https://github.com/InjectiveLabs/injective-chain-releases/releases/tag/v1.7.0-1661881062) - -### Version 10008 -Monday November 21th 2022 - -Block number: [19761600](https://explorer.injective.network/block/19761600) - -Released Artifacts: [Mainnet-10008-1668679102](https://github.com/InjectiveLabs/injective-chain-releases/releases/tag/v1.8.0-1668679102) diff --git a/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/canonical-1-12.md b/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/canonical-1-12.md deleted file mode 100644 index 1cf24188..00000000 --- a/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/canonical-1-12.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -sidebar_position: 14 ---- - -# Upgrade to v1.12.0 -Thursday January 11 2024 - -Following [proposal 314](https://hub.injective.network/proposals/314/) -This indicates that the upgrade procedure should be performed on block number **57076000** - - - [Summary](#summary) - - [Risks](#risks) - - [Recovery](#recovery) - - [Upgrade Procedure](#upgrade-procedure) - - [Notes for Validator Operators](##notes-for-validator-operators) - - [Notes for Service Providers](##notes-for-DEX-relayer-providers) - -## Summary - -The Injective Canonical Chain will undergo a scheduled enhancement upgrade on **Jan 11th 14:00 UTC**. - -The following is a short summary of the upgrade steps: - -1. Vote and wait till the node panics at block height **57076000**. -2. Backing up configs, data, and keys used for running the Injective Canonical Chain. -3. Install the [v1.12.0-1704530206](https://github.com/InjectiveLabs/injective-chain-releases/releases/tag/v1) -4. Start your node with the new injectived binary to fulfill the upgrade. - -Upgrade coordination and support for validators will be available on the `#validators` private channel of the [Injective Discord](https://discord.gg/injective). - -The network upgrade can take the following potential pathways: -1. **Happy path** -Validators successfully upgrade chain without purging the blockchain history and all validators are up within 1-2 hours of the scheduled upgrade. - -2. **Not-so-happy path** -Validators have trouble upgrading to latest Canonical chain. This could be some consensus breaking changes not covered in upgrade handler, or compatibility issue of the migrated state with new injectived binary, but validators can at least export the genesis. - -3. **Abort path** -In the rare event that the team becomes aware of unnoticed critical issues, the Injective team will attempt to patch all the breaking states and provide another official binary within 36 hours. -If the chain is not successfully resumed within 36 hours, the upgrade will be announced as aborted on the #mainnet-validators channel of [Discord](https://discord.gg/injective), and validators will need to resume running the chain without any updates or changes. A new governance proposal for the upgrade will need to be issued and voted on by the community for the next upgrade. - -## Risks - -As a validator performing the upgrade procedure on your consensus nodes carries a heightened risk of double-signing and being slashed. The most important piece of this procedure is verifying your software version and genesis file hash before starting your validator and signing. - -The riskiest thing a validator can do is discover that they made a mistake and repeat the upgrade procedure again during the network startup. If you discover a mistake in the process, the best thing to do is wait for the network to start before correcting it. If the network is halted and you have started with a different genesis file than the expected one, seek advice from an Injective developer before resetting your validator. - -## Recovery - -Prior to exporting chain state, validators are encouraged to take a full data snapshot at the export height before proceeding. Snapshotting depends heavily on infrastructure, but generally this can be done by backing up the `.injectived` directory. - -It is critically important to backup the `.injectived/data/priv_validator_state.json` file after stopping your injectived process. This file is updated every block as your validator participates in a consensus rounds. It is a critical file needed to prevent double-signing, in case the upgrade fails and the previous chain needs to be restarted. - -In the event that the upgrade does not succeed, validators and operators must restore the snapshot and downgrade back to [Injective Chain 10011 release](https://github.com/InjectiveLabs/injective-chain-releases/releases/tag/v1.11.6-1688984159) and continue the chain until next upgrade announcement. - -### Upgrade Procedure - -## Notes for Validators -Validator operators should configure the **timeout_commit** in **config.toml** to `300ms`. - -You must remove the wasm cache before upgrading to the new version (rm -rf .injectived/wasm/wasm/cache/). - -1. Verify you are currently running the correct version (`69fb0c5`) of `injectived`: - ```bash - injectived version - Version dev (69fb0c5) - Compiled at 20230710-1016 using Go go1.19.3 (amd64) - ``` - -2. After the chain has halted, make a backup of your `.injectived` directory - ```bash - cp ~/.injectived ./injectived-backup - ``` - **NOTE**: It is recommended for validators and operators to take a full data snapshot at the export height before proceeding in case the upgrade does not go as planned or if not enough voting power comes online in a sufficient and agreed upon amount of time. In such a case, the chain will fallback to continue operating the Chain. See [Recovery](#recovery) for details on how to proceed. - -3. Download and install the injective-chain `v1.12.0 release` - ```bash - wget https://github.com/InjectiveLabs/injective-chain-releases/releases/download/v1.12.0-1704530206/linux-amd64.zip - unzip linux-amd64.zip - sudo mv injectived peggo /usr/bin - sudo mv libwasmvm.x86_64.so /usr/lib - ``` - -4. Verify you are currently running the correct version (`b92723b13`) of `injectived` after downloading the v1.12.0 release: - ```bash - injectived version - Version dev (b92723b13) - Compiled at 20240106-0837 using Go go1.19.3 (amd64) - ``` - -5. Coordinate to restart your injectived with other validators - ```bash - injectived start - ``` - The binary will perform the upgrade automatically and continue the next consensus round if everything goes well. - -6. Verify you are currently running the correct version (`9e702f1`) of `peggo` after downloading the v1.12.0 release: - ```bash - peggo version - Version dev (9e702f1) - Compiled at 20240106-0837 using Go go1.19.3 (amd64) - ``` -8. Start peggo - ```bash - peggo orchestrator - ``` - -## Notes for DEX relayer providers -Relayer upgrade will be available after the chain is successfully upgraded as it relies on several other components that work with injectived. \ No newline at end of file diff --git a/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/canonical-1.12.1.md b/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/canonical-1.12.1.md deleted file mode 100644 index fe4bea84..00000000 --- a/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/canonical-1.12.1.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -sidebar_position: 15 ---- - -# Upgrade to v1.12.1 -Thursday January 22 2024 - -This is a **non-consensus breaking release**, node operators can upgrade in their earliest convenience. - -**Network downtime will not occur during this upgrade.** - -All nodes, validator and non-consensus nodes must be upgraded as soon as possible to this version. - -Validators should also upgrade the peggo version. - - - [Summary](#summary) - - [Risks](#risks) - - [Recovery](#recovery) - - [Upgrade Procedure](#upgrade-procedure) - - [Notes for Validator Operators](##notes-for-validator-operators) - - [Notes for Service Providers](##notes-for-DEX-relayer-providers) - -## Summary - -The Injective Canonical Chain will undergo a improvement upgrade on **Jan 22th**. - -The following is a short summary of the upgrade steps: - -1. Backing up configs, data, and keys used for running the Injective Canonical Chain. -3. Install the [v1.12.1-1705909076](https://github.com/InjectiveLabs/injective-chain-releases/releases/tag/v1.12.1-1705909076) -4. Start your node with the new injectived binary to fulfill the upgrade. - -Upgrade coordination and support for validators will be available on the `#validators` private channel of the [Injective Discord](https://discord.gg/injective). - -The network upgrade can take the following potential pathways: -1. **Happy path** -Validators successfully upgrade chain without purging the blockchain history and all validators are up within 5-10 minutes of the upgrade. - -2. **Not-so-happy path** -Validators have trouble upgrading to latest Canonical chain. - -3. **Abort path** -In the rare event that the team becomes aware of unnoticed critical issues, the Injective team will attempt to patch all the breaking states and provide another official binary within 36 hours. -If the chain is not successfully resumed within 36 hours, the upgrade will be announced as aborted on the #mainnet-validators channel of [Discord](https://discord.gg/injective), and validators will need to resume running the chain without any updates or changes. - -## Recovery - -Prior to exporting chain state, validators are encouraged to take a full data snapshot at the export height before proceeding. Snapshotting depends heavily on infrastructure, but generally this can be done by backing up the `.injectived` directory. - -It is critically important to backup the `.injectived/data/priv_validator_state.json` file after stopping your injectived process. This file is updated every block as your validator participates in a consensus rounds. It is a critical file needed to prevent double-signing, in case the upgrade fails and the previous chain needs to be restarted. - -In the event that the upgrade does not succeed, validators and operators must restore the snapshot and downgrade back to [Injective Chain v1.12.0 release](https://github.com/InjectiveLabs/injective-chain-releases/releases/v1.12.0-1704530206) and continue the chain until next upgrade announcement. - -### Upgrade Procedure - -## Notes for Validators - -You must remove the wasm cache before upgrading to the new version (rm -rf .injectived/wasm/wasm/cache/). - -1. Verify you are currently running the correct version (`b92723b13`) of `injectived`: - ```bash - injectived version - Version dev (b92723b13) - Compiled at 20240106-0837 using Go go1.19.3 (amd64) - ``` - -2. Make a backup of your `.injectived` directory - ```bash - cp ~/.injectived ./injectived-backup - ``` - - 3. Download and install the injective-chain `v1.12.1 release` - ```bash - wget https://github.com/InjectiveLabs/injective-chain-releases/releases/download/v1.12.1-1705909076/linux-amd64.zip - unzip linux-amd64.zip - sudo mv injectived peggo /usr/bin - sudo mv libwasmvm.x86_64.so /usr/lib - ``` - -4. Verify you are currently running the correct version (`c1a64b7ed`) of `injectived` after downloading the v1.12.1 release: - ```bash - injectived version - Version dev (c1a64b7ed) - Compiled at 20240122-0743 using Go go1.19.3 (amd64) - ``` - -5. Start injectived - ```bash - injectived start - ``` -6. Verify you are currently running the correct version (`e8089a7`) of `peggo` after downloading the v1.12.0 release: - ```bash - peggo version - Version dev (e8089a7) - Compiled at 20240122-0743 using Go go1.19.3 (amd64) - ``` -8. Start peggo - ```bash - peggo orchestrator - ``` \ No newline at end of file diff --git a/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/canonical-1.13.0.md b/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/canonical-1.13.0.md deleted file mode 100644 index 5b95c19e..00000000 --- a/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/canonical-1.13.0.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -sidebar_position: 16 ---- - -# Upgrade to v1.13.0 -Thursday August 1 2024 - -Following [proposal 420](https://hub.injective.network/proposals/420/) -This indicates that the upgrade procedure should be performed on block number **80319200** - - - [Summary](#summary) - - [Risks](#risks) - - [Recovery](#recovery) - - [Upgrade Procedure](#upgrade-procedure) - - [Notes for Validator Operators](##notes-for-validator-operators) - - [Notes for Service Providers](##notes-for-DEX-relayer-providers) - -## Summary -The Injective Canonical Chain will undergo a scheduled enhancement upgrade on **Jan 11th 14:00 UTC**. - -The following is a short summary of the upgrade steps: - -1. Vote and wait till the node panics at block height **80319200**. -2. Backing up configs, data, and keys used for running the Injective Canonical Chain. -3. Install the [v1.13.0-1722157491](https://github.com/InjectiveLabs/injective-chain-releases/releases/tag/v1.13.0-1722157491) -4. Start your node with the new injectived binary to fulfill the upgrade. - -Upgrade coordination and support for validators will be available on the `#validators` private channel of the [Injective Discord](https://discord.gg/injective). - -The network upgrade can take the following potential pathways: -1. **Happy path** -Validators successfully upgrade chain without purging the blockchain history and all validators are up within 5-10 minutes of the upgrade. - -2. **Not-so-happy path** -Validators have trouble upgrading to latest Canonical chain. - -3. **Abort path** -In the rare event that the team becomes aware of unnoticed critical issues, the Injective team will attempt to patch all the breaking states and provide another official binary within 36 hours. -If the chain is not successfully resumed within 36 hours, the upgrade will be announced as aborted on the #mainnet-validators channel of [Discord](https://discord.gg/injective), and validators will need to resume running the chain without any updates or changes. - -## Recovery - -Prior to exporting chain state, validators are encouraged to take a full data snapshot at the export height before proceeding. Snapshotting depends heavily on infrastructure, but generally this can be done by backing up the `.injectived` directory. - -It is critically important to backup the `.injectived/data/priv_validator_state.json` file after stopping your injectived process. This file is updated every block as your validator participates in a consensus rounds. It is a critical file needed to prevent double-signing, in case the upgrade fails and the previous chain needs to be restarted. - -In the event that the upgrade does not succeed, validators and operators must restore the snapshot and downgrade back to [Injective Chain v1.12.1 release](https://github.com/InjectiveLabs/injective-chain-releases/releases/tag/v1.12.1-1705909076) and continue the chain until next upgrade announcement. - -### Upgrade Procedure - -## Notes for Validators - -You must remove the wasm cache before upgrading to the new version (rm -rf .injectived/wasm/wasm/cache/). - -1. Verify you are currently running the correct version (`c1a64b7ed`) of `injectived`: - ```bash - injectived version - Version dev (c1a64b7ed) - Compiled at 20240122-0743 using Go go1.19.3 (amd64) - ``` - -2. Make a backup of your `.injectived` directory - ```bash - cp ~/.injectived ./injectived-backup - ``` - - 3. Download and install the injective-chain `v1.13.0 release` - ```bash - wget https://github.com/InjectiveLabs/injective-chain-releases/releases/download/v1.13.0-1722157491/linux-amd64.zip - unzip linux-amd64.zip - sudo mv injectived peggo /usr/bin - sudo mv libwasmvm.x86_64.so /usr/lib - ``` - -4. Verify you are currently running the correct version (`c1a64b7ed`) of `injectived` after downloading the v1.13.0 release: - ```bash - injectived version - Version dev (af924ca9) - Compiled at 20240728-0905 using Go go1.22.5 (amd64) - ``` - -5. Start injectived - ```bash - injectived start - ``` -6. Verify you are currently running the correct version (`ead1119`) of `peggo` after downloading the v1.13.0 release: - ```bash - peggo version - Version dev (ead1119) - Compiled at 20240728-0905 using Go go1.22.5 (amd64) - ``` -8. Start peggo - ```bash - peggo orchestrator - ``` diff --git a/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/canonical-1.13.2.md b/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/canonical-1.13.2.md deleted file mode 100644 index 437af409..00000000 --- a/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/canonical-1.13.2.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -sidebar_position: 17 ---- - -# Upgrade to v1.13.2 -Thursday August 20 2024 - -Following [proposal 424](https://hub.injective.network/proposal/424/) -This indicates that the upgrade procedure should be performed on block number **82830000** - - - [Summary](#summary) - - [Risks](#risks) - - [Recovery](#recovery) - - [Upgrade Procedure](#upgrade-procedure) - - [Notes for Validator Operators](##notes-for-validator-operators) - - [Notes for Service Providers](##notes-for-DEX-relayer-providers) - -## Summary -The Injective Canonical Chain will undergo a scheduled enhancement upgrade on **Aug 20th 15:00 UTC**. - -The following is a short summary of the upgrade steps: - -1. Vote and wait till the node panics at block height **82830000**. -2. Backing up configs, data, and keys used for running the Injective Canonical Chain. -3. Install the [v1.13.2-1723753267](https://github.com/InjectiveLabs/injective-chain-releases/releases/tag/v1.13.2-1723753267) -4. Start your node with the new injectived binary to fulfill the upgrade. - -Upgrade coordination and support for validators will be available on the `#validators` private channel of the [Injective Discord](https://discord.gg/injective). - -The network upgrade can take the following potential pathways: -1. **Happy path** -Validators successfully upgrade chain without purging the blockchain history and all validators are up within 5-10 minutes of the upgrade. - -2. **Not-so-happy path** -Validators have trouble upgrading to latest Canonical chain. - -3. **Abort path** -In the rare event that the team becomes aware of unnoticed critical issues, the Injective team will attempt to patch all the breaking states and provide another official binary within 36 hours. -If the chain is not successfully resumed within 36 hours, the upgrade will be announced as aborted on the #mainnet-validators channel of [Discord](https://discord.gg/injective), and validators will need to resume running the chain without any updates or changes. - -## Recovery - -Prior to exporting chain state, validators are encouraged to take a full data snapshot at the export height before proceeding. Snapshotting depends heavily on infrastructure, but generally this can be done by backing up the `.injectived` directory. - -It is critically important to backup the `.injectived/data/priv_validator_state.json` file after stopping your injectived process. This file is updated every block as your validator participates in a consensus rounds. It is a critical file needed to prevent double-signing, in case the upgrade fails and the previous chain needs to be restarted. - -In the event that the upgrade does not succeed, validators and operators must restore the snapshot and downgrade back to [Injective Chain v1.13.2 release](https://github.com/InjectiveLabs/injective-chain-releases/releases/tag/v1.13.2-1723753267) and continue the chain until next upgrade announcement. - -### Upgrade Procedure - -## Notes for Validators - -You must remove the wasm cache before upgrading to the new version (rm -rf .injectived/wasm/wasm/cache/). - -1. Verify you are currently running the correct version (`af924ca9`) of `injectived`: - ```bash - injectived version - Version dev (af924ca9) - Compiled at 20240728-0905 using Go go1.22.5 (amd64) - ``` - -2. Make a backup of your `.injectived` directory - ```bash - cp ~/.injectived ./injectived-backup - ``` - - 3. Download and install the injective-chain `v1.13.2 release` - ```bash - wget https://github.com/InjectiveLabs/injective-chain-releases/releases/download/v1.13.2-1723753267/linux-amd64.zip - unzip linux-amd64.zip - sudo mv injectived peggo /usr/bin - sudo mv libwasmvm.x86_64.so /usr/lib - ``` - -4. Verify you are currently running the correct version (`6f57bf03`) of `injectived` after downloading the v1.13.2 release: - ```bash - injectived version - Version dev (6f57bf03) - Compiled at 20240815-2021 using Go go1.22.5 (amd64) - ``` - -5. Start injectived - ```bash - injectived start - ``` -6. Verify you are currently running the correct version (`ead1119`) of `peggo` after downloading the v1.13.2 release: - ```bash - peggo version - Version dev (ead1119) - Compiled at 20240815-2021 using Go go1.22.5 (amd64) - ``` -8. Start peggo - ```bash - peggo orchestrator - ``` diff --git a/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/canonical-10002-rc1.md b/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/canonical-10002-rc1.md deleted file mode 100644 index b4241de6..00000000 --- a/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/canonical-10002-rc1.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -title: Upgrade to 10002-rc1 -sidebar_position: 3 ---- -# Upgrade to 10002-rc1 -Nov 8th 2021 - -The upgrade will take place via an on-chain software upgrade proposal passed by Injective governance. If passed, this proposal would commit the Injective Mainnet to halting the Canary Chain `injectived` application binary at approximately **14:00 UTC on Nov 8th** and starting the application binary for the Injective Canonical Chain. - -In case of a failed migration via the upgrade module, the Injective Labs team will post an official `injective-canonical-chain` genesis file, but it is recommended that validators should do try to export the genesis on their own node to verify the resulting genesis file. - -Following [proposal #65](https://hub.injective.network/proposals/65) -This indicates that the upgrade procedure should be performed on block number **4,352,000**. - - - [Summary](#summary) - - [Risks](#risks) - - [Recovery](#recovery) - - [Upgrade Procedure](#upgrade-procedure) - - [Notes for Service Providers](#notes-for-DEX-relayer-providers) - -## Summary - -The Injective Canary Chain will undergo a scheduled upgrade to Injective Canonical Chain on **Monday, November 8th 2021**. - -The following is a short summary of the upgrade steps: - -1. Vote and wait till the node panics at block height **4,352,000**. -2. Backing up configs, data, and keys used for running the Injective Canary Chain. -3. Install the [Injective 10002-rc1 release](https://github.com/InjectiveLabs/injective-chain-releases/releases/tag/v1.1.0-1636178708) -4. Start your node with the new injectived binary to fulfill the upgrade. - -Upgrade coordination and support for validators will be available on the `#mainnet-validators` private channel of the [Injective Discord](https://discord.gg/injective). - -The network upgrade can take the following potential pathways: -1. **Happy path** -Validators successfully migrate from the Canary chain to Canonical chain without purging the blockchain history and all validators are up within 1-2 hours of the scheduled upgrade. - -2. **Not-so-happy path** -Validators have trouble migrating from the Canary chain to Canonical chain. This could be some consensus breaking changes not covered in upgrade handler, or compatibility issue of the migrated state with new injectived binary, but validators can at least export the genesis. - -3. **Abort path** -In the rare event that the team becomes aware of unnoticed critical issues, the Injective team will attempt to patch all the breaking states and provide another official binary within 36 hours. -If the chain is not successfully resumed within 36 hours, the upgrade will be announced as aborted on the #mainnet-validators channel of [Discord](https://discord.gg/injective), and validators will need to resume running the Canary chain without any updates or changes. A new governance proposal for the upgrade will need to be issued and voted on by the community for the next upgrade. - -## Risks - -As a validator performing the upgrade procedure on your consensus nodes carries a heightened risk of -double-signing and being slashed. The most important piece of this procedure is verifying your -software version and genesis file hash before starting your validator and signing. - -The riskiest thing a validator can do is discover that they made a mistake and repeat the upgrade -procedure again during the network startup. If you discover a mistake in the process, the best thing -to do is wait for the network to start before correcting it. If the network is halted and you have -started with a different genesis file than the expected one, seek advice from an Injective developer -before resetting your validator. - -## Recovery - -Prior to exporting the Canary chain state, validators are encouraged to take a full data snapshot at the -export height before proceeding. Snapshotting depends heavily on infrastructure, but generally this -can be done by backing up the `.injectived` directory. - -It is critically important to backup the `.injectived/data/priv_validator_state.json` file after stopping your injectived process. This file is updated every block as your validator participates in a consensus rounds. It is a critical file needed to prevent double-signing, in case the upgrade fails and the previous chain needs to be restarted. - -In the event that the upgrade does not succeed, validators and operators must restore the snapshot and downgrade back to [Injective Chain 10001-rc7 release](https://github.com/InjectiveLabs/injective-chain-releases/releases/tag/v1.0.1-1635956190) and continue the chain until next upgrade announcement. - -### Upgrade Procedure - - - -1. Verify you are currently running the correct version (`b174465c`) of `injectived`: - ```bash - $ injectived version - commit: b174465c - go: go1.16.8 - ``` - -2. After the chain has halted, make a backup of your `.injectived` directory - ```bash - cp ~/.injectived ./injectived-backup - ``` - **NOTE**: It is recommended for validators and operators to take a full data snapshot at the export - height before proceeding in case the upgrade does not go as planned or if not enough voting power - comes online in a sufficient and agreed upon amount of time. In such a case, the chain will fallback - to continue operating the Canary Chain. See [Recovery](#recovery) for details on how to proceed. - -3. Download and install the injective-chain `10002-rc1 release` - ```bash - wget https://github.com/InjectiveLabs/injective-chain-releases/releases/download/v1.1.0-1636178708/linux-amd64.zip - unzip linux-amd64.zip - sudo mv injectived peggo /usr/bin - ``` - -4. Verify you are currently running the correct version (`eb018590`) of `injectived` after downloading the 10002-rc1 release: - ```bash - $ injectived version - commit: eb018590 - go: go1.17.2 - ``` - -5. Coordinate to restart your injectived with other validators - ```bash - injectived start - ``` - The binary will perform the upgrade automatically and continue the next consensus round if everything goes well. \ No newline at end of file diff --git a/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/canonical-10002-rc2.md b/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/canonical-10002-rc2.md deleted file mode 100644 index 59c46936..00000000 --- a/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/canonical-10002-rc2.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -sidebar_position: 4 ---- -# Upgrade to 10002-rc2 -November 15th 2021 - -Following [proposal #70](https://hub.injective.network/proposals/70) -This indicates that the upgrade procedure should be performed on block number **4, 594, 100** - - - [Summary](#summary) - - [Risks](#risks) - - [Recovery](#recovery) - - [Upgrade Procedure](#upgrade-procedure) - - [Notes for Service Providers](#notes-for-DEX-relayer-providers) - -## Summary - -The Injective Canonical Chain will undergo a scheduled upgrade to Injective Canonical Chain on **Monday, November 15th 2021**. - -The following is a short summary of the upgrade steps: - -1. Vote and wait till the node panics at block height **4, 594, 100**. -2. Backing up configs, data, and keys used for running the Injective Canary Chain. -3. Install the [Injective Chain 10002-rc2 release](https://github.com/InjectiveLabs/injective-chain-releases/releases/tag/v1.1.1-1636733798) -4. Start your node with the new injectived binary to fulfill the upgrade. - -Upgrade coordination and support for validators will be available on the `#mainnet-validators` private channel of the [Injective Discord](https://discord.gg/injective). - -The network upgrade can take the following potential pathways: -1. **Happy path** -Validators successfully upgrade chain without purging the blockchain history and all validators are up within 1-2 hours of the scheduled upgrade. - -2. **Not-so-happy path** -Validators have trouble upgrade chain. This could be some consensus breaking changes not covered in upgrade handler, or compatibility issue of the migrated state with new injectived binary, but validators can at least export the genesis. - -3. **Abort path** -In the rare event that the team becomes aware of unnoticed critical issues, the Injective team will attempt to patch all the breaking states and provide another official binary within 36 hours. -If the chain is not successfully resumed within 36 hours, the upgrade will be announced as aborted on the #mainnet-validators channel of [Discord](https://discord.gg/injective), and validators will need to resume running the chain without any updates or changes. A new governance proposal for the upgrade will need to be issued and voted on by the community for the next upgrade. - -## Risks - -As a validator performing the upgrade procedure on your consensus nodes carries a heightened risk of -double-signing and being slashed. The most important piece of this procedure is verifying your -software version and genesis file hash before starting your validator and signing. - -The riskiest thing a validator can do is discover that they made a mistake and repeat the upgrade -procedure again during the network startup. If you discover a mistake in the process, the best thing -to do is wait for the network to start before correcting it. If the network is halted and you have -started with a different genesis file than the expected one, seek advice from an Injective developer -before resetting your validator. - -## Recovery - -Prior to exporting thechain state, validators are encouraged to take a full data snapshot at the -export height before proceeding. Snapshotting depends heavily on infrastructure, but generally this -can be done by backing up the `.injectived` directory. - -It is critically important to backup the `.injectived/data/priv_validator_state.json` file after stopping your injectived process. This file is updated every block as your validator participates in a consensus rounds. It is a critical file needed to prevent double-signing, in case the upgrade fails and the previous chain needs to be restarted. - -In the event that the upgrade does not succeed, validators and operators must restore the snapshot and downgrade back to [Injective Chain 10002-rc1 release](https://github.com/InjectiveLabs/injective-chain-releases/releases/tag/v1.1.0-1636178708) and continue the chain until next upgrade announcement. - -### Upgrade Procedure - -1. Verify you are currently running the correct version (`eb018590`) of `injectived`: - ```bash - $ injectived version - commit: eb018590 - Compiled at 20211106-0605 using Go go1.17.2 (amd64) - - ``` - -2. After the chain has halted, make a backup of your `.injectived` directory - ```bash - cp ~/.injectived ./injectived-backup - ``` - **NOTE**: It is recommended for validators and operators to take a full data snapshot at the export - height before proceeding in case the upgrade does not go as planned or if not enough voting power - comes online in a sufficient and agreed upon amount of time. In such a case, the chain will fallback - to continue operating. See [Recovery](#recovery) for details on how to proceed. - -3. Download and install the injective-chain `10002-rc2 release` - ```bash - wget https://github.com/InjectiveLabs/injective-chain-releases/releases/download/v1.1.1-1636733798/linux-amd64.zip - unzip linux-amd64.zip - sudo mv injectived peggo /usr/bin - ``` - -4. Verify you are currently running the correct version (`096cbe5`) of `injectived` after downloading the 10002-rc2 release: - ```bash - $ injectived version - Version dev (096cbe5) - Compiled at 20211112-1620 using Go go1.17.2 (amd64) - ``` - -5. Coordinate to restart your injectived with other validators - ```bash - injectived start - ``` - The binary will perform the upgrade automatically and continue the next consensus round if everything goes well. \ No newline at end of file diff --git a/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/canonical-10003-rc1.md b/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/canonical-10003-rc1.md deleted file mode 100644 index f6e5fe00..00000000 --- a/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/canonical-10003-rc1.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -sidebar_position: 5 ---- - -# Upgrade to 10003-rc1 -Thursday Dec 30th - -Following [proposal #93](https://hub.injective.network/proposals/93) -This indicates that the upgrade procedure should be performed on block number **6159200** - - - [Summary](#summary) - - [Risks](#risks) - - [Recovery](#recovery) - - [Upgrade Procedure](#upgrade-procedure) - - [Notes for Service Providers](#notes-for-DEX-relayer-providers) - -## Summary - -The Injective Canonical Chain will undergo a scheduled enhancement upgrade on **Thursday Dec 30th (approximately 14:00 UTC)**. - -The following is a short summary of the upgrade steps: - -1. Vote and wait till the node panics at block height **6159200**. -2. Backing up configs, data, and keys used for running the Injective Canonical Chain. -3. Install the [Mainnet-10003-rc1-1640627705](https://github.com/InjectiveLabs/injective-chain-releases/releases/tag/v1.1.1-1640627705) -4. Start your node with the new injectived binary to fulfill the upgrade. - -Upgrade coordination and support for validators will be available on the `#mainnet-validators` private channel of the [Injective Discord](https://discord.gg/injective). - -The network upgrade can take the following potential pathways: -1. **Happy path** -Validators successfully upgrade chain without purging the blockchain history and all validators are up within 1-2 hours of the scheduled upgrade. - -2. **Not-so-happy path** -Validators have trouble upgrading to latest Canonical chain. This could be some consensus breaking changes not covered in upgrade handler, or compatibility issue of the migrated state with new injectived binary, but validators can at least export the genesis. - -3. **Abort path** -In the rare event that the team becomes aware of unnoticed critical issues, the Injective team will attempt to patch all the breaking states and provide another official binary within 36 hours. -If the chain is not successfully resumed within 36 hours, the upgrade will be announced as aborted on the #mainnet-validators channel of [Discord](https://discord.gg/injective), and validators will need to resume running the chain without any updates or changes. A new governance proposal for the upgrade will need to be issued and voted on by the community for the next upgrade. - -## Risks - -As a validator performing the upgrade procedure on your consensus nodes carries a heightened risk of -double-signing and being slashed. The most important piece of this procedure is verifying your -software version and genesis file hash before starting your validator and signing. - -The riskiest thing a validator can do is discover that they made a mistake and repeat the upgrade -procedure again during the network startup. If you discover a mistake in the process, the best thing -to do is wait for the network to start before correcting it. If the network is halted and you have -started with a different genesis file than the expected one, seek advice from an Injective developer -before resetting your validator. - -## Recovery - -Prior to exporting chain state, validators are encouraged to take a full data snapshot at the -export height before proceeding. Snapshotting depends heavily on infrastructure, but generally this -can be done by backing up the `.injectived` directory. - -It is critically important to backup the `.injectived/data/priv_validator_state.json` file after stopping your injectived process. This file is updated every block as your validator participates in a consensus rounds. It is a critical file needed to prevent double-signing, in case the upgrade fails and the previous chain needs to be restarted. - -In the event that the upgrade does not succeed, validators and operators must restore the snapshot and downgrade back to [Injective Chain 10002-rc2 release](https://github.com/InjectiveLabs/injective-chain-releases/releases/tag/v1.1.1-1636733798) and continue the chain until next upgrade announcement. - -### Upgrade Procedure - -1. Verify you are currently running the correct version (`096cbe5`) of `injectived`: - ```bash - $ injectived version - commit: 096cbe5 - Compiled at 20211106-0605 using Go go1.17.2 (amd64) - - ``` - -2. After the chain has halted, make a backup of your `.injectived` directory - ```bash - cp ~/.injectived ./injectived-backup - ``` - **NOTE**: It is recommended for validators and operators to take a full data snapshot at the export - height before proceeding in case the upgrade does not go as planned or if not enough voting power - comes online in a sufficient and agreed upon amount of time. In such a case, the chain will fallback - to continue operating the Chain. See [Recovery](#recovery) for details on how to proceed. - -3. Download and install the injective-chain `10003-rc1 release` - ```bash - wget https://github.com/InjectiveLabs/injective-chain-releases/releases/download/v1.1.1-1640627705/linux-amd64.zip - unzip linux-amd64.zip - sudo mv injectived peggo /usr/bin - ``` - -4. Verify you are currently running the correct version (`260e526`) of `injectived` after downloading the 10003-rc1 release: - ```bash - $ injectived version - Version dev (260e526) - Compiled at 20211227-1757 using Go go1.17.2 (amd64) - ``` - -5. Coordinate to restart your injectived with other validators - ```bash - injectived start - ``` - The binary will perform the upgrade automatically and continue the next consensus round if everything goes well. - - -## Notes for DEX relayer providers -Relayer upgrade will be available after the chain is successfully upgraded as it relies on several other components that work with injectived. diff --git a/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/canonical-10004-rc1-patch.md b/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/canonical-10004-rc1-patch.md deleted file mode 100644 index f13be39c..00000000 --- a/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/canonical-10004-rc1-patch.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -sidebar_position: 7 ---- - -# Upgrade to 10004-rc1-patch -Sunday Feb 20th - -Upgrade Injective from 10004-rc1 to 10004-rc1 [patch version 10004-rc1-1645352045](https://github.com/InjectiveLabs/injective-chain-releases/releases/tag/v1.4.0-1645352045) created due to an incident that happened on Sunday, Feb 20 at 3:55 AM UTC-05:00, when [Network halted at block 7941974](https://explorer.injective.network/block/7941974). - -This indicates that the upgrade procedure should be performed on block number **7941974** - - - [Summary](#summary) - - [Risks](#risks) - - [Recovery](#recovery) - - [Upgrade Procedure](#upgrade-procedure) - - [Notes for Service Providers](#notes-for-DEX-relayer-providers) - -## Summary - -- At 3:55 AM UTC-05:00 Network halted, [block height 7941974](https://explorer.injective.network/block/7941974) -- At 5:05 AM UTC-05:00 [New release created with rolled back fix, Version 10004-rc1-1645352045](https://github.com/InjectiveLabs/injective-chain-releases/releases/tag/v1.4.0-1645352045) -- At 06:08 UTC-05:00 [Network is back up]( https://explorer.injective.network/block/7941975) - - -The following is a short summary of the upgrade steps: - -1. Backing up configs, data, and keys used for running the Injective Canonical Chain. -2. Install the [Mainnet-10004-rc1-v1.4.0-1642928125](https://github.com/InjectiveLabs/injective-chain-releases/releases/tag/v1.4.0-1645352045) -3. Start your node with the new injectived binary to fulfill the upgrade. - -Upgrade coordination and support for validators will be available on the `#mainnet-validators` private channel of the [Injective Discord](https://discord.gg/injective). - -The network upgrade can take the following potential pathways: -1. Happy path -Validators successfully migrate from the 10004-rc1 Injective Chain to 10004-rc1 patch without purging the blockchain history and all validators are up within 1-2 hours. - -2. Not-so-happy path -Validators have trouble upgrading the chain. This could be some consensus-breaking changes not covered in the upgrade handler, or compatibility issue of the migrated state with new injectived binary, but validators can at least export the genesis. - -3. Abort path -In the rare event that the team becomes aware of unnoticed critical issues, the Injective team will attempt to patch all the breaking states and provide another official binary within 36 hours. - -## Recovery - -Prior to exporting Injective state, validators are encouraged to take a full data snapshot at the -export height before proceeding. Snapshotting depends heavily on infrastructure, but generally, this -can be done by backing up the `.injectived` directory. We would suggest using `aws s3 sync` with the delete flag, this will shorten the snapshotting time as only the file diffs are uploaded to the S3 bucket. - -It is critically important to back up the `.injectived/data/priv_validator_state.json` file after stopping your injectived process. This file is updated every block as your validator participates in consensus rounds. It is a critical file needed to prevent double-signing, in case the upgrade fails and the previous chain needs to be restarted. - -## Upgrade Procedure - -1. Verify you are currently running the correct (pre-upgrade) version (`94583db`) of `injectived`: - ```bash - $ injectived version - Version dev (94583db) - Compiled at 20220123-0855 using Go go1.17.6 (amd64) - ``` - -2. After the chain has halted, make a backup of your `.injectived` directory - ```bash - cp ~/.injectived ./injectived-backup - ``` - **NOTE**: It is recommended for validators and operators to take a full data snapshot at the export - height before proceeding in case the upgrade does not go as planned or if not enough voting power - comes online in a sufficient and agreed upon amount of time. In such a case, the chain will fallback - to continue operating the existing Canonical Chain. See [Recovery](#recovery) for details on how to proceed. - -3. Download and install Injective 10004-rc1 release - ```bash - wget https://github.com/InjectiveLabs/injective-chain-releases/releases/download/v1.4.0-1645352045/linux-amd64.zip - unzip linux-amd64.zip - sudo mv injectived /usr/bin - ``` - -4. Verify you are currently running the correct new version (`30b3dbf`) of `injectived` after downloading the 10004-rc1 release: - ```bash - $ injectived version - Version dev (30b3dbf) - Compiled at 20220220-1014 using Go go1.17.6 (amd64) - ``` - -5. Coordinate to restart your injectived with other validators - ```bash - injectived start - ``` - The binary will perform the upgrade automatically and continue the next consensus round if everything goes well. - -## Notes for DEX relayer providers -Relayer upgrade will be available after the chain is successfully upgraded as it relies on several other components that work with injectived. \ No newline at end of file diff --git a/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/canonical-10004-rc1.md b/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/canonical-10004-rc1.md deleted file mode 100644 index 08d135f8..00000000 --- a/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/canonical-10004-rc1.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -sidebar_position: 6 ---- - -# Upgrade to 10004-rc1 -Thuesday Jan 25th - -Following [proposal #106](https://hub.injective.network/proposals/106) -This indicates that the upgrade procedure should be performed on block number **7067700** - - - [Summary](#summary) - - [Risks](#risks) - - [Recovery](#recovery) - - [Upgrade Procedure](#upgrade-procedure) - - [Notes for Service Providers](#notes-for-DEX-relayer-providers) - -## Summary - -The Injective Canonical Chain will undergo a scheduled enhancement upgrade on **Tuesday Jan 25th (approximately at 14:00 UTC)**. - -The following is a short summary of the upgrade steps: - -1. Vote and wait till the node panics at block height **7067700**. -2. Backing up configs, data, and keys used for running the Injective Canonical Chain. -3. Install the [Mainnet-10004-rc1-v1.4.0-1642928125](https://github.com/InjectiveLabs/injective-chain-releases/releases/tag/v1.4.0-1642928125) -4. Start your node with the new injectived binary to fulfill the upgrade. - -Upgrade coordination and support for validators will be available on the `#mainnet-validators` private channel of the [Injective Discord](https://discord.gg/injective). - -The network upgrade can take the following potential pathways: -1. **Happy path** -Validators successfully upgrade chain without purging the blockchain history and all validators are up within 1-2 hours of the scheduled upgrade. - -2. **Not-so-happy path** -Validators have trouble upgrading to latest Canonical chain. This could be some consensus breaking changes not covered in upgrade handler, or compatibility issue of the migrated state with new injectived binary, but validators can at least export the genesis. - -3. **Abort path** -In the rare event that the team becomes aware of unnoticed critical issues, the Injective team will attempt to patch all the breaking states and provide another official binary within 36 hours. -If the chain is not successfully resumed within 36 hours, the upgrade will be announced as aborted on the #mainnet-validators channel of [Discord](https://discord.gg/injective), and validators will need to resume running the chain without any updates or changes. A new governance proposal for the upgrade will need to be issued and voted on by the community for the next upgrade. - -## Risks - -As a validator performing the upgrade procedure on your consensus nodes carries a heightened risk of -double-signing and being slashed. The most important piece of this procedure is verifying your -software version and genesis file hash before starting your validator and signing. - -The riskiest thing a validator can do is discover that they made a mistake and repeat the upgrade -procedure again during the network startup. If you discover a mistake in the process, the best thing -to do is wait for the network to start before correcting it. If the network is halted and you have -started with a different genesis file than the expected one, seek advice from an Injective developer -before resetting your validator. - -## Recovery - -Prior to exporting chain state, validators are encouraged to take a full data snapshot at the -export height before proceeding. Snapshotting depends heavily on infrastructure, but generally this -can be done by backing up the `.injectived` directory. - -It is critically important to backup the `.injectived/data/priv_validator_state.json` file after stopping your injectived process. This file is updated every block as your validator participates in a consensus rounds. It is a critical file needed to prevent double-signing, in case the upgrade fails and the previous chain needs to be restarted. - -In the event that the upgrade does not succeed, validators and operators must restore the snapshot and downgrade back to [Injective Chain 10003-rc1 release](https://github.com/InjectiveLabs/injective-chain-releases/releases/tag/v1.1.1-1640627705) and continue the chain until next upgrade announcement. - -### Upgrade Procedure - -1. Verify you are currently running the correct version (`260e526`) of `injectived`: - ```bash - $ injectived version - commit: 260e526 - Compiled at 20211227-1757 using Go go1.17.2 (amd64) - - ``` - -2. After the chain has halted, make a backup of your `.injectived` directory - ```bash - cp ~/.injectived ./injectived-backup - ``` - **NOTE**: It is recommended for validators and operators to take a full data snapshot at the export - height before proceeding in case the upgrade does not go as planned or if not enough voting power - comes online in a sufficient and agreed upon amount of time. In such a case, the chain will fallback - to continue operating the Chain. See [Recovery](#recovery) for details on how to proceed. - -3. Download and install the injective-chain `10004-rc1 release` - ```bash - wget https://github.com/InjectiveLabs/injective-chain-releases/releases/download/v1.4.0-1642928125/linux-amd64.zip - unzip linux-amd64.zip - sudo mv injectived peggo /usr/bin - ``` - -4. Verify you are currently running the correct version (`94583db`) of `injectived` after downloading the 10004-rc1 release: - ```bash - $ injectived version - Version dev (94583db) - Compiled at 20220123-0855 using Go go1.17.6 (amd64) - ``` - -5. Coordinate to restart your injectived with other validators - ```bash - injectived start - ``` - The binary will perform the upgrade automatically and continue the next consensus round if everything goes well. - - -## Notes for DEX relayer providers -Relayer upgrade will be available after the chain is successfully upgraded as it relies on several other components that work with injectived. diff --git a/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/canonical-10005-rc1.md b/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/canonical-10005-rc1.md deleted file mode 100644 index d510cab4..00000000 --- a/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/canonical-10005-rc1.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -sidebar_position: 8 ---- - -# Upgrade to 10005-rc1 -Monday April 11th - -Following [proposal #133](https://hub.injective.network/proposals/133) -This indicates that the upgrade procedure should be performed on block number **9614200** - - - [Summary](#summary) - - [Risks](#risks) - - [Recovery](#recovery) - - [Upgrade Procedure](#upgrade-procedure) - - [Notes for Service Providers](#notes-for-DEX-relayer-providers) - -## Summary - -The Injective Canonical Chain will undergo a scheduled enhancement upgrade on **Monday April 11th (approximately at 14:00 UTC)**. - -The following is a short summary of the upgrade steps: - -1. Vote and wait till the node panics at block height **9614200**. -2. Backing up configs, data, and keys used for running the Injective Canonical Chain. -3. Install the [Mainnet-v1.5.0-1649280277](https://github.com/InjectiveLabs/injective-chain-releases/releases/tag/v1.5.0-1649280277) -4. Start your node with the new injectived binary to fulfill the upgrade. - -Upgrade coordination and support for validators will be available on the `#mainnet-validators` private channel of the [Injective Discord](https://discord.gg/injective). - -The network upgrade can take the following potential pathways: -1. **Happy path** -Validators successfully upgrade chain without purging the blockchain history and all validators are up within 1-2 hours of the scheduled upgrade. - -2. **Not-so-happy path** -Validators have trouble upgrading to latest Canonical chain. This could be some consensus breaking changes not covered in upgrade handler, or compatibility issue of the migrated state with new injectived binary, but validators can at least export the genesis. - -3. **Abort path** -In the rare event that the team becomes aware of unnoticed critical issues, the Injective team will attempt to patch all the breaking states and provide another official binary within 36 hours. -If the chain is not successfully resumed within 36 hours, the upgrade will be announced as aborted on the #mainnet-validators channel of [Discord](https://discord.gg/injective), and validators will need to resume running the chain without any updates or changes. A new governance proposal for the upgrade will need to be issued and voted on by the community for the next upgrade. - -## Risks - -As a validator performing the upgrade procedure on your consensus nodes carries a heightened risk of -double-signing and being slashed. The most important piece of this procedure is verifying your -software version and genesis file hash before starting your validator and signing. - -The riskiest thing a validator can do is discover that they made a mistake and repeat the upgrade -procedure again during the network startup. If you discover a mistake in the process, the best thing -to do is wait for the network to start before correcting it. If the network is halted and you have -started with a different genesis file than the expected one, seek advice from an Injective developer -before resetting your validator. - -## Recovery - -Prior to exporting chain state, validators are encouraged to take a full data snapshot at the -export height before proceeding. Snapshotting depends heavily on infrastructure, but generally this -can be done by backing up the `.injectived` directory. - -It is critically important to backup the `.injectived/data/priv_validator_state.json` file after stopping your injectived process. This file is updated every block as your validator participates in a consensus rounds. It is a critical file needed to prevent double-signing, in case the upgrade fails and the previous chain needs to be restarted. - -In the event that the upgrade does not succeed, validators and operators must restore the snapshot and downgrade back to [Injective Chain 10004-rc1-patch release](https://github.com/InjectiveLabs/injective-chain-releases/releases/tag/v1.4.0-1645352045) and continue the chain until next upgrade announcement. - -### Upgrade Procedure - -1. Verify you are currently running the correct version (`30b3dbf`) of `injectived`: - ```bash - $ injectived version - Version dev (30b3dbf) - Compiled at 20220220-1014 using Go go1.17.6 (amd64) - ``` - -2. After the chain has halted, make a backup of your `.injectived` directory - ```bash - cp ~/.injectived ./injectived-backup - ``` - **NOTE**: It is recommended for validators and operators to take a full data snapshot at the export - height before proceeding in case the upgrade does not go as planned or if not enough voting power - comes online in a sufficient and agreed upon amount of time. In such a case, the chain will fallback - to continue operating the Chain. See [Recovery](#recovery) for details on how to proceed. - -3. Download and install the injective-chain `10005-rc1 release` - ```bash - wget https://github.com/InjectiveLabs/injective-chain-releases/releases/download/v1.5.0-1649280277/linux-amd64.zip - unzip linux-amd64.zip - sudo mv injectived peggo /usr/bin - ``` - -4. Verify you are currently running the correct version (`568ce23`) of `injectived` after downloading the 10005-rc1 release: - ```bash - $ injectived version - Version dev (568ce23) - Compiled at 20220406-2125 using Go go1.18 (amd64) - ``` - -5. Coordinate to restart your injectived with other validators - ```bash - injectived start - ``` - The binary will perform the upgrade automatically and continue the next consensus round if everything goes well. - - -## Notes for DEX relayer providers -Relayer upgrade will be available after the chain is successfully upgraded as it relies on several other components that work with injectived. diff --git a/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/canonical-10006-rc1.md b/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/canonical-10006-rc1.md deleted file mode 100644 index 0dc74bbc..00000000 --- a/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/canonical-10006-rc1.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -sidebar_position: 9 ---- - -# Upgrade to 10006-rc1 -Tuesday July 5th 2022 - -Following [proposal 159](https://hub.injective.network/proposals/159/) -This indicates that the upgrade procedure should be performed on block number **12569420** - - - [Summary](#summary) - - [Risks](#risks) - - [Recovery](#recovery) - - [Upgrade Procedure](#upgrade-procedure) - - [Notes for Service Providers](#notes-for-DEX-relayer-providers) - -## Summary - -The Injective Canonical Chain will undergo a scheduled enhancement upgrade on **July 5th 2022 14:00 UTC**. - -The following is a short summary of the upgrade steps: - -1. Vote and wait till the node panics at block height **12569420**. -2. Backing up configs, data, and keys used for running the Injective Canonical Chain. -3. Install the [Mainnet-v1.6.0-1656650662](https://github.com/InjectiveLabs/injective-chain-releases/releases/tag/v1.6.0-1656650662) -4. Start your node with the new injectived binary to fulfill the upgrade. - -Upgrade coordination and support for validators will be available on the `#mainnet-validators` private channel of the [Injective Discord](https://discord.gg/injective). - -The network upgrade can take the following potential pathways: -1. **Happy path** -Validators successfully upgrade chain without purging the blockchain history and all validators are up within 1-2 hours of the scheduled upgrade. - -2. **Not-so-happy path** -Validators have trouble upgrading to latest Canonical chain. This could be some consensus breaking changes not covered in upgrade handler, or compatibility issue of the migrated state with new injectived binary, but validators can at least export the genesis. - -3. **Abort path** -In the rare event that the team becomes aware of unnoticed critical issues, the Injective team will attempt to patch all the breaking states and provide another official binary within 36 hours. -If the chain is not successfully resumed within 36 hours, the upgrade will be announced as aborted on the #mainnet-validators channel of [Discord](https://discord.gg/injective), and validators will need to resume running the chain without any updates or changes. A new governance proposal for the upgrade will need to be issued and voted on by the community for the next upgrade. - -## Risks - -As a validator performing the upgrade procedure on your consensus nodes carries a heightened risk of -double-signing and being slashed. The most important piece of this procedure is verifying your -software version and genesis file hash before starting your validator and signing. - -The riskiest thing a validator can do is discover that they made a mistake and repeat the upgrade -procedure again during the network startup. If you discover a mistake in the process, the best thing -to do is wait for the network to start before correcting it. If the network is halted and you have -started with a different genesis file than the expected one, seek advice from an Injective developer -before resetting your validator. - -## Recovery - -Prior to exporting chain state, validators are encouraged to take a full data snapshot at the -export height before proceeding. Snapshotting depends heavily on infrastructure, but generally this -can be done by backing up the `.injectived` directory. - -It is critically important to backup the `.injectived/data/priv_validator_state.json` file after stopping your injectived process. This file is updated every block as your validator participates in a consensus rounds. It is a critical file needed to prevent double-signing, in case the upgrade fails and the previous chain needs to be restarted. - -In the event that the upgrade does not succeed, validators and operators must restore the snapshot and downgrade back to [Injective Chain 10005-rc1 release](https://github.com/InjectiveLabs/injective-chain-releases/releases/download/v1.5.0-1649280277/linux-amd64.zip) and continue the chain until next upgrade announcement. - -### Upgrade Procedure - -1. Verify you are currently running the correct version (`568ce23`) of `injectived`: - ```bash - $ injectived version - Version dev (568ce23) - Compiled at 20220406-2125 using Go go1.18 (amd64) - ``` - -2. After the chain has halted, make a backup of your `.injectived` directory - ```bash - cp ~/.injectived ./injectived-backup - ``` - **NOTE**: It is recommended for validators and operators to take a full data snapshot at the export - height before proceeding in case the upgrade does not go as planned or if not enough voting power - comes online in a sufficient and agreed upon amount of time. In such a case, the chain will fallback - to continue operating the Chain. See [Recovery](#recovery) for details on how to proceed. - -3. Download and install the injective-chain `10006-rc1 release` - ```bash - wget https://github.com/InjectiveLabs/injective-chain-releases/releases/download/v1.6.0-1656650662/linux-amd64.zip - unzip linux-amd64.zip - sudo mv injectived peggo /usr/bin - sudo mv libwasmvm.x86_64.so /usr/lib - ``` - -4. Verify you are currently running the correct version (`ef7f6f7a`) of `injectived` after downloading the 10006-rc1 release: - ```bash - $ injectived version - Version dev (ef7f6f7a) - Compiled at 20220701-0444 using Go go1.18.3 (amd64) - ``` - -5. Coordinate to restart your injectived with other validators - ```bash - injectived start - ``` - The binary will perform the upgrade automatically and continue the next consensus round if everything goes well. - -6. As the above release didn't include the updates to peggo correctly, we created a new release for peggo changes. Download and install the new Injective Chain 10006-rc1 release for peggo binary - ```bash - wget https://github.com/InjectiveLabs/injective-chain-releases/releases/download/v1.6.0-1657048292/linux-amd64.zip - unzip linux-amd64.zip - sudo mv peggo /usr/bin - ``` -7. Verify you are currently running the correct version (`ade8906`) of `peggo` after downloading the 10006-rc1 release: - ```bash - $ peggo version - Version dev (ade8906) - Compiled at 20220701-0444 using Go go1.18.3 (amd64) -``` -8. Start peggo - ``` - peggo start - ``` - -## Notes for DEX relayer providers -Relayer upgrade will be available after the chain is successfully upgraded as it relies on several other components that work with injectived. \ No newline at end of file diff --git a/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/canonical-10007-rc1.md b/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/canonical-10007-rc1.md deleted file mode 100644 index 0f749866..00000000 --- a/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/canonical-10007-rc1.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -sidebar_position: 10 ---- - -# Upgrade to 10007 -Thursday September 1th 2022 - -Following [proposal 170)](https://hub.injective.network/proposals/170/) -This indicates that the upgrade procedure should be performed on block number **14731000** - - - [Summary](#summary) - - [Risks](#risks) - - [Recovery](#recovery) - - [Upgrade Procedure](#upgrade-procedure) - - [Notes for Validator Operators](##notes-for-validator-operators) - - [Notes for Service Providers](##notes-for-DEX-relayer-providers) - -## Summary - -The Injective Canonical Chain will undergo a scheduled enhancement upgrade on **September 1st 14:00 UTC**. - -The following is a short summary of the upgrade steps: - -1. Vote and wait till the node panics at block height **14730999**. -2. Backing up configs, data, and keys used for running the Injective Canonical Chain. -3. Install the [Mainnet-v1.7.0-1665417543](https://github.com/InjectiveLabs/injective-chain-releases/releases/tag/v1.7.0-1665417543) -4. Start your node with the new injectived binary to fulfill the upgrade. - -Upgrade coordination and support for validators will be available on the `#mainnet-validators` private channel of the [Injective Discord](https://discord.gg/injective). - -The network upgrade can take the following potential pathways: -1. **Happy path** -Validators successfully upgrade chain without purging the blockchain history and all validators are up within 1-2 hours of the scheduled upgrade. - -2. **Not-so-happy path** -Validators have trouble upgrading to latest Canonical chain. This could be some consensus breaking changes not covered in upgrade handler, or compatibility issue of the migrated state with new injectived binary, but validators can at least export the genesis. - -3. **Abort path** -In the rare event that the team becomes aware of unnoticed critical issues, the Injective team will attempt to patch all the breaking states and provide another official binary within 36 hours. -If the chain is not successfully resumed within 36 hours, the upgrade will be announced as aborted on the #mainnet-validators channel of [Discord](https://discord.gg/injective), and validators will need to resume running the chain without any updates or changes. A new governance proposal for the upgrade will need to be issued and voted on by the community for the next upgrade. - -## Risks - -As a validator performing the upgrade procedure on your consensus nodes carries a heightened risk of -double-signing and being slashed. The most important piece of this procedure is verifying your -software version and genesis file hash before starting your validator and signing. - -The riskiest thing a validator can do is discover that they made a mistake and repeat the upgrade -procedure again during the network startup. If you discover a mistake in the process, the best thing -to do is wait for the network to start before correcting it. If the network is halted and you have -started with a different genesis file than the expected one, seek advice from an Injective developer -before resetting your validator. - -## Recovery - -Prior to exporting chain state, validators are encouraged to take a full data snapshot at the -export height before proceeding. Snapshotting depends heavily on infrastructure, but generally this -can be done by backing up the `.injectived` directory. - -It is critically important to backup the `.injectived/data/priv_validator_state.json` file after stopping your injectived process. This file is updated every block as your validator participates in a consensus rounds. It is a critical file needed to prevent double-signing, in case the upgrade fails and the previous chain needs to be restarted. - -In the event that the upgrade does not succeed, validators and operators must restore the snapshot and downgrade back to [Injective Chain 10006-rc1 release](https://github.com/InjectiveLabs/injective-chain-releases/releases/download/v1.6.0-1656650662/linux-amd64.zip) and continue the chain until next upgrade announcement. - -### Upgrade Procedure - -## Notes for Validators -Validator operators should configure the **timeout_commit** in **config.toml** to `1s`. - -1. Verify you are currently running the correct version (`ef7f6f7a`) of `injectived`: - ```bash - injectived version - Version dev (ef7f6f7a) - Compiled at 20220705-1911 using Go go1.18.3 (amd64) - ``` - -2. After the chain has halted, make a backup of your `.injectived` directory - ```bash - cp ~/.injectived ./injectived-backup - ``` - **NOTE**: It is recommended for validators and operators to take a full data snapshot at the export - height before proceeding in case the upgrade does not go as planned or if not enough voting power - comes online in a sufficient and agreed upon amount of time. In such a case, the chain will fallback - to continue operating the Chain. See [Recovery](#recovery) for details on how to proceed. - -3. Download and install the injective-chain `10007 release` - ```bash - wget https://github.com/InjectiveLabs/injective-chain-releases/releases/download/v1.7.0-1665417543/linux-amd64.zip - unzip linux-amd64.zip - sudo mv injectived peggo /usr/bin - sudo mv libwasmvm.x86_64.so /usr/lib - ``` - -4. Verify you are currently running the correct version (`178f6dbb`) of `injectived` after downloading the 10007 release: - ```bash - injectived version - Version dev (178f6dbb) - Compiled at 20220903-1641 using Go go1.18.5 (amd64) - ``` - -5. Coordinate to restart your injectived with other validators - ```bash - injectived start - ``` - The binary will perform the upgrade automatically and continue the next consensus round if everything goes well. - -6. Verify you are currently running the correct version (`ade8906`) of `peggo` after downloading the 10007 release: - ```bash - peggo version - Version dev (ade8906) - Compiled at 20220830-1738 using Go go1.18.5 (amd64) - ``` -8. Start peggo - ```bash - peggo start - ``` - -## Notes for DEX relayer providers -Relayer upgrade will be available after the chain is successfully upgraded as it relies on several other components that work with injectived. \ No newline at end of file diff --git a/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/canonical-10008.md b/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/canonical-10008.md deleted file mode 100644 index a77e7bb0..00000000 --- a/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/canonical-10008.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -sidebar_position: 11 ---- - -# Upgrade to 10008 - Camelot -Thursday November 21st 2022 - -Following [proposal 182](https://hub.injective.network/proposals/182/) -This indicates that the upgrade procedure should be performed on block number **19761600** - - - [Summary](#summary) - - [Risks](#risks) - - [Recovery](#recovery) - - [Upgrade Procedure](#upgrade-procedure) - - [Notes for Validator Operators](##notes-for-validator-operators) - - [Notes for Service Providers](##notes-for-DEX-relayer-providers) - -## Summary - -The Injective Canonical Chain will undergo a scheduled enhancement upgrade on **November 21st 14:00 UTC**. - -The following is a short summary of the upgrade steps: - -1. Vote and wait till the node panics at block height **19761599**. -2. Backing up configs, data, and keys used for running the Injective Canonical Chain. -3. Install the [Mainnet-10008-1668679102](https://github.com/InjectiveLabs/injective-chain-releases/releases/tag/v1.8.0-1668679102) -4. Start your node with the new injectived binary to fulfill the upgrade. - -Upgrade coordination and support for validators will be available on the `#mainnet-validators` private channel of the [Injective Discord](https://discord.gg/injective). - -The network upgrade can take the following potential pathways: -1. **Happy path** -Validators successfully upgrade chain without purging the blockchain history and all validators are up within 1-2 hours of the scheduled upgrade. - -2. **Not-so-happy path** -Validators have trouble upgrading to latest Canonical chain. This could be some consensus breaking changes not covered in upgrade handler, or compatibility issue of the migrated state with new injectived binary, but validators can at least export the genesis. - -3. **Abort path** -In the rare event that the team becomes aware of unnoticed critical issues, the Injective team will attempt to patch all the breaking states and provide another official binary within 36 hours. -If the chain is not successfully resumed within 36 hours, the upgrade will be announced as aborted on the #mainnet-validators channel of [Discord](https://discord.gg/injective), and validators will need to resume running the chain without any updates or changes. A new governance proposal for the upgrade will need to be issued and voted on by the community for the next upgrade. - -## Risks - -As a validator performing the upgrade procedure on your consensus nodes carries a heightened risk of -double-signing and being slashed. The most important piece of this procedure is verifying your -software version and genesis file hash before starting your validator and signing. - -The riskiest thing a validator can do is discover that they made a mistake and repeat the upgrade -procedure again during the network startup. If you discover a mistake in the process, the best thing -to do is wait for the network to start before correcting it. If the network is halted and you have -started with a different genesis file than the expected one, seek advice from an Injective developer -before resetting your validator. - -## Recovery - -Prior to exporting chain state, validators are encouraged to take a full data snapshot at the -export height before proceeding. Snapshotting depends heavily on infrastructure, but generally this -can be done by backing up the `.injectived` directory. - -It is critically important to backup the `.injectived/data/priv_validator_state.json` file after stopping your injectived process. This file is updated every block as your validator participates in a consensus rounds. It is a critical file needed to prevent double-signing, in case the upgrade fails and the previous chain needs to be restarted. - -In the event that the upgrade does not succeed, validators and operators must restore the snapshot and downgrade back to [Injective Chain 10007-rc1 release](https://github.com/InjectiveLabs/injective-chain-releases/releases/download/v1.7.0-1665417543/linux-amd64.zip) and continue the chain until next upgrade announcement. - -### Upgrade Procedure - -## Notes for Validators -Validator operators should configure the **timeout_commit** in **config.toml** to `300ms`. - -1. Verify you are currently running the correct version (`ca447cf8`) of `injectived`: - ```bash - injectived version - Version dev (ca447cf8) - Compiled at 20221024-1031 using Go go1.18.5 (amd64) - ``` - -2. After the chain has halted, make a backup of your `.injectived` directory - ```bash - cp ~/.injectived ./injectived-backup - ``` - **NOTE**: It is recommended for validators and operators to take a full data snapshot at the export - height before proceeding in case the upgrade does not go as planned or if not enough voting power - comes online in a sufficient and agreed upon amount of time. In such a case, the chain will fallback - to continue operating the Chain. See [Recovery](#recovery) for details on how to proceed. - -3. Download and install the injective-chain `10008 release` - ```bash - wget https://github.com/InjectiveLabs/injective-chain-releases/releases/download/v1.8.0-1668679102/linux-amd64.zip - unzip linux-amd64.zip - sudo mv injectived peggo /usr/bin - sudo mv libwasmvm.x86_64.so /usr/lib - ``` - -4. Verify you are currently running the correct version (`64c9081`) of `injectived` after downloading the 10008 release: - ```bash - injectived version - Version dev (64c9081) - Compiled at 20221117-0959 using Go go1.18.3 (amd64) - ``` - -5. Coordinate to restart your injectived with other validators - ```bash - injectived start - ``` - The binary will perform the upgrade automatically and continue the next consensus round if everything goes well. - -6. Verify you are currently running the correct version (`ade8906`) of `peggo` after downloading the 10008 release: - ```bash - peggo version - Version dev (ade8906) - Compiled at 20220830-1738 using Go go1.18.5 (amd64) - ``` -8. Start peggo - ```bash - peggo start - ``` - -## Notes for DEX relayer providers -Relayer upgrade will be available after the chain is successfully upgraded as it relies on several other components that work with injectived. \ No newline at end of file diff --git a/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/canonical-10009.md b/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/canonical-10009.md deleted file mode 100644 index ee100767..00000000 --- a/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/canonical-10009.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -sidebar_position: 12 ---- - -# Upgrade to 10009 -Tuesday January 18th 2022 - -Following [proposal 198](https://hub.injective.network/proposals/198/) -This indicates that the upgrade procedure should be performed on block number **24204000** - - - [Summary](#summary) - - [Risks](#risks) - - [Recovery](#recovery) - - [Upgrade Procedure](#upgrade-procedure) - - [Notes for Validator Operators](##notes-for-validator-operators) - - [Notes for Service Providers](##notes-for-DEX-relayer-providers) - -## Summary - -The Injective Canonical Chain will undergo a scheduled enhancement upgrade on **January 18th 14:00 UTC**. - -The following is a short summary of the upgrade steps: - -1. Vote and wait till the node panics at block height **24204000**. -2. Backing up configs, data, and keys used for running the Injective Canonical Chain. -3. Install the [Mainnet-10009-1673640888](https://github.com/InjectiveLabs/injective-chain-releases/releases/tag/v1.9.0-1673640888) -4. Start your node with the new injectived binary to fulfill the upgrade. - -Upgrade coordination and support for validators will be available on the `#mainnet-validators` private channel of the [Injective Discord](https://discord.gg/injective). - -The network upgrade can take the following potential pathways: -1. **Happy path** -Validators successfully upgrade chain without purging the blockchain history and all validators are up within 1-2 hours of the scheduled upgrade. - -2. **Not-so-happy path** -Validators have trouble upgrading to latest Canonical chain. This could be some consensus breaking changes not covered in upgrade handler, or compatibility issue of the migrated state with new injectived binary, but validators can at least export the genesis. - -3. **Abort path** -In the rare event that the team becomes aware of unnoticed critical issues, the Injective team will attempt to patch all the breaking states and provide another official binary within 36 hours. -If the chain is not successfully resumed within 36 hours, the upgrade will be announced as aborted on the #mainnet-validators channel of [Discord](https://discord.gg/injective), and validators will need to resume running the chain without any updates or changes. A new governance proposal for the upgrade will need to be issued and voted on by the community for the next upgrade. - -## Risks - -As a validator performing the upgrade procedure on your consensus nodes carries a heightened risk of -double-signing and being slashed. The most important piece of this procedure is verifying your -software version and genesis file hash before starting your validator and signing. - -The riskiest thing a validator can do is discover that they made a mistake and repeat the upgrade -procedure again during the network startup. If you discover a mistake in the process, the best thing -to do is wait for the network to start before correcting it. If the network is halted and you have -started with a different genesis file than the expected one, seek advice from an Injective developer -before resetting your validator. - -## Recovery - -Prior to exporting chain state, validators are encouraged to take a full data snapshot at the -export height before proceeding. Snapshotting depends heavily on infrastructure, but generally this -can be done by backing up the `.injectived` directory. - -It is critically important to backup the `.injectived/data/priv_validator_state.json` file after stopping your injectived process. This file is updated every block as your validator participates in a consensus rounds. It is a critical file needed to prevent double-signing, in case the upgrade fails and the previous chain needs to be restarted. - -In the event that the upgrade does not succeed, validators and operators must restore the snapshot and downgrade back to [Injective Chain 10008 release](https://github.com/InjectiveLabs/injective-chain-releases/releases/tag/v1.8.0-1668679102) and continue the chain until next upgrade announcement. - -### Upgrade Procedure - -## Notes for Validators -Validator operators should configure the **timeout_commit** in **config.toml** to `300ms`. - -1. Verify you are currently running the correct version (`64c9081`) of `injectived`: - ```bash - injectived version - Version dev (64c9081) - Compiled at 20221024-1031 using Go go1.18.5 (amd64) - ``` - -2. After the chain has halted, make a backup of your `.injectived` directory - ```bash - cp ~/.injectived ./injectived-backup - ``` - **NOTE**: It is recommended for validators and operators to take a full data snapshot at the export - height before proceeding in case the upgrade does not go as planned or if not enough voting power - comes online in a sufficient and agreed upon amount of time. In such a case, the chain will fallback - to continue operating the Chain. See [Recovery](#recovery) for details on how to proceed. - -3. Download and install the injective-chain `10009 release` - ```bash - wget https://github.com/InjectiveLabs/injective-chain-releases/releases/download/v1.9.0-1673640888/linux-amd64.zip - unzip linux-amd64.zip - sudo mv injectived peggo /usr/bin - sudo mv libwasmvm.x86_64.so /usr/lib - ``` - -4. Verify you are currently running the correct version (`3c87354f5`) of `injectived` after downloading the 10009 release: - ```bash - injectived version - Version dev (3c87354f5) - Compiled at 20230113-2015 using Go go1.18.3 (amd64) - ``` - -5. Coordinate to restart your injectived with other validators - ```bash - injectived start - ``` - The binary will perform the upgrade automatically and continue the next consensus round if everything goes well. - -6. Verify you are currently running the correct version (`ade8906`) of `peggo` after downloading the 10009 release: - ```bash - peggo version - Version dev (ade8906) - Compiled at 20220830-1738 using Go go1.18.5 (amd64) - ``` -8. Start peggo - ```bash - peggo start - ``` - -## Notes for DEX relayer providers -Relayer upgrade will be available after the chain is successfully upgraded as it relies on several other components that work with injectived. \ No newline at end of file diff --git a/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/canonical-10010.md b/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/canonical-10010.md deleted file mode 100644 index 3bd2efb1..00000000 --- a/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/canonical-10010.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -sidebar_position: 13 ---- - -# Upgrade to v1.10 -Friday March 17th 2023 - -Following [proposal 207](https://hub.injective.network/proposals/207/) -This indicates that the upgrade procedure should be performed on block number **28864000** - - - [Summary](#summary) - - [Risks](#risks) - - [Recovery](#recovery) - - [Upgrade Procedure](#upgrade-procedure) - - [Notes for Validator Operators](##notes-for-validator-operators) - - [Notes for Service Providers](##notes-for-DEX-relayer-providers) - -## Summary - -The Injective Canonical Chain will undergo a scheduled enhancement upgrade on **March 17th 14:00 UTC**. - -The following is a short summary of the upgrade steps: - -1. Vote and wait till the node panics at block height **28864000**. -2. Backing up configs, data, and keys used for running the Injective Canonical Chain. -3. Install the [Mainnet-v1.10-1678709842](https://github.com/InjectiveLabs/injective-chain-releases/releases/tag/v1.10-1678709842) -4. Start your node with the new injectived binary to fulfill the upgrade. - -Upgrade coordination and support for validators will be available on the `#mainnet-validators` private channel of the [Injective Discord](https://discord.gg/injective). - -The network upgrade can take the following potential pathways: -1. **Happy path** -Validators successfully upgrade chain without purging the blockchain history and all validators are up within 1-2 hours of the scheduled upgrade. - -2. **Not-so-happy path** -Validators have trouble upgrading to latest Canonical chain. This could be some consensus breaking changes not covered in upgrade handler, or compatibility issue of the migrated state with new injectived binary, but validators can at least export the genesis. - -3. **Abort path** -In the rare event that the team becomes aware of unnoticed critical issues, the Injective team will attempt to patch all the breaking states and provide another official binary within 36 hours. -If the chain is not successfully resumed within 36 hours, the upgrade will be announced as aborted on the #mainnet-validators channel of [Discord](https://discord.gg/injective), and validators will need to resume running the chain without any updates or changes. A new governance proposal for the upgrade will need to be issued and voted on by the community for the next upgrade. - -## Risks - -As a validator performing the upgrade procedure on your consensus nodes carries a heightened risk of -double-signing and being slashed. The most important piece of this procedure is verifying your -software version and genesis file hash before starting your validator and signing. - -The riskiest thing a validator can do is discover that they made a mistake and repeat the upgrade -procedure again during the network startup. If you discover a mistake in the process, the best thing -to do is wait for the network to start before correcting it. If the network is halted and you have -started with a different genesis file than the expected one, seek advice from an Injective developer -before resetting your validator. - -## Recovery - -Prior to exporting chain state, validators are encouraged to take a full data snapshot at the -export height before proceeding. Snapshotting depends heavily on infrastructure, but generally this -can be done by backing up the `.injectived` directory. - -It is critically important to backup the `.injectived/data/priv_validator_state.json` file after stopping your injectived process. This file is updated every block as your validator participates in a consensus rounds. It is a critical file needed to prevent double-signing, in case the upgrade fails and the previous chain needs to be restarted. - -In the event that the upgrade does not succeed, validators and operators must restore the snapshot and downgrade back to [Injective Chain 10009 release](https://github.com/InjectiveLabs/injective-chain-releases/releases/tag/v1.9.0-1673970775) and continue the chain until next upgrade announcement. - -### Upgrade Procedure - -## Notes for Validators -Validator operators should configure the **timeout_commit** in **config.toml** to `300ms`. - -1. Verify you are currently running the correct version (`3c87354f5`) of `injectived`: - ```bash - injectived version - Version v1.9.0 (3c87354f5) - Compiled at 20230118-1421 using Go go1.18.3 (amd64) - ``` - -2. After the chain has halted, make a backup of your `.injectived` directory - ```bash - cp ~/.injectived ./injectived-backup - ``` - **NOTE**: It is recommended for validators and operators to take a full data snapshot at the export - height before proceeding in case the upgrade does not go as planned or if not enough voting power - comes online in a sufficient and agreed upon amount of time. In such a case, the chain will fallback - to continue operating the Chain. See [Recovery](#recovery) for details on how to proceed. - -3. Download and install the injective-chain `10010 release` - ```bash - wget https://github.com/InjectiveLabs/injective-chain-releases/releases/tag/v1.10-1678709842 - unzip linux-amd64.zip - sudo mv injectived peggo /usr/bin - sudo mv libwasmvm.x86_64.so /usr/lib - ``` - -4. Verify you are currently running the correct version (`e218afcf7`) of `injectived` after downloading the 10009 release: - ```bash - injectived version - Version dev (e218afcf7) │ - Compiled at 20230313-1224 using Go go1.18.3 (amd64) - ``` - -5. Coordinate to restart your injectived with other validators - ```bash - injectived start - ``` - The binary will perform the upgrade automatically and continue the next consensus round if everything goes well. - -6. Verify you are currently running the correct version (`bede2b6`) of `peggo` after downloading the 10009 release: - ```bash - peggo version - Version dev (bede2b6) │ - Compiled at 20230313-1224 using Go go1.18.3 (amd64) - ``` -8. Start peggo - ```bash - peggo start - ``` - -## Notes for DEX relayer providers -Relayer upgrade will be available after the chain is successfully upgraded as it relies on several other components that work with injectived. \ No newline at end of file diff --git a/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/canonical-10011.md b/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/canonical-10011.md deleted file mode 100644 index d03bf03a..00000000 --- a/.gitbook/nodes/validators/mainnet/canonical-chain-upgrades/canonical-10011.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -sidebar_position: 13 ---- - -# Upgrade to 10011 -Thursday Jun 1th 2023 - -Following [proposal 231](https://hub.injective.network/proposals/231/) -This indicates that the upgrade procedure should be performed on block number **34775000** - - - [Summary](#summary) - - [Risks](#risks) - - [Recovery](#recovery) - - [Upgrade Procedure](#upgrade-procedure) - - [Notes for Validator Operators](##notes-for-validator-operators) - - [Notes for Service Providers](##notes-for-DEX-relayer-providers) - -## Summary - -The Injective Canonical Chain will undergo a scheduled enhancement upgrade on **Jun 1th 14:00 UTC**. - -The following is a short summary of the upgrade steps: - -1. Vote and wait till the node panics at block height **34775000**. -2. Backing up configs, data, and keys used for running the Injective Canonical Chain. -3. Install the [v1.11-1685225746](https://github.com/InjectiveLabs/injective-chain-releases/releases/tag/v1.11-1685225746) -4. Start your node with the new injectived binary to fulfill the upgrade. - -Upgrade coordination and support for validators will be available on the `#mainnet-validators` private channel of the [Injective Discord](https://discord.gg/injective). - -The network upgrade can take the following potential pathways: -1. **Happy path** -Validators successfully upgrade chain without purging the blockchain history and all validators are up within 1-2 hours of the scheduled upgrade. - -2. **Not-so-happy path** -Validators have trouble upgrading to latest Canonical chain. This could be some consensus breaking changes not covered in upgrade handler, or compatibility issue of the migrated state with new injectived binary, but validators can at least export the genesis. - -3. **Abort path** -In the rare event that the team becomes aware of unnoticed critical issues, the Injective team will attempt to patch all the breaking states and provide another official binary within 36 hours. -If the chain is not successfully resumed within 36 hours, the upgrade will be announced as aborted on the #mainnet-validators channel of [Discord](https://discord.gg/injective), and validators will need to resume running the chain without any updates or changes. A new governance proposal for the upgrade will need to be issued and voted on by the community for the next upgrade. - -## Risks - -As a validator performing the upgrade procedure on your consensus nodes carries a heightened risk of -double-signing and being slashed. The most important piece of this procedure is verifying your -software version and genesis file hash before starting your validator and signing. - -The riskiest thing a validator can do is discover that they made a mistake and repeat the upgrade -procedure again during the network startup. If you discover a mistake in the process, the best thing -to do is wait for the network to start before correcting it. If the network is halted and you have -started with a different genesis file than the expected one, seek advice from an Injective developer -before resetting your validator. - -## Recovery - -Prior to exporting chain state, validators are encouraged to take a full data snapshot at the -export height before proceeding. Snapshotting depends heavily on infrastructure, but generally this -can be done by backing up the `.injectived` directory. - -It is critically important to backup the `.injectived/data/priv_validator_state.json` file after stopping your injectived process. This file is updated every block as your validator participates in a consensus rounds. It is a critical file needed to prevent double-signing, in case the upgrade fails and the previous chain needs to be restarted. - -In the event that the upgrade does not succeed, validators and operators must restore the snapshot and downgrade back to [Injective Chain 10010 release](https://github.com/InjectiveLabs/injective-chain-releases/releases/tag/v1.10.1-1685036881) and continue the chain until next upgrade announcement. - -### Upgrade Procedure - -## Notes for Validators -Validator operators should configure the **timeout_commit** in **config.toml** to `300ms`. -You must remove the wasm cache before upgrading to the new version (rm -rf .injectived/wasm/wasm/cache/). - -1. Verify you are currently running the correct version (`b578d018c8`) of `injectived`: - ```bash - injectived version - Version dev (b578d018c8) - Compiled at 20230118-1421 using Go go1.18.3 (amd64) - ``` - -2. After the chain has halted, make a backup of your `.injectived` directory - ```bash - cp ~/.injectived ./injectived-backup - ``` - **NOTE**: It is recommended for validators and operators to take a full data snapshot at the export - height before proceeding in case the upgrade does not go as planned or if not enough voting power - comes online in a sufficient and agreed upon amount of time. In such a case, the chain will fallback - to continue operating the Chain. See [Recovery](#recovery) for details on how to proceed. - -3. Download and install the injective-chain `10011 release` - ```bash - wget https://github.com/InjectiveLabs/injective-chain-releases/releases/download/v1.11-1685225746/linux-amd64.zip - unzip linux-amd64.zip - sudo mv injectived peggo /usr/bin - sudo mv libwasmvm.x86_64.so /usr/lib - ``` - -4. Verify you are currently running the correct version (`f77eb5cfd7`) of `injectived` after downloading the 10009 release: - ```bash - injectived version - Version v1.11 (f77eb5cfd7) - Compiled at 20230527-2215 using Go go1.19.3 (amd64) - ``` - -5. Coordinate to restart your injectived with other validators - ```bash - injectived start - ``` - The binary will perform the upgrade automatically and continue the next consensus round if everything goes well. - -6. Verify you are currently running the correct version (`5868c94`) of `peggo` after downloading the 10009 release: - ```bash - peggo version - Version dev (5868c94) - Compiled at 20230527-2216 using Go go1.19.3 (amd64) - ``` -8. Start peggo - ```bash - peggo start - ``` - -## Notes for DEX relayer providers -Relayer upgrade will be available after the chain is successfully upgraded as it relies on several other components that work with injectived. \ No newline at end of file diff --git a/.gitbook/nodes/validators/mainnet/peggo.md b/.gitbook/nodes/validators/mainnet/peggo.md deleted file mode 100644 index 6f7aec14..00000000 --- a/.gitbook/nodes/validators/mainnet/peggo.md +++ /dev/null @@ -1,290 +0,0 @@ -# Peggo - -If you're on this page then you've probably become a Validator on Injective. Congratulations! Configuring `peggo` is the final step of your setup. - -Example of `.env` for peggo: - -```bash -PEGGO_ENV="local" # environment name for metrics (dev/test/staging/prod/local) -PEGGO_LOG_LEVEL="debug" # log level depth - -PEGGO_COSMOS_CHAIN_ID="injective-1" # chain ID of the Injective network -PEGGO_COSMOS_GRPC="tcp://localhost:9090" # gRPC of your injectived process -PEGGO_TENDERMINT_RPC="http://localhost:26657" # Tendermint RPC of your injectived process - -# Note: omitting PEGGO_COSMOS_GRPC and PEGGO_TENDERMINT_RPC enables stand-alone peggo mode. In this mode, -# peggo is connected to load balanced endpoints provided by the Injective network. This decouples peggo's connection from your injectived process. - -# Injective config -PEGGO_COSMOS_FEE_DENOM="inj" # token used to pay fees on Injective -PEGGO_COSMOS_GAS_PRICES="160000000inj" # default --gas-prices flag value for sending messages to Injective -PEGGO_COSMOS_KEYRING="file" # keyring backends ("os", "file", "kwallet", "memory", "pass", "test") -PEGGO_COSMOS_KEYRING_DIR= # path to your keyring dir -PEGGO_COSMOS_KEYRING_APP="peggo" # arbitrary name for your keyring app -PEGGO_COSMOS_FROM= # account address of your Validator (or your Delegated Orchestrator) -PEGGO_COSMOS_FROM_PASSPHRASE= # keyring passphrase -PEGGO_COSMOS_PK= # private key of your Validator (or your Delegated Orchestrator) -PEGGO_COSMOS_USE_LEDGER=false - -# Ethereum config -PEGGO_ETH_KEYSTORE_DIR= # path to your Ethereum keystore -PEGGO_ETH_FROM= # your Ethereum address (must be Delegated Ethereum address if you're a Validator) -PEGGO_ETH_PASSPHRASE= # passphrase of your Ethereum keystore -PEGGO_ETH_PK= # private key of your Ethereum address -PEGGO_ETH_GAS_PRICE_ADJUSTMENT=1.3 # suggested Ethereum gas price will be adjusted by this factor (Relayer) -PEGGO_ETH_MAX_GAS_PRICE="500gwei" # max gas price allowed for sending Eth transactions (Relayer) -PEGGO_ETH_CHAIN_ID=1 # chain ID of Ethereum network -PEGGO_ETH_RPC="http://localhost:8545" # RPC of your Ethereum node -PEGGO_ETH_ALCHEMY_WS="" # optional websocket endpoint for listening pending transactions on Peggy.sol -PEGGO_ETH_USE_LEDGER=false - -# Price feed provider for token assets (Batch Creator) -PEGGO_COINGECKO_API="https://api.coingecko.com/api/v3" - -# Relayer config -PEGGO_RELAY_VALSETS=true # set to `true` to relay Validator Sets -PEGGO_RELAY_VALSET_OFFSET_DUR="5m" # duration which needs to expire before a Valset is eligible for relaying -PEGGO_RELAY_BATCHES=true # set to `true` to relay Token Batches -PEGGO_RELAY_BATCH_OFFSET_DUR="5m" # duration which needs to expire before a Token Batch is eligible for relaying -PEGGO_RELAY_PENDING_TX_WAIT_DURATION="20m" # time to wait until a pending tx is processed - -# Batch Creator config -PEGGO_MIN_BATCH_FEE_USD=23.2 # minimum amount of fee a Token Batch must satisfy to be created - -# Metrics config -PEGGO_STATSD_PREFIX="peggo." -PEGGO_STATSD_ADDR="localhost:8125" -PEGGO_STATSD_STUCK_DUR="5m" -PEGGO_STATSD_MOCKING=false -PEGGO_STATSD_DISABLED=true -``` - -IMPORTANT NOTE: if you're running your own `injectived` (Injective node) and `geth` (Ethereum node) processes, ensure that they are in sync with the latest state. Outdated nodes can skew the business logic of `peggo` to display "false alarm" logs sometimes. - -## Step 1: Configuring .env - -```bash -# official Injective mainnet .env config -mkdir ~/.peggo -cp mainnet-config/10001/peggo-config.env ~/.peggo/.env -cd ~/.peggo -``` - -Ethereum config - -First, update the `PEGGO_ETH_RPC` in the `.env` file with a valid Ethereum EVM RPC Endpoint. - -To set up your own Ethereum full node, follow the instructions [here](https://ethereum.org/en/developers/docs/nodes-and-clients/run-a-node/). It's possible to use an external Ethereum RPC provider such as Alchemy or Infura, but keep in mind that the Peggo bridge relayer makes a heavy use of `eth_getLogs` calls which may increase your cost burden, depending on your provider. - -## **Managing Ethereum keys for `peggo`** - -Peggo supports two options to provide signing key credentials - using the Geth keystore (recommended) or by providing a plaintext Ethereum private key. - -#### **Option 1. Geth Keystore** - -You can find instructions for securely creating a new Ethereum account using a keystore in the Geth Documentation [here](https://geth.ethereum.org/docs/interface/managing-your-accounts). - -For convience, an example is provided below. - -```bash -geth account new --datadir=/home/ec2-user/.peggo/data/ - -INFO [03-23|18:18:36.407] Maximum peer count ETH=50 LES=0 total=50 -Your new account is locked with a password. Please give a password. Do not forget this password. -Password: -Repeat password: - -Your new key was generated - -Public address of the key: 0x9782dc957DaE6aDc394294954B27e2118D05176C -Path of the secret key file: /home/ec2-user/.peggo/data/keystore/UTC--2021-03-23T15-18-44.284118000Z--9782dc957dae6adc394294954b27e2118d05176c - -- You can share your public address with anyone. Others need it to interact with you. -- You must NEVER share the secret key with anyone! The key controls access to your funds! -- You must BACKUP your key file! Without the key, it's impossible to access account funds! -- You must REMEMBER your password! Without the password, it's impossible to decrypt the key! -``` - -Make sure you heed the warnings that geth provides, particularly in backing up your key file so that you don't lose your keys by mistake. We also recommend not using any quote or backtick characters in your passphrase for peggo compatibility purposes. - -You should now set the following env variables: - -```bash -# example values, replace with your own -PEGGO_ETH_KEYSTORE_DIR=/home/ec2-user/.peggo/data/keystore -PEGGO_ETH_FROM=0x9782dc957DaE6aDc394294954B27e2118D05176C -PEGGO_ETH_PASSPHRASE=12345678 -``` - -Then ensure that your Ethereum address has enough ETH. - -#### **Option 2. Ethereum Private Key (Unsafe)** - -Simply update the `PEGGO_ETH_PK` with a new Ethereum Private Key from a new account. - -Then ensure that your Ethereum address has enough ETH. - -## Injective config - -### **Creating your delegated Cosmos Key for sending Injective transactions** - -Your peggo orchestrator can either: - -* Use an explicitly delegated account key specific for sending validator specific Peggy transactions (i.e. `ValsetConfirm`, `BatchConfirm`, and `SendToCosmos` transactions) or -* Simply use your validator's account key ("your Validator is your Orchestrator") - -For isolation purposes, we recommend creating a delegated Cosmos key to send Injective transactions instead of using your validator account key. - -To create a new key, run - -```bash -injectived keys add $ORCHESTRATOR_KEY_NAME -``` - -Then ensure that your orchestrator inj address has INJ balance in it, so peggo orchestrator can send messages to Injective. - -To obtain your orchestrators's inj address, run - -```bash -injectived keys list $ORCHESTRATOR_KEY_NAME -``` - -You can transfer INJ from your validator account to orchestrator address using this command - -```bash -injectived tx bank send $VALIDATOR_KEY_NAME $ORCHESTRATOR_INJ_ADDRESS --chain-id=injective-1 --keyring-backend=file --yes --node=tcp://localhost:26657 --gas-prices=500000000inj -``` - -Example - -```bash -injectived tx bank send genesis inj1u3eyz8nkvym0p42h79aqgf37gckf7szreacy9e 20000000000000000000inj --chain-id=injective-1 --keyring-backend=file --yes --node=tcp://localhost:26657 --gas-prices=500000000inj -``` - -You can then verify that your orchestrator account has INJ balances by running - -```bash -injectived q bank balances $ORCHESTRATOR_INJ_ADDRESS -``` - -### **Managing Cosmos account keys for `peggo`** - -Peggo supports two options to provide Cosmos signing key credentials - using the Cosmos keyring (recommended) or by providing a plaintext private key. - -#### **Option 1. Cosmos Keyring** - -In the `.env` file, first specify the `PEGGO_COSMOS_FROM` and `PEGGO_COSMOS_FROM_PASSPHRASE` corresponding to your peggo account signing key. - -If you are using a delegated account key configuration as recommended above, this will be your `$ORCHESTRATOR_KEY_NAME` and passphrase respectively. Otherwise, this should be your `$VALIDATOR_KEY_NAME` and associated validator passphrase. - -Please note that the default keyring backend is `file` and that as such peggo will try to locate keys on disk by default. - -To use the default injectived key configuration, you should set the keyring path to the home directory of your injectived node, e.g. `~/.injectived`. - -You can also read more about the Cosmos Keyring setup [here](https://docs.cosmos.network/main/run-node/keyring.html). - -#### **Option 2. Cosmos Private Key (Unsafe)** - -In the `.env` file, specify the `PEGGO_COSMOS_PK` corresponding to your peggo account signing key. - -If you are using a delegated account key configuration as recommended above, this will be your orchestrator account's private key. Otherwise, this should be your validator's account private key. - -To obtain your orchestrator's Cosmos private key (if applicable), run - -```bash -injectived keys unsafe-export-eth-key $ORCHESTRATOR_KEY_NAME -``` - -To obtain your validator's Cosmos private key (if applicable), run - -```bash -injectived keys unsafe-export-eth-key $VALIDATOR_KEY_NAME -``` - -Again, this method is less secure and is not recommended. - -### Step 2: Register Your Orchestrator and Ethereum Address - -You can register orchestrator and ethereum address only once. It **CANNOT** be updated later. So Check twice before running below command. - -```bash -injectived tx peggy set-orchestrator-address $VALIDATOR_INJ_ADDRESS $ORCHESTRATOR_INJ_ADDRESS $ETHEREUM_ADDRESS --from $VALIDATOR_KEY_NAME --chain-id=injective-1 --keyring-backend=file --yes --node=tcp://localhost:26657 --gas-prices=500000000inj - -``` - -* To obtain your validator's inj address, run, `injectived keys list $VALIDATOR_KEY_NAME` -* To obtain your orchestrators's inj address, `injectived keys list $ORCHESTRATOR_KEY_NAME` - -Example: - -```bash -injectived tx peggy set-orchestrator-address inj10m247khat0esnl0x66vu9mhlanfftnvww67j9n inj1x7kvxlz2epqx3hpq6v8j8w859t29pgca4z92l2 0xf79D16a79130a07e77eE36e8067AeA783aBdA3b6 --from validator-key-name --chain-id=injective-1 --keyring-backend=file --yes --node=tcp://localhost:26657 --gas-prices=500000000inj -``` - -You can verify successful registration by checking for your Validator's mapped Ethereum address on https://lcd.injective.network/peggy/v1/valset/current. - -NOTE: Once you've registered your Orchestrator with the `set-orchestrator-address` message, you **CANNOT** register again. Once this step is complete, your `Validator` is bound to the provided Ethereum address (as well the Delegated address you may have provided). In other words, your peggo must always run with the addresses you provided for registration. - -### Step 3: Start the Relayer - -```bash -cd ~/.peggo -peggo orchestrator -``` - -This starts the Peggo bridge (relayer / orchestrator). - -### Step 4: Create a Peggo systemd service - -Add `peggo.service` file with below content under `/etc/systemd/system/peggo.service` - -```ini -[Unit] - Description=peggo - -[Service] - WorkingDirectory=/home/ec2-user/.peggo - ExecStart=/bin/bash -c 'peggo orchestrator ' - Type=simple - Restart=always - RestartSec=1 - User=ec2-user - -[Install] - WantedBy=multi-user.target -``` - -Then use the following commands to configure Environment variables, start and stop the peggo relayer. - -```bash -sudo systemctl start peggo -sudo systemctl stop peggo -sudo systemctl restart peggo -sudo systemctl status peggo - -# enable start on system boot -sudo systemctl enable peggo - -# To check Logs -journalctl -f -u peggo -``` - -### Step 5: (Optional) Protect Cosmos Keyring from unauthorized access - -{% hint style="info" %} -This is an advanced DevOps topic, consult with your sysadmin. -{% endhint %} - -Learn more about Cosmos Keyring setup [here](https://docs.cosmos.network/master/run-node/keyring.html). Once you've launched your node, the default keyring will have the validator operator key stored on disk in the encrypted form. Usually the keyring is located within node's homedir, i.e. `~/.injectived/keyring-file`. - -Some sections of the Injective Staking documentation will guide you through using this key for governance purposes, i.e. submitting transactions and setting up an Ethereum bridge. In order to protect the keys from unauthorized access, even when the keyring passphrase is leaked via configs, you can set OS permissions to allow disk access to `injectived` / `peggo` processes only. - -In Linux systems like Debian, Ubuntu and RHEL, this can be achieved using POSIX Access Control Lists (ACLs). Before beginning to work with ACLs, the file system must be mounted with ACLs turned on. There are some official guides for each distro: - -* [Ubuntu](https://help.ubuntu.com/community/FilePermissionsACLs) -* [Debian](https://wiki.debian.org/Permissions) -* [Amazon Linux (RHEL)](https://www.redhat.com/sysadmin/linux-access-control-lists) - -### Contribute - -If you'd like to inspect the Peggo orchestrator source code and contribute, you can do so at [https://github.com/InjectiveLabs/peggo](https://github.com/InjectiveLabs/peggo). diff --git a/.gitbook/nodes/validators/testnet/README.md b/.gitbook/nodes/validators/testnet/README.md deleted file mode 100644 index 4d49e996..00000000 --- a/.gitbook/nodes/validators/testnet/README.md +++ /dev/null @@ -1,138 +0,0 @@ -# Testnet - -#### Hardware Requirements - -| _Minimum_ | _Recommendation_ | -| :--------------------------: | :---------------------------: | -| RAM Memory 32GB | RAM Memory 64GB | -| CPU 8 cores | CPU 8 cores | -| Storage 2TB | Storage 2TB | -| Network 5Gbps+ | Network 5Gbps+ | -| AWS Instance type t2.2xlarge | AWS Instance type r6i.2xlarge | - -### Step 1: Create a Validator Account - -First, run the keygen command with your desired validator key name. - -```bash -export VALIDATOR_KEY_NAME=[my-validator-key] -injectived keys add $VALIDATOR_KEY_NAME -``` - -This will derive a new private key and encrypt it to disk. Make sure to remember the password you used. - -```bash -# EXAMPLE OUTPUT -- name: myvalidatorkey - type: local - address: inj1queq795wx8gzqc8706uz80whp07mcgg5nmpj6h - pubkey: injpub1r0mckeepqwzmrzt5af00hgc7fhve05rr0q3q6wvx4xn6k46zguzykdszg6cnu0zca4q - mnemonic: "" - threshold: 0 - pubkeys: [] - - -**Important** write this mnemonic phrase in a safe place. -It is the only way to recover your account if you ever forget your password. -``` - -{% hint style="warning" %} -**The output will contain a mnemonic phrase that represents your key in plain text. Make sure to save this phrase as a backup of your key, since without a key you will not be able to control your validator. The phrase is better be backed up on physical paper, storing it in cloud storage may compromise your validator later.** - -Remember the address starting from `inj`, this is going to be your Injective Chain Validator Account address. -{% endhint %} - -### Step 2: Obtain INJ - -In order to proceed with the next step, you will have to obtain some INJ on Injective. - -You can request funds from the [Testnet Faucet](https://faucet.injective.network/). - -After a few minutes, you should be able to verify that your deposit was successful on the UI. Alternatively, you can query your account balance using the `injectived` CLI with the following command: - -```bash -injectived q bank balances -``` - -### Step 3: Create your validator account - -Obtain your node's tendermint validator Bech32 encoded PubKey consensus address. - -```bash -VALIDATOR_PUBKEY=$(injectived tendermint show-validator) -echo $VALIDATOR_PUBKEY - -# Example: {"@type": "/cosmos.crypto.ed25519.PubKey", "key": "GWEJv/KSFhUUcKBWuf9TTT3Ful+3xV/1lFhchyW1TZ8="} -``` - -Then create your new validator initialized with a self-delegation with your INJ tokens. Most critically, you will need to decide on the values of your validator's staking parameters. - -* `--moniker` - Your validator's name -* `--amount` - Your validator's initial amount of INJ to bond -* `--commission-max-change-rate` - Your validator's maximum commission change rate percentage (per day) -* `--commission-max-rate` - Your validator's maximum commission rate percentage -* `--commission-rate` - Your validator's initial commission rate percentage -* `--min-self-delegation` - Your validator's minimum required self delegation - -Once you decide on your desired values, set them as follows. - -```bash -MONIKER= -AMOUNT=100000000000000000000inj # to delegate 100 INJ, as INJ is represented with 18 decimals. -COMMISSION_MAX_CHANGE_RATE=0.1 # e.g. for a 10% maximum change rate percentage per day -COMMISSION_MAX_RATE=0.1 # e.g. for a 10% maximum commission rate percentage -COMMISSION_RATE=0.1 # e.g. for a 10% initial commission rate percentage -MIN_SELF_DELEGATION_AMOUNT=50000000000000000000 # e.g. for a minimum 50 INJ self delegation required on the validator -``` - -Then run the following command to create your validator. - -```bash -injectived tx staking create-validator \ ---moniker=$MONIKER \ ---amount=$AMOUNT \ ---gas-prices=500000000inj \ ---pubkey=$VALIDATOR_PUBKEY \ ---from=$VALIDATOR_KEY_NAME \ ---keyring-backend=file \ ---yes \ ---node=tcp://localhost:26657 \ ---chain-id=injective-888 ---commission-max-change-rate=$COMMISSION_MAX_CHANGE_RATE \ ---commission-max-rate=$COMMISSION_MAX_RATE \ ---commission-rate=$COMMISSION_RATE \ ---min-self-delegation=$MIN_SELF_DELEGATION_AMOUNT -``` - -Extra `create-validator` options to consider: - -``` ---identity= The optional identity signature (ex. UPort or Keybase) ---pubkey= The Bech32 encoded PubKey of the validator ---security-contact= The validator's (optional) security contact email ---website= The validator's (optional) website -``` - -You can check that your validator was successfully created by checking the [staking dashboard](https://staking.injective.network/validators) or by entering the following CLI command. - -```bash -injectived q staking validators -``` - -If you see your validator in the list of validators, then congratulations, you have officially joined as an Equinox Staking validator! 🎉 - -### Step 4: (Optional) Delegate Additional INJ to your Validator - -To gain a deeper empirical understanding of user experience that your future delegators will experience, you can complete the remaining steps in the [Staking Guide](https://medium.com/injective-labs/injective-hub-guide-9a14f09f6a7d). - -These steps will allow you to experience the delegation flow using MetaMask Transactions. 🦊 - -Alternatively, you can always use the Injective CLI to send a delegation transaction. - -```bash -injectived tx staking delegate [validator-addr] [amount] --from $VALIDATOR_KEY_NAME --chain-id=injective-888 --keyring-backend=file --yes --node=tcp://localhost:26657 -``` - -### Next Steps - -Next, proceed to setup your Ethereum Bridge Relayer. This is a necessary step in order to prevent your validator from being slashed. You should do this immediately after setting up your validator. diff --git a/.gitbook/nodes/validators/testnet/testnet-peggo.md b/.gitbook/nodes/validators/testnet/testnet-peggo.md deleted file mode 100644 index 412107d6..00000000 --- a/.gitbook/nodes/validators/testnet/testnet-peggo.md +++ /dev/null @@ -1,387 +0,0 @@ -# Testnet Peggo - -## Equinox Testnet - -## Step 1: Configure your Peggo relayer - -```bash -mkdir ~/.peggo -cp testnet-config/staking/40014/peggo-config.env ~/.peggo/.env -cd ~/.peggo -``` - -First, update the `PEGGO_ETH_RPC` in the `.env` file with a valid Sepolia EVM RPC Endpoint. - -To set up your own Sepolia full node, follow the instructions [here](https://ethereum.org/en/developers/docs/nodes-and-clients/run-a-node/). It's possible to use an Alchemy or Infura RPC, but keep in mind that the Peggo bridge is still under development, and the request amount it makes to the RPC is not optimized. Ensure it does not incur high costs on your account. - -Peggo also requires access to your validator's Cosmos and Ethereum credentials to sign transactions for the corresponding networks. - -## **Cosmos Keys** - -There are two ways to provide the credential access - a keyring with encrypted keys, or just private key in plaintext. - -### **1. Cosmos Keyring** - -Update the `PEGGO_COSMOS_FROM` to your validator key name (or account address) and `PEGGO_COSMOS_FROM_PASSPHRASE` to your Cosmos Keyring passphrase. Please note that the default keyring backend is `file` and it will try to locate keys on disk. - -Keyring path must be pointing to homedir of your injectived node, if you want reuse the keys from there. - -Learn more about Cosmos Keyring setup [here](https://docs.cosmos.network/master/run-node/keyring.html). - -### **2. Cosmos Private Key (Unsafe)** - -Simply update the `PEGGO_COSMOS_PK` with your Validator's Account private key. - -To obtain your validator's Cosmos private key, run `injectived keys unsafe-export-eth-key $VALIDATOR_KEY_NAME`. - -This method is insecure and is not recommended. - -## **Ethereum Keys** - -There are two ways to provide the credential access - a Geth keystore with encrypted keys, or just private key in plaintext. - -### **1. Geth Keystore** - -Simply create a new private key store and update the following env variables: - -* `PEGGO_ETH_KEYSTORE_DIR` -* `PEGGO_ETH_FROM` -* `PEGGO_ETH_PASSPHRASE` - -You can find instructions for securely creating a new Ethereum account using a keystore in the Geth Documentation [here](https://geth.ethereum.org/docs/interface/managing-your-accounts). - -Example is provided below. - -```bash -geth account new --datadir=/home/ec2-user/.peggo/data/ - -INFO [03-23|18:18:36.407] Maximum peer count ETH=50 LES=0 total=50 -Your new account is locked with a password. Please give a password. Do not forget this password. -Password: -Repeat password: - -Your new key was generated - -Public address of the key: 0x9782dc957DaE6aDc394294954B27e2118D05176C -Path of the secret key file: /home/ec2-user/.peggo/data/keystore/UTC--2021-03-23T15-18-44.284118000Z--9782dc957dae6adc394294954b27e2118d05176c - -- You can share your public address with anyone. Others need it to interact with you. -- You must NEVER share the secret key with anyone! The key controls access to your funds! -- You must BACKUP your key file! Without the key, it's impossible to access account funds! -- You must REMEMBER your password! Without the password, it's impossible to decrypt the key! -``` - -Now you can set env variables like this: - -```ini -PEGGO_ETH_KEYSTORE_DIR=/home/ec2-user/.peggo/data/keystore -PEGGO_ETH_FROM=0x9782dc957DaE6aDc394294954B27e2118D05176C -PEGGO_ETH_PASSPHRASE=12345678 -``` - -Next, ensure that your Ethereum addresss has Sepolia ETH. You can request Sepolia ETH from the public faucet [here](https://www.alchemy.com/faucets/ethereum-sepolia). - -### **2. Ethereum Private Key (Unsafe)** - -Simply update the `PEGGO_ETH_PK` with a new Ethereum Private Key from a new account. - -Next, ensure that your Ethereum addresss has Sepolia ETH. You can request Sepolia ETH from the public faucet [here](https://www.alchemy.com/faucets/ethereum-sepolia). - -## Step 2: Register Your Ethereum Address - -```bash -cd ~/.peggo -peggo tx register-eth-key -``` - -You can verify successful registration by checking for your Validator's mapped Ethereum address on https://staking-lcd-testnet.injective.network/peggy/v1/valset/current. - -## Step 3: Start the Relayer - -```bash -peggo orchestrator -``` - -This starts the Peggo bridge (relayer / orchestrator). - -## Step 4: Create a Peggo systemd service - -Add `peggo.service` file with below content under `/etc/systemd/system/peggo.service` - -```ini -[Unit] - Description=peggo - -[Service] - WorkingDirectory=/home/ec2-user/.peggo - ExecStart=/bin/bash -c 'peggo orchestrator ' - Type=simple - Restart=always - RestartSec=1 - User=ec2-user - -[Install] - WantedBy=multi-user.target -``` - -Then run the following commands to configure Environment variables, start and stop the peggo relayer. - -```bash -sudo systemctl start peggo -sudo systemctl stop peggo -sudo systemctl restart peggo -sudo systemctl status peggo - -# enable start on system boot -sudo systemctl enable peggo - -# To check Logs -journalctl -f -u peggo -``` - -## Step 5: (Optional) Protect Cosmos Keyring from unauthorized access - -{% hint style="warning" %} -This is an advanced DevOps topic, consult with your sysadmin. -{% endhint %} - -Learn more about Cosmos Keyring setup [here](https://docs.cosmos.network/master/run-node/keyring.html). Once you've launched your node, the default keyring will have the validator operator key stored on disk in the encrypted form. Usually the keyring is located within node's homedir, i.e. `~/.injectived/keyring-file`. - -Some sections of the Injective Staking documentation will guide you through using this key for governance purposes, i.e. submitting transactions and setting up an Ethereum bridge. In order to protect the keys from unauthorized access, even when the keyring passphrase is leaked via configs, you can set OS permissions to allow disk access to `injectived` / `peggo` processes only. - -In Linux systems like Debian, Ubuntu and RHEL, this can be achieved using POSIX Access Control Lists (ACLs). Before beginning to work with ACLs, the file system must be mounted with ACLs turned on. There are some official guides for each distro: - -* [Ubuntu](https://help.ubuntu.com/community/FilePermissionsACLs) -* [Debian](https://wiki.debian.org/Permissions) -* [Amazon Linux (RHEL)](https://www.redhat.com/sysadmin/linux-access-control-lists) - -## Testnet - -## Step 1: Configure your Peggo relayer - -```bash -mkdir ~/.peggo -cp testnet-config/40014/peggo-config.env ~/.peggo/.env -cd ~/.peggo -``` - -First, update the `PEGGO_ETH_RPC` in the `.env` file with a valid Ethereum EVM RPC Endpoint. - -To create your own Ethereum full node, you can follow our instructions [here](https://ethereum.org/en/developers/docs/nodes-and-clients/run-a-node/). It's possible to use an external Ethereum RPC provider such as Alchemy or Infura, but keep in mind that the Peggo bridge relayer uses heavy use of `eth_getLogs` calls which may increase your cost burden depending on your provider. - -Peggo also requires access to your validator's delegated Injective Chain account and Ethereum key credentials to sign transactions for the corresponding networks. - -### **Creating your delegated Cosmos Key for sending Injective transactions** - -Your peggo relayer can either - -* Use an explicitly delegated account key specific for sending validator specific Peggy transactions (i.e. `ValsetConfirm`, `BatchConfirm`, and `SendToCosmos` transactions) or -* Simply use your validator's account key. - -For isolation purposes, we recommend creating a delegated Cosmos key to send Injective transactions instead of using your validator account key. - -To create a new key, run - -```bash -injectived keys add $ORCHESTRATOR_KEY_NAME -``` - -Then ensure that your orchestrator inj address has INJ balance. - -To obtain your orchestrators's inj address, run - -```bash -injectived keys list $ORCHESTRATOR_KEY_NAME -``` - -You can transfer INJ from your validator account to orchestrator address using this command - -```bash -injectived tx bank send $VALIDATOR_KEY_NAME $ORCHESTRATOR_INJ_ADDRESS --chain-id=injective-888 --keyring-backend=file --yes --node=tcp://localhost:26657 --gas-prices=500000000inj -``` - -Example - -```bash -injectived tx bank send genesis inj1u3eyz8nkvym0p42h79aqgf37gckf7szreacy9e 20000000000000000000inj --chain-id=injective-888 --keyring-backend=file --yes --node=tcp://localhost:26657 --gas-prices=500000000inj -``` - -You can then verify that your orchestrator account has INJ balances by running - -```bash -injectived q bank balances $ORCHESTRATOR_INJ_ADDRESS -``` - -### **Managing Cosmos account keys for `peggo`** - -Peggo supports two options to provide Cosmos signing key credentials - using the Cosmos keyring (recommended) or by providing a plaintext private key. - -#### **Option 1. Cosmos Keyring** - -In the `.env` file, first specify the `PEGGO_COSMOS_FROM` and `PEGGO_COSMOS_FROM_PASSPHRASE` corresponding to your peggo account signing key. - -If you are using a delegated account key configuration as recommended above, this will be your `$ORCHESTRATOR_KEY_NAME` and passphrase respectively. Otherwise, this should be your `$VALIDATOR_KEY_NAME` and associated validator passphrase. - -Please note that the default keyring backend is `file` and that as such peggo will try to locate keys on disk by default. - -To use the default injectived key configuration, you should set the keyring path to the home directory of your injectived node, e.g. `~/.injectived`. - -You can also read more about the Cosmos Keyring setup [here](https://docs.cosmos.network/master/run-node/keyring.html). - -#### **Option 2. Cosmos Private Key (Unsafe)** - -In the `.env` file, specify the `PEGGO_COSMOS_PK` corresponding to your peggo account signing key. - -If you are using a delegated account key configuration as recommended above, this will be your orchestrator account's private key. Otherwise, this should be your validator's account private key. - -To obtain your orchestrator's Cosmos private key (if applicable), run - -```bash -injectived keys unsafe-export-eth-key $ORCHESTRATOR_KEY_NAME -``` - -To obtain your validator's Cosmos private key (if applicable), run - -```bash -injectived keys unsafe-export-eth-key $VALIDATOR_KEY_NAME -``` - -Again, this method is less secure and is not recommended. - -### **Managing Ethereum keys for `peggo`** - -Peggo supports two options to provide signing key credentials - using the Geth keystore (recommended) or by providing a plaintext Ethereum private key. - -#### **Option 1. Geth Keystore** - -Simply create a new private key store and update the following env variables: - -* `PEGGO_ETH_KEYSTORE_DIR` -* `PEGGO_ETH_FROM` -* `PEGGO_ETH_PASSPHRASE` - -You can find instructions for securely creating a new Ethereum account using a keystore in the Geth Documentation [here](https://geth.ethereum.org/docs/interface/managing-your-accounts). - -For convience, an example is provided below. - -```bash -geth account new --datadir=/home/ec2-user/.peggo/data/ - -INFO [03-23|18:18:36.407] Maximum peer count ETH=50 LES=0 total=50 -Your new account is locked with a password. Please give a password. Do not forget this password. -Password: -Repeat password: - -Your new key was generated - -Public address of the key: 0x9782dc957DaE6aDc394294954B27e2118D05176C -Path of the secret key file: /home/ec2-user/.peggo/data/keystore/UTC--2021-03-23T15-18-44.284118000Z--9782dc957dae6adc394294954b27e2118d05176c - -- You can share your public address with anyone. Others need it to interact with you. -- You must NEVER share the secret key with anyone! The key controls access to your funds! -- You must BACKUP your key file! Without the key, it's impossible to access account funds! -- You must REMEMBER your password! Without the password, it's impossible to decrypt the key! -``` - -Make sure you heed the warnings that geth provides, particularly in backing up your key file so that you don't lose your keys by mistake. We also recommend not using any quote or backtick characters in your passphrase for peggo compatibility purposes. - -You should now set the following env variables: - -```bash -# example values, replace with your own -PEGGO_ETH_KEYSTORE_DIR=/home/ec2-user/.peggo/data/keystore -PEGGO_ETH_FROM=0x9782dc957DaE6aDc394294954B27e2118D05176C -PEGGO_ETH_PASSPHRASE=12345678 -``` - -Then ensure that your Ethereum address has enough ETH. - -#### **Option 2. Ethereum Private Key (Unsafe)** - -Simply update the `PEGGO_ETH_PK` with a new Ethereum Private Key from a new account. - -Then ensure that your Ethereum address has ETH. - -## Step 2: Register Your Orchestrator and Ethereum Address - -You can register orchestrator and ethereum address only once. It **CANNOT** be updated later. So Check twice before running below command. - -```bash -injectived tx peggy set-orchestrator-address $VALIDATOR_INJ_ADDRESS $ORCHESTRATOR_INJ_ADDRESS $ETHEREUM_ADDRESS --from $VALIDATOR_KEY_NAME --chain-id=injective-888 --keyring-backend=file --yes --node=tcp://localhost:26657 --gas-prices=500000000inj - -``` - -* To obtain your validator's inj address, run, `injectived keys list $VALIDATOR_KEY_NAME` -* To obtain your orchestrators's inj address, `injectived keys list $ORCHESTRATOR_KEY_NAME` - -Example: - -```bash -injectived tx peggy set-orchestrator-address inj10m247khat0esnl0x66vu9mhlanfftnvww67j9n inj1x7kvxlz2epqx3hpq6v8j8w859t29pgca4z92l2 0xf79D16a79130a07e77eE36e8067AeA783aBdA3b6 --from validator-key-name --chain-id=injective-888 --keyring-backend=file --yes --node=tcp://localhost:26657 --gas-prices=500000000inj -``` - -You can verify successful registration by checking for your Validator's mapped Ethereum address on https://testnet.lcd.injective.dev/peggy/v1/valset/current. - -## Step 3: Start the Relayer - -```bash -cd ~/.peggo -peggo orchestrator -``` - -This starts the Peggo bridge (relayer / orchestrator). - -## Step 4: Create a Peggo systemd service - -Add `peggo.service` file with below content under `/etc/systemd/system/peggo.service` - -```ini -[Unit] - Description=peggo - -[Service] - WorkingDirectory=/home/ec2-user/.peggo - ExecStart=/bin/bash -c 'peggo orchestrator ' - Type=simple - Restart=always - RestartSec=1 - User=ec2-user - -[Install] - WantedBy=multi-user.target -``` - -Then run the following commands to configure Environment variables, start and stop the peggo relayer. - -```bash -sudo systemctl start peggo -sudo systemctl stop peggo -sudo systemctl restart peggo -sudo systemctl status peggo - -# enable start on system boot -sudo systemctl enable peggo - -# To check Logs -journalctl -f -u peggo -``` - -## Step 5: (Optional) Protect Cosmos Keyring from unauthorized access - -{% hint style="warning" %} -This is an advanced DevOps topic, consult with your sysadmin. -{% endhint %} - -Learn more about Cosmos Keyring setup [here](https://docs.cosmos.network/master/run-node/keyring.html). Once you've launched your node, the default keyring will have the validator operator key stored on disk in the encrypted form. Usually the keyring is located within node's homedir, i.e. `~/.injectived/keyring-file`. - -Some sections of the Injective Staking documentation will guide you through using this key for governance purposes, i.e. submitting transactions and setting up an Ethereum bridge. In order to protect the keys from unauthorized access, even when the keyring passphrase is leaked via configs, you can set OS permissions to allow disk access to `injectived` / `peggo` processes only. - -In Linux systems like Debian, Ubuntu and RHEL, this can be achieved using POSIX Access Control Lists (ACLs). Before beginning to work with ACLs, the file system must be mounted with ACLs turned on. There are some official guides for each distro: - -* [Ubuntu](https://help.ubuntu.com/community/FilePermissionsACLs) -* [Debian](https://wiki.debian.org/Permissions) -* [Amazon Linux (RHEL)](https://www.redhat.com/sysadmin/linux-access-control-lists) - -## Contribute - -If you'd like to inspect the Peggo orchestrator source code and contribute, you can do so at [https://github.com/InjectiveLabs/peggo](https://github.com/InjectiveLabs/peggo) diff --git a/.gitbook/references.md b/.gitbook/references.md deleted file mode 100644 index 6ecc4ef6..00000000 --- a/.gitbook/references.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -description: Important references and links for the Injective Ecosystem ---- - -# References - -## Developer Resources - -### Developer Tools and Resources - -Developer tools and resources to get you building on Injective - -| **Resource** | **Description** | -| --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | -| Cosmovisor | Small process manager around Cosmos SDK binaries that monitors the governance module | -| [Injective 101](https://injective.notion.site/Injective-101-589dedc4c9c04531aae503dbb235d443) | One-stop-shop for Injective resources | -| Injectived | Command-line interface and node daemon that connects to Injective | -| [Injective Explorer](https://explorer.injective.network/) | Analytics platform that enables anyone to search addresses, trades, tokens, transactions, and other activities on Injective | -| Injective Local | Injective testnet and ecosystem containerized with Docker and orchestrated with a simple docker-compose file. | -| [Injective REST API](https://lcd.injective.network/swagger/) | Swagger API explorer | -| Injective TypeScript SDK | TypeScript monorepo that contains packages which can be used to interact with Injective from a Node.js or browser environments | -| [Injective Python and Go SDK](https://api.injective.exchange/) | Detailed API documentation for interacting with Injective via P | -| [Real-time Status (Mainnet)](https://status.injective.network/) | Real-time status of the endpoints and of the Injective network | -| [Real-time Status (Testnet)](https://testnet.status.injective.network) | Real-time status of the endpoints and of the Injective testnet network | - -### Ecosystem Tools and Resources - -Tools and resources developed by ecosystem developers and partners - -| **Resource** | **Description** | -| -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | -| [Desig](https://desig.io/) | Multi-party computation (MPC) multisig solution | -| [DiscoverINJ](https://alpha.discoverinj.com/console) | UI smart contract query / execute | -| [The Graph](https://substreams.streamingfast.io/intro-injective) | Substreams for extracting data from the Injective blockchain. | -| [NewMetric](https://app.newmetric.xyz/) | Custom, high-performance RPC nodes | -| [Notifi](https://injective.com/notifications/) | Receive notifications for the latest chain updates, ecosystem developments, market insights, and more via Notifi | -| [Pyth](https://docs.pyth.network/home) | Price feed oracles and market data | -| [Starship](https://docs.cosmology.zone/starship) | Unified development environment that allows Cosmos developers to spin up a fully simulated mini-cosmos ecosystem and write end-to-end test cases | -| [SubQuery](https://github.com/subquery/cosmos-subql-starter/tree/main/Injective/injective-starter) | Open-source data indexer providing custom APIs | -| [Synternet](https://docs.synternet.com/build/data-layer/developer-portal/subscribe-to-streams) | Subscribe or publish real-time live data stream | -| [Wormhole](https://docs.wormhole.com/wormhole) | Cross-chain messaging protocol | - -### Helpful Repos - -Helpful repositories for developing on and integrating Injective - -| **Repo** | **Description** | -| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | -| [CosmWasm101](https://github.com/InjectiveLabs/CosmWasm101) | Guide to match the CosmWasm 101 presentation for the 2023 Injective Global Hackathon | -| [cw20-adapter](https://github.com/InjectiveLabs/cw20-adapter/tree/master/contracts/cw20-adapter) | Contract that allows exchanging CW-20 tokens for Injective-chain issued native tokens (using the TokenFactory module) and vice-versa | -| [cw-injective](https://github.com/InjectiveLabs/cw-injective) | Packages that can be used to integrate CosmWasm with Injective | -| [injective-ts-examples](https://github.com/InjectiveLabs/injective-ts-examples) | Helpful repo to get started building on the injective-ts library | -| [injective-ui](https://github.com/InjectiveLabs/injective-ui) | Collection of UI packages to ease development on Injective | -| [swap-contract](https://github.com/InjectiveLabs/swap-contract) | Open source atomic token swap contract that showcasing an instant swap between two different tokens | -| [test-tube](https://github.com/injectiveLabs/test-tube) | Generic library for building testing environments for CosmWasm smart contracts | - -### Developer Support - -Find developer support on Discord or Telegram - -1. Join the [Injective Discord server](https://discord.gg/injective) and find the relevant channel. -2. Join the [Injective Developer Telegram channel](https://t.me/+8Y\_0HOFLhnRlZDU9). - -### Public Endpoints - -For a list of public endpoints visit [public-endpoints.md](nodes/public-endpoints.md "mention") - -### Private / Dedicated Node Services - -For a full list of private node services see [private-nodes.md](nodes/private-nodes.md "mention") diff --git a/.gitbook/toolkits/README.md b/.gitbook/toolkits/README.md deleted file mode 100644 index 5389ff64..00000000 --- a/.gitbook/toolkits/README.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -description: We offer developers various toolkits to interact with the Injective ecosystem. ---- - -# Toolkits - -The following developer tools include SDKs, APIs, and libraries essential for building dApps on Injective. - -## List of toolkits - -
injectivedInteract with Injective using CLIinjectivedcode-hero.png
Injective TS SDKInteract with Injective using TypeScripthttps://docs.ts.injective.networkdev-hero.png
Injective Go SDKInteract with Injective using Gohttps://github.com/InjectiveLabs/sdk-go/code-hero.png
Injective Python SDKInteract with Injective using Pythonhttps://github.com/InjectiveLabs/sdk-pythondev-hero.png
Injective CW SDKInteract with Injective using CWhttps://github.com/InjectiveLabs/cw-injectivecode-hero.png
The GraphInteract with Injective using The Graphhttps://docs.substreams.dev/documentation/how-to-guides/injectivedev-hero.png
- diff --git a/.gitbook/toolkits/injectived/README.md b/.gitbook/toolkits/injectived/README.md deleted file mode 100644 index 4a99abe8..00000000 --- a/.gitbook/toolkits/injectived/README.md +++ /dev/null @@ -1,8 +0,0 @@ -# injectived - -`injectived` is the command-line interface and node daemon that connects to Injective. Injective core is the official Golang reference implementation of the Injective node software. - -## Getting Started - -
InstallLearn how to install injectivedinstall-injectived.mdcode-hero.png
UsageLearn how to use injectivedusing-injectived.mddev-hero.png
CommandsLearn advanced commands for injectivedadvanced.mdtxs-hero.png
- diff --git a/.gitbook/toolkits/injectived/advanced.md b/.gitbook/toolkits/injectived/advanced.md deleted file mode 100644 index 093b2036..00000000 --- a/.gitbook/toolkits/injectived/advanced.md +++ /dev/null @@ -1,354 +0,0 @@ -# Commands - -This section describes the commands available from `injectived`, the command line interface that connects a running `injectived` process (node). - -:::tip Several `injectived` commands require subcommands, arguments, or flags to operate. To view this information, run the `injectived` command with the `--help` or `-h` flag. See `query` or `tx` for usage examples of the help flag. - -For the `chain-id` argument, `injective-1` should be used for mainnet, and `injective-888` should be used for testnet. ::: - -### `add-genesis-account` - -Adds a genesis account to `genesis.json`. For more information on `genesis.json`, see the Join Testnet or Join Mainnet guide. - -**Syntax** - -```bash -injectived add-genesis-account -``` - -**Example** - -```bash -injectived add-genesis-account acc1 100000000000inj -``` - -### `collect-gentxs` - -Collects genesis transactions and outputs them to `genesis.json`. For more information on `genesis.json`, see the Join Testnet or Join Mainnet guide. - -**Syntax** - -```bash -injectived collect-gentxs -``` - -### `debug` - -Helps debug the application. For a list of syntax and subcommands, run the `debug` command with the `--help` or `-h` flag: - -```bash -injectived debug -h -``` - -**Subcommands**: - -```bash -injectived debug [subcommand] -``` - -* **`addr`**: Convert an address between hex and bech32 -* **`pubkey`**: Decode a pubkey from proto JSON -* **`raw-bytes`**: Convert raw bytes output (e.g. \[72 101 108 108 111 44 32 112 108 97 121 103 114 111 117 110 100]) to hex - -### `export` - -Exports the state to JSON. - -**Syntax** - -```bash -injectived export -``` - -### `gentx` - -Adds a genesis transaction to `genesis.json`. For more information on `genesis.json`, see the Join Testnet or Join Mainnet guide. - -:::note The `gentx` command has many flags available. Run the `gentx` command with `--help` or `-h` to view all flags.\ -::: - -**Syntax** - -```bash -injectived gentx -``` - -**Example** - -```bash -injectived gentx myKey 100000000000inj --home=/path/to/home/dir --keyring-backend=os --chain-id=injective-1 \ - --moniker="myValidator" \ - --commission-max-change-rate=0.01 \ - --commission-max-rate=1.0 \ - --commission-rate=0.07 \ - --details="..." \ - --security-contact="..." \ - --website="..." -``` - -### `help` - -Shows an overview of available commands. - -**Syntax** - -```bash -injectived help -``` - -### `init` - -Initializes the configuration files for a node. - -**Syntax** - -```bash -injectived init -``` - -**Example** - -```bash -injectived init myNode -``` - -### `keys` - -Manages Keyring commands. These keys may be in any format supported by the Tendermint crypto library and can be used by light-clients, full nodes, or any other application that needs to sign with a private key. - -For a list of syntax and subcommands, run the `keys` command with the `--help` or `-h` flag: - -```bash -injectived keys -h -``` - -**Subcommands**: - -```bash -injectived keys [subcommand] -``` - -* **`add`**: Add an encrypted private key (either newly generated or recovered), encrypt it, and save to the provided file name -* **`delete`**: Delete the given keys -* **`export`**: Export private keys -* **`import`**: Import private keys into the local keybase -* **`list`**: List all keys -* **`migrate`**: Migrate keys from the legacy (db-based) Keybase -* **`mnemonic`**: Compute the bip39 mnemonic for some input entropy -* **`parse`**: Parse address from hex to bech32 and vice versa -* **`show`**: Retrieve key information by name or address -* **`unsafe-export-eth-key`**: Export an Ethereum private key in plain text -* **`unsafe-import-eth-key`**: Import Ethereum private keys into the local keybase - -\ -`migrate` - -Migrates the source genesis into the target version and prints to STDOUT. For more information on `genesis.json`, see the Join Testnet or Join Mainnet guide. - -**Syntax** - -```bash -injectived migrate -``` - -**Example** - -```bash -injectived migrate v1.9.0 /path/to/genesis.json --chain-id=injective-888 --genesis-time=2023-03-07T17:00:00Z -``` - -### `query` - -Manages queries. For a list of syntax and subcommands, run the `query` subcommand with the `--help` or `-h` flag: - -```bash -injectived query -h -``` - -**Subcommands**: - -```bash -injectived query [subcommand] -``` - -* **`account`**: Query for account by address -* **`auction`**: Querying commands for the `auction` module -* **`auth`**: Querying commands for the `auth` module -* **`authz`**: Querying commands for the `authz` module -* **`bank`**: Querying commands for the `bank` module -* **`block`**: Get verified data for a block at the given height -* **`chainlink`**: Querying commands for the `oracle` module -* **`distribution`**: Querying commands for the `distribution` module -* **`evidence`**: Query for evidence by hash or for all (paginated) submitted evidence -* **`exchange`**: Querying commands for the `exchange` module -* **`feegrant`**: Querying commands for the `feegrant` module -* **`gov`**: Querying commands for the `governance` module -* **`ibc`**: Querying commands for the `ibc` module -* **`ibc-fee`**: IBC relayer incentivization query subcommands -* **`ibc-transfer`**: IBC fungible token transfer query subcommands -* **`insurance`**: Querying commands for the `insurance` module -* **`interchain-accounts`**: Interchain accounts subcommands -* **`mint`**: Querying commands for the minting module -* **`oracle`**: Querying commands for the `oracle` module -* **`params`**: Querying commands for the `params` module -* **`peggy`**: Querying commands for the `peggy` module -* **`slashing`**: Querying commands for the `slashing` module -* **`staking`**: Querying commands for the `staking` module -* **`tendermint-validator-set`**: Get the full tendermint validator set at given height -* **`tokenfactory`**: Querying commands for the `tokenfactory` module -* **`tx`**: Query for a transaction by hash, account sequence, or combination or comma-separated signatures in a committed block -* **`txs`**: Query for paginated transactions that match a set of events -* **`upgrade`**: Querying commands for the `upgrade` module -* **`wasm`**: Querying commands for the `wasm` module -* **`xwasm`**: Querying commands for the `wasmx` module - -### `rollback` - -A state rollback is performed to recover from an incorrect application state transition, when Tendermint has persisted an incorrect app hash and is thus unable to make progress. Rollback overwrites a state at height _n_ with the state at height _n - 1_. The application also roll back to height _n - 1_. No blocks are removed, so upon restarting Tendermint the transactions in block _n_ will be re-executed against the application. - -**Syntax** - -```bash -injectived rollback -``` - -### `rosetta` - -Creates a Rosetta server. - -**Syntax** - -```bash -injectived rosetta [flags] -``` - -### `start` - -Runs the full node application with Tendermint in or out of process. By default, the application runs with Tendermint in process. - -{% hint style="info" %} -The `start` command has many flags available. Run the `start` command with `--help` or `-h` to view all flags. -{% endhint %} - -**Syntax** - -```bash -injectived start [flags] -``` - -### `status` - -Displays the status of a remote node. Use the `--node` or `-n` flag to specify a node endpoint. - -**Syntax** - -```bash -injectived status -``` - -### `tendermint` - -Manages the Tendermint protocol. For a list of syntax and subcommands, run the `query` subcommand with the `--help` or `-h` flag: - -```bash -injectived tendermint -h -``` - -**Subcommands**: - -```bash -injectived tendermint [subcommand] -``` - -* **`reset-state`**: Remove all the data and WAL -* **`show-address`**: Shows this node's tendermint validator consensus address -* **`show-node-id`**: Show this node's ID -* **`show-validator`**: Show this node's tendermint validator info -* **`unsafe-reset-all`**: Remove all the data and WAL, reset this node's validator to genesis state -* **`version`** Show tendermint library versions - -### `testnet` - -Creates a testnet with the specified number of directories and populates each directory with the necessary files. - -{% hint style="info" %} -The `testnet` command has many flags available. Run the `testnet` command with `--help` or `-h` to view all flags. -{% endhint %} - -**Syntax** - -```bash -injectived testnet [flags] -``` - -**Example** - -```bash -injectived testnet --v 4 --keyring-backend test --output-dir ./output --ip-addresses 192.168.10.2 -``` - -### `tx` - -Manages generation, signing, and broadcasting of transactions. See Using Injectived for examples. - -For more information on syntax and available subcommands and, run the `tx` command with the `--help` or `-h` flag: - -```bash -injectived tx -h -``` - -**Subcommands**: - -```bash -injectived tx [subcommand] -``` - -* **`auction`**: Auction transactions subcommands -* **`authz`**: Authorization transactions subcommands -* **`bank`**: Bank transactions subcommands -* **`broadcast`**: Broadcast transactions generated offline -* **`chainlink`**: Off-Chain Reporting (OCR) subcommands -* **`crisis`**: Crisis transactions subcommands -* **`decode`**: Decode a binary encoded transaction string -* **`distribution`**: Distribution transactions subcommands -* **`encode`**: Encode transactions generated offline -* **`evidence`**: Evidence transactions subcommands -* **`exchange`**: Exchange transactions subcommands -* **`feegrant`**: Feegrant transactions subcommands -* **`gov`**: Governance transactions subcommands -* **`ibc`**: IBC transactions subcommands -* **`ibc-fee`**: IBC relayer incentivization transactions subcommands -* **`ibc-transfer`**: IBC fungible token transfer transactions subcommands -* **`insurance`**: Insurance transactions subcommands -* **`multisign`**: Generate multisig signatures for transactions generated offline -* **`oracle`**: Oracle transactions subcommands -* **`peggy`**: Peggy transactions subcommands -* **`sign`**: Sign a transaction generated offline -* **`sign-batch`**: Sign transaction batch files -* **`slashing`**: Slashing transactions subcommands -* **`staking`**: Staking transactions subcommands -* **`tokenfactory`**: Tokenfactory transactions subcommands -* **`validate-signatures`**: Validate transaction signatures -* **`vesting`**: Vesting transactions subcommands -* **`wasm`**: Wasm transactions subcommands -* **`xwasm`**: Wasmx transactions subcommands - -### `validate-genesis` - -Validates the genesis file at the default location or at the location specified. For more information on the genesis file, see the Join Testnet or Join Mainnet guide. - -**Syntax** - -```bash -injectived validate-genesis -``` - -### `version` - -Returns the version of Injective you’re running. - -**Syntax** - -```bash -injectived version -``` diff --git a/.gitbook/toolkits/injectived/install-injectived.md b/.gitbook/toolkits/injectived/install-injectived.md deleted file mode 100644 index bd9b62af..00000000 --- a/.gitbook/toolkits/injectived/install-injectived.md +++ /dev/null @@ -1,46 +0,0 @@ -# Install injectived - -The easiest way to install `injectived` and Injective core is by downloading a pre-built binary for your operating system. Download the most recent Injective binaries from [the official releases repo](https://github.com/InjectiveLabs/injective-chain-releases). - -```bash -wget https://github.com/InjectiveLabs/injective-chain-releases/releases/download/v1.13.2-1723753267/linux-amd64.zip -``` - -This zip file will contain three binaries and a virtual machine: - -* **`injectived`** - Injective daemon -* **`peggo`** - Injective ERC-20 bridge relayer daemon -* **`injective-exchange`** - the Injective Exchange daemon -* **`libwasmvm.x86_64.so`** - the wasm virtual machine which is needed to execute smart contracts. - -Unzip and add `injectived`, to your `/usr/bin`. Also add `libwasmvm.x86_64.so` to user library path `/usr/lib`. - -Note that you do not need `injective-exchange` and `peggo` for deploying and instantiating smart contracts. - -```bash -unzip linux-amd64.zip -sudo mv injectived /usr/bin -sudo mv libwasmvm.x86_64.so /usr/lib -``` - -Confirm your version matches the output below (your output may be slightly different if a newer version is available): - -```bash -injectived version -Version v1.10.0 (bf0b93dca) -Compiled at 20230317-2113 using Go go1.19.4 (amd64) -``` - -## Start injectived - -Once you have `injectived` installed, you can start an instance of the chain by downloading this initialization script and starting the binary - -```bash -wget https://raw.githubusercontent.com/InjectiveLabs/injective-chain-releases/master/scripts/setup.sh -``` - -Once the `script.sh` is downloaded, run it and start the chain - -```bash -./setup.sh && injectived start -``` diff --git a/.gitbook/toolkits/injectived/using-injectived.md b/.gitbook/toolkits/injectived/using-injectived.md deleted file mode 100644 index f08172ab..00000000 --- a/.gitbook/toolkits/injectived/using-injectived.md +++ /dev/null @@ -1,160 +0,0 @@ -# Using injectived - -The following explains what one can do via `injectived`, the command-line interface that connects to Injective, as well as interact with the Injective blockchain. Every active validator and full node runs `injectived` and communicates with their node via `injectived`. In this relationship, `injectived` operates as both the client and the server. You can use `injectived` to interact with the Injective blockchain by uploading smart contracts, querying data, managing staking activities, working with governance proposals, and more. - -For more general information about `injectived`, run: - -```bash -injectived --help -``` - -For more information about a specific `injectived` command, append the `-h` or `--help` flag after the command. For example: - -```bash -injectived query --help. -``` - -### Accessing a Node - -To query the state and send transactions, you must connect to a node, which is the access point to the entire network of peer connections. You can either run your own full node or connect to someone else’s. See Interacting with Nodes. - -{% hint style="info" %} -An endpoint may be specified using the `--node=` option. For example, to query the Injective Testnet: - -Command: - -```bash -injectived query bank balances inj1clw20s2uxeyxtam6f7m84vgae92s9eh7vygagt --node=https://k8s.testnet.tm.injective.network:443 -``` - -Response: - -```bash -balances: -- amount: "9990004452404000000000" - denom: inj -- amount: "9689943532" - denom: peggy0x87aB3B4C8661e07D6372361211B96ed4Dc36B1B5 -pagination: - next_key: null - total: "0" -``` -{% endhint %} - -### Configuring `injectived` - -`injectived` enables you to interact with the node that runs on the Injective network, whether you run it yourself or not. To configure `injectived`, edit the the `config.toml` file in the `~/.injective/config/` directory. - -### Querying Blockchain State - -For testing purpose, we assume you are connected to a node in your local private network. - -Now that your very own Injective node is running, it is time to try sending tokens from the first account you created to a second account. In a new terminal window, start by running the following query command: - -```bash -injectived query bank balances $MY_VALIDATOR_ADDRESS --chain-id=injective-1 -``` - -You should see the current balance of the account you created, equal to the original balance of `inj` you granted it minus the amount you delegated via the `gentx`. Now, create a second account: - -```bash -injectived keys add recipient --keyring-backend=file - -# Put the generated address in a variable for later use. -RECIPIENT=$(injectived keys show recipient -a --keyring-backend=file) -``` - -The command above creates a local key-pair that is not yet registered on the chain. An account is created the first time it receives tokens from another account. Now, run the following command to send tokens to the `recipient` account: - -```bash -injectived tx bank send $MY_VALIDATOR_ADDRESS $RECIPIENT 1000000inj --chain-id=injective-1 --keyring-backend=file - -# Check that the recipient account did receive the tokens. -injectived query bank balances $RECIPIENT --chain-id=injective-1 -``` - -Finally, delegate some of the stake tokens sent to the `recipient` account to the validator: - -```bash -injectived tx staking delegate $(injectived keys show my_validator --bech val -a --keyring-backend=file) 500inj --from=recipient --chain-id=injective-1 --keyring-backend=file - -# Query the total delegations to `validator`. -injectived query staking delegations-to $(injectived keys show my_validator --bech val -a --keyring-backend=file) --chain-id=injective-1 -``` - -You should see two delegations, the first one made from the `gentx`, and the second one you just performed from the `recipient` account. - -### Generate, Sign, and Broadcast a Transaction - -Running the following command will execute the following steps: - -```bash -injectived tx bank send $MY_VALIDATOR_ADDRESS $RECIPIENT 1000inj --chain-id=injective-1 --keyring-backend=file -``` - -* Generate a transaction with one `Msg` (`x/bank`'s `MsgSend`), and print the generated transaction to the console. -* Ask the user for confirmation to send the transaction from the `$MY_VALIDATOR_ADDRESS` account. -* Fetch `$MY_VALIDATOR_ADDRESS` from the keyring. This is possible because we have set up the CLI's keyring in a previous step. -* Sign the generated transaction with the keyring's account. -* Broadcast the signed transaction to the network. This is possible because the CLI connects to the node's Tendermint RPC endpoint. - -The CLI bundles all the necessary steps into a simple-to-use user experience. However, it is possible to run all the steps individually as well. - -#### Generating a Transaction - -Generating a transaction can simply be done by appending the `--generate-only` flag on any `tx` command, e.g.: - -```bash -injectived tx bank send $MY_VALIDATOR_ADDRESS $RECIPIENT 1000inj --chain-id=injective-1 --generate-only -``` - -This will output the unsigned transaction as JSON in the console. We can also save the unsigned transaction to a file (to be passed around between signers more easily) by appending `> unsigned_tx.json` to the above command. - -#### Signing a Transaction - -Signing a transaction using the CLI requires the unsigned transaction to be saved in a file. Let's assume the unsigned transaction is in a file called `unsigned_tx.json` in the current directory (see previous paragraph on how to do that). Then, simply run the following command: - -```bash -injectived tx sign unsigned_tx.json --chain-id=injective-1 --keyring-backend=file --from=$MY_VALIDATOR_ADDRESS -``` - -This command will decode the unsigned transaction and sign it with `SIGN_MODE_DIRECT` with `$MY_VALIDATOR_ADDRESS`'s key, which we already set up in the keyring. The signed transaction will be output as JSON to the console, and, as above, we can save it to a file by appending `> signed_tx.json`. - -Some useful flags to consider in the `tx sign` command: - -* `--sign-mode`: you may use `amino-json` to sign the transaction using `SIGN_MODE_LEGACY_AMINO_JSON`, -* `--offline`: sign in offline mode. This means that the `tx sign` command doesn't connect to the node to retrieve the signer's account number and sequence, both needed for signing. In this case, you must manually supply the `--account-number` and `--sequence` flags. This is useful for offline signing, i.e. signing in a secure environment which doesn't have access to the internet. - -#### **Signing with Multiple Signers** - -{% hint style="info" %} -Please note that signing a transaction with multiple signers or with a multisig account, where at least one signer uses `SIGN_MODE_DIRECT`, is not yet possible. You may follow [this Github issue](https://github.com/cosmos/cosmos-sdk/issues/8141) for more info. -{% endhint %} - -Signing with multiple signers is done with the `tx multisign` command. This command assumes that all signers use `SIGN_MODE_LEGACY_AMINO_JSON`. The flow is similar to the `tx sign` command flow, but instead of signing an unsigned transaction file, each signer signs the file signed by previous signer(s). The `tx multisign` command will append signatures to the existing transactions. It is important that signers sign the transaction **in the same order** as given by the transaction, which is retrievable using the `GetSigners()` method. - -For example, starting with the `unsigned_tx.json`, and assuming the transaction has 4 signers, we would run: - -```bash -# Let signer1 sign the unsigned tx. -injectived tx multisignsign unsigned_tx.json signer_key_1 --chain-id=injective-1 --keyring-backend=file > partial_tx_1.json -# Now signer1 will send the partial_tx_1.json to the signer2. -# Signer2 appends their signature: -injectived tx multisignsign partial_tx_1.json signer_key_2 --chain-id=injective-1 --keyring-backend=file > partial_tx_2.json -# Signer2 sends the partial_tx_2.json file to signer3, and signer3 can append his signature: -injectived tx multisignsign partial_tx_2.json signer_key_3 --chain-id=injective-1 --keyring-backend=file > partial_tx_3.json -``` - -#### Broadcasting a Transaction - -Broadcasting a transaction is done using the following command: - -```bash -injectived tx broadcast tx_signed.json -``` - -You may optionally pass the `--broadcast-mode` flag to specify which response to receive from the node: - -* `block`: the CLI waits for the tx to be committed in a block. -* `sync`: the CLI waits for a CheckTx execution response only. -* `async`: the CLI returns immediately (transaction might fail). diff --git a/.gitbook/traders/getting-started.md b/.gitbook/traders/getting-started.md deleted file mode 100644 index f81622b2..00000000 --- a/.gitbook/traders/getting-started.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -description: >- - This section helps traders to learn more about trading instruments and start - trading on Injective ---- - -# Getting Started - -🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 - -This page is currently under work in progress. - -🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 diff --git a/.gitignore b/.gitignore index f928452b..5e06e6fe 100644 --- a/.gitignore +++ b/.gitignore @@ -10,7 +10,6 @@ .cache-loader # Misc -.env .DS_Store .env.local .env.development.local