What Is Instantiation?

The Instantiate function is the function that will run once (and only once) immediately upon initializing your smart contract after uploading it to the network. It is meant to set up the smart contract with all vital code that must be run first before any users have the ability to execute the contract. For those familiar with a solidity constructor on Ethereum, Instantiate serves the exact same purpose.

If you have any vital info to save to the state such as Config parameters or an admin/operator address to name a few options, those should probably be specified here. In addition, if your contract requires entropy for randomization or needs to register to receive a SNIP-20 token for payment, those operations should also be performed here, as other execution messages will rely on that data to be already instantiated.

Instantiate takes four arguments:

• "deps": allows the contract to interact with the outside world by reading and updating the contract state, accessing other contract states, and using helper functions to work with contract addresses.

• "env": is an object that represents the current state of the blockchain when the contract is executed, including the blockchain's height, timestamp, and the address of the contract being called.

• "info": metadata about the message that triggered the contract's execution, such as the sender's address and the native tokens that were sent with the message.

• "msg": is the message that triggers the contract's execution, which is currently represented by the "Empty" type in the codeblock above.

Why Is Prefixed Storage Needed?

Before we understand what the PrefixedStorage struct is, we should first understand the problem they attempt to solve. We may be tempted to think that the key-value model as described in Storage solves all our storage needs. And we'd technically be correct in thinking that. It is possible to efficiently store vast amounts of user data by just using the methods described in that page. However, we will see that doing this would be cumbersome for the developer in many cases. That's why there are many additional storage structures built on top of the methods described in Storage. Prefixed storage is an additional structure built on top of these methods for the convenience of the developer.

The Problem

We will go over a storage problem and discuss how we might tackle it with the methods we learnt in Storage to get to the root of what prefixed storage actually is. Suppose that we have contract that stores a different password (String) for each wallet address that interacts with it (so that the wallets can later give that password when querying the contract). How would we want to store all these passwords so that they can be checked when it is time for queries?

The Naive Approach

Our first approach might be to use a hashmap that stores all the passwords, and save it as binary using the methods we already know. So we would add the following lines to the init

let passwords: HashMap<&[u8], String> = HashMap::new();

save(&mut deps.storage, PASSWORDS_KEY, &passwords)?;

And then we can proceed to load, and add each users' password whenever a user sends the create_password HandleMsg. Note that I'm assuming we would generate the &[u8] key for the hashmap from the user's wallet address. This approach has a huge problem! That is whenever we want to add another wallet's password to the hashmap, we must load the entire hashmap with all the passwords stored inside it. This will increase gas costs as we gain thousands of users. Moreover, loading the hashmap for queries will strain the node.

The Reasonable Approach

We now realize that we can actually generate&[u8] storage keys for each user wallet and save the password directly to deps.storage as described in Storage. This way, we can use may_load to check if a user has a password, and if he does, learn what it is without loading all the other passwords. Then we would use the following lines of code to save a password

let key: &[u8] = env.message.sender.to_string().as_bytes();
save(&mut deps.storage, key, &msg.password)?;

This method does work! However, what if we want to save additional things that is associated to each user, such as token balances. Then using save on the same key would overwrite our previous data. The solution is to add a prefix to the storage key so that we know it belongs to the password property. One way to implement this is the following:

let prefix: String = "passwords".to_string();
let key: &[u8] = ( prefix + env.message.sender.to_string()).as_bytes();
save(&mut deps.storage, key, &msg.password)?;

This works but can be cumbersome and ugly, especially if you need to build more functionalities around this idea. This is exactly what prefixed storage does in the background! Prefixed Storage is built to solve this problem while hiding away all the ugliness.

What Is Prefixed Storage?

PrefixedStorage is a struct that keeps track of all the storage keys that are used to store various data under a shared namespace similar to described above. Prefixed storage is often used to keep track of storage keys of deps.storage, but it can in fact be used to store the keys of other storage structures.

Example

Let's solve the password problem that was mentioned above with prefixed storage. The solution to this problem resembles viewing keys for permissioned viewing. You will learn more about this in the coming sections. We first define a namespace (prefix) in state.rs.

pub const PREFIX_PASSWORDS: &[u8] = b"passwords";

The idea then is that all the wrapper functions that we've learnt in Storage also work on prefixed storage. We will only demonstrate save and may_load by example.

Saving To Prefixed Storage

We would instantiate a mutable PrefixedStorage object using the following lines of code to save a new password

let mut password_store = PrefixedStorage::new(PREFIX_PASSWORDS, &mut deps.storage);
let key: &[u8] = env.message.sender.to_string().as_bytes();
save(&mut password_store, key, &msg.password)?;

The reason why we can use the same wrapper functions is because Prefixed Storage implements the Storage trait, even though most of what it's doing is to add a prefix on top of the keys we provide to it.

Loading From Prefixed Storage

We may use both load and may_load We may load data from a mutable Prefixed Storage instance with the following lines of code

let mut password_store = PrefixedStorage::new(PREFIX_PASSWORDS, &mut deps.storage);
let key: &[u8] = env.message.sender.to_string().as_bytes();
// Throws error if there is no password saved before
let password: String = load(&password_store, key)?;

In queries, we don't want to use PrefixedStorage struct. Instead we use ReadonlyPrefixedStorage struct. It works in the exact same way, except that you cannot save to it.

let password_store = ReadonlyPrefixedStorage::new(PREFIX_PASSWORDS, &deps.storage);
let key = address.to_string().as_bytes();
let may_password: Option<String> = may_load(&password_store, key)?;

Removing From Prefixed Storage

We can use the remove wrapper function for this.

let mut password_store = PrefixedStorage::new(PREFIX_PASSWORDS, &mut deps.storage);
let key: &[u8] = env.message.sender.to_string().as_bytes();
remove(&mut password_store, key);

How Storage Works

CosmWasm storage uses a key-value storage design. Smart contracts can store data in binary, access it through a storage key, edit it, and save it. Similar to a HashMap, each storage key is associated with a specific piece of data stored in binary. The storage keys are formatted as references to byte arrays (&[u8]).

One advantage of the key-value design is that a particular data value is only loaded when the user explicitly loads it using its storage key. This prevents any unnecessary data from being processed, saving resources.

Any type of data may be stored this way as long as the user can serialize/deserialize (serde) the data to/from binary. Doing this manually every single time is cumbersome and repetitive, this is why we have wrapper functions that does this serde process for us.

All the data is actually stored in deps.storage , and the examples below show how to save/load data to/from there with a storage key.

Storage Keys

Creating a storage key is simple, any way of generating a constant &[u8] suffices. Developers often prefer generating these keys from strings as shown in the example below.

pub const CONFIG_KEY: &[u8] = b"config";

For example, the above key is likely used to store some data related to core configuration values of the contract. The convention is that storage keys are often all created in state.rs, and then imported to contract.rs. However, since storage keys are just constants, they could be declared anywhere in the contract.

The example above also highlights that storage keys are not meant to be secret nor hard to guess. Anyone who has the open source code can see what the storage keys are (and of course this is not enough for a user to load any data from the smart contract).

Prefixed Storage

One common technique in smart contracts, especially when multiple types of data are being stored, is to create separate sub-stores with unique prefixes. Thus instead of directly dealing with storage, we wrap it and put all Foo in a Storage with key "foo" + id, and all Bar in a Storage with key "bar" + id. This lets us add multiple types of objects without too much cognitive overhead. Similar separation like Mongo collections or SQL tables.

Since we have different types for Storage and ReadonlyStorage, we use two different constructors:

use cosmwasm_std::testing::MockStorage;
use cosmwasm_storage::{prefixed, prefixed_read};

let mut store = MockStorage::new();

let mut foos = prefixed(b"foo", &mut store);
foos.set(b"one", b"foo");

let mut bars = prefixed(b"bar", &mut store);
bars.set(b"one", b"bar");

let read_foo = prefixed_read(b"foo", &store);
assert_eq!(b"foo".to_vec(), read_foo.get(b"one").unwrap());

let read_bar = prefixed_read(b"bar", &store);
assert_eq!(b"bar".to_vec(), read_bar.get(b"one").unwrap());

Please note that only one mutable reference to the underlying store may be valid at one point. The compiler sees we do not ever use foos after constructing bars, so this example is valid. However, if we did use foos again at the bottom, it would properly complain about violating unique mutable reference.

The takeaway is to create the PrefixedStorage objects when needed and not to hang around to them too long.

Typed Storage

As we divide our storage space into different subspaces or "buckets", we will quickly notice that each "bucket" works on a unique type. This leads to a lot of repeated serialization and deserialization boilerplate that can be removed. We do this by wrapping a Storage with a type-aware TypedStorage struct that provides us a higher-level access to the data.

Note that TypedStorage itself does not implement the Storage interface, so when combining with PrefixStorage, make sure to wrap the prefix first.

use cosmwasm_std::testing::MockStorage;
use cosmwasm_storage::{prefixed, typed};

let mut store = MockStorage::new();
let mut space = prefixed(b"data", &mut store);
let mut bucket = typed::<_, Data>(&mut space);

// save data
let data = Data {
    name: "Maria".to_string(),
    age: 42,
};
bucket.save(b"maria", &data).unwrap();

// load it properly
let loaded = bucket.load(b"maria").unwrap();
assert_eq!(data, loaded);

// loading empty can return Ok(None) or Err depending on the chosen method:
assert!(bucket.load(b"john").is_err());
assert_eq!(bucket.may_load(b"john"), Ok(None));

Beyond the basic save, load, and may_load, there is a higher-level API exposed, update. Update will load the data, apply an operation and save it again (if the operation was successful). It will also return any error that occurred, or the final state that was written if successful.

let on_birthday = |mut m: Option<Data>| match m {
    Some(mut d) => {
        d.age += 1;
        Ok(d)
    },
    None => NotFound { kind: "Data" }.fail(),
};
let output = bucket.update(b"maria", &on_birthday).unwrap();
let expected = Data {
    name: "Maria".to_string(),
    age: 43,
};
assert_eq!(output, expected);

Bucket

Since the above idiom (a subspace for a class of items) is so common and useful, and there is no easy way to return this from a function (bucket holds a reference to space, and cannot live longer than the local variable), the two are often combined into a Bucket. A Bucket works just like the example above, except the creation can be in another function:

use cosmwasm_std::StdResult;
use cosmwasm_std::testing::MockStorage;
use cosmwasm_storage::{bucket, Bucket};

