Crate cosmwasm_std 

CosmWasm is a smart contract platform for the Cosmos ecosystem. This crate provides the standard library for Wasm-based smart contracts on Cosmos blockchains.

For more information, see: https://cosmwasm.cosmos.network

Modules

storage_keys

This modules is very advanced and will not be used directly by the vast majority of users. We want to offer it to ensure a stable storage key composition system but don’t encourage contract devs to use it directly.

testing

Exposed for testing only Both unit tests and integration tests are compiled to native code, so everything in here does not need to compile to Wasm.

Macros

assert_approx_eq

Asserts that two expressions are approximately equal to each other.

ensure

Quick check for a guard. If the condition (first argument) is false, then return the second argument x wrapped in Err(x).

ensure_eq

Quick check for a guard. Like assert_eq!, but rather than panic, it returns the third argument x wrapped in Err(x).

ensure_ne

Quick check for a guard. Like assert_ne!, but rather than panic, it returns the third argument x wrapped in Err(x).

impl_mul_fraction

Structs

Addr

A human readable address.

AllDelegationsResponse

DelegationsResponse is data format returned from StakingRequest::AllDelegations query

AllDenomMetadataResponse

AllValidatorsResponse

The data format returned from StakingRequest::AllValidators query

AnyMsg

A message encoded the same way as a protobuf Any. This is the same structure as messages in TxBody from ADR-020

Attribute

An key value pair that is used in the context of event attributes in logs

BalanceResponse

Binary

Binary is a wrapper around Vec to add base64 de/serialization with serde. It also adds some helper methods to help encode inline.

BlockInfo

BondedDenomResponse

BondedDenomResponse is data format returned from StakingRequest::BondedDenom query

CanonicalAddr

A blockchain address in its binary form.

ChannelResponse

Checksum

A SHA-256 checksum of a Wasm blob, used to identify a Wasm code. This must remain stable since this checksum is stored in the blockchain state.

ChecksumError

CodeInfoResponse

The essential data from wasmd’s CodeInfo/CodeInfoResponse.

Coin

Coins

A collection of coins, similar to Cosmos SDK’s sdk.Coins struct.

ContractInfo

ContractInfoResponse

ConversionOverflowError

The error returned by TryFrom conversions that overflow, for example when converting from Uint256 to Uint128.

DecCoin

A coin type with decimal amount. Modeled after the Cosmos SDK’s DecCoin type. However, in contrast to the Cosmos SDK the amount string MUST always have a dot at JSON level, see https://github.com/cosmos/cosmos-sdk/issues/10863. Also if Cosmos SDK chooses to migrate away from fixed point decimals (as shown [here](https://github.com/cosmos/cosmos-sdk/blob/v0.47.4/x/group/internal/math/dec.go#L13-L21 and discussed here), wasmd needs to truncate the decimal places to 18.

Decimal

A fixed-point decimal value with 18 fractional digits, i.e. Decimal(1_000_000_000_000_000_000) == 1.0

Decimal256

A fixed-point decimal value with 18 fractional digits, i.e. Decimal256(1_000_000_000_000_000_000) == 1.0

Decimal256RangeExceeded

DecimalRangeExceeded

Delegation

Delegation is basic (cheap to query) data about a delegation.

DelegationResponse

DelegationResponse is data format returned from StakingRequest::Delegation query

DelegationRewardsResponse

See https://github.com/cosmos/cosmos-sdk/blob/c74e2887b0b73e81d48c2f33e6b1020090089ee0/proto/cosmos/distribution/v1beta1/query.proto#L169-L178

DelegationTotalRewardsResponse

See https://github.com/cosmos/cosmos-sdk/blob/c74e2887b0b73e81d48c2f33e6b1020090089ee0/proto/cosmos/distribution/v1beta1/query.proto#L189-L200

DelegatorReward

DelegatorValidatorsResponse

See https://github.com/cosmos/cosmos-sdk/blob/b0acf60e6c39f7ab023841841fc0b751a12c13ff/proto/cosmos/distribution/v1beta1/query.proto#L212-L220

DelegatorWithdrawAddressResponse

