Crate cosmwasm_std
SourceModules§
- 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 inErr(x)
. - ensure_
eq - Quick check for a guard. Like
assert_eq!
, but rather than panic, it returns the third argumentx
wrapped inErr(x)
. - ensure_
ne - Quick check for a guard. Like
assert_ne!
, but rather than panic, it returns the third argumentx
wrapped in Err(x). - impl_
mul_ fraction
Structs§
- Addr
- A human readable address.
- AllDelegations
Response - DelegationsResponse is data format returned from StakingRequest::AllDelegations query
- AllDenom
Metadata Response - AllValidators
Response - 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
- Balance
Response - Binary
- Binary is a wrapper around Vec
to add base64 de/serialization with serde. It also adds some helper methods to help encode inline. - Block
Info - Bonded
Denom Response - BondedDenomResponse is data format returned from StakingRequest::BondedDenom query
- Canonical
Addr - A blockchain address in its binary form.
- Channel
Response - 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.
- Checksum
Error - Code
Info Response - The essential data from wasmd’s CodeInfo/CodeInfoResponse.
- Coin
- Coins
- A collection of coins, similar to Cosmos SDK’s
sdk.Coins
struct. - Contract
Info - Contract
Info Response - Conversion
Overflow Error - The error returned by
TryFrom
conversions that overflow, for example when converting fromUint256
toUint128
. - 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
- Decimal256
Range Exceeded - Decimal
Range Exceeded - Delegation
- Delegation is basic (cheap to query) data about a delegation.
- Delegation
Response - DelegationResponse is data format returned from StakingRequest::Delegation query
- Delegation
Rewards Response - See https://github.com/cosmos/cosmos-sdk/blob/c74e2887b0b73e81d48c2f33e6b1020090089ee0/proto/cosmos/distribution/v1beta1/query.proto#L169-L178
- Delegation
Total Rewards Response - See https://github.com/cosmos/cosmos-sdk/blob/c74e2887b0b73e81d48c2f33e6b1020090089ee0/proto/cosmos/distribution/v1beta1/query.proto#L189-L200
- Delegator
Reward - Delegator
Validators Response - See https://github.com/cosmos/cosmos-sdk/blob/b0acf60e6c39f7ab023841841fc0b751a12c13ff/proto/cosmos/distribution/v1beta1/query.proto#L212-L220
- Delegator
Withdraw Address Response - See https://github.com/cosmos/cosmos-sdk/blob/c74e2887b0b73e81d48c2f33e6b1020090089ee0/proto/cosmos/distribution/v1beta1/query.proto#L232-L240
- Denom
Metadata - Replicates the cosmos-sdk bank module Metadata type
- Denom
Metadata Response - Denom
Unit - Replicates the cosmos-sdk bank module DenomUnit type
- Deps
- DepsMut
- Divide
ByZero Error - 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.
- Full
Delegation - FullDelegation is all the info on the delegation, some (like accumulated_reward and can_redelegate) is expensive to query.
- Grpc
Query - 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. - Ibc2
Packet AckMsg - Message sent to the IBCv2 app upon receiving an acknowledgement packet
- Ibc2
Packet Receive Msg - 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. - Ibc2
Packet Send Msg - 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.
- Ibc2
Packet Timeout Msg - 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.
- Ibc2
Payload - 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.
- Ibc3
Channel Open Response - IbcAck
Callback Msg - IbcAcknowledgement
- IbcBasic
Response - 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.
- IbcCallback
Request - 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.
- IbcDestination
Callback Msg - The message type of the IBC destination callback.
- IbcDst
Callback - IbcEndpoint
- IbcPacket
- IbcPacket
AckMsg - The message that is passed into
ibc_packet_ack
- IbcPacket
Receive Msg - The message that is passed into
ibc_packet_receive
- IbcPacket
Timeout Msg - The message that is passed into
ibc_packet_timeout
- IbcReceive
Response - 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).
- IbcSrc
Callback - 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.
- IbcTimeout
Block - 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)
- IbcTimeout
Callback Msg - IbcTransfer
Callback - 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.
- Message
Info - Additional information from MsgInstantiateContract and MsgExecuteContract, which is passed
along with the contract execution message into the
instantiate
andexecute
entry points. - Migrate
Info - 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
- Overflow
Error - Owned
Deps - 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.
- Page
Request - Simplified version of the PageRequest type for pagination from the cosmos-sdk
- Port
IdResponse - Querier
Wrapper - RawRange
Response - 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
ormigrate
. - Round
Down Overflow Error - Round
UpOverflow Error - Signed
Decimal - A signed fixed-point decimal value with 18 fractional digits, i.e. SignedDecimal(1_000_000_000_000_000_000) == 1.0
- Signed
Decimal256 - A signed fixed-point decimal value with 18 fractional digits, i.e. SignedDecimal256(1_000_000_000_000_000_000) == 1.0
- Signed
Decimal256 Range Exceeded - Signed
Decimal Range Exceeded - StdError
- Structured error type for init, execute and query.
- SubMsg
- A submessage that will guarantee a
reply
call on success or error, depending on thereply_on
setting. If you do not need to process the result, use regular messages instead. - SubMsg
Response - The information we get back from a successful sub message execution
- Supply
Response - Timestamp
- A point in time in nanosecond precision.
- Transaction
Info - Transfer
MsgBuilder - 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.
- Validator
Metadata - Instances are created in the querier.
- Validator
Response - The data format returned from StakingRequest::Validator query
- Weighted
Vote Option
Enums§
- Aggregation
Error - BankMsg
- The message types of the bank module.
- Bank
Query - Checked
From Ratio Error - Checked
Multiply Fraction Error - Checked
Multiply Ratio Error - Coin
From StrError - Coins
Error - Contract
Result - 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.
- Cosmos
Msg - Distribution
Msg - The message types of the distribution module.
- Distribution
Query - Division
Error - GovMsg
- This message type allows the contract interact with the x/gov module in order to cast votes.
- Hash
Function - Ibc2Msg
- These are messages in the IBC lifecycle using the new Ibc2 approach. Only usable by Ibc2-enabled contracts
- IbcChannel
Close Msg - The message that is passed into
ibc_channel_close
- IbcChannel
Connect Msg - The message that is passed into
ibc_channel_connect
- IbcChannel
Open Msg - 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”.
- IbcSource
Callback Msg - The type of IBC source callback that is being called.
- Instantiate2
Address Error - 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
- Overflow
Operation - Pairing
Equality Error - Query
Request - Recover
Pubkey Error - 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.
- Staking
Msg - The message types of the staking module.
- Staking
Query - 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.
- StdError
Kind - SubMsg
Result - This is the result type that is returned from a sub message execution.
- System
Error - SystemError is used for errors inside the VM and is API friendly (i.e. serializable).
- System
Result - This is the outer result type returned by a querier to the contract.
- Verification
Error - Vote
Option - WasmMsg
- The message types of the wasm module.
- Wasm
Query
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.
- Custom
Msg - 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. - Custom
Query - 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 integersp
andq
. - Isqrt
- A trait for calculating the integer square root.
- Querier
- StdResult
Ext - 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§
- IbcChannel
Open Response - This serializes either as
null
or a JSON object. Within the response, a channel version can be specified. Ifnull
is provided instead, the incoming channel version is accepted. - Querier
Result - A short-hand alias for the two-level query result (1. accessing the contract, 2. executing query in the contract)
- Query
Response - RawRange
Entry - 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.