Basics

• Overview

• Cross-chain Messaging with IBC hooks

Usecases

• Key Value store

• VRF

• Confidential Voting

• Sealed Bid Auctions

Supported Networks

• Mainnet

• Testnet

Secret Network's CCL (Confidential Computing Layer) IBC Toolkit is a cross-chain messaging and confidential computation SDK for Cosmos developers.

The toolkit allows Cosmos developers to build novel cross-chain applications such as:

• private DAO voting mechanisms

• secure random number generation (Secret VRF)

• confidential data access control via Secret NFTs

• encrypted DeFi order books

• and more!

Continue to Cross-Chain messaging to learn how to use Secret Network's Confidential Computing Layer SDK , or dive into the Key value store tutorial here🔥

Overview

IBC-Hooks is an IBC middleware that uses incoming ICS-20 token transfers to initiate smart contract calls. This allows for arbitrary data to be passed in along with token transfers. This is useful for a variety of use cases such as cross-chain token swaps, auto-wrapping of SNIP-20 tokens, General Message Passing (GMP) between Secret Network and EVM chains, and much more! The mechanism enabling this is a memo field on every ICS20 transfer packet as of IBC v3.4.0. Wasm hooks is an IBC middleware that parses an ICS20 transfer, and if the memo field is of a particular form, it executes a Wasm contract call.

ICS20 Packet Structure

ICS20 is JSON native, so JSON is used for the memo format:

{
  //... other ibc fields omitted for example
  "data": {
    "denom": "denom on counterparty chain (e.g. uatom)", // will be transformed to the local denom (ibc/...)
    "amount": "1000",
    "sender": "addr on counterparty chain", // will be ignored and shown to the contract as a null sender (cannot be verifed over IBC)
    "receiver": "secret1contractAddr",
    "memo": {
      "wasm": {
        "contract": "secret1contractAddr",
        "msg": {
          "raw_message_fields": "raw_message_data"
        }
      }
    }
  }
}

An ICS20 packet is formatted correctly for Wasm hooks if the following all hold:

• memo is not blank

• memo is valid JSON

• memo has at least one key, with value "wasm"

• memo["wasm"] has exactly two entries, "contract" and "msg"

• memo["wasm"]["msg"] is a valid JSON object

• receiver == memo["wasm"]["contract"]

ICS20 Packet Execution Flow

Before Wasm hooks:

• Ensure the incoming IBC packet is cryptographically valid

• Ensure the incoming IBC packet has not timed out

In Wasm hooks, before packet execution:

• Ensure the packet is correctly formatted (as defined above)

• Edit the receiver to be the hardcoded IBC module account

In Wasm hooks, after packet execution:

• Construct wasm message as defined above

• Execute wasm message

• If wasm message has error, return ErrAck

• Otherwise continue through middleware

Auto-wrapping of SNIP-20 Example

The following contract receives funds from IBC, wraps them as SNIP-20 tokens, and then transfers them to the recipient that is specified in the ibc-hooks message:

#[entry_point]
pub fn execute(_deps: DepsMut, env: Env, info: MessageInfo, msg: Msg) -> StdResult<Response> {
    match msg {
        Msg::WrapDeposit {
            snip20_address,
            snip20_code_hash,
            recipient_address,
        } => Ok(Response::default().add_messages(vec![
            CosmosMsg::Wasm(cosmwasm_std::WasmMsg::Execute {
                contract_addr: snip20_address.clone(),
                code_hash: snip20_code_hash.clone(),
                msg: to_binary(&secret_toolkit::snip20::HandleMsg::Deposit { padding: None })
                    .unwrap(),
                funds: info.funds.clone(),
            }),
            CosmosMsg::Wasm(cosmwasm_std::WasmMsg::Execute {
                contract_addr: snip20_address,
                code_hash: snip20_code_hash,
                msg: to_binary(&secret_toolkit::snip20::HandleMsg::Transfer {
                    recipient: recipient_address,
                    amount: info.funds[0].amount,
                    memo: None,
                    padding: None,
                })
                .unwrap(),
                funds: vec![],
            }),
        ])),
        }
    }

Ack callbacks

A contract that sends an IBC transfer may need to listen for the acknowledgment (ack) of that packet. To allow contracts to listen to ack of specific packets, we provide Ack callbacks. The sender of an IBC transfer packet may specify a callback in the memo field of the transfer packet when the ack of that packet is received.

Ack callback implementation

For the callback to be processed, the transfer packet's memo should contain the following in its JSON:

{"ibc_callback": "secret1contractAddr"}

The WASM hooks will keep the mapping from the packet's channel and sequence to the contract in storage. When an ack is received, it will notify the specified contract via an execute message.

Interface for receiving the Acks and Timeouts

