diff --git a/.gitbook/developers/modules.md b/.gitbook/developers/modules.md
deleted file mode 100644
index f0dc8066..00000000
--- a/.gitbook/developers/modules.md
+++ /dev/null
@@ -1,2 +0,0 @@
-# Modules
-
diff --git a/.gitbook/developers/modules/README.md b/.gitbook/developers/modules/README.md
new file mode 100644
index 00000000..3a4a9ddf
--- /dev/null
+++ b/.gitbook/developers/modules/README.md
@@ -0,0 +1,22 @@
+import {
+ HomepageCard as Card,
+ HomepageSection as Section,
+} from "../../../src/components/HomepageComponents";
+import { DistributedIcon, CoreModulesIcon } from "../../../src/icons";
+
+# Injective Modules
+
+
diff --git a/.gitbook/developers/modules/core/README.md b/.gitbook/developers/modules/core/README.md
new file mode 100644
index 00000000..b0790a93
--- /dev/null
+++ b/.gitbook/developers/modules/core/README.md
@@ -0,0 +1,14 @@
+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
new file mode 100644
index 00000000..bd9f18a3
--- /dev/null
+++ b/.gitbook/developers/modules/core/auth/README.md
@@ -0,0 +1,710 @@
+---
+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
new file mode 100644
index 00000000..676654a2
--- /dev/null
+++ b/.gitbook/developers/modules/core/authz/README.md
@@ -0,0 +1,355 @@
+---
+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
new file mode 100644
index 00000000..a7eba4ae
--- /dev/null
+++ b/.gitbook/developers/modules/core/bank/README.md
@@ -0,0 +1,1039 @@
+---
+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
new file mode 100644
index 00000000..f3b75389
--- /dev/null
+++ b/.gitbook/developers/modules/core/circuit/README.md
@@ -0,0 +1,170 @@
+# `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
new file mode 100644
index 00000000..902280a6
--- /dev/null
+++ b/.gitbook/developers/modules/core/consensus/README.md
@@ -0,0 +1,7 @@
+---
+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
new file mode 100644
index 00000000..e4e29d0a
--- /dev/null
+++ b/.gitbook/developers/modules/core/crisis/README.md
@@ -0,0 +1,110 @@
+---
+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
new file mode 100644
index 00000000..32858fd6
--- /dev/null
+++ b/.gitbook/developers/modules/core/distribution/README.md
@@ -0,0 +1,1049 @@
+---
+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
new file mode 100644
index 00000000..82cd03ba
--- /dev/null
+++ b/.gitbook/developers/modules/core/evidence/README.md
@@ -0,0 +1,440 @@
+---
+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
new file mode 100644
index 00000000..07524449
--- /dev/null
+++ b/.gitbook/developers/modules/core/feegrant/README.md
@@ -0,0 +1,396 @@
+---
+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
new file mode 100644
index 00000000..45cb4535
--- /dev/null
+++ b/.gitbook/developers/modules/core/genutil/README.md
@@ -0,0 +1,89 @@
+# `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/gov/README.md b/.gitbook/developers/modules/core/gov/README.md
new file mode 100644
index 00000000..87b2fc5f
--- /dev/null
+++ b/.gitbook/developers/modules/core/gov/README.md
@@ -0,0 +1,2547 @@
+---
+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
new file mode 100644
index 00000000..71d91ccb
--- /dev/null
+++ b/.gitbook/developers/modules/core/group/README.md
@@ -0,0 +1,2166 @@
+---
+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
new file mode 100644
index 00000000..80198010
--- /dev/null
+++ b/.gitbook/developers/modules/core/mint/README.md
@@ -0,0 +1,383 @@
+---
+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
new file mode 100644
index 00000000..34c1d406
--- /dev/null
+++ b/.gitbook/developers/modules/core/nft/README.md
@@ -0,0 +1,89 @@
+---
+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
new file mode 100644
index 00000000..f8d374d0
--- /dev/null
+++ b/.gitbook/developers/modules/core/params/README.md
@@ -0,0 +1,79 @@
+---
+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
new file mode 100644
index 00000000..591a9a73
--- /dev/null
+++ b/.gitbook/developers/modules/core/slashing/README.md
@@ -0,0 +1,813 @@
+---
+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
new file mode 100644
index 00000000..c011a593
--- /dev/null
+++ b/.gitbook/developers/modules/core/staking/README.md
@@ -0,0 +1,3058 @@
+---
+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.
+
+
+
+### 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.
+
+
+
+### 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.
+
+
+
+
+### 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
new file mode 100644
index 00000000..0d98c160
--- /dev/null
+++ b/.gitbook/developers/modules/core/upgrade/README.md
@@ -0,0 +1,619 @@
+---
+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
new file mode 100644
index 00000000..8a5fa20d
--- /dev/null
+++ b/.gitbook/developers/modules/injective/README.md
@@ -0,0 +1,14 @@
+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
new file mode 100644
index 00000000..ecb09d89
--- /dev/null
+++ b/.gitbook/developers/modules/injective/auction/01_state.md
@@ -0,0 +1,60 @@
+---
+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
new file mode 100644
index 00000000..97f7253f
--- /dev/null
+++ b/.gitbook/developers/modules/injective/auction/02_messages.md
@@ -0,0 +1,32 @@
+---
+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
new file mode 100644
index 00000000..88018bc3
--- /dev/null
+++ b/.gitbook/developers/modules/injective/auction/03_end_block.md
@@ -0,0 +1,21 @@
+---
+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.
+
+
\ 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
new file mode 100644
index 00000000..ed87d2d7
--- /dev/null
+++ b/.gitbook/developers/modules/injective/auction/04_events.md
@@ -0,0 +1,28 @@
+---
+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
new file mode 100644
index 00000000..2f56a4a4
--- /dev/null
+++ b/.gitbook/developers/modules/injective/auction/05_params.md
@@ -0,0 +1,14 @@
+---
+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
new file mode 100644
index 00000000..55f22fdc
--- /dev/null
+++ b/.gitbook/developers/modules/injective/auction/README.md
@@ -0,0 +1,15 @@
+# `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
new file mode 100644
index 00000000..10dad042
Binary files /dev/null and b/.gitbook/developers/modules/injective/auction/img.png 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
new file mode 100644
index 00000000..f1227953
--- /dev/null
+++ b/.gitbook/developers/modules/injective/exchange/00_derivative_market_concepts.md
@@ -0,0 +1,244 @@
+---
+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
new file mode 100644
index 00000000..6d413d33
--- /dev/null
+++ b/.gitbook/developers/modules/injective/exchange/01_spot_market_concepts.md
@@ -0,0 +1,135 @@
+---
+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
new file mode 100644
index 00000000..8e9dc11f
--- /dev/null
+++ b/.gitbook/developers/modules/injective/exchange/02_binary_options_markets.md
@@ -0,0 +1,115 @@
+---
+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
new file mode 100644
index 00000000..e971f931
--- /dev/null
+++ b/.gitbook/developers/modules/injective/exchange/02_other_concepts.md
@@ -0,0 +1,69 @@
+---
+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
new file mode 100644
index 00000000..719cc7b2
--- /dev/null
+++ b/.gitbook/developers/modules/injective/exchange/03_state.md
@@ -0,0 +1,594 @@
+---
+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
new file mode 100644
index 00000000..99b858ee
--- /dev/null
+++ b/.gitbook/developers/modules/injective/exchange/04_state_transitions.md
@@ -0,0 +1,447 @@
+---
+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
new file mode 100644
index 00000000..75ad01c5
--- /dev/null
+++ b/.gitbook/developers/modules/injective/exchange/05_messages.md
@@ -0,0 +1,443 @@
+---
+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
new file mode 100644
index 00000000..b0e1a33a
--- /dev/null
+++ b/.gitbook/developers/modules/injective/exchange/06_proposals.md
@@ -0,0 +1,404 @@
+---
+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
new file mode 100644
index 00000000..6d0f1bf8
--- /dev/null
+++ b/.gitbook/developers/modules/injective/exchange/07_begin_block.md
@@ -0,0 +1,74 @@
+---
+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
new file mode 100644
index 00000000..b536c118
--- /dev/null
+++ b/.gitbook/developers/modules/injective/exchange/08_end_block.md
@@ -0,0 +1,78 @@
+---
+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
new file mode 100644
index 00000000..09008054
--- /dev/null
+++ b/.gitbook/developers/modules/injective/exchange/09_events.md
@@ -0,0 +1,169 @@
+---
+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
new file mode 100644
index 00000000..8dcdf5d1
--- /dev/null
+++ b/.gitbook/developers/modules/injective/exchange/10_params.md
@@ -0,0 +1,35 @@
+---
+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
new file mode 100644
index 00000000..16995856
--- /dev/null
+++ b/.gitbook/developers/modules/injective/exchange/11_msg_privileged_execute_contract.md
@@ -0,0 +1,127 @@
+---
+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
new file mode 100644
index 00000000..d9c8423d
--- /dev/null
+++ b/.gitbook/developers/modules/injective/exchange/README.md
@@ -0,0 +1,29 @@
+# `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
new file mode 100644
index 00000000..b7c3402c
--- /dev/null
+++ b/.gitbook/developers/modules/injective/insurance/01_state.md
@@ -0,0 +1,92 @@
+---
+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
new file mode 100644
index 00000000..08b66df4
--- /dev/null
+++ b/.gitbook/developers/modules/injective/insurance/02_state_transitions.md
@@ -0,0 +1,124 @@
+---
+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
new file mode 100644
index 00000000..416b1a03
--- /dev/null
+++ b/.gitbook/developers/modules/injective/insurance/03_messages.md
@@ -0,0 +1,95 @@
+---
+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
new file mode 100644
index 00000000..8fece042
--- /dev/null
+++ b/.gitbook/developers/modules/injective/insurance/04_end_block.md
@@ -0,0 +1,8 @@
+---
+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
new file mode 100644
index 00000000..5add6de2
--- /dev/null
+++ b/.gitbook/developers/modules/injective/insurance/05_events.md
@@ -0,0 +1,39 @@
+---
+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
new file mode 100644
index 00000000..2f042a3a
--- /dev/null
+++ b/.gitbook/developers/modules/injective/insurance/06_params.md
@@ -0,0 +1,13 @@
+---
+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
new file mode 100644
index 00000000..44c84d94
--- /dev/null
+++ b/.gitbook/developers/modules/injective/insurance/07_future_improvements.md
@@ -0,0 +1,11 @@
+---
+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
new file mode 100644
index 00000000..172cdb49
--- /dev/null
+++ b/.gitbook/developers/modules/injective/insurance/README.md
@@ -0,0 +1,19 @@
+# `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
new file mode 100644
index 00000000..c42047f4
--- /dev/null
+++ b/.gitbook/developers/modules/injective/ocr/01_concepts.md
@@ -0,0 +1,60 @@
+---
+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
new file mode 100644
index 00000000..5ab39bbd
--- /dev/null
+++ b/.gitbook/developers/modules/injective/ocr/02_state.md
@@ -0,0 +1,218 @@
+---
+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
new file mode 100644
index 00000000..ee0823ff
--- /dev/null
+++ b/.gitbook/developers/modules/injective/ocr/03_messages.md
@@ -0,0 +1,227 @@
+---
+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
new file mode 100644
index 00000000..787e24ae
--- /dev/null
+++ b/.gitbook/developers/modules/injective/ocr/04_proposals.md
@@ -0,0 +1,50 @@
+---
+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
new file mode 100644
index 00000000..6c2ed6a8
--- /dev/null
+++ b/.gitbook/developers/modules/injective/ocr/05_begin_block.md
@@ -0,0 +1,13 @@
+---
+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
new file mode 100644
index 00000000..c50e2acf
--- /dev/null
+++ b/.gitbook/developers/modules/injective/ocr/06_hooks.md
@@ -0,0 +1,17 @@
+---
+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
new file mode 100644
index 00000000..257d2c97
--- /dev/null
+++ b/.gitbook/developers/modules/injective/ocr/07_events.md
@@ -0,0 +1,102 @@
+---
+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
new file mode 100644
index 00000000..f78af34e
--- /dev/null
+++ b/.gitbook/developers/modules/injective/ocr/08_params.md
@@ -0,0 +1,14 @@
+---
+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
new file mode 100644
index 00000000..41e1e177
--- /dev/null
+++ b/.gitbook/developers/modules/injective/ocr/README.md
@@ -0,0 +1,21 @@
+# 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
new file mode 100644
index 00000000..5a5ed19e
--- /dev/null
+++ b/.gitbook/developers/modules/injective/oracle/01_state.md
@@ -0,0 +1,275 @@
+---
+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
new file mode 100644
index 00000000..32509c5f
--- /dev/null
+++ b/.gitbook/developers/modules/injective/oracle/02_keeper.md
@@ -0,0 +1,120 @@
+---
+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
new file mode 100644
index 00000000..599e47a3
--- /dev/null
+++ b/.gitbook/developers/modules/injective/oracle/03_messages.md
@@ -0,0 +1,190 @@
+---
+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
new file mode 100644
index 00000000..82488e8c
--- /dev/null
+++ b/.gitbook/developers/modules/injective/oracle/04_proposals.md
@@ -0,0 +1,227 @@
+---
+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
new file mode 100644
index 00000000..ea883770
--- /dev/null
+++ b/.gitbook/developers/modules/injective/oracle/05_events.md
@@ -0,0 +1,96 @@
+---
+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
new file mode 100644
index 00000000..60b92334
--- /dev/null
+++ b/.gitbook/developers/modules/injective/oracle/06_future_improvements.md
@@ -0,0 +1,10 @@
+---
+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
new file mode 100644
index 00000000..f30bd028
--- /dev/null
+++ b/.gitbook/developers/modules/injective/oracle/README.md
@@ -0,0 +1,39 @@
+# `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
new file mode 100644
index 00000000..037c1da0
--- /dev/null
+++ b/.gitbook/developers/modules/injective/peggy/01_definitions.md
@@ -0,0 +1,36 @@
+---
+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
new file mode 100644
index 00000000..2a7b4742
--- /dev/null
+++ b/.gitbook/developers/modules/injective/peggy/02_workflow.md
@@ -0,0 +1,164 @@
+---
+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**
+
+
+
+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**
+
+
+
+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**
+
+
+
+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
new file mode 100644
index 00000000..e589efe6
--- /dev/null
+++ b/.gitbook/developers/modules/injective/peggy/03_state.md
@@ -0,0 +1,265 @@
+---
+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
new file mode 100644
index 00000000..d2f14516
--- /dev/null
+++ b/.gitbook/developers/modules/injective/peggy/04_messages.md
@@ -0,0 +1,199 @@
+---
+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
new file mode 100644
index 00000000..41d2fa40
--- /dev/null
+++ b/.gitbook/developers/modules/injective/peggy/05_slashing.md
@@ -0,0 +1,91 @@
+---
+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
new file mode 100644
index 00000000..40bcae02
--- /dev/null
+++ b/.gitbook/developers/modules/injective/peggy/06_end_block.md
@@ -0,0 +1,51 @@
+---
+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
new file mode 100644
index 00000000..68ea6656
--- /dev/null
+++ b/.gitbook/developers/modules/injective/peggy/07_events.md
@@ -0,0 +1,143 @@
+---
+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
new file mode 100644
index 00000000..d76128cc
--- /dev/null
+++ b/.gitbook/developers/modules/injective/peggy/08_params.md
@@ -0,0 +1,112 @@
+---
+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
new file mode 100644
index 00000000..8dbcad36
--- /dev/null
+++ b/.gitbook/developers/modules/injective/peggy/09_relay_semantics.md
@@ -0,0 +1,53 @@
+---
+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
new file mode 100644
index 00000000..76771318
--- /dev/null
+++ b/.gitbook/developers/modules/injective/peggy/10_future_improvements.md
@@ -0,0 +1,22 @@
+---
+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
new file mode 100644
index 00000000..87c78767
--- /dev/null
+++ b/.gitbook/developers/modules/injective/peggy/README.md
@@ -0,0 +1,39 @@
+# `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
new file mode 100644
index 00000000..c66908f6
Binary files /dev/null and b/.gitbook/developers/modules/injective/peggy/images/SendToCosmos.png differ
diff --git a/.gitbook/developers/modules/injective/peggy/images/SendToEth.png b/.gitbook/developers/modules/injective/peggy/images/SendToEth.png
new file mode 100644
index 00000000..914787ed
Binary files /dev/null and b/.gitbook/developers/modules/injective/peggy/images/SendToEth.png differ
diff --git a/.gitbook/developers/modules/injective/peggy/images/valsetupdate.png b/.gitbook/developers/modules/injective/peggy/images/valsetupdate.png
new file mode 100644
index 00000000..5592111f
Binary files /dev/null and b/.gitbook/developers/modules/injective/peggy/images/valsetupdate.png differ
diff --git a/.gitbook/developers/modules/injective/permissions/01_concepts.md b/.gitbook/developers/modules/injective/permissions/01_concepts.md
new file mode 100644
index 00000000..9b166cbf
--- /dev/null
+++ b/.gitbook/developers/modules/injective/permissions/01_concepts.md
@@ -0,0 +1,57 @@
+---
+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
new file mode 100644
index 00000000..f026f149
--- /dev/null
+++ b/.gitbook/developers/modules/injective/permissions/02_state.md
@@ -0,0 +1,93 @@
+---
+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
new file mode 100644
index 00000000..fe0a11bf
--- /dev/null
+++ b/.gitbook/developers/modules/injective/permissions/03_state_transitions.md
@@ -0,0 +1,188 @@
+---
+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
new file mode 100644
index 00000000..c92ce1de
--- /dev/null
+++ b/.gitbook/developers/modules/injective/permissions/README.md
@@ -0,0 +1,13 @@
+# `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
new file mode 100644
index 00000000..730c65cb
--- /dev/null
+++ b/.gitbook/developers/modules/injective/tokenfactory/01_concepts.md
@@ -0,0 +1,23 @@
+---
+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
new file mode 100644
index 00000000..dfaefb62
--- /dev/null
+++ b/.gitbook/developers/modules/injective/tokenfactory/02_state.md
@@ -0,0 +1,74 @@
+---
+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
new file mode 100644
index 00000000..9869b19a
--- /dev/null
+++ b/.gitbook/developers/modules/injective/tokenfactory/03_messages.md
@@ -0,0 +1,145 @@
+---
+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
new file mode 100644
index 00000000..ac7a3185
--- /dev/null
+++ b/.gitbook/developers/modules/injective/tokenfactory/04_events.md
@@ -0,0 +1,54 @@
+---
+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
new file mode 100644
index 00000000..a2bd83cd
--- /dev/null
+++ b/.gitbook/developers/modules/injective/tokenfactory/05_params.md
@@ -0,0 +1,19 @@
+---
+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
new file mode 100644
index 00000000..d1b0a39b
--- /dev/null
+++ b/.gitbook/developers/modules/injective/tokenfactory/README.md
@@ -0,0 +1,14 @@
+# 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
new file mode 100644
index 00000000..50da6d18
--- /dev/null
+++ b/.gitbook/developers/modules/injective/wasmx/01_concepts.md
@@ -0,0 +1,53 @@
+---
+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
new file mode 100644
index 00000000..822bb8fb
--- /dev/null
+++ b/.gitbook/developers/modules/injective/wasmx/02_data.md
@@ -0,0 +1,38 @@
+---
+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
new file mode 100644
index 00000000..c815ddd5
--- /dev/null
+++ b/.gitbook/developers/modules/injective/wasmx/03_proposals.md
@@ -0,0 +1,130 @@
+---
+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
new file mode 100644
index 00000000..a1b1699c
--- /dev/null
+++ b/.gitbook/developers/modules/injective/wasmx/04_messages.md
@@ -0,0 +1,90 @@
+---
+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
new file mode 100644
index 00000000..2663c1f3
--- /dev/null
+++ b/.gitbook/developers/modules/injective/wasmx/05_params.md
@@ -0,0 +1,21 @@
+---
+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
new file mode 100644
index 00000000..71cdd4f7
--- /dev/null
+++ b/.gitbook/developers/modules/injective/wasmx/README.md
@@ -0,0 +1,17 @@
+# `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/.gitignore b/.gitignore
index 5e06e6fe..f928452b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -10,6 +10,7 @@
.cache-loader
# Misc
+.env
.DS_Store
.env.local
.env.development.local