fn people<'a, S: Storage>(storage: &'a mut S) -> Bucket<'a, S, Data> {
    bucket(b"people", storage)
}

fn do_stuff() -> StdResult<()> {
    let mut store = MockStorage::new();
    people(&mut store).save(b"john", &Data{
        name: "John",
        age: 314,
    })?;
    OK(())
}

Singleton

Singleton is another wrapper around the TypedStorage API. There are cases when we don't need a whole subspace to hold arbitrary key-value lookup for typed data, but rather a single storage key. The simplest example is some configuration information for a contract. For example, in the name service example, there is a Bucket to look up name to name data, but we also have a Singleton to store global configuration - namely the price of buying a name.

Please note that in this context, the term "singleton" does not refer to the singleton pattern but a container for a single element.

use cosmwasm_std::{Coin, coin, StdResult};
use cosmwasm_std::testing::MockStorage;

use cosmwasm_storage::{singleton};

#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
pub struct Config {
    pub purchase_price: Option<Coin>,
    pub transfer_price: Option<Coin>,
}

fn initialize() -> StdResult<()> {
    let mut store = MockStorage::new();
    let config = singleton(&mut store, b"config");
    config.save(&Config{
        purchase_price: Some(coin("5", "FEE")),
        transfer_price: None,
    })?;
    config.update(|mut cfg| {
        cfg.transfer_price = Some(coin(2, "FEE"));
        Ok(cfg)
    })?;
    let loaded = config.load()?;
    OK(())
}

Singleton works just like Bucket, except the save, load, update methods don't take a key, and update requires the object to already exist, so the closure takes type T, rather than Option<T>. (Use save to create the object the first time). For Buckets, we often don't know which keys exist, but Singletons should be initialized when the contract is instantiated.

Since the heart of much of the smart contract code is simply transformations upon some stored state, we may be able to just code the state transitions and let the TypedStorage APIs take care of all the boilerplate.

Summary

CosmWasm storage is built on a key-value storage design, similar to a HashMap, where data is stored in binary format and accessed using storage keys represented as byte arrays (&[u8]). Developers can serialize and deserialize data to/from binary, simplifying this process through wrapper functions. Storage keys are typically constants declared in state files and are not meant to be secret.

Prefixed storage allows for creating separate sub-stores with unique prefixes for organizing different data types, while Typed Storage provides a type-aware interface to reduce serialization boilerplate. CosmWasm also supports advanced abstractions like Buckets and Singletons. Buckets create subspaces for storing collections of items, while Singletons manage single elements, typically used for global contract configuration data. These APIs streamline storage handling, enabling efficient data management in smart contracts.

Now, we will explore some of these storage methods, such as PrefixedStorage, Singleton, and Keymap, in more depth to see how they interact with on-chain data.

Execution Messages are contract messages that trigger the execution of a smart contract and perform specific operations, such as updating the contract state or transferring tokens. If you’re familiar with RPC or AJAX, you can think of execution messages as the code that runs when a remote procedure is called. On Secret Network, execution messages are usually designed to be functions that run as quickly as possible and exit as early as possible when any errors are encountered, as this will help save gas. You can learn more about contract optimization here.

The standard practice on Secret Network is to have an enum with all the valid message types and reject all messages that don’t follow the usage pattern dictated in that enum; this enum is conventionally called ExecuteMsg and is usually in a file called msg.rs

#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum ExecuteMsg {
    Increment {},
    Reset { count: i32 },
}

As mentioned earlier, the standard way to choose what the contract should execute is to look at which ExecuteMsg is passed to the function. Let’s look at an example.

#[entry_point]
pub fn execute(
    deps: &DepsMut,
    env: Env,
    msg: ExecuteMsg,
) -> StdResult<Response> {
    match msg {
        ExecuteMsg::Increment {} => try_increment(deps, env),
        ExecuteMsg::Reset { count } => try_reset(deps, env, count),
    }
}

In this simple example, the code looks at the message passed, if the passage is the Increment message, it calls the function try_increment, otherwise, if the message is the Reset message, it calls the function try_reset with the count.

You may have noticed that the execution message takes two arguments in addition to the msg: deps and env. Let’s look at those more closely.

env

As the name perhaps implies, env contains all the information about the environment the contract is running in, but what does that mean exactly? On Secret Network the properties available in the Env struct are as follows:

• block: this contains all the information about the current block. This is the block height (height), the current time as a unix timestamp (time) and the chain id (chain_id) such as secret-4 or pulsar-3.

• message: contains information that was sent as part of the payload for the execution. This is the sender, or the wallet address of the person that called the handle function and sent_funds which contains a vector of native funds sent by the caller (SNIP-20s are not included).

• contract: contains a property with the contract’s address.

• contract_code_hash: this is a String containing the code hash of the current contract, it’s useful when registering with other contracts such as SNIP20s or SNIP721s or when working on a factory contract.

Now that you have an overview on what all those properties are, let’s take a look at a simple Execution Message.

Example ExecutionMsg

pub fn try_increment(deps: DepsMut, _env: Env) -> StdResult<Response> {
    config(deps.storage).update(|mut state| -> Result<_, StdError> {
        state.count += 1;
        Ok(state)
    })?;

    deps.api.debug("count incremented successfully");
    Ok(Response::default())
}

The execution message above reads the state from the storage(Deps) and increments the count property by one, then prints out the new count, if successful.

As mentioned previously, developers don’t really like working with raw binary data, so many resort to using more human friendly ways; you can find out more on the page about storage, here. But for the sake of this example, let’s look at what that config function is doing.

The developers of this contract opted for using storage singletons. A storage singleton can be thought as a prefixed typed storage solution with simple-to-use methods. This allows the developer to define a structure for the data that needs to be stored and handles encoding end decoding it, so the developer doesn’t have to think about it. This is how it’s implemented in this contract:

use cosmwasm_storage::{singleton, singleton_read, ReadonlySingleton, Singleton};

pub static CONFIG_KEY: &[u8] = b"config";

#[derive(Serialize, Deserialize, Clone, Debug, Eq, PartialEq, JsonSchema)]
pub struct State {
    pub count: i32,
    pub owner: Addr,
}

pub fn config(storage: &mut dyn Storage) -> Singleton<State> {
    singleton(storage, CONFIG_KEY)
}

The config function returns a singleton over the config key using the State struct as its type, this means that when reading and writing data from the storage, the singleton automatically serializes or deserializes the State struct.

Response

You may have noticed that the return type for a handle message is Response. Let's take a look at how Response is defined:

pub struct Response<T = Empty> {
    /// Optional list of messages to pass. These will be executed in order.
    /// If the ReplyOn variant matches the result (Always, Success on Ok, Error on Err),
    /// the runtime will invoke this contract's `reply` entry point
    /// after execution. Otherwise, they act like "fire and forget".
    /// Use `SubMsg::new` to create messages with the older "fire and forget" semantics.
    pub messages: Vec<SubMsg<T>>,
    /// The attributes that will be emitted as part of a "wasm" event.
    ///
    /// More info about events (and their attributes) can be found in [*Cosmos SDK* docs].
    ///
    /// [*Cosmos SDK* docs]: https://docs.cosmos.network/main/core/events.html
    pub attributes: Vec<Attribute>,
    /// Extra, custom events separate from the main `wasm` one. These will have
    /// `wasm-` prepended to the type.
    ///
    /// More info about events can be found in [*Cosmos SDK* docs].
    ///
    /// [*Cosmos SDK* docs]: https://docs.cosmos.network/main/core/events.html
    pub events: Vec<Event>,
    /// The binary payload to include in the response.
    pub data: Option<Binary>,
}

In CosmWasm, the Ok result and the Response object are essential parts of handling contract execution and signaling the outcome to the blockchain. Here's a breakdown of how these work:

Ok Result in CosmWasm

In Rust (and by extension, CosmWasm), functions that interact with the blockchain often return a Result type. This is a way to express whether the function was successful or if it encountered an error.

• Result<T, E>: A Result can either be:

  • Ok(T): Signifying the function executed successfully and returns a value of type T.

  • Err(E): Signifying that an error of type E occurred.

In the context of CosmWasm, the Ok result generally signifies that a contract's execution completed successfully, returning a Response object.

For example:

Ok(Response::default())

This line means that the contract execution was successful, and it returns a default Response. In CosmWasm, we use StdResult<Response> for contract execution functions.

Query messages retrieve the relevant smart contract and execute the query message. The results of the query are then returned to the sender of the query message, providing users with information about the state of the blockchain and the smart contracts running on it.

#[entry_point]
pub fn query(deps: Deps, _env: Env, msg: QueryMsg) -> StdResult<Binary> {
    match msg {
        QueryMsg::GetCount {} => to_binary(&query_count(deps)?),
    }
}

Contracts can define query functions, or read-only operations meant for data-retrieval. Doing so allows contracts to expose rich, custom data endpoints with JSON responses instead of raw bytes from the low-level key-value store. Because the blockchain state cannot be changed, the node can directly run the query without a transaction.

Users can specify which query function alongside any arguments with a JSON QueryMsg. Even though there is no gas fee, the query function’s execution is capped by gas determined by metered execution, which is not charged, as a form of spam protection.

Sending Native SCRT from a contract is realtively trivial and can be done using the message. This is a call. Any native denoms can be send in this way (ex. native IBC tokens).

Transaction logs

You can see the spent coins as events when you query for the transaction:

What are Keymaps?

A Keymap is hashmap-like storage structure that uses generic typed keys to store objects. It allows iteration with paging over keys and/or items without guaranteed ordering, although the order of insertion is preserved until you remove objects.

An example use-case for a keymap is if you want to contain a large amount of votes and iterate over them in the future. Since iterating over large amounts of data at once may be prohibitive, a keymap allows you to specify the amount of data that will be returned in each page. We will implement this voting example below to show how keymaps can be utilized in your own projects.

Importing the subpackage

To import this package (and also the packages that we will be using for unit tests), add the following dependencies to your Cargo.toml file

Configuring the testing environment

To import and initialize a keymap, use the following packages in your test environment:

Now let's write our first test!

Inserting key-value pairs into a Keymap

Let's start by creating a function that inserts key-value pairs into a keymap. This code defines a test function called test_keymap_perf_vote_insert() that creates a new Keymap that maps Vec<u8> keys to String values, and then inserts 1000 key-value pairs into the Keymap. Each key is a Vec<u8> containing an integer from 0 to 999, and each value is a String containing the text "I vote yes".