The contract that awaits the callback should implement the following interface for a sudo message:

#[cw_serde]
pub enum IBCLifecycleComplete {
    #[serde(rename = "ibc_ack")]
    IBCAck {
        /// The source channel (secret side) of the IBC packet
        channel: String,
        /// The sequence number that the packet was sent with
        sequence: u64,
        /// String encoded version of the ack as seen by OnAcknowledgementPacket(..)
        ack: String,
        /// Weather an ack is a success of failure according to the transfer spec
        success: bool,
    },
    #[serde(rename = "ibc_timeout")]
    IBCTimeout {
        /// The source channel (secret side) of the IBC packet
        channel: String,
        /// The sequence number that the packet was sent with
        sequence: u64,
    },
}

/// Message type for `sudo` entry_point
#[cw_serde]
pub enum SudoMsg {
    #[serde(rename = "ibc_lifecycle_complete")]
    IBCLifecycleComplete(IBCLifecycleComplete),
}

#[entry_point]
pub fn sudo(_deps: DepsMut, _env: Env, msg: SudoMsg) -> StdResult<Response> {
    match msg {
        SudoMsg::IBCLifecycleComplete(IBCLifecycleComplete::IBCAck {
            channel,
            sequence,
            ack,
            success,
        }) => todo!(),
        SudoMsg::IBCLifecycleComplete(IBCLifecycleComplete::IBCTimeout {
            channel,
            sequence,
        }) => todo!(),
    }
}

IBC Hooks for Cross-Chain Messaging

IBC-Hooks is an IBC middleware that uses incoming ICS-20 token transfers to initiate smart contract calls. Secret Network created a Cosmos Developer SDK that uses IBC hooks to execute Secret gateway contracts, which allows Cosmos developers on other chains to use Secret as a privacy layer for your chain.

The SDK abstracts the complexities involved in interacting with the Secret Network for applications that deal with Cosmos wallets. It introduces a secure method for generating confidential messages and reliably authenticating users at the same time using the chacha20poly1305 algorithm.

The SDK can be used be for developing major gateways that forward incoming messages to Secret Network, as well as built-in support for confidential messages directly in other contracts. To learn by doing, start with the key value store developer tutorial here.

SDK Requirements

• IBC Transfer channel between the consumer chain and Secret Network

Secret Network's IBC Developer Toolkit is available on any Cosmos chain that has established an IBC transfer channel with Secret Network!

Overview

Secret Network's Confidential Computation SDK uses IBC hooks to seamlessly handle cross-chain encrypted payloads, which means Cosmos developers can now encrypt and decrypt messages with a simple token transfer.

This tutorial explains how to upload your own Key-value store contract on Secret Network, which you can use to encrypt values on Secret Network and transmit them cross-chain from a Cosmos chain of your choice! After this tutorial, you will have the tools you need to encrypt messages on any IBC hooks-enabled Cosmos chain.

Getting Started

To get started, clone the repository:

git clone https://github.com/writersblockchain/cosmos-ccl-sdk.git

Configuring Environment Variables

Install the dependencies:

npm install

Create an env file. Simply update env.testnet to omit ".testnet" from the file name and then add your wallet's mnemonics:

SECRET_MNEMONIC=""
SECRET_CHAIN_ENDPOINT="https://lcd.mainnet.secretsaturn.net"
SECRET_CHAIN_ID="secret-4"
SECRET_TOKEN="uscrt"


CONSUMER_MNEMONIC=""
CONSUMER_CHAIN_ENDPOINT="https://rpc.osmosis.zone:443"
CONSUMER_CHAIN_ID="osmosis-1"
CONSUMER_TOKEN="uosmo"
CONSUMER_PREFIX="osmo"
CONSUMER_GAS_PRICE="0.25"
CONSUMER_DECIMALS=6

Upload the encryption contract on Secret Network

Now that you have your environment configured, it's time to upload the encryption contract to Secret Network.

First, compile the contract:

make build-mainnet-reproducible

This compiles the contract and creates a wasm file in the following directory:

"./optimized-wasm/gateway_simple.wasm.gz"

The files that make up the IBC SDK, including the script to upload the contract to Secret Network, are in ./src.

Compile the typescript files so you can execute them with node:

npm run build

Once you run the above command, the typescript files in ./src will be compiled as javascript files in ./dist.

Upload and instantiate the encryption contract on Secret Network Mainnet:

node dist/deploy.js

In your terminal, a codeID, codeHash, and contractAddress will be returned:

"code_id": 8882,
"code_hash": "f3c2e28cd1574d128ded60ce967cdb46f7515d807be49127bcc9249c5fd97802",
"address": "secret1q0mycclu927u5m0tn50zgl5af4utrlkzz706lm"

