diff --git a/.vitepress/config.ts b/.vitepress/config.ts index d463d06f4..389a8c0c6 100644 --- a/.vitepress/config.ts +++ b/.vitepress/config.ts @@ -329,23 +329,8 @@ function sidebarHome() { link: "/guides/metrics", }, { - text: "Integrations", - collapsed: true, - items: [ - { - text: "Test and deploy cosmwasm smart-contracts", - link: "/guides/cw-orch", - }, - { text: "Add zkML to your EVM rollup", link: "/guides/zkml" }, - { - text: "Add an IBC connection to your rollup", - link: "/guides/ibc-connection", - }, - { - text: "Use IBC token (TIA) as gas token in your rollup", - link: "/guides/use-tia-for-gas", - }, - ], + text: "Use IBC token (TIA) as gas token in your rollup", + link: "/guides/use-tia-for-gas", }, ], }, diff --git a/guides/cw-orch.md b/guides/cw-orch.md deleted file mode 100644 index 896a967ba..000000000 --- a/guides/cw-orch.md +++ /dev/null @@ -1,251 +0,0 @@ - -# Speed up your development with cw-orchestrator - -## Introduction - -cw-orchestrator is the most advanced scripting, testing, and deployment framework for CosmWasm smart-contracts. It makes it easy to write cross-environment compatible code for [cw-multi-test](https://github.com/CosmWasm/cw-multi-test), [Test Tube](https://github.com/osmosis-labs/test-tube), [Starship](https://github.com/cosmology-tech/starship) (alpha), and live networks, significantly reducing code duplication and test-writing time. - -Get ready to change the way you interact with contracts and simplify you smart-contracts journey. The following steps will allow you to integrate `cw-orch` and write clean code such as: - -```rust -counter.upload()?; -counter.instantiate(&InstantiateMsg { count: 0 }, None, None)?; -counter.increment()?; -let count = counter.get_count()?; -assert_eq!(count.count, 1); -``` - -In this quick-start guide, we will review the necessary steps in order to integrate [`cw-orch`](https://github.com/AbstractSDK/cw-orchestrator) into a simple contract crate. [We review integration of rust-workspaces (multiple contracts) at the end of this page](#integration-in-a-workspace). - -> **NOTE**: *Quicker than the quick start* -> ->If you're moving quicker than everybody else, we suggest looking at a before-after review of this example integration. This will help you catch the additions you need to make to your contract to be able to interact with it using cw-orchestrator. - -> **NOTE**: If you want to go more in depth, [browse the full `cw-orch` documentation](https://orchestrator.abstract.money/). - -## Summary - -- [Speed up your development with cw-orchestrator](#speed-up-your-development-with-cw-orchestrator) - - [Introduction](#introduction) - - [Summary](#summary) - - [Single Contract Integration](#single-contract-integration) - - [Adding `cw-orch` to your `Cargo.toml` file](#adding-cw-orch-to-your-cargotoml-file) - - [Creating an Interface](#creating-an-interface) - - [Interaction helpers](#interaction-helpers) - - [Using the integration](#using-the-integration) - - [Integration in a workspace](#integration-in-a-workspace) - - [Handling dependencies and features](#handling-dependencies-and-features) - - [Creating an interface crate](#creating-an-interface-crate) - - [Integrating single contracts](#integrating-single-contracts) - - [More examples and scripts](#more-examples-and-scripts) - -## Single Contract Integration - -Throughout this example, we will be using `cw-orch` to interact with a simple counter contract. All the steps below apply to any smart contract, no matter the complexity. - -### Adding `cw-orch` to your `Cargo.toml` file - -To use cw-orchestrator, you need to add `cw-orch` to your contract's TOML file. Run the command below in your contract's directory: - -```shell -cargo add cw-orch -``` - -Alternatively, you can add it manually in your `Cargo.toml` file as shown below: - -```toml -[dependencies] -cw-orch = {version = "0.21.2" } # Latest version at time of writing -``` - -### Creating an Interface -When using a single contract, we advise creating an `interface.rs` file inside your contract's directory. You then need to add this module to your `lib.rs` file. In order for this interface code to not land in your WASM smart-contracts you need to target-flag it like so: -```rust -#[cfg(not(target_arch = "wasm32"))] -mod interface; -``` -Then, inside that `interface.rs` file, you can define the interface for your contract: - -```rust -use cw_orch::{interface, prelude::*}; -use crate::msg::{ExecuteMsg, InstantiateMsg, MigrateMsg, QueryMsg}; -pub const CONTRACT_ID: &str = "counter_contract"; -#[interface(InstantiateMsg, ExecuteMsg, QueryMsg, MigrateMsg, id = CONTRACT_ID)] -pub struct CounterContract; -impl Uploadable for CounterContract { - /// Return the path to the wasm file corresponding to the contract - fn wasm(&self) -> WasmPath { - artifacts_dir_from_workspace!() - .find_wasm_path("counter_contract") - .unwrap() - } - /// Returns a CosmWasm contract wrapper - fn wrapper(&self) -> Box> { - Box::new( - ContractWrapper::new_with_empty( - crate::contract::execute, - crate::contract::instantiate, - crate::contract::query, - ) - .with_migrate(crate::contract::migrate), - ) - } -} -``` - -Learn more about the content of the interface creation specifics in the [`cw-orch` documentation](https://orchestrator.abstract.money/contracts/interfaces.html#creating-an-interface) - -> **NOTE**: It can be useful to re-export this struct to simplify usage (in `lib.rs`): -> -> ```rust -> #[cfg(not(target_arch = "wasm32"))] -> pub use crate::interface::CounterContract; -> ``` - -### Interaction helpers - -cw-orchestrator provides a additional macros that simplify contract calls and queries. The macro implements functions on the interface for each variant of the contract's `ExecuteMsg` and `QueryMsg`. - -Enabling this functionality is very straightforward. Find your `ExecuteMsg` and `QueryMsg` definitions (in `msg.rs` in our example) and add the `ExecuteFns` and `QueryFns` derive macros to them like below: - -```rust -#[cw_serde] -#[derive(cw_orch::ExecuteFns)] // Function generation -/// Execute methods for counter -pub enum ExecuteMsg { - /// Increment count by one - Increment {}, - /// Reset count - Reset { - /// Count value after reset - count: i32, - }, -} -#[cw_serde] -#[derive(cw_orch::QueryFns)] // Function generation -#[derive(QueryResponses)] -/// Query methods for counter -pub enum QueryMsg { - /// GetCount returns the current count as a json-encoded number - #[returns(GetCountResponse)] - GetCount {}, -} -// Custom response for the query -#[cw_serde] -/// Response from get_count query -pub struct GetCountResponse { - /// Current count in the state - pub count: i32, -} -``` - -Find out more about the interaction helpers in the [`cw-orch` documentation](https://orchestrator.abstract.money/contracts/interfaces.html#entry-point-function-generation) - -> **NOTE**: Again, it can be useful to re-export these generated traits to simplify usage (in `lib.rs`): -> -> ```rust -> pub use crate::msg::{ExecuteMsgFns as CounterExecuteMsgFns, QueryMsgFns as CounterQueryMsgFns}; -> ``` - -### Using the integration - -Now that all the setup is done, you can use your contract in tests, integration-tests or scripts. - -Start by importing your crate in `[dependencies]` or `[dev-dependencies]`: - -```toml -counter-contract = { path = "../counter-contract" } -``` - -You can now use: - -```rust -use counter_contract::{ - msg::InstantiateMsg, CounterContract, CounterExecuteMsgFns, CounterQueryMsgFns, -}; -use cw_orch::{anyhow, prelude::*, tokio}; -use tokio::runtime::Runtime; -const LOCAL_MNEMONIC: &str = "clip hire initial neck maid actor venue client foam budget lock catalog sweet steak waste crater broccoli pipe steak sister coyote moment obvious choose"; -pub fn main() -> anyhow::Result<()> { - std::env::set_var("LOCAL_MNEMONIC", LOCAL_MNEMONIC); - dotenv::dotenv().ok(); // Used to load the `.env` file if any - pretty_env_logger::init(); // Used to log contract and chain interactions - let rt = Runtime::new()?; - let network = networks::LOCAL_JUNO; - let chain = DaemonBuilder::default() - .handle(rt.handle()) - .chain(network) - .build()?; - let counter = CounterContract::new(chain); - counter.upload()?; - counter.instantiate(&InstantiateMsg { count: 0 }, None, None)?; - counter.increment()?; - let count = counter.get_count()?; - assert_eq!(count.count, 1); - Ok(()) -} -``` - -## Integration in a workspace - -In this paragraph, we will use the `cw-plus` repository as an example. You can review: - -- The full integration code with `cw-orch` added -- The complete diff that shows you all integration spots (if you want to go fast) - -### Handling dependencies and features - -When using workspaces, you need to add `cw-orch` to all crates that include `ExecuteMsg` and `QueryMsg` used in your contracts and derive the `ExecuteFns` and `QueryFns` on them. - -Refer above to [Interaction helpers](#interaction-helpers) for more details on how to do that. - -For instance, for the `cw20_base` contract, you need to execute those 2 steps on the `cw20-base` contract (where the `QueryMsg` are defined) as well as on the `cw20` package (where the `ExecuteMsg` are defined). - -### Creating an interface crate - -When using a workspace, we advise you to create a new crate inside your workspace for defining your contract's interfaces. In order to do that, use: - -```shell -cargo new interface --lib -cargo add cw-orch --package interface -``` - -Add the interface package to your workspace `Cargo.toml` file - -```toml -[workspace] -members = ["packages/*", "contracts/*", "interface"] -``` - -Inside this `interface` crate, we advise to integrate all your contracts 1 by 1 in separate files. Here is the structure of the `cw-plus` integration for reference: - -```bash -interface (interface collection) -├── Cargo.toml -└── src - ├── cw1_subkeys.rs - ├── cw1_whitelist.rs - ├── cw20_base.rs - ├── cw20_ics20.rs - └── .. -``` - -When importing your crates to get the messages types, you can use the following command in the interface folder. - -```shell -cargo add cw20-base --path ../contracts/cw20-base/ -cargo add cw20 --path ../packages/cw20 -``` - -### Integrating single contracts - -Now that you workspace is setup, you can [integrate with single contracts](#single-contract-integration) using the above section - -## More examples and scripts - -You can find more example interactions on the `counter-contract` example directly in the `cw-orchestrator` repo: - -- Some examples showcase interacting with live chains. -- Some other examples show how to use the library for testing your contracts. - -> **FINAL ADVICE**: Learn more and explore our full `cw-orch` documentation !. \ No newline at end of file diff --git a/guides/ibc-connection.md b/guides/ibc-connection.md deleted file mode 100644 index 1bc832b72..000000000 --- a/guides/ibc-connection.md +++ /dev/null @@ -1,364 +0,0 @@ -# IBC connection tutorial - -In this tutorial, we'll learn how to use [an Inter-Blockchain Communication (IBC) Protocol relayer](https://github.com/cosmos/relayer) to -create an IBC connection between a [GM world](/tutorials/gm-world.md) rollup and an Osmosis local testnet. - -:::warning Disclaimer -This initial version of IBC has high trust assumptions where receiving chains -only verify the signature of the single rollup node. For use in production, it's recommended -to wait for trust-minimized IBC support which includes state proofs and conditional clients. -Learn more about how conditional clients work in [ibc-go issue 5112](https://github.com/cosmos/ibc-go/issues/5112) -and a tracking issue for state proofs in [rollkit issue 1632](https://github.com/rollkit/rollkit/issues/1632). -::: - -## 💻 Pre-requisites {#prerequisites} - -### Software requirements - -* Docker running on your machine -* Go version ≥ 1.21.0 -* Ignite version ≥ v28.2.0 - -## Run a GM rollup chain - -Before you can create an IBC connection, you need to start a -local-celestia-devnet instance in a separate terminal: - -```bash -docker run -t -i --platform linux/amd64 -p 26657:26657 -p 26658:26658 -p 26659:26659 -p 9090:9090 ghcr.io/rollkit/local-celestia-devnet:v0.13.1 -``` - -:::warning -You will need to use Ignite v28.2.0, which you can install with: - -```bash -curl https://get.ignite.com/cli@v28.3.0! | bash -``` - -::: - -Scaffold the GM chain: - -```bash -cd $HOME -ignite scaffold chain gm --address-prefix gm -``` - -Change into the `gm` directory and install Rollkit with IBC compatibility: - -```bash -cd gm -go mod edit -replace github.com/cosmos/cosmos-sdk=github.com/rollkit/cosmos-sdk@v0.50.6-rollkit-v0.13.3-no-fraud-proofs -go mod tidy -go mod download -``` - -Now download the script to run the GM chain: - -```bash -wget https://rollkit.dev/gm/init-local.sh -``` - -Run the GM rollup: - -```bash -bash init-local.sh -``` - -:::tip -[See the guidelines in GM world rollup for environment setup](/tutorials/gm-world.md). -::: - -## Run your local-osmosis-testnet - -### Install Osmosis binary - -```bash -cd $HOME -git clone https://github.com/osmosis-labs/osmosis -cd osmosis -git checkout v21.0.1 -make install -``` - -### Run local-osmosis-testnet - -You also need to start local-osmosis-testnet in a separate terminal by downloading and running this script: - -```bash -wget https://rollkit.dev/ibc/init-osmosis-local.sh -``` - -Run the script: - -```bash -bash init-osmosis-local.sh -``` - -This will start your local Osmosis testnet, we'll create IBC connection between this testnet and GM chain in the next step. -> NOTE: Here, the key's name from `init-osmosis-local.sh` is `mykey` and `osmosis-relay` but you can modify - this script to change the name of your key. - -::: tip -We're using the `--rpc.addr [ip:port]` flag to point to port 46657, which is -the custom port to avoid conflicts with other running chains. -::: - -## Funds - -The following private key has funds on your Osmosis chain: - -```bash -Keyname: osmosis-relay -Address: osmo1vvl79phavqruppr6f5zy4ypxy7znshrqm390ll -Mnemonic: "milk verify alley price trust come maple will suit hood clay exotic" -``` - -The following private key has funds on your GM rollup chain: - -```bash -Keyname: gm-relay -Address: gm1vvl79phavqruppr6f5zy4ypxy7znshrqam48qy -Mnemonic: "milk verify alley price trust come maple will suit hood clay exotic" -``` - -## Setup relayer, create IBC connection and start relaying packets - -A relayer is like a middleman for blockchains in the IBC protocol. Instead of directly talking to each other, blockchains communicate through relayers. These relayers keep an eye on the paths that are open between different blockchains. When there's something new or changed, the relayer makes sure the message gets sent to the right place on the other blockchain. - -Apart from just passing messages, a relayer can also set up new paths between blockchains. This involves creating clients, connections, and channels, which are like communication channels between the blockchains. So, in simpler terms, a relayer makes sure blockchains can talk to each other smoothly. - -### Install relayer - -```bash -cd $HOME -git clone https://github.com/cosmos/relayer -cd relayer -git checkout v2.4.2 -make install -``` - -Verify your rly version with `rly version`: - -```bash -rly version -``` - -It should return: - -```bash -version: 2.4.2 -commit: 259b1278264180a2aefc2085f1b55753849c4815 -cosmos-sdk: v0.47.5 -go: go1.21.4 darwin/arm64 -``` - -### Setup relayer config - -Firstly, generate an empty config file with this command: - -```bash -rly config init -``` - -Afterward, replace the content of the file at `$HOME/.relayer/config/config.yaml` with the following configuration using any text editor you prefer. - -```yaml -global: - api-listen-addr: :5183 - timeout: 10s - memo: "" - light-cache-size: 20 -chains: - osmo-local: - type: cosmos - value: - key-directory: /root/.relayer/keys/osmosis-testnet-1 - key: default - chain-id: osmosis-testnet-1 - rpc-addr: http://localhost:46657 - account-prefix: osmo - keyring-backend: test - gas-adjustment: 1.5 - gas-prices: 0.1uosmo - min-gas-amount: 100000 - max-gas-amount: 1000000 - debug: true - timeout: 20s - block-timeout: "" - output-format: json - sign-mode: direct - extra-codecs: [] - coin-type: 118 - signing-algorithm: "" - broadcast-mode: batch - min-loop-duration: 0s - extension-options: [] - feegrants: null - gm-local: - type: cosmos - value: - key-directory: /root/.relayer/keys/test - key: default - chain-id: gm - rpc-addr: http://localhost:36657 - account-prefix: gm - keyring-backend: test - gas-adjustment: 1.5 - gas-prices: 0.1stake - min-gas-amount: 100000 - max-gas-amount: 1000000 - debug: true - timeout: 20s - block-timeout: "" - output-format: json - sign-mode: direct - extra-codecs: [] - coin-type: 118 - signing-algorithm: "" - broadcast-mode: batch - min-loop-duration: 0s - extension-options: [] - feegrants: null -paths: {} -``` - -### Create relayer account - -Add keys for each chain with this command - -The mnemonic-words are the mnemonics you received when initializing the local node. Ensure that each wallet has tokens to start relaying. - -```bash -rly keys restore osmo-local default "milk verify alley price trust come maple will suit hood clay exotic" -rly keys restore gm-local default "milk verify alley price trust come maple will suit hood clay exotic" -``` - -### Create IBC channel - -Create a new blank path to be used in generating a new path (connection and client) between two chains - -```bash -rly paths new osmosis-testnet-1 gm osmo-gm -``` - -and then you can create channel with this command - -```bash -rly transact link osmo-gm -``` - -This is a triple whammy; it creates a client, connection, and channel all in one command. - -Alternatively, you may create them one by one using these commands: - -```bash -rly transact clients osmo-local gm-local osmo-gm -rly transact connection osmo-gm -rly transact channel osmo-gm --src-port transfer --dst-port transfer --order unordered --version ics20-1 -``` - -At the end, it should return something like this : - -```bash -2024-02-15T09:22:04.062649Z info Connection handshake termination candidate {"path_name": "osmo-gm", "chain_id": "gm", "client_id": "07-tendermint-0", "termination_client_id": "07-tendermint-0", "observed_client_id": "07-tendermint-0", "termination_counterparty_client_id": "07-tendermint-0", "observed_counterparty_client_id": "07-tendermint-0"} -2024-02-15T09:22:04.062667Z info Found termination condition for connection handshake {"path_name": "osmo-gm", "chain_id": "gm", "client_id": "07-tendermint-0"} -2024-02-15T09:22:04.069040Z info Starting event processor for channel handshake {"src_chain_id": "osmosis-testnet-1", "src_port_id": "transfer", "dst_chain_id": "gm", "dst_port_id": "transfer"} -2024-02-15T09:22:04.070364Z info Chain is in sync {"chain_name": "gm-local", "chain_id": "gm"} -2024-02-15T09:22:04.070389Z info Chain is in sync {"chain_name": "osmo-local", "chain_id": "osmosis-testnet-1"} -2024-02-15T09:22:10.310493Z info Successful transaction {"provider_type": "cosmos", "chain_id": "osmosis-testnet-1", "gas_used": 165662, "fees": "24023uosmo", "fee_payer": "osmo1vvl79phavqruppr6f5zy4ypxy7znshrqm390ll", "height": 12, "msg_types": ["/ibc.core.client.v1.MsgUpdateClient", "/ibc.core.channel.v1.MsgChannelOpenInit"], "tx_hash": "D7E7E6EC0299C120C0E32167C11F0B60921EF88CC6524345BCEB3B266EF727AA"} -2024-02-15T09:22:15.293348Z info Successful transaction {"provider_type": "cosmos", "chain_id": "gm", "gas_used": 171590, "fees": "6510stake", "fee_payer": "gm1vvl79phavqruppr6f5zy4ypxy7znshrqam48qy", "height": 61, "msg_types": ["/ibc.core.client.v1.MsgUpdateClient", "/ibc.core.channel.v1.MsgChannelOpenTry"], "tx_hash": "DE5F15D2CEB85278FA916185A01FBA5DA604563462893288EC7A8745FB597B96"} -2024-02-15T09:22:18.300397Z info Successful transaction {"provider_type": "cosmos", "chain_id": "osmosis-testnet-1", "gas_used": 126689, "fees": "18177uosmo", "fee_payer": "osmo1vvl79phavqruppr6f5zy4ypxy7znshrqm390ll", "height": 14, "msg_types": ["/ibc.core.client.v1.MsgUpdateClient", "/ibc.core.channel.v1.MsgChannelOpenAck"], "tx_hash": "CB1FA1D3309513FC6C8599606DEFE75164F4CAE2ABD101D78133B287862A5ACA"} -2024-02-15T09:22:19.078583Z info Successfully created new channel {"chain_name": "osmo-local", "chain_id": "osmosis-testnet-1", "channel_id": "channel-0", "connection_id": "connection-0", "port_id": "transfer"} -2024-02-15T09:22:23.296353Z info Successful transaction {"provider_type": "cosmos", "chain_id": "gm", "gas_used": 124972, "fees": "4762stake", "fee_payer": "gm1vvl79phavqruppr6f5zy4ypxy7znshrqam48qy", "height": 69, "msg_types": ["/ibc.core.client.v1.MsgUpdateClient", "/ibc.core.channel.v1.MsgChannelOpenConfirm"], "tx_hash": "B917289EC7566B57B2D0EC759F2E703DBD652F9044362E78C05C4F6DF8FD7AC7"} -2024-02-15T09:22:24.080924Z info Successfully created new channel {"chain_name": "gm-local", "chain_id": "gm", "channel_id": "channel-0", "connection_id": "connection-0", "port_id": "transfer"}[!code focus] -2024-02-15T09:22:24.080992Z info Channel handshake termination candidate {"path_name": "osmo-gm", "chain_id": "gm", "client_id": "07-tendermint-0", "termination_port_id": "transfer", "observed_port_id": "transfer", "termination_counterparty_port_id": "transfer", "observed_counterparty_port_id": "transfer"}//[!code focus] -2024-02-15T09:22:24.080998Z info Found termination condition for channel handshake {"path_name": "osmo-gm", "chain_id": "gm", "client_id": "07-tendermint-0"}//[!code focus] -``` - -::: tip -Notice your `channel_id`, you need to specify it when you make the IBC transfer transaction in next step! -::: - -### Start relaying packets - -After completing all these steps, you can start relaying with: - -```bash -rly start -``` - -IBC transfer of tokens between `osmosis-testnet-1` and `gm` is now possible. - -### Transfer token from rollup chain to osmosis-local - -Make an ibc-transfer transaction. This tx will transfer 1000000stake from `gm-key` to receiver address in your local-osmosis chain. - -Set your keys and channel ID as variables: - -```bash -OSMO_KEY=osmo1vvl79phavqruppr6f5zy4ypxy7znshrqm390ll -GM_KEY=gm1vvl79phavqruppr6f5zy4ypxy7znshrqam48qy -CHANNEL_ID=channel-0 -``` - -```bash -gmd tx ibc-transfer transfer transfer $CHANNEL_ID $OSMO_KEY 42069stake --node tcp://localhost:36657 --chain-id gm --from gm-key --keyring-backend test --fees 5000stake -``` - -Then check the balance of the receiver address to see if the token has been relayed or not. - -```bash -osmosisd query bank balances $OSMO_KEY --node tcp://localhost:46657 --chain-id osmosis-testnet-1 -``` - -The balances query command should return something like this: - -```bash -balances: -- amount: "42069" - denom: ibc/C053D637CCA2A2BA030E2C5EE1B28A16F71CCB0E45E8BE52766DC1B241B77878 -- amount: "100000000999876914" - denom: uosmo -- amount: "100000000000000" - denom: utest -pagination: - next_key: null - total: "0" -``` - -::: tip -`ibc/64BA6E31FE887D66C6F8F31C7B1A80C7CA179239677B4088BB55F5EA07DBE273` is corresponding IBC denom in osmosis-testnet for native denom `stake` in GM chain. Your hash will be different than this and specific to your channel. -::: - -### Transfer token back from osmosis-local to rollup chain - -Set your channel hash from the last step like this: - -```bash -IBC_DENOM_STRING=youribc/64BA6E31FE887D66C6F8F31C7B1A80C7CA179239677B4088BB55F5EA07DBE273 -``` - -Make an ibc-transfer transaction: - -```bash -osmosisd tx ibc-transfer transfer transfer $CHANNEL_ID $GM_KEY 42069$IBC_DENOM_STRING --node tcp://localhost:46657 --chain-id osmosis-testnet-1 --from osmosis-relay --fees 500uosmo -``` - -And then check the balances of the receiver address to see if the token has been relayed or not: - -```bash -gmd query bank balances $GM_KEY --node tcp://localhost:36657 -``` - -The balances query command should return something like this, -which is close to the original balance, minus some gas fees: - -```bash -gmd query bank balances $GM_KEY --node tcp://localhost:36657 -balances: -- amount: "9999999999999999999897679" - denom: stake -pagination: - total: "1" -``` diff --git a/guides/zkml.md b/guides/zkml.md deleted file mode 100644 index aeae0678f..000000000 --- a/guides/zkml.md +++ /dev/null @@ -1,255 +0,0 @@ -# zkML Rollup Tutorial with Sindri - -## Introduction - Code Once, Verify Anywhere - -This guide will show you how to build verifiable machine learning inference into your Rollkit rollup using zero-knowledge proofs generated on [Sindri](https://sindri.app). -The rollup will rely on a local Celestia devnet for consensus and ensuring data availability. - -We will focus on using a ZK circuit that incorporates a compact deep neural network model to enable verifiable ML inference. -In this guide, we will deploy the circuit on Sindri, obtain a smart contract verifier (automatically generated by Sindri) for that circuit, deploy it on Rollkit, create a proof of ML inference on Sindri, and verify the proof on-chain. - -This approach not only secures the verification process of machine learning models, but also leverages the decentralized security and scalability of Celestia's architecture. - -## Prerequisites - -- An operational EVM using Rollkit (see next step) -- A [Sindri](https://sindri.app) API key, which can be obtained [here](https://hen4zp9gxq3.typeform.com/to/hJHlUF8c?typeform-source=sindri.app) -- Python 3.10+ installed as well as the [Sindri Python SDK](https://sindri.app/docs/reference/sdk/python/) (more information below) - -### Setting Up the Polaris EVM using Rollkit - -This walkthrough assumes you started the Polaris EVM using Rollkit and should be interpreted as a direct continuation of this Polaris EVM and Rollkit guide. - -### Installing the Sindri Python SDK - -Because we're working with ML, we're going to build with Sindri's Python SDK because Python is widely used in ML development. -The [Sindri Python SDK Quickstart Guide](https://sindri.app/docs/getting-started/api-sdk/#python-sdk) contains installation instructions and a high-level walkthrough of the functionality of this package, but the following will suffice if you have `pip` installed: - -```bash -pip install sindri -``` - -## Deploying and Proving a Cool zkML Circuit to Sindri - -For this tutorial, we'll be working with a pre-built zkML circuit built by Sindri. -_For a more in-depth description of this circuit and its corresponding ML model's behavior and design, please see [here](https://github.com/Sindri-Labs/sindri-resources/tree/main/circuit_tutorials/circom/food_ml/README.md)._ - -### Clone - -Clone the [Sindri Resources](https://github.com/Sindri-Labs/sindri-resources/tree/main) GitHub repo. - -```bash -cd $HOME -git clone https://github.com/Sindri-Labs/sindri-resources.git -``` - -Navigate to the `food_ml` circuit tutorial directory. - -```bash -cd sindri-resources/circuit_tutorials/circom/food_ml/ -``` - -Here, you will find a handful of files. -The `circuit/` directory contains the circuit code that we will upload to Sindri. -The `circuit/sindri.json` file is the Sindri manifest for your upload. -Within it, you can modify the circuit's `"name"` value to whatever you like. - -### Modify - -Open the `compile_and_prove.py` script and append the following lines to the very bottom. - -```python -# Obtain smart contract verifier for our circuit and save it to a file -smart_contract_code: str = sindri.get_circuit_smart_contract_verifier(circuit_id) -verifier_code_file: str = "Verifier.sol" -with open(verifier_code_file, "w") as f: - f.write(smart_contract_code) -print(f"Smart contract verifier code written to {verifier_code_file}\n") - -# Obtain our proof's proof+public formatted as calldata for our circuit's -# smart contract verifier -proof = sindri.get_proof(proof_id, include_smart_contract_calldata=True) -calldata_file: str = "calldata.txt" -calldata: str = proof["smart_contract_calldata"] - -# Fix formatting so it works with Rollkit -import json -a = json.loads("["+calldata_str+"]") -calldata_objects = [] -for i in a: - calldata_objects.append(json.dumps(i).replace("\"", "").replace(" ","")) -rollkit_calldata_str = " ".join(calldata_objects) - -# Save calldata to file -with open(calldata_file, "w") as f: - f.write(rollkit_calldata_str) -print(f"Proof calldata written to {calldata_file}\n") -``` - -These additions will allow us to fetch and save the following to files: - -- the circuit's smart contract verifier code that is generated by Sindri when we deployed our circuit -- the proof's proof+public formatted as calldata to run with the smart contract verifier _on Rollkit_ - -### Deploy and Prove your zkML Circuit on Sindri - -Export your Sindri API Key to an environment variable (or prepend it to the run command in the next step). - -```bash -export SINDRI_API_KEY= -``` - -Run the `compile_and_prove.py` script. -This will upload the `circuit/` directory to Sindri, where Sindri will compile and host your circuit. -Then, it will run a single proof for the circuit. -Finally, it will save the circuit's smart contract verifier code that is generated by Sindri to the `Verifier.sol` file and it will save the proof's proof+public formatted as `calldata` for that smart contract to `calldata.txt`. - -```bash -python3 compile_and_prove.py -``` - -Congratulations! -You just deployed a zkML circuit to Sindri and proved it on Sindri's production-quality infrastructure with built-in, custom GPU-accelerated proving techniques. -Furthermore, you now have smart contract verifier code (and some calldata) for verifying proofs of that circuit on-chain. - -## Deploy Smart Contract Verifier to Rollkit - -Next, we will deploy this smart contract to Rollkit and verify our zkML proof on-chain. -_This section assumes you have an operational Rollkit instance of Polaris EVM running and your `gm-portal/` directory is located in the `$HOME` directory on your machine._ - -### Deploy - -Copy your new `Verifier.sol` smart contract to the `~/gm-portal/contracts/src/.` directory in your Polaris EVM. - -```bash -cd $HOME -cp sindri-resources/circuit_tutorials/circom/food_ml/Verifier.sol gm-portal/contracts/src/Verifier.sol -``` - -Next, let's make a copy of the example `~/gm-portal/contracts/script/GmPortal.s.sol` and modify it to reference your new `Verifier.sol` contract. - -```bash -cd gm-portal/contracts/script/ -cp GmPortal.s.sol Verifier.s.sol -``` - -Open up the new `Verifier.s.sol` and modify it to interact with your new `Verifier.sol` instead of the example `GmPortal.sol`. - -``` -// SPDX-License-Identifier: MIT -pragma solidity ^0.8.13; - -import "forge-std/Script.sol"; - -import {Verifier} from "src/Verifier.sol"; - -contract VerifierScript is Script { - function setUp() public {} - - function run() public { - vm.startBroadcast(); - new Verifier(); - vm.stopBroadcast(); - } -} -``` - -Then, deploy the contract to your Rollkit environment. -_Your `PRIVATE_KEY` and `RPC_URL` are for your Rollkit Polaris EVM._ - -```bash -export PRIVATE_KEY=0xfffdbb37105441e14b0ee6330d855d8504ff39e705c3afa8f859ac9865f99306 -export RPC_URL=http://localhost:8545 -``` - -```bash -cd .. -forge script script/Verifier.s.sol:VerifierScript --rpc-url $RPC_URL --private-key $PRIVATE_KEY --broadcast -``` - -A successful deployment's output will look similar to the following. - -``` -forge script script/Verifier.s.sol:VerifierScript --rpc-url $RPC_URL --private-key $PRIVATE_KEY --broadcast -[⠒] Compiling... -[⠆] Compiling 20 files with 0.8.24 -[⠰] Solc 0.8.24 finished in 101.99ms -Compiler run successful! -Script ran successfully. - -== Logs == - i am a smart contract on Polaris EVM x Rollkit. gm! - -[...] - -## -Waiting for receipts. -⠉ [00:00:00] [######################] 1/1 receipts (0.0s) -##### 80085 -✅ [Success]Hash: 0xa06a4585af436e2271fc9f697488ce49771c6480e72caac76739e286564c0fc3 -Contract Address: 0x5C59C83c099F72FcE832208f96a23a1E43737a14 -Block: 5699 -Paid: 0.002924172006823068 ETH (974724 gas * 3.000000007 gwei) - -[...] -``` - -From your contract deployment output, **export your contract address**: `Contract Address: 0x5C59C83c099F72FcE832208f96a23a1E43737a14`. _Note that the address will be different._ - -```bash -export CONTRACT_ADDRESS=0x5C59C83c099F72FcE832208f96a23a1E43737a14 -``` - -## Interact with the Contract - Verify your zkML Proof On-Chain - -Now, we will send your zkML circuit's proof to the contract and verify it on-chain. -Keep in mind that your verifier contract can be used across any EVM-compatible environment. -Thus, we can compare the cost of execution across multiple environments. - -First, grab the contents of your proof calldata and save it in a variable. - -```bash -CALLDATA=$(cat $HOME/sindri-resources/circuit_tutorials/circom/food_ml/calldata.txt) -``` - -Then, interact with the smart contract using the calldata. - -```bash -cast send $CONTRACT_ADDRESS \ -"verifyProof(uint256[2],uint256[2][2],uint256[2],uint256[1])" \ -$CALLDATA \ ---private-key $PRIVATE_KEY \ ---rpc-url $RPC_URL -``` - -The output will look like the following. - -```bash -cast send $CONTRACT_ADDRESS "verifyProof(uint256[2],uint256[2][2],uint256[2],uint256[1])" $CALLDATA --private-key $PRIVATE_KEY --rpc-url $RPC_URL - -blockHash 0xbbd872d0c37fe889c2456daf80505c20f262b001842d919d06e48c163319af3d -blockNumber 11544 -contractAddress -cumulativeGasUsed 231649 -effectiveGasPrice 3000000007 -from 0x20f33CE90A13a4b5E7697E3544c3083B8F8A51D4 -gasUsed 231649 -logs [] -logsBloom 0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 -root -status 1 -transactionHash 0x58096aabd3cb58bdef28501bda01b6cf4a37ed0ba482f81462bc1043bb91f996 -transactionIndex 0 -type 2 -to 0x5C59C83c099F72FcE832208f96a23a1E43737a14 -``` - -:::tip -Note: To see the decoded output of the contract call (to check if the proof was verified), you will need to view the call in a block explorer. -::: - -## Congratulations - -Congratulations, you've just verified a zkML circuit on Rollkit. - -For further reading, check out [Sindri's blog post](https://sindri.app/blog/2024/02/21/zkml-modularity/) explaining how using Sindri + Rollkit x Celestia means verifiable ML doesn’t have to be prohibitively expensive for operators or end users. diff --git a/tutorials/execution/cosmwasm.md b/tutorials/execution/cosmwasm.md index 8b0d67f38..0528c035e 100644 --- a/tutorials/execution/cosmwasm.md +++ b/tutorials/execution/cosmwasm.md @@ -209,7 +209,7 @@ docker exec -it $CW sh In order to deploy a contract, you can use the command line as described below. For a better experience and to use Rust code instead of the command line to -deploy/script and test your contracts, you can use [cw-orchestrator](/guides/cw-orch.md). +deploy/script and test your contracts, you can use cw-orchestrator. ```bash @@ -232,7 +232,7 @@ In the previous steps, we have stored out contract's tx hash in an environment variable for later use. The following guide will show you how to deploy and interact with a contract using CLI. -For scripting using Rust, you can use [cw-orchestrator](/guides/cw-orch.md). +For scripting using Rust, you can use cw-orchestrator. ### 🔎 Contract querying {#contract-querying}