This test is passing! Which means that it asserts that the Keymap contains 1000 key-value pairs, which map a number from 0 - 999 with the string "I vote yes."

Iterating with Keymaps

There are two methods that create an iterator in Keymap. These are .iter and .iter_keys. iter_keys only iterates over the keys whereas iter iterates over (key, item) pairs. Let's use iter to test the iterator functionality of aKeymap that maps Vec<u8> keys to a struct Vote.

We are going to create a new Keymap that maps Vec<u8> keys to a struct Vote that has two fields, vote and person. It then inserts two key-value pairs into the Keymap, where the keys are the byte vectors b"key1".to_vec() and b"key2".to_vec(), and the values are Vote structs containing information about the vote and the person who cast it.

We then use iter() to check that the size of the iterator is 2, which means there are two key-value pairs in the Keymap:

Our test is passing! This means that the first element returned by the iterator matches the expected key-value pair for key1, and that the second element returned by the iterator matches the expected key-value pair for key2.

Additional Resources

Introduction

In this tutorial, we are going to create our own SNIP-20 token on Secret Network using Secret Labs' SNIP-20 reference implementation contract, and we will learn how to upload, instantiate, execute, and query our SNIP-20 contract using Secret.js. Let's dive in!

Source Code

You can clone the source code , which we will reference throughout the course of this documentation.

Prerequisites

Use to set up your developer environment.

Build and Deploy Contract

Now that you've cloned the SNIP-20 reference implementation repo above, let's compile the contract. In your terminal run make build-mainnet-reproducible.

The compiled wasm file will be output in ./optimized-wasm.

Uploading and Instantiating the SNIP-20 Contract

Now let's upload and instantiate the SNIP-20 Contract. We have already written an for your convenience. If you would like to make any changes to your SNIP-20 token, you can do so .

The initMsg object in our upload.js file is referencing the instantiation message defined in . Notice the optional config variable. If we include config, there is a variety of additional contract functionality that we could program, such as burn, mint, admin privileges, etc.

Now we are going to instantiate some ZBRA coin. If you want to create your own coin name, update the name, symbol, and amount fields respectively.

Otherwise, run node upload:

Upon successful execution, a codeId, contract hash, and contract address will be returned:

Query the Token Info

To check that the instantiation of our SNIP-20 ZEBRA token was successful, let's query the smart contract's token info.

Run node query_token_info:

The following is returned upon successful query:

SNIP-20 Contract Messages

Now let's execute the transfer message with secret.js. Be sure to update the recipient wallet address with your own wallet before executing the code below. For testing purposes, I am using two Keplr wallet connected to the Secret Network testnet in order to move funds back and forth:

Congrats! You just successfully transferred your own SNIP-20 token on Secret Network! 🎉

Deps (or the mutable version DepsMut) holds all external dependencies of the contract, and is designed to allow easy dependency injection at runtime. Those external dependencies are as follows:

Storage

As the name suggests, storage allows reading and writing data in a contract's memory. Secret Network contracts use a key-value store for reading and writing data and provide three easy-to-use methods to do so:

• get(&self, key: &[u8]) -> Option<Vec<u8>> reads data stored in the specified key

• set(&self, key: &[u8], value: &[u8]) which writes data to the storage in the specified key

• remove(&self, key: &[u8]) which deletes a key alongside its data.

You may have noticed that storage uses byte arrays exclusively to read and write data, so to make it more user-friendly there are certain libraries that the community has developed. You can learn more about this .

Api

Api consists of a collection of callbacks to system functions defined outside of the wasm modules. Those are functions that are defined in the chain’s code, this allows calling useful functions without needing to include them in the contract’s code and assures a smaller binary size as well as a higher certainty that they’re going to be implemented correctly.

• canonical_address(&self, human: &HumanAddr) -> StdResult<CanonicalAddr> Takes a human readable address and returns a binary representation of it.

• human_address(&self, canonical: &CanonicalAddr) -> StdResult<HumanAddr> Takes a canonical address and returns a human readble address. This is the inverse of canonical_address

• secp256k1_verify(&self, message_hash: &[u8], signature: &[u8], public_key: &[u8]) -> Result<bool, VerificationError> 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.

• secp256k1_recover_pubkey( &self, message_hash: &[u8], signature: &[u8], recovery_param: u8 ) -> Result<Vec, RecoverPubkeyError> Recovers a public key from a message hash and a signature.

• ed25519_verify( &self, message: &[u8], signature: &[u8], public_key: &[u8] ) -> Result<bool, VerificationError> Verifies messages against a signature, with the public key of the signer, using the ed25519 elliptic curve digital signature parametrization / algorithm.

• 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.

• secp256k1_sign( &self, message: &[u8], private_key: &[u8] ) -> Result<Vec, SigningError> Signs a message with a private key using the secp256k1 elliptic curve digital signature parametrization / algorithm.

• ed25519_sign( &self, message: &[u8], private_key: &[u8] ) -> Result<Vec, SigningError> Signs a message with a private key using the ed25519 elliptic curve digital signature parametrisation / algorithm.

• (CosmWasm 1.0) debug - a function that allows for debug prints, which can be used during development to print to STDOUT in a testnet or LocalSecret environment (replaces debug_print from CosmWasm v0.10)

• (New in Secret-Cosmwasm v1.1.10) gas_evaporate(evaporate: u32) -> u32 - this API function allows a contract to consume a set amount of gas. Use together with check_gas in order to create contract calls that consume an exact amount of gas regardless of the code path taken.

• (New in Secret-Cosmwasm v1.1.10) check_gas() -> u64 - this API returns the current amount of gas consumed by a contract call.

AppendStore is meant to replicate the functionality of an append list in a cosmwasm efficient manner. The length of the list is stored and used to pop/push items to the list. It also has a method to create a read only iterator.

This storage object also has the method remove to remove a stored object from an arbitrary position in the list, but this can be extremely inefficient.

❗ Removing a storage object further from the tail gets increasingly inefficient. We recommend you use pop and push whenever possible.

The same conventions from Item also apply here, that is:

1. AppendStore has to be told the type of the stored objects. And the serde optionally.

2. Every methods needs it's own reference to deps.storage.

Initialize

To import and initialize this storage object as a static constant in state.rs, do the following:

❗ Initializing the object as const instead of static will also work but be less efficient since the variable won't be able to cache length data.

Often times we need these storage objects to be associated to a user address or some other key that is variable. In this case, you need not initialize a completely new AppendStore inside contract.rs. Instead, you can create a new AppendStore by adding a suffix to an already existing AppendStore. This has the benefit of preventing you from having to rewrite the signature of the AppendStore. For example

Sometimes when iterating these objects, we may want to load the next n objects at once. This may be prefered if the objects we are iterating over are cheap to store or if we know that multiple objects will need to be accessed back to back. In such cases we may want to change the internal indexing size (default of 1). We do this in state.rs:

Read/Write

The main user facing methods to read/write to AppendStore are pop, push, get_len, set_at (which replaces data at a position within the length bound), clear (which deletes all data in the storage), remove (which removes an item in an arbitrary position, this is very inefficient). An extensive list of examples of these being used can be found inside the unit tests of AppendStore found in append_store.rs.

Iterator

AppendStore also implements a readonly iterator feature. This feature is also used to create a paging wrapper method called paging. The way you create the iterator is:

More examples can be found in the unit tests. And the paging wrapper is used in the following manner:

Secret Network provides all the tools necessary to build fully private decentralized applications, but contracts do not automatically inherit perfect privacy. Privacy has a cost. Developers have both the freedom and the burden of choosing a privacy model that fits their applications' needs.

Protecting sensitive user data is not even the whole story when it comes to Secret dApps. Achieving a proper level of privacy can be mission critical in certain areas, such as competitive gaming, where an information leak could lead to a compromised system, say, if an attacker were able to cheat.

As a developer, it is your responsibility to understand the gamut of privacy risks, their implications, and how to best mitigate them.

Perfect Privacy

Let's start off with a thought experiment. In an ideal world, a perfectly private application would be one that an attacker could not plausibly deduce any information about regarding its state, history, or participants. To an observer, any time a participant reads from or writes to the contract, it would be indistinguishable from every other action.

All outputs would appear to be random and unpredictable, with no discernible patterns that could be used to infer the underlying operations or data. On top of all that, the timing and frequency of executions would need to be consistent across the lifespan of the application.

Understanding The Risks

In reality, there are many forms of contextual data that an attacker can use to infer information, de-anonymize users, or compromise the privacy of applications purely through analysis:

• transaction sender's address, their public transaction history, the timing and frequency of their transactions, and their relation to other accounts on the network

• public inputs and outputs of an execution, such as sent or received funds (e.g., wrapping/unwrapping SCRT or IBC tokens)

• timing of an execution, its temporal locality to other transactions (e.g., clustering, dispersion, co-ocurrence), and an execution's order relative to other on-chain events

• size of the encrypted inputs and outputs of executions, shape and size of the event log, and public transaction metadata including gas_used and nested calls to other contracts

• timing, frequency, shape and size of query requests and query responses

• storage access patterns when a contract reads from and writes to the encrypted application database

Additionally, there are active attacks that can expose unwanted leaks of information:

• executions that produce measurable side-effects

• tx replay attacks, side-chain attacks, the Millionaire's Problem

• targeted storage access pattern attacks

Mitigating The Risks

Its important to note that a few of the risks listed above can only be mitigated by user OPSEC. For example, the timing and frequency of executions, tx sender address, and relations to other accounts are risks typically assumed by end-users. In these cases, education is the best instrument to protect users' privacy.

Some of the other risks should be mitigated by client-side software, such as wallets and dApp front-ends. This includes padding inputs to executions and queries, being strategic about the timing and distribution of query requests, and creating workflows that allow users to more easily create identities that are not linked to their public account.

The remaining privacy risks are those which can only be mitigated through contract design. Developers should strive to make all queries and executions appear indistinguishable from one another to an outside observer. This includes:

• padding query and execution results (see pad_query_result and pad_handle_result from the Secret Toolkit)

• using Gas Evaporation to make all methods consume a consistent amount of gas

• adding decoy attributes to the event log when necessary

• understanding storage access pattern attacks and employing a system of decoys or oblivious data models (or even UTXO)

CosmWasm smart contracts