Update contracts.json with your contractAddress and codeHash accordingly:

{
    "gateway": {
        "address": "secret1q0mycclu927u5m0tn50zgl5af4utrlkzz706lm",
        "hash": "d4a018804bf63b6cfd5be52b650368e8ad89f57c66841f6b2da7ee143dfc75fb"
    }
}

Encrypt a payload with Typescript SDK

Now that you have your encryption smart contract uploaded on Secret Network, let's use it to store encrypted messages from Osmosis Mainnet Most of the ECDH cryptography has been abstracted away so there are only a few values you need to change.

The functions in ./src are helper functions that help us configure cross-chain network clients, IBC token transfers, etc. However, there is also an additional function which executes the gateway contract called execute-gateway.js! Execute-gateway.js demonstrates sending a token transfer to store an unencrypted as well as an encrypted message.

To encrypt the payload, run execute-gateway.js:

node dist/execute-gateway.js

This will initiate a Token transfer:

Sending IBC token...
receiver: secret1q0mycclu927u5m0tn50zgl5af4utrlkzz706lm
token: uosmo
amount: 1
source_channel: channel-88
memo: {"wasm":{"contract":"secret1q0mycclu927u5m0tn50zgl5af4utrlkzz706lm","msg":{"extension":{"msg":{"store_secret":{"text":"new_text_68ss4"}}}}}}

As well as an IBC Acknowledgement response:

