Skip to main content

Develop Your First Strategy

Strategy bot is a wasm code configured with static FIS query. For concepts and components, see overview

Installation​

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

See installations for more details

Example context​

This example explains how to implement an example called bank-dummy, which will deposit 1 lux from sender if some of the configured addresses having odd balance

Let's code​

Init project​

Create bank-dummy project and init new rust library using cargo

mkdir bank-dummpy && cd bank-dummy
cargo init --lib

Project structure looks like

bank-dummy
├── Cargo.toml
└── src
    └── lib.rs

Configure Cargo.toml​

[package]
name = "bank-dummy"
version = "0.0.1"
edition = "2021"

[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 = []

Start coding​

Source code should be placed in src/lib.rs

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

#[cw_serde]
pub struct InstantiateMsg {}

#[cw_serde]
pub enum ExecuteMsg {}

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

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

#[cw_serde]
pub struct Fund {
    receivers: Vec<String>,
}

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

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

#[cw_serde]
pub struct MsgSend {
    from_address: String,
    to_address: String,
    amount: Vec<BankAmount>,
}

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

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

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

#[entry_point]
pub fn query(_deps: Deps, env: Env, msg: QueryMsg) -> StdResult<Binary> {
    let command = from_json::<Fund>(msg.msg)?;
    let balances_input = msg.fis_input[0].clone();

    let mut instructions = vec![];
    for i in 0..balances_input.data.len() {
        let fis_input = from_json::<BankAmount>(balances_input.data.get(i).unwrap())?;
        let balance = Uint256::from_str(fis_input.amount.as_str()).unwrap();
        if balance % Uint256::from_u128(2u128) == Uint256::one() {
            instructions.push(FISInstruction {
                plane: "COSMOS".to_string(),
                action: "COSMOS_BANK_SEND".to_string(),
                address: "".to_string(),
                msg: to_json_binary(&MsgSend {
                    from_address: env.contract.address.clone().into_string(),
                    to_address: command.receivers[i].clone(),
                    amount: vec![BankAmount {
                        denom: fis_input.denom.to_string(),
                        amount: "1".to_string(),
                    }],
                })
                .unwrap()
                .to_vec(),
            })
        }
    }

    Ok(to_json_binary(&StrategyOutput { instructions }).unwrap())
}

Code components​

Query function

The query function is triggered by Flux to execute the strategy. It returns a StrategyOutput containing FIS instructions that Flux Astromesh will execute later.

Please read the following code comments for the implementation details

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

#[cw_serde]
pub struct Fund {
    receivers: Vec<String>,
}

#[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 this example
    // command has type Fund, json serialized, which points out the receivers to top up if their balance are ODD
    let command = from_json::<Fund>(msg.msg)?;
    let balances_input = msg.fis_input[0].clone();

    // compose instructions base on input
    let mut instructions = vec![];
    for i in 0..balances_input.data.len() {
        let fis_input = from_json::<BankAmount>(balances_input.data.get(i).unwrap())?;
        let balance = Uint256::from_str(fis_input.amount.as_str()).unwrap();

        // if the receiver balance is odd, we send 1 lux
        if balance % Uint256::from_u128(2u128) == Uint256::one() {
            instructions.push(FISInstruction {
                plane: "COSMOS".to_string(),
                action: "COSMOS_BANK_SEND".to_string(),
                address: "".to_string(),
                msg: to_json_binary(&MsgSend {
                    from_address: env.contract.address.clone().into_string(),
                    to_address: command.receivers[i].clone(),
                    amount: vec![BankAmount {
                        denom: fis_input.denom.to_string(),
                        amount: "1".to_string(),
                    }],
                })
                .unwrap()
                .to_vec(),
            })
        }
    }

    // return instruction formatted as json
    Ok(to_json_binary(&StrategyOutput { instructions }).unwrap())
}

Explain for the fields is elaborated as follows:

QueryMsg

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

QueryMsg contains the input of the client's message in msg field and input from configured Flux instruction set in fis_input

Strategy must know how to decode both fields

FisInput

FisInput contains the query result, data is a vector of arbitrary Binary, the strategy code must know how to deserialize it. In the given example, code uses Fund struct to decode input in data field

#[cw_serde]
pub struct Fund {
    receivers: Vec<String>,
}

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

StrategyOutput

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

StrategyOutput should contains an array of FISInstruction. These instructions will be executed by Flux Astromesh after the strategy query method is trigerred

FISInstruction