Smart contracts on Secret Network follow the widely used CosmWasm framework. The framework is built as a module for the Cosmos SDK and allows developers to build smart contracts with Rust which compile to WebAssmebly (Wasm). This type of efficient and fast binary, combined with the power of a low-level typed coding language, makes CosmWasm a secure and efficient way for developers to write smart contracts. Contracts on Secret have a public binary just like any other smart contract network, only the contract input, output and state is encrypted.

Secret Contracts slightly differ from any standard CosmWasm implementation as they handle encrypted data, secure enclaves, and the key design around that. Secret currently emulates CosmWasm v1.1.9 and is completely compatible over IBC with other V1.0+ Cosmos Smart contract networks.

Encrypted data storage

Private data (contract input, output and state) on Secret is encrypted using an unforgeable contract encryption key which is unique for every contract. Moreover, the user dedicated state in a contract is only visible to the user themselves. Because of this design, contract migration is a privacy risk. If enabled, a contract admin could upload a malicious contract that reads and prints data entrusted to the old contract. Additionally, iterators and raw queries are not supported as one can not iterate over data stored by a different user as there is no access to their dedicated encryption key.

Available tools and cool features

Secret contract encrypted input and access-controlled output is very powerful and enables many different usecases, combining this with novel development tools creates a powerful framework for developers to leverage. Below some of these tools and ideas are listed to get your brain going.

• Privacy as a Service - More utility for other blockchains by leveraging Secret contracts cross-chain. Want to build on polygon, ethereum, Sei, Neutron or Aptos but want additional features only possible with data privacy? You can use Secret contracts cross-chain to keep your application decentralized and offer users new and interesting ways to explore your dApp.

• Storage of private/encryption key (fragments) - One can use Secret contracts to store very sensitive info to enable cool usecases like access-controlled content or even cross-chain account ownership for DAOs and unstoppable threshold wallets.

• on-chain randomness (secret-vrf) and hidden (game) state - Games on Secret benefit of true on-chain randomness that can remain hiddin inside the contract forever if so desired. Together with a hidden gamestate this brings a whole new dimension and fairness to turn-based games for Web3 like Poker or Mario party and more clarity and ownership to casino games and lootboxes.

• Frontrunning resistant and privatized DeFi - because of an encrypted mempool secret is frontrunning resistant by default. Order size - unknown, Placed bids - unknown, liquidation points - unknown and many other features from orderbooks to dark pools have these privacy features as well.

• Secret.js - a Javascript library for interacting with the Secret network, Secret contracts, providing encrypted input and creating viewing keys/permits for encrypted output. The library can also be considered as a more complete Cosm.js and can be used on every other cosmos chain. - Alternatives in Python, Kotlin, .Net and more exist as well.

• Polar, Fadroma, Secret-toolkit (CW-plus) and Secret IDE - Secret has dedicated tooling sets built by external teams and core development that abstract boilerplate code (for DeFi), help with testing scenarios, simplify contract development nightmares like storage and type handling and even catch errors as you work in a dedicated IDE.

• IBC, Interchain accounts/Queries/contracts, Axelar GMP, Bidshop messaging and more - Want to build your application crosschain? Secret has many options for both Message and Asset bridging protocols with the most renowned being IBC (current version IBC-go V4).

Trusted vs untrusted data and Contract verification

The privacy of Secret Network is reliant on secure enclaves, which impacts how the network performs but also how one should design their contracts to enhance privacy. Firstly, it is important to note that only data originating from inside the enclave is verifiable and any data coming from external resources has to be verified before relying on it for execution. This means data coming from contract callbacks is to be trusted, but the sender address is not. If I allow the sender to create an item on-chain, then only the sender should be able to remove that item. Verifying that it is indeed the sender (data owner) that is requesting this change is done by "input data verification". Explanation of the various network level integrated methods is available here.

In practice a Secret contract developer does not have to think too much about this as its abstracted away in the data verification process in the contract module of the network.

Replay/Side-chain attacks - privacy design

When designing contracts for Secret network, one should take into account the usage of so-called replay attacks and other theoretical attack vectors on secure enclave derived privacy. An example of this is the abundant usage of the Contract hash in Secret contract development. The usage of a contract hash is required to link the input to the specific contract being called. Otherwise one could make a forked chain and replace the contract with one that reads and prints the input parameters. Although encryption for Secret contracts is handled by the protocol, developers should still be mindful of their contract design to optimize for these privacy aspects.

One example of such a privacy optimized design would be the use of the Gas evaporation function as added in the v1.9 upgrade and documented here (link coming soon).

Contract execution result

There are various types of outputs that can be expected, including:

• An updated contract state (i.e., the user’s data should update the state or be stored for future computations)

• A computation result encrypted for the transaction sender (i.e., a result should be returned privately to the sender)

• Callbacks to other contracts (i.e., a contract is called conditional on the outcome of a Secret Contract function)

• Send messages to other modules (i.e., for sending value transfer messages that depend on the outcome of a computation).

• Reply - Send more detailed error logs of various submessages as explained here.

Summary

• Secret Contracts have private input, output and state. This means all data on-chain is stored as cyphertext and is only accessible by the owner (either the contract or the user). More details are available in the encryption specs.

• The binary of any contract is public, meaning the execution logic is verifiable just like any other smart contract blockchain.

• Secret smart contracts are IBC compatible (CosmWasm v1.0+), allowing for cross-chain logic with other IBC-connected chains.

• from v1.11 Secret now supports migrate-able contracts just like vanilla CW, it does not support iterators due to contract privacy design. Workarounds are highlighted under storage.

• When designing Secret contracts, the verification of input-data is key to ensure the secure execution of transactions as not all blockchain data is exposed automatically to the enclave.

• Developers need to be mindful of data leakage via replay attacks, improper padding, and more so that the privacy for users of their contracts is optimized.

Max gas per block

As explained in the Gas and fee section Secret computational load is denominated in gas. The amount of gas that can be spend at every block is capped via the max_gas block parameter. This cap is currently set at 6,000,000 (6 million) gas meaning a block will never contain more computational load than what is represented by 6 million gas. The computational load per gas unit is calculated and then denominated in the chain binary.

You can find the Gas settings for Secret Network in the Network code here - [SDK/Go message types] , [Wasm messages]

Expected block time

The max_gas parameter is chosen in such a way that validators can ensure they process the full computational load within the target block execution time (~6s). If this computation and expected blocktime don't align the blocks will become longer and longer as they await 66% of voting power to sign the block. When block time increases the TPS of the blockchain drastically decreases only complicating the situation further.

You can read more about this interplay between blocktime, TPS and scalability in this post mortem of the Shade airdrop.

Encryption overhead

One can expect the overhead of all enclave and encryption transactions to be roughly 30% over a vanilla wasm engine. This overhead comes from the decryption and re-encryption done in the enclave and the varying verification's that are required of the message input data. This overhead does not exist for standard SDK messages like "stake", "transfer", "vote" etc.

Additionally Secret leverages an older engine for the wasm VM dubbed "Wasm3". The vanilla engine "Wasmer" is roughly10-15x more performant. This engine is not yet supported as there is no Enclave compatible version, development effort to support it though is underway as listed in the core roadmap.

Transactions per second

Because of above factors the TPS of Secret is limited in comparison to vanilla Tendermint and Cosmos SDK benchmarks. Based on an average of 100.000 gas for a contract interaction (something like an NFT mint or non-routed DEX swap) Secret can process 60 TXs per block which at ~6s per block 10 WASM transactions per second. SDK interactions take a lot less gas meaning the overall TPS of Secret in practice is ~25.

As explained in the above section this number can still be significantly increased by upgrading the WASM engine but has proven sufficient so far in periods of high demand

Enclave Queries

Important to note is that Queries related to contract state require the API node to access the enclave, these are therefore more resource expensive than SDK queries. Secret API infrastructure needs to be scaled accordingly to fit heavy load user interfaces. One can expect to require more Secret API nodes than standard Cosmos API nodes for a similar application. As transaction complexity overhead decreases with better engines so does increase the ability for a node to process queries. Verified queries on Secret have already become a hundred times more performant with 1.4-1.6 upgrades, and with the current community API they are in a very stable spot.

Scalability

Short term scalability improvements can come from a WASM engine replacement and increase in Light client verification methods so to lower the enclave load. Also storage access can become more performant with an SGX backend change which is on the short term roadmap. Long term Secret does not have to worry about blockspace with the plenty opportunities of replicated security and the cosmos sdk. For more on the core development roadmap check out the documentation here.

Transaction priority and fee market

Secret network uses Tendermint as a consensus engine combined with the Cosmos SDK, as such it has a relatively high throughput and the possibility for easy horizontal scalability. Because of this, there is no fee market on Secret Network, which means there is no fee-based prioritization built into the standard tendermint binary required to run Secret. Using a higher transaction fee will only increase the number of block signers (validators) that are willing to process your transaction. This might speed up finality but does not prioritize your transaction in the cue.

Gas and the Gas fee

The fee a user pays for a transaction is based on two things: the computational resources/block space that is used and the fee that validators ask for these resources. These two elements are called gas and the gas fee.

The gas required for the computation is determined by the smart contract engine. The current gas estimates per type of contract interaction are listed here (for SDK components) and here (for enclave components). More complex transactions will consume more gas.

The gas fee is determined by validators themselves as a parameter in their node service. The min_gas_fee parameter allows validators to set a minimum fee denominated in uSCRT . If a transaction has a lower allocated fee, they will not add it to blocks they propose. Validators propose blocks based on random selection following their Voting power. The min_gas_fee for each block is dependent on the proposing validator. If blocks become too full or an attacker spams the network, the validators can increase their fee. Secret validators run three tiers of fee's; this choice is up to the validator. Overall, we can assume more than 40% of validators support the "low" fee option, meaning pushing a TX with the low fee often gets processed within a few blocks. Pushing a TX with the "High" fee will increase the chance that the next block can fit your transaction. These TXs are therefore considered "faster". The current recommended fee options are listed in the Cosmos chain registry.

Fee calculation + execution time

Now let's assume we execute a swap for a single Dex pool. We can expect this to take roughly 150000 Gas . Executing this at the "low" fee option, we will pay 0.0125 uSCRT for each Gasunit used. The total fee for this transaction then becomes: 150000 * 0.0125 = 1.875 uSCRT = 1.875/1000000 = 0.001875 SCRT. At 40% voting power supporting a min_gas_fee of 0.0125 uSCRT we can expect this transaction to be finalized after 4 blocks ( 4*6s = 24s) with a 97.5% certainty [1- (40%**4) = 0,9744].

