Skip to main content

Develop Your First Intent Solver

Intent solver bot is a strategy. Refer to concepts here

Installation​

  • Install rust toolchain, add environment wasm32-unknown-unknown
  • Golang 1.21 and an IDE

See installations for more details

Example context​

This example demonstates how to write an astromesh transfer intent solver. The intent solver supports two actions:

  • Withdraw from all planes to cosmos.
  • Deposit equally some token amount from COSMOS to 3 planes. E.g user could distrubute 30 USDT equally into 3 planes (wasm, evm and svm), each plane has 10 USDT

Now the example purpose is clear, let's see below sections to start coding

Let's code​

Init project​

Let's name the project plane-util

mkdir plane-util && plane-util
cargo init --lib

Folder structure:

├── Cargo.toml
└── src
    └── lib.rs

Configure Cargo.toml​

Use this template with this basic example, later on, feel free to customize it for specific need

[package]
name = "plane-util"
version = "0.0.1"
edition = "2021"

# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

[dependencies]
cosmwasm-std = "2.0.1"
serde = { version = "1.0.145", default-features = false, features = ["derive"] }
cosmwasm-schema = "2.0.1"

[lib]
crate-type = ["cdylib", "rlib"]

[features]
# use library feature to disable all instantiate/execute/query exports
library = []

Coding​

use cosmwasm_schema::cw_serde;
use cosmwasm_std::{
    entry_point, from_json, to_json_binary, to_json_vec, Binary, Deps, DepsMut, Env, MessageInfo,
    Response, StdResult, Uint256,
};
use std::vec::Vec;

#[cw_serde]
pub struct InstantiateMsg {}

#[cw_serde]
pub enum ExecuteMsg {}

#[cw_serde]
pub struct FisInput {
    data: Vec<Binary>,
}

#[cw_serde]
pub struct QueryMsg {
    msg: Binary,
    fis_input: Vec<FisInput>,
}

#[cw_serde]
pub struct FISInstruction {
    plane: String,
    action: String,
    address: String,
    msg: Vec<u8>,
}

#[cw_serde]
pub enum AbstractionObject {
    WithdrawAllPlane {},
    DepositEqually {
        denom: String,
        amount: Uint256,
    }
}

#[cw_serde]
pub struct StrategyOutput {
    instructions: Vec<FISInstruction>,
}

#[cw_serde]
pub struct AstroTransferMsg {
    sender: String,
    receiver: String,
    src_plane: String,
    dst_plane: String,
    coin: Coin,
}

#[cw_serde]
pub struct Coin {
    denom: String,
    amount: Uint256,
}

#[entry_point]
pub fn instantiate(
    _deps: DepsMut,
    _env: Env,
    _info: MessageInfo,
    _msg: InstantiateMsg,
) -> StdResult<Response> {
    Ok(Response::new().add_attribute("method", "instantiate"))
}

#[entry_point]
pub fn execute(
    _deps: DepsMut,
    _env: Env,
    _info: MessageInfo,
    _msg: ExecuteMsg,
) -> StdResult<Response> {
    Ok(Response::new().add_attribute("method", "execute"))
}

#[entry_point]
pub fn query(_deps: Deps, env: Env, msg: QueryMsg) -> StdResult<Binary> {
    // parse the input message, it can be any type (json, proto or encrypted binary)
    // in intent solver, input is usually json called Abstraction Object
    // in this example, we parse msg as AbstractionObject
    let abs_obj = from_json::<AbstractionObject>(msg.msg.to_vec()).unwrap();
    let fis_input = &msg.fis_input.get(0).unwrap().data;

    // compile the object into FIS instructions
    let instructions = match abs_obj {
        // WithdrawAllPlane case, we get balances of a `denom` from all planes and compose instructions
        // to send them all back to cosmos
        // the query was specified when we trigger the intent
        AbstractionObject::WithdrawAllPlane { } => {
            let address = env.contract.address;
            // get wasm, evm, svm balances in order
            let wasm_balance = from_json::<Coin>(fis_input.get(0).unwrap()).unwrap();
            let evm_balance = from_json::<Coin>(fis_input.get(1).unwrap()).unwrap();
            let svm_balance = from_json::<Coin>(fis_input.get(2).unwrap()).unwrap();

            let planes = vec!["WASM", "EVM", "SVM"];
            let balances = vec![wasm_balance, evm_balance, svm_balance];
            let mut ixs = vec![];
            for i in 0..planes.len() {
                let plane = planes.get(i).unwrap();
                let balance = balances.get(i).unwrap();
                let mut denom = balance.clone().denom;
                if plane == &"EVM" || plane == &"SVM" {
                    denom = String::from("astro/") + denom.as_str();
                }

                if !balance.amount.is_zero() {
                    ixs.push(FISInstruction {
                        plane: "COSMOS".to_string(),
                        action: "COSMOS_ASTROMESH_TRANSFER".to_string(),
                        address: "".to_string(),
                        msg: to_json_vec(&AstroTransferMsg {
                            sender: address.to_string(),
                            receiver: address.to_string(),
                            src_plane: plane.to_string(),
                            dst_plane: "COSMOS".to_string(),
                            coin: Coin {
                                denom,
                                amount: balance.amount,
                            },
                        })
                        .unwrap(),
                    })
                }
            }
            ixs
        },
        // DepositEqually, we split the amount into 3 parts and send it to each plane
        // The balance query is also configured when we trigger the intent
        AbstractionObject::DepositEqually { denom, amount } => {
            let address = env.contract.address;
            let balance = from_json::<Coin>(fis_input.get(0).unwrap()).unwrap();
            assert!(
                balance.amount.le(&amount),
                "transfer amount must not exceed current balance"
            );
            let divided_amount = amount.checked_div(Uint256::from(3u128)).unwrap();
            vec!["WASM", "EVM", "SVM"]
                .iter()
                .map(|plane| FISInstruction {
                    plane: "COSMOS".to_string(),
                    action: "COSMOS_ASTROMESH_TRANSFER".to_string(),
                    address: "".to_string(),
                    msg: to_json_vec(&AstroTransferMsg {
                        sender: address.to_string(),
                        receiver: address.to_string(),
                        src_plane: "COSMOS".to_string(),
                        dst_plane: plane.to_string(),
                        coin: Coin {
                            denom: denom.clone(),
                            amount: divided_amount,
                        },
                    })
                    .unwrap(),
                })
                .collect()
        }
    };

    // return the instructions in json format
    StdResult::Ok(to_json_binary(&StrategyOutput { instructions }).unwrap())
}