Flux instruction set (FIS) Instructions are the actions that Flux Astromesh will execute after running strategy. For details, see transaction instructions

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

Build​

cargo build --lib --target wasm32-unknown-unknown --release

Ensure the compiled binary existed at target/wasm32-unknown-unknown/release/bank_dummy.wasm

Deploy strategy​

Assume we are in bank-dummy folder, let's copy bank_dummy.wasm to sdk-go as strategy.wasm

cp target/wasm32-unknown-unknown/release/bank_dummy.wasm ../sdk-go/examples/chain/21_MsgConfigStrategy/strategy.wasm
cd ../sdk-go
yes 12345678 | go run examples/chain/21_MsgConfigStrategy/example.go

strategytypes.MsgConfigStrategy details:

msg := &strategytypes.MsgConfigStrategy{
    // message sender
    Sender:   senderAddress.String(),
    // strategy config type
    Config:   strategytypes.Config_deploy,
    // strategy binary
    Strategy: <binary_goes_here>,
    // the predefined query which result will be input into strategy
    Query: &types.FISQueryRequest{
        // in this case, this query tracks balances of accounts you want to make the amount even
        Instructions: []*types.FISQueryInstruction{
            {
                Plane:   types.Plane_COSMOS,
                Action:  types.QueryAction_COSMOS_BANK_BALANCE,
                Address: []byte{},
                Input: [][]byte{
                    []byte("lux1cml96vmptgw99syqrrz8az79xer2pcgp209sv4,lux1jcltmuhplrdcwp7stlr4hlhlhgd4htqhu86cqx"),
                    []byte("usdt,lux"),
                },
            },
        },
    },
    // for strategy, it's good practice to specify who can trigger it in TriggerPermission
    TriggerPermission: &strategytypes.PermissionConfig{
        Type:      strategytypes.AccessType_only_addresses,
        Addresses: []string{senderAddress.String()},
    },
}

Trigger strategy​

Find the deployed strategy ID​

Use this chain API to find the latest Id:

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

In our context, use

http://lcd.localhost/flux/strategy/v1beta1/strategies/owner/lux1cml96vmptgw99syqrrz8az79xer2pcgp209sv4
{
    "strategies": [
        "id": "7F0F8A1C1FF06F3C2F045BFF82902541986298264E56D6695D436CD0548206A3", <- this is the ID of deployed strategy
        "code_checksum": "5DCB02E4166CE3BF6D37B91AC69825A40FCC66A9714323C8CA89DD1580216773",
        "owner": "lux1cml96vmptgw99syqrrz8az79xer2pcgp209sv4",
        "query": {
        "instructions": [
            {
            "plane": "COSMOS",
            "action": "COSMOS_BANK_BALANCE",
            "address": null,
            "input": [
                "bHV4MWNtbDk2dm1wdGd3OTlzeXFycno4YXo3OXhlcjJwY2dwMjA5c3Y0LGx1eDFqY2x0bXVocGxyZGN3cDdzdGxyNGhsaGxoZ2Q0aHRxaHU4NmNxeA==",
                "dXNkdCxsdXg="
            ]
            }
        ]
        },
        "query_hash": "C0B98BE41D7BAB5C0800F774B0370D7638502807FF20164D7DD9D43A4A7E7730",
        "is_enabled": true,
        "trigger_permission": {
            "type": "anyone",
            "addresses": []
        },
        "metadata": null
    ]
},

Run the script​

Copy the id and paste into MsgTriggerStrategies, see the following code snippet:

msg := &strategytypes.MsgTriggerStrategies{
    Sender: senderAddress.String(),
    Ids:    []string{"7F0F8A1C1FF06F3C2F045BFF82902541986298264E56D6695D436CD0548206A3"},
    Inputs: [][]byte{
        []byte(`{"receivers":["lux1jcltmuhplrdcwp7stlr4hlhlhgd4htqhu86cqx","lux1kmmz47pr8h46wcyxw8h3k8s85x0ncykqp0xmgj"]}`),
    },
}
go run examples/chain/21_MsgConfigStrategy/example.go

We can try these steps multiple times:

  • Send some balances to configured addresses (lux1jcltmuhplrdcwp7stlr4hlhlhgd4htqhu86cqx, lux1kmmz47pr8h46wcyxw8h3k8s85x0ncykqp0xmgj)
  • Run the script to see the their odd balance increased by 1

Congratulations! Now you know how to build a strategy on Flux Astromesh. Happy building!