Struct cosmwasm_std::SubMsg

pub struct SubMsg<T = Empty> {
    pub id: u64,
    pub payload: Binary,
    pub msg: CosmosMsg<T>,
    pub gas_limit: Option<u64>,
    pub reply_on: ReplyOn,
}

A submessage that will guarantee a reply call on success or error, depending on the reply_on setting. If you do not need to process the result, use regular messages instead.

Note: On error the submessage execution will revert any partial state changes due to this message, but not revert any state changes in the calling contract. If this is required, it must be done manually in the reply entry point.

Fields

id: u64

An arbitrary ID chosen by the contract. This is typically used to match Replys in the reply entry point to the submessage.

payload: Binary

Some arbirary data that the contract can set in an application specific way. This is just passed into the reply entry point and is not stored to state. Any encoding can be used. If id is used to identify a particular action, the encoding can also be different for each of those actions since you can match id first and then start processing the payload.

The environment restricts the length of this field in order to avoid abuse. The limit is environment specific and can change over time. The initial default is 128 KiB.

Unset/nil/null cannot be differentiated from empty data.

On chains running CosmWasm 1.x this field will be ignored.

msg: CosmosMsg<T>

gas_limit: Option<u64>

Gas limit measured in Cosmos SDK gas.

Setting this to None means unlimited. Then the submessage execution can consume all gas of the current execution context.

reply_on: ReplyOn

Implementations

impl<T> SubMsg<T>

pub fn new(msg: impl Into<CosmosMsg<T>>) -> Self

Creates a “fire and forget” message with the pre-0.14 semantics. Since this is just an alias for SubMsg::reply_never it is somewhat recommended to use the latter in order to make the behaviour more explicit in the caller code. But that’s up to you for now.

By default, the submessage’s gas limit will be unlimited. Use SubMsg::with_gas_limit to change it. Setting payload is not advised as this will never be used.

pub fn reply_on_success(msg: impl Into<CosmosMsg<T>>, id: u64) -> Self

Creates a SubMsg that will provide a reply with the given id if the message returns Ok.

By default, the submessage’s payload will be empty and the gas limit will be unlimited. Use SubMsg::with_payload and SubMsg::with_gas_limit to change those.

pub fn reply_on_error(msg: impl Into<CosmosMsg<T>>, id: u64) -> Self

Creates a SubMsg that will provide a reply with the given id if the message returns Err.

By default, the submessage’s payload will be empty and the gas limit will be unlimited. Use SubMsg::with_payload and SubMsg::with_gas_limit to change those.

pub fn reply_always(msg: impl Into<CosmosMsg<T>>, id: u64) -> Self

Create a SubMsg that will always provide a reply with the given id.

By default, the submessage’s payload will be empty and the gas limit will be unlimited. Use SubMsg::with_payload and SubMsg::with_gas_limit to change those.

pub fn reply_never(msg: impl Into<CosmosMsg<T>>) -> Self

Create a SubMsg that will never reply. This is equivalent to standard message semantics.

By default, the submessage’s gas limit will be unlimited. Use SubMsg::with_gas_limit to change it. Setting payload is not advised as this will never be used.

pub fn with_gas_limit(self, limit: u64) -> Self

Add a gas limit to the submessage. This gas limit measured in Cosmos SDK gas.

Examples

let sub_msg: SubMsg = SubMsg::reply_always(msg, 1234).with_gas_limit(60_000);
assert_eq!(sub_msg.id, 1234);
assert_eq!(sub_msg.gas_limit, Some(60_000));
assert_eq!(sub_msg.reply_on, ReplyOn::Always);

pub fn with_payload(self, payload: impl Into<Binary>) -> Self

Add a payload to the submessage.

Examples

let sub_msg: SubMsg = SubMsg::reply_always(msg, 1234)
    .with_payload(vec![1, 2, 3, 4]);
assert_eq!(sub_msg.id, 1234);
assert_eq!(sub_msg.payload, Binary::new(vec![1, 2, 3, 4]));
assert_eq!(sub_msg.reply_on, ReplyOn::Always);

Trait Implementations

impl<T: Clone> Clone for SubMsg<T>

fn clone(&self) -> SubMsg<T>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Debug> Debug for SubMsg<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de, T> Deserialize<'de> for SubMsg<T>

where T: Deserialize<'de>,

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<T: JsonSchema> JsonSchema for SubMsg<T>

fn schema_name() -> String

The name of the generated JSON Schema.

fn schema_id() -> Cow<'static, str>

Returns a string that uniquely identifies the schema produced by this type.

fn json_schema(gen: &mut SchemaGenerator) -> Schema

Generates a JSON Schema for this type.

fn is_referenceable() -> bool

Whether JSON Schemas generated for this type should be re-used where possible using the $ref keyword.

impl<T: PartialEq> PartialEq for SubMsg<T>

fn eq(&self, other: &SubMsg<T>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> Serialize for SubMsg<T>

where T: Serialize,

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl<T: Eq> Eq for SubMsg<T>

impl<T> StructuralPartialEq for SubMsg<T>