FeeGrant

Secret also allows for Gas abstraction for users by leveraging the CosmosSDK FeeGrant module. This module allows one to submit transactions where a different wallet is paying the gas fees as long as they granted you a budget to do that.

Documentation to create Feegrant functionality in your UI are here. This tool is widely used in different Secret UIs (for ex: Secret dashboard) and there is a community run FeeGrant faucet available for dApps to use. - Faucet - Code

As Secret runs the compute module from within the enclave of the validator node it handles 2 types of data, data coming from within the enclave or outside of it. This data can then be separated as trusted (in-enclave) and un-trusted (outside enclave) meaning you can only rely on the trusted to be true in all cases, the untrusted data can be forged either with replay attacks on forked chains or state modification attacks.

The amount of trusted data options can be increased by additional verification mechanisms.

Input data verification

During execution, some contracts may want to use "external-data", meaning data generated outside of the enclave and sent into the enclave, such as the tx sender address, the funds sent with the tx, block height, etc...

As these parameters are sent to the enclave, they can theoretically be tampered with, and an attacker might send false data; making relying on this data conceivably risky.

For example, let's say we are implementing an admin interface for a contract, i.e. functionality only for a predefined address. We want to ensure the env.message.sender parameter provided during contract execution is legitimate, so we will confirm that env.message.sender == predefined_address. If this condition is met we can provide admin functionality. If the env.message.sender parameter can be tampered with — we effectively can't rely on it and cannot implement the admin interface.

In-enclave light client - fork protection

This verification is done by a light-client implemented inside of the enclave which validates all compute transactions and their order. It matches the set of transactions to be executed with the data hash field of the block at the current height. This means we can trust contract executions (Attention: not other modules like Bank), User address, inputs and sent funds are all part of the signed and validated inputs.

The light client does not validate internal contract calls - when your contract calls another during runtime - but these are signed in such a way that it can only be generated by another contract inside a genuine enclave. This can be considered trusted execution as well.

Merkle proofs (coming soon) - State modification attacks

Looking at state modification attacks - these refer to attacks that attempt to modify the internal state of the chain to create behaviour that allows to compromise confidential data. This can be done by changing the internal state values of the chain (even encrypted values can be replaced with other valid encrypted values) and executing the real transactions to see what happens.

For example, imagine a contract that has the following logic:

1. Receive transaction from user with some amount of SCRT

2. Validate that payment is exactly 1000 SCRT

3. If payment is correct, reveal secret value

An attacker can use a modified chain to attack this logic in the following way:

1. Send a transaction on the real chain with 1000 SCRT from an address that has 1 SCRT

2. Wait for the transaction to fail on mainnet

3. On a modified chain fund the attacker's address with 1000 SCRT

4. Replay the real block from mainnet

5. Reveal the secret value

This scenario illustrates how payment systems need to consider these attack values.

Protecting against modified state is being actively developed, and will be solved by validating that values that are read from the chain are part of the merkle tree of the chain itself - Coming end of 2023

Summary of trusted vs untrusted data - from a contract perspective

Trusted = No means this data can easily be forged. An attacker can take its node offline and replay old inputs. This data that is Trusted = No by itself cannot be trusted in order to reveal secrets. This is more applicable to init and handle, but know that an attacker can replay the input msg to its offline node.

When a smart contract is executed, CosmWasm meters how much gas the execution consumes while the program is running. On Secret Network, this all happens within the enclave. However, once execution completes, the total amount of gas that was consumed leaves the enclave and is made public in transaction metadata.

Privacy Risks of gas_used

The public gas_used result of a contract execution message reflects the sum of costs for the actual instructions that were executed. Within a typical smart contract, most of its methods consume different amounts of gas. With SNIP-20 for example, an attacker could deduce which method a transaction executed with a high degree of certainty; create_viewing_key vs. transfer vs. increase_allowance, each of which produce a distinct gas_used amount in the public transaction metadata.

In some cases, this can leak even more information such as which code path was taken, the value of a conditional, how many iterations a loop completed, and so on.

Gas Evaporation

Evaporation is a concept that was introduced to overcome the privacy risks associated with gas_used. Evaporation refers to the practice of deliberately consuming extra gas during execution in order to pad the gas_used amount before it leaves the enclave.

With evaporation, clients can now instruct contracts on exactly how much gas their execution should consume, yielding a consistent gas_used across all methods.

A contract can evaporate an arbitrary amount of gas using the built-in API function gas_evaporate. In order to evaporate any remaining gas, the check_gas API function allows contracts to calculate the difference between the amount consumed up to that point, and the amount the client wants the contract to consume by the end of its execution:

See the evaporation example contract's for more details.

Note that there is no API function to get the amount of actual gas remaining. Instead, that information must come from the client. This practice ensures that users are still able to execute multiple messages in a single transaction by specifying gas limits to each contract execution individually.

Gas Tracking

The new check_gas API function essentially gives contracts read access to CosmWasm's internal gas metering. Calling this function more than once during execution allows contracts to track changes in the amount of gas consumed. This simple feature enables a realm of interesting use cases not previously possible.

In its simplest form, gas tracking can be used as a development aid to inspect the amount of gas used by certain blocks of code, giving developers more insight and help with optimizing their gas footprint.

Opportunistic Execution

A more advanced use case involving gas tracking is opportunistic execution, where contracts take advantage of excess gas that would otherwise be evaporated by performing work that needs to be done anyway. That work could be anything from generic housecleaning duties, such as processing items in a queue, to more intentional duties, such as notarizing previous user actions to protect against tx-replay attacks.

To give an example, imagine an NFT auction contract that accepts bids on listed items. When a listing expires, the listed NFT should be transferred to the highest bidder. In typical contract design, the transfer would only actually happen once the winning bidder calls a method to "claim" their winnings. However, with opportunistic execution, the contract can automatically perform the transfer during any execution. For example, someone creating a viewing key could end up paying the gas fees to complete the transfer of a previous listing's NFT to its winning bidder.

Query Permits

Query permits are an alternative querying method introduced in the SNIP-24 design specification. Query permits use of a cryptographic technique known as public-key encryption coupled with digital signatures.

A permit is a formatted message, it outlines several arguments such as what tokens the permit applies to and what permissions the permit should allow (e.g. should the permit allow the querier to view a user’s transaction history, balance, etc.). Permits are not saved in the smart contract state and do not require the initiation of a blockchain transaction. Therefore, permits are a less permanent way of gaining viewing access with less network strain.

Signing Permits

Users can sign permits with their account’s private key to give certain dApps or parties viewing access to specific parts of their private data for a specified amount of time. To get viewing access a user sends a query, with the signed permit as an argument, to a smart contract. Once received, the smart contract, using the user’s public key, can validate the identity based on the signature the user provided. If the user’s identity is confirmed, the smart contract returns the data as requested.

Introduction

The ability to generate fair and verifiable random numbers on blockchain without compromising security or usability is critical for many decentralized applications. However, generating true randomness is difficult because blockchains rely on consensus mechanisms, such as Proof of Work or Proof of Stake, to reach agreement on the state of the network, and these consensus mechanisms are deterministic and therefore do not provide a source of true randomness. There have been attempts to solve this problem by various methods, such as using random data from external sources (the hash of a previous block, etc) or by using off-chain solutions, such as Chainlink’s VRF oracle, but these solutions are not optimal as they are either deterministic, rely on trusted parties, and/or require additional fees for gas and infrastructure. What is needed is a verifiable random number generator that exists on-chain, and this is now possible across blockchain ecosystems through Secret Network Random Number Generator (RNG).

Why Randomness Matters

The ability to generate true randomness is a fundamental requirement for blockchains. Verifiable randomness guarantees that operations such as the minting of NFTs, on-chain games, and DAOs are equitable and secure. In the case of NFT minting, randomness allows for features such as unordered minting, trait randomization, and identity numbering, all of which are critical for verifying the authenticity and security of NFT collections. In Web3 gaming, components such as gambling, damage calculation, loot boxes, boss drops, etc, rely on randomness to create trust amongst players and ensure that no player has an unfair advantage. And in the case of DAO tooling, randomness is required for features such as wallet initialization, task assigning, unordered voting/liquidations, order book ordering, etc. By using Secret Network RNG in these and other applications, the Interchain can help to ensure the security, transparency, and fairness of blockchain operations, which in turn promotes the growth and adoption of the Cosmos.

How It Works

Secret Network is built on top of Tendermint, a peer-to-peer networking protocol that provides Byzantine-Fault-Tolerance (BFT) and Proof-of-Stake (PoS) consensus. This consensus ensures that all nodes maintain the same blockchain and that all nodes have the ability to propose new blocks. From a high-level standpoint, a new consensus round is:

1. Initiated with a Proposer Node

2. The Proposer selects transactions in the mempool to be included in a new block

3. This proposed block is broadcasted to all nodes (Pre-vote phase) and nodes verify that the block is valid, simultaneously verifying that the Proposer is also valid and sign the pre-vote message

4. If >2/3 of nodes pre-vote for this block, the block is deemed valid

5. Once a block is committed, there is no way to revert it and there is instant finality

The process of block proposal and execution involves a crucial intermediary step known as the "prevote phase." Secret Network RNG creates verifiable on-chain randomness by generating a random number that is attached to each Proposer’s block proposal, and this random number can then be used for on-chain randomness for the current block and exhibits the following properties:

1. The number is generated with sufficient entropy

2. The block proposer cannot predict or influence the entropy generation

3. Outside actors cannot predict random numbers before they are used to compute network transactions

Secret Network achieves this by implementing the following privacy network consensus:

Secret Network Consensus Schema

Secret Network is unique from other blockchains because it utilizes Software Guard Extensions (SGX) to provide a Trusted Execution Environment (TEE) by creating a secure area in memory, called an "enclave," where sensitive data and code can be processed in a way that is isolated from the rest of the blockchain. This means that even if the operating system, other applications, or an attacker were to somehow compromise the security of the blockchain, the data and code within the SGX enclave remains protected.

Secret Network’s SGX allows for private computation on-chain and uniquely positions Secret Network to be the privacy provider of the interchain. In order to provide randomness as an interchain service, Secret Network’s SGX generates a random number on-chain during the block proposal stage of Tendermint. Block proposers generate a random number inside of the Trusted Execution Environment using RDRAND/RDSEED instruction.

