pub trait Api {
    fn addr_validate(&self, human: &str) -> StdResult<Addr>;
    fn addr_canonicalize(&self, human: &str) -> StdResult<CanonicalAddr>;
    fn addr_humanize(&self, canonical: &CanonicalAddr) -> StdResult<Addr>;
    fn secp256k1_verify(
        message_hash: &[u8],
        signature: &[u8],
        public_key: &[u8]
    ) -> Result<bool, VerificationError>; fn secp256k1_recover_pubkey(
        message_hash: &[u8],
        signature: &[u8],
        recovery_param: u8
    ) -> Result<Vec<u8>, RecoverPubkeyError>; fn ed25519_verify(
        message: &[u8],
        signature: &[u8],
        public_key: &[u8]
    ) -> Result<bool, VerificationError>; fn ed25519_batch_verify(
        messages: &[&[u8]],
        signatures: &[&[u8]],
        public_keys: &[&[u8]]
    ) -> Result<bool, VerificationError>; fn debug(&self, message: &str); }
Expand description

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.

This is a trait to allow mocks in the test code. Its members have a read-only reference to the Api instance to allow accessing configuration. Implementations must not have mutable state, such that an instance can freely be copied and shared between threads without affecting the behaviour. Given an Api instance, all members should return the same value when called with the same arguments. In particular this means the result must not depend in the state of the chain. If you need to access chaim state, you probably want to use the Querier. Side effects (such as logging) are allowed.

We can use feature flags to opt-in to non-essential methods for backwards compatibility in systems that don’t have them all.

Required Methods

Takes a human readable address and validates if it is valid. If it the validation succeeds, a Addr containing the same data as the input is returned.

This validation checks two things:

  1. The address is valid in the sense that it can be converted to a canonical representation by the backend.
  2. The address is normalized, i.e. humanize(canonicalize(input)) == input.

Check #2 is typically needed for upper/lower case representations of the same address that are both valid according to #1. This way we ensure uniqueness of the human readable address. Clients should perform the normalization before sending the addresses to the CosmWasm stack. But please note that the definition of normalized depends on the backend.

let input = "what-users-provide";
let validated: Addr = api.addr_validate(input).unwrap();
assert_eq!(validated, input);

Takes a human readable address and returns a canonical binary representation of it. This can be used when a compact fixed length representation is needed.

Takes a canonical address and returns a human readble address. This is the inverse of addr_canonicalize.

Emits a debugging message that is handled depending on the environment (typically printed to console or ignored). Those messages are not persisted to chain.