cosmwasm_std/
lib.rs

1//! CosmWasm is a smart contract platform for the Cosmos ecosystem.
2//! This crate provides the standard library for Wasm-based smart contracts on Cosmos blockchains.
3//!
4//! For more information, see: <https://cosmwasm.cosmos.network>
5
6#[cfg(not(feature = "std"))]
7core::compile_error!(
8    r#"Please enable `cosmwasm-std`'s `std` feature, as we might move existing functionality to that feature in the future.
9Builds without the std feature are currently not expected to work. If you need no_std support see #1484.
10"#
11);
12
13#[macro_use]
14extern crate alloc;
15
16// Exposed on all platforms
17
18mod __internal;
19mod addresses;
20mod assertions;
21mod binary;
22mod checksum;
23mod coin;
24mod coins;
25mod conversion;
26mod deps;
27mod encoding;
28mod errors;
29mod forward_ref;
30mod hex_binary;
31mod ibc;
32mod ibc2;
33mod import_helpers;
34#[cfg(feature = "iterator")]
35mod iterator;
36mod math;
37mod metadata;
38mod msgpack;
39mod never;
40mod pagination;
41mod query;
42mod results;
43mod sections;
44mod serde;
45mod stdack;
46mod timestamp;
47mod traits;
48mod types;
49mod utils;
50
51/// This module is to simplify no_std imports
52pub(crate) mod prelude;
53
54/// This modules is very advanced and will not be used directly by the vast majority of users.
55/// We want to offer it to ensure a stable storage key composition system but don't encourage
56/// contract devs to use it directly.
57pub mod storage_keys;
58
59pub use crate::addresses::{
60    instantiate2_address, instantiate2_address_impl, Addr, CanonicalAddr, Instantiate2AddressError,
61};
62pub use crate::binary::Binary;
63pub use crate::checksum::{Checksum, ChecksumError};
64pub use crate::coin::{coin, coins, has_coins, Coin};
65pub use crate::coins::Coins;
66pub use crate::deps::{Deps, DepsMut, OwnedDeps};
67pub use crate::encoding::{from_base64, from_hex, to_base64, to_hex};
68pub use crate::errors::{
69    AggregationError, CheckedFromRatioError, CheckedMultiplyFractionError,
70    CheckedMultiplyRatioError, CoinFromStrError, CoinsError, ConversionOverflowError,
71    DivideByZeroError, DivisionError, ErrorKind as StdErrorKind, OverflowError, OverflowOperation,
72    PairingEqualityError, RecoverPubkeyError, RoundDownOverflowError, RoundUpOverflowError,
73    StdError, StdResult, StdResultExt, SystemError, VerificationError,
74};
75pub use crate::hex_binary::HexBinary;
76pub use crate::ibc::IbcChannelOpenResponse;
77pub use crate::ibc::{
78    Ibc3ChannelOpenResponse, IbcAckCallbackMsg, IbcAcknowledgement, IbcBasicResponse,
79    IbcCallbackRequest, IbcChannel, IbcChannelCloseMsg, IbcChannelConnectMsg, IbcChannelOpenMsg,
80    IbcDestinationCallbackMsg, IbcDstCallback, IbcEndpoint, IbcMsg, IbcOrder, IbcPacket,
81    IbcPacketAckMsg, IbcPacketReceiveMsg, IbcPacketTimeoutMsg, IbcReceiveResponse,
82    IbcSourceCallbackMsg, IbcSrcCallback, IbcTimeout, IbcTimeoutBlock, IbcTimeoutCallbackMsg,
83    IbcTransferCallback, TransferMsgBuilder,
84};
85pub use crate::ibc2::{
86    Ibc2Msg, Ibc2PacketAckMsg, Ibc2PacketReceiveMsg, Ibc2PacketSendMsg, Ibc2PacketTimeoutMsg,
87    Ibc2Payload,
88};
89#[cfg(feature = "iterator")]
90pub use crate::iterator::{Order, Record};
91pub use crate::math::{
92    Decimal, Decimal256, Decimal256RangeExceeded, DecimalRangeExceeded, Fraction, Int128, Int256,
93    Int512, Int64, Isqrt, SignedDecimal, SignedDecimal256, SignedDecimal256RangeExceeded,
94    SignedDecimalRangeExceeded, Uint128, Uint256, Uint512, Uint64,
95};
96pub use crate::metadata::{DenomMetadata, DenomUnit};
97pub use crate::msgpack::{from_msgpack, to_msgpack_binary, to_msgpack_vec};
98pub use crate::never::Never;
99pub use crate::pagination::PageRequest;
100pub use crate::query::{
101    AllDelegationsResponse, AllDenomMetadataResponse, AllValidatorsResponse, BalanceResponse,
102    BankQuery, BondedDenomResponse, ChannelResponse, CodeInfoResponse, ContractInfoResponse,
103    CustomQuery, DecCoin, Delegation, DelegationResponse, DelegationRewardsResponse,
104    DelegationTotalRewardsResponse, DelegatorReward, DelegatorValidatorsResponse,
105    DelegatorWithdrawAddressResponse, DenomMetadataResponse, DistributionQuery, FullDelegation,
106    GrpcQuery, IbcQuery, PortIdResponse, QueryRequest, RawRangeEntry, RawRangeResponse,
107    StakingQuery, SupplyResponse, Validator, ValidatorMetadata, ValidatorResponse, WasmQuery,
108};
109
110#[cfg(all(feature = "stargate", feature = "cosmwasm_1_2"))]
111pub use crate::results::WeightedVoteOption;
112pub use crate::results::{
113    attr, wasm_execute, wasm_instantiate, AnyMsg, Attribute, BankMsg, ContractResult, CosmosMsg,
114    CustomMsg, Empty, Event, MsgResponse, QueryResponse, Reply, ReplyOn, Response, SubMsg,
115    SubMsgResponse, SubMsgResult, SystemResult, WasmMsg,
116};
117#[cfg(feature = "staking")]
118pub use crate::results::{DistributionMsg, StakingMsg};
119#[cfg(feature = "stargate")]
120pub use crate::results::{GovMsg, VoteOption};
121pub use crate::serde::{from_json, to_json_binary, to_json_string, to_json_vec};
122pub use crate::stdack::StdAck;
123pub use crate::timestamp::Timestamp;
124pub use crate::traits::{Api, HashFunction, Querier, QuerierResult, QuerierWrapper, Storage};
125pub use crate::types::{BlockInfo, ContractInfo, Env, MessageInfo, MigrateInfo, TransactionInfo};
126
127//
128// Exports
129//
130
131#[cfg(all(feature = "exports", target_arch = "wasm32"))]
132mod exports;
133
134#[cfg(all(feature = "exports", target_arch = "wasm32", feature = "cosmwasm_2_2"))]
135pub use crate::exports::do_migrate_with_info;
136#[cfg(all(feature = "exports", target_arch = "wasm32"))]
137pub use crate::exports::{
138    do_execute, do_ibc_destination_callback, do_ibc_source_callback, do_instantiate, do_migrate,
139    do_query, do_reply, do_sudo,
140};
141#[cfg(all(feature = "exports", target_arch = "wasm32", feature = "ibc2"))]
142pub use crate::exports::{
143    do_ibc2_packet_ack, do_ibc2_packet_receive, do_ibc2_packet_send, do_ibc2_packet_timeout,
144};
145#[cfg(all(feature = "exports", target_arch = "wasm32", feature = "stargate"))]
146pub use crate::exports::{
147    do_ibc_channel_close, do_ibc_channel_connect, do_ibc_channel_open, do_ibc_packet_ack,
148    do_ibc_packet_receive, do_ibc_packet_timeout,
149};
150
151/// Exposed for testing only
152/// Both unit tests and integration tests are compiled to native code, so everything in here does not need to compile to Wasm.
153#[cfg(not(target_arch = "wasm32"))]
154pub mod testing;
155
156pub use cosmwasm_core::{BLS12_381_G1_GENERATOR, BLS12_381_G2_GENERATOR};
157
158/// This attribute macro generates the boilerplate required to call into the
159/// contract-specific logic from the entry-points to the Wasm module.
160///
161/// It should be added to the contract's init, handle, migrate and query implementations
162/// like this:
163/// ```
164/// # use cosmwasm_std::{
165/// #     Storage, Api, Querier, DepsMut, Deps, entry_point, Env, StdError, MessageInfo,
166/// #     Response, QueryResponse,
167/// # };
168/// #
169/// # type InstantiateMsg = ();
170/// # type ExecuteMsg = ();
171/// # type QueryMsg = ();
172///
173/// #[entry_point]
174/// pub fn instantiate(
175///     deps: DepsMut,
176///     env: Env,
177///     info: MessageInfo,
178///     msg: InstantiateMsg,
179/// ) -> Result<Response, StdError> {
180/// #   Ok(Default::default())
181/// }
182///
183/// #[entry_point]
184/// pub fn execute(
185///     deps: DepsMut,
186///     env: Env,
187///     info: MessageInfo,
188///     msg: ExecuteMsg,
189/// ) -> Result<Response, StdError> {
190/// #   Ok(Default::default())
191/// }
192///
193/// #[entry_point]
194/// pub fn query(
195///     deps: Deps,
196///     env: Env,
197///     msg: QueryMsg,
198/// ) -> Result<QueryResponse, StdError> {
199/// #   Ok(Default::default())
200/// }
201/// ```
202///
203/// where `InstantiateMsg`, `ExecuteMsg`, and `QueryMsg` are contract defined
204/// types that implement `DeserializeOwned`.
205///
206/// ## Set the version of the state of your contract
207///
208/// The VM will use this as a hint whether it needs to run the migrate function of your contract or not.
209///
210/// ```
211/// # use cosmwasm_std::{
212/// #     DepsMut, entry_point, Env, MigrateInfo,
213/// #     Response, StdResult,
214/// # };
215/// #
216/// # type MigrateMsg = ();
217/// #[entry_point]
218/// #[migrate_version(2)]
219/// pub fn migrate(deps: DepsMut, env: Env, msg: MigrateMsg, migrate_info: MigrateInfo) -> StdResult<Response> {
220///     todo!();
221/// }
222/// ```
223///
224/// It is also possible to assign the migrate version number to
225/// a given constant name:
226///
227/// ```
228/// # use cosmwasm_std::{
229/// #     DepsMut, entry_point, Env, MigrateInfo,
230/// #     Response, StdResult,
231/// # };
232/// #
233/// # type MigrateMsg = ();
234/// const CONTRACT_VERSION: u64 = 66;
235///
236/// #[entry_point]
237/// #[migrate_version(CONTRACT_VERSION)]
238/// pub fn migrate(deps: DepsMut, env: Env, msg: MigrateMsg, migrate_info: MigrateInfo) -> StdResult<Response> {
239///     todo!();
240/// }
241/// ```
242pub use cosmwasm_derive::entry_point;