RDRAND and RDSEED are Intel Secure Key technology instructions used in computer processors to generate random numbers

The RDRAND instruction is used to generate random numbers, while the RDSEED instruction is used to generate seed values for cryptographic purposes. Externally influencing RDRAND that is executed inside an SGX enclave is very difficult to do, with no known practical or theoretical attacks that can reduce the resulting entropy of the instructions.

In addition to generating random numbers using SGX, Secret Network adds an additional layer of security to the output of the random number generation by pairing it with an Initial Randomness Seed (IRS). This seed originates from a shared consensus seed among all network nodes, and the random number and IRS are combined using an algorithm called HKDF(rfc5869) to certify that the final number is truly random and cannot be predicted by anyone, even if they were to influence the original random number generation.

Secret Network also includes an additional key that is available to all nodes on the network within the TEE called the Random Encryption Key (REK). The REK is used to encrypt the generated random number using symmetrical encryption, and the encrypted blob (Erand) is attached as a new field to the block proposal. The REK is derived from the consensus seed, so all network nodes can derive it without the need for key-sharing protocols.

In order to make sure the random number generated by the block proposer is secure, a majority of network validators must signal their approval of the proposed block before the encrypted number can be decrypted. Tendermint’s pre-vote mechanism allows the blockchain to “signal” that the proposed block has been authorized by a majority of network validators, and guarantees attempted execution of the block. Therefore, the only way to decrypt the Initial Randomness Seed is for nodes to submit a 66% majority of pre commits/commits to the TEE. The TEE will then verify this majority and decrypt the seed, returning it to the caller in its decrypted state, which can be then used for network randomness.

To prevent errors or malicious behavior, the encrypted number will be accompanied by a proof, which is defined so that an SGX enclave can verify that the proposed encrypted random number matches the block height and active set of the current Tendermint block. The proof is created using a one-way-function that takes the encrypted random value, the block height, active validator set, and the Random Encryption Key (known only to network nodes). With the proof key, SGX enclaves can verify that the proof was made within the enclave.

Combatting Potential Attack Vectors

Secret Network’s TEE is continuously updated in response to changes to the active set of network validators. In order to avoid the issue of verifying changes to network validators, the active network validators influence the result of the derived random value during the decryption and verification process of the random number. Thus, changes to the active validator set produce a different random number, thereby rendering attacks using modified active validator sets ineffective. In addition, attempts to fork the chain and decrypt the number using a different active validator set are also rendered ineffective.

If a harmful actor were to attempt to fork the chain to predict the next number, the attack is rendered ineffective because the next number is generated randomly by the block proposer's enclave and cannot be predicted. Furthermore, a validator cannot execute blocks without the ability to decrypt the random number, which requires submitting prevotes to do so. If the malicious validator attempts to reuse a previous random number, the validator must submit a proof that links the encrypted random number with the block height and validator set, which it cannot.

To avoid being able to replay previous signatures with a new encrypted value, the encrypted number must be part of the transactions signed by the validators when creating their approval votes. To validate the prevotes, the TEE needs to receive the signatures and the original transactions. As an optimization, validation of the prevotes by Tendermint can be offloaded to the TEE to avoid verifying the same data twice.

Given that the voting power of validators fluctuates constantly and the computation of the active set's hash can be demanding, Secret Network achieves optimization by setting a minimum sensitivity to the changes in voting power. However, this can lead to disparities between the pre-vote weight and the weight calculated by the TEE, so the validation threshold must be lowered for the TEE. For instance, on Secret Network, if a 0.1% sensitivity to voting power changes is established, a prevote threshold of 61% would be necessary to consider the worst-case scenario where 50 validators, who together make up 66% of voting power, submitted prevotes with a 0.1%-ε higher voting power than what the TEE is aware of.

Finally, if a malicious actor were to somehow break Secret Network’s SGX and steal the REK it would be inconsequential because random numbers are generated independently for each block, so knowledge of a single random value is of no use without the ability to influence block creation. Even in a scenario where the malicious actor was a validator and could submit random numbers for blocks they propose, it would be ineffective because they do not have access to the consensus seed as stated above.

Conclusion

In conclusion, the Secret Network Random Number Generator (RNG) is a significant breakthrough in the generation of verifiable and fair random numbers on-chain. By leveraging the power of SGX and Tendermint consensus, Secret Network has created a first-in-class on-chain solution that generates random numbers with sufficient entropy, and these numbers are then encrypted, paired with an Initial Randomness Seed, and attached to block proposals where they are decrypted in order to generate true on-chain randomness. Coupled with cross-chain interoperable smart contracts over IBC, Secret Network enables thousands of developers and projects across the Cosmos access to state-of-the-art on-chain RNG.

Maths

Execute messages

Here we use a sample contract for selling a secret message to illustrate padding, gas evaporation, and side-chain attack prevention using a trusted actor to confirm transactions. In the contract we define three methods: posting a secret for sale, buying a secret, and confirming purchases. All three message types have two optional parameters: gas_target and padding. These will be used to help mask which message is being called.

Using padding and evaporation in execute

Padding and evaporation are parameters that are set for all message types.

The padding parameter is used by the client to pad the size of message being sent to the contract. The padding parameter is not used within the contract itself and is only necessary when using Keplr's amino format. In other cases the dapp or wallet can simply add extra space characters to the end of the json message.

We also want to pad the result sent back to the client. We can use the pad_handle_result function from secret toolkit to format the response to a fixed block size. If you have responses that are large, you will need a sufficiently large block size to successfully mask the method being run.

After padding the result at the end of execute entry point function, we use gas_target along with the evaporation api functions to evaporate any remaining gas to hit the gas target. Note, we simply ignore both the padding and the gas_target message parameters using .. in the match statement.

Making data written to chain constant size

Just like we want to use padding to hide the message type when sending between the client and the contract, the number of bytes written to the chain can leak information about what is written. For example, a coin amount stored as a Uint128 will write a different number of bytes depending on the size of the number, and also in our example the secret message could leak information based on its length. For data structs we want to store on chain we usually create a stored version and create conversion methods between the unstored and stored versions. Note in the example, we use the secret toolkit space_pad function to make all secrets stored as 256 bytes long masking the content.

Preventing a side chain attack

Padding and evaporation help to protect privacy about what types of functions are being called in a contract and about what data is being read and written from storage. However, our contract is still vulnerable to a side chain attack if a buyer can simply purchase a secret without a trusted actor confirming the transaction. This is because a malicious actor could fork the chain and buy the secret on the forked chain without ever paying any coins on the mainnet.

In our case a trusted actor who can confirm the purchase is the seller of the secret. If all purchases must have the ConfirmPurchase transaction performed after buying, then it is impossible for the side-chain attack to occur. Other contracts that need to implement this functionality might require a trusted third-party actor instead, for example a game contract where turns are executed on-chain.

This section will go over 4 different design options with highlighted use cases. This section should hopefully spark interest into using Secret's Confidential Computing Layer (or "CCL") as a whole and help developers understand the possibilities and limitations of this contract development paradigm.

Understanding the Confidential Computing Layer

The CCL in its most basic form is the idea that one can create products with privacy or additional utility for users who are not on Secret Network itself while using Secret contracts in the backend for the application.

Do you want to tap into Ethereum's liquidity, the polygon NFT scene or just want to add additional encryption-powered use cases to your current techstack? Secret's CCL might be a perfect fit.

1. Query Secret (ex. Secret-VRF)

The first design pathway only takes data from a Secret contract but is non-interactive beyond that. This means implementing use cases in this path can be considered relatively simple by leveraging IBC, Axelar GMP or other cross-chain messaging solutions.

In this dApp design scheme, we see Secret as a blackbox that has data accessible useful to any other chain on request. The requested data will have to be transferred publicly. The best example is on-chain randomness via Secret-VRF.

By leveraging a slightly altered version of Tendermint and the Secure Enclave of every validator, Secret managed to create a truly random number generator on-chain. Every block and every contract call, the number is different and the numbers are verifiable via a callback after the block finalises. A developer on another blockchain can design a lottery completely on-chain by determining the random outcome using Secret-vrf. Simply make a contract on the consumer chain that requests a random-number (over IBC) from a Secret contract. Make sure the lottery entries close before requesting the number as it will arrive over public channels after the block closes on Secret. The number is now used within the contract on the consumer chain to assign the winner; no data has to return to the Secret contract.

Want to leverage Secret-VRF for your application on EVM or IBC? - Read more here!

2. Authentication via Secret contracts (ex. web-Auth login, Threshold wallets)

For the second design pathway, data flows towards Secret in an encrypted format with the output merely verifying if the input matches a pre-set pattern or any other defined criteria. Secret contracts here are mainly a decentralized and immutable data-storage mechanism with easily definable access controls.

The best example for this design pathway is web2-esque authentication for application login or other access controlled services. The first dApp leveraging this to its full extent was ALTER, a p2p encrypted communication platform enhanced with Secret smart contracts. The ALTER dApp allows users to store their session encryption key on the Secret Network inside of a Secret contract. Access to this contract and the key is then gated by a Wallet login functionality that ties one's crypto wallet public key to this contract - users can now sign in with their wallet and start messaging. However, this could be taken much further into the web2 realm by allowing sign in via Google web-Auth, password or even biometrics. You can also have usecases where we merely check if a user is who they say they are against identity, credit scoring or other personal information oracles.

The Authentication use case however can be taken much further. A Secret contract could not only check the input against a string it contains, but also influence actions on another chain. The first use case in this region is Unstoppable wallets, a form of on-chain Threshold wallets with unparalleled access control and ownership designed by SCRT labs. For unstoppable wallets, a Secret contract governs one part of a larger private key (MPC) and by programming access control policies into the contract, it will decide to sign or not sign a specific message. Every wallet signer commits the signature for the proposed TX to the Secret contract, the contract checks if the set policies are met and returns a valid signature that can be posted to Ethereum or any other blockchain for that matter. One could even decide to provide the Secret contract with a majority share of the private key allowing it to process transactions on its own for automated strategies or even Walletless applications where users can sign TXs with web2 authentication methods instead.

Want to learn more about Unstoppable wallets? - Watch this talk from the SCRT labs CEO and Secret Network founder Guy Zyskind at Gateway to Cosmos Prague 2023.

