From 3c3db71c5cab78a18ad82746b94fcb78afc5a19c Mon Sep 17 00:00:00 2001 From: Jehan Date: Mon, 28 Oct 2024 07:44:48 -0700 Subject: [PATCH] docs: add spawn page to docs (#2338) * add spawn page * add .md extension to doc; change links * update dead link to new one --------- Co-authored-by: MSalopek --- .../consumer-development/app-integration.md | 3 +- .../changeover-procedure.md | 2 +- .../consumer-chain-governance.md | 2 +- .../consumer-genesis-transformation.md | 2 +- .../consumer-development/create-with-spawn.md | 107 ++++++++++++++++++ docs/docs/consumer-development/offboarding.md | 2 +- docs/docs/consumer-development/onboarding.md | 5 +- 7 files changed, 116 insertions(+), 7 deletions(-) create mode 100644 docs/docs/consumer-development/create-with-spawn.md diff --git a/docs/docs/consumer-development/app-integration.md b/docs/docs/consumer-development/app-integration.md index 0671db05a7..57ec14fc48 100644 --- a/docs/docs/consumer-development/app-integration.md +++ b/docs/docs/consumer-development/app-integration.md @@ -1,5 +1,5 @@ --- -sidebar_position: 1 +sidebar_position: 2 --- # Developing an ICS consumer chain @@ -31,4 +31,3 @@ With these modules enabled, the consumer chain can mint its own governance token ## Standalone chain to consumer chain changeover See the [standalone chain to consumer chain changeover guide](./changeover-procedure.md) for more information on how to transition your standalone chain to a consumer chain. - diff --git a/docs/docs/consumer-development/changeover-procedure.md b/docs/docs/consumer-development/changeover-procedure.md index 240925fc0d..17b8faa713 100644 --- a/docs/docs/consumer-development/changeover-procedure.md +++ b/docs/docs/consumer-development/changeover-procedure.md @@ -1,5 +1,5 @@ --- -sidebar_position: 5 +sidebar_position: 6 --- # Changeover Procedure diff --git a/docs/docs/consumer-development/consumer-chain-governance.md b/docs/docs/consumer-development/consumer-chain-governance.md index c8586efe3a..86b56f8418 100644 --- a/docs/docs/consumer-development/consumer-chain-governance.md +++ b/docs/docs/consumer-development/consumer-chain-governance.md @@ -1,5 +1,5 @@ --- -sidebar_position: 2 +sidebar_position: 3 --- # Consumer Chain Governance diff --git a/docs/docs/consumer-development/consumer-genesis-transformation.md b/docs/docs/consumer-development/consumer-genesis-transformation.md index d77e8ec559..360332aa25 100644 --- a/docs/docs/consumer-development/consumer-genesis-transformation.md +++ b/docs/docs/consumer-development/consumer-genesis-transformation.md @@ -1,5 +1,5 @@ --- -sidebar_position: 6 +sidebar_position: 7 --- # Consumer Genesis Transformation diff --git a/docs/docs/consumer-development/create-with-spawn.md b/docs/docs/consumer-development/create-with-spawn.md new file mode 100644 index 0000000000..07e202b041 --- /dev/null +++ b/docs/docs/consumer-development/create-with-spawn.md @@ -0,0 +1,107 @@ +--- +sidebar_position: 1 +--- + +# Create an ICS chain with Spawn + +## Requirements + +- [`go 1.22+`](https://go.dev/doc/install) +- [`Docker`](https://docs.docker.com/get-docker/) + +[MacOS + Ubuntu Setup](https://github.com/rollchains/spawn/blob/release/v0.50/docs/versioned_docs/version-v0.50.x/01-setup/01-system-setup.md) + +## Getting Started + +**Note:** This tutorial focuses on using the Spawn CLI to create an ICS consumer chain. For more complete documentation on Spawn, see the [Spawn documentation](https://rollchains.github.io/spawn/v0.50/). + +In this tutorial, we'll create and interact with a new Interchain security enabled blockchain called "consumer", with the token denomination "uconsu". + +1. Clone this repo and install + +```shell +git clone https://github.com/rollchains/spawn.git +cd spawn +git checkout v0.50.4 +make install +``` + +2. Create your chain using the `spawn` command and customize it to your needs! + +```shell +GITHUB_USERNAME= + +spawn new consumer \ +--consensus=interchain-security \ +--bech32=consu `# the prefix for addresses` \ +--denom=uconsu `# the coin denomination to create` \ +--bin=consumerd `# the name of the binary` \ +--disabled=tokenfactory,globalfee,ibc-packetforward,ibc-ratelimit,cosmwasm,wasm-light-client,optimistic-execution,ignite-cli `# disable features. [tokenfactory,globalfee,ibc-packetforward,ibc-ratelimit,cosmwasm,wasm-light-client,ignite-cli]` \ +--org=${GITHUB_USERNAME} `# the github username or organization to use for the module imports, optional` +``` + +> _NOTE:_ `spawn` creates a ready to use repository complete with `git` and GitHub CI. It can be quickly pushed to a new repository getting you and your team up and running quickly. + +3. Spin up a local testnet for your chain + +```shell +cd consumer + +# Starts 2 networks for the IBC testnet at http://127.0.0.1:8080. +# - Builds the docker image of your chain +# - Launches a testnet with IBC automatically connected and relayed +# +# Note: you can run a single node, non IBC testnet, with `make sh-testnet`. +make testnet +``` + +4. Open a new terminal window and send a transaction on your new chain + +```shell +# list the keys that have been provisioned with funds in genesis +consumerd keys list + +# send a transaction from one account to another +consumerd tx bank send acc0 $(consumerd keys show acc1 -a) 1337uconsu --chain-id=localchain-1 + +# enter "y" to confirm the transaction +# then query your balances tfor proof the transaction executed successfully +consumerd q bank balances $(consumerd keys show acc1 -a) +``` + +5. (optional) Send an IBC transaction + +```shell +# submit a cross chain transfer from acc0 to the other address +consumerd tx ibc-transfer transfer transfer channel-0 cosmos1hj5fveer5cjtn4wd6wstzugjfdxzl0xpxvjjvr 7uconsu --from=acc0 --chain-id=localchain-1 --yes + +# Query the other side to confirm it went through +sleep 10 + +# Interact with the other chain without having to install the cosmos binary +# - Endpoints found at: GET http://127.0.0.1:8080/info +local-ic interact localcosmos-1 query 'bank balances cosmos1hj5fveer5cjtn4wd6wstzugjfdxzl0xpxvjjvr' --api-endpoint=http://127.0.0.1:8080 +``` + +6. Push your new chain to a github repository + +```shell +# Create a new repository on GitHub from the gh cli +gh repo create ics-consumer --source=. --remote=origin --push +``` + +> You can also push it the old fashioned way with https://github.com/new and `git push origin main`. + +In this tutorial, we configured a new custom chain, launched a testnet for it, tested a simple token transfer, and confirmed it was successful. +This tutorial demonstrates just how easy it is to create a brand new custom Cosmos-SDK blockchain from scratch, saving developers time. + +## Modify your chain + +New module code is usually added in the `x/` directory of your repository. +Check out the [Cosmos SDK documentation](https://docs.cosmos.network/v0.50/build/building-modules/intro) for more information on how to add modules to your chain. + +Once you're ready you can preview your chain using the section below. + +## List your chain + +You can [list your chain on Forge](https://forge.cosmos.network/list-your-chain), even if it's not finished, in the **pre-launch** stage. diff --git a/docs/docs/consumer-development/offboarding.md b/docs/docs/consumer-development/offboarding.md index ff252ad550..0567566ed2 100644 --- a/docs/docs/consumer-development/offboarding.md +++ b/docs/docs/consumer-development/offboarding.md @@ -1,5 +1,5 @@ --- -sidebar_position: 4 +sidebar_position: 5 title: Offboarding Checklist --- # Consumer Offboarding diff --git a/docs/docs/consumer-development/onboarding.md b/docs/docs/consumer-development/onboarding.md index 1613a2f268..5d6f42ef20 100644 --- a/docs/docs/consumer-development/onboarding.md +++ b/docs/docs/consumer-development/onboarding.md @@ -1,7 +1,8 @@ --- -sidebar_position: 3 +sidebar_position: 4 title: Onboarding Checklist --- + # Consumer Onboarding Checklist The following checklists will aid in onboarding a new consumer chain to Interchain Security. @@ -52,6 +53,7 @@ gather community support and accept feedback from the community, validators and - [ ] if desired, decide on power-shaping parameters (see [Power Shaping](../features/power-shaping.md)) Example of initialization parameters: + ```js // ConsumerInitializationParameters provided in MsgCreateConsumer or MsgUpdateConsumer { @@ -100,6 +102,7 @@ Example of initialization parameters: ``` Example of power-shaping parameters: + ```js // PowerShaping parameters provided in MsgCreateConsumer or MsgUpdateConsumer {