Verifiable on-chain random number generator for the entire Cosmos.
This VRF tutorial uses IBC Hooks, as introduced in IBC v3.4.0. If your chain is on a previous IBC version, see the SecretVRF tutorial using proxy contracts here.
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.
Learn more about how SecretVRF works in-depth here.
To use SecretVRF on any IBC-enabled chain with IBC hooks, all that is required is:
An IBC transfer channel between Secret Network and the consumer chain that receives randomness.
Uploading the RNG Consumer Contract to your chain and directing it to your chain's transfer channel
Git clone the IBC hooks randomness repository:
Update the SECRET_TRANSFER_CHANNEL_ID and the CHAIN_TRANSFER_CHANNEL_ID to the channel-id for your IBC-enabled chain:
For this example, we request randomness on Juno Mainnet, but you can request randomness on any IBC-compatible chain that has a transfer channel established with Secret Network.
Once you have updated the transfer channels, compile the contract:
Upload the compiled contract:
Upon successful upload, a code_id is returned:
Instantiate the contract with the returned code_id:
Upon succesful instantiation, a contract_address is returned:
Now that you've instantiated your randomness contract, all that's left is to request randomness! Simply execute request_random:
A transaction hash will be returned:
You can update the job_id string to any string of your choosing
Navigate to the recently received transactions for your contract:
And then view the magic of cross-chain randomness with IBC hooks 😍:
Congrats! You've just sent a verifiable on-chain random byte with SecretVRF 🙌.
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.
Coming soon
Coming soon
Learn how to use Secret Network as the confidential computation layer of the Cosmos
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 ChaCha20-Poly1305, an authenticated encryption with additional data (AEAD) algorithm.
The key for this symmetric encryption is created by using the Elliptic-curve Diffie-Hellman (ECDH) scheme, comprising of two components:
An extra encryption public key provided from the Secret Gateway Contract
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.
Learn how to use Secret Network as the confidential computation layer of the Cosmos with IBC hooks
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.
See fullstack demo for Osmosis Mainnet here.
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.
In this example, you will send a token from Osmosis mainnet to Secret Network mainnet to encrypt a string🔥
To get started, clone the repository:
Install the dependencies:
Create an env file. Simply update env.testnet to omit ".testnet" from the file name and then add your wallet's mnemonics:
Now that you have your environment configured, it's time to upload the encryption contract to Secret Network.
First, compile the contract:
This compiles the contract and creates a wasm file in the following directory:
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:
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:
In your terminal, a codeID, codeHash, and contractAddress will be returned:
Update contracts.json with your contractAddress and codeHash accordingly:
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.
Feel free to update the strings to be encrypted.
To encrypt the payload, run execute-gateway.js:
This will initiate a Token transfer:
As well as an IBC Acknowledgement response:
Congrats! You have now used the Secret Network CCL SDK to encrypt a string on Osmosis Mainnet!
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:
There is a gateway contract deployed to Secret Network, which has the ability to encrypt a string, as well as query the encrypted string.
The gateway contract imports helper functions from the SDK, which is where the gateway contract imports encryption and query types, etc.
You can add additional functionality to the gateway contract as you see fit. For example, you could write an execute message that stores encrypted votes or encrypted NFTs, etc!
To use the SDK's encryption helper functions, simply write your gateway contract messages inside of the InnerMethods enum , which imports GatewayExecuteMsg from the SDK :)
Now let's examine each of the gateway contract's files to understand how it encrypts a user-inputted string.
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 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 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:
Check if Message is Encrypted:
If the message is encrypted (msg.is_encrypted()), it proceeds with decryption.
Extract Encryption Parameters:
Retrieves the encryption parameters from the message (msg.encrypted()).
Check Nonce:
Ensures the nonce has not been used before to prevent replay attacks.
Load Encryption Wallet:
Loads the encryption wallet from storage.
Decrypt Payload:
Decrypts the payload using the wallet and the provided parameters (payload, user_key, and nonce).
decrypt_to_payload uses chacha20poly1305 algorithm
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.
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).
Return Decrypted Message and Updated Info:
Returns the decrypted message and updated MessageInfo with the verified sender.
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:
Configured the development environment with the necessary dependencies and environment variables.
Uploaded and instantiated an encryption contract on the Secret Network mainnet.
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.
Note that for our consumer chain, we are using the endpoint, chainID, token, and prefix for Osmosis Mainnet. But you could update this for any Cosmos chain that has IBC hooks enabled and a transfer channel with Secret Network