3. Sister contracts (ex. Private data for NFTs, verified p2p communication)

In a "sister contract" design scheme the Secret contract and the CCL consumer chain act as two separate entities with which the user interacts separately. This allows developers to work with encrypted output, something none of the other CCL design flows allow.

Sister Contracts is the idea that one can accompany applications on other networks with access controlled data or functions by leveraging a Secret contract. The simplest usecase to explain here is in the realm of NFTs, certificates or other non-fungible personally assigned data objects. It is of paramount importance to many dApps that their usecase is accessible by many, hence why developers often choose for EVM or specifically Ethereum as their home network. With Sister contracts, one can have NFTs, certificates, Invoices or any other item be created on this user-rich chain while simultaneously linking it to a counterpart on Secret network. At any moment in time, the user who owns the item on Ethereum can verify their ownership to the Secret counter-party contract to reveal additional information only visible to them.

The above scenario requires users to interact with two networks to get the full experience of the respective dApp even if cross-chain messaging is already used by the developer. This is because private metadata can only remain private if the user interacts directly with the Secret blockchain without intermediaries like public bridging solutions. Developers can abstract many of these complexities by making intuitive UIs that allow users to use the same wallet for both networks (Metamask for ex.).

Do you want to flare up your NFT with additional private metadata, have access-controlled content for your marketplace or content platform, or store sensitive information related to invoices, IDS or certificates all while keeping your assets or dApps in the most liquid markets? - Then start building a Sister contract with Data privacy for your application now!

4. Private input with delayed public output (ex. private voting, sealed bid auctions, Game-state obscuring)

Lastly, a hybrid approach is possible between the previous design flows, one where there is a private input from any other chain but what is returned is a delayed public output so that all interactions for the user remain to a single chain. As explained before, we can only guarantee output privacy for a user if they are directly interacting with Secret network, but sometimes privacy is not needed for the output - it is only needed for the input.

One such example is private voting. Voting is inherently a public system, the result matters to everyone who voted and maybe beyond that. However, it is important participants can vote at their discretion with full privacy so there is an honest and non-biased outcome. In blockchain, this is not the case: close to all DAOs and chain governance is public by default.

One can design a dApp that allows Ethereum (or any other chain) DAOs to vote privately by voting via a Secret contract instead. Users encrypt their vote and their VP with the TX encryption key of the Secret network contract. The contract remains open for a set amount of time to collect votes after which it tallies results and emits the output. The output can be sent back to the consumer chain to complete the official voting process.

This same concept applies to many different use cases like sealed bid auctions and obscuring the game-state of turn-based games. The first mainnet application on Polygon called Bidshop is using Secret Network in this way to enable a gamified auction platform. To enable these use cases, cross-chain messaging is needed from either Axelar GMP, IBC or other solutions. Bidshop will be allowing integrations for other dApps on their novel trustless message bridge as well, want to get connected? Let us know!

Unstoppable/threshold Wallet(less)

Secret contracts are an awesome tool for native account abstraction. This all comes down to the fact that Secret-contracts can store (parts of) private keys in their state without revealing them to other network participants or observers. This concept was first thought out by scrt labs in a proof of concept multiple years ago [Code], then uttilised by Alter for easy log-in (as explained here), but the newest version uses novel additive HE and MPC to create a form of Unstoppable Threshold wallets [Code]. This proof of concept is now taken by obi.money and primevault to develop walletless experiences and secure threshold wallets for the next million users.

Obi.money can help you setup smart accounts for your Secret dApp already, feel free to reach out to them!

Want to learn more about Unstoppable wallets? - Watch this talk from the SCRT labs CEO and Secret Network founder Guy Zyskind at Gateway to Cosmos Prague 2023.

Cosmos Native AuthZ/ICA

One can also use the native AuthZ module supported on Secret to have other accounts perform any specified action for any specified amount of time and limit. A usecase for this is more secure voting and autocompounding interfaces like Restake.app.

Smart contracts can also use ICA/ICS-999 (although host module is not supported yet) to control accounts on other chains over IBC and manage funds in interesting ways. Feel free to check out the codebases/Apps of Quasar and calc.finance to get an idea of what that can look like.

Smart contract based

One can also leverage cosmos wide forms of account abstraction like this one implemented by Larry from delphi.

Secret network has active integrations with:

• Axelar Satellite/app.squidrouter.com

  • Using the Axelar SDK users can bridge Ethereum and other EVM/Non-EVM assets into Cosmos and Secret arriving immediately as Wrapped SNIP-20 private tokens into their Secret account.

  • Squid is a cheaper (gas wise) version for Axelar based bridging one can use as a widget.

• Houdiniswap/Xblock

  • One can uttilise the Xblock integration or Houdini widget to let users onboard Crypto assets like XMR, BTC, ETH and more privately directly into SCRT

• Kado.money

  • Kado supports SCRT and direct Noble USDC onboarding onto Secret network. One can uttilise their Widget to allow for in-app onboarding via Paypal, Credit, Debit and more.

• TransAk

  • TransAk support SCRT onboarding using Debit, Credit, paypal and other gateways

Oracle integrations for SCRT and other asset prizes:

• OJO - Testnet

  • Integration docs

  • Oracle module docs

• Band - Mainnet

  • Integration docs

  • Proxy contract

Permissioned viewing is entirely unique to Secret Network with its encrypted state. It gives you ability to have precise control over who has access to what data. In order to determine when data is allowed to be released however, you need to have a way to prove who is trying to access it. Our two ways of doing this are through Viewing Keys and Permits/Certs.

How To Choose Between Viewing Keys and Permits

With the new Shockwave alpha update, Permits have become more efficient in almost every application. The exception is inter-contract communication permissions. Here, viewing keys still hold a lead. However, in some cases you may want to include an option to use both in your smart contract and leave the decision up to the users. Some users will have a preference for one over the other.

Smart contracts on Secret Network follow the widely used CosmWasm framework. The framework is built as a module for the Cosmos SDK and allows developers to build smart contracts with Rust which compile to WebAssmebly (Wasm). This type of efficient and fast binary, combined with the power of a low-level typed coding language, makes CosmWasm a secure and efficient way for developers to write smart contracts. Contracts on Secret have a public binary just like any other smart contract network, only the contract input, output and state is encrypted. The contracts are executed in the Wasm VM as deployed via the Wasmd Cosmos SDK module on the Secret blockchain.

Secret Contracts slightly differ from any standard CosmWasm implementation as they handle encrypted data, secure enclaves, and the key design around that. Secret currently emulates CosmWasm v1.1.9 and is completely compatible over IBC with other V1.0+ Cosmos Smart contract networks.

The components of a CosmWasm contract

A Secret contract has 4 different components as listed below each serving a different function. A deeper overview of the implementation of these 4 components/files is given in the Contract-components section.

• Instantiate - the logic that is ran once on initialization of the contract. This will usually be the initial conditions and configuration of the contract.

• Execute - this is where the transactional logic resides. These are functions that modify contract data

• Query - these are functions that are ran as read-only and cannot modify contract data

• State/storage - the long-term storage of the contract. By default, data used by contracts will be lost between transactions.

Each contract will contain these basic building blocks, with their logic being built around how they work. You can read more about the interplay of Entry-points as depicted in the graphic below in this starter guide.

Introduction

In the CosmWasm SDK, submessages are a powerful feature that allows a contract to execute additional messages within the context of its own execution. SubMsg just wraps the CosmosMsg, adding some info to it: the id field, and reply_on. reply_on describes if the reply message should be sent on processing success, on failure, or both. To create submessages, instead of setting all the fields separately, you would typically use helper constructors: SubMsg::reply_on_success, SubMsg::reply_on_error and SubMsg::reply_always.

In this tutorial, you will learn how to use submessages to execute a counter smart contract on Secret Network from another Secret Network smart contract 😊

Getting Started

2. git clone the :

Our Multi Contract System

In this tutorial, we will use submessages to execute a that is already deployed to the Secret Network Testnet. Thus, we are working with two smart contracts:

1. - which executes the Counter Contract using submessages

2. - which is executed by the Manager Contract

Designing the Manager Contract

Increment contains one parameter, the string contract. This is the contract address of the counter contract, which we will increment.

Reply entry point

Submessages offer different options for the other contract to provide a reply. There are four reply options you can choose:

Here is an example of how to handle the reply:

The submessage returns a Result containing:

• Ok(Response) if the submessage executed successfully, with an action attribute set to "increment".

• Err(ContractError) if the submessage execution failed, with the error encapsulated in a custom contract error.

Executing the Manager contract

Now let's use this manager smart contract to increment a counter smart contract with submessages!

The counter contract we will be executing is deployed here:

cd into manager/node:

Install the dependencies:

Upon successful execution, you will see a tx returned in your terminal:

Querying the counter contract

Now, let's query the counter contract to make sure it was executed correctly!

cd into counter/node:

Install the dependencies:

And run node query:

You will see that the counter contract has been incremented by 1 :)

Summary

In this tutorial, you learned how to utilize submessages in the CosmWasm SDK to perform complex, atomic operations within smart contracts on the Secret Network. This guide walked you through executing a counter smart contract from another contract, detailing the setup of a Manager Contract that triggered the Counter Contract using submessages, managing replies, and verifying the execution results 🤓

As of Secret Network V1.7 delegators can autocompound their SCRT Staking rewards using the native Restake feature.

How it works

Normally SCRT delegated to a validator accrues SCRT rewards every block as a claimable balance. With the autorestaking feature enabled however the SCRT rewards will never be claimable and also never in the claimed balance state. Every x amount of blocks (currently 1000 set by the chain parameter - restake_period) all claimable rewards, on the Restake enabled validators by the user, will be removed from the reward balance and accredited to the staked balance.

Delegators can enable Restaking independently for every validator they stake with using the set-auto-restaking command available in or on any UI implementing the Secret.JS command.

The feature only activates if the delegator has a balance with the validators larger than minimum_restake_threshold which is currently set to 10 SCRT

Introduction

Secret Network's randomness API allows developers to access random numbers in their CosmWasm contracts, enhancing the capabilities of the platform. The randomness feature is accessible within Secret Contracts through the Env struct. It includes an optional random field, which contains a random number as a Binary type. The random field is only available when the "random" feature is enabled.

Use Cases

Randomness is essential in many applications, including:

• Gaming and gambling platforms, where fair and unpredictable outcomes are crucial

