From d8c851c8fd6b9267f46f9d3cec8d29bc14102933 Mon Sep 17 00:00:00 2001 From: Reece Williams Date: Sun, 29 Sep 2024 13:24:06 -0500 Subject: [PATCH 01/11] re-order, add testimonials --- docs/sidebars.js | 40 ------------------- .../version-v0.50.x/00-meet-spawn.md | 9 +++++ .../01-nameservice.md | 2 +- .../07-conclusion.md | 2 +- .../08-ibc-module.md} | 14 +++---- .../02-build-your-application/_category_.json | 2 +- 6 files changed, 19 insertions(+), 50 deletions(-) rename docs/versioned_docs/version-v0.50.x/{03-demos/02-ibc-module.md => 02-build-your-application/08-ibc-module.md} (95%) diff --git a/docs/sidebars.js b/docs/sidebars.js index 3d59195f..ec21434f 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -16,47 +16,7 @@ const sidebars = { // By default, Docusaurus generates a sidebar from the docs folder structure defaultSidebar: [ { type: "autogenerated", dirName: "." }, - // { - // type: "category", - // label: "Resources", - // collapsed: true, - // items: [ - // { - // type: "link", - // label: "IBC", - // href: "https://ibc.cosmos.network/v8", - // }, - // { - // type: "link", - // label: "Cosmos-SDK", - // href: "https://docs.cosmos.network", - // }, - // { - // type: "link", - // label: "Developer Portal", - // href: "https://tutorials.cosmos.network", - // }, - // { - // type: "link", - // label: "Awesome Cosmos", - // href: "https://github.com/cosmos/awesome-cosmos", - // }, - // ], - // }, ], - - // But you can create a sidebar manually - /* - tutorialSidebar: [ - 'intro', - 'hello', - { - type: 'category', - label: 'Tutorial', - items: ['tutorial-basics/create-a-document'], - }, - ], - */ }; module.exports = sidebars diff --git a/docs/versioned_docs/version-v0.50.x/00-meet-spawn.md b/docs/versioned_docs/version-v0.50.x/00-meet-spawn.md index c1b49946..8f02ccec 100644 --- a/docs/versioned_docs/version-v0.50.x/00-meet-spawn.md +++ b/docs/versioned_docs/version-v0.50.x/00-meet-spawn.md @@ -16,3 +16,12 @@ Spawn is the easiest way to build, maintain and scale a Cosmos SDK blockchain. S [Follow Along with the NameService demo](../version-v0.50.x/02-build-your-application/01-nameservice.md) + + +## Testimonials + +> "Spawn is a marked transformation in CosmosSDK protocol development, allowing scaffolding and upgrading from 0.47 to 0.50 to be achievable and understandable. Without the tool, this would have been a dedicated multi-month effort" - Ash, [Burnt.com](https://burnt.com/) + + +> "Spawn has truly streamlined the developer onboarding process into the Cosmos ecosystem, seamless and efficient." - [Anil](https://x.com/anilcse_/status/1840444855576846355) [VitWit](https://www.vitwit.com/) + diff --git a/docs/versioned_docs/version-v0.50.x/02-build-your-application/01-nameservice.md b/docs/versioned_docs/version-v0.50.x/02-build-your-application/01-nameservice.md index 617d1ff4..cb59f35f 100644 --- a/docs/versioned_docs/version-v0.50.x/02-build-your-application/01-nameservice.md +++ b/docs/versioned_docs/version-v0.50.x/02-build-your-application/01-nameservice.md @@ -1,6 +1,6 @@ --- title: "Name Service" -sidebar_label: "Build A Name Service" +sidebar_label: "Build a Name Service" sidebar_position: 1 slug: /build/name-service --- diff --git a/docs/versioned_docs/version-v0.50.x/02-build-your-application/07-conclusion.md b/docs/versioned_docs/version-v0.50.x/02-build-your-application/07-conclusion.md index b5c594c8..58ac8964 100644 --- a/docs/versioned_docs/version-v0.50.x/02-build-your-application/07-conclusion.md +++ b/docs/versioned_docs/version-v0.50.x/02-build-your-application/07-conclusion.md @@ -21,7 +21,7 @@ You just crafted your first blockchain, module, and custom logic with Spawn. You ## What's Next? -Extend the NameService to include IBC support with the [ibc-module](../03-demos/02-ibc-module.md) tutorial. +Extend the NameService to include IBC support with the [ibc-module](./08-ibc-module.md) tutorial. diff --git a/docs/versioned_docs/version-v0.50.x/03-demos/02-ibc-module.md b/docs/versioned_docs/version-v0.50.x/02-build-your-application/08-ibc-module.md similarity index 95% rename from docs/versioned_docs/version-v0.50.x/03-demos/02-ibc-module.md rename to docs/versioned_docs/version-v0.50.x/02-build-your-application/08-ibc-module.md index bc8f0393..2afa31d1 100644 --- a/docs/versioned_docs/version-v0.50.x/03-demos/02-ibc-module.md +++ b/docs/versioned_docs/version-v0.50.x/02-build-your-application/08-ibc-module.md @@ -1,18 +1,18 @@ --- -title: "IBC Module" -sidebar_label: "IBC NameService Module" -sidebar_position: 1 -slug: /demo/ibc-module +title: "IBC NameService Module" +sidebar_label: "IBC NameService (Part 2)" +sidebar_position: 8 +slug: /build/name-service-ibc-module --- -# IBC NameService Module +# IBC Name Service Module -In this section, you will build on top of the Service tutorial to add cross chain functionality. This will allow you to sent a name from another network. +In this section, you will build on top of the Name Service tutorial to add cross chain functionality. This will allow you to sent a name from another network. ## Prerequisites - [System Setup](../01-setup/01-system-setup.md) - [Install Spawn](../01-setup/02-install-spawn.md) -- [Build Your Name Service Chain Tutorial](../02-build-your-application/01-nameservice.md) +- [Build Your Name Service Chain Tutorial](./01-nameservice.md) ## Create your chain diff --git a/docs/versioned_docs/version-v0.50.x/02-build-your-application/_category_.json b/docs/versioned_docs/version-v0.50.x/02-build-your-application/_category_.json index a288d2c0..f404af08 100644 --- a/docs/versioned_docs/version-v0.50.x/02-build-your-application/_category_.json +++ b/docs/versioned_docs/version-v0.50.x/02-build-your-application/_category_.json @@ -1,5 +1,5 @@ { - "label": "Your First Application", + "label": "Build Your Application", "position": 2, "link": null } From bc3e740e47d5018f643deec24fd4cf939a8130c1 Mon Sep 17 00:00:00 2001 From: Reece Williams Date: Sun, 29 Sep 2024 15:01:42 -0500 Subject: [PATCH 02/11] cw-nft demo --- .../{01-demo.md => 01-ibc-transfer-demo.md} | 0 .../03-demos/02-cw-nft-demo.md | 274 ++++++++++++++++++ 2 files changed, 274 insertions(+) rename docs/versioned_docs/version-v0.50.x/03-demos/{01-demo.md => 01-ibc-transfer-demo.md} (100%) create mode 100644 docs/versioned_docs/version-v0.50.x/03-demos/02-cw-nft-demo.md diff --git a/docs/versioned_docs/version-v0.50.x/03-demos/01-demo.md b/docs/versioned_docs/version-v0.50.x/03-demos/01-ibc-transfer-demo.md similarity index 100% rename from docs/versioned_docs/version-v0.50.x/03-demos/01-demo.md rename to docs/versioned_docs/version-v0.50.x/03-demos/01-ibc-transfer-demo.md diff --git a/docs/versioned_docs/version-v0.50.x/03-demos/02-cw-nft-demo.md b/docs/versioned_docs/version-v0.50.x/03-demos/02-cw-nft-demo.md new file mode 100644 index 00000000..dff840a2 --- /dev/null +++ b/docs/versioned_docs/version-v0.50.x/03-demos/02-cw-nft-demo.md @@ -0,0 +1,274 @@ +--- +title: "NFTs" +sidebar_label: "NFT Demo" +sidebar_position: 1 +slug: /demo/cw-nft +--- + +# Non-fungible Token Demo + +You will build a new chain with [CosmWasm](https://cosmwasm.com/), enabling support for smart contracts on a new Cosmos-SDK application. You will download a pre-built contract, upload it, and interact with it to transfer the ownership of some data. + +If you do not know what an NFT is, you can read about them here: [investopedia.com/non-fungible-tokens-nft](https://www.investopedia.com/non-fungible-tokens-nft-5115211). + +:::note Warning +Some parts of this tutorial will not have the added context about spawn's inner workings or how commands work. Run through [Build Your Application](../02-build-your-application/01-nameservice.md) for this context. +::: + +## Prerequisites +- [System Setup](../01-setup/01-system-setup.md) +- [Install Spawn](../01-setup/02-install-spawn.md) + +:::note Danger +Some machines like Windows and ARM64 (MacOS) will not work with running the testnet. This is a limitation of the operating system hardware with wasm and required C language libraries / DLLs. For the best experience, use a Linux machine or a cloud-based linux instance from [Hetzner](https://www.hetzner.com/cloud/) or [Digital Ocean](https://www.digitalocean.com/pricing/droplets) for $6 per month. +::: + + +## Create your chain + +Build a new chain that has CosmWasm configured. + + + + +```bash +GITHUB_USERNAME=rollchains + +spawn new rollchain \ +--consensus=proof-of-stake \ +--bech32=roll \ +--denom=uroll \ +--bin=rolld \ +--disabled=block-explorer \ +--org=${GITHUB_USERNAME} +``` + +
+ +View UI Selector + +If you remove the `--disabled` flag; a more intuitive UI selection approach will be taken. Make sure CosmWasm is selected with the green arrow, then press `done`. + +![Image](https://github.com/user-attachments/assets/16698f3f-143b-4258-9ff2-fc429764b58c) + +
+ +--- + + +## Start the testnet + +:::note Note +If `make sh-testnet` does not start due to a port bind error, you can kill your previously running testnet with `killall -9 rolld`, then try again. +::: + + +```bash +# move into the chain directory +cd rollchain + +# - Installs the binary +# - Setups the default keys with funds +# - Starts the chain in your shell +make sh-testnet +``` + +## Verify CosmWasm is enabled + +```bash +rolld q wasm params +``` + + +
+ +Expected Output + +```bash +code_upload_access: + addresses: [] + permission: Everybody + instantiate_default_permission: Everybody +``` + +
+ +## Upload the contract to the network + +You will use the [CW721](https://github.com/public-awesome/cw-nfts) contract for your NFT journey. CW721 stands for CosmWasm 721. [721 corresponds to the Ethereum specification for NFTs](https://www.coinbase.com/learn/crypto-glossary/what-is-erc-721). Understanding this is out of scope for this tutorial. Just know you can create, transfer, and query data. + +Download the contract code from the CosmWasm NFTs repository, then upload it to the network with the application binary. + +```bash +# Download the the NFT contract to your machine +curl -LO https://github.com/public-awesome/cw-nfts/releases/download/v0.19.0/cw721_base.wasm + +# Upload the source code to the chain +# - gas is is amount of compute resources to allocate. +rolld tx wasm store ./cw721_base.wasm --from=acc0 --chain-id=localchain-1 \ + --gas=auto --gas-adjustment=2.0 --yes +``` + +## Verify the code was uploaded + +```bash +# Code id: "1" is available +rolld q wasm list-code + +# See the details (A lot of spam) +rolld q tx 4601FBACBDF93E4309D92E968F8B4E7F9177BCB132B65AA363AFDC26FE6B5CB6 +``` + +
+ +Expected Code Info + +```bash +(main) -> $ rolld q wasm list-code +code_infos: +- code_id: "1" + creator: roll1hj5fveer5cjtn4wd6wstzugjfdxzl0xpg2te87 + data_hash: E13AA30E0D70EA895B294AD1BC809950E60FE081B322B1657F75B67BE6021B1C + instantiate_permission: + addresses: [] + permission: Everybody +pagination: + next_key: null + total: "0" +``` + +
+ + + +## Create a new NFT collection + +With the source now uploaded, anyone can create a new NFT collection with this base contract code now on the chain. This will be a new contract that only we control. Now, instantiate the contract to create the new NFT collection. + +
+ +Instantiate Format Source + +You can find the instantiate, execute, and query messages (json) formats in the contract source code. + +```rust reference title="packages/cw721/src/msg.rs" +https://github.com/public-awesome/cw-nfts/blob/v0.19.0/packages/cw721/src/msg.rs#L126-L143 +``` +
+ +:::note Warning +Notice the MESSAGE= below has no spaces in the JSON. This is required for the command line to parse it correctly. Failure to do so will result in the error + +`ERR failure when running app err="accepts 2 arg(s), received 3"` +::: + +```bash +# Get our account address for the acc0 wallet / key. +rolld keys show acc0 -a # roll1hj5fveer5cjtn4wd6wstzugjfdxzl0xpg2te87 + +# Create the NFT collection with our account +# as the authorized minter / creator for new NFTs. +MESSAGE='{"name":"Roll","symbol":"ROLL","minter":"roll1hj5fveer5cjtn4wd6wstzugjfdxzl0xpg2te87"}' + +# Create the NFT collection +rolld tx wasm instantiate 1 $MESSAGE --no-admin --from=acc0 --label="my-nft" \ + --chain-id=localchain-1 --gas=auto --gas-adjustment=2.0 --yes +``` + +## Contract address + +A contract address is where all the collection and information is stored. It never changes and is the unique identifier for interaction. Think of this similar to a website, google.com always brings you to google search. `NFT_CONTRACT` is always the RollNFTs collection. + +```bash +# View all contract addresses we have created +rolld q wasm list-contracts-by-creator roll1hj5fveer5cjtn4wd6wstzugjfdxzl0xpg2te87 + +# The contract address for the NFT collection we just created +NFT_CONTRACT=roll14hj2tavq8fpesdwxxcu44rty3hh90vhujrvcmstl4zr3txmfvw9sjczpjh +``` + + + +## Create an NFT in the collection + +The acc0 account now must create the first NFT in the collection since it is the minter. Specify the unique ID (1), the owner (acc0), and some data to be associated with this NFT. Set the url of a sunflower image as the metadata for this tutorial. + +:::note Note +The `token_uri` is a URL that points to the metadata of the NFT. This can be a [JSON object](https://eips.ethereum.org/EIPS/eip-721#specification) or a URL to a JSON object. +This URL can be a link to an external service like [IPFS](https://ipfs.tech/), or the raw text directly. The contract does not care, it is up to you to manage the data and build the services around it. +::: + +
+ +Execute Format Source + +```rust reference title="packages/cw721/src/msg.rs" +https://github.com/public-awesome/cw-nfts/blob/v0.19.0/packages/cw721/src/msg.rs#L80-L91 +``` +
+ + +```bash +MESSAGE='{"mint":{"token_id":"1","owner":"roll1hj5fveer5cjtn4wd6wstzugjfdxzl0xpg2te87","token_uri":"https://onlinejpgtools.com/images/examples-onlinejpgtools/sunflower.jpg"}}' + +rolld tx wasm execute $NFT_CONTRACT $MESSAGE --from=acc0 --chain-id=localchain-1 \ + --gas=auto --gas-adjustment=2.0 --yes +``` + +## Grab this NFT data + +There is now an NFT with the ID of 1 owned by `roll1hj5fveer5cjtn4wd6wstzugjfdxzl0xpg2te87`. Now query the contract to see the data and verify it is correct. + +
+ +Query Format Source + +```rust reference title="packages/cw721/src/msg.rs" +https://github.com/public-awesome/cw-nfts/blob/v0.19.0/packages/cw721/src/msg.rs#L157-L161 +``` + +```rust reference title="packages/cw721/src/msg.rs" +https://github.com/public-awesome/cw-nfts/blob/v0.19.0/packages/cw721/src/msg.rs#L236-L240 +``` + +
+ +```bash +# Get who is the owner of ID 1 +rolld q wasm state smart $NFT_CONTRACT '{"owner_of":{"token_id":"1"}}' + +# Retrieve the NFT info +rolld q wasm state smart $NFT_CONTRACT '{"nft_info":{"token_id":"1"}}' +``` + +## Transfer the NFT to another account + +Now move the token from the originally minted account (acc0) to another account (acc1). This is a simple transfer of ownership to move who owns the data. + +
+ +Execute Format Source + +```rust reference title="packages/cw721/src/msg.rs" +https://github.com/public-awesome/cw-nfts/blob/v0.19.0/packages/cw721/src/msg.rs#L44-L48 +``` + +
+ +```bash +# Recipient account +rolld keys show acc1 -a # roll1efd63aw40lxf3n4mhf7dzhjkr453axur57cawh + +MESSAGE='{"transfer_nft":{"recipient":"roll1efd63aw40lxf3n4mhf7dzhjkr453axur57cawh","token_id":"1"}}' +rolld tx wasm execute $NFT_CONTRACT $MESSAGE --from=acc0 --chain-id=localchain-1 --gas=auto --gas-adjustment=2.0 --yes + +# Get who is the owner of 1 +# Moved to: roll1efd63aw40lxf3n4mhf7dzhjkr453axur57cawh +rolld q wasm state smart $NFT_CONTRACT '{"owner_of":{"token_id":"1"}}' +``` + +## Conclusion + +In this tutorial, you built a new chain with CosmWasm enabled, launched a testnet for it, and launched an NFT collection! You uploaded a contract, created an NFT, and transferred it to another account. This is the foundation for building a new unique marketplace or game on the Interchain. + + From 028d1cb90145f3638f53d7be87819936708a2b3b Mon Sep 17 00:00:00 2001 From: Reece Williams Date: Sun, 29 Sep 2024 17:50:49 -0500 Subject: [PATCH 03/11] cosmetic tweaks --- .../03-demos/01-ibc-transfer-demo.md | 2 +- .../version-v0.50.x/03-demos/02-cw-nft-demo.md | 18 ++++++------------ 2 files changed, 7 insertions(+), 13 deletions(-) diff --git a/docs/versioned_docs/version-v0.50.x/03-demos/01-ibc-transfer-demo.md b/docs/versioned_docs/version-v0.50.x/03-demos/01-ibc-transfer-demo.md index 35abc176..caa92e3d 100644 --- a/docs/versioned_docs/version-v0.50.x/03-demos/01-ibc-transfer-demo.md +++ b/docs/versioned_docs/version-v0.50.x/03-demos/01-ibc-transfer-demo.md @@ -1,6 +1,6 @@ --- title: "IBC Transfers" -sidebar_label: "IBC Transfer Demo" +sidebar_label: "IBC Transfers" sidebar_position: 1 slug: /demo/ibc --- diff --git a/docs/versioned_docs/version-v0.50.x/03-demos/02-cw-nft-demo.md b/docs/versioned_docs/version-v0.50.x/03-demos/02-cw-nft-demo.md index dff840a2..3204ab6e 100644 --- a/docs/versioned_docs/version-v0.50.x/03-demos/02-cw-nft-demo.md +++ b/docs/versioned_docs/version-v0.50.x/03-demos/02-cw-nft-demo.md @@ -1,6 +1,6 @@ --- -title: "NFTs" -sidebar_label: "NFT Demo" +title: "CW NFTs" +sidebar_label: "CosmWasm NFTs" sidebar_position: 1 slug: /demo/cw-nft --- @@ -28,9 +28,6 @@ Some machines like Windows and ARM64 (MacOS) will not work with running the test Build a new chain that has CosmWasm configured. - - - ```bash GITHUB_USERNAME=rollchains @@ -53,8 +50,6 @@ If you remove the `--disabled` flag; a more intuitive UI selection approach will ---- - ## Start the testnet @@ -79,7 +74,6 @@ make sh-testnet rolld q wasm params ``` -
Expected Output @@ -105,7 +99,7 @@ curl -LO https://github.com/public-awesome/cw-nfts/releases/download/v0.19.0/cw7 # Upload the source code to the chain # - gas is is amount of compute resources to allocate. -rolld tx wasm store ./cw721_base.wasm --from=acc0 --chain-id=localchain-1 \ +rolld tx wasm store ./cw721_base.wasm --from=acc0 \ --gas=auto --gas-adjustment=2.0 --yes ``` @@ -172,7 +166,7 @@ MESSAGE='{"name":"Roll","symbol":"ROLL","minter":"roll1hj5fveer5cjtn4wd6wstzugjf # Create the NFT collection rolld tx wasm instantiate 1 $MESSAGE --no-admin --from=acc0 --label="my-nft" \ - --chain-id=localchain-1 --gas=auto --gas-adjustment=2.0 --yes + --gas=auto --gas-adjustment=2.0 --yes ``` ## Contract address @@ -211,7 +205,7 @@ https://github.com/public-awesome/cw-nfts/blob/v0.19.0/packages/cw721/src/msg.rs ```bash MESSAGE='{"mint":{"token_id":"1","owner":"roll1hj5fveer5cjtn4wd6wstzugjfdxzl0xpg2te87","token_uri":"https://onlinejpgtools.com/images/examples-onlinejpgtools/sunflower.jpg"}}' -rolld tx wasm execute $NFT_CONTRACT $MESSAGE --from=acc0 --chain-id=localchain-1 \ +rolld tx wasm execute $NFT_CONTRACT $MESSAGE --from=acc0 \ --gas=auto --gas-adjustment=2.0 --yes ``` @@ -260,7 +254,7 @@ https://github.com/public-awesome/cw-nfts/blob/v0.19.0/packages/cw721/src/msg.rs rolld keys show acc1 -a # roll1efd63aw40lxf3n4mhf7dzhjkr453axur57cawh MESSAGE='{"transfer_nft":{"recipient":"roll1efd63aw40lxf3n4mhf7dzhjkr453axur57cawh","token_id":"1"}}' -rolld tx wasm execute $NFT_CONTRACT $MESSAGE --from=acc0 --chain-id=localchain-1 --gas=auto --gas-adjustment=2.0 --yes +rolld tx wasm execute $NFT_CONTRACT $MESSAGE --from=acc0 --gas=auto --gas-adjustment=2.0 --yes # Get who is the owner of 1 # Moved to: roll1efd63aw40lxf3n4mhf7dzhjkr453axur57cawh From c41aa890e0e931a25ce6b0d4fbee1f2f8e85a4da Mon Sep 17 00:00:00 2001 From: Reece Williams Date: Sun, 29 Sep 2024 17:51:33 -0500 Subject: [PATCH 04/11] add tokenfactory tutorial --- .../03-demos/01-ibc-transfer-demo.md | 2 +- .../03-demos/02-cw-nft-demo.md | 2 +- .../03-demos/03-tokenfactory.md | 242 ++++++++++++++++++ 3 files changed, 244 insertions(+), 2 deletions(-) create mode 100644 docs/versioned_docs/version-v0.50.x/03-demos/03-tokenfactory.md diff --git a/docs/versioned_docs/version-v0.50.x/03-demos/01-ibc-transfer-demo.md b/docs/versioned_docs/version-v0.50.x/03-demos/01-ibc-transfer-demo.md index caa92e3d..d3ffc578 100644 --- a/docs/versioned_docs/version-v0.50.x/03-demos/01-ibc-transfer-demo.md +++ b/docs/versioned_docs/version-v0.50.x/03-demos/01-ibc-transfer-demo.md @@ -1,8 +1,8 @@ --- title: "IBC Transfers" sidebar_label: "IBC Transfers" -sidebar_position: 1 slug: /demo/ibc +# sidebar_position: 1 --- # IBC Demo diff --git a/docs/versioned_docs/version-v0.50.x/03-demos/02-cw-nft-demo.md b/docs/versioned_docs/version-v0.50.x/03-demos/02-cw-nft-demo.md index 3204ab6e..9549a7bf 100644 --- a/docs/versioned_docs/version-v0.50.x/03-demos/02-cw-nft-demo.md +++ b/docs/versioned_docs/version-v0.50.x/03-demos/02-cw-nft-demo.md @@ -1,8 +1,8 @@ --- title: "CW NFTs" sidebar_label: "CosmWasm NFTs" -sidebar_position: 1 slug: /demo/cw-nft +# sidebar_position: 1 --- # Non-fungible Token Demo diff --git a/docs/versioned_docs/version-v0.50.x/03-demos/03-tokenfactory.md b/docs/versioned_docs/version-v0.50.x/03-demos/03-tokenfactory.md new file mode 100644 index 00000000..fc853c68 --- /dev/null +++ b/docs/versioned_docs/version-v0.50.x/03-demos/03-tokenfactory.md @@ -0,0 +1,242 @@ +--- +title: "Token Factory" +sidebar_label: "Token Factory" +slug: /demo/tokenfactory +# sidebar_position: 1 +--- + +# Tokenfactory + +You will build a new chain with [TokenFactory](https://github.com/strangelove-ventures/tokenfactory), enabling any account to create, transfer, and interact with fractionalized native tokens. + +:::note Warning +Some parts of this tutorial will not have the added context about spawn's inner workings or how commands work. Run through [Build Your Application](../02-build-your-application/01-nameservice.md) for this context. +::: + +## Prerequisites +- [System Setup](../01-setup/01-system-setup.md) +- [Install Spawn](../01-setup/02-install-spawn.md) + + +## Create your chain + +Build a new chain that has TokenFactory configured. By default, it is enabled. + +```bash +GITHUB_USERNAME=rollchains + +spawn new rollchain \ +--consensus=proof-of-stake \ +--bech32=roll \ +--denom=uroll \ +--bin=rolld \ +--disabled=cosmwasm,block-explorer \ +--org=${GITHUB_USERNAME} +``` + + +## Start the testnet + +:::note Note +If `make sh-testnet` does not start due to a port bind error, you can kill your previously running testnet with `killall -9 rolld`, then try again. +::: + + +```bash +# move into the chain directory +cd rollchain + +# - Installs the binary +# - Setups the default keys with funds +# - Starts the chain in your shell +make sh-testnet +``` + +## Confirm tokenfactory is enabled + +```bash +rolld q tokenfactory params +``` + +
+params output + +The `denom_creation_fee` is a cost the application can set for creating new tokens by default, there is no cost. + +The `denom_creation_gas_consume` is the amount of indirect resource cost to consume for creating a new token. +It is a more indirect approach to charging and is a better experience overall for developers on a network. + +```bash +params: + denom_creation_fee: [] + denom_creation_gas_consume: "100000" +``` +
+ +## Create a token + + +```bash +# Create a denom (native token) +# - gas is is amount of compute resources to allocate. +rolld tx tokenfactory create-denom mytoken --from=acc0 --chain-id=localchain-1 --yes +``` + +## Verify the token was created + +```bash +# Get our account address for the acc0 wallet / key. +# acc0 is roll1hj5fveer5cjtn4wd6wstzugjfdxzl0xpg2te87 +rolld q tokenfactory denoms-from-creator $(rolld keys show acc0 -a) +``` + +
+denoms-from-creator output +```bash +denoms: +- factory/roll1hj5fveer5cjtn4wd6wstzugjfdxzl0xpg2te87/mytoken +``` +
+ +The output shows a denom with the named `factory/roll1hj5fveer5cjtn4wd6wstzugjfdxzl0xpg2te87/mytoken` + +:::note Note +Why did it add extra data to the token? + +Imagine we have 2 people, both named John. If we only use the name John, how do we know which John we are talking about? We need to add more information to the name to make it unique. This is the same concept, but with tokens. The extra data is added to ensure the token is unique while we can still contain the same base name. With tokenfactory, we place the creators name in the token. Read more about [naming collisions](https://en.wikipedia.org/wiki/Naming_collision). +::: + + +## Modify token metadata + +Clients (websites, frontends, users) may wish to see more information about the token. This is where metadata comes in. You can add a ticker symbol, description, and decimal places to the token. + +The Interchain uses 6 decimal places as the default standard. This process of expressing fractions of a value in whole numbers is called [fixed-point arithmetic](https://en.wikipedia.org/wiki/Fixed-point_arithmetic) and is used for financial precision. This means that 1 token is really 1,000,000 (10^6) of these micro base tokens. If I want to send you 0.5 of a token, I really send you 500,000 of these micro base tokens on the backend. + +```bash +# 'Denom' is short for denomination. +DENOM=factory/roll1hj5fveer5cjtn4wd6wstzugjfdxzl0xpg2te87/mytoken +DESCRIPTION="My token description" + +rolld tx tokenfactory modify-metadata $DENOM MYTOKEN "$DESCRIPTION" 6 --from acc0 --yes +``` + +## Verify the token metadata + +```bash +rolld q bank denom-metadata $DENOM +``` + +
+bank denom-metadata output +```bash +metadata: + base: factory/roll1hj5fveer5cjtn4wd6wstzugjfdxzl0xpg2te87/mytoken + denom_units: + - aliases: + - MYTOKEN + denom: factory/roll1hj5fveer5cjtn4wd6wstzugjfdxzl0xpg2te87/mytoken + - aliases: + - factory/roll1hj5fveer5cjtn4wd6wstzugjfdxzl0xpg2te87/mytoken + denom: MYTOKEN + exponent: 6 + description: My token description + display: MYTOKEN + name: factory/roll1hj5fveer5cjtn4wd6wstzugjfdxzl0xpg2te87/mytoken + symbol: MYTOKEN +``` +
+ +## Create new tokens to transfer + +The base token structure is created, but no tokens actually exists yet. We must mint new tokens to then be able to transfer them between accounts. + +```bash +# Mint 5,000,000 micro mytoken. By default this goes to the token creator. +rolld tx tokenfactory mint 5000000$DENOM --from acc0 --yes + +# Verify token creator balance: roll1hj5fveer5cjtn4wd6wstzugjfdxzl0xpg2te87 +rolld q bank balances $(rolld keys show acc0 -a) +``` + + +
+bank balances output +```bash +balances: +- amount: "5000000" + denom: factory/roll1hj5fveer5cjtn4wd6wstzugjfdxzl0xpg2te87/mytoken +- amount: "900" + denom: test +- amount: "9000000" + denom: uroll +pagination: + total: "3" +``` +
+ + +## Create new tokens for another account + +While you could mint tokens followed by a manual `tx bank send` transfer, you can also mint-to another account directly. + +```bash +# Mint 1,000,000 to another account +rolld tx tokenfactory mint-to $(rolld keys show acc1 -a) 1000000$DENOM --from acc0 --yes + +rolld q bank balances $(rolld keys show acc1 -a) +``` + +
+mint-to output +```bash +balances: +- amount: "1000000" + denom: factory/roll1hj5fveer5cjtn4wd6wstzugjfdxzl0xpg2te87/mytoken +- amount: "800" + denom: test +- amount: "10000000" + denom: uroll +pagination: + total: "3" +``` + +note, you can check for just a specific token balance with +```bash +rolld q bank balance $(rolld keys show acc0 -a) $DENOM +``` + +```bash +balance: + amount: "5000000" + denom: factory/roll1hj5fveer5cjtn4wd6wstzugjfdxzl0xpg2te87/mytoken +``` +
+ +## Transfer tokens + +Now with tokens minted, either user can transfer them as they please between any accounts. Even ones that do not yet have any tokens. + +```bash +# Send 7 base micro tokens from acc0 to acc1 +rolld tx bank send acc0 $(rolld keys show acc1 -a) 7$DENOM --from acc0 --yes + +# Verify the 7 base tokens sent and has increased to 1000007, or 1.000007 +rolld q bank balances $(rolld keys show acc1 -a) +``` + +## Burn tokens + +If you wish to remove tokens from the system, you can burn them from the admin account. + +```bash +# Burn micro tokens from account +rolld tx tokenfactory burn 123$DENOM --from acc0 --yes + +# Verify the tokens have been reduced +rolld q bank balances $(rolld keys show acc0 -a) +``` + +## Conclusion + +In this tutorial, you built a new chain with the TokenFactory feature, launched a testnet for it, and created a new native token. You minted tokens, transferred them between accounts, and burned them. These tokens could be kept internally for some personal or application based accounting, or transferred to other chains via IBC. This is showcased in the [IBC Transfer Demo](../03-demos/01-ibc-transfer-demo.md). From a3173a137e440a874ce6c5afe330a01d0d4238c8 Mon Sep 17 00:00:00 2001 From: Reece Williams Date: Sun, 29 Sep 2024 18:36:28 -0500 Subject: [PATCH 05/11] learn: network security types --- .../04-learn-spawn/01-consensus-algos.md | 152 ++++++++++++++++++ .../04-learn-spawn/_category_.json | 5 + 2 files changed, 157 insertions(+) create mode 100644 docs/versioned_docs/version-v0.50.x/04-learn-spawn/01-consensus-algos.md create mode 100644 docs/versioned_docs/version-v0.50.x/04-learn-spawn/_category_.json diff --git a/docs/versioned_docs/version-v0.50.x/04-learn-spawn/01-consensus-algos.md b/docs/versioned_docs/version-v0.50.x/04-learn-spawn/01-consensus-algos.md new file mode 100644 index 00000000..be4a7535 --- /dev/null +++ b/docs/versioned_docs/version-v0.50.x/04-learn-spawn/01-consensus-algos.md @@ -0,0 +1,152 @@ +--- +title: "Network Security" +sidebar_label: "Network Security Types" +slug: /learn/consensus-security +# sidebar_position: 1 +--- + +# Network Security Types + +## Prerequisites +- [System Setup](../01-setup/01-system-setup.md) +- [Install Spawn](../01-setup/02-install-spawn.md) + +Learn about the different network security methods you can create with spawn and the different pros and cons of each. These are called [consensus algorithms](https://en.wikipedia.org/wiki/Consensus_(computer_science)) and are how the network agrees on what actions get put through, and which are rejected. + +:::note Danger +This topic is a little more advanced due to technical speak. It is condensed to as a high level of an overview as possible. Please contribute if you can make it more accessible to average readers. +::: + +## Choose for me (TLDR) + +If you just want to build an application and don't want to focus on tokenomics or game theory, use [proof of authority](#proof-of-authority-poa). If a token is part of your product or required to financially reward users with some lock mechanism and long term incentives, use [proof of stake](#proof-of-stake-pos). If you have plans for a large amount of value to be secured or don't want to run your own network nodes, use [interchain security](#interchain-security-ics). + +## Proof of Authority (PoA) + +### Default +If you do not know which security module best fits for you, use this one. The source code for this feature can be found [here](https://github.com/strangelove-ventures/poa). The most popular example of this security model is [Circle's](https://www.circle.com/en/) USDC issuance network, [Noble](https://www.noble.xyz/) ([twitter](https://twitter.com/noble_xyz)). + +### What it does +If you have an application and you want the network to run as efficiently as possible with a trusted set of internal nodes or external trusted 3 parties (validators), use [Proof of Authority](https://en.wikipedia.org/wiki/Proof_of_authority). + +### Create a PoA network +To create a new network with proof-of-authority, use the `--consensus=proof-of-authority` flag. If `--consensus` is not present, a selector UI will appear in your terminal to see all options. + +```bash +-> $ spawn new mychain +Consensus Selector (( enter to toggle )) + Done + ✔ proof-of-authority + proof-of-stake + interchain-security +``` + +```bash +spawn new rollchain \ + --consensus=proof-of-authority \ + --disabled=cosmwasm,block-explorer +``` + +### Considerations + +#### Benefits +- Fast Transactions: Fewer people need to agree, so it can process transactions very quickly. +- Less Power Usage: Doesn’t require much electricity, making it more eco-friendly. +- Easy to Maintain: Only a few trusted people are in charge, making it simpler to run. +- Stable Performance: Because only a few people make decisions, things tend to run smoothly and predictably. + +#### Downsides +- Centralized Control: A small group of people are in charge, which can lead to concerns about too much power in one place. +- Requires Trust: You have to trust the people in charge to make fair decisions, which can be risky. +- Less Diversity: Having fewer people in control means less variety in opinions and locations, which might be a problem if those people get compromised. +- Less Community Involvement: Regular users don’t have much of a role in helping the system, so it feels less like a community effort. + +## Proof of Stake (PoS) + +### What it does +You can have the value of a network back itself by users risking their own tokens to prove they are trustworthy. This is called [Proof of Stake](https://en.wikipedia.org/wiki/Proof_of_stake). Believers in an application lock their tokens to earn a small portion of rewards, similar to a bank account. However, if they misbehave by trying to cheat the system or submit bad actions, the network will take a portion of their value (usually 5 - 10%) as a penalty. + +This security type is useful when you want a more distributed network that can be run by anyone with some holdings in the network. It is a trustless way to secure a network and the most popular security model in the ecosystem currently (Sept 2024). + +### Create a PoS network +To create a new network with proof-of-stake, use the `--consensus=proof-of-stake` flag. If `--consensus` is not present, a selector UI will appear in your terminal to see all options. + +```bash +-> $ spawn new mychain +Consensus Selector (( enter to toggle )) + Done + proof-of-authority + ✔ proof-of-stake + interchain-security +``` + +```bash +spawn new rollchain \ + --consensus=proof-of-stake \ + --disabled=cosmwasm,block-explorer +``` + +### Considerations + +#### Benefits +- More People Involved: Anyone can participate if they’re willing to invest, which makes the system feel more balanced and community-driven. +- Eco-Friendly: Like PoA, PoS doesn’t use much electricity, making it good for the environment. +- More Fairness: The system allows many people to help make decisions, reducing the chance of one group having too much control. +- Grows with the Community: More people can get involved as the system grows, making it scalable and inclusive. + +#### Downsides +- Slower Decision Making: Because more people are involved, it can take longer to reach a decision due to governance and politics +- Wealthy Have More Power: The more you invest, the more influence you have, which can lead to rich people having more control. +- Complex to Get Started: It can be harder for someone new to understand how to participate compared to systems with fewer decision-makers. +- Risk of Losing Investment: If you make a mistake or act dishonestly, you could lose your money, which adds some financial risk. + +## Interchain Security (ICS) + +### What it does + +Interchain security shares the economic proof of stake security of a larger parent provider with a sub network, called a consumer *(since they consume security)*. This is useful when you want to create a new network that is secure from day one, without having to bootstrap a new set of network operators and validators, and have alignment with the parent. Current networks utilizing this are [CosmosHub](https://cosmos.network/interchain-security/), [Stride](https://www.stride.zone/), and [Lido's Neutron](https://www.neutron.org/). If you are from ethereum, this is similar to an [Actively Validated Services (AVS) on Eigenlayer](https://app.eigenlayer.xyz/avs). + +The cost of running these networks is relatively low as you just pay a portion of your networks fees. This is a great way to take an application from a testnet to a mainnet with a trusted security model, especially if your application deals with a lot of possible monetary value. To compromise the network, an attacker would have to compromise the more secure parent network, which is a very high bar. + +### Create an ICS Consumer network +To create a new network with interchain-security, use the `--consensus=interchain-security` flag. If `--consensus` is not present, a selector UI will appear in your terminal to see all options. + +::note Note +We do not support creating provider networks. +::: + +```bash +-> $ spawn new mychain +Consensus Selector (( enter to toggle )) + Done + proof-of-authority + proof-of-stake + ✔ interchain-security +``` + +```bash +spawn new rollchain \ + --consensus=interchain-security \ + --disabled=cosmwasm,block-explorer +``` + +### Considerations + +#### Benefits +- No Need for Consumer Chain to Build Its Own Security: The smaller or newer chain doesn't have to recruit its own set of people to protect it. It automatically benefits from the protection of the parent network, saving time and effort. +- Easier Node Bootstrapping: Since the parent network provides the security, the consumer chain doesn’t have to build a large number of participants to protect the system from scratch. This makes launching a new chain much faster and easier. +- Shared Trust: By using the same security as a well-known, established chain, the consumer chain inherits the trust and credibility of the parent network, making it more appealing to users and developers. +- Aligned Interests: Since the parent network's security also protects the consumer chain, both chains have an interest in maintaining a secure, well-functioning system. This alignment reduces the risk of conflicts between the two. + + + +#### Downsides +- Dependence on Parent Network: The consumer chain becomes dependent on the parent network. If something goes wrong with the parent network’s security or operations, the consumer chain is also affected, even if it is unrelated to the issue. +- Limited Autonomy: The consumer chain may have less control over its own security decisions, since it’s tied to the security model of the parent network. This could limit flexibility in responding to specific needs or changes. +- Potential Congestion: If many consumer chains share the same parent network, the shared security system might become congested or stretched thin, leading to slower response times or performance issues. +- Complexity in Governance: Any changes to the shared security might require coordination between both the parent network and the consumer chain, adding complexity to decision-making and governance. +- Risk of Centralization: The reliance on a single parent network’s security model might lead to centralization, where a handful of large chains dominate the ecosystem. This reduces the diversity of security models and could concentrate power. + +## Conclusion + +You have now learned about different network security types, how to select different ones, and the pros and cons of each. You can now create a new chain with the security model that best fits your application's needs. diff --git a/docs/versioned_docs/version-v0.50.x/04-learn-spawn/_category_.json b/docs/versioned_docs/version-v0.50.x/04-learn-spawn/_category_.json new file mode 100644 index 00000000..3dff53c2 --- /dev/null +++ b/docs/versioned_docs/version-v0.50.x/04-learn-spawn/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Learn Spawn", + "position": 4, + "link": null +} From 3e111c7dcef6a2c20e9f33d5fefa5db42de07667 Mon Sep 17 00:00:00 2001 From: Reece Williams Date: Sun, 29 Sep 2024 18:52:34 -0500 Subject: [PATCH 06/11] feat: what spawn does backup --- .../04-learn-spawn/00-what-spawn-does.md | 96 +++++++++++++++++++ 1 file changed, 96 insertions(+) create mode 100644 docs/versioned_docs/version-v0.50.x/04-learn-spawn/00-what-spawn-does.md diff --git a/docs/versioned_docs/version-v0.50.x/04-learn-spawn/00-what-spawn-does.md b/docs/versioned_docs/version-v0.50.x/04-learn-spawn/00-what-spawn-does.md new file mode 100644 index 00000000..9a960422 --- /dev/null +++ b/docs/versioned_docs/version-v0.50.x/04-learn-spawn/00-what-spawn-does.md @@ -0,0 +1,96 @@ +--- +title: "Spawns Purpose" +sidebar_label: "What Spawn Does" +slug: /learn/what-spawn-does +# sidebar_position: 1 +--- + +# What Spawn Does + +Learn about what spawn does, how it works, and how it can help you build your applications faster than ever before + +## Overview + +Spawn is a powerful tool designed to streamline the process of building, maintaining, and scaling Cosmos SDK blockchains. As a developer, Spawn offers several compelling reasons to incorporate it into your workflow. + +Before, you would have at least a week setting up a new chain. You would manually copy paste some other codebase, modify it to your needs, debug issues, add custom test, fix github actions, and then you have a base network. Now you can do all this in just a flew clicks. Spawn takes in your context and with magic, generates a new network for you fitting your needs. + +## New Development + +Say you have a project idea, and you want to get started on writing the logic. Spawn gets you from 0 to 1 with the template matching your exact needs. The modular approach allows you to pick what you just have, such as smart contracts, and remove the things you don't. This way, you can focus on what matters to you. + +Get started building your first chain using the `new-chain` command. Spawn will guide you through the process of selecting the modules you need and configuring your new chain. + +```bash +spawn new mychain --help +``` + +Using `--help` will showcase examples and other options you may want to consider for your new network. + +```bash +Create a new project + +Usage: + spawn new-chain [project-name] [flags] + +Aliases: + new-chain, new, init, create + +Flags: + -b, --binary string binary name (default "simd") + --bypass-prompt bypass UI prompt + --debug enable debugging + --denom string bank token denomination (default "token") + -h, --help help for new-chain + --org string github organization (default "rollchains") + --skip-git ignore git init + --wallet-prefix string chain bech32 wallet prefix (default "cosmos") +``` + +### Security Selection + +You can read about different security models in the [Consensus Security](./01-consensus-algos.md) section. If you don't know which to select, use proof of authority for your application. + +```bash +spawn new mychain +``` + +After running the new command, use your arrow keys and use 'enter' to select the module you want to use. You can only use 1 from this list. Then select done. + +``` +Consensus Selector (( enter to toggle )) + Done + ✔ proof-of-authority + proof-of-stake + interchain-security +``` + +### Feature Selection + +You now select which features you want to include in your base application. Usually you would have to do these manually, each taking about 15 minutes to add. With spawn, we let you select them right away, automatically configure them, **and** give you testing to give you the assurance it works. + +As you scroll through features, + +```bash +Feature Selector (( enter to toggle )) + Done + ✔ tokenfactory + ✔ ibc-packetforward + ✔ ibc-ratelimit + cosmwasm + wasm-light-client + ✔ optimistic-execution + ignite-cli + ✔ block-explorer +tokenfactory: Native token minting, sending, and burning on the chain +``` + + + +--- + +# Testing + +# Modules + +# testnets From da2b71b2423a707b9f3512c92a31f3e96948ff2d Mon Sep 17 00:00:00 2001 From: Reece Williams Date: Sun, 29 Sep 2024 22:15:32 -0500 Subject: [PATCH 07/11] rm deployments --- docs/dev/DEPLOYMENTS.md | 27 --------------------------- 1 file changed, 27 deletions(-) delete mode 100644 docs/dev/DEPLOYMENTS.md diff --git a/docs/dev/DEPLOYMENTS.md b/docs/dev/DEPLOYMENTS.md deleted file mode 100644 index 6142fed7..00000000 --- a/docs/dev/DEPLOYMENTS.md +++ /dev/null @@ -1,27 +0,0 @@ -# Deployment Information - -Spawn created applications are able to be deployed in a large number of configurations. The following are some of the most common configurations: - -## Single Node - -The simplest deployment is a single node. This is the easiest to set up and is the most common for development and testing. It is also the most common for small scale production deployments. This has the following downsides: -- Single point of failure -- No redundancy -- No scalability -- Insecure IBC - -TODO: Add some options for easy deployment for single node deployments. If there's some GH action thing to deploy to a cloud that would be ideal. - -## Single Node with Horcrux - -A single node with Horcrux is a single node deployment with a Horcrux backup. This is a simple way to add redundancy to a single node deployment. This is similar to the This has the following downsides: -- No redundancy for the chain node -- Still pretty insecure IBC - -TODO: Add a guide for setting this up. this option is relatively hard to do and doesn't really offer a whole ton more but we have it :shrug: - -## Full Consensus Network - -A full consensus network is a network with a full set of nodes. This is the most secure and scalable deployment. It requires at least 4 nodes to be secure. It is more expensive to run and more complex to set up, but provides much more security for IBC and allows for more complex incetive structures. - -TODO: Some of the following: guides for setting up all the nodes yourself, maybe a cloud deployment option. A list of validators who are interested in deploying these types of networks. A talk to us button. \ No newline at end of file From 3dc69844a46c3ca7a4b41cefab4d9c8cee4109fb Mon Sep 17 00:00:00 2001 From: Reece Williams Date: Sun, 29 Sep 2024 22:16:04 -0500 Subject: [PATCH 08/11] fix: remove 'we' and be more declaring --- .../version-v0.50.x/01-setup/01-system-setup.md | 4 ++-- .../02-build-your-application/01-nameservice.md | 2 +- .../version-v0.50.x/02-build-your-application/05-testnet.md | 4 ++-- .../02-build-your-application/06-extra-challenge.md | 2 +- .../version-v0.50.x/03-demos/01-ibc-transfer-demo.md | 2 +- .../version-v0.50.x/03-demos/02-cw-nft-demo.md | 6 +++--- .../version-v0.50.x/03-demos/03-tokenfactory.md | 4 ++-- .../version-v0.50.x/04-learn-spawn/01-consensus-algos.md | 2 +- 8 files changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/versioned_docs/version-v0.50.x/01-setup/01-system-setup.md b/docs/versioned_docs/version-v0.50.x/01-setup/01-system-setup.md index b823d4fa..e49419f4 100644 --- a/docs/versioned_docs/version-v0.50.x/01-setup/01-system-setup.md +++ b/docs/versioned_docs/version-v0.50.x/01-setup/01-system-setup.md @@ -9,13 +9,13 @@ slug: /install/system-setup # Overview :::note Synopsis -Setup your development environment with the essentials to get started building your blockchain. +Setup your development environment with the essentials to get started building the blockchain. ::: ## System Requirements -Before we can install and interact with spawn, you must have the following core tools installed: +Before you can install and interact with spawn, you must have the following core tools installed: * [`Go 1.22+`](https://go.dev/doc/install) * [`Docker`](https://docs.docker.com/get-docker/) * [`Git`](https://git-scm.com/) diff --git a/docs/versioned_docs/version-v0.50.x/02-build-your-application/01-nameservice.md b/docs/versioned_docs/version-v0.50.x/02-build-your-application/01-nameservice.md index cb59f35f..750406c9 100644 --- a/docs/versioned_docs/version-v0.50.x/02-build-your-application/01-nameservice.md +++ b/docs/versioned_docs/version-v0.50.x/02-build-your-application/01-nameservice.md @@ -24,7 +24,7 @@ Building your first Cosmos-SDK blockchain with Spawn. This tutorial focuses on a ## Generate a New Chain -Let's create a new chain called 'rollchain'. We are going to set defining characteristics such as +Let's create a new chain called 'rollchain'. You are going to set defining characteristics such as - Which modules to disable from the template *if any* - Proof of Stake consensus - Wallet prefix (bech32) diff --git a/docs/versioned_docs/version-v0.50.x/02-build-your-application/05-testnet.md b/docs/versioned_docs/version-v0.50.x/02-build-your-application/05-testnet.md index 73642ba7..4532f8ac 100644 --- a/docs/versioned_docs/version-v0.50.x/02-build-your-application/05-testnet.md +++ b/docs/versioned_docs/version-v0.50.x/02-build-your-application/05-testnet.md @@ -28,9 +28,9 @@ The chain will begin to create (mint) new blocks. You can see the logs of the ne ### Interact Set Name -Using the newly built binary *(rolld from the --bin flag when we created the chain)*, you are going to execute the `set` transaction to your name. In this example we will use "alice". This links account `acc1` address to the desired name in the keeper. +Using the newly built binary *(rolld from the --bin flag when the chain was created)*, you are going to execute the `set` transaction to your name. In this example, use "alice". This links account `acc1` address to the desired name in the keeper. -Then, we resolve this name with the nameservice lookup. `$(rolld keys show acc1 -a)` is a substitute for the acc1's address. You can also use just `roll1hj5fveer5cjtn4wd6wstzugjfdxzl0xpg2te87` here. +Then, resolve this name with the nameservice lookup. `$(rolld keys show acc1 -a)` is a substitute for the acc1's address. You can also use just `roll1hj5fveer5cjtn4wd6wstzugjfdxzl0xpg2te87` here. ```bash rolld tx nameservice set alice --from=acc1 --yes diff --git a/docs/versioned_docs/version-v0.50.x/02-build-your-application/06-extra-challenge.md b/docs/versioned_docs/version-v0.50.x/02-build-your-application/06-extra-challenge.md index 9ff08e77..01b29829 100644 --- a/docs/versioned_docs/version-v0.50.x/02-build-your-application/06-extra-challenge.md +++ b/docs/versioned_docs/version-v0.50.x/02-build-your-application/06-extra-challenge.md @@ -91,7 +91,7 @@ make proto-gen
Hint #2 -

Iterate through the `k.Keeper.NameMapping`, check the Value(). if it matches the name we requested, return that wallet (Key)

+

Iterate through the `k.Keeper.NameMapping`, check the Value(). if it matches the name requested, return that wallet (Key)

diff --git a/docs/versioned_docs/version-v0.50.x/03-demos/01-ibc-transfer-demo.md b/docs/versioned_docs/version-v0.50.x/03-demos/01-ibc-transfer-demo.md index d3ffc578..e3cb24af 100644 --- a/docs/versioned_docs/version-v0.50.x/03-demos/01-ibc-transfer-demo.md +++ b/docs/versioned_docs/version-v0.50.x/03-demos/01-ibc-transfer-demo.md @@ -18,7 +18,7 @@ In this tutorial, we'll create and interact with a new Cosmos-SDK blockchain cal Create your chain using the spawn command line tool. Change the `GITHUB_USERNAME` to your github username. If you do not have a github, leaving it as default is fine. -We create a [Proof of Authority](https://en.wikipedia.org/wiki/Proof_of_authority) network to focus on our application logic rather than worry about the security model. This is a great starting point for new chains. +Create a [Proof of Authority](https://en.wikipedia.org/wiki/Proof_of_authority) network to focus on the application logic rather than worry about the security model. This is a great starting point for new chains. ```bash GITHUB_USERNAME=rollchains diff --git a/docs/versioned_docs/version-v0.50.x/03-demos/02-cw-nft-demo.md b/docs/versioned_docs/version-v0.50.x/03-demos/02-cw-nft-demo.md index 9549a7bf..d34d4950 100644 --- a/docs/versioned_docs/version-v0.50.x/03-demos/02-cw-nft-demo.md +++ b/docs/versioned_docs/version-v0.50.x/03-demos/02-cw-nft-demo.md @@ -137,7 +137,7 @@ pagination: ## Create a new NFT collection -With the source now uploaded, anyone can create a new NFT collection with this base contract code now on the chain. This will be a new contract that only we control. Now, instantiate the contract to create the new NFT collection. +With the source now uploaded, anyone can create a new NFT collection with this base contract code now on the chain. This will be a new contract that only you control. Now, instantiate the contract to create the new NFT collection.
@@ -174,10 +174,10 @@ rolld tx wasm instantiate 1 $MESSAGE --no-admin --from=acc0 --label="my-nft" \ A contract address is where all the collection and information is stored. It never changes and is the unique identifier for interaction. Think of this similar to a website, google.com always brings you to google search. `NFT_CONTRACT` is always the RollNFTs collection. ```bash -# View all contract addresses we have created +# View all contract addresses a wallet has created rolld q wasm list-contracts-by-creator roll1hj5fveer5cjtn4wd6wstzugjfdxzl0xpg2te87 -# The contract address for the NFT collection we just created +# The contract address for the NFT collection just created NFT_CONTRACT=roll14hj2tavq8fpesdwxxcu44rty3hh90vhujrvcmstl4zr3txmfvw9sjczpjh ``` diff --git a/docs/versioned_docs/version-v0.50.x/03-demos/03-tokenfactory.md b/docs/versioned_docs/version-v0.50.x/03-demos/03-tokenfactory.md index fc853c68..8421d192 100644 --- a/docs/versioned_docs/version-v0.50.x/03-demos/03-tokenfactory.md +++ b/docs/versioned_docs/version-v0.50.x/03-demos/03-tokenfactory.md @@ -103,7 +103,7 @@ The output shows a denom with the named `factory/roll1hj5fveer5cjtn4wd6wstzugjfd :::note Note Why did it add extra data to the token? -Imagine we have 2 people, both named John. If we only use the name John, how do we know which John we are talking about? We need to add more information to the name to make it unique. This is the same concept, but with tokens. The extra data is added to ensure the token is unique while we can still contain the same base name. With tokenfactory, we place the creators name in the token. Read more about [naming collisions](https://en.wikipedia.org/wiki/Naming_collision). +Imagine there are 2 people, both named John. If only the name John is used, which John is it talking about? More information must be added to the name to make it unique. This is the same concept, but with tokens. The extra data is added to ensure the token is unique while it can still contain the same base name. With tokenfactory, the creators name is placed in the token. Read more about [naming collisions](https://en.wikipedia.org/wiki/Naming_collision). ::: @@ -149,7 +149,7 @@ metadata: ## Create new tokens to transfer -The base token structure is created, but no tokens actually exists yet. We must mint new tokens to then be able to transfer them between accounts. +The base token structure is created, but no tokens actually exists yet. Mint new tokens to then be able to transfer them between accounts. ```bash # Mint 5,000,000 micro mytoken. By default this goes to the token creator. diff --git a/docs/versioned_docs/version-v0.50.x/04-learn-spawn/01-consensus-algos.md b/docs/versioned_docs/version-v0.50.x/04-learn-spawn/01-consensus-algos.md index be4a7535..24a59417 100644 --- a/docs/versioned_docs/version-v0.50.x/04-learn-spawn/01-consensus-algos.md +++ b/docs/versioned_docs/version-v0.50.x/04-learn-spawn/01-consensus-algos.md @@ -112,7 +112,7 @@ The cost of running these networks is relatively low as you just pay a portion o To create a new network with interchain-security, use the `--consensus=interchain-security` flag. If `--consensus` is not present, a selector UI will appear in your terminal to see all options. ::note Note -We do not support creating provider networks. +Spawn does not support creating provider networks. ::: ```bash From 06340de6d92bb8732091d946f4cf71e168007993 Mon Sep 17 00:00:00 2001 From: Reece Williams Date: Sun, 29 Sep 2024 22:16:26 -0500 Subject: [PATCH 09/11] docs: what spawn does structure, modules, and testnet --- .../04-learn-spawn/00-what-spawn-does.md | 162 +++++++++++++++--- 1 file changed, 137 insertions(+), 25 deletions(-) diff --git a/docs/versioned_docs/version-v0.50.x/04-learn-spawn/00-what-spawn-does.md b/docs/versioned_docs/version-v0.50.x/04-learn-spawn/00-what-spawn-does.md index 9a960422..88743285 100644 --- a/docs/versioned_docs/version-v0.50.x/04-learn-spawn/00-what-spawn-does.md +++ b/docs/versioned_docs/version-v0.50.x/04-learn-spawn/00-what-spawn-does.md @@ -7,26 +7,20 @@ slug: /learn/what-spawn-does # What Spawn Does -Learn about what spawn does, how it works, and how it can help you build your applications faster than ever before +Spawn is a powerful tool designed to streamline the process of building, maintaining, and scaling your blockchain application. ## Overview -Spawn is a powerful tool designed to streamline the process of building, maintaining, and scaling Cosmos SDK blockchains. As a developer, Spawn offers several compelling reasons to incorporate it into your workflow. - -Before, you would have at least a week setting up a new chain. You would manually copy paste some other codebase, modify it to your needs, debug issues, add custom test, fix github actions, and then you have a base network. Now you can do all this in just a flew clicks. Spawn takes in your context and with magic, generates a new network for you fitting your needs. +Setting up a new blockchain used to take at least a week, requiring manual edits, debugging, and configuring tests. Now, with Spawn, you can create a custom network in just a few clicks. It generates a personalized network tailored to your project, letting you focus on writing product logic. The modular approach allows you to include or remove features, so you can start building quickly without the hassle of setting up everything from scratch. Spawn simplifies the process, especially for new developers, by removing guesswork and speeding up the setup. ## New Development -Say you have a project idea, and you want to get started on writing the logic. Spawn gets you from 0 to 1 with the template matching your exact needs. The modular approach allows you to pick what you just have, such as smart contracts, and remove the things you don't. This way, you can focus on what matters to you. - -Get started building your first chain using the `new-chain` command. Spawn will guide you through the process of selecting the modules you need and configuring your new chain. +Get started building using the `new-chain` command. Spawn will guide you through the process of selecting the modules you need and configuring your new chain. Using `--help` will showcase examples and other options you may want to consider for your new network. ```bash spawn new mychain --help ``` -Using `--help` will showcase examples and other options you may want to consider for your new network. - ```bash Create a new project @@ -37,25 +31,23 @@ Aliases: new-chain, new, init, create Flags: - -b, --binary string binary name (default "simd") - --bypass-prompt bypass UI prompt - --debug enable debugging - --denom string bank token denomination (default "token") - -h, --help help for new-chain - --org string github organization (default "rollchains") - --skip-git ignore git init - --wallet-prefix string chain bech32 wallet prefix (default "cosmos") + -b, --binary string Application binary name (default "simd") + --bypass-prompt Bypass UI prompter + --denom string Bank token denomination (default "token") + --org string Github organization name (default "rollchains") + --skip-git No git repository created + --wallet-prefix string Users wallet namespace (default "cosmos") ``` ### Security Selection -You can read about different security models in the [Consensus Security](./01-consensus-algos.md) section. If you don't know which to select, use proof of authority for your application. +You can read about different security models in the [Consensus Security](./01-consensus-algos.md) section. If you don't know which to select, use proof of authority. ```bash spawn new mychain ``` -After running the new command, use your arrow keys and use 'enter' to select the module you want to use. You can only use 1 from this list. Then select done. +After running the new command, navigate with your arrow keys and press 'enter' to select the module you want to use. You can only use 1 from this consensus list. Then select done. ``` Consensus Selector (( enter to toggle )) @@ -67,9 +59,9 @@ Consensus Selector (( enter to toggle )) ### Feature Selection -You now select which features you want to include in your base application. Usually you would have to do these manually, each taking about 15 minutes to add. With spawn, we let you select them right away, automatically configure them, **and** give you testing to give you the assurance it works. +You now select which features you want to include in your base application. Usually you would have to do these manually, each taking about 15 minutes to integrate. With spawn, you select them right away. It automatically configures them **and** give you testing for the assurance it works. -As you scroll through features, +An information guide will be displayed for each feature at the bottom of the UI, sharing information about what the feature does. Select the following then press 'enter' on done to continue. ```bash Feature Selector (( enter to toggle )) @@ -85,12 +77,132 @@ Feature Selector (( enter to toggle )) tokenfactory: Native token minting, sending, and burning on the chain ``` +Just like that, an entire network is generated. Everything you need to get started and more! Let's dive in. + +## Structure + +Opening up this newly generated `mychain/` gives you a general view into the entire layout. + +```bash title="ls -laG" +.github/ +app/ +chains/ +cmd/ +contrib/ +explorer/ +interchaintest/ +proto/ +scripts/ + +.gitignore +.goreleaser.yaml +chain_metadata.json +chain_registry_assets.json +chain_registry.json +chains.yaml +docker-compose.yml +Dockerfile +go.mod +go.sum +Makefile +README.md +``` +### .github/ ---- +This directory contains all the workflow actions for native github integration out of the box. It handles +- Integration & Unit tests for every code change +- Docker images saved to [ghcr](https://github.com/features/packages) on a new version tag +- Public cloud or private hosted testnets +- App binary releases +- PR title formatting +- Markdown file valid link reviews + +### app/ + +App is the main location for all of the application connection logic. + +- **decorators/** - Initial logic as new transactions are received. Used to override input data, block requests, or add additional logic before the action begins initial processing. +- **upgrades/** - You have to run an upgrade when you add or remove logic and nodes are already running different logic. This is where you put the upgrade information and state migrations. +- **ante.go** - The decorators for the entire network, wired together. +- **app.go** - The entire application connected and given access to the cosmos-sdk. The brain of the program. +- **upgrades.go** - Registers the upgrades/ folder logic when one is pending processing. + +### chains/ + +The chains/ directory is where the local and public testnet configuration files are placed. Reference the [testnets](#testnets) section for more information + +### cmd/ + +The cmd/ directory is the entry point for the wiring connections and is where the main.go file is located. This is where the application is started and the chain is initialized when you run the binary. By default, `simd` is the binary name and is saved to your $GOPATH (/home/user/go/bin/). + +### explorer/ + +If you enabled the explorer in the feature selection, this is where the [ping.pub](https://ping.pub/) explorer files are located. When running a testnet with `make sh-testnet` or `make testnet`, you can launch the explorer along side the chain to view activity in real time. Blocks, transactions, uptime, connections, and more are all viewable. Easily launch it with the `docker compose up` command in the root of the directory. + +### interchaintest/ + +Interchaintest is a generalized integration test environment for the Interchain and beyond. It supports Cosmos, Ethereum, UTXO (Bitcoin), and other chain types. By default you will see many test like `ibc_test.go`, `ibc_rate_limit_test.go` and `tokenfactory_test.go` after generation. Any features you select are placed here automatically to confirm your network is working as expected. This are run with the github action automatically on every code change **or** you can run them manually with `make local-image && make ictest-*`, where the * is the testname *(ictest-ibc, ictest-tokenfactory, etc)*. + +### proto/ + +[Proto, also called protocol buffers](https://protobuf.dev/), are a generalized way to define the structure of data. Discussed this more in the [Modules](#modules) sub section. + +### scripts/ + +Scripts automate some more complex requirements list setting up a fast testnet or generating code on the fly. You should not need to modify anything here until you are more advanced. These are shown in the `make help` command to abstract away complexity. + +### chain_metadata.json + +A cosmetic file showcasing a format for the network. Fill in the data here once you push to the public so developers can easily see what your network is about. This is required for [ICS consumer networks](./01-consensus-algos.md#create-an-ics-consumer-network). If you do not use ICS, you can delete this file if you wish. + +### chain_registry.json & assets + +These files are the format needed to upload to [https://cosmos.directory/](https://cosmos.directory/) ([github](https://github.com/cosmos/chain-registry)). Frontends use this data to connect to the network, especially in the [local-interchain testnet tool](#testnets). + +## Modules + +We're all here to build new logic on top. The SDK calls these modules, or e**x**tensions, x/ for short. To make this easy spawn has a build in generator for a module. + +```bash +spawn module new --help +``` + +```bash +Usage: + spawn module new [name] [flags] + +Aliases: + new, c, create + +Examples: + spawn module new mymodule [--ibc-module] + +Flags: + --ibc-middleware Set the module as an IBC Middleware + --ibc-module Set the module as an IBC Module +``` + +All you need to have is the name you wish to call it, and if you want standard or an IBC module. IBC enables cross network communication of the logic. This is a powerful feature that allows you to build a network of networks. You can try this out with the [IBC module demo](../02-build-your-application/08-ibc-module.md) demo. + +For now, just create a default module called `example` + +```bash +spawn module new example +``` + +``` +🎉 New Module 'example' generated! +🏅 Commands: + - $ make proto-gen # convert proto files into code +``` + +This created a new x/example module and the [proto/](#proto) files in the expected structure. `genesis.proto` contains the data saved and more hardcoded. `query.proto` is how you allow external actors to grab data from the network and `tx.proto` is how you allow external actors to send data to the network. Spawn also connects it to the application if you look through your `app/app.go`. + +Learn how to make a new module with the [Name Service](../02-build-your-application/01-nameservice.md) guide. -# Testing +## Testnets -# Modules +This uses the [local-interchain](https://github.com/strangelove-ventures/interchaintest/tree/main/local-interchain) format and supports JSON or YAML. By default, 2 IBC network defaults are included. **self-ibc** and **testnet**. Run the testnet with `make testnet` to automatically build, setup, and launch a complex network simply. -# testnets +Self IBC is really only useful if you are building [IBC Modules](../02-build-your-application/08-ibc-module.md). Follow that guide to see how to use it. From 9ce91ac12a44abdb0a15c71320206b46f1829416 Mon Sep 17 00:00:00 2001 From: Reece Williams Date: Mon, 30 Sep 2024 11:58:10 -0500 Subject: [PATCH 10/11] small nit --- .../versioned_docs/version-v0.50.x/03-demos/02-cw-nft-demo.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/versioned_docs/version-v0.50.x/03-demos/02-cw-nft-demo.md b/docs/versioned_docs/version-v0.50.x/03-demos/02-cw-nft-demo.md index d34d4950..5c4c9252 100644 --- a/docs/versioned_docs/version-v0.50.x/03-demos/02-cw-nft-demo.md +++ b/docs/versioned_docs/version-v0.50.x/03-demos/02-cw-nft-demo.md @@ -20,7 +20,9 @@ Some parts of this tutorial will not have the added context about spawn's inner - [Install Spawn](../01-setup/02-install-spawn.md) :::note Danger -Some machines like Windows and ARM64 (MacOS) will not work with running the testnet. This is a limitation of the operating system hardware with wasm and required C language libraries / DLLs. For the best experience, use a Linux machine or a cloud-based linux instance from [Hetzner](https://www.hetzner.com/cloud/) or [Digital Ocean](https://www.digitalocean.com/pricing/droplets) for $6 per month. +Some machines like Windows will not work with running the testnet. This is a limitation of the operating system hardware with wasm and required C language libraries / DLLs. + +For the best experience, try `make testnet` or use a Linux machine or a cloud-based linux instance from [Hetzner](https://www.hetzner.com/cloud/) or [Digital Ocean](https://www.digitalocean.com/pricing/droplets) for $6 per month. ::: From 3cbb7355305ae6f8a55a5cdb768eaec32af5af66 Mon Sep 17 00:00:00 2001 From: Reece Williams Date: Mon, 30 Sep 2024 12:07:14 -0500 Subject: [PATCH 11/11] move meet spawn to core docs --- .../version-v0.50.x/00-meet-spawn.md | 201 ++++++++++++++++- .../04-learn-spawn/00-what-spawn-does.md | 208 ------------------ .../04-learn-spawn/_category_.json | 2 +- 3 files changed, 201 insertions(+), 210 deletions(-) delete mode 100644 docs/versioned_docs/version-v0.50.x/04-learn-spawn/00-what-spawn-does.md diff --git a/docs/versioned_docs/version-v0.50.x/00-meet-spawn.md b/docs/versioned_docs/version-v0.50.x/00-meet-spawn.md index 8f02ccec..b4b5920e 100644 --- a/docs/versioned_docs/version-v0.50.x/00-meet-spawn.md +++ b/docs/versioned_docs/version-v0.50.x/00-meet-spawn.md @@ -13,7 +13,7 @@ Spawn is the easiest way to build, maintain and scale a Cosmos SDK blockchain. S ## NameService Demo -[Follow Along with the NameService demo](../version-v0.50.x/02-build-your-application/01-nameservice.md) +[Follow Along with the NameService demo](./02-build-your-application/01-nameservice.md) @@ -25,3 +25,202 @@ Spawn is the easiest way to build, maintain and scale a Cosmos SDK blockchain. S > "Spawn has truly streamlined the developer onboarding process into the Cosmos ecosystem, seamless and efficient." - [Anil](https://x.com/anilcse_/status/1840444855576846355) [VitWit](https://www.vitwit.com/) +--- + +## Spawn Overview + +Setting up a new blockchain used to take at least a week, requiring manual edits, debugging, and configuring tests. Now, with Spawn, you can create a custom network in just a few clicks. It generates a personalized network tailored to your project, letting you focus on writing product logic. The modular approach allows you to include or remove features, so you can start building quickly without the hassle of setting up everything from scratch. Spawn simplifies the process, especially for new developers, by removing guesswork and speeding up the setup. + +## New Development + +Get started building using the `new-chain` command. Spawn will guide you through the process of selecting the modules you need and configuring your new chain. Using `--help` will showcase examples and other options you may want to consider for your new network. + +```bash +spawn new mychain --help +``` + +```bash +Create a new project + +Usage: + spawn new-chain [project-name] [flags] + +Aliases: + new-chain, new, init, create + +Flags: + -b, --binary string Application binary name (default "simd") + --bypass-prompt Bypass UI prompter + --denom string Bank token denomination (default "token") + --org string Github organization name (default "rollchains") + --skip-git No git repository created + --wallet-prefix string Users wallet namespace (default "cosmos") +``` + +### Security Selection + +You can read about different security models in the [Consensus Security](./04-learn-spawn/01-consensus-algos.md) section. If you don't know which to select, use proof of authority. + +```bash +spawn new mychain +``` + +After running the new command, navigate with your arrow keys and press 'enter' to select the module you want to use. You can only use 1 from this consensus list. Then select done. + +``` +Consensus Selector (( enter to toggle )) + Done + ✔ proof-of-authority + proof-of-stake + interchain-security +``` + +### Feature Selection + +You now select which features you want to include in your base application. Usually you would have to do these manually, each taking about 15 minutes to integrate. With spawn, you select them right away. It automatically configures them **and** give you testing for the assurance it works. + +An information guide will be displayed for each feature at the bottom of the UI, sharing information about what the feature does. Select the following then press 'enter' on done to continue. + +```bash +Feature Selector (( enter to toggle )) + Done + ✔ tokenfactory + ✔ ibc-packetforward + ✔ ibc-ratelimit + cosmwasm + wasm-light-client + ✔ optimistic-execution + ignite-cli + ✔ block-explorer +tokenfactory: Native token minting, sending, and burning on the chain +``` + +Just like that, an entire network is generated. Everything you need to get started and more! Let's dive in. + +## Structure + +Opening up this newly generated `mychain/` gives you a general view into the entire layout. + +```bash title="ls -laG" +.github/ +app/ +chains/ +cmd/ +contrib/ +explorer/ +interchaintest/ +proto/ +scripts/ + +.gitignore +.goreleaser.yaml +chain_metadata.json +chain_registry_assets.json +chain_registry.json +chains.yaml +docker-compose.yml +Dockerfile +go.mod +go.sum +Makefile +README.md +``` + +### .github/ + +This directory contains all the workflow actions for native github integration out of the box. It handles +- Integration & Unit tests for every code change +- Docker images saved to [ghcr](https://github.com/features/packages) on a new version tag +- Public cloud or private hosted testnets +- App binary releases +- PR title formatting +- Markdown file valid link reviews + +### app/ + +App is the main location for all of the application connection logic. + +- **decorators/** - Initial logic as new transactions are received. Used to override input data, block requests, or add additional logic before the action begins initial processing. +- **upgrades/** - You have to run an upgrade when you add or remove logic and nodes are already running different logic. This is where you put the upgrade information and state migrations. +- **ante.go** - The decorators for the entire network, wired together. +- **app.go** - The entire application connected and given access to the cosmos-sdk. The brain of the program. +- **upgrades.go** - Registers the upgrades/ folder logic when one is pending processing. + +### chains/ + +The chains/ directory is where the local and public testnet configuration files are placed. Reference the [testnets](#testnets) section for more information + +### cmd/ + +The cmd/ directory is the entry point for the wiring connections and is where the main.go file is located. This is where the application is started and the chain is initialized when you run the binary. By default, `simd` is the binary name and is saved to your $GOPATH (/home/user/go/bin/). + +### explorer/ + +If you enabled the explorer in the feature selection, this is where the [ping.pub](https://ping.pub/) explorer files are located. When running a testnet with `make sh-testnet` or `make testnet`, you can launch the explorer along side the chain to view activity in real time. Blocks, transactions, uptime, connections, and more are all viewable. Easily launch it with the `docker compose up` command in the root of the directory. + +### interchaintest/ + +Interchaintest is a generalized integration test environment for the Interchain and beyond. It supports Cosmos, Ethereum, UTXO (Bitcoin), and other chain types. By default you will see many test like `ibc_test.go`, `ibc_rate_limit_test.go` and `tokenfactory_test.go` after generation. Any features you select are placed here automatically to confirm your network is working as expected. This are run with the github action automatically on every code change **or** you can run them manually with `make local-image && make ictest-*`, where the * is the testname *(ictest-ibc, ictest-tokenfactory, etc)*. + +### proto/ + +[Proto, also called protocol buffers](https://protobuf.dev/), are a generalized way to define the structure of data. Discussed this more in the [Modules](#modules) sub section. + +### scripts/ + +Scripts automate some more complex requirements list setting up a fast testnet or generating code on the fly. You should not need to modify anything here until you are more advanced. These are shown in the `make help` command to abstract away complexity. + +### chain_metadata.json + +A cosmetic file showcasing a format for the network. Fill in the data here once you push to the public so developers can easily see what your network is about. This is required for [ICS consumer networks](./04-learn-spawn/01-consensus-algos.md#create-an-ics-consumer-network). If you do not use ICS, you can delete this file if you wish. + +### chain_registry.json & assets + +These files are the format needed to upload to [https://cosmos.directory/](https://cosmos.directory/) ([github](https://github.com/cosmos/chain-registry)). Frontends use this data to connect to the network, especially in the [local-interchain testnet tool](#testnets). + +## Modules + +We're all here to build new logic on top. The SDK calls these modules, or e**x**tensions, x/ for short. To make this easy spawn has a build in generator for a module. + +```bash +spawn module new --help +``` + +```bash +Usage: + spawn module new [name] [flags] + +Aliases: + new, c, create + +Examples: + spawn module new mymodule [--ibc-module] + +Flags: + --ibc-middleware Set the module as an IBC Middleware + --ibc-module Set the module as an IBC Module +``` + +All you need to have is the name you wish to call it, and if you want standard or an IBC module. IBC enables cross network communication of the logic. This is a powerful feature that allows you to build a network of networks. You can try this out with the [IBC module demo](./02-build-your-application/08-ibc-module.md) demo. + +For now, just create a default module called `example` + +```bash +spawn module new example +``` + +``` +🎉 New Module 'example' generated! +🏅 Commands: + - $ make proto-gen # convert proto files into code +``` + +This created a new x/example module and the [proto/](#proto) files in the expected structure. `genesis.proto` contains the data saved and more hardcoded. `query.proto` is how you allow external actors to grab data from the network and `tx.proto` is how you allow external actors to send data to the network. Spawn also connects it to the application if you look through your `app/app.go`. + +Learn how to make a new module with the [Name Service](./02-build-your-application/01-nameservice.md) guide. + +## Testnets + +This uses the [local-interchain](https://github.com/strangelove-ventures/interchaintest/tree/main/local-interchain) format and supports JSON or YAML. By default, 2 IBC network defaults are included. **self-ibc** and **testnet**. Run the testnet with `make testnet` to automatically build, setup, and launch a complex network simply. + +Self IBC is really only useful if you are building [IBC Modules](./02-build-your-application/08-ibc-module.md). Follow that guide to see how to use it. diff --git a/docs/versioned_docs/version-v0.50.x/04-learn-spawn/00-what-spawn-does.md b/docs/versioned_docs/version-v0.50.x/04-learn-spawn/00-what-spawn-does.md deleted file mode 100644 index 88743285..00000000 --- a/docs/versioned_docs/version-v0.50.x/04-learn-spawn/00-what-spawn-does.md +++ /dev/null @@ -1,208 +0,0 @@ ---- -title: "Spawns Purpose" -sidebar_label: "What Spawn Does" -slug: /learn/what-spawn-does -# sidebar_position: 1 ---- - -# What Spawn Does - -Spawn is a powerful tool designed to streamline the process of building, maintaining, and scaling your blockchain application. - -## Overview - -Setting up a new blockchain used to take at least a week, requiring manual edits, debugging, and configuring tests. Now, with Spawn, you can create a custom network in just a few clicks. It generates a personalized network tailored to your project, letting you focus on writing product logic. The modular approach allows you to include or remove features, so you can start building quickly without the hassle of setting up everything from scratch. Spawn simplifies the process, especially for new developers, by removing guesswork and speeding up the setup. - -## New Development - -Get started building using the `new-chain` command. Spawn will guide you through the process of selecting the modules you need and configuring your new chain. Using `--help` will showcase examples and other options you may want to consider for your new network. - -```bash -spawn new mychain --help -``` - -```bash -Create a new project - -Usage: - spawn new-chain [project-name] [flags] - -Aliases: - new-chain, new, init, create - -Flags: - -b, --binary string Application binary name (default "simd") - --bypass-prompt Bypass UI prompter - --denom string Bank token denomination (default "token") - --org string Github organization name (default "rollchains") - --skip-git No git repository created - --wallet-prefix string Users wallet namespace (default "cosmos") -``` - -### Security Selection - -You can read about different security models in the [Consensus Security](./01-consensus-algos.md) section. If you don't know which to select, use proof of authority. - -```bash -spawn new mychain -``` - -After running the new command, navigate with your arrow keys and press 'enter' to select the module you want to use. You can only use 1 from this consensus list. Then select done. - -``` -Consensus Selector (( enter to toggle )) - Done - ✔ proof-of-authority - proof-of-stake - interchain-security -``` - -### Feature Selection - -You now select which features you want to include in your base application. Usually you would have to do these manually, each taking about 15 minutes to integrate. With spawn, you select them right away. It automatically configures them **and** give you testing for the assurance it works. - -An information guide will be displayed for each feature at the bottom of the UI, sharing information about what the feature does. Select the following then press 'enter' on done to continue. - -```bash -Feature Selector (( enter to toggle )) - Done - ✔ tokenfactory - ✔ ibc-packetforward - ✔ ibc-ratelimit - cosmwasm - wasm-light-client - ✔ optimistic-execution - ignite-cli - ✔ block-explorer -tokenfactory: Native token minting, sending, and burning on the chain -``` - -Just like that, an entire network is generated. Everything you need to get started and more! Let's dive in. - -## Structure - -Opening up this newly generated `mychain/` gives you a general view into the entire layout. - -```bash title="ls -laG" -.github/ -app/ -chains/ -cmd/ -contrib/ -explorer/ -interchaintest/ -proto/ -scripts/ - -.gitignore -.goreleaser.yaml -chain_metadata.json -chain_registry_assets.json -chain_registry.json -chains.yaml -docker-compose.yml -Dockerfile -go.mod -go.sum -Makefile -README.md -``` - -### .github/ - -This directory contains all the workflow actions for native github integration out of the box. It handles -- Integration & Unit tests for every code change -- Docker images saved to [ghcr](https://github.com/features/packages) on a new version tag -- Public cloud or private hosted testnets -- App binary releases -- PR title formatting -- Markdown file valid link reviews - -### app/ - -App is the main location for all of the application connection logic. - -- **decorators/** - Initial logic as new transactions are received. Used to override input data, block requests, or add additional logic before the action begins initial processing. -- **upgrades/** - You have to run an upgrade when you add or remove logic and nodes are already running different logic. This is where you put the upgrade information and state migrations. -- **ante.go** - The decorators for the entire network, wired together. -- **app.go** - The entire application connected and given access to the cosmos-sdk. The brain of the program. -- **upgrades.go** - Registers the upgrades/ folder logic when one is pending processing. - -### chains/ - -The chains/ directory is where the local and public testnet configuration files are placed. Reference the [testnets](#testnets) section for more information - -### cmd/ - -The cmd/ directory is the entry point for the wiring connections and is where the main.go file is located. This is where the application is started and the chain is initialized when you run the binary. By default, `simd` is the binary name and is saved to your $GOPATH (/home/user/go/bin/). - -### explorer/ - -If you enabled the explorer in the feature selection, this is where the [ping.pub](https://ping.pub/) explorer files are located. When running a testnet with `make sh-testnet` or `make testnet`, you can launch the explorer along side the chain to view activity in real time. Blocks, transactions, uptime, connections, and more are all viewable. Easily launch it with the `docker compose up` command in the root of the directory. - -### interchaintest/ - -Interchaintest is a generalized integration test environment for the Interchain and beyond. It supports Cosmos, Ethereum, UTXO (Bitcoin), and other chain types. By default you will see many test like `ibc_test.go`, `ibc_rate_limit_test.go` and `tokenfactory_test.go` after generation. Any features you select are placed here automatically to confirm your network is working as expected. This are run with the github action automatically on every code change **or** you can run them manually with `make local-image && make ictest-*`, where the * is the testname *(ictest-ibc, ictest-tokenfactory, etc)*. - -### proto/ - -[Proto, also called protocol buffers](https://protobuf.dev/), are a generalized way to define the structure of data. Discussed this more in the [Modules](#modules) sub section. - -### scripts/ - -Scripts automate some more complex requirements list setting up a fast testnet or generating code on the fly. You should not need to modify anything here until you are more advanced. These are shown in the `make help` command to abstract away complexity. - -### chain_metadata.json - -A cosmetic file showcasing a format for the network. Fill in the data here once you push to the public so developers can easily see what your network is about. This is required for [ICS consumer networks](./01-consensus-algos.md#create-an-ics-consumer-network). If you do not use ICS, you can delete this file if you wish. - -### chain_registry.json & assets - -These files are the format needed to upload to [https://cosmos.directory/](https://cosmos.directory/) ([github](https://github.com/cosmos/chain-registry)). Frontends use this data to connect to the network, especially in the [local-interchain testnet tool](#testnets). - -## Modules - -We're all here to build new logic on top. The SDK calls these modules, or e**x**tensions, x/ for short. To make this easy spawn has a build in generator for a module. - -```bash -spawn module new --help -``` - -```bash -Usage: - spawn module new [name] [flags] - -Aliases: - new, c, create - -Examples: - spawn module new mymodule [--ibc-module] - -Flags: - --ibc-middleware Set the module as an IBC Middleware - --ibc-module Set the module as an IBC Module -``` - -All you need to have is the name you wish to call it, and if you want standard or an IBC module. IBC enables cross network communication of the logic. This is a powerful feature that allows you to build a network of networks. You can try this out with the [IBC module demo](../02-build-your-application/08-ibc-module.md) demo. - -For now, just create a default module called `example` - -```bash -spawn module new example -``` - -``` -🎉 New Module 'example' generated! -🏅 Commands: - - $ make proto-gen # convert proto files into code -``` - -This created a new x/example module and the [proto/](#proto) files in the expected structure. `genesis.proto` contains the data saved and more hardcoded. `query.proto` is how you allow external actors to grab data from the network and `tx.proto` is how you allow external actors to send data to the network. Spawn also connects it to the application if you look through your `app/app.go`. - -Learn how to make a new module with the [Name Service](../02-build-your-application/01-nameservice.md) guide. - -## Testnets - -This uses the [local-interchain](https://github.com/strangelove-ventures/interchaintest/tree/main/local-interchain) format and supports JSON or YAML. By default, 2 IBC network defaults are included. **self-ibc** and **testnet**. Run the testnet with `make testnet` to automatically build, setup, and launch a complex network simply. - -Self IBC is really only useful if you are building [IBC Modules](../02-build-your-application/08-ibc-module.md). Follow that guide to see how to use it. diff --git a/docs/versioned_docs/version-v0.50.x/04-learn-spawn/_category_.json b/docs/versioned_docs/version-v0.50.x/04-learn-spawn/_category_.json index 3dff53c2..47bd16d0 100644 --- a/docs/versioned_docs/version-v0.50.x/04-learn-spawn/_category_.json +++ b/docs/versioned_docs/version-v0.50.x/04-learn-spawn/_category_.json @@ -1,5 +1,5 @@ { - "label": "Learn Spawn", + "label": "Learn", "position": 4, "link": null }