See https://github.com/cosmos/cosmos-sdk/blob/c74e2887b0b73e81d48c2f33e6b1020090089ee0/proto/cosmos/distribution/v1beta1/query.proto#L232-L240

DenomMetadata

Replicates the cosmos-sdk bank module Metadata type

DenomMetadataResponse

DenomUnit

Replicates the cosmos-sdk bank module DenomUnit type

Deps

DepsMut

DivideByZeroError

Empty

An empty struct that serves as a placeholder in different places, such as contracts that don’t set a custom message.

Env

Event

A full Cosmos SDK event.

FullDelegation

FullDelegation is all the info on the delegation, some (like accumulated_reward and can_redelegate) is expensive to query.

GrpcQuery

Queries the chain using a grpc query. This allows to query information that is not exposed in our API. The chain needs to allowlist the supported queries. The drawback of this query is that you have to handle the protobuf encoding and decoding yourself.

HexBinary

This is a wrapper around Vec to add hex de/serialization with serde. It also adds some helper methods to help encode inline.

Ibc2PacketAckMsg

Message sent to the IBCv2 app upon receiving an acknowledgement packet

Ibc2PacketReceiveMsg

IBC2PacketReceiveMsg represents a message received via the IBC2 protocol. The message that is passed into ibc2_packet_receive. It contains the payload data along with metadata about the source and relayer.

Ibc2PacketSendMsg

Ibc2PacketSendMsg represents a payload sent event in the IBC2 protocol. Since sending IBCv2 packet is permissionless, the IBC protocol introduces an extra entry point, in which the application can verify the message sent from a port ID belonging to the contract.

Ibc2PacketTimeoutMsg

IBC2PacketTimeoutMsg represents a timeout event for a packet that was not successfully delivered within the expected timeframe in the IBC2 protocol. It includes details about the source and destination clients, and the sequence number of the timed-out packet.

Ibc2Payload

Payload value should be encoded in a format defined by the channel version, and the module on the other side should know how to parse this.

Ibc3ChannelOpenResponse

IbcAckCallbackMsg

IbcAcknowledgement

IbcBasicResponse

This is the return value for the majority of the ibc handlers. That are able to dispatch messages / events on their own, but have no meaningful return value to the calling code.

IbcCallbackRequest

This is just a type representing the data that has to be sent with the IBC message to receive callbacks. It should be serialized and sent with the IBC message. The specific field and format to send it in can vary depending on the IBC message, but is usually the memo field by convention.

IbcChannel

IbcChannel defines all information on a channel. This is generally used in the hand-shake process, but can be queried directly.

IbcDestinationCallbackMsg

The message type of the IBC destination callback.

IbcDstCallback

IbcEndpoint

IbcPacket

IbcPacketAckMsg

The message that is passed into ibc_packet_ack

IbcPacketReceiveMsg

The message that is passed into ibc_packet_receive

IbcPacketTimeoutMsg

The message that is passed into ibc_packet_timeout

IbcReceiveResponse

This defines the return value on packet response processing. This “success” case should be returned even in application-level errors, Where the acknowledgement bytes contain an encoded error message to be returned to the calling chain. (Returning ContractResult::Err will abort processing of this packet and not inform the calling chain).

IbcSrcCallback

IbcTimeout

In IBC each package must set at least one type of timeout: the timestamp or the block height. Using this rather complex enum instead of two timeout fields we ensure that at least one timeout is set.

IbcTimeoutBlock

IBCTimeoutHeight Height is a monotonically increasing data type that can be compared against another Height for the purposes of updating and freezing clients. Ordering is (revision_number, timeout_height)

IbcTimeoutCallbackMsg

IbcTransferCallback

Int64

An implementation of i64 that is using strings for JSON encoding/decoding, such that the full i64 range can be used for clients that convert JSON numbers to floats, like JavaScript and jq.

Int128

An implementation of i128 that is using strings for JSON encoding/decoding, such that the full i128 range can be used for clients that convert JSON numbers to floats, like JavaScript and jq.

Int256

An implementation of i256 that is using strings for JSON encoding/decoding, such that the full i256 range can be used for clients that convert JSON numbers to floats, like JavaScript and jq.