• Cryptographic systems that require secure random keys or nonces

• Randomized algorithms for various use cases, such as distributed systems or optimization problems

How It Works

1. The proposer for each block generates a strong, random seed inside .

2. This seed is then included in the block header and signed by all validators who can verify its authenticity inside their SGX.

3. Secret Network's in-SGX light client prevents the proposer from simulating a block before all other validators sign it. Consequently, the proposer cannot gain maximal extractable value (MEV) by generating random seeds until they find a favorable simulation of the block.

4. Before calling the contract, the chain injects env.block.random = hkdf_sha256(block_random_seed + wasm_call_count).

   Thus each contract call gets a unique random seed.

Optimizing your code is especially important on blockchain due to the fact that inefficient code costs your users money and can jam up the entire network. With any function you make, try to complete it in as few steps as possible and avoid unnecessary computation. One of the most costly actions you can make is loading and saving data, thus you should ensure you are only saving what is needed. Aside from this, there are a few other tips we can provide.

Avoid Vector and Arrays

When dealing with large sets of data, vectors and arrays can be especially problematic because in order to save load a single item within them, you must effectively load the entire vector and all of its contents, which naturally can amount to an enormous amount of inefficiency when you only need one item! There are several ways around this: Keymap, AppendStore, or even deconstructing vectors into a set of data keyed to a counter variable. Research each options pros and cons, and choose which one is best for your particular contract.

Cosmwasm and Secret

Secret Contracts are an implementation of the Rust-based library CosmWasm, while additionally enabling computation with private metadata. This brings unique use cases to Secret Network which aren’t possible on other blockchains, and also means that Secret Contracts have features that are different from standard CosmWasm contracts including: contract hashes, a specialized approach to iterators, raw queries, and contract migration.

Contract Hashes

Contract hashes are required to bind a transaction to the specific contract being called. Otherwise, in a forked chain you could replace the called contract with one that decrypts and prints the input message.

Iterator Feature

Secret contracts do not have access to standard CosmWasm iterators because keys and values of data are encrypted when stored on-chain. This means that there is no logical structure that can allow iteration over these keys. However, Secret Labs has developed iterator functionality that can be imported using the Secret Toolkit storage package.

Raw Query

Raw queries are not available since raw data is encrypted when stored on-chain. Data can be decrypted only by the contract that owns the data, and so data is only available via permissioned contract queries (smart queries).

CW-plus

CW-plus, a toolkit for CosmWasm contracts is largely supported but might not be optimal to use in all cases. Secret has its own Toolkit called Secret-Toolkit that has the majority of CW-plus functionality. Alternatively one can alter small parts of CW-plus around the missing Iterator feature to leverage that library as well.

Working with a Singleton in CosmWasm

In CosmWasm smart contracts, a Singleton is a specialized structure that combines the concepts of PrefixedStorage and TypedStorage, allowing you to store and manage a single data entity efficiently under a specific storage key. This is particularly useful when you need to store just one instance of a state (such as contract configuration or global data) without the need for complex key management.

How Singleton Works:

pub struct Singleton<'a, T>
where
    T: Serialize + DeserializeOwned,
{
    storage: &'a mut dyn Storage,
    key: Vec<u8>,
    data: PhantomData<T>,
}

• storage: &'a mut dyn Storage: The Singleton holds a mutable reference to the storage layer, which is where the contract data is stored on-chain. This reference allows it to interact with and modify the stored data.

• key: Vec<u8>: The Singleton operates on a single storage key, provided during its instantiation. This key is typically transformed using to_length_prefixed to avoid collisions with other stored data, ensuring that the contract can safely manage this unique piece of state.

• data: PhantomData<T>: Rust’s PhantomData is a marker for the data type T without actually holding an instance of it. This allows the Singleton to enforce that it works with a specific type (T) that must implement Serialize and DeserializeOwned traits, which are essential for encoding/decoding the data stored in the singleton.

Key Features of Singleton:

1. No Need for Multiple Keys: A Singleton simplifies storage management by removing the need to manually manage multiple keys. The storage key is predefined in the constructor, and all operations (read, write, update) are tied to this single key. This ensures you are only ever working with one data object in storage.

2. Type-Safe Storage: The Singleton uses TypedStorage functionality, which ensures that the data stored and retrieved from the storage is type-safe. This means you always work with the exact type you’ve defined (in this case, T), reducing the risk of errors during serialization and deserialization.

3. Avoids Key Collisions: By applying the to_length_prefixed transformation to the given storage key, the Singleton ensures there are no name collisions in storage. This is particularly useful in larger contracts where multiple data points might otherwise share similar key names.

There are common wrapper functions that are included in the state.rs of most secret contract templates, which are save, load, may_load, remove, and update.

save

The save function overwrites previously saved data associated to that storage key. save will serialize the model and store, returns an error on serialization issues:

 pub fn save(&mut self, data: &T) -> StdResult<()> {
        self.storage.set(&self.key, &to_vec(data)?);
        Ok(())
    }

• Purpose: It takes a reference to the storage and the data to be saved (usually the contract's state).

• Usage: You call save when you want to persist new data or update existing data in storage.

load

This function reads or retrieves data from the contract's state. It is commonly used when you need to access a piece of data stored in the contract, such as the current state or configuration.

 /// load will return an error if no data is set at the given key, or on parse error
    pub fn load(&self) -> StdResult<T> {
        let value = self.storage.get(&self.key);
        must_deserialize(&value)
    }

• Purpose: It accesses the storage and loads the state associated with the provided key.

• Usage: load is used whenever the contract needs to read existing data, such as fetching the configuration or state before making any modifications.

may_load

 /// may_load will parse the data stored at the key if present, returns Ok(None) if no data there.
    /// returns an error on issues parsing
    pub fn may_load(&self) -> StdResult<Option<T>> {
        let value = self.storage.get(&self.key);
        may_deserialize(&value)
    }

• Purpose: This function attempts to retrieve and deserialize data from storage, returning Ok(None) if no data exists at the given key. It returns an error only if deserialization fails.

• Usage: may_load is used when the existence of the data is optional. It allows you to safely check if data exists and handle cases where the data might not be present.

• Behavior: It fetches the data associated with the key and attempts to deserialize it using may_deserialize. If the key does not have any data, it returns Ok(None) instead of an error, making it more forgiving than load.

remove

    pub fn remove(&mut self) {
        self.storage.remove(&self.key)
    }

• Purpose: This function deletes or removes data associated with a specific key from the contract’s storage.

• Usage: remove is used when you no longer need to store certain data in the contract and want to free up space by removing the key-value pair from storage.

• Behavior: It accesses the storage object and deletes the data associated with the provided key.

update

This function loads, modifies, and then saves data back to the contract's state. It’s commonly used when the contract state needs to be modified, such as incrementing a counter or updating a setting.

/// update will load the data, perform the specified action, and store the result
    /// in the database. This is shorthand for some common sequences, which may be useful
    ///
    /// This is the least stable of the APIs, and definitely needs some usage
    pub fn update<A, E>(&mut self, action: A) -> Result<T, E>
    where
        A: FnOnce(T) -> Result<T, E>,
        E: From<StdError>,
    {
        let input = self.load()?;
        let output = action(input)?;
        self.save(&output)?;
        Ok(output)
    }

• Purpose: It allows for atomic updates to the state by accepting a closure (a function passed as an argument) that modifies the data and then saves it back to storage.

• Usage: update is ideal for changing existing data in the state, like incrementing a value, while ensuring that the storage operation is performed safely in one transaction.

Summary

• save: Persists or updates state in the contract’s storage.

• load: Retrieves and reads existing data from the contract’s storage.

• may_load: Fetches and deserializes data if it exists, returning Ok(None) if no data is found at the key, and an error if deserialization fails.

• remove: Deletes the data associated with a specific key from storage.

• update: Modifies existing data in storage, allowing for atomic and safe updates.

These wrapper functions provide clean abstractions to manage the contract's state, making the contract logic easier to write and maintain. They are especially useful in ensuring that storage operations (which are critical for on-chain data) are handled efficiently and consistently across the contract.

Contract code hash helper function

To retrieve a Secret Network smart contract's code hash from within a Secret contract call, you can use Stargate queries to directly query the on-chain data from inside the contract.

This helper function is particularly interesting if you desire to make complicated contract structures that involve submessages or just cross-contract messages to different Secret Network contracts. With this code snippet, you do not need to supply the code_hash of each contract that you are going to call in submessage or normal messages. It is sufficient to know the contract address of the other contract, the code snipped will fetch the latest on chain code_hash for you.

The Secret Network team has designed a helper function, get_contract_code_hash, exactly for this purpose.

Simply add the Anybuf package and the "stargate" feature for cosmwasm-std to your cargo.toml:

[dependencies]
cosmwasm-std = { package = "secret-cosmwasm-std", version = "1.1.10", features = ["stargate"]}
anybuf = {version = "0.5.0"}

And then add the function to your contract:

fn get_contract_code_hash(deps: DepsMut, contract_address: String) -> StdResult<String> {
    let code_hash_query: cosmwasm_std::QueryRequest<cosmwasm_std::Empty> = cosmwasm_std::QueryRequest::Stargate {
        path: "/secret.compute.v1beta1.Query/CodeHashByContractAddress".into(),
        data: Binary(Anybuf::new()
        .append_string(1, contract_address)
        .into_vec())
    };

    let raw = to_vec(&code_hash_query).map_err(|serialize_err| {
        StdError::generic_err(format!("Serializing QueryRequest: {}", serialize_err))
    })?;

    let code_hash = match deps.querier.raw_query(&raw) {
        SystemResult::Err(system_err) => Err(StdError::generic_err(format!(
            "Querier system error: {}",
            system_err
        ))),
        SystemResult::Ok(ContractResult::Err(contract_err)) => Err(StdError::generic_err(format!(
            "Querier contract error: {}",
            contract_err
        ))),
        SystemResult::Ok(ContractResult::Ok(value)) => Ok(value)
    }?;

    // Remove the "\n@" if it exists at the start of the code_hash
    let mut code_hash_str = String::from_utf8(code_hash.to_vec()).map_err(|err| {
        StdError::generic_err(format!("Invalid UTF-8 sequence: {}", err))
    })?;

    if code_hash_str.starts_with("\n@") {
        code_hash_str = code_hash_str.trim_start_matches("\n@").to_string();
    }

    Ok(code_hash_str)
}