Trait secret_cosmwasm_std::Api

pub trait Api {
    // Required methods
    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(
        &self,
        message_hash: &[u8],
        signature: &[u8],
        public_key: &[u8]
    ) -> Result<bool, VerificationError>;
    fn secp256k1_recover_pubkey(
        &self,
        message_hash: &[u8],
        signature: &[u8],
        recovery_param: u8
    ) -> Result<Vec<u8>, RecoverPubkeyError>;
    fn ed25519_verify(
        &self,
        message: &[u8],
        signature: &[u8],
        public_key: &[u8]
    ) -> Result<bool, VerificationError>;
    fn ed25519_batch_verify(
        &self,
        messages: &[&[u8]],
        signatures: &[&[u8]],
        public_keys: &[&[u8]]
    ) -> Result<bool, VerificationError>;
    fn debug(&self, message: &str);
    fn secp256k1_sign(
        &self,
        message: &[u8],
        private_key: &[u8]
    ) -> Result<Vec<u8>, SigningError>;
    fn ed25519_sign(
        &self,
        message: &[u8],
        private_key: &[u8]
    ) -> Result<Vec<u8>, SigningError>;
    fn check_gas(&self) -> StdResult<u64>;
    fn gas_evaporate(&self, evaporate: u32) -> StdResult<()>;
}

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

fn addr_validate(&self, human: &str) -> StdResult<Addr>

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.

Examples

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

fn addr_canonicalize(&self, human: &str) -> StdResult<CanonicalAddr>

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

Please note that the length of the resulting address is defined by the chain and can vary from address to address. On Cosmos chains 20 and 32 bytes are typically used. But that might change. So your contract should not make assumptions on the size.

fn addr_humanize(&self, canonical: &CanonicalAddr) -> StdResult<Addr>

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

fn secp256k1_verify( &self, message_hash: &[u8], signature: &[u8], public_key: &[u8] ) -> Result<bool, VerificationError>

ECDSA secp256k1 signature verification.

This function verifies message hashes (hashed unsing SHA-256) against a signature, with the public key of the signer, using the secp256k1 elliptic curve digital signature parametrization / algorithm.

The signature and public key are in “Cosmos” format:

• signature: Serialized “compact” signature (64 bytes).
• public key: Serialized according to SEC 2

fn secp256k1_recover_pubkey( &self, message_hash: &[u8], signature: &[u8], recovery_param: u8 ) -> Result<Vec<u8>, RecoverPubkeyError>

Recovers a public key from a message hash and a signature.

This is required when working with Ethereum where public keys are not stored on chain directly.

recovery_param must be 0 or 1. The values 2 and 3 are unsupported by this implementation, which is the same restriction as Ethereum has (https://github.com/ethereum/go-ethereum/blob/v1.9.25/internal/ethapi/api.go#L466-L469). All other values are invalid.

Returns the recovered pubkey in compressed form, which can be used in secp256k1_verify directly.

fn ed25519_verify( &self, message: &[u8], signature: &[u8], public_key: &[u8] ) -> Result<bool, VerificationError>

EdDSA ed25519 signature verification.

This function verifies messages against a signature, with the public key of the signer, using the ed25519 elliptic curve digital signature parametrization / algorithm.

The maximum currently supported message length is 4096 bytes. The signature and public key are in Tendermint format:

• signature: raw ED25519 signature (64 bytes).
• public key: raw ED25519 public key (32 bytes).

fn ed25519_batch_verify( &self, messages: &[&[u8]], signatures: &[&[u8]], public_keys: &[&[u8]] ) -> Result<bool, VerificationError>

Performs batch Ed25519 signature verification.

Batch verification asks whether all signatures in some set are valid, rather than asking whether each of them is valid. This allows sharing computations among all signature verifications, performing less work overall, at the cost of higher latency (the entire batch must complete), complexity of caller code (which must assemble a batch of signatures across work-items), and loss of the ability to easily pinpoint failing signatures.

This batch verification implementation is adaptive, in the sense that it detects multiple signatures created with the same verification key, and automatically coalesces terms in the final verification equation.

In the limiting case where all signatures in the batch are made with the same verification key, coalesced batch verification runs twice as fast as ordinary batch verification.

Three Variants are suppported in the input for convenience:

• Equal number of messages, signatures, and public keys: Standard, generic functionality.
• One message, and an equal number of signatures and public keys: Multiple digital signature (multisig) verification of a single message.
• One public key, and an equal number of messages and signatures: Verification of multiple messages, all signed with the same private key.

Any other variants of input vectors result in an error.

Notes:

• The “one-message, with zero signatures and zero public keys” case, is considered the empty case.
• The “one-public key, with zero messages and zero signatures” case, is considered the empty case.
• The empty case (no messages, no signatures and no public keys) returns true.

fn debug(&self, message: &str)

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

fn secp256k1_sign( &self, message: &[u8], private_key: &[u8] ) -> Result<Vec<u8>, SigningError>

ECDSA secp256k1 signing.

This function signs a message with a private key using the secp256k1 elliptic curve digital signature parametrization / algorithm.

• message: Arbitrary message.
• private key: Raw secp256k1 private key (32 bytes)

fn ed25519_sign( &self, message: &[u8], private_key: &[u8] ) -> Result<Vec<u8>, SigningError>

EdDSA Ed25519 signing.

This function signs a message with a private key using the ed25519 elliptic curve digital signature parametrization / algorithm.

• message: Arbitrary message.
• private key: Raw ED25519 private key (32 bytes)

fn check_gas(&self) -> StdResult<u64>

Check Gas.

This function will return the amount of gas currently used by the contract.

fn gas_evaporate(&self, evaporate: u32) -> StdResult<()>

Gas evaporation.

This function will burn a evaporate a precise and reproducible amount of sdk gas.

• evaporate: Amount of SDK gas to evaporate.

Implementors

impl Api for MockApi