Int512

An implementation of i512 that is using strings for JSON encoding/decoding, such that the full i512 range can be used for clients that convert JSON numbers to floats, like JavaScript and jq.

MessageInfo

Additional information from MsgInstantiateContract and MsgExecuteContract, which is passed along with the contract execution message into the instantiate and execute entry points.

MigrateInfo

The structure contains additional information related to the contract’s migration procedure - the sender address and the contract’s migrate version currently stored on the blockchain. The old_migrate_version is optional, since there is no guarantee that the currently stored contract’s binary contains that information.

MsgResponse

OverflowError

OwnedDeps

Holds all external dependencies of the contract. Designed to allow easy dependency injection at runtime. This cannot be copied or cloned since it would behave differently for mock storages and a bridge storage in the VM.

PageRequest

Simplified version of the PageRequest type for pagination from the cosmos-sdk

PortIdResponse

QuerierWrapper

RawRangeResponse

Reply

The result object returned to reply. We always get the ID from the submessage back and then must handle success and error cases ourselves.

Response

A response of a contract entry point, such as instantiate, execute or migrate.

RoundDownOverflowError

RoundUpOverflowError

SignedDecimal

A signed fixed-point decimal value with 18 fractional digits, i.e. SignedDecimal(1_000_000_000_000_000_000) == 1.0

SignedDecimal256

A signed fixed-point decimal value with 18 fractional digits, i.e. SignedDecimal256(1_000_000_000_000_000_000) == 1.0

SignedDecimal256RangeExceeded

SignedDecimalRangeExceeded

StdError

Structured error type for init, execute and query.

SubMsg

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.

SubMsgResponse

The information we get back from a successful sub message execution

SupplyResponse

Timestamp

A point in time in nanosecond precision.

TransactionInfo

TransferMsgBuilder

Uint64

A thin wrapper around u64 that is using strings for JSON encoding/decoding, such that the full u64 range can be used for clients that convert JSON numbers to floats, like JavaScript and jq.

Uint128

A thin wrapper around u128 that is using strings for JSON encoding/decoding, such that the full u128 range can be used for clients that convert JSON numbers to floats, like JavaScript and jq.

Uint256

An implementation of u256 that is using strings for JSON encoding/decoding, such that the full u256 range can be used for clients that convert JSON numbers to floats, like JavaScript and jq.

Uint512

An implementation of u512 that is using strings for JSON encoding/decoding, such that the full u512 range can be used for clients that convert JSON numbers to floats, like JavaScript and jq.

Validator

Instances are created in the querier.

ValidatorMetadata

Instances are created in the querier.

ValidatorResponse

The data format returned from StakingRequest::Validator query

WeightedVoteOption

Enums

AggregationError

BankMsg

The message types of the bank module.

BankQuery

CheckedFromRatioError

CheckedMultiplyFractionError

CheckedMultiplyRatioError

CoinFromStrError

CoinsError

ContractResult

This is the final result type that is created and serialized in a contract for every init/execute/migrate call. The VM then deserializes this type to distinguish between successful and failed executions.

CosmosMsg

DistributionMsg

The message types of the distribution module.

DistributionQuery

DivisionError

GovMsg

This message type allows the contract interact with the x/gov module in order to cast votes.

HashFunction

Ibc2Msg

These are messages in the IBC lifecycle using the new Ibc2 approach. Only usable by Ibc2-enabled contracts

IbcChannelCloseMsg

The message that is passed into ibc_channel_close

IbcChannelConnectMsg

The message that is passed into ibc_channel_connect

IbcChannelOpenMsg

The message that is passed into ibc_channel_open

IbcMsg

These are messages in the IBC lifecycle. Only usable by IBC-enabled contracts (contracts that directly speak the IBC protocol via 6 entry points)

IbcOrder

IbcOrder defines if a channel is ORDERED or UNORDERED Values come from https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/ibc/core/channel/v1/channel.proto#L69-L80 Naming comes from the protobuf files and go translations.

IbcQuery

These are queries to the various IBC modules to see the state of the contract’s IBC connection. Most of these will return errors if the contract is not “ibc enabled”.

