diff --git a/docs/build/build.md b/docs/build/build.md index 12c1265fc..3b86eb472 100644 --- a/docs/build/build.md +++ b/docs/build/build.md @@ -1,15 +1,13 @@ --- sidebar_position: 0 --- + # Build -* [Architecture](./architecture/README.md) - Overview and detailed explanation of the system architecture. -* [Building Apps](./building-apps/00-app-go.md) - The documentation in this section will guide you through the process of developing your dApp using the Cosmos SDK framework. -* [Modules](./modules/README.md) - Information about the various modules available in the Cosmos SDK: Auth, Authz, Bank, Crisis, Distribution, Evidence, Feegrant, Governance, Mint, Params, Slashing, Staking, Upgrade, NFT, Consensus, Circuit, Genutil. -* [Migrations](./migrations/01-intro.md) - See what has been updated in each release the process of the transition between versions. -* [Packages](./packages/README.md) - Explore a curated collection of pre-built modules and functionalities, streamlining the development process. -* [Tooling](./tooling/README.md) - A suite of utilities designed to enhance the development workflow, optimizing the efficiency of Cosmos SDK-based projects. -* [ADR's](./architecture/README.md) - Provides a structured repository of key decisions made during the development process, which have been documented and offers rationale behind key decisions being made. -* [RFC](./rfc/README.md) - A Request for Comments (RFC) is a record of discussion on an open-ended topic related to the design and implementation of the Cosmos SDK, for which no immediate decision is required. -* [Specifications](./spec/README.md) - A detailed reference for the specifications of various components and features. -* [REST API](https://docs.cosmos.network/api) - A comprehensive reference for the application programming interfaces (APIs) provided by the SDK. +* [Building Apps](./building-apps/00-app-go.md) - The documentation in this section will guide you through the process of developing your dApp using the Cosmos SDK framework. +* [Modules](./modules/README.md) - Information about the various modules available in the Cosmos SDK: Auth, Authz, Bank, Crisis, Distribution, Evidence, Feegrant, Governance, Mint, Params, Slashing, Staking, Upgrade, NFT, Consensus, Circuit, Genutil. +* [Migrations](./migrations/01-intro.md) - See what has been updated in each release the process of the transition between versions. +* [Packages](./packages/README.md) - Explore a curated collection of pre-built modules and functionalities, streamlining the development process. +* [Tooling](./tooling/README.md) - A suite of utilities designed to enhance the development workflow, optimizing the efficiency of Cosmos SDK-based projects. +* [ADR's](./architecture/README.md) - Provides a structured repository of key decisions made during the development process, which have been documented and offers rationale behind key decisions being made. +* [REST API](https://docs.cosmos.network/api) - A comprehensive reference for the application programming interfaces (APIs) provided by the SDK. diff --git a/docs/glossary.md b/docs/glossary.md index a2da9d7bd..6021a3f2c 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -6,52 +6,69 @@ sidebar_position: 3 # Glossary ## ABCI (Application Blockchain Interface) + The interface between the Tendermint consensus engine and the application state machine, allowing them to communicate and perform state transitions. ABCI is a critical component of the Cosmos SDK, enabling developers to build applications using any programming language that can communicate via ABCI. ## ATOM + The native staking token of the Cosmos Hub, used for securing the network, participating in governance, and paying fees for transactions. ## CometBFT + A Byzantine Fault Tolerant (BFT) consensus engine that powers the Cosmos SDK. CometBFT is responsible for handling the consensus and networking layers of a blockchain. ## Cosmos Hub + The first blockchain built with the Cosmos SDK, functioning as a hub for connecting other blockchains in the Cosmos ecosystem through IBC. ## Cosmos SDK + A framework for building blockchain applications, focusing on modularity, scalability, and interoperability. ## CosmWasm + A smart contract engine for the Cosmos SDK that enables developers to write and deploy smart contracts in WebAssembly (Wasm). CosmWasm is designed to be secure, efficient, and easy to use, allowing developers to build complex applications on top of the Cosmos SDK. ## Delegator + A participant in a Proof of Stake network who delegates their tokens to a validator. Delegators share in the rewards and risks associated with the validator's performance in the consensus process. ## Gas + A measure of computational effort required to execute a transaction or smart contract on a blockchain. In the Cosmos ecosystem, gas is used to meter transactions and allocate resources fairly among users. Users must pay a gas fee, usually in the native token, to have their transactions processed by the network. ## Governance + The decision-making process in the Cosmos ecosystem, which allows token holders to propose and vote on network upgrades, parameter changes, and other critical decisions. ## IBC (Inter-Blockchain Communication) + A protocol for secure and reliable communication between heterogeneous blockchains built on the Cosmos SDK. IBC enables the transfer of tokens and data across multiple blockchains. ## Interoperability + The ability of different blockchains and distributed systems to communicate and interact with each other, enabling the seamless transfer of information, tokens, and other digital assets. In the context of Cosmos, the Inter-Blockchain Communication (IBC) protocol is a core technology that enables interoperability between blockchains built with the Cosmos SDK and other compatible blockchains. Interoperability allows for increased collaboration, innovation, and value creation across different blockchain ecosystems. ## Light Clients + Lightweight blockchain clients that verify and process only a small subset of the blockchain data, allowing users to interact with the network without downloading the entire blockchain. ABCI++ aims to enhance the security and performance of light clients by enabling them to efficiently verify state transitions and proofs. ## Module + A self-contained, reusable piece of code that can be used to build blockchain functionality within a Cosmos SDK application. Modules can be developed by the community and shared for others to use. ## Slashing + The process of penalizing validators or delegators by reducing their staked tokens if they behave maliciously or fail to meet the network's performance requirements. ## Staking + The process of locking up tokens as collateral to secure the network, participate in consensus, and earn rewards in a Proof of Stake (PoS) blockchain like Cosmos. ## State Sync + A feature that allows new nodes to quickly synchronize with the current state of the blockchain without downloading and processing all previous blocks. State Sync is particularly useful for nodes that have been offline for an extended period or are joining the network for the first time. ABCI++ aims to improve the efficiency and security of State Sync. ## Validator -A network participant responsible for proposing new blocks, validating transactions, and securing the Cosmos SDK-based blockchain through staking tokens. Validators play a crucial role in maintaining the security and integrity of the network. \ No newline at end of file + +A network participant responsible for proposing new blocks, validating transactions, and securing the Cosmos SDK-based blockchain through staking tokens. Validators play a crucial role in maintaining the security and integrity of the network. diff --git a/docusaurus.config.js b/docusaurus.config.js index 2e9582267..a43bef8a4 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -45,7 +45,7 @@ const config = { path: "main", banner: "unreleased", }, - "0.52": { + 0.52: { path: "v0.52", label: "v0.52", }, @@ -123,7 +123,8 @@ const config = { type: "doc", label: "Tutorials", collapsed: false, - docId: "tutorials/vote-extensions/auction-frontrunning/getting-started", + docId: + "tutorials/vote-extensions/auction-frontrunning/getting-started", position: "left", }, { @@ -247,7 +248,7 @@ const config = { markdown: { mermaid: true, }, - themes: ["@you54f/theme-github-codeblock", '@docusaurus/theme-mermaid'], + themes: ["@you54f/theme-github-codeblock", "@docusaurus/theme-mermaid"], plugins: [ async function myPlugin(context, options) { return { @@ -498,9 +499,6 @@ const config = { if (existingPath.includes("/user/run-node")) { return [existingPath.replace("/user/run-node", "/run-node")]; } - if (existingPath.includes("/user/validate")) { - return [existingPath.replace("/user/validate", "/validate")]; - } return undefined; }, }, @@ -512,15 +510,14 @@ const config = { "data-website-id": "752cab42-f5d6-4af3-9d31-fb0d6e501c4a", "data-project-name": "Cosmos SDK", "data-project-color": "#5064FB", - "data-modal-disclaimer": "This is a custom LLM for Interchain with access to Cosmos SDK developer documentation and resources. Please note that answers are generated by an AI so please use your best judgement before implementing.", - "data-modal-image": - "img/logo-sdk.svg", - "data-project-logo": - "img/logo-sdk-white.svg", + "data-modal-disclaimer": + "This is a custom LLM for Interchain with access to Cosmos SDK developer documentation and resources. Please note that answers are generated by an AI so please use your best judgement before implementing.", + "data-modal-image": "img/logo-sdk.svg", + "data-project-logo": "img/logo-sdk-white.svg", "data-user-analytics-fingerprint-enabled": "true", async: true, }, - ] + ], }; module.exports = config; diff --git a/sync_script.sh b/sync_script.sh index e3ea203cb..b0df8d5f9 100755 --- a/sync_script.sh +++ b/sync_script.sh @@ -2,19 +2,15 @@ set -e -o pipefail -# Set the remote repository URL to clone from -REMOTE_REPO_URL="https://github.com/cosmos/cosmos-sdk.git" - # Store the current working directory in WORK_DIR WORK_DIR=$(pwd) # Remove any existing 'cosmos-sdk' directory and clone the remote repository rm -rf ./cosmos-sdk -git clone "$REMOTE_REPO_URL" cosmos-sdk +git clone https://github.com/cosmos/cosmos-sdk.git cosmos-sdk -# Read the versions from a JSON file and remove the 'v' prefix +# Read the versions from a JSON file VERSIONS=($(jq -r '.[]' versions.json)) - VERSIONS+=("main") # Iterate over each version @@ -24,7 +20,6 @@ for version in "${VERSIONS[@]}"; do branch="main" # Set the branch to 'main' version_directory="" # For 'main', the version directory is empty else - version="${version#v}" # Remove the 'v' prefix from the version number branch="release/v$version.x" # Determine the branch name version_directory="version-$version" # Create a directory name based on the version fi @@ -42,39 +37,37 @@ for version in "${VERSIONS[@]}"; do git fetch origin "$branch" git checkout "$branch" - # Check if the branch exists in the remote repository - if ! git show-ref --verify "refs/remotes/origin/$branch" &>/dev/null; then - echo "Branch $branch does not exist in the remote repository." - continue - else - echo "Branch $branch exists, continuing..." - fi - # Run the pre.sh script cd docs && sh ./pre.sh - for folder in "build" "learn"; do - if [ "$version" == "main" ]; then - cp -r "$WORK_DIR/cosmos-sdk/docs/$folder" "$WORK_DIR/docs/" - elif [[ -d "$WORK_DIR/cosmos-sdk/docs/docs/" ]]; then # 0.50 and 0.47 - cp -r "$WORK_DIR/cosmos-sdk/docs/docs/$folder" "$WORK_DIR/versioned_docs/$version_directory/" - else - cp -r "$WORK_DIR/cosmos-sdk/docs/$folder" "$WORK_DIR/versioned_docs/$version_directory/" - fi - done + # Copy the 'build', 'learn' and 'user' directories to the 'docs' directory if [ "$version" == "main" ]; then - cp -r "$WORK_DIR/cosmos-sdk/client/docs/swagger-ui/swagger.yaml" "$WORK_DIR/openapi/" + mkdir -p "$WORK_DIR/docs" + cp -r "$WORK_DIR/cosmos-sdk/docs/build" "$WORK_DIR/docs" + cp -r "$WORK_DIR/cosmos-sdk/docs/learn" "$WORK_DIR/docs" + cp -r "$WORK_DIR/cosmos-sdk/docs/user" "$WORK_DIR/docs" + cp -r "$WORK_DIR/cosmos-sdk/client/docs/swagger-ui/swagger.yaml" "$WORK_DIR/openapi/" + elif [ "$version" == "0.50" ] || [ "$version" == "0.47" ]; then + mkdir -p "$WORK_DIR/versioned_docs/$version_directory" + cp -r "$WORK_DIR/cosmos-sdk/docs/docs/build" "$WORK_DIR/versioned_docs/$version_directory" + cp -r "$WORK_DIR/cosmos-sdk/docs/docs/learn" "$WORK_DIR/versioned_docs/$version_directory" + cp -r "$WORK_DIR/cosmos-sdk/docs/docs/user" "$WORK_DIR/versioned_docs/$version_directory" + # add main tutorials on versioned_docs + cp -r $WORK_DIR/docs/tutorials "$WORK_DIR/versioned_docs/$version_directory" + else + mkdir -p "$WORK_DIR/versioned_docs/$version_directory" + cp -r "$WORK_DIR/cosmos-sdk/docs/build" "$WORK_DIR/versioned_docs/$version_directory" + cp -r "$WORK_DIR/cosmos-sdk/docs/learn" "$WORK_DIR/versioned_docs/$version_directory" + cp -r "$WORK_DIR/cosmos-sdk/docs/user" "$WORK_DIR/versioned_docs/$version_directory" + # add main tutorials on versioned_docs + cp -r $WORK_DIR/docs/tutorials "$WORK_DIR/versioned_docs/$version_directory" fi + + git checkout -- . # Discard changes to the repository done # Leave the 'cosmos-sdk' directory after processing cd "$WORK_DIR" -# This is copied to ensure main and 0.50 are up to date with one another -cp -a "docs/user" "versioned_docs/version-0.50" - -wget -O "docs/user/run-node/04-rosetta.md" "https://raw.githubusercontent.com/cosmos/rosetta/main/README.md" -cp -r "docs/user/run-node/04-rosetta.md" "versioned_docs/version-0.50/user/run-node/04-rosetta.md" - -# Remove the 'cosmos-sdk' directory if needed - rm -rf ./cosmos-sdk +# Remove the 'cosmos-sdk' directory +rm -rf ./cosmos-sdk \ No newline at end of file diff --git a/versioned_docs/version-0.50/build/build.md b/versioned_docs/version-0.50/build/build.md index 12c1265fc..3b86eb472 100644 --- a/versioned_docs/version-0.50/build/build.md +++ b/versioned_docs/version-0.50/build/build.md @@ -1,15 +1,13 @@ --- sidebar_position: 0 --- + # Build -* [Architecture](./architecture/README.md) - Overview and detailed explanation of the system architecture. -* [Building Apps](./building-apps/00-app-go.md) - The documentation in this section will guide you through the process of developing your dApp using the Cosmos SDK framework. -* [Modules](./modules/README.md) - Information about the various modules available in the Cosmos SDK: Auth, Authz, Bank, Crisis, Distribution, Evidence, Feegrant, Governance, Mint, Params, Slashing, Staking, Upgrade, NFT, Consensus, Circuit, Genutil. -* [Migrations](./migrations/01-intro.md) - See what has been updated in each release the process of the transition between versions. -* [Packages](./packages/README.md) - Explore a curated collection of pre-built modules and functionalities, streamlining the development process. -* [Tooling](./tooling/README.md) - A suite of utilities designed to enhance the development workflow, optimizing the efficiency of Cosmos SDK-based projects. -* [ADR's](./architecture/README.md) - Provides a structured repository of key decisions made during the development process, which have been documented and offers rationale behind key decisions being made. -* [RFC](./rfc/README.md) - A Request for Comments (RFC) is a record of discussion on an open-ended topic related to the design and implementation of the Cosmos SDK, for which no immediate decision is required. -* [Specifications](./spec/README.md) - A detailed reference for the specifications of various components and features. -* [REST API](https://docs.cosmos.network/api) - A comprehensive reference for the application programming interfaces (APIs) provided by the SDK. +* [Building Apps](./building-apps/00-app-go.md) - The documentation in this section will guide you through the process of developing your dApp using the Cosmos SDK framework. +* [Modules](./modules/README.md) - Information about the various modules available in the Cosmos SDK: Auth, Authz, Bank, Crisis, Distribution, Evidence, Feegrant, Governance, Mint, Params, Slashing, Staking, Upgrade, NFT, Consensus, Circuit, Genutil. +* [Migrations](./migrations/01-intro.md) - See what has been updated in each release the process of the transition between versions. +* [Packages](./packages/README.md) - Explore a curated collection of pre-built modules and functionalities, streamlining the development process. +* [Tooling](./tooling/README.md) - A suite of utilities designed to enhance the development workflow, optimizing the efficiency of Cosmos SDK-based projects. +* [ADR's](./architecture/README.md) - Provides a structured repository of key decisions made during the development process, which have been documented and offers rationale behind key decisions being made. +* [REST API](https://docs.cosmos.network/api) - A comprehensive reference for the application programming interfaces (APIs) provided by the SDK. diff --git a/versioned_docs/version-0.50/build/modules/README.md b/versioned_docs/version-0.50/build/modules/README.md deleted file mode 100644 index 0d98c1601..000000000 --- a/versioned_docs/version-0.50/build/modules/README.md +++ /dev/null @@ -1,619 +0,0 @@ ---- -sidebar_position: 1 ---- - -# `x/upgrade` - -## Abstract - -`x/upgrade` is an implementation of a Cosmos SDK module that facilitates smoothly -upgrading a live Cosmos chain to a new (breaking) software version. It accomplishes this by -providing a `PreBlocker` hook that prevents the blockchain state machine from -proceeding once a pre-defined upgrade block height has been reached. - -The module does not prescribe anything regarding how governance decides to do an -upgrade, but just the mechanism for coordinating the upgrade safely. Without software -support for upgrades, upgrading a live chain is risky because all of the validators -need to pause their state machines at exactly the same point in the process. If -this is not done correctly, there can be state inconsistencies which are hard to -recover from. - -* [Concepts](#concepts) -* [State](#state) -* [Events](#events) -* [Client](#client) - * [CLI](#cli) - * [REST](#rest) - * [gRPC](#grpc) -* [Resources](#resources) - -## Concepts - -### Plan - -The `x/upgrade` module defines a `Plan` type in which a live upgrade is scheduled -to occur. A `Plan` can be scheduled at a specific block height. -A `Plan` is created once a (frozen) release candidate along with an appropriate upgrade -`Handler` (see below) is agreed upon, where the `Name` of a `Plan` corresponds to a -specific `Handler`. Typically, a `Plan` is created through a governance proposal -process, where if voted upon and passed, will be scheduled. The `Info` of a `Plan` -may contain various metadata about the upgrade, typically application specific -upgrade info to be included on-chain such as a git commit that validators could -automatically upgrade to. - -```go -type Plan struct { - Name string - Height int64 - Info string -} -``` - -#### Sidecar Process - -If an operator running the application binary also runs a sidecar process to assist -in the automatic download and upgrade of a binary, the `Info` allows this process to -be seamless. This tool is [Cosmovisor](https://github.com/cosmos/cosmos-sdk/tree/main/tools/cosmovisor#readme). - -### Handler - -The `x/upgrade` module facilitates upgrading from major version X to major version Y. To -accomplish this, node operators must first upgrade their current binary to a new -binary that has a corresponding `Handler` for the new version Y. It is assumed that -this version has fully been tested and approved by the community at large. This -`Handler` defines what state migrations need to occur before the new binary Y -can successfully run the chain. Naturally, this `Handler` is application specific -and not defined on a per-module basis. Registering a `Handler` is done via -`Keeper#SetUpgradeHandler` in the application. - -```go -type UpgradeHandler func(Context, Plan, VersionMap) (VersionMap, error) -``` - -During each `EndBlock` execution, the `x/upgrade` module checks if there exists a -`Plan` that should execute (is scheduled at that height). If so, the corresponding -`Handler` is executed. If the `Plan` is expected to execute but no `Handler` is registered -or if the binary was upgraded too early, the node will gracefully panic and exit. - -### StoreLoader - -The `x/upgrade` module also facilitates store migrations as part of the upgrade. The -`StoreLoader` sets the migrations that need to occur before the new binary can -successfully run the chain. This `StoreLoader` is also application specific and -not defined on a per-module basis. Registering this `StoreLoader` is done via -`app#SetStoreLoader` in the application. - -```go -func UpgradeStoreLoader (upgradeHeight int64, storeUpgrades *store.StoreUpgrades) baseapp.StoreLoader -``` - -If there's a planned upgrade and the upgrade height is reached, the old binary writes `Plan` to the disk before panicking. - -This information is critical to ensure the `StoreUpgrades` happens smoothly at correct height and -expected upgrade. It eliminiates the chances for the new binary to execute `StoreUpgrades` multiple -times everytime on restart. Also if there are multiple upgrades planned on same height, the `Name` -will ensure these `StoreUpgrades` takes place only in planned upgrade handler. - -### Proposal - -Typically, a `Plan` is proposed and submitted through governance via a proposal -containing a `MsgSoftwareUpgrade` message. -This proposal prescribes to the standard governance process. If the proposal passes, -the `Plan`, which targets a specific `Handler`, is persisted and scheduled. The -upgrade can be delayed or hastened by updating the `Plan.Height` in a new proposal. - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/upgrade/v1beta1/tx.proto#L29-L41 -``` - -#### Cancelling Upgrade Proposals - -Upgrade proposals can be cancelled. There exists a gov-enabled `MsgCancelUpgrade` -message type, which can be embedded in a proposal, voted on and, if passed, will -remove the scheduled upgrade `Plan`. -Of course this requires that the upgrade was known to be a bad idea well before the -upgrade itself, to allow time for a vote. - -```protobuf reference -https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/upgrade/v1beta1/tx.proto#L48-L57 -``` - -If such a possibility is desired, the upgrade height is to be -`2 * (VotingPeriod + DepositPeriod) + (SafetyDelta)` from the beginning of the -upgrade proposal. The `SafetyDelta` is the time available from the success of an -upgrade proposal and the realization it was a bad idea (due to external social consensus). - -A `MsgCancelUpgrade` proposal can also be made while the original -`MsgSoftwareUpgrade` proposal is still being voted upon, as long as the `VotingPeriod` -ends after the `MsgSoftwareUpgrade` proposal. - -## State - -The internal state of the `x/upgrade` module is relatively minimal and simple. The -state contains the currently active upgrade `Plan` (if one exists) by key -`0x0` and if a `Plan` is marked as "done" by key `0x1`. The state -contains the consensus versions of all app modules in the application. The versions -are stored as big endian `uint64`, and can be accessed with prefix `0x2` appended -by the corresponding module name of type `string`. The state maintains a -`Protocol Version` which can be accessed by key `0x3`. - -* Plan: `0x0 -> Plan` -* Done: `0x1 | byte(plan name) -> BigEndian(Block Height)` -* ConsensusVersion: `0x2 | byte(module name) -> BigEndian(Module Consensus Version)` -* ProtocolVersion: `0x3 -> BigEndian(Protocol Version)` - -The `x/upgrade` module contains no genesis state. - -## Events - -The `x/upgrade` does not emit any events by itself. Any and all proposal related -events are emitted through the `x/gov` module. - -## Client - -### CLI - -A user can query and interact with the `upgrade` module using the CLI. - -#### Query - -The `query` commands allow users to query `upgrade` state. - -```bash -simd query upgrade --help -``` - -##### applied - -The `applied` command allows users to query the block header for height at which a completed upgrade was applied. - -```bash -simd query upgrade applied [upgrade-name] [flags] -``` - -If upgrade-name was previously executed on the chain, this returns the header for the block at which it was applied. -This helps a client determine which binary was valid over a given range of blocks, as well as more context to understand past migrations. - -Example: - -```bash -simd query upgrade applied "test-upgrade" -``` - -Example Output: - -```bash -"block_id": { - "hash": "A769136351786B9034A5F196DC53F7E50FCEB53B48FA0786E1BFC45A0BB646B5", - "parts": { - "total": 1, - "hash": "B13CBD23011C7480E6F11BE4594EE316548648E6A666B3575409F8F16EC6939E" - } - }, - "block_size": "7213", - "header": { - "version": { - "block": "11" - }, - "chain_id": "testnet-2", - "height": "455200", - "time": "2021-04-10T04:37:57.085493838Z", - "last_block_id": { - "hash": "0E8AD9309C2DC411DF98217AF59E044A0E1CCEAE7C0338417A70338DF50F4783", - "parts": { - "total": 1, - "hash": "8FE572A48CD10BC2CBB02653CA04CA247A0F6830FF19DC972F64D339A355E77D" - } - }, - "last_commit_hash": "DE890239416A19E6164C2076B837CC1D7F7822FC214F305616725F11D2533140", - "data_hash": "E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855", - "validators_hash": "A31047ADE54AE9072EE2A12FF260A8990BA4C39F903EAF5636B50D58DBA72582", - "next_validators_hash": "A31047ADE54AE9072EE2A12FF260A8990BA4C39F903EAF5636B50D58DBA72582", - "consensus_hash": "048091BC7DDC283F77BFBF91D73C44DA58C3DF8A9CBC867405D8B7F3DAADA22F", - "app_hash": "28ECC486AFC332BA6CC976706DBDE87E7D32441375E3F10FD084CD4BAF0DA021", - "last_results_hash": "E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855", - "evidence_hash": "E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855", - "proposer_address": "2ABC4854B1A1C5AA8403C4EA853A81ACA901CC76" - }, - "num_txs": "0" -} -``` - -##### module versions - -The `module_versions` command gets a list of module names and their respective consensus versions. - -Following the command with a specific module name will return only -that module's information. - -```bash -simd query upgrade module_versions [optional module_name] [flags] -``` - -Example: - -```bash -simd query upgrade module_versions -``` - -Example Output: - -```bash -module_versions: -- name: auth - version: "2" -- name: authz - version: "1" -- name: bank - version: "2" -- name: crisis - version: "1" -- name: distribution - version: "2" -- name: evidence - version: "1" -- name: feegrant - version: "1" -- name: genutil - version: "1" -- name: gov - version: "2" -- name: ibc - version: "2" -- name: mint - version: "1" -- name: params - version: "1" -- name: slashing - version: "2" -- name: staking - version: "2" -- name: transfer - version: "1" -- name: upgrade - version: "1" -- name: vesting - version: "1" -``` - -Example: - -```bash -regen query upgrade module_versions ibc -``` - -Example Output: - -```bash -module_versions: -- name: ibc - version: "2" -``` - -##### plan - -The `plan` command gets the currently scheduled upgrade plan, if one exists. - -```bash -regen query upgrade plan [flags] -``` - -Example: - -```bash -simd query upgrade plan -``` - -Example Output: - -```bash -height: "130" -info: "" -name: test-upgrade -time: "0001-01-01T00:00:00Z" -upgraded_client_state: null -``` - -#### Transactions - -The upgrade module supports the following transactions: - -* `software-proposal` - submits an upgrade proposal: - -```bash -simd tx upgrade software-upgrade v2 --title="Test Proposal" --summary="testing" --deposit="100000000stake" --upgrade-height 1000000 \ ---upgrade-info '{ "binaries": { "linux/amd64":"https://example.com/simd.zip?checksum=sha256:aec070645fe53ee3b3763059376134f058cc337247c978add178b6ccdfb0019f" } }' --from cosmos1.. -``` - -* `cancel-software-upgrade` - cancels a previously submitted upgrade proposal: - -```bash -simd tx upgrade cancel-software-upgrade --title="Test Proposal" --summary="testing" --deposit="100000000stake" --from cosmos1.. -``` - -### REST - -A user can query the `upgrade` module using REST endpoints. - -#### Applied Plan - -`AppliedPlan` queries a previously applied upgrade plan by its name. - -```bash -/cosmos/upgrade/v1beta1/applied_plan/{name} -``` - -Example: - -```bash -curl -X GET "http://localhost:1317/cosmos/upgrade/v1beta1/applied_plan/v2.0-upgrade" -H "accept: application/json" -``` - -Example Output: - -```bash -{ - "height": "30" -} -``` - -#### Current Plan - -`CurrentPlan` queries the current upgrade plan. - -```bash -/cosmos/upgrade/v1beta1/current_plan -``` - -Example: - -```bash -curl -X GET "http://localhost:1317/cosmos/upgrade/v1beta1/current_plan" -H "accept: application/json" -``` - -Example Output: - -```bash -{ - "plan": "v2.1-upgrade" -} -``` - -#### Module versions - -`ModuleVersions` queries the list of module versions from state. - -```bash -/cosmos/upgrade/v1beta1/module_versions -``` - -Example: - -```bash -curl -X GET "http://localhost:1317/cosmos/upgrade/v1beta1/module_versions" -H "accept: application/json" -``` - -Example Output: - -```bash -{ - "module_versions": [ - { - "name": "auth", - "version": "2" - }, - { - "name": "authz", - "version": "1" - }, - { - "name": "bank", - "version": "2" - }, - { - "name": "crisis", - "version": "1" - }, - { - "name": "distribution", - "version": "2" - }, - { - "name": "evidence", - "version": "1" - }, - { - "name": "feegrant", - "version": "1" - }, - { - "name": "genutil", - "version": "1" - }, - { - "name": "gov", - "version": "2" - }, - { - "name": "ibc", - "version": "2" - }, - { - "name": "mint", - "version": "1" - }, - { - "name": "params", - "version": "1" - }, - { - "name": "slashing", - "version": "2" - }, - { - "name": "staking", - "version": "2" - }, - { - "name": "transfer", - "version": "1" - }, - { - "name": "upgrade", - "version": "1" - }, - { - "name": "vesting", - "version": "1" - } - ] -} -``` - -### gRPC - -A user can query the `upgrade` module using gRPC endpoints. - -#### Applied Plan - -`AppliedPlan` queries a previously applied upgrade plan by its name. - -```bash -cosmos.upgrade.v1beta1.Query/AppliedPlan -``` - -Example: - -```bash -grpcurl -plaintext \ - -d '{"name":"v2.0-upgrade"}' \ - localhost:9090 \ - cosmos.upgrade.v1beta1.Query/AppliedPlan -``` - -Example Output: - -```bash -{ - "height": "30" -} -``` - -#### Current Plan - -`CurrentPlan` queries the current upgrade plan. - -```bash -cosmos.upgrade.v1beta1.Query/CurrentPlan -``` - -Example: - -```bash -grpcurl -plaintext localhost:9090 cosmos.slashing.v1beta1.Query/CurrentPlan -``` - -Example Output: - -```bash -{ - "plan": "v2.1-upgrade" -} -``` - -#### Module versions - -`ModuleVersions` queries the list of module versions from state. - -```bash -cosmos.upgrade.v1beta1.Query/ModuleVersions -``` - -Example: - -```bash -grpcurl -plaintext localhost:9090 cosmos.slashing.v1beta1.Query/ModuleVersions -``` - -Example Output: - -```bash -{ - "module_versions": [ - { - "name": "auth", - "version": "2" - }, - { - "name": "authz", - "version": "1" - }, - { - "name": "bank", - "version": "2" - }, - { - "name": "crisis", - "version": "1" - }, - { - "name": "distribution", - "version": "2" - }, - { - "name": "evidence", - "version": "1" - }, - { - "name": "feegrant", - "version": "1" - }, - { - "name": "genutil", - "version": "1" - }, - { - "name": "gov", - "version": "2" - }, - { - "name": "ibc", - "version": "2" - }, - { - "name": "mint", - "version": "1" - }, - { - "name": "params", - "version": "1" - }, - { - "name": "slashing", - "version": "2" - }, - { - "name": "staking", - "version": "2" - }, - { - "name": "transfer", - "version": "1" - }, - { - "name": "upgrade", - "version": "1" - }, - { - "name": "vesting", - "version": "1" - } - ] -} -``` - -## Resources - -A list of (external) resources to learn more about the `x/upgrade` module. - -* [Cosmos Dev Series: Cosmos Blockchain Upgrade](https://medium.com/web3-surfers/cosmos-dev-series-cosmos-sdk-based-blockchain-upgrade-b5e99181554c) - The blog post that explains how software upgrades work in detail. diff --git a/versioned_docs/version-0.50/build/rfc/rfc/PROCESS.md b/versioned_docs/version-0.50/build/rfc/rfc/PROCESS.md deleted file mode 100644 index a34af2269..000000000 --- a/versioned_docs/version-0.50/build/rfc/rfc/PROCESS.md +++ /dev/null @@ -1,62 +0,0 @@ -# RFC Creation Process - -1. Copy the `rfc-template.md` file. Use the following filename pattern: `rfc-next_number-title.md` -2. Create a draft Pull Request if you want to get an early feedback. -3. Make sure the context and a solution is clear and well documented. -4. Add an entry to a list in the [README](./README.md) file. -5. Create a Pull Request to propose a new ADR. - -## What is an RFC? - -An RFC is a sort of async whiteboarding session. It is meant to replace the need for a distributed team to come together to make a decision. Currently, the Cosmos SDK team and contributors are distributed around the world. The team conducts working groups to have a synchronous discussion and an RFC can be used to capture the discussion for a wider audience to better understand the changes that are coming to the software. - -The main difference the Cosmos SDK is defining as a differentiation between RFC and ADRs is that one is to come to consensus and circulate information about a potential change or feature. An ADR is used if there is already consensus on a feature or change and there is not a need to articulate the change coming to the software. An ADR will articulate the changes and have a lower amount of communication . - -## RFC life cycle - -RFC creation is an **iterative** process. An RFC is meant as a distributed colloboration session, it may have many comments and is usually the bi-product of no working group or synchornous communication - -1. Proposals could start with a new GitHub Issue, be a result of existing Issues or a discussion. - -2. An RFC doesn't have to arrive to `main` with an _accepted_ status in a single PR. If the motivation is clear and the solution is sound, we SHOULD be able to merge it and keep a _proposed_ status. It's preferable to have an iterative approach rather than long, not merged Pull Requests. - -3. If a _proposed_ RFC is merged, then it should clearly document outstanding issues either in the RFC document notes or in a GitHub Issue. - -4. The PR SHOULD always be merged. In the case of a faulty RFC, we still prefer to merge it with a _rejected_ status. The only time the RFC SHOULD NOT be merged is if the author abandons it. - -5. Merged RFCs SHOULD NOT be pruned. - -6. If there is consensus and enough feedback then the RFC can be accepted. - -> Note: An RFC is written when there is no working group or team session on the problem. RFC's are meant as a distributed white boarding session. If there is a working group on the proposal there is no need to have an RFC as there is synchornous whiteboarding going on. - -### RFC status - -Status has two components: - -```text -{CONSENSUS STATUS} -``` - -#### Consensus Status - -```text -DRAFT -> PROPOSED -> LAST CALL yyyy-mm-dd -> ACCEPTED | REJECTED -> SUPERSEDED by ADR-xxx - \ | - \ | - v v - ABANDONED -``` - -* `DRAFT`: [optional] an ADR which is work in progress, not being ready for a general review. This is to present an early work and get an early feedback in a Draft Pull Request form. -* `PROPOSED`: an ADR covering a full solution architecture and still in the review - project stakeholders haven't reached an agreed yet. -* `LAST CALL `: [optional] clear notify that we are close to accept updates. Changing a status to `LAST CALL` means that social consensus (of Cosmos SDK maintainers) has been reached and we still want to give it a time to let the community react or analyze. -* `ACCEPTED`: ADR which will represent a currently implemented or to be implemented architecture design. -* `REJECTED`: ADR can go from PROPOSED or ACCEPTED to rejected if the consensus among project stakeholders will decide so. -* `SUPERSEEDED by ADR-xxx`: ADR which has been superseded by a new ADR. -* `ABANDONED`: the ADR is no longer pursued by the original authors. - -## Language used in RFC - -* The background/goal should be written in the present tense. -* Avoid using a first, personal form. diff --git a/versioned_docs/version-0.50/build/rfc/rfc/README.md b/versioned_docs/version-0.50/build/rfc/rfc/README.md deleted file mode 100644 index 8b8ead241..000000000 --- a/versioned_docs/version-0.50/build/rfc/rfc/README.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -sidebar_position: 1 ---- - -# Requests for Comments - -A Request for Comments (RFC) is a record of discussion on an open-ended topic -related to the design and implementation of the Cosmos SDK, for which no -immediate decision is required. - -The purpose of an RFC is to serve as a historical record of a high-level -discussion that might otherwise only be recorded in an ad-hoc way (for example, -via gists or Google docs) that are difficult to discover for someone after the -fact. An RFC _may_ give rise to more specific architectural _decisions_ for -the Cosmos SDK, but those decisions must be recorded separately in -[Architecture Decision Records (ADR)](../architecture). - -As a rule of thumb, if you can articulate a specific question that needs to be -answered, write an ADR. If you need to explore the topic and get input from -others to know what questions need to be answered, an RFC may be appropriate. - -## RFC Content - -An RFC should provide: - -* A **changelog**, documenting when and how the RFC has changed. -* An **abstract**, briefly summarizing the topic so the reader can quickly tell - whether it is relevant to their interest. -* Any **background** a reader will need to understand and participate in the - substance of the discussion (links to other documents are fine here). -* The **discussion**, the primary content of the document. - -The [rfc-template.md](./rfc-template.md) file includes placeholders for these -sections. - -## Table of Contents - -* [RFC-001: Tx Validation](./rfc-001-tx-validation.md) diff --git a/versioned_docs/version-0.50/build/rfc/rfc/rfc-001-tx-validation.md b/versioned_docs/version-0.50/build/rfc/rfc/rfc-001-tx-validation.md deleted file mode 100644 index 923e1c720..000000000 --- a/versioned_docs/version-0.50/build/rfc/rfc/rfc-001-tx-validation.md +++ /dev/null @@ -1,25 +0,0 @@ -# RFC 001: Transaction Validation - -## Changelog - -* 2023-03-12: Proposed - -## Background - -Transation Validation is crucial to a functioning state machine. Within the Cosmos SDK there are two validation flows, one is outside the message server and the other within. The flow outside of the message server is the `ValidateBasic` function. It is called in the antehandler on both `CheckTx` and `DeliverTx`. There is an overhead and sometimes duplication of validation within these two flows. This extra validation provides an additional check before entering the mempool. - -With the deprecation of [`GetSigners`](https://github.com/cosmos/cosmos-sdk/issues/11275) we have the optionality to remove [sdk.Msg](https://github.com/cosmos/cosmos-sdk/blob/16a5404f8e00ddcf8857c8a55dca2f7c109c29bc/types/tx_msg.go#L16) and the `ValidateBasic` function. - -With the separation of CometBFT and Cosmos-SDK, there is a lack of control of what transactions get broadcasted and included in a block. This extra validation in the antehandler is meant to help in this case. In most cases the transaction is or should be simulated against a node for validation. With this flow transactions will be treated the same. - -## Proposal - -The acceptance of this RFC would move validation within `ValidateBasic` to the message server in modules, update tutorials and docs to remove mention of using `ValidateBasic` in favour of handling all validation for a message where it is executed. - -We can and will still support the `Validatebasic` function for users and provide an extension interface of the function once `sdk.Msg` is depreacted. - -> Note: This is how messages are handled in VMs like Ethereum and CosmWasm. - -### Consequences - -The consequence of updating the transaction flow is that transaction that may have failed before with the `ValidateBasic` flow will now be included in a block and fees charged. diff --git a/versioned_docs/version-0.50/build/rfc/rfc/rfc-template.md b/versioned_docs/version-0.50/build/rfc/rfc/rfc-template.md deleted file mode 100644 index 417a795d0..000000000 --- a/versioned_docs/version-0.50/build/rfc/rfc/rfc-template.md +++ /dev/null @@ -1,83 +0,0 @@ -# RFC {RFC-NUMBER}: {TITLE} - -## Changelog - -* {date}: {changelog} - -## Background - -> The next section is the "Background" section. This section should be at least two paragraphs and can take up to a whole -> page in some cases. The guiding goal of the background section is: as a newcomer to this project (new employee, team -> transfer), can I read the background section and follow any links to get the full context of why this change is -> necessary? -> -> If you can't show a random engineer the background section and have them acquire nearly full context on the necessity -> for the RFC, then the background section is not full enough. To help achieve this, link to prior RFCs, discussions, and -> more here as necessary to provide context so you don't have to simply repeat yourself. - - -## Proposal - -> The next required section is "Proposal" or "Goal". Given the background above, this section proposes a solution. -> This should be an overview of the "how" for the solution, but for details further sections will be used. - - -## Abandoned Ideas (Optional) - -> As RFCs evolve, it is common that there are ideas that are abandoned. Rather than simply deleting them from the -> document, you should try to organize them into sections that make it clear they're abandoned while explaining why they -> were abandoned. -> -> When sharing your RFC with others or having someone look back on your RFC in the future, it is common to walk the same -> path and fall into the same pitfalls that we've since matured from. Abandoned ideas are a way to recognize that path -> and explain the pitfalls and why they were abandoned. - -## Descision - -> This section describes alternative designs to the chosen design. This section -> is important and if an adr does not have any alternatives then it should be -> considered that the ADR was not thought through. - -## Consequences (optional) - -> This section describes the resulting context, after applying the decision. All -> consequences should be listed here, not just the "positive" ones. A particular -> decision may have positive, negative, and neutral consequences, but all of them -> affect the team and project in the future. - -### Backwards Compatibility - -> All ADRs that introduce backwards incompatibilities must include a section -> describing these incompatibilities and their severity. The ADR must explain -> how the author proposes to deal with these incompatibilities. ADR submissions -> without a sufficient backwards compatibility treatise may be rejected outright. - -### Positive - -> {positive consequences} - -### Negative - -> {negative consequences} - -### Neutral - -> {neutral consequences} - - - -### References - -> Links to external materials needed to follow the discussion may be added here. -> -> In addition, if the discussion in a request for comments leads to any design -> decisions, it may be helpful to add links to the ADR documents here after the -> discussion has settled. - -## Discussion - -> This section contains the core of the discussion. -> -> There is no fixed format for this section, but ideally changes to this -> section should be updated before merging to reflect any discussion that took -> place on the PR that made those changes. diff --git a/versioned_docs/version-0.50/learn/advanced/baseapp b/versioned_docs/version-0.50/learn/advanced/baseapp deleted file mode 100644 index e69de29bb..000000000 diff --git a/versioned_docs/version-0.50/learn/glossary.md b/versioned_docs/version-0.50/learn/glossary.md deleted file mode 100644 index 672d03adb..000000000 --- a/versioned_docs/version-0.50/learn/glossary.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -sidebar_position: 4 - ---- - -# Glossary - -## ABCI (Application Blockchain Interface) -The interface between the Tendermint consensus engine and the application state machine, allowing them to communicate and perform state transitions. ABCI is a critical component of the Cosmos SDK, enabling developers to build applications using any programming language that can communicate via ABCI. - -## ATOM -The native staking token of the Cosmos Hub, used for securing the network, participating in governance, and paying fees for transactions. - -## CometBFT -A Byzantine Fault Tolerant (BFT) consensus engine that powers the Cosmos SDK. CometBFT is responsible for handling the consensus and networking layers of a blockchain. - -## Cosmos Hub -The first blockchain built with the Cosmos SDK, functioning as a hub for connecting other blockchains in the Cosmos ecosystem through IBC. - -## Cosmos SDK -A framework for building blockchain applications, focusing on modularity, scalability, and interoperability. - -## CosmWasm -A smart contract engine for the Cosmos SDK that enables developers to write and deploy smart contracts in WebAssembly (Wasm). CosmWasm is designed to be secure, efficient, and easy to use, allowing developers to build complex applications on top of the Cosmos SDK. - -## Delegator -A participant in a Proof of Stake network who delegates their tokens to a validator. Delegators share in the rewards and risks associated with the validator's performance in the consensus process. - -## Gas -A measure of computational effort required to execute a transaction or smart contract on a blockchain. In the Cosmos ecosystem, gas is used to meter transactions and allocate resources fairly among users. Users must pay a gas fee, usually in the native token, to have their transactions processed by the network. - -## Governance -The decision-making process in the Cosmos ecosystem, which allows token holders to propose and vote on network upgrades, parameter changes, and other critical decisions. - -## IBC (Inter-Blockchain Communication) -A protocol for secure and reliable communication between heterogeneous blockchains built on the Cosmos SDK. IBC enables the transfer of tokens and data across multiple blockchains. - -## Interoperability -The ability of different blockchains and distributed systems to communicate and interact with each other, enabling the seamless transfer of information, tokens, and other digital assets. In the context of Cosmos, the Inter-Blockchain Communication (IBC) protocol is a core technology that enables interoperability between blockchains built with the Cosmos SDK and other compatible blockchains. Interoperability allows for increased collaboration, innovation, and value creation across different blockchain ecosystems. - -## Light Clients -Lightweight blockchain clients that verify and process only a small subset of the blockchain data, allowing users to interact with the network without downloading the entire blockchain. ABCI++ aims to enhance the security and performance of light clients by enabling them to efficiently verify state transitions and proofs. - -## Module -A self-contained, reusable piece of code that can be used to build blockchain functionality within a Cosmos SDK application. Modules can be developed by the community and shared for others to use. - -## Slashing -The process of penalizing validators or delegators by reducing their staked tokens if they behave maliciously or fail to meet the network's performance requirements. - -## Staking -The process of locking up tokens as collateral to secure the network, participate in consensus, and earn rewards in a Proof of Stake (PoS) blockchain like Cosmos. - -## State Sync -A feature that allows new nodes to quickly synchronize with the current state of the blockchain without downloading and processing all previous blocks. State Sync is particularly useful for nodes that have been offline for an extended period or are joining the network for the first time. ABCI++ aims to improve the efficiency and security of State Sync. - -## Validator -A network participant responsible for proposing new blocks, validating transactions, and securing the Cosmos SDK-based blockchain through staking tokens. Validators play a crucial role in maintaining the security and integrity of the network. \ No newline at end of file diff --git a/versioned_docs/version-0.50/tutorials/vote-extensions/auction-frontrunning/00-getting-started.md b/versioned_docs/version-0.50/tutorials/vote-extensions/auction-frontrunning/00-getting-started.md index 212f957da..a68a6e159 100644 --- a/versioned_docs/version-0.50/tutorials/vote-extensions/auction-frontrunning/00-getting-started.md +++ b/versioned_docs/version-0.50/tutorials/vote-extensions/auction-frontrunning/00-getting-started.md @@ -2,10 +2,10 @@ ## Table of Contents -* [Getting Started](#overview-of-the-project) -* [Understanding Front-Running](01-understanding-front-running) -* [Mitigating Front-running with Vote Extensions](02-mitigating-front-running-with-vote-extensions) -* [Demo of Mitigating Front-Running](03-demo-of-mitigating-front-running) +- [Getting Started](#overview-of-the-project) +- [Understanding Front-Running](./01-understanding-frontrunning.md) +- [Mitigating Front-running with Vote Extensions](./02-mitigating-front-running-with-vote-extesions.md) +- [Demo of Mitigating Front-Running](./03-demo-of-mitigating-front-running.md) ## Getting Started diff --git a/versioned_docs/version-0.50/tutorials/vote-extensions/auction-frontrunning/02-mitigating-front-running-with-vote-extensions.md.md b/versioned_docs/version-0.50/tutorials/vote-extensions/auction-frontrunning/02-mitigating-front-running-with-vote-extensions.md similarity index 100% rename from versioned_docs/version-0.50/tutorials/vote-extensions/auction-frontrunning/02-mitigating-front-running-with-vote-extensions.md.md rename to versioned_docs/version-0.50/tutorials/vote-extensions/auction-frontrunning/02-mitigating-front-running-with-vote-extensions.md diff --git a/versioned_docs/version-0.50/tutorials/vote-extensions/auction-frontrunning/03-demo-of-mitigating-front-running.md b/versioned_docs/version-0.50/tutorials/vote-extensions/auction-frontrunning/03-demo-of-mitigating-front-running.md index 48cf22a40..63f37b4ae 100644 --- a/versioned_docs/version-0.50/tutorials/vote-extensions/auction-frontrunning/03-demo-of-mitigating-front-running.md +++ b/versioned_docs/version-0.50/tutorials/vote-extensions/auction-frontrunning/03-demo-of-mitigating-front-running.md @@ -11,19 +11,19 @@ cd scripts configure.sh ``` -If this doesnt work please ensure you have run `make build` in the `tutorials/nameservice/base` directory. +If this doesn't work please ensure you have run `make build` in the `tutorials/nameservice/base` directory. 2. Have alice attempt to reserve `bob.cosmos`: This is a normal transaction that alice wants to execute. The script ``./scripts/reserve.sh "bob.cosmos"` is used to send this transaction. ```shell -bash reserve.sh "bob.cosmos" +reserve.sh "bob.cosmos" ``` 3. Query to verify the name has been reserved: This is to check the result of the transaction. The script `./scripts/whois.sh "bob.cosmos"` is used to query the state of the blockchain. ```shell -bash whois.sh "bob.cosmos" +whois.sh "bob.cosmos" ``` It should return: @@ -59,7 +59,7 @@ tail -f $HOME/cosmos/nodes/#{validator}/logs 4. List the Beacon's keys: This is to verify the addresses of the validators. The script `./scripts/list-beacon-keys.sh` is used to list the keys. ```shell -bash list-beacon-keys.sh +list-beacon-keys.sh ``` We should receive something similar to the following: diff --git a/versioned_docs/version-0.50/tutorials/vote-extensions/auction-frontrunning/_category_.json b/versioned_docs/version-0.50/tutorials/vote-extensions/auction-frontrunning/_category_.json index d949f628c..aab0cfdf6 100644 --- a/versioned_docs/version-0.50/tutorials/vote-extensions/auction-frontrunning/_category_.json +++ b/versioned_docs/version-0.50/tutorials/vote-extensions/auction-frontrunning/_category_.json @@ -1,5 +1,5 @@ { - "label": "Mitigating Auction Front-Running Tutorial", + "label": " Mitigating Auction Front-Running Tutorial", "position": 0, "link": null } \ No newline at end of file diff --git a/versioned_docs/version-0.50/tutorials/vote-extensions/oracle/00-getting-started.md b/versioned_docs/version-0.50/tutorials/vote-extensions/oracle/00-getting-started.md index c96886a64..59ea65be9 100644 --- a/versioned_docs/version-0.50/tutorials/vote-extensions/oracle/00-getting-started.md +++ b/versioned_docs/version-0.50/tutorials/vote-extensions/oracle/00-getting-started.md @@ -2,19 +2,18 @@ ## Table of Contents -- [Getting Started](00-getting-started.md) -- [What is an Oracle?](01-what-is-an-oracle.md) -- [Implementing Vote Extensions](02-implementing-vote-extensions.md) -- [Testing the Oracle Module](03-testing-oracle.md) +* [What is an Oracle?](./01-what-is-an-oracle.md) +* [Implementing Vote Extensions](./02-implementing-vote-extensions.md) +* [Testing the Oracle Module](./03-testing-oracle.md) ## Prerequisites Before you start with this tutorial, make sure you have: -- A working chain project. This tutorial won't cover the steps of creating a new chain/module. -- Familiarity with the Cosmos SDK. If you're not, we suggest you start with [Cosmos SDK Tutorials](https://tutorials.cosmos.network), as ABCI++ is considered an advanced topic. -- Read and understood [What is an Oracle?](01-what-is-an-oracle.md). This provides necessary background information for understanding the Oracle module. -- Basic understanding of Go programming language. +* A working chain project. This tutorial won't cover the steps of creating a new chain/module. +* Familiarity with the Cosmos SDK. If you're not, we suggest you start with [Cosmos SDK Tutorials](https://tutorials.cosmos.network), as ABCI++ is considered an advanced topic. +* Read and understood [What is an Oracle?](01-what-is-an-oracle.md). This provides necessary background information for understanding the Oracle module. +* Basic understanding of Go programming language. ## What are Vote extensions? @@ -28,8 +27,10 @@ We’ll go through the creation of a simple price oracle module focusing on the We’ll go through the implementation of: -- `ExtendVote` to get information from external price APIs. -- `VerifyVoteExtension` to check that the format of the provided votes is correct. -- `PrepareProposal` to process the vote extensions from the previous block and include them into the proposal as a transaction. -- `ProcessProposal` to check that the first transaction in the proposal is actually a “special tx” that contains the price information. -- `PreBlocker` to make price information available during FinalizeBlock. +* `ExtendVote` to get information from external price APIs. +* `VerifyVoteExtension` to check that the format of the provided votes is correct. +* `PrepareProposal` to process the vote extensions from the previous block and include them into the proposal as a transaction. +* `ProcessProposal` to check that the first transaction in the proposal is actually a “special tx” that contains the price information. +* `PreBlocker` to make price information available during FinalizeBlock. + +If you would like to see the complete working oracle module please see [here](https://github.com/cosmos/sdk-tutorials/blob/master/tutorials/oracle/base/x/oracle) diff --git a/versioned_docs/version-0.50/tutorials/vote-extensions/oracle/02-implementing-vote-extensions.md b/versioned_docs/version-0.50/tutorials/vote-extensions/oracle/02-implementing-vote-extensions.md index 0a33e11f6..aa610b5d3 100644 --- a/versioned_docs/version-0.50/tutorials/vote-extensions/oracle/02-implementing-vote-extensions.md +++ b/versioned_docs/version-0.50/tutorials/vote-extensions/oracle/02-implementing-vote-extensions.md @@ -52,7 +52,7 @@ func (h *VoteExtHandler) ExtendVoteHandler() sdk.ExtendVoteHandler { } ``` -As you can see above, the creation of a vote extension is pretty simple and we just have to return bytes. CometBFT will handle the signing of these bytes for us. We ignored the process of getting the prices but you can see a more complete example [here:](../base/x/oracle/abci/vote_extensions.go) +As you can see above, the creation of a vote extension is pretty simple and we just have to return bytes. CometBFT will handle the signing of these bytes for us. We ignored the process of getting the prices but you can see a more complete example [here:](https://github.com/cosmos/sdk-tutorials/blob/master/tutorials/oracle/base/x/oracle/abci/vote_extensions.go) Here we’ll do some simple checks like: @@ -104,7 +104,7 @@ type StakeWeightedPrices struct { } ``` -Now we create the `PrepareProposalHandler`. In this step we’ll first check if the vote extensions’ signatures are correct using a helper function called ValidateVoteExtensions from the baseapp pacakge. +Now we create the `PrepareProposalHandler`. In this step we’ll first check if the vote extensions’ signatures are correct using a helper function called ValidateVoteExtensions from the baseapp package. ```go func (h *ProposalHandler) PrepareProposal() sdk.PrepareProposalHandler { diff --git a/versioned_docs/version-0.50/tutorials/vote-extensions/oracle/03-testing-oracle.md b/versioned_docs/version-0.50/tutorials/vote-extensions/oracle/03-testing-oracle.md index 859b9518e..905ca0d74 100644 --- a/versioned_docs/version-0.50/tutorials/vote-extensions/oracle/03-testing-oracle.md +++ b/versioned_docs/version-0.50/tutorials/vote-extensions/oracle/03-testing-oracle.md @@ -1,13 +1,13 @@ # Testing the Oracle Module -We will guide you through the process of testing the Oracle module in your application. The Oracle module uses vote extensions to provide current price data. +We will guide you through the process of testing the Oracle module in your application. The Oracle module uses vote extensions to provide current price data. If you would like to see the complete working oracle module please see [here](https://github.com/cosmos/sdk-tutorials/blob/master/tutorials/oracle/base/x/oracle). ## Step 1: Compile and Install the Application First, we need to compile and install the application. Please ensure you are in the `tutorials/oracle/base` directory. Run the following command in your terminal: ```shell -bash make install +make install ``` This command compiles the application and moves the resulting binary to a location in your system's PATH. @@ -17,7 +17,7 @@ This command compiles the application and moves the resulting binary to a locati Next, we need to initialise the application. Run the following command in your terminal: ```shell -bash make init +make init ``` This command runs the script `tutorials/oracle/base/scripts/init.sh`, which sets up the necessary configuration for your application to run. This includes creating the `app.toml` configuration file and initialising the blockchain with a genesis block. @@ -27,7 +27,7 @@ This command runs the script `tutorials/oracle/base/scripts/init.sh`, which sets Now, we can start the application. Run the following command in your terminal: ```shell -tutoriald start +exampled start ``` This command starts your application, begins the blockchain node, and starts processing transactions. @@ -37,7 +37,7 @@ This command starts your application, begins the blockchain node, and starts pro Finally, we can query the current prices from the Oracle module. Run the following command in your terminal: ```shell -bash tutoriald q oracle prices +exampled q oracle prices ``` This command queries the current prices from the Oracle module. The expected output shows that the vote extensions were successfully included in the block and the Oracle module was able to retrieve the price data. diff --git a/versioned_docs/version-0.50/user/run-node/01-run-node.md b/versioned_docs/version-0.50/user/run-node/01-run-node.md index 9b1dfb4eb..f16eb42f5 100644 --- a/versioned_docs/version-0.50/user/run-node/01-run-node.md +++ b/versioned_docs/version-0.50/user/run-node/01-run-node.md @@ -166,26 +166,16 @@ and set `rpc.laddr` in `config.toml` to the CometBFT node's RPC address. ## Logging -Logging provides a way to see what is going on with a node. By default the `info` level is set. This is a global level and all info logs will be outputted to the terminal. +Logging provides a way to see what is going on with a node. By default the info level is set. This is a global level and all info logs will be outputted to the terminal. If you would like to filter specific logs to the terminal instead of all, then setting `module:log_level` is how this can work. -If you would like to filter specific logs to the terminal instead of all, then setting `:` is how this can work. Example: -In `config.toml`: +In config.toml: ```toml -log_level: "state:info,p2p:info,consensus:info,x/staking:info,x/ibc:info,*:error" +log_level: "state:info,p2p:info,consensus:info,x/staking:info,x/ibc:info,*error" ``` -Or directly in the command line: - -```bash - start --log_level "state:info,p2p:info,consensus:info,x/staking:info,x/ibc:info,*:error" -``` - -The above will show info logs for the state, p2p, consensus, staking, and ibc modules, and error logs for all other modules. -When no log filtering is required, simply use one of the supported global log levels: `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `panic` or `disabled`. - ## State Sync State sync is the act in which a node syncs the latest or close to the latest state of a blockchain. This is useful for users who don't want to sync all the blocks in history. Read more in [CometBFT documentation](https://docs.cometbft.com/v0.37/core/state-sync). diff --git a/versioned_docs/version-0.50/user/run-node/06-run-production.md b/versioned_docs/version-0.50/user/run-node/06-run-production.md index 807ceea56..31d2932e0 100644 --- a/versioned_docs/version-0.50/user/run-node/06-run-production.md +++ b/versioned_docs/version-0.50/user/run-node/06-run-production.md @@ -238,11 +238,11 @@ reconnect = true ```bash vim $HOME/.simd/config/config.toml -priv_validator_laddr = "tcp://127.0.0.1:26659" +priv_validator_laddr = "tcp://0.0.0.0:26659" ``` :::tip -The above address it set to `127.0.0.1` but it is recommended to set the tmkms server to secure the startup +The above address it set to `0.0.0.0` but it is recommended to set the tmkms server to secure the startup ::: :::tip diff --git a/versioned_docs/version-0.50/user/run-node/_category_.json b/versioned_docs/version-0.50/user/run-node/_category_.json index 7fcac509a..65e64b945 100644 --- a/versioned_docs/version-0.50/user/run-node/_category_.json +++ b/versioned_docs/version-0.50/user/run-node/_category_.json @@ -1,5 +1,5 @@ { "label": "Running a Node, API and CLI", - "position": 1, + "position": 0, "link": null } \ No newline at end of file diff --git a/versioned_docs/version-0.52/build/_category_.json b/versioned_docs/version-0.52/build/_category_.json new file mode 100644 index 000000000..9f3088236 --- /dev/null +++ b/versioned_docs/version-0.52/build/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Build", + "position": 0, + "link": null +} \ No newline at end of file diff --git a/versioned_docs/version-0.52/abci/00-introduction.md b/versioned_docs/version-0.52/build/abci/00-introduction.md similarity index 100% rename from versioned_docs/version-0.52/abci/00-introduction.md rename to versioned_docs/version-0.52/build/abci/00-introduction.md diff --git a/versioned_docs/version-0.52/abci/01-prepare-proposal.md b/versioned_docs/version-0.52/build/abci/01-prepare-proposal.md similarity index 100% rename from versioned_docs/version-0.52/abci/01-prepare-proposal.md rename to versioned_docs/version-0.52/build/abci/01-prepare-proposal.md diff --git a/versioned_docs/version-0.52/abci/02-process-proposal.md b/versioned_docs/version-0.52/build/abci/02-process-proposal.md similarity index 100% rename from versioned_docs/version-0.52/abci/02-process-proposal.md rename to versioned_docs/version-0.52/build/abci/02-process-proposal.md diff --git a/versioned_docs/version-0.52/abci/03-vote-extensions.md b/versioned_docs/version-0.52/build/abci/03-vote-extensions.md similarity index 100% rename from versioned_docs/version-0.52/abci/03-vote-extensions.md rename to versioned_docs/version-0.52/build/abci/03-vote-extensions.md diff --git a/versioned_docs/version-0.52/abci/04-checktx.md b/versioned_docs/version-0.52/build/abci/04-checktx.md similarity index 100% rename from versioned_docs/version-0.52/abci/04-checktx.md rename to versioned_docs/version-0.52/build/abci/04-checktx.md diff --git a/versioned_docs/version-0.52/abci/_category_.json b/versioned_docs/version-0.52/build/abci/_category_.json similarity index 100% rename from versioned_docs/version-0.52/abci/_category_.json rename to versioned_docs/version-0.52/build/abci/_category_.json diff --git a/versioned_docs/version-0.52/architecture/PROCESS.md b/versioned_docs/version-0.52/build/architecture/PROCESS.md similarity index 100% rename from versioned_docs/version-0.52/architecture/PROCESS.md rename to versioned_docs/version-0.52/build/architecture/PROCESS.md diff --git a/versioned_docs/version-0.52/architecture/README.md b/versioned_docs/version-0.52/build/architecture/README.md similarity index 100% rename from versioned_docs/version-0.52/architecture/README.md rename to versioned_docs/version-0.52/build/architecture/README.md diff --git a/versioned_docs/version-0.52/architecture/_category_.json b/versioned_docs/version-0.52/build/architecture/_category_.json similarity index 100% rename from versioned_docs/version-0.52/architecture/_category_.json rename to versioned_docs/version-0.52/build/architecture/_category_.json diff --git a/versioned_docs/version-0.52/architecture/adr-002-docs-structure.md b/versioned_docs/version-0.52/build/architecture/adr-002-docs-structure.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-002-docs-structure.md rename to versioned_docs/version-0.52/build/architecture/adr-002-docs-structure.md diff --git a/versioned_docs/version-0.52/architecture/adr-003-dynamic-capability-store.md b/versioned_docs/version-0.52/build/architecture/adr-003-dynamic-capability-store.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-003-dynamic-capability-store.md rename to versioned_docs/version-0.52/build/architecture/adr-003-dynamic-capability-store.md diff --git a/versioned_docs/version-0.52/architecture/adr-004-split-denomination-keys.md b/versioned_docs/version-0.52/build/architecture/adr-004-split-denomination-keys.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-004-split-denomination-keys.md rename to versioned_docs/version-0.52/build/architecture/adr-004-split-denomination-keys.md diff --git a/versioned_docs/version-0.52/architecture/adr-006-secret-store-replacement.md b/versioned_docs/version-0.52/build/architecture/adr-006-secret-store-replacement.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-006-secret-store-replacement.md rename to versioned_docs/version-0.52/build/architecture/adr-006-secret-store-replacement.md diff --git a/versioned_docs/version-0.52/architecture/adr-007-specialization-groups.md b/versioned_docs/version-0.52/build/architecture/adr-007-specialization-groups.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-007-specialization-groups.md rename to versioned_docs/version-0.52/build/architecture/adr-007-specialization-groups.md diff --git a/versioned_docs/version-0.52/architecture/adr-008-dCERT-group.md b/versioned_docs/version-0.52/build/architecture/adr-008-dCERT-group.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-008-dCERT-group.md rename to versioned_docs/version-0.52/build/architecture/adr-008-dCERT-group.md diff --git a/versioned_docs/version-0.52/architecture/adr-009-evidence-module.md b/versioned_docs/version-0.52/build/architecture/adr-009-evidence-module.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-009-evidence-module.md rename to versioned_docs/version-0.52/build/architecture/adr-009-evidence-module.md diff --git a/versioned_docs/version-0.52/architecture/adr-010-modular-antehandler.md b/versioned_docs/version-0.52/build/architecture/adr-010-modular-antehandler.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-010-modular-antehandler.md rename to versioned_docs/version-0.52/build/architecture/adr-010-modular-antehandler.md diff --git a/versioned_docs/version-0.52/architecture/adr-011-generalize-genesis-accounts.md b/versioned_docs/version-0.52/build/architecture/adr-011-generalize-genesis-accounts.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-011-generalize-genesis-accounts.md rename to versioned_docs/version-0.52/build/architecture/adr-011-generalize-genesis-accounts.md diff --git a/versioned_docs/version-0.52/architecture/adr-012-state-accessors.md b/versioned_docs/version-0.52/build/architecture/adr-012-state-accessors.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-012-state-accessors.md rename to versioned_docs/version-0.52/build/architecture/adr-012-state-accessors.md diff --git a/versioned_docs/version-0.52/architecture/adr-013-metrics.md b/versioned_docs/version-0.52/build/architecture/adr-013-metrics.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-013-metrics.md rename to versioned_docs/version-0.52/build/architecture/adr-013-metrics.md diff --git a/versioned_docs/version-0.52/architecture/adr-014-proportional-slashing.md b/versioned_docs/version-0.52/build/architecture/adr-014-proportional-slashing.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-014-proportional-slashing.md rename to versioned_docs/version-0.52/build/architecture/adr-014-proportional-slashing.md diff --git a/versioned_docs/version-0.52/architecture/adr-016-validator-consensus-key-rotation.md b/versioned_docs/version-0.52/build/architecture/adr-016-validator-consensus-key-rotation.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-016-validator-consensus-key-rotation.md rename to versioned_docs/version-0.52/build/architecture/adr-016-validator-consensus-key-rotation.md diff --git a/versioned_docs/version-0.52/architecture/adr-017-historical-header-module.md b/versioned_docs/version-0.52/build/architecture/adr-017-historical-header-module.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-017-historical-header-module.md rename to versioned_docs/version-0.52/build/architecture/adr-017-historical-header-module.md diff --git a/versioned_docs/version-0.52/architecture/adr-018-extendable-voting-period.md b/versioned_docs/version-0.52/build/architecture/adr-018-extendable-voting-period.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-018-extendable-voting-period.md rename to versioned_docs/version-0.52/build/architecture/adr-018-extendable-voting-period.md diff --git a/versioned_docs/version-0.52/architecture/adr-019-protobuf-state-encoding.md b/versioned_docs/version-0.52/build/architecture/adr-019-protobuf-state-encoding.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-019-protobuf-state-encoding.md rename to versioned_docs/version-0.52/build/architecture/adr-019-protobuf-state-encoding.md diff --git a/versioned_docs/version-0.52/architecture/adr-020-protobuf-transaction-encoding.md b/versioned_docs/version-0.52/build/architecture/adr-020-protobuf-transaction-encoding.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-020-protobuf-transaction-encoding.md rename to versioned_docs/version-0.52/build/architecture/adr-020-protobuf-transaction-encoding.md diff --git a/versioned_docs/version-0.52/architecture/adr-021-protobuf-query-encoding.md b/versioned_docs/version-0.52/build/architecture/adr-021-protobuf-query-encoding.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-021-protobuf-query-encoding.md rename to versioned_docs/version-0.52/build/architecture/adr-021-protobuf-query-encoding.md diff --git a/versioned_docs/version-0.52/architecture/adr-022-custom-panic-handling.md b/versioned_docs/version-0.52/build/architecture/adr-022-custom-panic-handling.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-022-custom-panic-handling.md rename to versioned_docs/version-0.52/build/architecture/adr-022-custom-panic-handling.md diff --git a/versioned_docs/version-0.52/architecture/adr-023-protobuf-naming.md b/versioned_docs/version-0.52/build/architecture/adr-023-protobuf-naming.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-023-protobuf-naming.md rename to versioned_docs/version-0.52/build/architecture/adr-023-protobuf-naming.md diff --git a/versioned_docs/version-0.52/architecture/adr-024-coin-metadata.md b/versioned_docs/version-0.52/build/architecture/adr-024-coin-metadata.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-024-coin-metadata.md rename to versioned_docs/version-0.52/build/architecture/adr-024-coin-metadata.md diff --git a/versioned_docs/version-0.52/architecture/adr-027-deterministic-protobuf-serialization.md b/versioned_docs/version-0.52/build/architecture/adr-027-deterministic-protobuf-serialization.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-027-deterministic-protobuf-serialization.md rename to versioned_docs/version-0.52/build/architecture/adr-027-deterministic-protobuf-serialization.md diff --git a/versioned_docs/version-0.52/architecture/adr-028-public-key-addresses.md b/versioned_docs/version-0.52/build/architecture/adr-028-public-key-addresses.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-028-public-key-addresses.md rename to versioned_docs/version-0.52/build/architecture/adr-028-public-key-addresses.md diff --git a/versioned_docs/version-0.52/architecture/adr-029-fee-grant-module.md b/versioned_docs/version-0.52/build/architecture/adr-029-fee-grant-module.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-029-fee-grant-module.md rename to versioned_docs/version-0.52/build/architecture/adr-029-fee-grant-module.md diff --git a/versioned_docs/version-0.52/architecture/adr-030-authz-module.md b/versioned_docs/version-0.52/build/architecture/adr-030-authz-module.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-030-authz-module.md rename to versioned_docs/version-0.52/build/architecture/adr-030-authz-module.md diff --git a/versioned_docs/version-0.52/architecture/adr-031-msg-service.md b/versioned_docs/version-0.52/build/architecture/adr-031-msg-service.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-031-msg-service.md rename to versioned_docs/version-0.52/build/architecture/adr-031-msg-service.md diff --git a/versioned_docs/version-0.52/architecture/adr-032-typed-events.md b/versioned_docs/version-0.52/build/architecture/adr-032-typed-events.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-032-typed-events.md rename to versioned_docs/version-0.52/build/architecture/adr-032-typed-events.md diff --git a/versioned_docs/version-0.52/architecture/adr-033-protobuf-inter-module-comm.md b/versioned_docs/version-0.52/build/architecture/adr-033-protobuf-inter-module-comm.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-033-protobuf-inter-module-comm.md rename to versioned_docs/version-0.52/build/architecture/adr-033-protobuf-inter-module-comm.md diff --git a/versioned_docs/version-0.52/architecture/adr-034-account-rekeying.md b/versioned_docs/version-0.52/build/architecture/adr-034-account-rekeying.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-034-account-rekeying.md rename to versioned_docs/version-0.52/build/architecture/adr-034-account-rekeying.md diff --git a/versioned_docs/version-0.52/architecture/adr-035-rosetta-api-support.md b/versioned_docs/version-0.52/build/architecture/adr-035-rosetta-api-support.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-035-rosetta-api-support.md rename to versioned_docs/version-0.52/build/architecture/adr-035-rosetta-api-support.md diff --git a/versioned_docs/version-0.52/architecture/adr-036-arbitrary-signature.md b/versioned_docs/version-0.52/build/architecture/adr-036-arbitrary-signature.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-036-arbitrary-signature.md rename to versioned_docs/version-0.52/build/architecture/adr-036-arbitrary-signature.md diff --git a/versioned_docs/version-0.52/architecture/adr-037-gov-split-vote.md b/versioned_docs/version-0.52/build/architecture/adr-037-gov-split-vote.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-037-gov-split-vote.md rename to versioned_docs/version-0.52/build/architecture/adr-037-gov-split-vote.md diff --git a/versioned_docs/version-0.52/architecture/adr-038-state-listening.md b/versioned_docs/version-0.52/build/architecture/adr-038-state-listening.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-038-state-listening.md rename to versioned_docs/version-0.52/build/architecture/adr-038-state-listening.md diff --git a/versioned_docs/version-0.52/architecture/adr-039-epoched-staking.md b/versioned_docs/version-0.52/build/architecture/adr-039-epoched-staking.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-039-epoched-staking.md rename to versioned_docs/version-0.52/build/architecture/adr-039-epoched-staking.md diff --git a/versioned_docs/version-0.52/architecture/adr-040-storage-and-smt-state-commitments.md b/versioned_docs/version-0.52/build/architecture/adr-040-storage-and-smt-state-commitments.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-040-storage-and-smt-state-commitments.md rename to versioned_docs/version-0.52/build/architecture/adr-040-storage-and-smt-state-commitments.md diff --git a/versioned_docs/version-0.52/architecture/adr-041-in-place-store-migrations.md b/versioned_docs/version-0.52/build/architecture/adr-041-in-place-store-migrations.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-041-in-place-store-migrations.md rename to versioned_docs/version-0.52/build/architecture/adr-041-in-place-store-migrations.md diff --git a/versioned_docs/version-0.52/architecture/adr-042-group-module.md b/versioned_docs/version-0.52/build/architecture/adr-042-group-module.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-042-group-module.md rename to versioned_docs/version-0.52/build/architecture/adr-042-group-module.md diff --git a/versioned_docs/version-0.52/architecture/adr-043-nft-module.md b/versioned_docs/version-0.52/build/architecture/adr-043-nft-module.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-043-nft-module.md rename to versioned_docs/version-0.52/build/architecture/adr-043-nft-module.md diff --git a/versioned_docs/version-0.52/architecture/adr-044-protobuf-updates-guidelines.md b/versioned_docs/version-0.52/build/architecture/adr-044-protobuf-updates-guidelines.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-044-protobuf-updates-guidelines.md rename to versioned_docs/version-0.52/build/architecture/adr-044-protobuf-updates-guidelines.md diff --git a/versioned_docs/version-0.52/architecture/adr-045-check-delivertx-middlewares.md b/versioned_docs/version-0.52/build/architecture/adr-045-check-delivertx-middlewares.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-045-check-delivertx-middlewares.md rename to versioned_docs/version-0.52/build/architecture/adr-045-check-delivertx-middlewares.md diff --git a/versioned_docs/version-0.52/architecture/adr-046-module-params.md b/versioned_docs/version-0.52/build/architecture/adr-046-module-params.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-046-module-params.md rename to versioned_docs/version-0.52/build/architecture/adr-046-module-params.md diff --git a/versioned_docs/version-0.52/architecture/adr-047-extend-upgrade-plan.md b/versioned_docs/version-0.52/build/architecture/adr-047-extend-upgrade-plan.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-047-extend-upgrade-plan.md rename to versioned_docs/version-0.52/build/architecture/adr-047-extend-upgrade-plan.md diff --git a/versioned_docs/version-0.52/architecture/adr-048-consensus-fees.md b/versioned_docs/version-0.52/build/architecture/adr-048-consensus-fees.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-048-consensus-fees.md rename to versioned_docs/version-0.52/build/architecture/adr-048-consensus-fees.md diff --git a/versioned_docs/version-0.52/architecture/adr-049-state-sync-hooks.md b/versioned_docs/version-0.52/build/architecture/adr-049-state-sync-hooks.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-049-state-sync-hooks.md rename to versioned_docs/version-0.52/build/architecture/adr-049-state-sync-hooks.md diff --git a/versioned_docs/version-0.52/architecture/adr-050-sign-mode-textual-annex1.md b/versioned_docs/version-0.52/build/architecture/adr-050-sign-mode-textual-annex1.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-050-sign-mode-textual-annex1.md rename to versioned_docs/version-0.52/build/architecture/adr-050-sign-mode-textual-annex1.md diff --git a/versioned_docs/version-0.52/architecture/adr-050-sign-mode-textual-annex2.md b/versioned_docs/version-0.52/build/architecture/adr-050-sign-mode-textual-annex2.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-050-sign-mode-textual-annex2.md rename to versioned_docs/version-0.52/build/architecture/adr-050-sign-mode-textual-annex2.md diff --git a/versioned_docs/version-0.52/architecture/adr-050-sign-mode-textual.md b/versioned_docs/version-0.52/build/architecture/adr-050-sign-mode-textual.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-050-sign-mode-textual.md rename to versioned_docs/version-0.52/build/architecture/adr-050-sign-mode-textual.md diff --git a/versioned_docs/version-0.52/architecture/adr-053-go-module-refactoring.md b/versioned_docs/version-0.52/build/architecture/adr-053-go-module-refactoring.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-053-go-module-refactoring.md rename to versioned_docs/version-0.52/build/architecture/adr-053-go-module-refactoring.md diff --git a/versioned_docs/version-0.52/architecture/adr-054-semver-compatible-modules.md b/versioned_docs/version-0.52/build/architecture/adr-054-semver-compatible-modules.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-054-semver-compatible-modules.md rename to versioned_docs/version-0.52/build/architecture/adr-054-semver-compatible-modules.md diff --git a/versioned_docs/version-0.52/architecture/adr-055-orm.md b/versioned_docs/version-0.52/build/architecture/adr-055-orm.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-055-orm.md rename to versioned_docs/version-0.52/build/architecture/adr-055-orm.md diff --git a/versioned_docs/version-0.52/architecture/adr-057-app-wiring.md b/versioned_docs/version-0.52/build/architecture/adr-057-app-wiring.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-057-app-wiring.md rename to versioned_docs/version-0.52/build/architecture/adr-057-app-wiring.md diff --git a/versioned_docs/version-0.52/architecture/adr-058-auto-generated-cli.md b/versioned_docs/version-0.52/build/architecture/adr-058-auto-generated-cli.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-058-auto-generated-cli.md rename to versioned_docs/version-0.52/build/architecture/adr-058-auto-generated-cli.md diff --git a/versioned_docs/version-0.52/architecture/adr-059-test-scopes.md b/versioned_docs/version-0.52/build/architecture/adr-059-test-scopes.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-059-test-scopes.md rename to versioned_docs/version-0.52/build/architecture/adr-059-test-scopes.md diff --git a/versioned_docs/version-0.52/architecture/adr-060-abci-1.0.md b/versioned_docs/version-0.52/build/architecture/adr-060-abci-1.0.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-060-abci-1.0.md rename to versioned_docs/version-0.52/build/architecture/adr-060-abci-1.0.md diff --git a/versioned_docs/version-0.52/architecture/adr-061-liquid-staking.md b/versioned_docs/version-0.52/build/architecture/adr-061-liquid-staking.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-061-liquid-staking.md rename to versioned_docs/version-0.52/build/architecture/adr-061-liquid-staking.md diff --git a/versioned_docs/version-0.52/architecture/adr-062-collections-state-layer.md b/versioned_docs/version-0.52/build/architecture/adr-062-collections-state-layer.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-062-collections-state-layer.md rename to versioned_docs/version-0.52/build/architecture/adr-062-collections-state-layer.md diff --git a/versioned_docs/version-0.52/architecture/adr-063-core-module-api.md b/versioned_docs/version-0.52/build/architecture/adr-063-core-module-api.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-063-core-module-api.md rename to versioned_docs/version-0.52/build/architecture/adr-063-core-module-api.md diff --git a/versioned_docs/version-0.52/architecture/adr-064-abci-2.0.md b/versioned_docs/version-0.52/build/architecture/adr-064-abci-2.0.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-064-abci-2.0.md rename to versioned_docs/version-0.52/build/architecture/adr-064-abci-2.0.md diff --git a/versioned_docs/version-0.52/architecture/adr-065-store-v2.md b/versioned_docs/version-0.52/build/architecture/adr-065-store-v2.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-065-store-v2.md rename to versioned_docs/version-0.52/build/architecture/adr-065-store-v2.md diff --git a/versioned_docs/version-0.52/architecture/adr-067-simulator-v2.md b/versioned_docs/version-0.52/build/architecture/adr-067-simulator-v2.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-067-simulator-v2.md rename to versioned_docs/version-0.52/build/architecture/adr-067-simulator-v2.md diff --git a/versioned_docs/version-0.52/architecture/adr-068-preblock.md b/versioned_docs/version-0.52/build/architecture/adr-068-preblock.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-068-preblock.md rename to versioned_docs/version-0.52/build/architecture/adr-068-preblock.md diff --git a/versioned_docs/version-0.52/architecture/adr-069-gov-improvements.md b/versioned_docs/version-0.52/build/architecture/adr-069-gov-improvements.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-069-gov-improvements.md rename to versioned_docs/version-0.52/build/architecture/adr-069-gov-improvements.md diff --git a/versioned_docs/version-0.52/architecture/adr-070-unordered-transactions.md b/versioned_docs/version-0.52/build/architecture/adr-070-unordered-transactions.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-070-unordered-transactions.md rename to versioned_docs/version-0.52/build/architecture/adr-070-unordered-transactions.md diff --git a/versioned_docs/version-0.52/architecture/adr-073-indexer.md b/versioned_docs/version-0.52/build/architecture/adr-073-indexer.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-073-indexer.md rename to versioned_docs/version-0.52/build/architecture/adr-073-indexer.md diff --git a/versioned_docs/version-0.52/architecture/adr-074-implicit-msg-signers.md b/versioned_docs/version-0.52/build/architecture/adr-074-implicit-msg-signers.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-074-implicit-msg-signers.md rename to versioned_docs/version-0.52/build/architecture/adr-074-implicit-msg-signers.md diff --git a/versioned_docs/version-0.52/architecture/adr-template.md b/versioned_docs/version-0.52/build/architecture/adr-template.md similarity index 100% rename from versioned_docs/version-0.52/architecture/adr-template.md rename to versioned_docs/version-0.52/build/architecture/adr-template.md diff --git a/versioned_docs/version-0.52/build/build.md b/versioned_docs/version-0.52/build/build.md new file mode 100644 index 000000000..3b86eb472 --- /dev/null +++ b/versioned_docs/version-0.52/build/build.md @@ -0,0 +1,13 @@ +--- +sidebar_position: 0 +--- + +# Build + +* [Building Apps](./building-apps/00-app-go.md) - The documentation in this section will guide you through the process of developing your dApp using the Cosmos SDK framework. +* [Modules](./modules/README.md) - Information about the various modules available in the Cosmos SDK: Auth, Authz, Bank, Crisis, Distribution, Evidence, Feegrant, Governance, Mint, Params, Slashing, Staking, Upgrade, NFT, Consensus, Circuit, Genutil. +* [Migrations](./migrations/01-intro.md) - See what has been updated in each release the process of the transition between versions. +* [Packages](./packages/README.md) - Explore a curated collection of pre-built modules and functionalities, streamlining the development process. +* [Tooling](./tooling/README.md) - A suite of utilities designed to enhance the development workflow, optimizing the efficiency of Cosmos SDK-based projects. +* [ADR's](./architecture/README.md) - Provides a structured repository of key decisions made during the development process, which have been documented and offers rationale behind key decisions being made. +* [REST API](https://docs.cosmos.network/api) - A comprehensive reference for the application programming interfaces (APIs) provided by the SDK. diff --git a/versioned_docs/version-0.52/building-apps/00-app-go.md b/versioned_docs/version-0.52/build/building-apps/00-app-go.md similarity index 100% rename from versioned_docs/version-0.52/building-apps/00-app-go.md rename to versioned_docs/version-0.52/build/building-apps/00-app-go.md diff --git a/versioned_docs/version-0.52/building-apps/01-app-go-v2.md b/versioned_docs/version-0.52/build/building-apps/01-app-go-v2.md similarity index 100% rename from versioned_docs/version-0.52/building-apps/01-app-go-v2.md rename to versioned_docs/version-0.52/build/building-apps/01-app-go-v2.md diff --git a/versioned_docs/version-0.52/building-apps/02-app-mempool.md b/versioned_docs/version-0.52/build/building-apps/02-app-mempool.md similarity index 100% rename from versioned_docs/version-0.52/building-apps/02-app-mempool.md rename to versioned_docs/version-0.52/build/building-apps/02-app-mempool.md diff --git a/versioned_docs/version-0.52/building-apps/03-app-upgrade.md b/versioned_docs/version-0.52/build/building-apps/03-app-upgrade.md similarity index 100% rename from versioned_docs/version-0.52/building-apps/03-app-upgrade.md rename to versioned_docs/version-0.52/build/building-apps/03-app-upgrade.md diff --git a/versioned_docs/version-0.52/building-apps/04-security-part-1.md b/versioned_docs/version-0.52/build/building-apps/04-security-part-1.md similarity index 100% rename from versioned_docs/version-0.52/building-apps/04-security-part-1.md rename to versioned_docs/version-0.52/build/building-apps/04-security-part-1.md diff --git a/versioned_docs/version-0.52/building-apps/05-app-testnet.md b/versioned_docs/version-0.52/build/building-apps/05-app-testnet.md similarity index 100% rename from versioned_docs/version-0.52/building-apps/05-app-testnet.md rename to versioned_docs/version-0.52/build/building-apps/05-app-testnet.md diff --git a/versioned_docs/version-0.52/building-apps/06-app-go-genesis.md b/versioned_docs/version-0.52/build/building-apps/06-app-go-genesis.md similarity index 100% rename from versioned_docs/version-0.52/building-apps/06-app-go-genesis.md rename to versioned_docs/version-0.52/build/building-apps/06-app-go-genesis.md diff --git a/versioned_docs/version-0.52/building-apps/06-system-tests.md b/versioned_docs/version-0.52/build/building-apps/06-system-tests.md similarity index 100% rename from versioned_docs/version-0.52/building-apps/06-system-tests.md rename to versioned_docs/version-0.52/build/building-apps/06-system-tests.md diff --git a/versioned_docs/version-0.52/building-apps/_category_.json b/versioned_docs/version-0.52/build/building-apps/_category_.json similarity index 100% rename from versioned_docs/version-0.52/building-apps/_category_.json rename to versioned_docs/version-0.52/build/building-apps/_category_.json diff --git a/versioned_docs/version-0.52/building-modules/00-intro.md b/versioned_docs/version-0.52/build/building-modules/00-intro.md similarity index 100% rename from versioned_docs/version-0.52/building-modules/00-intro.md rename to versioned_docs/version-0.52/build/building-modules/00-intro.md diff --git a/versioned_docs/version-0.52/building-modules/01-module-manager.md b/versioned_docs/version-0.52/build/building-modules/01-module-manager.md similarity index 100% rename from versioned_docs/version-0.52/building-modules/01-module-manager.md rename to versioned_docs/version-0.52/build/building-modules/01-module-manager.md diff --git a/versioned_docs/version-0.52/building-modules/02-messages-and-queries.md b/versioned_docs/version-0.52/build/building-modules/02-messages-and-queries.md similarity index 100% rename from versioned_docs/version-0.52/building-modules/02-messages-and-queries.md rename to versioned_docs/version-0.52/build/building-modules/02-messages-and-queries.md diff --git a/versioned_docs/version-0.52/building-modules/03-msg-services.md b/versioned_docs/version-0.52/build/building-modules/03-msg-services.md similarity index 100% rename from versioned_docs/version-0.52/building-modules/03-msg-services.md rename to versioned_docs/version-0.52/build/building-modules/03-msg-services.md diff --git a/versioned_docs/version-0.52/building-modules/04-query-services.md b/versioned_docs/version-0.52/build/building-modules/04-query-services.md similarity index 100% rename from versioned_docs/version-0.52/building-modules/04-query-services.md rename to versioned_docs/version-0.52/build/building-modules/04-query-services.md diff --git a/versioned_docs/version-0.52/building-modules/05-protobuf-annotations.md b/versioned_docs/version-0.52/build/building-modules/05-protobuf-annotations.md similarity index 100% rename from versioned_docs/version-0.52/building-modules/05-protobuf-annotations.md rename to versioned_docs/version-0.52/build/building-modules/05-protobuf-annotations.md diff --git a/versioned_docs/version-0.52/building-modules/06-keeper.md b/versioned_docs/version-0.52/build/building-modules/06-keeper.md similarity index 100% rename from versioned_docs/version-0.52/building-modules/06-keeper.md rename to versioned_docs/version-0.52/build/building-modules/06-keeper.md diff --git a/versioned_docs/version-0.52/building-modules/06-preblock-beginblock-endblock.md b/versioned_docs/version-0.52/build/building-modules/06-preblock-beginblock-endblock.md similarity index 100% rename from versioned_docs/version-0.52/building-modules/06-preblock-beginblock-endblock.md rename to versioned_docs/version-0.52/build/building-modules/06-preblock-beginblock-endblock.md diff --git a/versioned_docs/version-0.52/building-modules/08-genesis.md b/versioned_docs/version-0.52/build/building-modules/08-genesis.md similarity index 100% rename from versioned_docs/version-0.52/building-modules/08-genesis.md rename to versioned_docs/version-0.52/build/building-modules/08-genesis.md diff --git a/versioned_docs/version-0.52/building-modules/09-module-interfaces.md b/versioned_docs/version-0.52/build/building-modules/09-module-interfaces.md similarity index 100% rename from versioned_docs/version-0.52/building-modules/09-module-interfaces.md rename to versioned_docs/version-0.52/build/building-modules/09-module-interfaces.md diff --git a/versioned_docs/version-0.52/building-modules/11-structure.md b/versioned_docs/version-0.52/build/building-modules/11-structure.md similarity index 100% rename from versioned_docs/version-0.52/building-modules/11-structure.md rename to versioned_docs/version-0.52/build/building-modules/11-structure.md diff --git a/versioned_docs/version-0.52/building-modules/12-errors.md b/versioned_docs/version-0.52/build/building-modules/12-errors.md similarity index 100% rename from versioned_docs/version-0.52/building-modules/12-errors.md rename to versioned_docs/version-0.52/build/building-modules/12-errors.md diff --git a/versioned_docs/version-0.52/building-modules/13-upgrade.md b/versioned_docs/version-0.52/build/building-modules/13-upgrade.md similarity index 100% rename from versioned_docs/version-0.52/building-modules/13-upgrade.md rename to versioned_docs/version-0.52/build/building-modules/13-upgrade.md diff --git a/versioned_docs/version-0.52/building-modules/14-simulator.md b/versioned_docs/version-0.52/build/building-modules/14-simulator.md similarity index 100% rename from versioned_docs/version-0.52/building-modules/14-simulator.md rename to versioned_docs/version-0.52/build/building-modules/14-simulator.md diff --git a/versioned_docs/version-0.52/building-modules/15-depinject.md b/versioned_docs/version-0.52/build/building-modules/15-depinject.md similarity index 100% rename from versioned_docs/version-0.52/building-modules/15-depinject.md rename to versioned_docs/version-0.52/build/building-modules/15-depinject.md diff --git a/versioned_docs/version-0.52/building-modules/16-testing.md b/versioned_docs/version-0.52/build/building-modules/16-testing.md similarity index 100% rename from versioned_docs/version-0.52/building-modules/16-testing.md rename to versioned_docs/version-0.52/build/building-modules/16-testing.md diff --git a/versioned_docs/version-0.52/building-modules/18-define-hooks.md b/versioned_docs/version-0.52/build/building-modules/18-define-hooks.md similarity index 100% rename from versioned_docs/version-0.52/building-modules/18-define-hooks.md rename to versioned_docs/version-0.52/build/building-modules/18-define-hooks.md diff --git a/versioned_docs/version-0.52/building-modules/_category_.json b/versioned_docs/version-0.52/build/building-modules/_category_.json similarity index 100% rename from versioned_docs/version-0.52/building-modules/_category_.json rename to versioned_docs/version-0.52/build/building-modules/_category_.json diff --git a/versioned_docs/version-0.52/migrations/01-intro.md b/versioned_docs/version-0.52/build/migrations/01-intro.md similarity index 100% rename from versioned_docs/version-0.52/migrations/01-intro.md rename to versioned_docs/version-0.52/build/migrations/01-intro.md diff --git a/versioned_docs/version-0.52/migrations/02-upgrading.md b/versioned_docs/version-0.52/build/migrations/02-upgrading.md similarity index 100% rename from versioned_docs/version-0.52/migrations/02-upgrading.md rename to versioned_docs/version-0.52/build/migrations/02-upgrading.md diff --git a/versioned_docs/version-0.52/migrations/_category_.json b/versioned_docs/version-0.52/build/migrations/_category_.json similarity index 100% rename from versioned_docs/version-0.52/migrations/_category_.json rename to versioned_docs/version-0.52/build/migrations/_category_.json diff --git a/versioned_docs/version-0.52/modules/README.md b/versioned_docs/version-0.52/build/modules/README.md similarity index 100% rename from versioned_docs/version-0.52/modules/README.md rename to versioned_docs/version-0.52/build/modules/README.md diff --git a/versioned_docs/version-0.52/modules/_category_.json b/versioned_docs/version-0.52/build/modules/_category_.json similarity index 100% rename from versioned_docs/version-0.52/modules/_category_.json rename to versioned_docs/version-0.52/build/modules/_category_.json diff --git a/versioned_docs/version-0.52/modules/accounts/README.md b/versioned_docs/version-0.52/build/modules/accounts/README.md similarity index 100% rename from versioned_docs/version-0.52/modules/accounts/README.md rename to versioned_docs/version-0.52/build/modules/accounts/README.md diff --git a/versioned_docs/version-0.52/modules/auth/1-vesting.md b/versioned_docs/version-0.52/build/modules/auth/1-vesting.md similarity index 100% rename from versioned_docs/version-0.52/modules/auth/1-vesting.md rename to versioned_docs/version-0.52/build/modules/auth/1-vesting.md diff --git a/versioned_docs/version-0.52/modules/auth/2-tx.md b/versioned_docs/version-0.52/build/modules/auth/2-tx.md similarity index 100% rename from versioned_docs/version-0.52/modules/auth/2-tx.md rename to versioned_docs/version-0.52/build/modules/auth/2-tx.md diff --git a/versioned_docs/version-0.52/modules/auth/README.md b/versioned_docs/version-0.52/build/modules/auth/README.md similarity index 100% rename from versioned_docs/version-0.52/modules/auth/README.md rename to versioned_docs/version-0.52/build/modules/auth/README.md diff --git a/versioned_docs/version-0.52/modules/authz/README.md b/versioned_docs/version-0.52/build/modules/authz/README.md similarity index 100% rename from versioned_docs/version-0.52/modules/authz/README.md rename to versioned_docs/version-0.52/build/modules/authz/README.md diff --git a/versioned_docs/version-0.52/modules/bank/README.md b/versioned_docs/version-0.52/build/modules/bank/README.md similarity index 100% rename from versioned_docs/version-0.52/modules/bank/README.md rename to versioned_docs/version-0.52/build/modules/bank/README.md diff --git a/versioned_docs/version-0.52/modules/circuit/README.md b/versioned_docs/version-0.52/build/modules/circuit/README.md similarity index 100% rename from versioned_docs/version-0.52/modules/circuit/README.md rename to versioned_docs/version-0.52/build/modules/circuit/README.md diff --git a/versioned_docs/version-0.52/modules/consensus/README.md b/versioned_docs/version-0.52/build/modules/consensus/README.md similarity index 100% rename from versioned_docs/version-0.52/modules/consensus/README.md rename to versioned_docs/version-0.52/build/modules/consensus/README.md diff --git a/versioned_docs/version-0.52/modules/distribution/README.md b/versioned_docs/version-0.52/build/modules/distribution/README.md similarity index 100% rename from versioned_docs/version-0.52/modules/distribution/README.md rename to versioned_docs/version-0.52/build/modules/distribution/README.md diff --git a/versioned_docs/version-0.52/modules/epochs/README.md b/versioned_docs/version-0.52/build/modules/epochs/README.md similarity index 100% rename from versioned_docs/version-0.52/modules/epochs/README.md rename to versioned_docs/version-0.52/build/modules/epochs/README.md diff --git a/versioned_docs/version-0.52/modules/evidence/README.md b/versioned_docs/version-0.52/build/modules/evidence/README.md similarity index 100% rename from versioned_docs/version-0.52/modules/evidence/README.md rename to versioned_docs/version-0.52/build/modules/evidence/README.md diff --git a/versioned_docs/version-0.52/modules/feegrant/README.md b/versioned_docs/version-0.52/build/modules/feegrant/README.md similarity index 100% rename from versioned_docs/version-0.52/modules/feegrant/README.md rename to versioned_docs/version-0.52/build/modules/feegrant/README.md diff --git a/versioned_docs/version-0.52/modules/genutil/README.md b/versioned_docs/version-0.52/build/modules/genutil/README.md similarity index 100% rename from versioned_docs/version-0.52/modules/genutil/README.md rename to versioned_docs/version-0.52/build/modules/genutil/README.md diff --git a/versioned_docs/version-0.52/modules/gov/README.md b/versioned_docs/version-0.52/build/modules/gov/README.md similarity index 100% rename from versioned_docs/version-0.52/modules/gov/README.md rename to versioned_docs/version-0.52/build/modules/gov/README.md diff --git a/versioned_docs/version-0.52/modules/group/README.md b/versioned_docs/version-0.52/build/modules/group/README.md similarity index 100% rename from versioned_docs/version-0.52/modules/group/README.md rename to versioned_docs/version-0.52/build/modules/group/README.md diff --git a/versioned_docs/version-0.52/modules/mint/README.md b/versioned_docs/version-0.52/build/modules/mint/README.md similarity index 100% rename from versioned_docs/version-0.52/modules/mint/README.md rename to versioned_docs/version-0.52/build/modules/mint/README.md diff --git a/versioned_docs/version-0.52/modules/nft/README.md b/versioned_docs/version-0.52/build/modules/nft/README.md similarity index 100% rename from versioned_docs/version-0.52/modules/nft/README.md rename to versioned_docs/version-0.52/build/modules/nft/README.md diff --git a/versioned_docs/version-0.52/modules/params/README.md b/versioned_docs/version-0.52/build/modules/params/README.md similarity index 100% rename from versioned_docs/version-0.52/modules/params/README.md rename to versioned_docs/version-0.52/build/modules/params/README.md diff --git a/versioned_docs/version-0.52/modules/protocolpool/README.md b/versioned_docs/version-0.52/build/modules/protocolpool/README.md similarity index 100% rename from versioned_docs/version-0.52/modules/protocolpool/README.md rename to versioned_docs/version-0.52/build/modules/protocolpool/README.md diff --git a/versioned_docs/version-0.52/modules/slashing/README.md b/versioned_docs/version-0.52/build/modules/slashing/README.md similarity index 100% rename from versioned_docs/version-0.52/modules/slashing/README.md rename to versioned_docs/version-0.52/build/modules/slashing/README.md diff --git a/versioned_docs/version-0.52/modules/staking/README.md b/versioned_docs/version-0.52/build/modules/staking/README.md similarity index 100% rename from versioned_docs/version-0.52/modules/staking/README.md rename to versioned_docs/version-0.52/build/modules/staking/README.md diff --git a/versioned_docs/version-0.52/modules/upgrade/README.md b/versioned_docs/version-0.52/build/modules/upgrade/README.md similarity index 100% rename from versioned_docs/version-0.52/modules/upgrade/README.md rename to versioned_docs/version-0.52/build/modules/upgrade/README.md diff --git a/versioned_docs/version-0.52/modules/validate/README.md b/versioned_docs/version-0.52/build/modules/validate/README.md similarity index 100% rename from versioned_docs/version-0.52/modules/validate/README.md rename to versioned_docs/version-0.52/build/modules/validate/README.md diff --git a/versioned_docs/version-0.52/packages/01-depinject.md b/versioned_docs/version-0.52/build/packages/01-depinject.md similarity index 100% rename from versioned_docs/version-0.52/packages/01-depinject.md rename to versioned_docs/version-0.52/build/packages/01-depinject.md diff --git a/versioned_docs/version-0.52/packages/README.md b/versioned_docs/version-0.52/build/packages/README.md similarity index 100% rename from versioned_docs/version-0.52/packages/README.md rename to versioned_docs/version-0.52/build/packages/README.md diff --git a/versioned_docs/version-0.52/packages/_category_.json b/versioned_docs/version-0.52/build/packages/_category_.json similarity index 100% rename from versioned_docs/version-0.52/packages/_category_.json rename to versioned_docs/version-0.52/build/packages/_category_.json diff --git a/versioned_docs/version-0.52/rfc/PROCESS.md b/versioned_docs/version-0.52/build/rfc/PROCESS.md similarity index 100% rename from versioned_docs/version-0.52/rfc/PROCESS.md rename to versioned_docs/version-0.52/build/rfc/PROCESS.md diff --git a/versioned_docs/version-0.52/rfc/README.md b/versioned_docs/version-0.52/build/rfc/README.md similarity index 100% rename from versioned_docs/version-0.52/rfc/README.md rename to versioned_docs/version-0.52/build/rfc/README.md diff --git a/versioned_docs/version-0.50/build/rfc/rfc/_category_.json b/versioned_docs/version-0.52/build/rfc/_category_.json similarity index 100% rename from versioned_docs/version-0.50/build/rfc/rfc/_category_.json rename to versioned_docs/version-0.52/build/rfc/_category_.json diff --git a/versioned_docs/version-0.52/rfc/rfc-001-tx-validation.md b/versioned_docs/version-0.52/build/rfc/rfc-001-tx-validation.md similarity index 100% rename from versioned_docs/version-0.52/rfc/rfc-001-tx-validation.md rename to versioned_docs/version-0.52/build/rfc/rfc-001-tx-validation.md diff --git a/versioned_docs/version-0.52/rfc/rfc-002-zero-copy-encoding.md b/versioned_docs/version-0.52/build/rfc/rfc-002-zero-copy-encoding.md similarity index 100% rename from versioned_docs/version-0.52/rfc/rfc-002-zero-copy-encoding.md rename to versioned_docs/version-0.52/build/rfc/rfc-002-zero-copy-encoding.md diff --git a/versioned_docs/version-0.52/rfc/rfc-004-accounts.md b/versioned_docs/version-0.52/build/rfc/rfc-004-accounts.md similarity index 100% rename from versioned_docs/version-0.52/rfc/rfc-004-accounts.md rename to versioned_docs/version-0.52/build/rfc/rfc-004-accounts.md diff --git a/versioned_docs/version-0.52/rfc/rfc-005-optimistic-execution.md b/versioned_docs/version-0.52/build/rfc/rfc-005-optimistic-execution.md similarity index 100% rename from versioned_docs/version-0.52/rfc/rfc-005-optimistic-execution.md rename to versioned_docs/version-0.52/build/rfc/rfc-005-optimistic-execution.md diff --git a/versioned_docs/version-0.52/rfc/rfc-006-handlers.md b/versioned_docs/version-0.52/build/rfc/rfc-006-handlers.md similarity index 100% rename from versioned_docs/version-0.52/rfc/rfc-006-handlers.md rename to versioned_docs/version-0.52/build/rfc/rfc-006-handlers.md diff --git a/versioned_docs/version-0.52/rfc/rfc-template.md b/versioned_docs/version-0.52/build/rfc/rfc-template.md similarity index 100% rename from versioned_docs/version-0.52/rfc/rfc-template.md rename to versioned_docs/version-0.52/build/rfc/rfc-template.md diff --git a/versioned_docs/version-0.52/spec/README.md b/versioned_docs/version-0.52/build/spec/README.md similarity index 100% rename from versioned_docs/version-0.52/spec/README.md rename to versioned_docs/version-0.52/build/spec/README.md diff --git a/versioned_docs/version-0.52/spec/SPEC_MODULE.md b/versioned_docs/version-0.52/build/spec/SPEC_MODULE.md similarity index 100% rename from versioned_docs/version-0.52/spec/SPEC_MODULE.md rename to versioned_docs/version-0.52/build/spec/SPEC_MODULE.md diff --git a/versioned_docs/version-0.52/spec/SPEC_STANDARD.md b/versioned_docs/version-0.52/build/spec/SPEC_STANDARD.md similarity index 100% rename from versioned_docs/version-0.52/spec/SPEC_STANDARD.md rename to versioned_docs/version-0.52/build/spec/SPEC_STANDARD.md diff --git a/versioned_docs/version-0.52/spec/_category_.json b/versioned_docs/version-0.52/build/spec/_category_.json similarity index 100% rename from versioned_docs/version-0.52/spec/_category_.json rename to versioned_docs/version-0.52/build/spec/_category_.json diff --git a/versioned_docs/version-0.52/spec/_ics/README.md b/versioned_docs/version-0.52/build/spec/_ics/README.md similarity index 100% rename from versioned_docs/version-0.52/spec/_ics/README.md rename to versioned_docs/version-0.52/build/spec/_ics/README.md diff --git a/versioned_docs/version-0.52/spec/_ics/ics-030-signed-messages.md b/versioned_docs/version-0.52/build/spec/_ics/ics-030-signed-messages.md similarity index 100% rename from versioned_docs/version-0.52/spec/_ics/ics-030-signed-messages.md rename to versioned_docs/version-0.52/build/spec/_ics/ics-030-signed-messages.md diff --git a/versioned_docs/version-0.52/spec/addresses/README.md b/versioned_docs/version-0.52/build/spec/addresses/README.md similarity index 100% rename from versioned_docs/version-0.52/spec/addresses/README.md rename to versioned_docs/version-0.52/build/spec/addresses/README.md diff --git a/versioned_docs/version-0.52/spec/addresses/bech32.md b/versioned_docs/version-0.52/build/spec/addresses/bech32.md similarity index 100% rename from versioned_docs/version-0.52/spec/addresses/bech32.md rename to versioned_docs/version-0.52/build/spec/addresses/bech32.md diff --git a/versioned_docs/version-0.52/spec/fee_distribution/f1_fee_distr.pdf b/versioned_docs/version-0.52/build/spec/fee_distribution/f1_fee_distr.pdf similarity index 100% rename from versioned_docs/version-0.52/spec/fee_distribution/f1_fee_distr.pdf rename to versioned_docs/version-0.52/build/spec/fee_distribution/f1_fee_distr.pdf diff --git a/versioned_docs/version-0.52/spec/fee_distribution/f1_fee_distr.tex b/versioned_docs/version-0.52/build/spec/fee_distribution/f1_fee_distr.tex similarity index 100% rename from versioned_docs/version-0.52/spec/fee_distribution/f1_fee_distr.tex rename to versioned_docs/version-0.52/build/spec/fee_distribution/f1_fee_distr.tex diff --git a/versioned_docs/version-0.52/spec/store/README.md b/versioned_docs/version-0.52/build/spec/store/README.md similarity index 100% rename from versioned_docs/version-0.52/spec/store/README.md rename to versioned_docs/version-0.52/build/spec/store/README.md diff --git a/versioned_docs/version-0.52/spec/store/interblock-cache.md b/versioned_docs/version-0.52/build/spec/store/interblock-cache.md similarity index 100% rename from versioned_docs/version-0.52/spec/store/interblock-cache.md rename to versioned_docs/version-0.52/build/spec/store/interblock-cache.md diff --git a/versioned_docs/version-0.52/tooling/00-protobuf.md b/versioned_docs/version-0.52/build/tooling/00-protobuf.md similarity index 100% rename from versioned_docs/version-0.52/tooling/00-protobuf.md rename to versioned_docs/version-0.52/build/tooling/00-protobuf.md diff --git a/versioned_docs/version-0.52/tooling/01-cosmovisor.md b/versioned_docs/version-0.52/build/tooling/01-cosmovisor.md similarity index 100% rename from versioned_docs/version-0.52/tooling/01-cosmovisor.md rename to versioned_docs/version-0.52/build/tooling/01-cosmovisor.md diff --git a/versioned_docs/version-0.52/tooling/02-confix.md b/versioned_docs/version-0.52/build/tooling/02-confix.md similarity index 100% rename from versioned_docs/version-0.52/tooling/02-confix.md rename to versioned_docs/version-0.52/build/tooling/02-confix.md diff --git a/versioned_docs/version-0.52/tooling/03-hubl.md b/versioned_docs/version-0.52/build/tooling/03-hubl.md similarity index 100% rename from versioned_docs/version-0.52/tooling/03-hubl.md rename to versioned_docs/version-0.52/build/tooling/03-hubl.md diff --git a/versioned_docs/version-0.52/tooling/README.md b/versioned_docs/version-0.52/build/tooling/README.md similarity index 100% rename from versioned_docs/version-0.52/tooling/README.md rename to versioned_docs/version-0.52/build/tooling/README.md diff --git a/versioned_docs/version-0.52/tooling/_category_.json b/versioned_docs/version-0.52/build/tooling/_category_.json similarity index 100% rename from versioned_docs/version-0.52/tooling/_category_.json rename to versioned_docs/version-0.52/build/tooling/_category_.json diff --git a/versioned_docs/version-0.52/rfc/_category_.json b/versioned_docs/version-0.52/rfc/_category_.json deleted file mode 100644 index a5712bdae..000000000 --- a/versioned_docs/version-0.52/rfc/_category_.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "label": "RFC", - "position": 7, - "link": null -} \ No newline at end of file diff --git a/versioned_docs/version-0.52/tutorials/_category_.json b/versioned_docs/version-0.52/tutorials/_category_.json new file mode 100644 index 000000000..f27bca92d --- /dev/null +++ b/versioned_docs/version-0.52/tutorials/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Advanced Tutorials", + "position": 2, + "link": null +} \ No newline at end of file diff --git a/versioned_docs/version-0.52/tutorials/tutorials.md b/versioned_docs/version-0.52/tutorials/tutorials.md new file mode 100644 index 000000000..e6828c9fa --- /dev/null +++ b/versioned_docs/version-0.52/tutorials/tutorials.md @@ -0,0 +1,12 @@ +--- +sidebar_position: 0 +--- +# Tutorials + +## Advanced Tutorials + +This section provides a concise overview of tutorials focused on implementing vote extensions in the Cosmos SDK. Vote extensions are a powerful feature for enhancing the security and fairness of blockchain applications, particularly in scenarios like implementing oracles and mitigating auction front-running. + +* **Implementing Oracle with Vote Extensions** - This tutorial details how to use vote extensions for the implementation of a secure and reliable oracle within a blockchain application. It demonstrates the use of vote extensions to securely include oracle data submissions in blocks, ensuring the data's integrity and reliability for the blockchain. + +* **Mitigating Auction Front-Running with Vote Extensions** - Explore how to prevent auction front-running using vote extensions. This tutorial outlines the creation of a module aimed at mitigating front-running in nameservice auctions, emphasising the `ExtendVote`, `PrepareProposal`, and `ProcessProposal` functions to facilitate a fair auction process. \ No newline at end of file diff --git a/versioned_docs/version-0.52/tutorials/vote-extensions/_category_.json b/versioned_docs/version-0.52/tutorials/vote-extensions/_category_.json new file mode 100644 index 000000000..a2aecebd0 --- /dev/null +++ b/versioned_docs/version-0.52/tutorials/vote-extensions/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Vote Extensions Tutorials", + "position": 1, + "link": null +} \ No newline at end of file diff --git a/versioned_docs/version-0.52/tutorials/vote-extensions/auction-frontrunning/00-getting-started.md b/versioned_docs/version-0.52/tutorials/vote-extensions/auction-frontrunning/00-getting-started.md new file mode 100644 index 000000000..a68a6e159 --- /dev/null +++ b/versioned_docs/version-0.52/tutorials/vote-extensions/auction-frontrunning/00-getting-started.md @@ -0,0 +1,40 @@ +# Getting Started + +## Table of Contents + +- [Getting Started](#overview-of-the-project) +- [Understanding Front-Running](./01-understanding-frontrunning.md) +- [Mitigating Front-running with Vote Extensions](./02-mitigating-front-running-with-vote-extesions.md) +- [Demo of Mitigating Front-Running](./03-demo-of-mitigating-front-running.md) + +## Getting Started + +### Overview of the Project + +This tutorial outlines the development of a module designed to mitigate front-running in nameservice auctions. The following functions are central to this module: + +* `ExtendVote`: Gathers bids from the mempool and includes them in the vote extension to ensure a fair and transparent auction process. +* `PrepareProposal`: Processes the vote extensions from the previous block, creating a special transaction that encapsulates bids to be included in the current proposal. +* `ProcessProposal`: Validates that the first transaction in the proposal is the special transaction containing the vote extensions and ensures the integrity of the bids. + +In this advanced tutorial, we will be working with an example application that facilitates the auctioning of nameservices. To see what frontrunning and nameservices are [here](./01-understanding-frontrunning.md) This application provides a practical use case to explore the prevention of auction front-running, also known as "bid sniping", where a validator takes advantage of seeing a bid in the mempool to place their own higher bid before the original bid is processed. + +The tutorial will guide you through using the Cosmos SDK to mitigate front-running using vote extensions. The module will be built on top of the base blockchain provided in the `tutorials/base` directory and will use the `auction` module as a foundation. By the end of this tutorial, you will have a better understanding of how to prevent front-running in blockchain auctions, specifically in the context of nameservice auctioning. + +## What are Vote extensions? + +Vote extensions is arbitrary information which can be inserted into a block. This feature is part of ABCI 2.0, which is available for use in the SDK 0.50 release and part of the 0.38 CometBFT release. + +More information about vote extensions can be seen [here](https://docs.cosmos.network/main/build/abci/vote-extensions). + +## Requirements and Setup + +Before diving into the advanced tutorial on auction front-running simulation, ensure you meet the following requirements: + +* [Golang >1.21.5](https://golang.org/doc/install) installed +* Familiarity with the concepts of front-running and MEV, as detailed in [Understanding Front-Running](./01-understanding-frontrunning.md) +* Understanding of Vote Extensions as described [here](https://docs.cosmos.network/main/build/abci/vote-extensions) + +You will also need a foundational blockchain to build upon coupled with your own module. The `tutorials/base` directory has the necessary blockchain code to start your custom project with the Cosmos SDK. For the module, you can use the `auction` module provided in the `tutorials/auction/x/auction` directory as a reference but please be aware that all of the code needed to implement vote extensions is already implemented in this module. + +This will set up a strong base for your blockchain, enabling the integration of advanced features such as auction front-running simulation. diff --git a/versioned_docs/version-0.52/tutorials/vote-extensions/auction-frontrunning/01-understanding-frontrunning.md b/versioned_docs/version-0.52/tutorials/vote-extensions/auction-frontrunning/01-understanding-frontrunning.md new file mode 100644 index 000000000..31602b0e6 --- /dev/null +++ b/versioned_docs/version-0.52/tutorials/vote-extensions/auction-frontrunning/01-understanding-frontrunning.md @@ -0,0 +1,41 @@ +# Understanding Front-Running and more + +## Introduction + +Blockchain technology is vulnerable to practices that can affect the fairness and security of the network. Two such practices are front-running and Maximal Extractable Value (MEV), which are important for blockchain participants to understand. + +## What is Front-Running? + +Front-running is when someone, such as a validator, uses their ability to see pending transactions to execute their own transactions first, benefiting from the knowledge of upcoming transactions. In nameservice auctions, a front-runner might place a higher bid before the original bid is confirmed, unfairly winning the auction. + +## Nameservices and Nameservice Auctions + +Nameservices are human-readable identifiers on a blockchain, akin to internet domain names, that correspond to specific addresses or resources. They simplify interactions with typically long and complex blockchain addresses, allowing users to have a memorable and unique identifier for their blockchain address or smart contract. + +Nameservice auctions are the process by which these identifiers are bid on and acquired. To combat front-running—where someone might use knowledge of pending bids to place a higher bid first—mechanisms such as commit-reveal schemes, auction extensions, and fair sequencing are implemented. These strategies ensure a transparent and fair bidding process, reducing the potential for Maximal Extractable Value (MEV) exploitation. + +## What is Maximal Extractable Value (MEV)? + +MEV is the highest value that can be extracted by manipulating the order of transactions within a block, beyond the standard block rewards and fees. This has become more prominent with the growth of decentralised finance (DeFi), where transaction order can greatly affect profits. + +## Implications of MEV + +MEV can lead to: + +- **Network Security**: Potential centralisation, as those with more computational power might dominate the process, increasing the risk of attacks. +- **Market Fairness**: An uneven playing field where only a few can gain at the expense of the majority. +- **User Experience**: Higher fees and network congestion due to the competition for MEV. + +## Mitigating MEV and Front-Running + +Some solutions being developed to mitigate MEV and front-running, including: + +- **Time-delayed Transactions**: Random delays to make transaction timing unpredictable. +- **Private Transaction Pools**: Concealing transactions until they are mined. +- **Fair Sequencing Services**: Processing transactions in the order they are received. + +For this tutorial, we will be exploring the last solution, fair sequencing services, in the context of nameservice auctions. + +## Conclusion + +MEV and front-running are challenges to blockchain integrity and fairness. Ongoing innovation and implementation of mitigation strategies are crucial for the ecosystem's health and success. diff --git a/docs/tutorials/vote-extensions/auction-frontrunning/02-mitigating-front-running-with-vote-extesions.md b/versioned_docs/version-0.52/tutorials/vote-extensions/auction-frontrunning/02-mitigating-front-running-with-vote-extensions.md similarity index 98% rename from docs/tutorials/vote-extensions/auction-frontrunning/02-mitigating-front-running-with-vote-extesions.md rename to versioned_docs/version-0.52/tutorials/vote-extensions/auction-frontrunning/02-mitigating-front-running-with-vote-extensions.md index 56c2d4029..421b6ed8c 100644 --- a/docs/tutorials/vote-extensions/auction-frontrunning/02-mitigating-front-running-with-vote-extesions.md +++ b/versioned_docs/version-0.52/tutorials/vote-extensions/auction-frontrunning/02-mitigating-front-running-with-vote-extensions.md @@ -2,9 +2,9 @@ ## Table of Contents -- [Prerequisites](#prerequisites) -- [Implementing Structs for Vote Extensions](#implementing-structs-for-vote-extensions) -- [Implementing Handlers and Configuring Handlers](#implementing-handlers-and-configuring-handlers) +* [Prerequisites](#prerequisites) +* [Implementing Structs for Vote Extensions](#implementing-structs-for-vote-extensions) +* [Implementing Handlers and Configuring Handlers](#implementing-handlers-and-configuring-handlers) ## Prerequisites diff --git a/versioned_docs/version-0.52/tutorials/vote-extensions/auction-frontrunning/03-demo-of-mitigating-front-running.md b/versioned_docs/version-0.52/tutorials/vote-extensions/auction-frontrunning/03-demo-of-mitigating-front-running.md new file mode 100644 index 000000000..63f37b4ae --- /dev/null +++ b/versioned_docs/version-0.52/tutorials/vote-extensions/auction-frontrunning/03-demo-of-mitigating-front-running.md @@ -0,0 +1,106 @@ +# Demo of Mitigating Front-Running with Vote Extensions + +The purpose of this demo is to test the implementation of the `VoteExtensionHandler` and `PrepareProposalHandler` that we have just added to the codebase. These handlers are designed to mitigate front-running by ensuring that all validators have a consistent view of the mempool when preparing proposals. + +In this demo, we are using a 3 validator network. The Beacon validator is special because it has a custom transaction provider enabled. This means that it can potentially manipulate the order of transactions in a proposal to its advantage (i.e., front-running). + +1. Bootstrap the validator network: This sets up a network with 3 validators. The script `./scripts/configure.sh is used to configure the network and the validators. + +```shell +cd scripts +configure.sh +``` + +If this doesn't work please ensure you have run `make build` in the `tutorials/nameservice/base` directory. + + +2. Have alice attempt to reserve `bob.cosmos`: This is a normal transaction that alice wants to execute. The script ``./scripts/reserve.sh "bob.cosmos"` is used to send this transaction. + +```shell +reserve.sh "bob.cosmos" +``` + +3. Query to verify the name has been reserved: This is to check the result of the transaction. The script `./scripts/whois.sh "bob.cosmos"` is used to query the state of the blockchain. + +```shell +whois.sh "bob.cosmos" +``` + +It should return: + +```{ + "name": { + "name": "bob.cosmos", + "owner": "cosmos1nq9wuvuju4jdmpmzvxmg8zhhu2ma2y2l2pnu6w", + "resolve_address": "cosmos1h6zy2kn9efxtw5z22rc5k9qu7twl70z24kr3ht", + "amount": [ + { + "denom": "uatom", + "amount": "1000" + } + ] + } +} +``` + +To detect front-running attempts by the beacon, scrutinise the logs during the `ProcessProposal` stage. Open the logs for each validator, including the beacon, `val1`, and `val2`, to observe the following behavior. Open the log file of the validator node. The location of this file can vary depending on your setup, but it's typically located in a directory like `$HOME/cosmos/nodes/#{validator}/logs`. The directory in this case will be under the validator so, `beacon` `val1` or `val2`. Run the following to tail the logs of the validator or beacon: + +```shell +tail -f $HOME/cosmos/nodes/#{validator}/logs +``` + +```shell +2:47PM ERR ❌️:: Detected invalid proposal bid :: name:"bob.cosmos" resolveAddress:"cosmos1wmuwv38pdur63zw04t0c78r2a8dyt08hf9tpvd" owner:"cosmos1wmuwv38pdur63zw04t0c78r2a8dyt08hf9tpvd" amount: module=server +2:47PM ERR ❌️:: Unable to validate bids in Process Proposal :: module=server +2:47PM ERR prevote step: state machine rejected a proposed block; this should not happen:the proposer may be misbehaving; prevoting nil err=null height=142 module=consensus round=0 +``` + + +4. List the Beacon's keys: This is to verify the addresses of the validators. The script `./scripts/list-beacon-keys.sh` is used to list the keys. + +```shell +list-beacon-keys.sh +``` + +We should receive something similar to the following: + +```shell +[ + { + "name": "alice", + "type": "local", + "address": "cosmos1h6zy2kn9efxtw5z22rc5k9qu7twl70z24kr3ht", + "pubkey": "{\"@type\":\"/cosmos.crypto.secp256k1.PubKey\",\"key\":\"A32cvBUkNJz+h2vld4A5BxvU5Rd+HyqpR3aGtvEhlm4C\"}" + }, + { + "name": "barbara", + "type": "local", + "address": "cosmos1nq9wuvuju4jdmpmzvxmg8zhhu2ma2y2l2pnu6w", + "pubkey": "{\"@type\":\"/cosmos.crypto.secp256k1.PubKey\",\"key\":\"Ag9PFsNyTQPoJdbyCWia5rZH9CrvSrjMsk7Oz4L3rXQ5\"}" + }, + { + "name": "beacon-key", + "type": "local", + "address": "cosmos1ez9a6x7lz4gvn27zr368muw8jeyas7sv84lfup", + "pubkey": "{\"@type\":\"/cosmos.crypto.secp256k1.PubKey\",\"key\":\"AlzJZMWyN7lass710TnAhyuFKAFIaANJyw5ad5P2kpcH\"}" + }, + { + "name": "cindy", + "type": "local", + "address": "cosmos1m5j6za9w4qc2c5ljzxmm2v7a63mhjeag34pa3g", + "pubkey": "{\"@type\":\"/cosmos.crypto.secp256k1.PubKey\",\"key\":\"A6F1/3yot5OpyXoSkBbkyl+3rqBkxzRVSJfvSpm/AvW5\"}" + } +] +``` + +This allows us to match up the addresses and see that the bid was not front run by the beacon due as the resolve address is Alice's address and not the beacons address. + +By running this demo, we can verify that the `VoteExtensionHandler` and `PrepareProposalHandler` are working as expected and that they are able to prevent front-running. + +## Conclusion + +In this tutorial, we've tackled front-running and MEV, focusing on nameservice auctions' vulnerability to these issues. We've explored vote extensions, a key feature of ABCI 2.0, and integrated them into a Cosmos SDK application. + +Through practical exercises, you've implemented vote extensions, and tested their effectiveness in creating a fair auction system. You've gained practical insights by configuring a validator network and analysing blockchain logs. + +Keep experimenting with these concepts, engage with the community, and stay updated on new advancements. The knowledge you've acquired here is crucial for developing secure and fair blockchain applications. diff --git a/versioned_docs/version-0.52/tutorials/vote-extensions/auction-frontrunning/_category_.json b/versioned_docs/version-0.52/tutorials/vote-extensions/auction-frontrunning/_category_.json new file mode 100644 index 000000000..aab0cfdf6 --- /dev/null +++ b/versioned_docs/version-0.52/tutorials/vote-extensions/auction-frontrunning/_category_.json @@ -0,0 +1,5 @@ +{ + "label": " Mitigating Auction Front-Running Tutorial", + "position": 0, + "link": null +} \ No newline at end of file diff --git a/versioned_docs/version-0.52/tutorials/vote-extensions/oracle/00-getting-started.md b/versioned_docs/version-0.52/tutorials/vote-extensions/oracle/00-getting-started.md new file mode 100644 index 000000000..59ea65be9 --- /dev/null +++ b/versioned_docs/version-0.52/tutorials/vote-extensions/oracle/00-getting-started.md @@ -0,0 +1,36 @@ +# Getting Started + +## Table of Contents + +* [What is an Oracle?](./01-what-is-an-oracle.md) +* [Implementing Vote Extensions](./02-implementing-vote-extensions.md) +* [Testing the Oracle Module](./03-testing-oracle.md) + +## Prerequisites + +Before you start with this tutorial, make sure you have: + +* A working chain project. This tutorial won't cover the steps of creating a new chain/module. +* Familiarity with the Cosmos SDK. If you're not, we suggest you start with [Cosmos SDK Tutorials](https://tutorials.cosmos.network), as ABCI++ is considered an advanced topic. +* Read and understood [What is an Oracle?](01-what-is-an-oracle.md). This provides necessary background information for understanding the Oracle module. +* Basic understanding of Go programming language. + +## What are Vote extensions? + +Vote extensions is arbitrary information which can be inserted into a block. This feature is part of ABCI 2.0, which is available for use in the SDK 0.50 release and part of the 0.38 CometBFT release. + +More information about vote extensions can be seen [here](https://docs.cosmos.network/main/build/abci/vote-extensions). + +## Overview of the project + +We’ll go through the creation of a simple price oracle module focusing on the vote extensions implementation, ignoring the details inside the price oracle itself. + +We’ll go through the implementation of: + +* `ExtendVote` to get information from external price APIs. +* `VerifyVoteExtension` to check that the format of the provided votes is correct. +* `PrepareProposal` to process the vote extensions from the previous block and include them into the proposal as a transaction. +* `ProcessProposal` to check that the first transaction in the proposal is actually a “special tx” that contains the price information. +* `PreBlocker` to make price information available during FinalizeBlock. + +If you would like to see the complete working oracle module please see [here](https://github.com/cosmos/sdk-tutorials/blob/master/tutorials/oracle/base/x/oracle) diff --git a/versioned_docs/version-0.52/tutorials/vote-extensions/oracle/01-what-is-an-oracle.md b/versioned_docs/version-0.52/tutorials/vote-extensions/oracle/01-what-is-an-oracle.md new file mode 100644 index 000000000..9d50ddb36 --- /dev/null +++ b/versioned_docs/version-0.52/tutorials/vote-extensions/oracle/01-what-is-an-oracle.md @@ -0,0 +1,13 @@ +# What is an Oracle? + +An oracle in blockchain technology is a system that provides external data to a blockchain network. It acts as a source of information that is not natively accessible within the blockchain's closed environment. This can range from financial market prices to real-world event, making it crucial for decentralised applications. + +## Oracle in the Cosmos SDK + +In the Cosmos SDK, an oracle module can be implemented to provide external data to the blockchain. This module can use features like vote extensions to submit additional data during the consensus process, which can then be used by the blockchain to update its state with information from the outside world. + +For instance, a price oracle module in the Cosmos SDK could supply timely and accurate asset price information, which is vital for various financial operations within the blockchain ecosystem. + +## Conclusion + +Oracles are essential for blockchains to interact with external data, enabling them to respond to real-world information and events. Their implementation is key to the reliability and robustness of blockchain networks. diff --git a/versioned_docs/version-0.52/tutorials/vote-extensions/oracle/02-implementing-vote-extensions.md b/versioned_docs/version-0.52/tutorials/vote-extensions/oracle/02-implementing-vote-extensions.md new file mode 100644 index 000000000..aa610b5d3 --- /dev/null +++ b/versioned_docs/version-0.52/tutorials/vote-extensions/oracle/02-implementing-vote-extensions.md @@ -0,0 +1,219 @@ +# Implementing Vote Extensions + +## Implement ExtendVote + +First we’ll create the `OracleVoteExtension` struct, this is the object that will be marshaled as bytes and signed by the validator. + +In our example we’ll use JSON to marshal the vote extension for simplicity but we recommend to find an encoding that produces a smaller output, given that large vote extensions could impact CometBFT’s performance. Custom encodings and compressed bytes can be used out of the box. + +```go +// OracleVoteExtension defines the canonical vote extension structure. +type OracleVoteExtension struct { + Height int64 + Prices map[string]math.LegacyDec +} +``` + +Then we’ll create a `VoteExtensionsHandler` struct that contains everything we need to query for prices. + +```go +type VoteExtHandler struct { + logger log.Logger + currentBlock int64 // current block height + lastPriceSyncTS time.Time // last time we synced prices + providerTimeout time.Duration // timeout for fetching prices from providers + providers map[string]Provider // mapping of provider name to provider (e.g. Binance -> BinanceProvider) + providerPairs map[string][]keeper.CurrencyPair // mapping of provider name to supported pairs (e.g. Binance -> [ATOM/USD]) + + Keeper keeper.Keeper // keeper of our oracle module +} +``` + +Finally, a function that returns `sdk.ExtendVoteHandler` is needed too, and this is where our vote extension logic will live. + +```go +func (h *VoteExtHandler) ExtendVoteHandler() sdk.ExtendVoteHandler { + return func(ctx sdk.Context, req *abci.RequestExtendVote) (*abci.ResponseExtendVote, error) { + // here we'd have a helper function that gets all the prices and does a weighted average using the volume of each market + prices := h.getAllVolumeWeightedPrices() + + voteExt := OracleVoteExtension{ + Height: req.Height, + Prices: prices, + } + + bz, err := json.Marshal(voteExt) + if err != nil { + return nil, fmt.Errorf("failed to marshal vote extension: %w", err) + } + + return &abci.ResponseExtendVote{VoteExtension: bz}, nil + } +} +``` + +As you can see above, the creation of a vote extension is pretty simple and we just have to return bytes. CometBFT will handle the signing of these bytes for us. We ignored the process of getting the prices but you can see a more complete example [here:](https://github.com/cosmos/sdk-tutorials/blob/master/tutorials/oracle/base/x/oracle/abci/vote_extensions.go) + +Here we’ll do some simple checks like: + +* Is the vote extension unmarshaled correctly? +* Is the vote extension for the right height? +* Some other validation, for example, are the prices from this extension too deviated from my own prices? Or maybe checks that can detect malicious behavior. + +```go +func (h *VoteExtHandler) VerifyVoteExtensionHandler() sdk.VerifyVoteExtensionHandler { + return func(ctx sdk.Context, req *abci.RequestVerifyVoteExtension) (*abci.ResponseVerifyVoteExtension, error) { + var voteExt OracleVoteExtension + err := json.Unmarshal(req.VoteExtension, &voteExt) + if err != nil { + return nil, fmt.Errorf("failed to unmarshal vote extension: %w", err) + } + + if voteExt.Height != req.Height { + return nil, fmt.Errorf("vote extension height does not match request height; expected: %d, got: %d", req.Height, voteExt.Height) + } + + // Verify incoming prices from a validator are valid. Note, verification during + // VerifyVoteExtensionHandler MUST be deterministic. For brevity and demo + // purposes, we omit implementation. + if err := h.verifyOraclePrices(ctx, voteExt.Prices); err != nil { + return nil, fmt.Errorf("failed to verify oracle prices from validator %X: %w", req.ValidatorAddress, err) + } + + return &abci.ResponseVerifyVoteExtension{Status: abci.ResponseVerifyVoteExtension_ACCEPT}, nil + } +} +``` + +## Implement PrepareProposal + +```go +type ProposalHandler struct { + logger log.Logger + keeper keeper.Keeper // our oracle module keeper + valStore baseapp.ValidatorStore // to get the current validators' pubkeys +} +``` + +And we create the struct for our “special tx”, that will contain the prices and the votes so validators can later re-check in ProcessPRoposal that they get the same result than the block’s proposer. With this we could also check if all the votes have been used by comparing the votes received in ProcessProposal. + +```go +type StakeWeightedPrices struct { + StakeWeightedPrices map[string]math.LegacyDec + ExtendedCommitInfo abci.ExtendedCommitInfo +} +``` + +Now we create the `PrepareProposalHandler`. In this step we’ll first check if the vote extensions’ signatures are correct using a helper function called ValidateVoteExtensions from the baseapp package. + +```go +func (h *ProposalHandler) PrepareProposal() sdk.PrepareProposalHandler { + return func(ctx sdk.Context, req *abci.RequestPrepareProposal) (*abci.ResponsePrepareProposal, error) { + err := baseapp.ValidateVoteExtensions(ctx, h.valStore, req.Height, ctx.ChainID(), req.LocalLastCommit) + if err != nil { + return nil, err + } +... +``` + +Then we proceed to make the calculations only if the current height if higher than the height at which vote extensions have been enabled. Remember that vote extensions are made available to the block proposer on the next block at which they are produced/enabled. + +```go +... + proposalTxs := req.Txs + + if req.Height > ctx.ConsensusParams().Abci.VoteExtensionsEnableHeight { + stakeWeightedPrices, err := h.computeStakeWeightedOraclePrices(ctx, req.LocalLastCommit) + if err != nil { + return nil, errors.New("failed to compute stake-weighted oracle prices") + } + + injectedVoteExtTx := StakeWeightedPrices{ + StakeWeightedPrices: stakeWeightedPrices, + ExtendedCommitInfo: req.LocalLastCommit, + } +... +``` + +Finally we inject the result as a transaction at a specific location, usually at the beginning of the block: + +## Implement ProcessProposal + +Now we can implement the method that all validators will execute to ensure the proposer is doing his work correctly. + +Here, if vote extensions are enabled, we’ll check if the tx at index 0 is an injected vote extension + +```go +func (h *ProposalHandler) ProcessProposal() sdk.ProcessProposalHandler { + return func(ctx sdk.Context, req *abci.RequestProcessProposal) (*abci.ResponseProcessProposal, error) { + if req.Height > ctx.ConsensusParams().Abci.VoteExtensionsEnableHeight { + var injectedVoteExtTx StakeWeightedPrices + if err := json.Unmarshal(req.Txs[0], &injectedVoteExtTx); err != nil { + h.logger.Error("failed to decode injected vote extension tx", "err", err) + return &abci.ResponseProcessProposal{Status: abci.ResponseProcessProposal_REJECT}, nil + } +... +``` + +Then we re-validate the vote extensions signatures using +baseapp.ValidateVoteExtensions, re-calculate the results (just like in PrepareProposal) and compare them with the results we got from the injected tx. + +```go + err := baseapp.ValidateVoteExtensions(ctx, h.valStore, req.Height, ctx.ChainID(), injectedVoteExtTx.ExtendedCommitInfo) + if err != nil { + return nil, err + } + + // Verify the proposer's stake-weighted oracle prices by computing the same + // calculation and comparing the results. We omit verification for brevity + // and demo purposes. + stakeWeightedPrices, err := h.computeStakeWeightedOraclePrices(ctx, injectedVoteExtTx.ExtendedCommitInfo) + if err != nil { + return &abci.ResponseProcessProposal{Status: abci.ResponseProcessProposal_REJECT}, nil + } + + if err := compareOraclePrices(injectedVoteExtTx.StakeWeightedPrices, stakeWeightedPrices); err != nil { + return &abci.ResponseProcessProposal{Status: abci.ResponseProcessProposal_REJECT}, nil + } + } + + return &abci.ResponseProcessProposal{Status: abci.ResponseProcessProposal_ACCEPT}, nil + } +} +``` + +Important: In this example we avoided using the mempool and other basics, please refer to the DefaultProposalHandler for a complete implementation: [https://github.com/cosmos/cosmos-sdk/blob/v0.50.1/baseapp/abci_utils.go](https://github.com/cosmos/cosmos-sdk/blob/v0.50.1/baseapp/abci_utils.go) + +## Implement PreBlocker + +Now validators are extending their vote, verifying other votes and including the result in the block. But how do we actually make use of this result? This is done in the PreBlocker which is code that is run before any other code during FinalizeBlock so we make sure we make this information available to the chain and its modules during the entire block execution (from BeginBlock). + +At this step we know that the injected tx is well-formatted and has been verified by the validators participating in consensus, so making use of it is straightforward. Just check if vote extensions are enabled, pick up the first transaction and use a method in your module’s keeper to set the result. + +```go +func (h *ProposalHandler) PreBlocker(ctx sdk.Context, req *abci.RequestFinalizeBlock) (*sdk.ResponsePreBlock, error) { + res := &sdk.ResponsePreBlock{} + if len(req.Txs) == 0 { + return res, nil + } + + if req.Height > ctx.ConsensusParams().Abci.VoteExtensionsEnableHeight { + var injectedVoteExtTx StakeWeightedPrices + if err := json.Unmarshal(req.Txs[0], &injectedVoteExtTx); err != nil { + h.logger.Error("failed to decode injected vote extension tx", "err", err) + return nil, err + } + + // set oracle prices using the passed in context, which will make these prices available in the current block + if err := h.keeper.SetOraclePrices(ctx, injectedVoteExtTx.StakeWeightedPrices); err != nil { + return nil, err + } + } + return res, nil +} + +``` + +## Conclusion + +In this tutorial, we've created a simple price oracle module that incorporates vote extensions. We've seen how to implement `ExtendVote`, `VerifyVoteExtension`, `PrepareProposal`, `ProcessProposal`, and `PreBlocker` to handle the voting and verification process of vote extensions, as well as how to make use of the results during the block execution. diff --git a/versioned_docs/version-0.52/tutorials/vote-extensions/oracle/03-testing-oracle.md b/versioned_docs/version-0.52/tutorials/vote-extensions/oracle/03-testing-oracle.md new file mode 100644 index 000000000..905ca0d74 --- /dev/null +++ b/versioned_docs/version-0.52/tutorials/vote-extensions/oracle/03-testing-oracle.md @@ -0,0 +1,57 @@ +# Testing the Oracle Module + +We will guide you through the process of testing the Oracle module in your application. The Oracle module uses vote extensions to provide current price data. If you would like to see the complete working oracle module please see [here](https://github.com/cosmos/sdk-tutorials/blob/master/tutorials/oracle/base/x/oracle). + +## Step 1: Compile and Install the Application + +First, we need to compile and install the application. Please ensure you are in the `tutorials/oracle/base` directory. Run the following command in your terminal: + +```shell +make install +``` + +This command compiles the application and moves the resulting binary to a location in your system's PATH. + +## Step 2: Initialise the Application + +Next, we need to initialise the application. Run the following command in your terminal: + +```shell +make init +``` + +This command runs the script `tutorials/oracle/base/scripts/init.sh`, which sets up the necessary configuration for your application to run. This includes creating the `app.toml` configuration file and initialising the blockchain with a genesis block. + +## Step 3: Start the Application + +Now, we can start the application. Run the following command in your terminal: + +```shell +exampled start +``` + +This command starts your application, begins the blockchain node, and starts processing transactions. + +## Step 4: Query the Oracle Prices + +Finally, we can query the current prices from the Oracle module. Run the following command in your terminal: + +```shell +exampled q oracle prices +``` + +This command queries the current prices from the Oracle module. The expected output shows that the vote extensions were successfully included in the block and the Oracle module was able to retrieve the price data. + +## Understanding Vote Extensions in Oracle + +In the Oracle module, the `ExtendVoteHandler` function is responsible for creating the vote extensions. This function fetches the current prices from the provider, creates a `OracleVoteExtension` struct with these prices, and then marshals this struct into bytes. These bytes are then set as the vote extension. + +In the context of testing, the Oracle module uses a mock provider to simulate the behavior of a real price provider. This mock provider is defined in the mockprovider package and is used to return predefined prices for specific currency pairs. + +## Conclusion + +In this tutorial, we've delved into the concept of Oracle's in blockchain technology, focusing on their role in providing external data to a blockchain network. We've explored vote extensions, a powerful feature of ABCI++, and integrated them into a Cosmos SDK application to create a price oracle module. + +Through hands-on exercises, you've implemented vote extensions, and tested their effectiveness in providing timely and accurate asset price information. You've gained practical insights by setting up a mock provider for testing and analysing the process of extending votes, verifying vote extensions, and preparing and processing proposals. + +Keep experimenting with these concepts, engage with the community, and stay updated on new advancements. The knowledge you've acquired here is crucial for developing robust and reliable blockchain applications that can interact with real-world data. diff --git a/versioned_docs/version-0.52/tutorials/vote-extensions/oracle/_category_.json b/versioned_docs/version-0.52/tutorials/vote-extensions/oracle/_category_.json new file mode 100644 index 000000000..b63ffe2ff --- /dev/null +++ b/versioned_docs/version-0.52/tutorials/vote-extensions/oracle/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Oracle Tutorial", + "position": 1, + "link": null +} \ No newline at end of file diff --git a/versioned_docs/version-0.52/user/run-node/00-keyring.md b/versioned_docs/version-0.52/user/run-node/00-keyring.md new file mode 100644 index 000000000..b4a202006 --- /dev/null +++ b/versioned_docs/version-0.52/user/run-node/00-keyring.md @@ -0,0 +1,134 @@ +--- +sidebar_position: 1 +--- + +# Setting up the keyring + +:::note Synopsis +This document describes how to configure and use the keyring and its various backends for an [**application**](../../learn/beginner/00-app-anatomy.md). +::: + +The keyring holds the private/public keypairs used to interact with a node. For instance, a validator key needs to be set up before running the blockchain node, so that blocks can be correctly signed. The private key can be stored in different locations, called "backends", such as a file or the operating system's own key storage. + +## Available backends for the keyring + +Starting with the v0.38.0 release, Cosmos SDK comes with a new keyring implementation +that provides a set of commands to manage cryptographic keys in a secure fashion. The +new keyring supports multiple storage backends, some of which may not be available on +all operating systems. + +### The `os` backend + +The `os` backend relies on operating system-specific defaults to handle key storage +securely. Typically, an operating system's credential sub-system handles password prompts, +private keys storage, and user sessions according to the user's password policies. Here +is a list of the most popular operating systems and their respective passwords manager: + +* macOS: [Keychain](https://support.apple.com/en-gb/guide/keychain-access/welcome/mac) +* Windows: [Credentials Management API](https://docs.microsoft.com/en-us/windows/win32/secauthn/credentials-management) +* GNU/Linux: + * [libsecret](https://gitlab.gnome.org/GNOME/libsecret) + * [kwallet](https://api.kde.org/frameworks/kwallet/html/index.html) + +GNU/Linux distributions that use GNOME as default desktop environment typically come with +[Seahorse](https://wiki.gnome.org/Apps/Seahorse). Users of KDE based distributions are +commonly provided with [KDE Wallet Manager](https://userbase.kde.org/KDE_Wallet_Manager). +Whilst the former is in fact a `libsecret` convenient frontend, the latter is a `kwallet` +client. + +`os` is the default option since operating system's default credentials managers are +designed to meet users' most common needs and provide them with a comfortable +experience without compromising on security. + +The recommended backends for headless environments are `file` and `pass`. + +### The `file` backend + +The `file` backend more closely resembles the keybase implementation used prior to +v0.38.1. It stores the keyring encrypted within the app's configuration directory. This +keyring will request a password each time it is accessed, which may occur multiple +times in a single command resulting in repeated password prompts. If using bash scripts +to execute commands using the `file` option you may want to utilize the following format +for multiple prompts: + +```shell +# assuming that KEYPASSWD is set in the environment +$ gaiacli config keyring-backend file # use file backend +$ (echo $KEYPASSWD; echo $KEYPASSWD) | gaiacli keys add me # multiple prompts +$ echo $KEYPASSWD | gaiacli keys show me # single prompt +``` + +:::tip +The first time you add a key to an empty keyring, you will be prompted to type the password twice. +::: + +### The `pass` backend + +The `pass` backend uses the [pass](https://www.passwordstore.org/) utility to manage on-disk +encryption of keys' sensitive data and metadata. Keys are stored inside `gpg` encrypted files +within app-specific directories. `pass` is available for the most popular UNIX +operating systems as well as GNU/Linux distributions. Please refer to its manual page for +information on how to download and install it. + +:::tip +**pass** uses [GnuPG](https://gnupg.org/) for encryption. `gpg` automatically invokes the `gpg-agent` +daemon upon execution, which handles the caching of GnuPG credentials. Please refer to `gpg-agent` +man page for more information on how to configure cache parameters such as credentials TTL and +passphrase expiration. +::: + +The password store must be set up prior to first use: + +```shell +pass init +``` + +Replace `` with your GPG key ID. You can use your personal GPG key or an alternative +one you may want to use specifically to encrypt the password store. + +### The `kwallet` backend + +The `kwallet` backend uses `KDE Wallet Manager`, which comes installed by default on the +GNU/Linux distributions that ships KDE as default desktop environment. Please refer to +[KWallet Handbook](https://docs.kde.org/stable5/en/kdeutils/kwallet5/index.html) for more +information. + +### The `test` backend + +The `test` backend is a password-less variation of the `file` backend. Keys are stored +unencrypted on disk. + +**Provided for testing purposes only. The `test` backend is not recommended for use in production environments**. + +### The `memory` backend + +The `memory` backend stores keys in memory. The keys are immediately deleted after the program has exited. + +**Provided for testing purposes only. The `memory` backend is not recommended for use in production environments**. + +### Setting backend using the env variable + +You can set the keyring-backend using env variable: `BINNAME_KEYRING_BACKEND`. For example, if your binary name is `gaia-v5` then set: `export GAIA_V5_KEYRING_BACKEND=pass` + +## Adding keys to the keyring + +:::warning +Make sure you can build your own binary, and replace `simd` with the name of your binary in the snippets. +::: + +Applications developed using the Cosmos SDK come with the `keys` subcommand. For the purpose of this tutorial, we're running the `simd` CLI, which is an application built using the Cosmos SDK for testing and educational purposes. For more information, see [`simapp`](https://github.com/cosmos/cosmos-sdk/tree/main/simapp). + +You can use `simd keys` for help about the keys command and `simd keys [command] --help` for more information about a particular subcommand. + +To create a new key in the keyring, run the `add` subcommand with a `` argument. For the purpose of this tutorial, we will solely use the `test` backend, and call our new key `my_validator`. This key will be used in the next section. + +```bash +$ simd keys add my_validator --keyring-backend test + +# Put the generated address in a variable for later use. +MY_VALIDATOR_ADDRESS=$(simd keys show my_validator -a --keyring-backend test) +``` + +This command generates a new 24-word mnemonic phrase, persists it to the relevant backend, and outputs information about the keypair. If this keypair will be used to hold value-bearing tokens, be sure to write down the mnemonic phrase somewhere safe! + +By default, the keyring generates a `secp256k1` keypair. The keyring also supports `ed25519` keys, which may be created by passing the `--algo ed25519` flag. A keyring can of course hold both types of keys simultaneously, and the Cosmos SDK's `x/auth` module supports natively these two public key algorithms. diff --git a/versioned_docs/version-0.52/user/run-node/01-run-node.md b/versioned_docs/version-0.52/user/run-node/01-run-node.md new file mode 100644 index 000000000..9b1dfb4eb --- /dev/null +++ b/versioned_docs/version-0.52/user/run-node/01-run-node.md @@ -0,0 +1,228 @@ +--- +sidebar_position: 1 +--- + +# Running a Node + +:::note Synopsis +Now that the application is ready and the keyring populated, it's time to see how to run the blockchain node. In this section, the application we are running is called [`simapp`](https://github.com/cosmos/cosmos-sdk/tree/main/simapp), and its corresponding CLI binary `simd`. +::: + +:::note Pre-requisite Readings + +* [Anatomy of a Cosmos SDK Application](../../learn/beginner/00-app-anatomy.md) +* [Setting up the keyring](./00-keyring.md) + +::: + +## Initialize the Chain + +:::warning +Make sure you can build your own binary, and replace `simd` with the name of your binary in the snippets. +::: + +Before actually running the node, we need to initialize the chain, and most importantly its genesis file. This is done with the `init` subcommand: + +```bash +# The argument is the custom username of your node, it should be human-readable. +simd init --chain-id my-test-chain +``` + +The command above creates all the configuration files needed for your node to run, as well as a default genesis file, which defines the initial state of the network. + +:::tip +All these configuration files are in `~/.simapp` by default, but you can overwrite the location of this folder by passing the `--home` flag to each commands, +or set an `$APPD_HOME` environment variable (where `APPD` is the name of the binary). +::: + +The `~/.simapp` folder has the following structure: + +```bash +. # ~/.simapp + |- data # Contains the databases used by the node. + |- config/ + |- app.toml # Application-related configuration file. + |- config.toml # CometBFT-related configuration file. + |- genesis.json # The genesis file. + |- node_key.json # Private key to use for node authentication in the p2p protocol. + |- priv_validator_key.json # Private key to use as a validator in the consensus protocol. +``` + +## Updating Some Default Settings + +If you want to change any field values in configuration files (for ex: genesis.json) you can use `jq` ([installation](https://stedolan.github.io/jq/download/) & [docs](https://stedolan.github.io/jq/manual/#Assignment)) & `sed` commands to do that. Few examples are listed here. + +```bash +# to change the chain-id +jq '.chain_id = "testing"' genesis.json > temp.json && mv temp.json genesis.json + +# to enable the api server +sed -i '/\[api\]/,+3 s/enable = false/enable = true/' app.toml + +# to change the voting_period +jq '.app_state.gov.voting_params.voting_period = "600s"' genesis.json > temp.json && mv temp.json genesis.json + +# to change the inflation +jq '.app_state.mint.minter.inflation = "0.300000000000000000"' genesis.json > temp.json && mv temp.json genesis.json +``` + +### Client Interaction + +When instantiating a node, GRPC and REST are defaulted to localhost to avoid unknown exposure of your node to the public. It is recommended to not expose these endpoints without a proxy that can handle load balancing or authentication is setup between your node and the public. + +:::tip +A commonly used tool for this is [nginx](https://nginx.org). +::: + + +## Adding Genesis Accounts + +Before starting the chain, you need to populate the state with at least one account. To do so, first [create a new account in the keyring](./00-keyring.md#adding-keys-to-the-keyring) named `my_validator` under the `test` keyring backend (feel free to choose another name and another backend). + +Now that you have created a local account, go ahead and grant it some `stake` tokens in your chain's genesis file. Doing so will also make sure your chain is aware of this account's existence: + +```bash +simd genesis add-genesis-account $MY_VALIDATOR_ADDRESS 100000000000stake +``` + +Recall that `$MY_VALIDATOR_ADDRESS` is a variable that holds the address of the `my_validator` key in the [keyring](./00-keyring.md#adding-keys-to-the-keyring). Also note that the tokens in the Cosmos SDK have the `{amount}{denom}` format: `amount` is an 18-digit-precision decimal number, and `denom` is the unique token identifier with its denomination key (e.g. `atom` or `uatom`). Here, we are granting `stake` tokens, as `stake` is the token identifier used for staking in [`simapp`](https://github.com/cosmos/cosmos-sdk/tree/main/simapp). For your own chain with its own staking denom, that token identifier should be used instead. + +Now that your account has some tokens, you need to add a validator to your chain. Validators are special full-nodes that participate in the consensus process (implemented in the [underlying consensus engine](../../learn/intro/02-sdk-app-architecture.md#cometbft)) in order to add new blocks to the chain. Any account can declare its intention to become a validator operator, but only those with sufficient delegation get to enter the active set (for example, only the top 125 validator candidates with the most delegation get to be validators in the Cosmos Hub). For this guide, you will add your local node (created via the `init` command above) as a validator of your chain. Validators can be declared before a chain is first started via a special transaction included in the genesis file called a `gentx`: + +```bash +# Create a gentx. +simd genesis gentx my_validator 100000000stake --chain-id my-test-chain --keyring-backend test + +# Add the gentx to the genesis file. +simd genesis collect-gentxs +``` + +A `gentx` does three things: + +1. Registers the `validator` account you created as a validator operator account (i.e. the account that controls the validator). +2. Self-delegates the provided `amount` of staking tokens. +3. Link the operator account with a CometBFT node pubkey that will be used for signing blocks. If no `--pubkey` flag is provided, it defaults to the local node pubkey created via the `simd init` command above. + +For more information on `gentx`, use the following command: + +```bash +simd genesis gentx --help +``` + +## Configuring the Node Using `app.toml` and `config.toml` + +The Cosmos SDK automatically generates two configuration files inside `~/.simapp/config`: + +* `config.toml`: used to configure the CometBFT, learn more on [CometBFT's documentation](https://docs.cometbft.com/v0.37/core/configuration), +* `app.toml`: generated by the Cosmos SDK, and used to configure your app, such as state pruning strategies, telemetry, gRPC and REST servers configuration, state sync... + +Both files are heavily commented, please refer to them directly to tweak your node. + +One example config to tweak is the `minimum-gas-prices` field inside `app.toml`, which defines the minimum gas prices the validator node is willing to accept for processing a transaction. Depending on the chain, it might be an empty string or not. If it's empty, make sure to edit the field with some value, for example `10token`, or else the node will halt on startup. For the purpose of this tutorial, let's set the minimum gas price to 0: + +```toml + # The minimum gas prices a validator is willing to accept for processing a + # transaction. A transaction's fees must meet the minimum of any denomination + # specified in this config (e.g. 0.25token1;0.0001token2). + minimum-gas-prices = "0stake" +``` + +:::tip +When running a node (not a validator!) and not wanting to run the application mempool, set the `max-txs` field to `-1`. + +```toml +[mempool] +# Setting max-txs to 0 will allow for a unbounded amount of transactions in the mempool. +# Setting max_txs to negative 1 (-1) will disable transactions from being inserted into the mempool. +# Setting max_txs to a positive number (> 0) will limit the number of transactions in the mempool, by the specified amount. +# +# Note, this configuration only applies to SDK built-in app-side mempool +# implementations. +max-txs = "-1" +``` + +::: + +## Run a Localnet + +Now that everything is set up, you can finally start your node: + +```bash +simd start +``` + +You should see blocks come in. + +The previous command allow you to run a single node. This is enough for the next section on interacting with this node, but you may wish to run multiple nodes at the same time, and see how consensus happens between them. + +The naive way would be to run the same commands again in separate terminal windows. This is possible, however in the Cosmos SDK, we leverage the power of [Docker Compose](https://docs.docker.com/compose/) to run a localnet. If you need inspiration on how to set up your own localnet with Docker Compose, you can have a look at the Cosmos SDK's [`docker-compose.yml`](https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/docker-compose.yml). + +### Standalone App/CometBFT + +By default, the Cosmos SDK runs CometBFT in-process with the application +If you want to run the application and CometBFT in separate processes, +start the application with the `--with-comet=false` flag +and set `rpc.laddr` in `config.toml` to the CometBFT node's RPC address. + +## Logging + +Logging provides a way to see what is going on with a node. By default the `info` level is set. This is a global level and all info logs will be outputted to the terminal. + +If you would like to filter specific logs to the terminal instead of all, then setting `:` is how this can work. +Example: + +In `config.toml`: + +```toml +log_level: "state:info,p2p:info,consensus:info,x/staking:info,x/ibc:info,*:error" +``` + +Or directly in the command line: + +```bash + start --log_level "state:info,p2p:info,consensus:info,x/staking:info,x/ibc:info,*:error" +``` + +The above will show info logs for the state, p2p, consensus, staking, and ibc modules, and error logs for all other modules. +When no log filtering is required, simply use one of the supported global log levels: `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `panic` or `disabled`. + +## State Sync + +State sync is the act in which a node syncs the latest or close to the latest state of a blockchain. This is useful for users who don't want to sync all the blocks in history. Read more in [CometBFT documentation](https://docs.cometbft.com/v0.37/core/state-sync). + +State sync works thanks to snapshots. Read how the SDK handles snapshots [here](https://github.com/cosmos/cosmos-sdk/blob/825245d/store/snapshots/README.md). + +### Local State Sync + +Local state sync work similar to normal state sync except that it works off a local snapshot of state instead of one provided via the p2p network. The steps to start local state sync are similar to normal state sync with a few different designs. + +1. As mentioned in https://docs.cometbft.com/v0.37/core/state-sync, one must set a height and hash in the config.toml along with a few rpc servers (the afromentioned link has instructions on how to do this). +2. Run ` ` to restore a local snapshot (note: first load it from a file with the *load* command). +3. Bootsrapping Comet state in order to start the node after the snapshot has been ingested. This can be done with the bootstrap command ` comet bootstrap-state` + +### Snapshots Commands + +The Cosmos SDK provides commands for managing snapshots. +These commands can be added in an app with the following snippet in `cmd//root.go`: + +```go +import ( + "github.com/cosmos/cosmos-sdk/client/snapshot" +) + +func initRootCmd(/* ... */) { + // ... + rootCmd.AddCommand( + snapshot.Cmd(appCreator), + ) +} +``` + +Then following commands are available at ` snapshots [command]`: + +* **list**: list local snapshots +* **load**: Load a snapshot archive file into snapshot store +* **restore**: Restore app state from local snapshot +* **export**: Export app state to snapshot store +* **dump**: Dump the snapshot as portable archive format +* **delete**: Delete a local snapshot diff --git a/versioned_docs/version-0.52/user/run-node/02-interact-node.md b/versioned_docs/version-0.52/user/run-node/02-interact-node.md new file mode 100644 index 000000000..a511aec41 --- /dev/null +++ b/versioned_docs/version-0.52/user/run-node/02-interact-node.md @@ -0,0 +1,289 @@ +--- +sidebar_position: 1 +--- + +# Interacting with the Node + +:::note Synopsis +There are multiple ways to interact with a node: using the CLI, using gRPC or using the REST endpoints. +::: + +:::note Pre-requisite Readings + +* [gRPC, REST and CometBFT Endpoints](../../learn/advanced/06-grpc_rest.md) +* [Running a Node](./01-run-node.md) + +::: + +## Using the CLI + +Now that your chain is running, it is time to try sending tokens from the first account you created to a second account. In a new terminal window, start by running the following query command: + +```bash +simd query bank balances $MY_VALIDATOR_ADDRESS +``` + +You should see the current balance of the account you created, equal to the original balance of `stake` you granted it minus the amount you delegated via the `gentx`. Now, create a second account: + +```bash +simd keys add recipient --keyring-backend test + +# Put the generated address in a variable for later use. +RECIPIENT=$(simd keys show recipient -a --keyring-backend test) +``` + +The command above creates a local key-pair that is not yet registered on the chain. An account is created the first time it receives tokens from another account. Now, run the following command to send tokens to the `recipient` account: + +```bash +simd tx bank send $MY_VALIDATOR_ADDRESS $RECIPIENT 1000000stake --chain-id my-test-chain --keyring-backend test + +# Check that the recipient account did receive the tokens. +simd query bank balances $RECIPIENT +``` + +Finally, delegate some of the stake tokens sent to the `recipient` account to the validator: + +```bash +simd tx staking delegate $(simd keys show my_validator --bech val -a --keyring-backend test) 500stake --from recipient --chain-id my-test-chain --keyring-backend test + +# Query the total delegations to `validator`. +simd query staking delegations-to $(simd keys show my_validator --bech val -a --keyring-backend test) +``` + +You should see two delegations, the first one made from the `gentx`, and the second one you just performed from the `recipient` account. + +## Using gRPC + +The Protobuf ecosystem developed tools for different use cases, including code-generation from `*.proto` files into various languages. These tools allow the building of clients easily. Often, the client connection (i.e. the transport) can be plugged and replaced very easily. Let's explore one of the most popular transport: [gRPC](../../learn/advanced/06-grpc_rest.md). + +Since the code generation library largely depends on your own tech stack, we will only present three alternatives: + +* `grpcurl` for generic debugging and testing, +* programmatically via Go, +* CosmJS for JavaScript/TypeScript developers. + +### grpcurl + +[grpcurl](https://github.com/fullstorydev/grpcurl) is like `curl` but for gRPC. It is also available as a Go library, but we will use it only as a CLI command for debugging and testing purposes. Follow the instructions in the previous link to install it. + +Assuming you have a local node running (either a localnet, or connected a live network), you should be able to run the following command to list the Protobuf services available (you can replace `localhost:9000` by the gRPC server endpoint of another node, which is configured under the `grpc.address` field inside [`app.toml`](../run-node/01-run-node.md#configuring-the-node-using-apptoml-and-configtoml)): + +```bash +grpcurl -plaintext localhost:9090 list +``` + +You should see a list of gRPC services, like `cosmos.bank.v1beta1.Query`. This is called reflection, which is a Protobuf endpoint returning a description of all available endpoints. Each of these represents a different Protobuf service, and each service exposes multiple RPC methods you can query against. + +In order to get a description of the service you can run the following command: + +```bash +grpcurl -plaintext \ + localhost:9090 \ + describe cosmos.bank.v1beta1.Query # Service we want to inspect +``` + +It's also possible to execute an RPC call to query the node for information: + +```bash +grpcurl \ + -plaintext \ + -d "{\"address\":\"$MY_VALIDATOR_ADDRESS\"}" \ + localhost:9090 \ + cosmos.bank.v1beta1.Query/AllBalances +``` + +The list of all available gRPC query endpoints is [coming soon](https://github.com/cosmos/cosmos-sdk/issues/7786). + +#### Query for historical state using grpcurl + +You may also query for historical data by passing some [gRPC metadata](https://github.com/grpc/grpc-go/blob/master/Documentation/grpc-metadata.md) to the query: the `x-cosmos-block-height` metadata should contain the block to query. Using grpcurl as above, the command looks like: + +```bash +grpcurl \ + -plaintext \ + -H "x-cosmos-block-height: 123" \ + -d "{\"address\":\"$MY_VALIDATOR_ADDRESS\"}" \ + localhost:9090 \ + cosmos.bank.v1beta1.Query/AllBalances +``` + +Assuming the state at that block has not yet been pruned by the node, this query should return a non-empty response. + +### Programmatically via Go + +The following snippet shows how to query the state using gRPC inside a Go program. The idea is to create a gRPC connection, and use the Protobuf-generated client code to query the gRPC server. + +#### Install Cosmos SDK + + +```bash +go get github.com/cosmos/cosmos-sdk@main +``` + +```go +package main + +import ( + "context" + "fmt" + + "google.golang.org/grpc" + + "github.com/cosmos/cosmos-sdk/codec" + sdk "github.com/cosmos/cosmos-sdk/types" + banktypes "github.com/cosmos/cosmos-sdk/x/bank/types" +) + +func queryState() error { + myAddress, err := sdk.AccAddressFromBech32("cosmos1...") // the my_validator or recipient address. + if err != nil { + return err + } + + // Create a connection to the gRPC server. + grpcConn, err := grpc.Dial( + "127.0.0.1:9090", // your gRPC server address. + grpc.WithInsecure(), // The Cosmos SDK doesn't support any transport security mechanism. + // This instantiates a general gRPC codec which handles proto bytes. We pass in a nil interface registry + // if the request/response types contain interface instead of 'nil' you should pass the application specific codec. + grpc.WithDefaultCallOptions(grpc.ForceCodec(codec.NewProtoCodec(nil).GRPCCodec())), + ) + if err != nil { + return err + } + defer grpcConn.Close() + + // This creates a gRPC client to query the x/bank service. + bankClient := banktypes.NewQueryClient(grpcConn) + bankRes, err := bankClient.Balance( + context.Background(), + &banktypes.QueryBalanceRequest{Address: myAddress.String(), Denom: "stake"}, + ) + if err != nil { + return err + } + + fmt.Println(bankRes.GetBalance()) // Prints the account balance + + return nil +} + +func main() { + if err := queryState(); err != nil { + panic(err) + } +} +``` + +You can replace the query client (here we are using `x/bank`'s) with one generated from any other Protobuf service. The list of all available gRPC query endpoints is [coming soon](https://github.com/cosmos/cosmos-sdk/issues/7786). + +#### Query for historical state using Go + +Querying for historical blocks is done by adding the block height metadata in the gRPC request. + +```go +package main + +import ( + "context" + "fmt" + + "google.golang.org/grpc" + "google.golang.org/grpc/metadata" + + "github.com/cosmos/cosmos-sdk/codec" + sdk "github.com/cosmos/cosmos-sdk/types" + grpctypes "github.com/cosmos/cosmos-sdk/types/grpc" + banktypes "github.com/cosmos/cosmos-sdk/x/bank/types" +) + +func queryState() error { + myAddress, err := sdk.AccAddressFromBech32("cosmos1yerherx4d43gj5wa3zl5vflj9d4pln42n7kuzu") // the my_validator or recipient address. + if err != nil { + return err + } + + // Create a connection to the gRPC server. + grpcConn, err := grpc.Dial( + "127.0.0.1:9090", // your gRPC server address. + grpc.WithInsecure(), // The Cosmos SDK doesn't support any transport security mechanism. + // This instantiates a general gRPC codec which handles proto bytes. We pass in a nil interface registry + // if the request/response types contain interface instead of 'nil' you should pass the application specific codec. + grpc.WithDefaultCallOptions(grpc.ForceCodec(codec.NewProtoCodec(nil).GRPCCodec())), + ) + if err != nil { + return err + } + defer grpcConn.Close() + + // This creates a gRPC client to query the x/bank service. + bankClient := banktypes.NewQueryClient(grpcConn) + + var header metadata.MD + _, err = bankClient.Balance( + metadata.AppendToOutgoingContext(context.Background(), grpctypes.GRPCBlockHeightHeader, "12"), // Add metadata to request + &banktypes.QueryBalanceRequest{Address: myAddress.String(), Denom: "stake"}, + grpc.Header(&header), // Retrieve header from response + ) + if err != nil { + return err + } + blockHeight := header.Get(grpctypes.GRPCBlockHeightHeader) + + fmt.Println(blockHeight) // Prints the block height (12) + + return nil +} + +func main() { + if err := queryState(); err != nil { + panic(err) + } +} +``` + +### CosmJS + +CosmJS documentation can be found at [https://cosmos.github.io/cosmjs](https://cosmos.github.io/cosmjs). As of January 2021, CosmJS documentation is still work in progress. + +## Using the REST Endpoints + +As described in the [gRPC guide](../../learn/advanced/06-grpc_rest.md), all gRPC services on the Cosmos SDK are made available for more convenient REST-based queries through gRPC-gateway. The format of the URL path is based on the Protobuf service method's full-qualified name, but may contain small customizations so that final URLs look more idiomatic. For example, the REST endpoint for the `cosmos.bank.v1beta1.Query/AllBalances` method is `GET /cosmos/bank/v1beta1/balances/{address}`. Request arguments are passed as query parameters. + +Note that the REST endpoints are not enabled by default. To enable them, edit the `api` section of your `~/.simapp/config/app.toml` file: + +```toml +# Enable defines if the API server should be enabled. +enable = true +``` + +As a concrete example, the `curl` command to make balances request is: + +```bash +curl \ + -X GET \ + -H "Content-Type: application/json" \ + http://localhost:1317/cosmos/bank/v1beta1/balances/$MY_VALIDATOR_ADDRESS +``` + +Make sure to replace `localhost:1317` with the REST endpoint of your node, configured under the `api.address` field. + +The list of all available REST endpoints is available as a Swagger specification file, it can be viewed at `localhost:1317/swagger`. Make sure that the `api.swagger` field is set to true in your [`app.toml`](../run-node/01-run-node.md#configuring-the-node-using-apptoml-and-configtoml) file. + +### Query for historical state using REST + +Querying for historical state is done using the HTTP header `x-cosmos-block-height`. For example, a curl command would look like: + +```bash +curl \ + -X GET \ + -H "Content-Type: application/json" \ + -H "x-cosmos-block-height: 123" \ + http://localhost:1317/cosmos/bank/v1beta1/balances/$MY_VALIDATOR_ADDRESS +``` + +Assuming the state at that block has not yet been pruned by the node, this query should return a non-empty response. + +### Cross-Origin Resource Sharing (CORS) + +[CORS policies](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) are not enabled by default to help with security. If you would like to use the rest-server in a public environment we recommend you provide a reverse proxy, this can be done with [nginx](https://www.nginx.com/). For testing and development purposes there is an `enabled-unsafe-cors` field inside [`app.toml`](../run-node/01-run-node.md#configuring-the-node-using-apptoml-and-configtoml). diff --git a/versioned_docs/version-0.52/user/run-node/03-txs.md b/versioned_docs/version-0.52/user/run-node/03-txs.md new file mode 100644 index 000000000..106f02e8e --- /dev/null +++ b/versioned_docs/version-0.52/user/run-node/03-txs.md @@ -0,0 +1,387 @@ +--- +sidebar_position: 1 +--- + +# Generating, Signing and Broadcasting Transactions + +:::note Synopsis +This document describes how to generate an (unsigned) transaction, signing it (with one or multiple keys), and broadcasting it to the network. +::: + +## Using the CLI + +The easiest way to send transactions is using the CLI, as we have seen in the previous page when [interacting with a node](./02-interact-node.md#using-the-cli). For example, running the following command + +```bash +simd tx bank send $MY_VALIDATOR_ADDRESS $RECIPIENT 1000stake --chain-id my-test-chain --keyring-backend test +``` + +will run the following steps: + +* generate a transaction with one `Msg` (`x/bank`'s `MsgSend`), and print the generated transaction to the console. +* ask the user for confirmation to send the transaction from the `$MY_VALIDATOR_ADDRESS` account. +* fetch `$MY_VALIDATOR_ADDRESS` from the keyring. This is possible because we have [set up the CLI's keyring](./00-keyring.md) in a previous step. +* sign the generated transaction with the keyring's account. +* broadcast the signed transaction to the network. This is possible because the CLI connects to the node's CometBFT RPC endpoint. + +The CLI bundles all the necessary steps into a simple-to-use user experience. However, it's possible to run all the steps individually too. + +### Generating a Transaction + +Generating a transaction can simply be done by appending the `--generate-only` flag on any `tx` command, e.g.: + +```bash +simd tx bank send $MY_VALIDATOR_ADDRESS $RECIPIENT 1000stake --chain-id my-test-chain --generate-only +``` + +This will output the unsigned transaction as JSON in the console. We can also save the unsigned transaction to a file (to be passed around between signers more easily) by appending `> unsigned_tx.json` to the above command. + +### Signing a Transaction + +Signing a transaction using the CLI requires the unsigned transaction to be saved in a file. Let's assume the unsigned transaction is in a file called `unsigned_tx.json` in the current directory (see previous paragraph on how to do that). Then, simply run the following command: + +```bash +simd tx sign unsigned_tx.json --chain-id my-test-chain --keyring-backend test --from $MY_VALIDATOR_ADDRESS +``` + +This command will decode the unsigned transaction and sign it with `SIGN_MODE_DIRECT` with `$MY_VALIDATOR_ADDRESS`'s key, which we already set up in the keyring. The signed transaction will be output as JSON to the console, and, as above, we can save it to a file by appending `--output-document signed_tx.json`. + +Some useful flags to consider in the `tx sign` command: + +* `--sign-mode`: you may use `amino-json` to sign the transaction using `SIGN_MODE_LEGACY_AMINO_JSON`, +* `--offline`: sign in offline mode. This means that the `tx sign` command doesn't connect to the node to retrieve the signer's account number and sequence, both needed for signing. In this case, you must manually supply the `--account-number` and `--sequence` flags. This is useful for offline signing, i.e. signing in a secure environment which doesn't have access to the internet. + +#### Signing with Multiple Signers + +:::warning +Please note that signing a transaction with multiple signers or with a multisig account, where at least one signer uses `SIGN_MODE_DIRECT`, is not yet possible. You may follow [this Github issue](https://github.com/cosmos/cosmos-sdk/issues/8141) for more info. +::: + +Signing with multiple signers is done with the `tx multisign` command. This command assumes that all signers use `SIGN_MODE_LEGACY_AMINO_JSON`. The flow is similar to the `tx sign` command flow, but instead of signing an unsigned transaction file, each signer signs the file signed by previous signer(s). The `tx multisign` command will append signatures to the existing transactions. It is important that signers sign the transaction **in the same order** as given by the transaction, which is retrievable using the `GetSigners()` method. + +For example, starting with the `unsigned_tx.json`, and assuming the transaction has 4 signers, we would run: + +```bash +# Let signer1 sign the unsigned tx. +simd tx multisign unsigned_tx.json signer_key_1 --chain-id my-test-chain --keyring-backend test > partial_tx_1.json +# Now signer1 will send the partial_tx_1.json to the signer2. +# Signer2 appends their signature: +simd tx multisign partial_tx_1.json signer_key_2 --chain-id my-test-chain --keyring-backend test > partial_tx_2.json +# Signer2 sends the partial_tx_2.json file to signer3, and signer3 can append his signature: +simd tx multisign partial_tx_2.json signer_key_3 --chain-id my-test-chain --keyring-backend test > partial_tx_3.json +``` + +### Broadcasting a Transaction + +Broadcasting a transaction is done using the following command: + +```bash +simd tx broadcast tx_signed.json +``` + +You may optionally pass the `--broadcast-mode` flag to specify which response to receive from the node: + +* `sync`: the CLI waits for a CheckTx execution response only. +* `async`: the CLI returns immediately (transaction might fail). + +### Encoding a Transaction + +In order to broadcast a transaction using the gRPC or REST endpoints, the transaction will need to be encoded first. This can be done using the CLI. + +Encoding a transaction is done using the following command: + +```bash +simd tx encode tx_signed.json +``` + +This will read the transaction from the file, serialize it using Protobuf, and output the transaction bytes as base64 in the console. + +### Decoding a Transaction + +The CLI can also be used to decode transaction bytes. + +Decoding a transaction is done using the following command: + +```bash +simd tx decode [protobuf-byte-string] +``` + +This will decode the transaction bytes and output the transaction as JSON in the console. You can also save the transaction to a file by appending `> tx.json` to the above command. + +## Programmatically with Go + +It is possible to manipulate transactions programmatically via Go using the Cosmos SDK's `TxBuilder` interface. + +### Generating a Transaction + +Before generating a transaction, a new instance of a `TxBuilder` needs to be created. Since the Cosmos SDK supports both Amino and Protobuf transactions, the first step would be to decide which encoding scheme to use. All the subsequent steps remain unchanged, whether you're using Amino or Protobuf, as `TxBuilder` abstracts the encoding mechanisms. In the following snippet, we will use Protobuf. + +```go +import ( + "github.com/cosmos/cosmos-sdk/simapp" +) + +func sendTx() error { + // Choose your codec: Amino or Protobuf. Here, we use Protobuf, given by the following function. + app := simapp.NewSimApp(...) + + // Create a new TxBuilder. + txBuilder := app.TxConfig().NewTxBuilder() + + // --snip-- +} +``` + +We can also set up some keys and addresses that will send and receive the transactions. Here, for the purpose of the tutorial, we will be using some dummy data to create keys. + +```go +import ( + "github.com/cosmos/cosmos-sdk/testutil/testdata" +) + +priv1, _, addr1 := testdata.KeyTestPubAddr() +priv2, _, addr2 := testdata.KeyTestPubAddr() +priv3, _, addr3 := testdata.KeyTestPubAddr() +``` + +Populating the `TxBuilder` can be done via its methods: + +```go reference +https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/client/tx_config.go#L33-L50 +``` + +```go +import ( + banktypes "github.com/cosmos/cosmos-sdk/x/bank/types" +) + +func sendTx() error { + // --snip-- + + // Define two x/bank MsgSend messages: + // - from addr1 to addr3, + // - from addr2 to addr3. + // This means that the transactions needs two signers: addr1 and addr2. + msg1 := banktypes.NewMsgSend(addr1, addr3, types.NewCoins(types.NewInt64Coin("atom", 12))) + msg2 := banktypes.NewMsgSend(addr2, addr3, types.NewCoins(types.NewInt64Coin("atom", 34))) + + err := txBuilder.SetMsgs(msg1, msg2) + if err != nil { + return err + } + + txBuilder.SetGasLimit(...) + txBuilder.SetFeeAmount(...) + txBuilder.SetMemo(...) + txBuilder.SetTimeoutHeight(...) +} +``` + +At this point, `TxBuilder`'s underlying transaction is ready to be signed. + +### Signing a Transaction + +We set encoding config to use Protobuf, which will use `SIGN_MODE_DIRECT` by default. As per [ADR-020](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-020-protobuf-transaction-encoding.md), each signer needs to sign the `SignerInfo`s of all other signers. This means that we need to perform two steps sequentially: + +* for each signer, populate the signer's `SignerInfo` inside `TxBuilder`, +* once all `SignerInfo`s are populated, for each signer, sign the `SignDoc` (the payload to be signed). + +In the current `TxBuilder`'s API, both steps are done using the same method: `SetSignatures()`. The current API requires us to first perform a round of `SetSignatures()` _with empty signatures_, only to populate `SignerInfo`s, and a second round of `SetSignatures()` to actually sign the correct payload. + +```go +import ( + cryptotypes "github.com/cosmos/cosmos-sdk/crypto/types" + "github.com/cosmos/cosmos-sdk/types/tx/signing" + xauthsigning "github.com/cosmos/cosmos-sdk/x/auth/signing" +) + +func sendTx() error { + // --snip-- + + privs := []cryptotypes.PrivKey{priv1, priv2} + accNums:= []uint64{..., ...} // The accounts' account numbers + accSeqs:= []uint64{..., ...} // The accounts' sequence numbers + + // First round: we gather all the signer infos. We use the "set empty + // signature" hack to do that. + var sigsV2 []signing.SignatureV2 + for i, priv := range privs { + sigV2 := signing.SignatureV2{ + PubKey: priv.PubKey(), + Data: &signing.SingleSignatureData{ + SignMode: encCfg.TxConfig.SignModeHandler().DefaultMode(), + Signature: nil, + }, + Sequence: accSeqs[i], + } + + sigsV2 = append(sigsV2, sigV2) + } + err := txBuilder.SetSignatures(sigsV2...) + if err != nil { + return err + } + + // Second round: all signer infos are set, so each signer can sign. + sigsV2 = []signing.SignatureV2{} + for i, priv := range privs { + signerData := xauthsigning.SignerData{ + ChainID: chainID, + AccountNumber: accNums[i], + Sequence: accSeqs[i], + } + sigV2, err := tx.SignWithPrivKey( + encCfg.TxConfig.SignModeHandler().DefaultMode(), signerData, + txBuilder, priv, encCfg.TxConfig, accSeqs[i]) + if err != nil { + return nil, err + } + + sigsV2 = append(sigsV2, sigV2) + } + err = txBuilder.SetSignatures(sigsV2...) + if err != nil { + return err + } +} +``` + +The `TxBuilder` is now correctly populated. To print it, you can use the `TxConfig` interface from the initial encoding config `encCfg`: + +```go +func sendTx() error { + // --snip-- + + // Generated Protobuf-encoded bytes. + txBytes, err := encCfg.TxConfig.TxEncoder()(txBuilder.GetTx()) + if err != nil { + return err + } + + // Generate a JSON string. + txJSONBytes, err := encCfg.TxConfig.TxJSONEncoder()(txBuilder.GetTx()) + if err != nil { + return err + } + txJSON := string(txJSONBytes) +} +``` + +### Broadcasting a Transaction + +The preferred way to broadcast a transaction is to use gRPC, though using REST (via `gRPC-gateway`) or the CometBFT RPC is also posible. An overview of the differences between these methods is exposed [here](../../learn/advanced/06-grpc_rest.md). For this tutorial, we will only describe the gRPC method. + +```go +import ( + "context" + "fmt" + + "google.golang.org/grpc" + + "github.com/cosmos/cosmos-sdk/types/tx" +) + +func sendTx(ctx context.Context) error { + // --snip-- + + // Create a connection to the gRPC server. + grpcConn := grpc.Dial( + "127.0.0.1:9090", // Or your gRPC server address. + grpc.WithInsecure(), // The Cosmos SDK doesn't support any transport security mechanism. + ) + defer grpcConn.Close() + + // Broadcast the tx via gRPC. We create a new client for the Protobuf Tx + // service. + txClient := tx.NewServiceClient(grpcConn) + // We then call the BroadcastTx method on this client. + grpcRes, err := txClient.BroadcastTx( + ctx, + &tx.BroadcastTxRequest{ + Mode: tx.BroadcastMode_BROADCAST_MODE_SYNC, + TxBytes: txBytes, // Proto-binary of the signed transaction, see previous step. + }, + ) + if err != nil { + return err + } + + fmt.Println(grpcRes.TxResponse.Code) // Should be `0` if the tx is successful + + return nil +} +``` + +#### Simulating a Transaction + +Before broadcasting a transaction, we sometimes may want to dry-run the transaction, to estimate some information about the transaction without actually committing it. This is called simulating a transaction, and can be done as follows: + +```go +import ( + "context" + "fmt" + "testing" + + "github.com/cosmos/cosmos-sdk/client" + "github.com/cosmos/cosmos-sdk/types/tx" + authtx "github.com/cosmos/cosmos-sdk/x/auth/tx" +) + +func simulateTx() error { + // --snip-- + + // Simulate the tx via gRPC. We create a new client for the Protobuf Tx + // service. + txClient := tx.NewServiceClient(grpcConn) + txBytes := /* Fill in with your signed transaction bytes. */ + + // We then call the Simulate method on this client. + grpcRes, err := txClient.Simulate( + context.Background(), + &tx.SimulateRequest{ + TxBytes: txBytes, + }, + ) + if err != nil { + return err + } + + fmt.Println(grpcRes.GasInfo) // Prints estimated gas used. + + return nil +} +``` + +## Using gRPC + +It is not possible to generate or sign a transaction using gRPC, only to broadcast one. In order to broadcast a transaction using gRPC, you will need to generate, sign, and encode the transaction using either the CLI or programmatically with Go. + +### Broadcasting a Transaction + +Broadcasting a transaction using the gRPC endpoint can be done by sending a `BroadcastTx` request as follows, where the `txBytes` are the protobuf-encoded bytes of a signed transaction: + +```bash +grpcurl -plaintext \ + -d '{"tx_bytes":"{{txBytes}}","mode":"BROADCAST_MODE_SYNC"}' \ + localhost:9090 \ + cosmos.tx.v1beta1.Service/BroadcastTx +``` + +## Using REST + +It is not possible to generate or sign a transaction using REST, only to broadcast one. In order to broadcast a transaction using REST, you will need to generate, sign, and encode the transaction using either the CLI or programmatically with Go. + +### Broadcasting a Transaction + +Broadcasting a transaction using the REST endpoint (served by `gRPC-gateway`) can be done by sending a POST request as follows, where the `txBytes` are the protobuf-encoded bytes of a signed transaction: + +```bash +curl -X POST \ + -H "Content-Type: application/json" \ + -d'{"tx_bytes":"{{txBytes}}","mode":"BROADCAST_MODE_SYNC"}' \ + localhost:1317/cosmos/tx/v1beta1/txs +``` + +## Using CosmJS (JavaScript & TypeScript) + +CosmJS aims to build client libraries in JavaScript that can be embedded in web applications. Please see [https://cosmos.github.io/cosmjs](https://cosmos.github.io/cosmjs) for more information. As of January 2021, CosmJS documentation is still work in progress. diff --git a/versioned_docs/version-0.52/user/run-node/04-rosetta.md b/versioned_docs/version-0.52/user/run-node/04-rosetta.md new file mode 100644 index 000000000..de74d9898 --- /dev/null +++ b/versioned_docs/version-0.52/user/run-node/04-rosetta.md @@ -0,0 +1,144 @@ +# Rosetta + +The `rosetta` project implements Coinbase's [Rosetta API](https://www.rosetta-api.org). This document provides instructions on how to use the Rosetta API integration. For information about the motivation and design choices, refer to [ADR 035](https://docs.cosmos.network/main/architecture/adr-035-rosetta-api-support). + +## Installing Rosetta + +The Rosetta API server is a stand-alone server that connects to a node of a chain developed with Cosmos SDK. + +Rosetta can be added to any cosmos chain node. standalone or natively. + +### Standalone + +Rosetta can be executed as a standalone service, it connects to the node endpoints and expose the required endpoints. + +Install Rosetta standalone server with the following command: + +```bash +go install github.com/cosmos/rosetta +``` + +Alternatively, for building from source, simply run `make build`. The binary will be located in the root folder. + +### Native - As a node command + +To enable Native Rosetta API support, it's required to add the `RosettaCommand` to your application's root command file (e.g. `simd/cmd/root.go`). + +Import the `rosettaCmd` package: + +```go +import "github.com/cosmos/rosetta/cmd" +``` + +Find the following line: + +```go +initRootCmd(rootCmd, encodingConfig) +``` + +After that line, add the following: + +```go +rootCmd.AddCommand( + rosettaCmd.RosettaCommand(encodingConfig.InterfaceRegistry, encodingConfig.Codec) +) +``` + +The `RosettaCommand` function builds the `rosetta` root command and is defined in the `rosettaCmd` package (`github.com/cosmos/rosetta/cmd`). + +Since we’ve updated the Cosmos SDK to work with the Rosetta API, updating the application's root command file is all you need to do. + +An implementation example can be found in `simapp` package. + +## Use Rosetta Command + +To run Rosetta in your application CLI, use the following command: + +> **Note:** if using the native approach, add your node name before any rosetta comand. + +```shell +rosetta --help +``` + +To test and run Rosetta API endpoints for applications that are running and exposed, use the following command: + +```shell +rosetta + --blockchain "your application name (ex: gaia)" + --network "your chain identifier (ex: testnet-1)" + --tendermint "tendermint endpoint (ex: localhost:26657)" + --grpc "gRPC endpoint (ex: localhost:9090)" + --addr "rosetta binding address (ex: :8080)" + --grpc-types-server (optional) "gRPC endpoint for message descriptor types" +``` + +## Plugins - Multi chain connections + +Rosetta will try to reflect the node types trough reflection over the node gRPC endpoints, there may be cases were this approach is not enough. It is possible to extend or implement the required types easily trough plugins. + +To use Rosetta over any chain, it is required to set up prefixes and registering zone specific interfaces through plugins. + +Each plugin is a minimalist implementation of `InitZone` and `RegisterInterfaces` which allow Rosetta to parse chain specific data. There is an example for cosmos-hub chain under `plugins/cosmos-hun/` folder +- **InitZone**: An empty method that is executed first and defines prefixes, parameters and other settings. +- **RegisterInterfaces**: This method receives an interface registry which is were the zone specific types and interfaces will be loaded + +In order to add a new plugin: +1. Create a folder over `plugins` folder with the name of the desired zone +2. Add a `main.go` file with the mentioned methods above. +3. Build the code binary through `go build -buildmode=plugin -o main.so main.go` + +The plugin folder is selected through the cli `--plugin` flag and loaded into the Rosetta server. + +## Extensions + +There are two ways in which you can customize and extend the implementation with your custom settings. + +### Message extension + +In order to make an `sdk.Msg` understandable by rosetta the only thing which is required is adding the methods to your messages that satisfy the `rosetta.Msg` interface. Examples on how to do so can be found in the staking types such as `MsgDelegate`, or in bank types such as `MsgSend`. + +### Client interface override + +In case more customization is required, it's possible to embed the Client type and override the methods which require customizations. + +Example: + +```go +package custom_client +import ( + +"context" +"github.com/coinbase/rosetta-sdk-go/types" +"github.com/cosmos/rosetta/lib" +) + +// CustomClient embeds the standard cosmos client +// which means that it implements the cosmos-rosetta-gateway Client +// interface while at the same time allowing to customize certain methods +type CustomClient struct { + *rosetta.Client +} + +func (c *CustomClient) ConstructionPayload(_ context.Context, request *types.ConstructionPayloadsRequest) (resp *types.ConstructionPayloadsResponse, err error) { + // provide custom signature bytes + panic("implement me") +} +``` + +NOTE: when using a customized client, the command cannot be used as the constructors required **may** differ, so it's required to create a new one. We intend to provide a way to init a customized client without writing extra code in the future. + +### Error extension + +Since rosetta requires to provide 'returned' errors to network options. In order to declare a new rosetta error, we use the `errors` package in cosmos-rosetta-gateway. + +Example: + +```go +package custom_errors +import crgerrs "github.com/cosmos/rosetta/lib/errors" + +var customErrRetriable = true +var CustomError = crgerrs.RegisterError(100, "custom message", customErrRetriable, "description") +``` + +Note: errors must be registered before cosmos-rosetta-gateway's `Server`.`Start` method is called. Otherwise the registration will be ignored. Errors with same code will be ignored too. diff --git a/docs/validate/05-run-testnet.md b/versioned_docs/version-0.52/user/run-node/05-run-testnet.md similarity index 92% rename from docs/validate/05-run-testnet.md rename to versioned_docs/version-0.52/user/run-node/05-run-testnet.md index e9a06ed34..c2b5da598 100644 --- a/docs/validate/05-run-testnet.md +++ b/versioned_docs/version-0.52/user/run-node/05-run-testnet.md @@ -8,7 +8,7 @@ sidebar_position: 1 The `simd testnet` subcommand makes it easy to initialize and start a simulated test network for testing purposes. ::: -In addition to the commands for [running a node](../user/run-node/01-run-node.md), the `simd` binary also includes a `testnet` command that allows you to start a simulated test network in-process or to initialize files for a simulated test network that runs in a separate process. +In addition to the commands for [running a node](./01-run-node.md), the `simd` binary also includes a `testnet` command that allows you to start a simulated test network in-process or to initialize files for a simulated test network that runs in a separate process. ## Initialize Files diff --git a/versioned_docs/version-0.52/user/run-node/06-run-production.md b/versioned_docs/version-0.52/user/run-node/06-run-production.md new file mode 100644 index 000000000..807ceea56 --- /dev/null +++ b/versioned_docs/version-0.52/user/run-node/06-run-production.md @@ -0,0 +1,269 @@ +--- +sidebar_position: 1 +--- + +# Running in Production + +:::note Synopsis +This section describes how to securely run a node in a public setting and/or on a mainnet on one of the many Cosmos SDK public blockchains. +::: + +When operating a node, full node or validator, in production it is important to set your server up securely. + +:::note +There are many different ways to secure a server and your node, the described steps here is one way. To see another way of setting up a server see the [run in production tutorial](https://tutorials.cosmos.network/hands-on-exercise/5-run-in-prod/1-overview.html). +::: + +:::note +This walkthrough assumes the underlying operating system is Ubuntu. +::: + +## Sever Setup + +### User + +When creating a server most times it is created as user `root`. This user has heightened privileges on the server. When operating a node, it is recommended to not run your node as the root user. + +1. Create a new user + +```bash +sudo adduser change_me +``` + +2. We want to allow this user to perform sudo tasks + +```bash +sudo usermod -aG sudo change_me +``` + +Now when logging into the server, the non `root` user can be used. + +### Go + +1. Install the [Go](https://go.dev/doc/install) version preconized by the application. + +:::warning +In the past, validators [have had issues](https://github.com/cosmos/cosmos-sdk/issues/13976) when using different versions of Go. It is recommended that the whole validator set uses the version of Go that is preconized by the application. +::: + +### Firewall + +Nodes should not have all ports open to the public, this is a simple way to get DDOS'd. Secondly it is recommended by [CometBFT](github.com/cometbft/cometbft) to never expose ports that are not required to operate a node. + +When setting up a firewall there are a few ports that can be open when operating a Cosmos SDK node. There is the CometBFT json-RPC, prometheus, p2p, remote signer and Cosmos SDK GRPC and REST. If the node is being operated as a node that does not offer endpoints to be used for submission or querying then a max of three endpoints are needed. + +Most, if not all servers come equipped with [ufw](https://help.ubuntu.com/community/UFW). Ufw will be used in this tutorial. + +1. Reset UFW to disallow all incoming connections and allow outgoing + +```bash +sudo ufw default deny incoming +sudo ufw default allow outgoing +``` + +2. Lets make sure that port 22 (ssh) stays open. + +```bash +sudo ufw allow ssh +``` + +or + +```bash +sudo ufw allow 22 +``` + +Both of the above commands are the same. + +3. Allow Port 26656 (cometbft p2p port). If the node has a modified p2p port then that port must be used here. + +```bash +sudo ufw allow 26656/tcp +``` + +4. Allow port 26660 (cometbft [prometheus](https://prometheus.io)). This acts as the applications monitoring port as well. + +```bash +sudo ufw allow 26660/tcp +``` + +5. IF the node which is being setup would like to expose CometBFTs jsonRPC and Cosmos SDK GRPC and REST then follow this step. (Optional) + +##### CometBFT JsonRPC + +```bash +sudo ufw allow 26657/tcp +``` + +##### Cosmos SDK GRPC + +```bash +sudo ufw allow 9090/tcp +``` + +##### Cosmos SDK REST + +```bash +sudo ufw allow 1317/tcp +``` + +6. Lastly, enable ufw + +```bash +sudo ufw enable +``` + +### Signing + +If the node that is being started is a validator there are multiple ways a validator could sign blocks. + +#### File + +File based signing is the simplest and default approach. This approach works by storing the consensus key, generated on initialization, to sign blocks. This approach is only as safe as your server setup as if the server is compromised so is your key. This key is located in the `config/priv_val_key.json` directory generated on initialization. + +A second file exists that user must be aware of, the file is located in the data directory `data/priv_val_state.json`. This file protects your node from double signing. It keeps track of the consensus keys last sign height, round and latest signature. If the node crashes and needs to be recovered this file must be kept in order to ensure that the consensus key will not be used for signing a block that was previously signed. + +#### Remote Signer + +A remote signer is a secondary server that is separate from the running node that signs blocks with the consensus key. This means that the consensus key does not live on the node itself. This increases security because your full node which is connected to the remote signer can be swapped without missing blocks. + +The two most used remote signers are [tmkms](https://github.com/iqlusioninc/tmkms) from [Iqlusion](https://www.iqlusion.io) and [horcrux](https://github.com/strangelove-ventures/horcrux) from [Strangelove](https://strange.love). + +##### TMKMS + +###### Dependencies + +1. Update server dependencies and install extras needed. + +```sh +sudo apt update -y && sudo apt install build-essential curl jq -y +``` + +2. Install Rust: + +```sh +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh +``` + +3. Install Libusb: + +```sh +sudo apt install libusb-1.0-0-dev +``` + +###### Setup + +There are two ways to install tmkms, from source or `cargo install`. In the examples we will cover downloading or building from source and using softsign. Softsign stands for software signing, but you could use a [yubihsm](https://www.yubico.com/products/hardware-security-module/) as your signing key if you wish. + +1. Build: + +From source: + +```bash +cd $HOME +git clone https://github.com/iqlusioninc/tmkms.git +cd $HOME/tmkms +cargo install tmkms --features=softsign +tmkms init config +tmkms softsign keygen ./config/secrets/secret_connection_key +``` + +or + +Cargo install: + +```bash +cargo install tmkms --features=softsign +tmkms init config +tmkms softsign keygen ./config/secrets/secret_connection_key +``` + +:::note +To use tmkms with a yubikey install the binary with `--features=yubihsm`. +::: + +2. Migrate the validator key from the full node to the new tmkms instance. + +```bash +scp user@123.456.32.123:~/.simd/config/priv_validator_key.json ~/tmkms/config/secrets +``` + +3. Import the validator key into tmkms. + +```bash +tmkms softsign import $HOME/tmkms/config/secrets/priv_validator_key.json $HOME/tmkms/config/secrets/priv_validator_key +``` + +At this point, it is necessary to delete the `priv_validator_key.json` from the validator node and the tmkms node. Since the key has been imported into tmkms (above) it is no longer necessary on the nodes. The key can be safely stored offline. + +4. Modifiy the `tmkms.toml`. + +```bash +vim $HOME/tmkms/config/tmkms.toml +``` + +This example shows a configuration that could be used for soft signing. The example has an IP of `123.456.12.345` with a port of `26659` a chain_id of `test-chain-waSDSe`. These are items that most be modified for the usecase of tmkms and the network. + +```toml +# CometBFT KMS configuration file + +## Chain Configuration + +[[chain]] +id = "osmosis-1" +key_format = { type = "bech32", account_key_prefix = "cosmospub", consensus_key_prefix = "cosmosvalconspub" } +state_file = "/root/tmkms/config/state/priv_validator_state.json" + +## Signing Provider Configuration + +### Software-based Signer Configuration + +[[providers.softsign]] +chain_ids = ["test-chain-waSDSe"] +key_type = "consensus" +path = "/root/tmkms/config/secrets/priv_validator_key" + +## Validator Configuration + +[[validator]] +chain_id = "test-chain-waSDSe" +addr = "tcp://123.456.12.345:26659" +secret_key = "/root/tmkms/config/secrets/secret_connection_key" +protocol_version = "v0.34" +reconnect = true +``` + +5. Set the address of the tmkms instance. + +```bash +vim $HOME/.simd/config/config.toml + +priv_validator_laddr = "tcp://127.0.0.1:26659" +``` + +:::tip +The above address it set to `127.0.0.1` but it is recommended to set the tmkms server to secure the startup +::: + +:::tip +It is recommended to comment or delete the lines that specify the path of the validator key and validator: + +```toml +# Path to the JSON file containing the private key to use as a validator in the consensus protocol +# priv_validator_key_file = "config/priv_validator_key.json" + +# Path to the JSON file containing the last sign state of a validator +# priv_validator_state_file = "data/priv_validator_state.json" +``` + +::: + +6. Start the two processes. + +```bash +tmkms start -c $HOME/tmkms/config/tmkms.toml +``` + +```bash +simd start +``` diff --git a/versioned_docs/version-0.52/user/run-node/07-multisig-guide.md b/versioned_docs/version-0.52/user/run-node/07-multisig-guide.md new file mode 100644 index 000000000..f7be5b1f4 --- /dev/null +++ b/versioned_docs/version-0.52/user/run-node/07-multisig-guide.md @@ -0,0 +1,108 @@ +--- +sidebar_position: 1 +--- + +# Guide to Multisig transactions + +## Overview + +Multisignature accounts are accounts that are generated from multiple public keys. A multisig necessitates that any transaction made on its behalf must be signed by a specified threshold of its members. + +A common use case for multisigs is to increase security of a signing account, and/or enable multiple parties to agree on and authorize a transaction. + +The first step is to create a multisig signing key by using the public keys of all possible signers and the minimum threshold of addresses that are needed to sign any transaction from the account. The threshold can be the same amount as the total number of addresses comprising the multisig. + +Whatever machine is generating the multisig, it should at least have all of the public keys imported into the same keyring. + +When you want to create a multisig transaction, you would create the transaction as normal, but instead of signing it with a single account's private key, you would need to sign it with the private keys of the accounts that make up the multisig key. + +This is done by signing the transaction multiple times, once with each private key. The order of the signatures matters and must match the order of the public keys in the multisig key. + +Once you have a transaction with the necessary signatures, it can be broadcasted to the network. The network will verify that the transaction has the necessary signatures from the accounts in the multisig key before it is executed. + +## Step by step guide to multisig transactions + +This tutorial will use the test keyring which will store the keys in the default home directory `~/.simapp` unless otherwise specified. +Verify which keys are available in the test keyring by running `--keyring-backend test`. + +Prior to this tutorial set the keyring backend to "test" in `~/.simapp/client.toml` to always the test keyring which will specify a consistent keyring for the entirety of the tutorial. Additionally, set the default keyring by running `simd config set client keyring-backend test`. + +```shell +simd keys list +``` + +If you don't already have accounts listed create the accounts using the below. + +```shell +simd keys add alice +simd keys add bob +simd keys add recipient +``` + +Alternatively the public keys comprising the multisig can be imported into the keyring. + +```shell +simd keys add alice --pubkey --keyring backend test +``` + +Create the multisig account between bob and alice. + +```shell +simd keys add alice-bob-multisig --multisig alice,bob --multisig-threshold 2 +``` + +Before generating any transaction, verify the balance of each account and note the amount. This step is crucial to confirm that the transaction can be processed successfully. + +```shell +simd query bank balances my_validator +simd query bank balances alice-bob-multisig +``` + +Ensure that the alice-bob-multisig account is funded with a sufficient balance to complete the transaction (gas included). In our case, the genesis account, my_validator, holds our funds. Therefore, we will transfer funds from the `my_validator` account to the `alice-bob-multisig` account. +Fund the multisig by sending it `stake` from the genesis account. + +```shell + simd tx bank send my_validator alice-bob-multisig "10000stake" +``` + +Check both accounts again to see if the funds have transferred. + +```shell +simd query bank balances alice-bob-multisig +``` + +Initiate the transaction. This command will create a transaction from the multisignature account `alice-bob-multisig` to send 1000stake to the recipient account. The transaction will be generated but not broadcasted yet. + +```shell +simd tx bank send alice-bob-multisig recipient 1000stake --generate-only --chain-id my-test-chain > tx.json +``` + +Alice signs the transaction using their key and refers to the multisig address. Execute the command below to accomplish this: + +```shell +simd tx sign --from alice --multisig=cosmos1re6mg24kvzjzmwmly3dqrqzdkruxwvctw8wwds tx.json --chain-id my-test-chain > tx-signed-alice.json +``` + +Let's repeat for Bob. + +```shell +simd tx sign --from bob --multisig=cosmos1re6mg24kvzjzmwmly3dqrqzdkruxwvctw8wwds tx.json --chain-id my-test-chain > tx-signed-bob.json +``` + +Execute a multisign transaction by using the `simd tx multisign` command. This command requires the names and signed transactions of all the participants in the multisig account. Here, Alice and Bob are the participants: + +```shell +simd tx multisign tx.json alice-bob-multisig tx-signed-alice.json tx-signed-bob.json --chain-id my-test-chain > tx-signed.json +``` + +Once the multisigned transaction is generated, it needs to be broadcasted to the network. This is done using the simd tx broadcast command: + +```shell +simd tx broadcast tx-signed.json --chain-id my-test-chain --gas auto --fees 250stake +``` + +Once the transaction is broadcasted, it's a good practice to verify if the transaction was successful. You can query the recipient's account balance again to confirm if the funds were indeed transferred: + +```shell +simd query bank balances alice-bob-multisig +``` diff --git a/versioned_docs/version-0.52/user/run-node/08-onchain-multisig.md b/versioned_docs/version-0.52/user/run-node/08-onchain-multisig.md new file mode 100644 index 000000000..a93e59620 --- /dev/null +++ b/versioned_docs/version-0.52/user/run-node/08-onchain-multisig.md @@ -0,0 +1,248 @@ +--- +sidebar_position: 1 +--- + +# Guide to On-Chain Multisig transactions + +## Overview + +Multisignature **on-chain** accounts are an improvement over the previous implementation as these introduce a new set of +features. + +### Threshold and quorums + +The previous implementation only allowed for m-of-n multisig accounts, where m is the number of signatures required to +authorize a transaction and n is the total number of signers. The new implementation allows for more flexibility by +introducing threshold and quorum values. The quorum is the minimum voting power to make a proposal valid, while the +threshol is the minimum of voting power of YES votes to pass a proposal. + +### Revote + +Multisigs can allow members to change their votes after the initial vote. This is useful when a member changes their mind +or when new information becomes available. + +### Early execution + +Multisigs can be configured to allow for early execution of proposals. This is useful when a proposal is time-sensitive or +when the proposer wants to execute the proposal as soon as it reaches the threshold. It can also be used to mimic the +behavior of the previous multisig implementation. + +### Voting period + +Multisigs can be configured to have a voting period. This is the time window during which members can vote on a proposal. +If the proposal does not reach the threshold within the voting period, it is considered failed. + +## Setup + +We'll create a multisig with 3 members with a 2/3 passing threshold. + +First create the 3 members, Alice, Bob and Carol: + +```bash! +simd keys add alice --keyring-backend test --home ./.testnets/node0/simd/ +simd keys add bob --keyring-backend test --home ./.testnets/node0/simd/ +simd keys add carol --keyring-backend test --home ./.testnets/node0/simd/ +``` + +And we initialize them with some tokens (sent from one of our nodes): + +```bash! +simd tx bank send $(simd keys show node0 --address --keyring-backend=test --home ./.testnets/node0/simd/) $(simd keys show alice --address --keyring-backend=test --home ./.testnets/node0/simd/) 100stake --fees 5stake --chain-id $CHAINID --keyring-backend test --home ./.testnets/node0/simd/ +simd tx bank send $(simd keys show node0 --address --keyring-backend=test --home ./.testnets/node0/simd/) $(simd keys show bob --address --keyring-backend=test --home ./.testnets/node0/simd/) 100stake --fees 5stake --chain-id $CHAINID --keyring-backend test --home ./.testnets/node0/simd/ +simd tx bank send $(simd keys show node0 --address --keyring-backend=test --home ./.testnets/node0/simd/) $(simd keys show carol --address --keyring-backend=test --home ./.testnets/node0/simd/) 100stake --fees 5stake --chain-id $CHAINID --keyring-backend test --home ./.testnets/node0/simd/ +``` + +Now we craft our initialization message, in it we'll include the members' addresses, their weights and the configuration of our multisig. + +```json +{ + "members": [ + { + "address": "cosmos1pr26h2vq9adq3acvh37pz6wtk65u3y8798scq0", + "weight": 1000 + }, + { + "address": "cosmos1j4p2xlg393rg4mma0058alzgvkrjdddd2f5fll", + "weight": 1000 + }, + { + "address": "cosmos1vaqh39cdex9sgr46ef0tdln5cn0hdyd3s0lx4l", + "weight": 1000 + } + ], + "config": { + "threshold": 2000, + "quorum": 2000, + "voting_period": 86400, + "revote": false, + "early_execution": true + } +} +``` + +In the configuration we set the threshold and quorum to the same, 2/3 of the members must vote yes to pass the proposal. Other configurations can set the quorum and threshold to different values to mimic how organizations work. + +We've also set `early_execution` to true, to allow executing as soon as the proposal passes. + +Voting period is in seconds, so we've set that to 24h. And finally `revote` was set to false, because we don't want to allow members to change their vote mid-way through. + +To initialize the multisig, we have to run the `accounts init` passing the account type and the json we created. + + +```bash! +initcontents=$(cat init.json) +simd tx accounts init multisig $initcontents --fees 5stake --chain-id $CHAINID --keyring-backend test --home ./.testnets/node0/simd/ --from alice +``` + +If everything goes well, we'll get back a tx hash, and we'll check the tx result to get our newly created multisig's address. + +```bash! +simd q tx 472B5B4E181D2F399C0ACE4DEEB26FE4351D13E593ED8E793B005C48BFD32621 --output json | jq -r '.events[] | select(.type == "account_creation") | .attributes[] | select(.key == "address") | .value' +``` + +In this case, the address is `cosmos1uds6tz96dxfllz7tz3s3tm8tlg6x95g0mc2987sx6psjz98qlpss89sheu`. We can now send tokens to it, just like to a normal account. + +```bash! +simd tx bank send $(simd keys show node0 --address --keyring-backend=test --home ./.testnets/node0/simd/) cosmos1uds6tz96dxfllz7tz3s3tm8tlg6x95g0mc2987sx6psjz98qlpss89sheu 10000stake --fees 5stake --chain-id $CHAINID --keyring-backend test --home ./.testnets/node0/simd/ +``` + +## Proposals + +#### Create proposal + +In this multisig, every action is a proposal. We'll do a simple proposal to send tokens from the multisig to Alice. + +```json +{ + "proposal": { + "title": "Send 1000 tokens to Alice", + "summary": "Alice is a great multisig member so let's pay her.", + "messages": [ + { + "@type": "/cosmos.bank.v1beta1.MsgSend", + "from_address": "cosmos1uds6tz96dxfllz7tz3s3tm8tlg6x95g0mc2987sx6psjz98qlpss89sheu", + "to_address": "cosmos1pr26h2vq9adq3acvh37pz6wtk65u3y8798scq0", + "amount": [ + { + "denom": "stake", + "amount": "1000" + } + ] + } + ] + } +} +``` + +> The content of messages was created using a simple `tx send` command and passing the flag `--generate-only` so we could copy the message. + +Now we send the tx that will create the proposal: + +```bash! +propcontents=$(cat createprop.json) +simd tx accounts execute cosmos1uds6tz96dxfllz7tz3s3tm8tlg6x95g0mc2987sx6psjz98qlpss89sheu cosmos.accounts.defaults.multisig.v1.MsgCreateProposal $propcontents --fees 5stake --chain-id $CHAINID --keyring-backend test --home ./.testnets/node0/simd/ --from alice +``` + +This will again return a tx hash that we can use to find out the newly created proposal. + +```bash! +simd q tx 5CA4420B67FB040B3DF2484CB875E030123662F43AE9958A9F8028C1281C8654 --output json | jq -r '.events[] | select(.type == "proposal_created") | .attributes[] | select(.key == "proposal_id") | .value' +``` + +In this case, because this is the first proposal, we'll get that the proposal ID is 0. We can use this to query it. + +```bash! +simd q accounts query cosmos1uds6tz96dxfllz7tz3s3tm8tlg6x95g0mc2987sx6psjz98qlpss89sheu cosmos.accounts.defaults.multisig.v1.QueryProposal '{"proposal_id":1}' +``` + +We get back all the details from the proposal, including the end of the voting period and the current status of the proposal. + +```yaml +response: + '@type': /cosmos.accounts.defaults.multisig.v1.QueryProposalResponse + proposal: + messages: + - '@type': /cosmos.bank.v1beta1.MsgSend + amount: + - amount: "1000" + denom: stake + from_address: cosmos1uds6tz96dxfllz7tz3s3tm8tlg6x95g0mc2987sx6psjz98qlpss89sheu + to_address: cosmos1pr26h2vq9adq3acvh37pz6wtk65u3y8798scq0 + status: PROPOSAL_STATUS_VOTING_PERIOD + summary: Alice is a great multisig member so let's pay her. + title: Send 1000 tokens to Alice + voting_period_end: "1717064354" +``` + +### Vote on the proposal + +Just like before, we'll use `tx accounts execute`, but this time to vote. As we have a 2/3 passing threshold, we have to vote with at least 2 members. + +```bash! +simd tx accounts execute cosmos1uds6tz96dxfllz7tz3s3tm8tlg6x95g0mc2987sx6psjz98qlpss89sheu cosmos.accounts.defaults.multisig.v1.MsgVote '{"proposal_id":0, "vote":"VOTE_OPTION_YES"}' --fees 5stake --chain-id $CHAINID --keyring-backend test --home ./.testnets/node0/simd/ --from alice --yes +simd tx accounts execute cosmos1uds6tz96dxfllz7tz3s3tm8tlg6x95g0mc2987sx6psjz98qlpss89sheu cosmos.accounts.defaults.multisig.v1.MsgVote '{"proposal_id":0, "vote":"VOTE_OPTION_YES"}' --fees 5stake --chain-id $CHAINID --keyring-backend test --home ./.testnets/node0/simd/ --from bob --yes +``` + +### Execute the proposal + +Once we got enough votes, we can execute the proposal. + +```bash! +simd tx accounts execute cosmos1uds6tz96dxfllz7tz3s3tm8tlg6x95g0mc2987sx6psjz98qlpss89sheu cosmos.accounts.defaults.multisig.v1.MsgExecuteProposal '{"proposal_id":0}' --fees 5stake --chain-id $CHAINID --keyring-backend test --home ./.testnets/node0/simd/ --from bob --yes +``` + +Querying the tx hash will get us information about the success or failure of the proposal execution. + +```yaml +- attributes: + - index: true + key: proposal_id + value: "0" + - index: true + key: yes_votes + value: "2000" + - index: true + key: no_votes + value: "0" + - index: true + key: abstain_votes + value: "0" + - index: true + key: status + value: PROPOSAL_STATUS_PASSED + - index: true + key: reject_err + value: + - index: true + key: exec_err + value: + - index: true + key: msg_index + value: "0" + type: proposal_tally +``` + +Now checking the multisig and Alice's balance, we'll see that the send was performed correctly. + +```bash! +simd q bank balances cosmos1uds6tz96dxfllz7tz3s3tm8tlg6x95g0mc2987sx6psjz98qlpss89sheu + +balances: +- amount: "9000" + denom: stake +pagination: + total: "1" +``` + +```bash! +simd q bank balances $(./build/simd keys show alice --address) + +balances: +- amount: "1080" + denom: stake +pagination: + total: "1" +``` + + + diff --git a/versioned_docs/version-0.52/user/run-node/_category_.json b/versioned_docs/version-0.52/user/run-node/_category_.json new file mode 100644 index 000000000..7fcac509a --- /dev/null +++ b/versioned_docs/version-0.52/user/run-node/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Running a Node, API and CLI", + "position": 1, + "link": null +} \ No newline at end of file diff --git a/versioned_docs/version-0.52/user/user.md b/versioned_docs/version-0.52/user/user.md new file mode 100644 index 000000000..5429e8ad6 --- /dev/null +++ b/versioned_docs/version-0.52/user/user.md @@ -0,0 +1,10 @@ +--- +sidebar_position: 0 +--- +# User Guides + +This section is designed for developers who are using the Cosmos SDK to build applications. It provides essential guides and references to effectively use the SDK's features. + +* [Setting up keys](./run-node/00-keyring.md) - Learn how to set up secure key management using the Cosmos SDK's keyring feature. This guide provides a streamlined approach to cryptographic key handling, which is crucial for securing your application. +* [Running a node](./run-node/01-run-node.md) - This guide provides step-by-step instructions to deploy and manage a node in the Cosmos network. It ensures a smooth and reliable operation of your blockchain application by covering all the necessary setup and maintenance steps. +* [CLI](./run-node/02-interact-node.md) - Discover how to navigate and interact with the Cosmos SDK using the Command Line Interface (CLI). This section covers efficient and powerful command-based operations that can help you manage your application effectively. diff --git a/versioned_sidebars/version-0.52-sidebars.json b/versioned_sidebars/version-0.52-sidebars.json new file mode 100644 index 000000000..a9a3bcb28 --- /dev/null +++ b/versioned_sidebars/version-0.52-sidebars.json @@ -0,0 +1,26 @@ +{ + "learnSidebar": [ + { + "type": "autogenerated", + "dirName": "learn" + } + ], + "buildSidebar": [ + { + "type": "autogenerated", + "dirName": "build" + } + ], + "userSidebar": [ + { + "type": "autogenerated", + "dirName": "user" + } + ], + "tutorialsSidebar": [ + { + "type": "autogenerated", + "dirName": "tutorials" + } + ] +}