Broadcasted IbcTX. Waiting for Ack: Promise { <pending> }
ibc Ack Received!
info ack: {
  packet: {
    sequence: '252',
    source_port: 'transfer',
    source_channel: 'channel-88',
    destination_port: 'transfer',
    destination_channel: 'channel-1',
    data: Uint8Array(887) [
      123,  34,  97, 109, 111, 117, 110, 116,  34,  58,  34,  49,
       34,  44,  34, 100, 101, 110, 111, 109,  34,  58,  34, 117,
       97, 120, 108,  34,  44,  34, 109, 101, 109, 111,  34,  58,
       34, 123,  92,  34, 119,  97, 115, 109,  92,  34,  58, 123,
       92,  34,  99, 111, 110, 116, 114,  97,  99, 116,  92,  34,
       58,  92,  34, 115, 101,  99, 114, 101, 116,  49, 113,  48,
      109, 121,  99,  99, 108, 117,  57,  50,  55, 117,  53, 109,
       48, 116, 110,  53,  48, 122, 103, 108,  53,  97, 102,  52,
      117, 116, 114, 108,
      ... 787 more items
    ],
    timeout_height: { revision_number: '0', revision_height: '0' },
    timeout_timestamp: '1722277043000000000'
  },

Congrats! You have now used the Secret Network CCL SDK to encrypt a string on Osmosis Mainnet!

Encryption SDK - how it works

Now that you have used Secret Network's CCL SDK to successfully encrypt a string cross-chain, let's examine the gateway smart contract you deployed on Secret Network to understand how everything works underneath the hood.

At a high level, you can think of the SDK like so:

1. There is a gateway contract deployed to Secret Network, which has the ability to encrypt a string, as well as query the encrypted string.

2. The gateway contract imports helper functions from the SDK, which is where the gateway contract imports encryption and query types, etc.

Now let's examine each of the gateway contract's files to understand how it encrypts a user-inputted string.

state.rs

state.rs is where we define the keymap that holds our encrypted strings. The keymap SECRETS is designed to store a mapping from account user addresses (as strings) to their secrets (also as strings), using the Bincode2 serialization format.

msg.rs

msg.rs is where we define the functionality of our gateway contract. It has 2 primary functionalities: storing encrypted strings and querying encrypted strings. Note that the types ExecuteMsg and QueryMsg are defined in the SDK here.

• GatewayExecuteMsg: Defines execution messages that can be sent to the contract, including resetting an encryption key, sending encrypted data, and extending with additional message types.

• GatewayQueryMsg: Defines query messages that can be sent to the contract, including querying for an encryption key, querying with authentication data, querying with a permit, and extending with additional query types.

contract.rs

contract.rs contains the smart contract logic which allows the following:

• Execution: Processes messages to reset the encryption key or store a secret, ensuring only authorized access.

• Querying: Handles queries to retrieve the encryption key and perform permissioned queries.

The encryption logic, handle_encrypted_wrapper, is imported from the SDK at line 55. This is where the encryption magic happens ⭐.

You can review the function in the SDK here. It has the following functionality:

1. Check if Message is Encrypted:

   • If the message is encrypted (msg.is_encrypted()), it proceeds with decryption.

2. Extract Encryption Parameters:

   • Retrieves the encryption parameters from the message (msg.encrypted()).

3. Check Nonce:

   • Ensures the nonce has not been used before to prevent replay attacks.

4. Load Encryption Wallet:

   • Loads the encryption wallet from storage.

5. Decrypt Payload:

   • Decrypts the payload using the wallet and the provided parameters (payload, user_key, and nonce).

      let decrypted  = wallet.decrypt_to_payload(
            &params.payload,
            &params.user_key,
            &params.nonce,
        )?;

1. Verify Credentials:

• Constructs a CosmosCredential from the decrypted data.

• Inserts the nonce into storage to mark it as used.

• Verifies the sender using the verify_arbitrary function with the credential.

1. Deserialize Inner Message:

• Converts the decrypted payload into the original message type E.

• Ensures the decrypted message is not encrypted (nested encryption is not allowed).

1. Return Decrypted Message and Updated Info:

• Returns the decrypted message and updated MessageInfo with the verified sender.

Summary

In this tutorial, you learned how to utilize Secret Network's Confidential Computation SDK to encrypt and decrypt messages across Cosmos chains using IBC hooks. By following the steps outlined, you successfully:

1. Configured the development environment with the necessary dependencies and environment variables.

2. Uploaded and instantiated an encryption contract on the Secret Network mainnet.

3. Encrypted and transmitted a payload from the Osmosis Mainnet to the Secret mainnet using IBC token transfers.

With these tools and knowledge, you are now equipped to handle cross-chain encrypted payloads on any IBC hooks-enabled Cosmos chain, enhancing the security and confidentiality of your blockchain applications.

For any Cosmos chain, you can use encrypted payloads to execute and query confidential messages on Secret Network smart contracts.

Using our Confidential Computation Layer (CCL) SDK, you can seamlessly handle encrypted payloads, as the master gateway contract on Secret Network automatically decrypts the payload and hands the decrypted payload over to the target contract.

The encryption of the payload is done using the , an algorithm.

The key for this symmetric encryption is created by using the (ECDH) scheme, comprising of two components:

1. An extra encryption public key provided from the Secret Gateway Contract

2. A randomly created (ephemeral) encryption private key on the user side (independent of the user wallet's private key)

Combining both of these keys together via the ECDH Scheme yields our encryption key, which we use to encrypt the payload with ChaCha20-Poly1305.

As a first example for this, we have used the CCL SDK to encrypt a string and subsequently store it in a Secret Network contract.

Overview

The is a relayer implementation written in Golang. It can create clients, connections, and channels, as well as relay packets and update and upgrade clients.

In order to use Secret Network's IBC Developer Toolkit, you need an IBC transfer channel established between Secret Network and your Cosmos chain.

In this section, you will learn:

• How to get started with the Go relayer.

• Basic Go relayer commands.

• How to create a transfer channel between Secret Network testnet and Neutron testnet.

Let's get started!

Installing Go Relayer

Clone the :

Build the Go relayer:

To check that the installation was successful, run:

Which returns:

Configuring Go Relayer

The configuration data is added to the config file, stored at $HOME/.relayer/config/config.yaml by default.

If this is the first time you run the relayer, first initialize the config with the following command:

And check the config with:

Now you are all set to add the chains and paths you want to relay on, add your keys and start relaying. You will set up two testnet chains: Neutron's pion-1 and Secret Network's pulsar-3.

Add chain configs

Create wallet keys

Create new keys for the relayer to use when signing and relaying transactions:

Query your key balances:

Then, dit the relayer's key values in the config file to match the key-names chosen above. The configuration data is added to the config file, stored at $HOME/.relayer/config/config.yaml:

Configure path metadata in the config file

You configured the chain metadata, now you need path metadata.

Update your config file like so to use a configuration path that has been tested in production:

Alternatively, you can also create your own path like so:

If you create your own path, be sure to add your transfer channels to the channel filters in the config.yaml like so:

Check Configuration Status

Before starting to relay and after making some changes to the config, you can check the status of the chains in the config:

Which returns this output when healthy:

And you can check the status of the paths in the config:

Starting the Relayer

Finally, start the relayer on the desired path. The relayer will periodically update the clients and listen for IBC messages to relay:

Further reading:

CCL SDK

Data Structures

The essential parameters required for chacha20poly1305flow are defined in the following data structure:

EncryptedParams

A data structure that is visible to all network participants and can be transmitted over non-secure channels

EncryptedPayload

Data meant to be encrypted and stored in the payload field of EncryptedParams

Custom Contract Message

Your contract must define an endpoint where a user can pass all the required fields of the EncryptedParams. E.g:

If you want to define a custom message, rename the fields, or add additional fields, there is a helpful trait WithEncryption that you can implement. It simply tells the compiler how to extract the essential parameters from your custom message and turn it into EncryptedParams

Implementing the trait for your message will allow you to use other useful methods of the SDK (like handle_encrypted_wrapper) that significantly simplify the development experience.

Example of the implementation for the ExecuteMsg is as follows:

Extending existing data structures

The SDK has multiple data structures that already implement WithEncryption trait and also use the template engine of Rust to make them easily extendable. Take for example the following message:

You can define a new message that extends the GatewayExecuteMsg by simply providing a new type for the Extension instead of the default Option<Empty> like this:

Your extended type in this case is available under MyGatewayExecuteMsg::Extension variant and you can use it in your contract like this:

Functions and methods

handle_encrypted_wrapper

The encryption logic, handle_encrypted_wrapper, is where the encryption magic happens ⭐

1. Check if Message is Encrypted:

   • If the message is encrypted (msg.is_encrypted()), it proceeds with decryption.

2. Extract Encryption Parameters:

   • Retrieves the encryption parameters from the message (msg.encrypted()).

3. Check Nonce:

   • Ensures the nonce has not been used before to prevent replay attacks.

4. Load Encryption Wallet:

   • Loads the encryption wallet from storage.

5. Decrypt Payload:

   • Decrypts the payload using the wallet and the provided parameters (payload, user_key, and nonce).

1. Verify Credentials:

• Constructs a CosmosCredential from the decrypted data.

• Inserts the nonce into storage to mark it as used.

• Verifies the sender using the verify_arbitrary function with the credential.

1. Deserialize Inner Message:

• Converts the decrypted payload into the original message type E.

• Ensures the decrypted message is not encrypted (nested encryption is not allowed).

1. Return Decrypted Message and Updated Info:

• Returns the decrypted message and updated MessageInfo with the verified sender.

chacha20poly1305_decrypt

The following function uses the following types for as the input parameters:

• cosmwasm_std::Binary,

• std::vec::Vec.

• [u8]

• and others that implement Deref<Target = [u8]> trait

Various authentication utilities

To verify a message that was was signed through a method cosmos arbitrary (036) message format, you can use the following function:

The method takes in a CosmosCredential struct as an argument which is a a helpful wrapper over essential required fields required for the verification:

Both CosmosCredential and EncryptedParams can be used with String or base64 encoded Binary types

To generate a preamble message for the cosmos arbitrary (036) message format, you can use the following utility function:

The function uses a hardcoded JSON string with all the required keys present and sorted.

Typescript Demo

Dependencies

For encryption, we recommend using @solar-republic/neutrino which has useful chacha20poly1305related functionalities and additional primitives for generating ephemereal lightweight wallets. Installation:

For signing, encoding and other cryptographic needs in the Cosmos ecosystem, it is common to use the suite of @cosmjs packages. You can install the following:

If you are developing in the browser environment or connecting to a public network you might also need

Generating Wallets

For chacha20poly1305, we need to use a crypthographic keypair and it's advised to use one that isn't the same as the user's wallet. The SDK provides a method for generating a new wallet that can be used for encryption purposes. For our purposes, we just need a private / public keys of Secp256k1 type and there are various ways to generate them.

@cosmjs/crypto

@solar-republic/neutrino

@secretjs

Query Client

Before proceeding to encryption, you might want to create a quering client that will be used for querying the state and contract of the Secret Network. At the very least, it is requited for fetching the public key of a gateway contract for deriving a shared key used later for encryption.

To perform a simple query on a secret contract we can use methods from @solar-republic/neutrino:

For more persistent use-cases you can use secretjs:

Signatures

Browser Wallets

Most of the Cosmos wallets provide a method for signing arbitrary messages following the mentioned specification.

Although the API method requires a chainId, it is set to empty string before signing the message

Cosmology

CosmJS

Manually

Getting Signer and Signer Address

Firstly we need to get an amino signer that will be used for generating the signature. @cosmjs has a defined interface OfflineAminoSigner with signAmino and getAccounts methods and any other signer that implements it can be used for the purpose.

Generating the message and StdSignDoc

To use signAmino, we need to generate a StdSignDoc object that will be used for signing the message to pass as an argument.

CosmJS provides a function for this:

The 036 standard requires the message fields to AminoMsg to be:

As for the rest of the fields, they can be set to an empty string or 0. The final example will look like this:

After getting the document we can sign it with the signer:

Encryption

After getting a public key of a gateway contract you can use it to derive a shared key like this:

Encrypting + Signing

Produced digest of hashing the ciphertext can be used as our message that we want to sign according to the 036 standard. The final message will look like this:

After this we are getting all the required fields for creating an EncryptedPayload message or an ExecuteMsg::Encrypted { ... }

Broadcasting the message

The encrypted message is safe to broadcast over public blockchain and other infrastructure. A common use-case in context of Cosmos account might be broadcasting it over IBC originating from a chain other than the Secret Network.

The potential use-case might involve broadcasting the message by initiating an IBC message directly and attaching the message as a payload (IBC-Hook) or passing the message to a smart contract on a remote chain to process and bridge it to the Secret Network.

Since Cosmwasm is quite flexible with defining messages due to supporting JSON serialization, it is possible the process is very similar in both cases so we only going to cover IBC-hooks for simplicity:

Secret VRF (Verifiable Random Function)

Secret VRF is a provably fair and verifiable on-chain random number generator (RNG) that enables smart contracts to access random values without compromising security or usability. Coupled with cross-chain interoperable smart contracts using IBC hooks, Secret Network enables developers and projects across the Cosmos access to state-of-the-art on-chain RNG.

Use Secret VRF to build reliable smart contracts for any application that relies on unpredictable outcomes:

• NFT Minting: Utilize randomness for features like unordered minting, trait randomization, and identity numbering, enhancing the authenticity and security of NFT collections.

• Web3 Gaming: Apply randomness in gambling, damage calculation, loot boxes, and boss drops to build trust among players by ensuring fairness and preventing any player from having an unfair advantage.

• DAO Operations: Employ randomness for wallet initialization, task assigning, unordered voting/liquidations, and order book ordering, facilitating equitable and secure decentralized governance and operations.

Getting Started

To use SecretVRF on any IBC-enabled chain with IBC hooks, all that is required is:

1. An IBC transfer channel between Secret Network and the consumer chain that receives randomness.

2. Uploading the RNG Consumer Contract to your chain and directing it to your chain's transfer channel

Requesting Randomness

Git clone the IBC hooks randomness repository:

git clone https://github.com/SecretFoundation/ibchooks-secretVRF.git

Update the SECRET_TRANSFER_CHANNEL_ID and the CHAIN_TRANSFER_CHANNEL_ID to the channel-id for your IBC-enabled chain:

//Juno
const SECRET_TRANSFER_CHANNEL_ID: &str = "channel-8";
const CHAIN_TRANSFER_CHANNEL_ID: &str = "channel-48";

Once you have updated the transfer channels, compile the contract:

make build-mainnet-reproducible

Upload the compiled contract:

junod tx wasm store consumer-side/artifacts/secret_ibc_rng_consumer_side_proxy.wasm --from <your-wallet> --chain-id juno-1 --node https://rpc.juno.chaintools.tech:443 --gas 1200000 --gas-prices 0.075ujuno

Upon successful upload, a code_id is returned:

{"key":"code_id","value":"4210"}]}]}]"