IbcSourceCallbackMsg

The type of IBC source callback that is being called.

Instantiate2AddressError

Never

Never can never be instantiated. This can be used in places where we want to ensure that no error is returned, such as the ibc_packet_receive entry point.

Order

OverflowOperation

PairingEqualityError

QueryRequest

RecoverPubkeyError

ReplyOn

Use this to define when the contract gets a response callback. If you only need it for errors or success you can select just those in order to save gas.

StakingMsg

The message types of the staking module.

StakingQuery

StdAck

This is a standard IBC acknowledgement type. IBC application are free to use any acknowledgement format they want. However, for compatibility purposes it is recommended to use this.

StdErrorKind

SubMsgResult

This is the result type that is returned from a sub message execution.

SystemError

SystemError is used for errors inside the VM and is API friendly (i.e. serializable).

SystemResult

This is the outer result type returned by a querier to the contract.

VerificationError

VoteOption

WasmMsg

The message types of the wasm module.

WasmQuery

Constants

BLS12_381_G1_GENERATOR

A generator in G1 (in compressed serialization).

BLS12_381_G2_GENERATOR

A generator in G2 (in compressed serialization).

Traits

Api

Api are callbacks to system functions implemented outside of the wasm modules. Currently it just supports address conversion but we could add eg. crypto functions here.

CustomMsg

A trait for custom message types which are embedded in CosmosMsg::Custom(..). Those are messages that the contract and the chain need to agree on in advance as the chain must be able to deserialize and execute them.

CustomQuery

A trait that is required to avoid conflicts with other query types like BankQuery and WasmQuery in generic implementations. You need to implement it in your custom query type.

Fraction

A fraction p/q with integers p and q.

Isqrt

A trait for calculating the integer square root.

Querier

StdResultExt

Storage

Storage provides read and write access to a persistent storage. If you only want to provide read access, provide &Storage

Functions

attr

Creates a new Attribute. Attribute::new is an alias for this.

coin

A shorthand constructor for Coin

coins

A shortcut constructor for a set of one denomination of coins

from_base64

Deserialize a bag of bytes from Base64 into a vector of bytes

from_hex

Decode a bag of bytes from hex into a vector of bytes

from_json

Deserializes the given JSON bytes to a data structure.

from_msgpack

Deserializes the given MessagePack bytes to a data structure.

has_coins

has_coins returns true if the list of coins has at least the required amount

instantiate2_address

Creates a contract address using the predictable address format introduced with wasmd 0.29. When using instantiate2, this is a way to precompute the address. When using instantiate, the contract address will use a different algorithm and cannot be pre-computed as it contains inputs from the chain’s state at the time of message execution.

to_base64

Encode a bag of bytes into the Base64 format

to_hex

Encode a bag of bytes into the hex format

to_json_binary

Serializes the given data structure as JSON bytes.

to_json_string

Serializes the given data structure as a JSON string.

to_json_vec

Serializes the given data structure as a JSON byte vector.

to_msgpack_binary

Serializes the given data structure as MessagePack bytes.

to_msgpack_vec

Serializes the given data structure as a MessagePack byte vector.

wasm_execute

Shortcut helper as the construction of WasmMsg::Execute can be quite verbose in contract code

wasm_instantiate

Shortcut helper as the construction of WasmMsg::Instantiate can be quite verbose in contract code.

Type Aliases

IbcChannelOpenResponse

This serializes either as null or a JSON object. Within the response, a channel version can be specified. If null is provided instead, the incoming channel version is accepted.

QuerierResult

A short-hand alias for the two-level query result (1. accessing the contract, 2. executing query in the contract)

QueryResponse

RawRangeEntry

Record

A record of a key-value storage that is created through an iterator API. The first element (key) is always raw binary data. The second element (value) is binary by default but can be changed to a custom type. This allows contracts to reuse the type when deserializing database records.

StdResult

The return type for init, execute and query. Since the error type cannot be serialized to JSON, this is only available within the contract and its unit tests.

Attribute Macros

entry_point

This attribute macro generates the boilerplate required to call into the contract-specific logic from the entry-points to the Wasm module.