Code components​

Since intent solver make use of strategy, they shares same definitions, see strategy code components

Deploy intent solver​

Assume we are in plane-util folder, let's copy plane_util.wasm to sdk-go as intent_solver.wasm

cp target/wasm32-unknown-unknown/release/plane_util.wasm ../sdk-go/examples/chain/24_ConfigIntentSolver/intent_solver.wasm
cd ../sdk-go
yes 12345678 | go run examples/chain/24_ConfigIntentSolver/example.go

Metadata and prompts display​

We use same message to deploy intent solver, field explainations can be found in strategy deploy section

Also, Flux Astromesh supports metadata for intent solver, creator can configure metadata for displaying prompts on Astromesh app

msg := &strategytypes.MsgConfigStrategy{
    Sender:   senderAddress.String(),
    Config:   strategytypes.Config_deploy,
    Id:       "",
    Strategy: bz,
    Query:    &types.FISQueryRequest{},
    Metadata: &strategytypes.StrategyMetadata{
        // metadata goes here
    },
}

Fields:

{
  "name": <Intent name>,
  "description": <Intent description>,
  "logo": <Logo url>,
  "website":  <Intent website>,
  "type": <Type of the strategy, for intent solver, should set type = INTENT_SOLVER>,
  "tags": [
    "helper"
  ],
  "schema": "<Schema json string>"
}

Default Schema expected by Fluxd has following structure

{
  "groups": [
    {
      "name": "<group name>",
      "prompts": {
        "<action>": {
          "template": "<prompt template>",
          "query": {
            "instructions": <FISQueryInstructions>
          }
        }
      }
    }
  ]
}

Example:

{
  "name": "Astromesh plane util",
  "description": "Astromesh transfer intent solver that helps user manage tokens easily",
  "logo": "https://media.licdn.com/dms/image/D560BAQG83Lxt5OyW4Q/company-logo_200_200/0/1706516333778?e=1724889600&v=beta&t=_fD4VtBEpNKJ8gESgFOcZyTDrQFlRUfxw1iQD8mItnM",
  "website": "https://www.astromesh.xyz",
  "type": 1,
  "tags": [
    "helper"
  ],
  "schema": "{\"groups\":[{\"name\":\"transfer helper\",\"prompts\":{\"withdraw_all_planes\":{\"template\":\"withdraw ${denom:string} from planes to cosmos\",\"query\":{\"instructions\":[{\"plane\":\"COSMOS\",\"action\":\"COSMOS_ASTROMESH_BALANCE\",\"address\":\"\",\"input\":[\"JHt3YWxsZXR9\",\"JHtkZW5vbX0=\"]}]}}}}]}"
}

Schema

This is example of schema when we look closer

{
  "groups": [
    {
      "name": "transfer helper",
      "prompts": {
        "withdraw_all_planes": {
          "template": "withdraw ${denom:string} from planes to cosmos",
          "query": {
            "instructions": [
              {
                "plane": "COSMOS",
                "action": "COSMOS_ASTROMESH_BALANCE",
                "address": "",
                "input": [
                  "JHt3YWxsZXR9",
                  "JHtkZW5vbX0="
                ]
              }
            ]
          }
        }
      }
    }
  ]
}

Display of intent solver on Astromesh frontend app (TBU)

Trigger​

Find intent (strategy) ID​

Use this chain API to find the latest Id:

http://lcd.localhost/flux/strategy/v1beta1/strategies/owner/{strategy_owner}

Run trigger script​

Copy the id and past into MsgTriggerStrategies, code should looks like this one:

msg := &strategytypes.MsgTriggerStrategies{
    Sender: senderAddress.String(),
    Ids:    []string{"F03BE7C54C3B01DFA36118EF104AE8C4FCD82C32CAC6E6D0D23D832AA207BDDB"},
    Inputs: [][]byte{
        []byte(`{"withdraw_all_plane":{}}`),
    },
    Queries: []*astromeshtypes.FISQueryRequest{
        {
            Instructions: []*astromeshtypes.FISQueryInstruction{
                {
                    Plane:   astromeshtypes.Plane_COSMOS,
                    Action:  astromeshtypes.QueryAction_COSMOS_ASTROMESH_BALANCE,
                    Address: nil,
                    Input: [][]byte{
                        []byte(senderAddress.String()),
                        []byte("usdt"),
                    },
                },
            },
        },
    },
}

Run trigger script

yes 12345678 | go run examples/chain/26_TriggerIntentSolver/example.go

Different point from using normal strategy, we need dynamic FIS query. This query will run before invoking the bot's query function

In this example, we would like to get the sender balances on all vm planes, hence use QueryAction_COSMOS_ASTROMESH_BALANCE

Now we can try deposit usdt to different planes and run the script to see balances are all transferred back to cosmos in one script

Congratulations! Now you know how to build an intent solver bot on Flux Astromesh. Happy building!