Instantiate the contract with the returned code_id:

junod tx wasm instantiate 4210 '{}' --label RNG-IBC-JUNO --no-admin --from <your-wallet> --chain-id juno-1 --node https://rpc.juno.chaintools.tech:443 --gas 200000 --gas-prices 0.075ujuno

Upon succesful instantiation, a contract_address is returned:

[{"key":"_contract_address","value":"juno1srwcjsaslt9ewujg6wcpcwv08lsrsn6rx6ja5mqx4qngqjh8cugqt73c8m"},

Now that you've instantiated your randomness contract, all that's left is to request randomness! Simply execute request_random:

junod tx wasm execute "juno1srwcjsaslt9ewujg6wcpcwv08lsrsn6rx6ja5mqx4qngqjh8cugqt73c8m" '{"request_random":{"job_id":"1"}}' --from <your-wallet> --chain-id juno-1 --node https://rpc.juno.chaintools.tech:443 --gas 200000 --gas-prices 0.075ujuno --amount 1ujuno

A transaction hash will be returned:

txhash: 92D5BDA1344529B58EAD5A0068A807632F46BCCCF05CF10E67211F9CBBD2A74B

Navigate to the recently received transactions for your contract:

And then view the magic of cross-chain randomness with IBC hooks 😍:

{"amount":"1","denom":"transfer/channel-8/ujuno","memo":"{\"wasm\": {\"contract\": \"juno1srwcjsaslt9ewujg6wcpcwv08lsrsn6rx6ja5mqx4qngqjh8cugqt73c8m\", \"msg\": {\"receive_random\": {\"job_id\": \"1\", \"randomness\": \"bjFHP7rrLwP4f6fpGpeTt5+N1zPiTO+y7da7RI9kHzk=\", \"signature\": \"y+Kwu0T2gwRwDZGCdDPzGrm6hE2S2UZF1e1jm47pv85pdRdP7HdOfl6T+VKfAE4hPxSWJ5LBcTSNZ+b0KTe0xQ==\"}}}}","receiver":"juno1srwcjsaslt9ewujg6wcpcwv08lsrsn6rx6ja5mqx4qngqjh8cugqt73c8m","sender":"secret1up0mymn4993hgn7zpzu4je34w0n5s7l0mem7rk"}

Congrats! You've just sent a verifiable on-chain random byte with SecretVRF 🙌.

Conclusion

Secret VRF revolutionizes blockchain applications by providing a secure and verifiable source of randomness, critical for fairness in NFT minting, gaming, and DAO operations. Its seamless integration with IBC hooks enables cross-chain interoperability, allowing developers across the Cosmos ecosystem to build more reliable and elegant smart contracts.

If you have any questions, join our discord and a Secret developer will assist you ASAP.

Overview

This tutorial explains how to upload a confidential sealed bid auction contract on Secret Network, which you can execute and query for private auctions on any IBC-connected chain. 🚀

The SDK abstracts IBC interactions with the Secret Network for applications that use Cosmos wallets. It introduces a secure method for generating confidential messages and reliably authenticating users at the same time using the chacha20poly1305 algorithm.

In this tutorial you will learn:

1. How to run the fullstack cross-chain Next.js application in your browser.

2. How to use the core smart contract logic for confidential cross-chain auctions using IBC hooks.

3. How to deploy your very own auction contract on Secret Network.

Getting Started

Clone the repo:

git clone https://github.com/writersblockchain/cosmos-ccl-encrypted-payloads-demo

cd into next-frontend and install the dependencies:

cd next-frontend && npm install

Add environment variables in cosmos-ccl-encrypted-payloads-demo/next-frontend:

NEXT_PUBLIC_SECRET_CHAIN_ENDPOINT="https://lcd.mainnet.secretsaturn.net"
NEXT_PUBLIC_SECRET_CHAIN_ID="secret-4"
NEXT_PUBLIC_CONSUMER_CHAIN_ID="osmosis-1"

Start the application:

npm run dev

The fullstack Next.js application should now be running in your browser! You can use it to create confidential auctions and bids. Now that you have the application running in your browser, let's dive into the smart contract logic!

Understanding the contract

Execution Messages

To encrypt auction bids using the SDK, we use the enum called InnerMethods, which wraps the possible actions in the auction smart contract, namely, CreateAuctionItem and Bid, with the SDK encryption logic:

#[cw_serde]
pub enum InnerMethods {
    CreateAuctionItem {
        name: String,
        description: String,
        end_time: Uint64
    },

    Bid {
        auction_id: Uint64,
        amount: Uint128
    },
}

pub type ExecuteMsg                 =   GatewayExecuteMsg<InnerMethods>;

InnerMethods leverage the SDK by using the GatewayExecuteMsg to structure encrypted execution messages for cross-chain auction management and bidding:

#[cw_serde]
pub enum ExecuteMsg {

    Encrypted {
        payload             :   Binary,
        payload_signature   :   Binary,
        payload_hash        :   Binary,
        user_key            :   Binary,
        nonce               :   Binary,
    }

    ResetEncryptionKey  { },

    Extension {
        msg: {
            CreateAuctionItem { ... }   /   Bid { ... },   
        }
    }
}

Understanding the Encryption SDK

The magic of Secret Network's encryption SDK happens here, with handle_encrypted_wrapper:

let (
        msg, 
        info
    ) = sdk::handle_encrypted_wrapper(
        deps.api, deps.storage, info, msg
    )?;

The Extension variant inExecuteMsg leverages the functionality of handle_encrypted_wrapper because the wrapper decrypts and verifies the entire message payload before the Extension message is processed. Here’s how it works:

1. handle_encrypted_wrapper Applies to the Entire Input:

   • When the execute function is called, the msg and info parameters are initially encrypted.

   • handle_encrypted_wrapper is invoked with these parameters:

     Copy

      let (msg, info) = sdk::handle_encrypted_wrapper(deps.api, deps.storage, info, msg)?;

   • This function decrypts and verifies the wrapper (encrypted payload) to produce:

     • A decrypted msg (of type ExecuteMsg).

     • A decrypted info (with verified sender details).

2. Decrypted msg Can Contain ExecuteMsg::Extension:

   • After decryption, the msg can match any variant of ExecuteMsg, including ExecuteMsg::Extension.

   • For example:

     Copy

     ExecuteMsg::Extension { msg } => {
         match msg {
             InnerMethods::CreateAuctionItem { name, description, end_time } => { /* logic */ },
             InnerMethods::Bid { auction_id, 
                         amount  } => { /* logic */ },
         }
     },

   • Here, Extension contains an additional layer of messages (InnerMethods) which define specific functionality.

3. How handle_encrypted_wrapper Affects Extension:

   • The msg inside ExecuteMsg::Extension (i.e., InnerMethods) is also encrypted in the original input.

   • handle_encrypted_wrapper ensures:

     • The outer msg is decrypted (revealing Extension).

     • The inner data (e.g., InnerMethods) is now in cleartext and ready for logical execution.

   • Without this decryption, the contract could not access or process InnerMethods within the Extension.

4. Validation and Security:

   • By verifying and decrypting the entire payload at the wrapper level, the contract ensures:

     • The Extension message is authentic and unaltered.

     • The sender (info) is authenticated and valid.

     • Any operations within InnerMethods (like bidding) are authorized based on the decrypted info and secure data.

Frontend Encryption Logic

Now that you understand how the encryption SDK functions, let's look how it's connected to the frontend. The Next.js encryption logic can be found in Gateway.ts:

Create Auction:

 const create_auction = async (name: string, description: string, end_time: string = "60") => {
    const contract = contractConfig.auctions;
    const msg = { create_auction_item: { name, description, end_time } }
    return await execute_gateway_contract(contract, msg);
  }

Bid on Auction:

  const bid_auction = async (auction_id: string, amount: string) => {
    const contract = contractConfig.auctions;
    const msg = { bid: { auction_id, amount } }
    return await execute_gateway_contract(contract, msg);
  }

Both of these functions access a confidential auction contract already deployed on Secret Network (at the end of this tutorial, you will learn how to deploy your own).

Then, we call the execute_gateway_contract function, which is where all of the cross-chain SDK logic is implemented using IBC hooks:

const execute_gateway_contract = async (contract: Contract, msg: object) => {
    const ibcConfig = loadIbcConfig(chainId);
    const keplrOfflineSigner = (window as any).getOfflineSigner(chainId);

    const response = await sendIBCToken(
      cosmosjs!,
      keplrAddress!,
      contract.address,
      token!,
      "1",
      ibcConfig.consumer_channel_id,
      await gatewayChachaHookMemo(
        keplrOfflineSigner,
        { extension: { msg } },
        chainId!,
        contract,
      )
    );
    return response;
  };

You can further examine sendIBCToken and gatewayChachaHookMemo in the CCL-SDK ibc.ts file here.

Query Messages

There are two types of queries using the CCL SDK:

1. Unauthenticated queries ie Extension, which are queries that don’t require sensitive or protected data. Example: Retrieving a list of auctions, which is public.

2. Authenticated queries ie Inner Queries (WithPermit, WithAuthData), which are queries that require auth_data from the caller for permission validation. Example: MyBid { auction_id: u64 } retrieves a user-specific bid.

To query encrypted bids using the CCL SDK, use the enum InnerQueries, which wraps the possible queries in the auction smart contract, namely, MyBid, with the CCL SDK encryption logic:

#[cw_serde]
pub enum ExtendedQueries {
    Auctions {},
    Auction { auction_id: u64 },
    AllBids { auction_id: u64 },
    Result { auction_id: u64 },
}

#[cw_serde]
pub enum InnerQueries {
    MyBid { auction_id: u64 },
}

pub type ExecuteMsg                 =   GatewayExecuteMsg<InnerMethods>;
pub type QueryMsg                   =   GatewayQueryMsg<InnerQueries, CosmosAuthData, ExtendedQueries>

InnerMethods leverages the SDK by using the GatewayQueryMsg types to query encrypted cross-chain bids. You have the choice of using two different types of encrypted queries: query_with_auth_data and query_with_permit. In this tutorial, you we will learn how to implement query_with_permit.

1. WithAuthData:

pub fn query_with_auth_data(
    deps        :   Deps, 
    env         :   Env, 
    auth_data   :   CosmosAuthData,
    query       :   InnerQueries
) -> StdResult<Binary> {
    auth_data.verify(deps.api)?;
    auth_data.check_data(deps.storage, &env)?;
    let address = auth_data.primary_address()?;
    query_inner(deps, env,address, query)
}

1. WithPermit:

pub fn query_with_permit(
    deps        :   Deps, 
    env         :   Env, 
    permit      :   Permit,
    hrp         :   Option<String>,
    query       :   InnerQueries
) -> StdResult<Binary> {
    let address = secret_toolkit::permit::validate(
        deps, 
        PERMIT_PREFIX, 
        &permit, 
        env.contract.address.to_string(), 
        hrp.as_deref()
    )?;
    query_inner(deps, env, address, query)
}

Frontend Query Logic

The Next.js query decryption logic can be found in Gateway.ts:

Query auctions:

  const query_auctions = () => {
    return query_contract_public(contractConfig.auctions, { extension: { query: { auctions: { } } } });
  }

Query bids:

 const query_my_bid = (auction_id: number, message?: string) => {
    return query_contract_auth(contractConfig.auctions, { my_bid: { auction_id } }, message);
  }