api-design

name: api-design

description: Best practices for designing CosmWasm smart contract APIs. Use when defining message types, designing execute/query interfaces, or optimizing API ergonomics.

license: BSD-3-Clause

metadata:

author: axone.xyz

version: "1.0"

CosmWasm API Design Best Practices

Core Principles

1. Minimalism - Include only what's necessary; avoid bloated APIs

2. Clarity - Names should be self-documenting

3. Consistency - Follow established patterns across all contracts

4. Documentation - Every public type and field must have doc comments

Message Type Patterns

InstantiateMsg

/// Contract instantiation message

#[cosmwasm_schema::cw_serde]

#[derive(Default)]

pub struct MyContractInstantiateMsg {

    /// Optional configuration parameter with sensible default

    #[serde(default)]

    pub some_config: Option<String>,

}

Guidelines:

• Derive Default when possible for easier testing

• Use #[serde(default)] for optional fields

• Keep required fields minimal

• Document each field

ExecuteMsg

/// Contract execute messages

#[cosmwasm_schema::cw_serde]

#[derive(cw_orch::ExecuteFns)]

pub enum MyContractExecuteMsg {

    /// Update the contract configuration

    UpdateConfig {

        /// New admin address (optional)

        new_admin: Option<String>,

    },

    /// Process an action with the given parameters

    ProcessAction {

        /// Unique identifier for the action

        action_id: String,

        /// Amount to process

        amount: Uint128,

    },

}

Guidelines:

• Use verb-based names (Update, Process, Create, Remove)

• Group related parameters in structs if >3 fields

• Document each variant AND each field

• Derive ExecuteFns for cw-orch integration

QueryMsg

/// Contract query messages

#[cosmwasm_schema::cw_serde]

#[derive(cw_orch::QueryFns, QueryResponses)]

pub enum MyContractQueryMsg {

    /// Get the current configuration

    #[returns(ConfigResponse)]

    Config {},

    

    /// Get item by ID

    #[returns(ItemResponse)]

    Item {

        /// The item identifier

        id: String,

    },

    

    /// List all items with pagination

    #[returns(ItemsResponse)]

    Items {

        /// Start after this ID for pagination

        start_after: Option<String>,

        /// Maximum number of items to return

        limit: Option<u32>,

    },

}

Guidelines:

• Always include #[returns(ResponseType)] attribute

• Use noun-based names for queries

• Include pagination for list queries (start_after, limit)

• Derive QueryFns and QueryResponses

Response Types

#[cosmwasm_schema::cw_serde]

pub struct ConfigResponse {

    /// Current admin address

    pub admin: Addr,

    /// Whether the contract is paused

    pub paused: bool,

}



#[cosmwasm_schema::cw_serde]

pub struct ItemsResponse {

    /// List of items

    pub items: Vec<ItemInfo>,

}

Guidelines:

• Response types should mirror what clients need

• Use specific types (Addr, Uint128) not strings

• Document all fields

Abstract SDK Integration

Use the app_msg_types! macro to generate wrapper types:

use crate::contract::MyContract;

use cosmwasm_schema::QueryResponses;



// Generates ExecuteMsg, QueryMsg, InstantiateMsg wrappers

abstract_app::app_msg_types!(MyContract, MyContractExecuteMsg, MyContractQueryMsg);

Documentation Standards

Rust Doc Comments

/// Brief one-line description of the variant.

/// 

/// Optional longer description that explains:

/// - When to use this

/// - Side effects

/// - Related messages

/// 

/// # Errors

/// 

/// Returns `ContractError::Unauthorized` if caller is not admin.

Field Documentation

Every field must have a doc comment:

• Describe what the field represents

• Mention default values if applicable

• Note any constraints (min/max values, format)

Serde Patterns

Optional Fields with Defaults

#[serde(default)]

pub optional_field: Option<String>,



#[serde(default = "default_limit")]

pub limit: u32,



fn default_limit() -> u32 {

    10

}

Flatten for Nested Configs

#[cosmwasm_schema::cw_serde]

pub struct InstantiateMsg {

    #[serde(flatten)]

    pub base_config: BaseConfig,

    pub custom_field: String,

}

Rename for JSON Clarity

#[serde(rename = "owner")]

pub owner_addr: Addr,