Basics

• Overview

• Connecting Metamask to Secret Network

• Cross-chain Messaging

Usecases

• Storing Encrypted Data on Secret Network

• Confidential Voting

• Sealed Bid Auction

• VRF

• Tokens

Supported Networks

• EVM Mainnet

• EVM Testnet

Secret Network's EVM Toolkit is a cross-chain messaging and confidential computation SDK for EVM developers.

The toolkit allows EVM developers to build novel cross-chain applications such as private DAO voting mechanisms, secure random number generation (Secret VRF), confidential data access control via EVM NFTs, encrypted DeFi order books, and more.

Secret Network currently supports two cross-chain messaging solutions:

1. SecretPath (recommended)

1. Axelar GMP

Connecting Metamask to Secret Network

Now you have a Secret testnet wallet address that you can use to sign transactions with your Metamask wallet!

SecretPath 🤝 Reown

SecretPath connects Secret Network to 20+ EVM chains, enabling public EVM chains to call functions on Secret Network while preserving the privacy of the inputs and validity of the outputs.

With Reown (formerly called WalletConnect), you can create a seamless user experience with one wallet login that allows users to interact with Secret Network smart contracts on every SecretPath-connected chain.

In this tutorial, you will learn how to configure SecretPath and Reown in React.js so you can create seamless UI for confidential cross-chain computation 😄

Reown Configuration

1. Sign in to Reown.

2. Create a Reown project.

In this tutorial, you are building a React.js application. Select "Javascript" for platform to build your React.js app:

After successfully creating a project, you will see your project id:

Connecting Reown to SecretPath

1. Clone the SecretPath Reown repository:

git clone https://github.com/writersblockchain/secretpath-walletconnect

1. Install the dependencies:

cd frontend 
npm install 

1. Update the project-id with your project-id

Now you're ready to use Reown with SecretPath!

Configuring Reown for SecretPath

Now that you have your environment properly configured, let's understand how everything is connected. Run npm run start to see your Reown application:

npm run start

Out of the box, you can use this React application as a starting point for your SecretPath + Reown applications.

Click "Connect Wallet" and sign in to your Metamask or EVM wallet. Click on the network you are currently connected to in order to see all of the EVM networks available:

All of these 20+ networks are connected to SecretPath, which means any of these chains can call functions on Secret Network smart contracts 🤯

Now let's breakdown each of the parameters that are required to properly configure our Web3Modal.

Web3Modal Parameters

We must pass 5 parameters to Web3Modal: chainImages, ethersConfig, chains, projectId, and metadata.

chainImages

chainImages is an object that associates EVM chain IDs with images that are displayed in the wallet UI. You can add additional chain IDs and images for each additional chain you would like included in your application. Currently, every chain that is supported by SecretPath is included.

ethersConfig

ethersConfig is an object that contains boilerplate ethers configuration code.

chains

chains contains the RPC info for each chain that you connect to SecretPath. The chain info is imported from the chains.js file in the config folder. If you have added RPC info for a chain to Metamask before, this should look familiar.

projectId

Your unique project id generated by Reown.

metadata

Metadata unique to your dApp.

Putting it all together: SecretPath + Reown

Now that you have your Reown interface enabled to your liking, let's understand how it connects the EVM to Secret Network with SecretPath.

Open App.js. Notice that there are 3 functions working in tandem here:

1. useEffect, which returns the currently enabled chain ID (so every time the user switches to a new chain, this is saved in the application state)

2. requestRandomness - this is our SecretPath function which requests a verifiable random number from a Secret smart contract. It takes the parameter chainId, because the application must know which EVM gateway contract to execute based on which EVM chain is currently connected.

3. querySecret - a query function that queries the random number stored in the Secret Network smart contract

Finally, on click, requestRandomness calls the request_random handle in the Secret smart contract, which returns a random number between 1-200. SecretPath knows which EVM gateway contract to execute based on which chain ID is currently enabled by Reown (you can see the if/else logic here).

Summary

✨ SecretPath integrates Secret Network with over 20 EVM chains, enabling public EVM chains to execute functions on Secret Network while preserving privacy and ensuring output validity. Using Reown, developers can create a seamless user experience, allowing users to interact with Secret Network smart contracts across all SecretPath-connected chains through a single wallet login.

This tutorial provides a step-by-step guide to configuring SecretPath and Reown in a React application, starting from signing in with Reown and creating a project, to setting up the development environment. Key configurations include specifying parameters for Web3Modal, such as chainImages, ethersConfig, chains, projectId, and metadata. The tutorial also explains how to connect EVM to Secret Network using functions like requestRandomness and querySecret within the app, ensuring smooth and confidential cross-chain computations ✨

Secret Network currently supports two cross-chain messaging solutions:

1. SecretPath (recommended)

1. Axelar GMP

SecretPath is a protocol for lightweight, secure, privacy preserving message-passing between chains. Its purpose is to serve as a critical building block for bringing private data onchain in a useful yet privacy-preserving manner.

In technical terms, SecretPath is a message passing system for non-malleable, trustless interchain message passing. In more practical terms, SecretPath enables public chains to call arbitrary functions on private compute chains while preserving the privacy of the inputs and validity of the outputs. SecretPath is built using a primitive that we call TNLS ("Transport Network Layer Security") which is effectively a blockchain derivative of the TLS protocol.

SecretPath itself does not store or compute over data. Rather, it connects public blockchains and their applications to privacy-preserving computation networks. This design allows public blockchain applications to build and operate private computation contracts on privacy-preserving chains while keeping their primary smart contract logic and liquidity on public blockchains.

Ultimately, SecretPath enables the building of new applications that combine the transparency, UX, and latency benefits of public blockchains with the trust-minimized and private computation features of privacy-preserving blockchains.

The following sections provide a detailed technical overview of the current relayer and gateway architecture for SecretPath.

1. To get an overview of the Architecture go here: Architecture Overview

2. If you like to use SecretVRF in the most elegant way for you as an EVM developer, go here:VRF Developer Tutorial

3. To review supported EVM chains, go here: Supported Networks

As an user and developer, all you need to know is how to send messages to one gateway/receive messages from a gateway, which will be covered in those respective documentation sections. More tutorials with encrypted payloads are coming soon.

As a maintainer, you might want to look more closely at the relayer section of the codebase as well here: https://github.com/SecretSaturn/SecretPath

You can try a demo of SecretPath that bridges Secret VRF into EVMs here: vrfdemo.secretsaturn.net

This documentation was adapted from https://fortress-labs.gitbook.io/snakepath, courtesy of Leor Fishman.

SecretPath consists of two core primitives: relayers and gateways.

Gateways are the onchain smart contracts that handle the broadcasting, receipt, packaging, and verification of messages. Gateways are also the mechanism by which application developers will interface with the SecretPath protocol.

These gateways are relatively simple and generic, primarily consisting of two capabilities. First, gateways can handle signature operations. For gateways on public blockchains, that means verification; for those on privacy-preserving blockchains, that means verification as well as signing. Second, gateways handle serdes operations: converting contract inputs into correctly formatted packets and vice versa.

Relayers watch for messages on one chain and then call another chain with that message. For SecretPath, the primary security-related concern is liveness, not resistance to node collusion or censorship. The relayer is not tasked with relaying funds/tokens from one chain to another, but rather with watching for encrypted messages that need to be passed. The relayer does not have access to encryption keys that can decrypt these messages or signing keys to generate new valid ones, meaning that the relayer cannot compromise the data in security or correctness.

The most a relayer can do is to not transmit the data as requested, which would cause liveness problems for the network, but would not compromise user funds, smart contract applications, or sensitive data. This also makes the requirements for running a relayer significantly lower: a relayer needs only to be able to watch for transactions on host chains and create transactions on destination chains based on those host chain transactions.

Gateways are the onchain smart contracts that handle the broadcasting, receipt, packaging, and verification of messages. Gateways are also the mechanism by which application developers will interface with the SecretPath protocol.These gateways are relatively simple and generic, primarily consisting of three capabilities.

First, gateways can handle signature operations. For gateways on public blockchains, that means verification; for those on privacy-preserving blockchains, that means verification as well as signing.

Second, gateways handle serialize/deserialize operations: converting contract inputs into correctly formatted packets and vice versa.

Third, gateways on privacy-preserving chains can re-encrypt their inputs under the key of the final compute contract.

For more background on how the high-level architecture of SecretPath differs from that of other interoperability networks, see section 4 of the Snakepath whitepaper.

Here you'll find a more in-depth overview with a detailed description of what the two core primitives (Gateways & Relayers) do. First, let us give you the core idea on what SecretPath really hinges on.

The core idea of SecretPath is the following:

The "master private gateway" is a confidential smart contract living on Secret Network.

Since this contract is confidential by default , we can store a (secret) private key, which only this smart contract can use to sign messages/packets and is unknown to the operators or to any contract administrators.

The only trust assumption that we have for this bridge model to work is therefore that the private key does not leak out the TEE (trusted execution environment)/confidential computation environment. In case the TEE breaks and that private signing keys could potentially leak, the encryption and verification keys can be rotated to new ones, keeping the bridge intact. Since we only rely on a smart contract to handle the core bridging functionality, we call this trustless. Some may argue that since we are using TEE's, we are not completely trustless but instead trust-minimized.

Everything else around this "master private gateway" is untrusted. We only use a lot of consistency checks and hashing to ensure that data weren't manipulated along any transmission path.

As outlined in the overview, the primary functions of the Gateway are:

1. Handle signature operations

For the "master public gateway" that is on a public blockchain, that means only verification of signatures. In our case, this public gateways verifies all secp256k1 signatures signed by the user or by the master private gateway.

The private master gateway does verification of the secp256k1 signed and encrypted user payloads. It also signs all outgoing messages using secp256k1 so that other user made private contracts as well as the public gateway contract can verify the validity of the message/packet.

2. Serialize/deserialize operations

Both gateways also handle serialize/deserialize operations. They convert contract inputs into correctly formatted packets and vice versa, while also doing the appropiate conversions between base64 (mainly used for secret) and hex (mainly used for EVMs) inputs.

3. Re-encrypt inputs

Third, gateways on privacy-preserving chains can re-encrypt their inputs under the key of the final compute contract. The master private gateway can handle encrypted or unencrypted payloads. In the case of encrypted payloads, the payload is encrypted using a shared key that is generated via ECDH from a user's randomly generated private key and the gateways encryption public key. We use the well known Chacha20-Poly1305 to do the symmetric encryption using that shared key.

Please check out Usecases to see all of the tutorials with SecretPath.

The public EVM gateway sits at the heart of SecretPath. It coordinates the tasks (stored in the Task stuct and saved in a mapping(uint256 => Task) public tasks). It verifies the inputs when sending in encrypted Payloads in send and verifies the incoming callback packet in postExecution. A UML diagram of the upgradeable Gateway contract, together with it's dependencies, is shown below.

Secretpath in itself is a trustless protocol, meaning that everyone can deploy a public gateway on their own chain. Here's how to do it:

Prerequisites

Before you begin, make sure you have the following installed on your system:

• Git: Version control system for cloning repositories.

• Foundry: A blazing fast, portable, and modular toolkit for Ethereum application development.

• Anaconda: For creating a virtual environment (Python 3.11).

• Python 3.11 & : Required for running the relayer scripts. Python package installer.

• Access to the Sepolia Testnet: You'll need to interact with the edeXa Testnet.

Cloning the Repository and Initial Setup

1. Clone the SecretPath Repository

   Copy

   git clone -b Solana https://github.com/SecretSaturn/SecretPath.git

2. Navigate to the Public Gateway Directory

   Copy

   cd SecretPath/TNLS-Gateways/public-gateway

3. Initialize Submodules

   Copy

   git submodule update --init --recursive

Deploying the Gateway Contract

You'll deploy the gateway contract using Foundry's forge tool.

Run the Forge Script

Replace <YOUR_PRIVATE_KEY> with your actual private key. Keep your private key secure and do not share it.

forge script script/DeployGatewayScript.s.sol:DeployGatewayScript \
  --rpc-url "https://rpc.sepolia.org" \
  --broadcast \
  --retries 10 \
  -vvv \
  --optimize \
  --optimizer-runs 10000000 \
  --legacy \
  --private-key <YOUR_PRIVATE_KEY> \
  --evm-version paris

Handling Gas Price Error

If you encounter the following error:

Error:
Failed to send transaction

Context:
- server returned an error response: error code -32009: Gas price below configured minimum gas price

You need to adjust the gas price.

a. Estimate the Correct Gas Price

Visit the Ethereum Sepolia Testnet explorer to check recent gas prices:

https://sepolia.etherscan.io

b. Add the Gas Price Flag

Re-run the forge script with the --with-gas-price flag:

forge script script/DeployGatewayScript.s.sol:DeployGatewayScript \
  --rpc-url "https://rpc.sepolia.org" \
  --broadcast \
  --retries 10 \
  -vvv \
  --optimize \
  --optimizer-runs 10000000 \
  --legacy \
  --private-key <YOUR_PRIVATE_KEY> \
  --evm-version paris \
  --with-gas-price 2gwei

Understanding the Deployment Output

Upon successful deployment, you will see two contract addresses:

• Implementation Address: The first address, representing the implementation contract.

• Gateway Address: The second address, which is the Transparent Upgradeable Proxy contract.

Note: The Gateway Admin is your wallet address (you are the owner of the contracts). The Proxy Admin is specified in the logs of the Gateway Address contract deployment. The Proxy Admin contract is exclusively used for upgrading contracts, and the Gateway Admin is the owner of this Proxy Admin contract.

Configuring the Relayer

Navigate to the Relayer Directory

cd ../../TNLS-RELAYERS

Open config.yml for Editing

nano config.yml

Add the Following Configuration

Replace <YOUR_GATEWAY_ADDRESS> with the Gateway Address obtained from the deployment step.

"11155111": #Ethereum Sepolia
  active: false
  type: "evm"
  chain_id: "11155111"
  api_endpoint: https://eth-sepolia-public.unifra.io
  contract_address: "0x3879E146140b627a5C858a08e507B171D9E43139"
  timeout: 1

Add Environment Variables

Create a .env file or set the following environment variables. Replace the placeholders with your actual private keys. Keep your private keys secure and do not share them.

ethereum-private-key = <YOUR_ETHEREUM_PRIVATE_KEY>
solana-private-key = <YOUR_SOLANA_PRIVATE_KEY>
secret-private-key = <YOUR_SECRET_PRIVATE_KEY>

Setting Up the Virtual Environment

Install Anaconda

Download and install Anaconda for your operating system:

• Anaconda Installation Guide

Create a Virtual Environment

conda create --name secretpath_env python=3.11

Activate the Virtual Environment

conda activate secretpath_env

Install Dependencies

Navigate to the relayer directory if you're not already there:

cd TNLS-RELAYERS

Install the required Python packages, make sure to not install depencencies as this may lead to dependency hell.

pip install -r requirements.txt --no-dependencies

Running the Relayer

Start the Relayer

python3 web_app.py

Handling the LRU Error

If you encounter an error related to lru-dict, update it using:

pip install --upgrade lru-dict

Axelar General Message Passing

Axelar enables secure interchain communication and token transfers, spanning consensus methods including Cosmos and Ethereum. Through the use of General Message Passing (GMP), developers building on Ethereum can execute smart contracts on Secret and vice versa. This means complete composability across Web3.

With GMP you can:

• Call a contract on chain B from chain A.

• Call a contract on chain B from chain A and attach some tokens.

In this tutorial, you will learn how to use Axelar GMP to send a string between Polygon Mainnet and Secret Mainnet. To learn more about the flow architecture, see the Axelar documentation here.

Prerequisites

• For GMP to work, both chain A and chain B must be EVM or Cosmos with a deployed Axelar Gateway contract. For this tutorial we will be using the Polygon Mainnet Axelar Gateway contract. We will go into this in more detail momentarily.

• Have Metamask installed and your wallet funded with POL tokens.

Upload a contract to Polygon

In order to execute a smart contract on Secret network, you must first upload and instantiate a smart contract on Polygon that can execute messages using Axelar GMP. We will be uploading the SendReceive.sol contract to Polygon for this demo.

To upload the contract, we will use Remix Online IDE, which is a powerful toolset for developing, deploying, debugging, and testing Ethereum and EVM-compatible smart contracts.

First, navigate to Remix and create a new blank workspace:

Next, create a new file called SendReceive.sol and paste the Axelar GMP solidity code. This will autofill your workspace with the necessary dependencies for your SendReceive.sol contract 🤯

Now all that's left is to compile and upload the contract. Navigate to the Solidity compiler using the sidebar and click "Compile SendReceive.sol". Then, navigate to "Deploy and run transactions." Toggle the Environment from "Remix VM (Shanghai)" to "Injected Provider - MetaMask" and make sure that in your MetaMask wallet you have currently selected Polygon network.

The constructor of SendReceive.sol contains 3 variables that you must now input in order to instantiate the contract and link it to Axelar's Polygon gateway contract and gas receiver contract, as well as the chain name:

GATEWAY CONTRACT: "0x6f015F16De9fC8791b234eF68D486d2bF203FBA8"
GASRECEIVER CONTRACT: "0x2d5d7d31F671F86C782533cc367F14109a082712"
CHAINNAME: "Polygon"

Input these strings like so and then click "Transact":

Upon successful instantiation, the contract address will be returned in the Remix terminal, which you can then view on the Polygon explorer. And the deployed contract can now be interacted with in the "Deployed Contracts" window:

Congrats, you've just deployed an Axelar GMP-compatible contract to Polygon mainnet that can send and receive messages to and from a Secret Network smart contract 🎉

Upload a contract to Secret Network

Now that you've uploaded a GMP-compatible contract to Polygon, let's do the same on Secret Network so that the contracts can communicate with each other across the Cosmos!

First, clone this Secret Network examples repository:

git clone https://github.com/SecretFoundation/secret-ethereum-gmp.git

Compile the contract by running make build-mainnet in your terminal:

make build-mainnet

Now, open a new terminal window and cd into node:

cd node

npm install to install the package.json dependencies:

npm install

Create a .env file in /node and add your wallet mnemonic in order to upload the contract:

You can then upload and instantiate the contract by running node index.js.

node index.js

Upon successful instantiation, a Secret contract address is returned that you can then use to send messages to and from Polygon:

Now let's send a string from Polygon to Secret! 🚀

Send a string from Polygon to Secret

Now that you have a GMP-compatible contract instantiated on Secret Network, you have all of the variables needed in order to send a cross-chain message using the SendReceive.sol contract.

In order to send messages using Axelar GMP, the user prepays the relayer gas fee on the source chain to Axelar’s Gas Services contract.

To make sure you have enough gas, add .60 Matic, (roughly .40 USD or 800000000000000000 Wei), to the transaction:

Now all that's left is to execute the transaction! From the "Deployed contracts" section of Remix, open the dropdown for the send function, which should have three inputs: destinationChain, destinationAddress, and message. Input the following:

destinationChain: "secret"
destinationAddress: "Your Secret Contract Address"
destinationMessage: "Your message that you want to send!"

Once you have inputed these strings and your contract address, select "transact." Congratulations! You've just sent a string from Polygon to Secret Network! 🎉

Query the string on Secret

Now that you've successfully executed a cross-chain message from Polygon to Secret using Axelar GMP, let's query the message on Secret Network to see if the message was actually received by the Secret contract.

First, confirm that the transaction has been successfully relayed by Axelar.

Once the transaction has been executed successfully, you can use Secret.js to query the message:

let get_stored_message = async () => {
  let query = await secretjs.query.compute.queryContract({
    contract_address: contractAddress,
    query: {
      get_stored_message: {},
    },
    code_hash: contractCodeHash,
  });

  console.log(query);
};

get_stored_message();

To execute this query, navigate to the query.js file in examples/secret-ethereum-gmp/node and replace the contractAdress and contractCodeHash with your contract address and code hash, respectively.

Then run node query.

node query

If the message was executed successfully, the query will return the Ethereum wallet address that sent the transaction as well as the message that the wallet included:

{
sender: `0x49e01eb08bBF0696Ed0df8cD894906f7Da635929`,
message: `one small step for Secret!`
}

Great work! Now let's send a string from Secret to Polygon!

Send a string from Secret to Polygon

To execute the SendMessageEvm transaction, navigate to the execute.js file in examples/secret-ethereum-gmp/node and replace the contractAdress and contractCodeHash with your contract address and code hash.

Then, update destinationAddress to your Polygon contract address, and myMessage to the message that you want to send:

Gas Token

Next, in order to send a GMP message from Secret to Polygon, you need to acquire some AXL tokens and include the correct IBC denom representing those tokens to your transaction to pay for gas, so that the message can be executed over IBC

The correct IBC denom is already included in the secret.js transaction, but in order for it to execute successfully, you need to have this IBC denom funded in your wallet. To add this token to your wallet, you can send Axelar tokens to your Secret wallet address over IBC.

Once you have properly configured your execute.js file and procured the IBC denom needed to execute the transaction, all that's left is to run node execute.

node execute 

The transaction should return a transactionHash as well as data about the IBC routing:

Now, navigate to Axelarscan to monitor the status of the transaction.

And for good measure, view the transaction on the Polygon Explorer to see that the message was received!

Congratulations! You now have all of the tools to send a message from Secret Network to Polygon using Axelar GMP! 🎉

Summary

Axelar's General Message Passing (GMP) offers a powerful solution for achieving secure interchain communication and token transfers across Secret and Ethereum. This documentation has guided you through the process of deploying GMP-compatible contracts on both Polygon and Secret Network, illustrating how to send messages across these networks.

If you run into any errors or questions, ping the #dev-issues channel on Secret Network's Discord and somebody will get back to you shortly 😊

One of SecretPath's key features is the ability to use encrypted payloads to send over confidential messages to a Secret Smart contract.

SecretPath can seamlessly handle encrypted payloads, as the master gateway contract on Secret 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:

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 SecretPath to encrypt a string and subsequently store it in a Secret contract.

Overview

SecretPath seamlessly handles encrypted payloads on the EVM, which means EVM developers can use SecretPath to encrypt and decrypt messages cross-chain with little-to-no Rust experience required.

This tutorial explains how to:

1. Upload your own Key-value store contract on Secret Network

2. Encrypt data on the EVM and transmit encrypted data cross-chain to Secret Network

3. Connect your key value store contract to a React frontend.

After this tutorial, you will have the tools you need to use SecretPath to encrypt messages on any EVM-compatible chain.

Getting Started

To get started, clone the EVM key value store repository:

git clone https://github.com/writersblockchain/evm-kv-store-demo.git

Configuring Environment

cd into secret-contract/node

cd secret-contract/node

Install the dependencies:

npm install

Upload the Key-value contract to Secret Network

In the node folder, open the upload.js file and review the instantiate message at line 56:

 let init = {
    gateway_address: gatewayAddress,
    gateway_hash: gatewayHash,
    gateway_key: gatewayPublicKeyBytes,
  };

• gatewayAddress is the SecretPath gateway contract address for testnet

• gatewayHash is the SecretPath gateway contract hash for testnet

• gatewayKey is public key used for SecretPath encryption on Secret testnet

To upload and instantiate the contract, run node upload:

node upload

Upon successful upload, a contractHash and address will be returned:

codeId:  5701
Contract_hash: "6311a3f85261fc720d9a61e4ee46fae1c8a23440122b2ed1bbcebf49e3e46ad2"
contract_address:  "secret1j0gpu6tlwnc9fw55wcfsfuml00kqpcnqz7dck7"

make build-mainnet

Encrypt a payload

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

cd into evm-kv-store-demo/kv-store-frontend:

cd evm-kv-store-demo/kv-store-frontend

Install the dependencies:

npm i

Open .env and change the routing_contract and routing_code_hash to the address and code hash for your contract:

REACT_APP_SECRET_ADDRESS="secret1neeyum9p9h6u0d5jkxlqx9w5nrz49hzrr63jsw"
REACT_APP_CODE_HASH="6994d8ff9ed1af73ef4685a9f5c8a5568804afb5fa5ce49ec8496fb271a9760a"

That's it! You dApp is now connected to your Secret smart contract and ready to encrypt key value pairs. To start the application, run:

npm run start

Congrats! You now have now deployed a fullstack cross-chain decentralized application that passes encrypted key-value pairs from the EVM and stores them on Secret Network 🎉

SecretPath - a deep dive 🏊‍♀️

Now that you have successfully uploaded a key-value contract to Secret Network and connected it to a React frontend, let's examine the code to understand how SecretPath passes encrypted data from the EVM to Secret Network.

From a high-level, all that you need to know is there is a public SecretPath contract deployed on every EVM chain listed here, which communicates with a private SecretPath contract deployed on Secret Network, and it is these public/private contract pairs that encrypt your data and pass messages from the EVM to Secret Network.

When you create your cross-chain dApp, you simply need to format your data so that it can be transmitted successfully from the public SecretPath contract to the private SecretPath contract.

All of the data formatting for the public EVM contract happens in submit.js. This is almost entirely boilerplate code except for the variables handle and data:

  // The function name of the function that is called on the private contract
  const handle = "store_value";

  // Data are the calldata/parameters that are passed into the contract
  const data = JSON.stringify({
    key: key,
    value: value,
    viewing_key: viewing_key
  });

handle is the name of the function that we are executing in our private Secret smart contract, and data is the data that we pass to the function that we are executing in the Secret contract, which in the case of the key value contract is key, value, and viewing_key.

Let's now look at the Secret Network contract that we uploaded to better understand the store_value function and how it uses the parameters key, value, and viewing_key.

Understanding the Private (Secret) Contract

At line 109, we have a match statement, which includes the handle "store_value":

 // determine which function to call based on the included handle
    let handle = msg.handle.as_str();
    match handle {
        "store_value" => store_value(deps, env, msg.input_values, msg.task, msg.input_hash),
        "retrieve_value" => retrieve_value(deps, env, msg.input_values, msg.task, msg.input_hash),
        "change_value" => change_value(deps, env, msg.input_values, msg.task, msg.input_hash),
        _ => Err(StdError::generic_err("invalid handle".to_string())),
    }

Since we pass the handle store_value from your dApp to your Secret contract, it knows to execute the store_value function!

Inside of the store_value function, we use the key, value, and viewing_key parameters that we pass from the EVM in order to create a key map with our key-value pairs:

let input: InputStoreMsg = serde_json_wasm::from_str(&input_values)
        .map_err(|err| StdError::generic_err(err.to_string()))?;
  
  // create a task information store
    let storage_item = StorageItem {
        value: input.value,
        viewing_key: input.viewing_key,
    };
    
  // map task to task info
    KV_MAP.insert(deps.storage, &input.key, &storage_item)?;

This data is encrypted and stored inside of your Secret smart contract. The data can now only be revealed with a query that uses the proper viewing_key:

const secretjs = new SecretNetworkClient({
                url: "https://pulsar.lcd.secretnodes.com",
                chainId: "pulsar-3",
            });

            const query_tx = await secretjs.query.compute.queryContract({
                contract_address: process.env.REACT_APP_SECRET_ADDRESS,
                code_hash: process.env.REACT_APP_CODE_HASH,
                query: {
                    retrieve_value: {
                        key: key,
                        viewing_key: viewingKey
                    }
                },
            });

Summary

In this tutorial, you've learned how to deploy a key-value store smart contract on Secret Network, encrypt and transmit messages from an EVM-compatible chain, and integrate the contract with a React frontend. Using SecretPath, you can now seamlessly handle encrypted payloads cross-chain with minimal Rust experience. By following the steps outlined, you're equipped to build decentralized applications that leverage SecretPath for secure, cross-chain communication and data storage.

Overview

A first-price sealed-bid auction, also known as a "blind auction", is a type of auction in which all bidders simultaneously submit sealed bids so that no bidder knows the bid of any other participant. The highest bidder pays the price that was submitted. In this tutorial you will learn how to create a cross-chain sealed bid auction dApp with encrypted bids using SecretPath.

SecretPath Contract Design

1. Contract Deployment: Participants initiate the process by deploying a Sealed Bid Contract to the Secret Network. This contract contains their auction items and encrypted bids, safeguarding the bid details from public exposure.

2. Contract Execution via Public Gateway:

   • The execution sequence begins when the Sealed Bid Contract is interacted with via the Ethereum Virtual Machine (EVM).

   • The SecretPath Public Gateway Smart Contract serves as the intermediary, facilitating communication between the EVM and Secret Network.

3. Secure Message Transmission:

   • Messages and transactions pass through the Public Gateway to the Private Gateway Smart Contract, utilizing ECDH to ensure that the data exchanged remains confidential and tamper-proof, maintaining the integrity of the sealed bid throughout the process.

4. Finalization:

   • Once the bidding period concludes, the Sealed Bid Contract processes the bids to determine the winner securely.

   • The outcome is then communicated back through the gateway contracts to the relevant parties on the EVM.

Overview

A first-price sealed-bid auction, also known as a "blind auction", is a type of auction in which all bidders simultaneously submit sealed bids so that no bidder knows the bid of any other participant. The highest bidder pays the price that was submitted. In this tutorial you will learn how to create a cross-chain sealed bid auction dApp with encrypted bids using SecretPath.

You will start by configuring your developer environment and then learn how to use SecretPath to enable cross-chain encryption and decryption, using Secret Network as a Confidential Computing Layer (CCL) for the EVM.

Getting Started

To get started, clone the SecretPath tutorials repository:

git clone https://github.com/writersblockchain/sealed-bid-auctions.git

EVM Prerequisites

1. Fund your Sepolia wallet.

Secret Network Prerequisites

1. Add Secret Network testnet to Keplr.

2. Fund your Secret testnet wallet.

Uploading Sealed Bid Contract

cd into sealed-bid-auctions/sealed-bid-contract

cd sealed-bid-auctions/sealed-bid-contract

Update the env file with your Secret Network wallet mnemonic, and rename it ".env" instead of ".env.example"

Compile the contract

make build-mainnet

cd into secret-contract/node:

cd node

Install the node dependencies

npm install

Set SecretPath parameters:

Open upload.js and configure the SecretPath gatewayAddress, gatewayHash, and gatewayPublicKey:

const gatewayAddress = "secret10ex7r7c4y704xyu086lf74ymhrqhypayfk7fkj";

const gatewayHash =
  "012dd8efab9526dec294b6898c812ef6f6ad853e32172788f54ef3c305c1ecc5";

const gatewayPublicKey = "0x046d0aac3ef10e69055e934ca899f508ba516832dc74aa4ed4d741052ed5a568774d99d3bfed641a7935ae73aac8e34938db747c2f0e8b2aa95c25d069a575cc8b";
 

Upload and instantiate the contract:

node upload

List an Auction Item

Now that you've instantiated a sealed bid contract on Secret Network, it's time to create your first auction item with SecretPath!

cd into sealed-bid-auctions/evm-contract:

cd sealed-bid-auctions/evm-contract

Install the dependencies

npm i

Configure env

Configure the envwith your sealed bid auction contract address and codehash, and rename it ".env" instead of ".env.example".

Configure SecretPath

Open scripts/create_auction.js and navigate to line 44, the publicClientAddress. This is the SecretPath gateway address for Sepolia testnet.

Similarly, there is a SecretPath gateway encryption key, which is on line 63. This is used for ChaCha20-Poly1305 Payload encryption and can be found in the docs here.

Next, configure the auction name, description, and end_time to your liking (end_time is the amount of minutes that the auction will be live for), and note the handle variable, which is the function that is actually being called in the Secret contract that you deployed. You are executing the create_auction_item handle, which executes the create_auction-item function in your sealed bid contract.

Now that you have all of your SecretPath code configured, execute the SecretPath Sepolia public gateway contract to send your auction item to the Secret contract:

npx hardhat run scripts/create_auction.js --network sepolia 

Upon successful execution, info about your SecretPath payload will be returned:

Payload Hash: 0x6a822118ea803fe9274c502d354dfd6b24e99f9a67b8b4b11032649dc4b82da1
Payload Signature: 0x77e3a0fd7bb8ea7d96889ed82521672ee0a7e0c5cb81cdc2187e7253407e8f136204d578f13a832dcacb1b2509118114b4aca0635984bb1d7d673579572cf9261b
Recovered public key: 0x0423d8d8b518902cd6b0da592af0424719c355a724687cb74d96bd1171eb148edb87f3e9ca67f9ccecde109333461162af4dc09b33604c7e82242852a7142878ec
Verify this matches the user address: 0x49e01eb08bBF0696Ed0df8cD894906f7Da635929
_userAddress: 0x49e01eb08bBF0696Ed0df8cD894906f7Da635929
  _routingInfo: secret1xw2ge736z7la2fwuwwh89edwcxks4dv3qf2mg8 
  _payloadHash: 0x6a822118ea803fe9274c502d354dfd6b24e99f9a67b8b4b11032649dc4b82da1 
  _info: {"user_key":"0x026c4af0a833ed26f82058d882a0e18114ac398eebdc05b206d11a9060c075026c","user_pubkey":"0x0423d8d8b518902cd6b0da592af0424719c355a724687cb74d96bd1171eb148edb87f3e9ca67f9ccecde109333461162af4dc09b33604c7e82242852a7142878ec","routing_code_hash":"6d38a8569aba096b0849253dbf8de09b9c72dd693f2a6d1d87697fc0877cbc29","task_destination_network":"pulsar-3","handle":"create_bid","nonce":"0x0d0075c1a22be720ad003eba","payload":"0x0b47475944f9a0c966f9b8be7f779f291c31eb11a78132a19fb23aef1b97a92b189e938b5d1975d81836f2ff0aa89e0ade4b48140c609e996ba7d5efb4c0a99272ad1858db46721cb7b9868afd57aeccaa9166270b9e0ca5f8d4d9bf0cc8907a648b1587bf6f2c4081fbbb7b480848ebd7dd3f9872586583293f1f0ae68cf45c4f5c7cc190efd4d9989d5fba0237114fa63b68ed737a1936ab76f974862e072e2f84e445e5968aff6ca085186e0cb8139a29a262587735706eb68ec9a655114d317a777b3394d3221bb94d5f8ed689e71a770be1c56e9dd1bfea4e5fc191b00cbc3323b851064bfe18ba2e4b8720e618d212634b3d048478c90a004b4cd7a751ce8c8ed43323245ce064fdd82ebaa6d6e41e2256c73525afd092b77917e6e6281a9a0ba72836e66cd539e99d335c83decb91ee53d15cab8bf699b44c4aea43ffa34bc64c57f3873b3159d02e6439d8650d974b62053ef9c56122fb83d2b69a7c870b87ca44358fbb74435ea03faaf3303dc4025194030270b2dd32d125bb839d4e0e6f984835a788fde0464a068658c5b6a1d7c30ba46603ba8c870f940a87c1b2e3577d741d4b8b1120561ac85d7b6898f80a5e57c43dbfe456da501fcab2837a81f1755a6db7f928f3d3f23793e71f108fc6b4b6257317b8279c0c2b00019e08b90f28658eb9fc211f554b3b9325d5add78c2db37b6d48793e","payload_signature":"0x77e3a0fd7bb8ea7d96889ed82521672ee0a7e0c5cb81cdc2187e7253407e8f136204d578f13a832dcacb1b2509118114b4aca0635984bb1d7d673579572cf9261b","callback_gas_limit":300000}
  _callbackAddress: 0x3879e146140b627a5c858a08e507b171d9e43139,
  _callbackSelector: 0x373d450c,
  _callbackGasLimit: 300000
Transaction sent! Hash: 0xae5dd78f381b67e470a70eaf757c306a1ee605f145007cd7a6e4f4cb8d56be4b
Transaction confirmed! Block Number: 5683035

Bid On Auction Item

Now it's time to place an encrypted bid on your listed auction item. Open bid.js and adjust the amount that you want to bid as well as the index of the auction item.

Once you have set your bid, execute the bid function:

npx hardhat run scripts/bid.js --network sepolia

Upon successful execution, info about your SecretPath payload will be returned. Now let's query your auction item and bids with secret.js.

Querying Auction Items and Bids

cd into sealed-bid-auctions/sealed-bid-contract/node:

cd sealed-bid-auctions/sealed-bid-contract/node

Make sure you have added your Sealed bid contract address and codehash to your env file, and then query the auction item with node query_auction:

node query_auction 

If your auction item was submitted successfully, it should be returned like so:

{
  name: 'auction item #1',
  description: 'this is the 1st auction item',
  end_time: 4397696,
  message: 'Retrieved value successfully'
}

Now, query the encrypted bids by running node query_bid:

node query_bid

If the bidding is still open, it will return the message:

{ message: 'Bidding is open' }

If the bidding is closed, it will return the highest bid:

{ message: 'Bidding is closed. The highest bid is: 300' }

This is programmed in the retrieve_bids_query function of the Sealed Bid contract and can be adjusted to your liking 😊

Conclusion

Congrats! You deployed your very own sealed bid auction contract on Secret Network and used SecretPath to send cross-chain encrypted bids on Sepolia testnet. See the fullstack demo here. You now have all of the tools you need to start building your own cross-chain SecretPath contracts on the EVM 🎉

Note that the end user of the application is not exposed to Secret Network and is only working directly in the EVM environment. However, the data is fully protected and cannot be viewed by anyone.

If you have any questions or run into any issues, post them on the Secret Developer Discord and somebody will assist you shortly.

Introduction

Confidential voting on Secret Network enables developers to create and manage voting systems where proposals and votes remain encrypted and secure. This ensures confidentiality and integrity in voting processes across EVM-compatible chains. There are 2 cross-chain voting solutions on Secret Network, the first uses SecretPath, and the other ECDH cryptography.

1. Enabling Confidential Voting with SecretPath

• Overview: Introduction to using SecretPath as a Confidential Computation Layer for EVM chains, allowing encrypted data transfer and storage on Secret Network. Description of how SecretPath functions as a bridge for encrypted data, facilitating the creation and voting on proposals within a Secret smart contract.

• Setup and Deployment: Step-by-step guide on setting up the development environment, compiling and uploading the Secret contract, and configuring the frontend to interact with the SecretPath-enabled voting system.

• Passing Encrypted Data: Detailed explanation of how to pass encrypted proposals and votes from the EVM to the Secret Network using SecretPath.

1. Encrypting and Decrypting Votes on EVM with ECDH cryptography

• Introduction: Guide to encrypting and decrypting votes using Secret Network smart contracts, aimed at building confidential voting on any EVM chain.

• Setup and Configuration: Instructions for setting up the developer environment, configuring environment variables, and generating cryptographic keys for encryption. Steps to upload and instantiate the Secret Network and Polygon smart contracts, enabling creation and voting on proposals.

• Executing Contracts: Processes for creating proposals, voting, and decrypting votes using the deployed smart contracts on the Polygon testnet and Secret Network.

Overview

SecretPath enables EVM developers to use Secret Network as a Confidential Computation Layer (CCL) for all EVM-compatible chains.

In this developer tutorial, you will learn how to use SecretPath to enable confidential voting on the EVM.

Understanding SecretPath

At a high level, you can think of SecretPath as a confidential bridge that passes encrypted data from your EVM chain to a Secret Network smart contract where the data remains encrypted.

To work with SecretPath, you must first create a Secret smart contract that stores the encrypted data that you want to send from the EVM. For our purposes, we have created a Secret smart contract with 2 functionalities:

1. Create proposals

2. Vote on existing proposals

You create and vote on proposals from the EVM, and then that data is sent to your Secret smart contract via SecretPath where it remains encrypted . Pretty cool, right!? 😎 Let's start by examining our Secret voting contract, and then we will breakdown how to send messages to it from the EVM with SecretPath.

Secret Network Prerequisites

1. Add Secret Network testnet to Keplr.

2. Fund your Secret testnet wallet.

Getting Started with Secret Network

To get started, clone the examples repo:

git clone https://github.com/writersblockchain/secretpath-voting.git

cd into secretpath-tutorials/secretpath-voting/voting-contract:

cd secretpath-voting/voting-contract

Open contract.rs and examine the match statement at line 67:

match handle {
        "create_proposal" => create_proposal(deps, env, msg.input_values, msg.task, msg.input_hash),
        "create_vote" => create_vote(deps, env, msg.input_values, msg.task, msg.input_hash),

        _ => Err(StdError::generic_err("invalid handle".to_string())),
    }

This handle msg is where you define the functionality of your SecretPath contract. For our purposes, we have written the functions create_proposal and create_vote. You can examine those functions in more detail if you'd like and make adjustments as you see fit 🤓.

Compiling and uploading the Secret contract

Update the env file with your Secret Network wallet mnemonic, and rename it ".env" instead of ".env.example"

Compile the contract

make build-mainnet

cd into voting-contract/node:

cd node

Install the node dependencies

npm install

Set SecretPath parameters:

Open upload.js and configure the SecretPath gatewayAddress, gatewayHash, and gatewayPublicKey:

const gatewayAddress = "secret10ex7r7c4y704xyu086lf74ymhrqhypayfk7fkj";

const gatewayHash =
 "ad8ca07ffba1cb26ebf952c29bc4eced8319c171430993e5b5089887f27b3f70";

const gatewayPublicKey =
"0x046d0aac3ef10e69055e934ca899f508ba516832dc74aa4ed4d741052ed5a568774d99d3bfed641a7935ae73aac8e34938db747c2f0e8b2aa95c25d069a575cc8b";

gatewayAddress, gatewayHash, and gatewayPublicKey are needed for instantiating contracts that utilize SecretPath and can be found in the docs here. You will always use these same 3 parameters for instantiating a SecretPath-compatible contract on testnet.

Upload and instantiate the contract:

node upload

Upon successful upload and instantiation, add the contract codeHash and address to your env.

Send encrypted data to your Secret Contract on the EVM

Now that you have instantiated your confidential voting contract on Secret Network, it's time to pass your encrypted data from the EVM to Secret Network. Remember the create_proposal and create_vote functions from the Secret contract? Now you will execute those functions and send encrypted data to the voting contract! 🤯

Bootstrapping the frontend

Let's create and vote on your first proposal with SecretPath!

cd into secretpath-voting/frontend:

cd secretpath-voting/frontend

Install the dependencies

npm i

Configure env

Configure the envwith your confidential voting contractAddress and codeHash.

Run the application

npm run start

You should see the following React application running locally in the browser:

Now, create and vote on a proposal to understand the frontend functionality. Then, let's look at the underlying code to understand how we are passing encrypted data from the EVM to Secret Network 🙂

Passing Encrypted Data with SecretPath

As stated above, we have two functions we are executing with SecretPath: create_proposal and create_vote. In our React application, there are two corresponding components which execute these functions: CreateProposal and VoteonProposal.

Create a Voting Proposal

Open CreateProposal.js and navigate to the handleSubmit function, which contains all of our SecretPath logic.

For our purposes, we only need to examine 2 lines of code, data on line 88 and handle on line 218.

1. data is the encrypted data that we are passing from the EVM to the Secret Network voting contract. It takes a user input of name, description, and end_time. This corresponds with the ProposalStoreMsg in the Secret contract.

2. handle is the function that is actually being called in the Secret contract that you deployed. You are passing the create_proposal handle, which executes the create_proposal function in your Secret voting contract.

Now that you have all of your SecretPath code configured, execute the frontend to send your voting proposal to the Secret contract!

Upon successful execution, your SecretPath transaction hash will be logged in the console.

Vote on a Proposal

Open VoteonProposal.js and navigate to the handleSubmit function, which, again, contains all of our SecretPath logic.

1. data is the encrypted data that we are passing from the EVM to the Secret Network voting contract. It takes a user input of vote, ("yes" or "no"), wallet_address (the wallet address of the voter), and index.This corresponds with the VoteStoreMsg in the Secret contract.

1. handle: You are passing the create_vote handle, which executes the create_vote function in your Secret voting contract.

Execute the frontend to vote on an existing proposal and send the encrypted vote to the Secret contract!

Upon successful execution, your SecretPath transaction hash will be logged in the console.

Secret Queries - retrieving proposals and votes from Secret contract storage

Perhaps you are wondering how the React frontend queries the Secret voting contract to display the data that we pass from the EVM. This is possible with secret.js, the javascript SDK for Secret Network.

We have 2 query functions defined in our Secret voting contract, RetrieveProposals and RetrieveVotes. Once you have created proposals with votes, you can use execute these query functions with secret.js to:

1. Query all proposals

2. Query all votes

These queried proposals and their associated votes are then displayed in our React frontend.

Conclusion

Congrats! You deployed your very own confidential voting contract on Secret Network and used SecretPath to send cross-chain encrypted votes on an EVM chain. See the fullstack demo here. You now have all of the tools you need to start building your own cross-chain SecretPath contracts on the EVM 🎉

If you have any questions or run into any issues, post them on the Secret Developer Discord and somebody will assist you shortly.

// Load the contract ABI into an ethers Interface.
const iface = new ethers.utils.Interface(abi);

// Load routing contract address and code hash from environment variables.
const routing_contract = process.env.REACT_APP_SECRET_ADDRESS;
const routing_code_hash = process.env.REACT_APP_CODE_HASH;

// Connect to the Ethereum network through a web provider (e.g., MetaMask).
const provider = new ethers.providers.Web3Provider(window.ethereum, "any");

// Request user accounts from the Ethereum provider.
const [myAddress] = await provider.send("eth_requestAccounts", []);

// Generate a new random wallet and extract private key and public key.
const wallet = ethers.Wallet.createRandom();
const userPrivateKeyBytes = arrayify(wallet.privateKey);
const userPublicKey = new SigningKey(wallet.privateKey).compressedPublicKey;
const userPublicKeyBytes = arrayify(userPublicKey);

// Hardcoded public key for the gateway and conversion to bytes.
const gatewayPublicKey = "A20KrD7xDmkFXpNMqJn1CLpRaDLcdKpO1NdBBS7VpWh3";
const gatewayPublicKeyBytes = base64_to_bytes(gatewayPublicKey);

// Compute a shared key using Elliptic Curve Diffie-Hellman (ECDH) and hash it with SHA-256.
const sharedKey = await sha256(
  ecdh(userPrivateKeyBytes, gatewayPublicKeyBytes)
);

// Get the selector (method ID) for the `upgradeHandler` function from the ABI.
const callbackSelector = iface.getSighash(
  iface.getFunction("upgradeHandler")
);
const callbackGasLimit = 300000;  // Set the gas limit for the callback.

// Create the data object from form state for payload.
const data = JSON.stringify({
  name: name,
  description: description,
  end_time: minutes,
});

// Determine the appropriate client address based on the network (chainId).
let publicClientAddress;

// Mainnet client addresses by chain ID.
if (chainId === "1") { publicClientAddress = mainnet.publicClientAddressEthereumMainnet; }
// Add similar conditions for other chain IDs, both mainnet and testnet.

// Lowercase the client address to ensure consistency.
const callbackAddress = publicClientAddress.toLowerCase();

// Log relevant information.
console.log("callback address: ", callbackAddress);
console.log(data);
console.log(callbackAddress);

// Construct the payload with necessary information for processing.
const payload = {
  data: data,
  routing_info: routing_contract,
  routing_code_hash: routing_code_hash,
  user_address: myAddress,
  user_key: bytes_to_base64(userPublicKeyBytes),
  callback_address: bytes_to_base64(arrayify(callbackAddress)),
  callback_selector: bytes_to_base64(arrayify(callbackSelector)),
  callback_gas_limit: callbackGasLimit,
};

// Serialize the payload to JSON and prepare it for encryption.
const payloadJson = JSON.stringify(payload);
const plaintext = json_to_bytes(payload);
const nonce = crypto.getRandomValues(bytes(12)); // Generate a nonce for encryption.

// Encrypt the payload using ChaCha20-Poly1305, obtain the ciphertext and authentication tag.
const [ciphertextClient, tagClient] = chacha20_poly1305_seal(
  sharedKey,
  nonce,
  plaintext
);
const ciphertext = concat([ciphertextClient, tagClient]);

// Compute the hashes of the ciphertext and prepare it for signature.
const ciphertextHash = keccak256(ciphertext);
const payloadHash = keccak256(
  concat([
    text_to_bytes("\x19Ethereum Signed Message:\n32"),
    arrayify(ciphertextHash),
  ])
);

// Sign the payload hash using the user's account.
const msgParams = ciphertextHash;
const params = [myAddress, msgParams];
const method = "personal_sign";
const payloadSignature = await provider.send(method, params);

// Recover public key from the signature to verify it.
const user_pubkey = recoverPublicKey(payloadHash, payloadSignature);

// Bundle info for the transaction.
const _info = {
  user_key: hexlify(userPublicKeyBytes),
  user_pubkey: user_pubkey,
  routing_code_hash: routing_code_hash,
  task_destination_network: "pulsar-3",
  handle: "create_proposal",
  nonce: hexlify(nonce),
  payload: hexlify(ciphertext),
  payload_signature: payloadSignature,
  callback_gas_limit: callbackGasLimit,
};

// Encode the transaction data using the interface.
const functionData = iface.encodeFunctionData("send", [
  payloadHash,
  myAddress,
  routing_contract,
  _info,
]);

// Fetch the current gas price and calculate the transaction cost.
const gasFee = await provider.getGasPrice();
let amountOfGas;
if (chainId === "4202") {
  amountOfGas = gasFee.mul(callbackGasLimit).mul(100000).div(2);
} else {
  amountOfGas = gasFee.mul(callbackGasLimit).mul(3).div(2);
}

// Set up transaction parameters.
const tx_params = {
  gas: hexlify(150000),
  to: publicClientAddress,
  from: myAddress,
  value: hexlify(amountOfGas),
  data: functionData,
};

// Send the transaction and handle the response.
try {
  const txHash = await provider.send("eth_sendTransaction", [tx_params]);
  console.log(`Transaction Hash: ${txHash}`);

  setIsModalVisible(true); // Show the modal on success
} catch (error) {
  console.error("Error submitting transaction:", error);
}

For a detailed demonstration, you can watch our video tutorial available here:

After we've gone through an extensive example on how our example contract works, here's how to implement SecretVRF via SecretPath in your own contract in 4 easy steps:

Importing the Interface

First, import the ISecretVRF interface into your Solidity Contract:

/// @notice Interface of the VRF Gateway contract. Must be imported. 
interface ISecretVRF { 
    function requestRandomness(uint32 _numWords, uint32 _callbackGasLimit) external payable returns (uint256 requestId); 
}

Set the SecretVRF gateway contract

Second, set your gateway address to the Secret VRF Gateways. You only need to make sure that your contract knows the correct SecretVRF Gateway address, for example:

/// @notice VRFGateway stores address to the Gateway contract to call for VRF
address public VRFGateway;

address public immutable owner;

constructor() {
   owner = msg.sender;
}

modifier onlyOwner() {
    require(msg.sender == owner, "UNAUTHORIZED");
    _;
}

/// @notice Sets the address to the Gateway contract 
/// @param _VRFGateway address of the gateway
function setGatewayAddress(address _VRFGateway) external onlyOwner {
    VRFGateway = _VRFGateway;
}

Call the SecretVRF Gateway contract

Now, we implement the function that calls the SecretVRF Gateway on EVM. Note that you have to pay an extra amount of your gas token as CallbackGas:

/// @notice Event that is emitted when a VRF call was made (optional) 
/// @param requestId requestId of the VRF request. Contract can track a VRF call that way 
event requestedRandomness(uint256 requestId);

/// @notice Demo function on how to implement a VRF call using Secret VRF
function requestRandomnessTest(uint32 _numWords, uint32 _callbackGasLimit) external payable {
    // Get the VRFGateway contract interface 
    ISecretVRF vrfContract = ISecretVRF(VRFGateway);

    // Call the VRF contract to request random numbers. 
    // Returns requestId of the VRF request. A  contract can track a VRF call that way.
    uint256 requestId = vrfContract.requestRandomness{value: msg.value}(_numWords, _callbackGasLimit);

    // Emit the event
    emit requestedRandomness(requestId);
}

The callback gas is the amount of gas that you have to pay for the message coming on the way back. If you do pay less than the amount specified below, your Gateway TX will fail:

/// @notice Increase the task_id to check for problems 
/// @param _callbackGasLimit the Callback Gas Limit

function estimateRequestPrice(uint32 _callbackGasLimit) private view returns (uint256) {
    uint256 baseFee = _callbackGasLimit*block.basefee;
    return baseFee;
}

Since this check is dependent on the current block.basefee of the block it is included in, it is recommended that you estimate the gas fee beforehand and add some extra overhead to it. An example of how this can be implemented in your frontend can be found in this example and here:

//Then calculate how much gas you have to pay for the callback
//Forumla: callbackGasLimit*block.basefee.
//Use an appropriate overhead for the transaction, 1,5x = 3/2 is recommended since gasPrice fluctuates.

const gasFee = await provider.getGasPrice();
const amountOfGas = gasFee.mul(callbackGasLimit).mul(3).div(2);

Wait for the callback

From here, the SecretVRF Gateway will take care of everything, just wait 1-2 blocks for Gateway to provide you the random number by getting it from the Secret Networks on chain VRF and do the callback.

The SecretVRF gateway contract will always call the contract that called the VRF contract (using msg.sender) with the function selector bytes 0x38ba4614, which is the function:

function fulfillRandomWords(uint256 requestId, uint256[] calldata randomWords) external 

Now, the SecretVRF Gateway contract will verify the validity of the call and when all checks pass, it will call this function. In this case, we just emit a log as an example to finish our demo. Emitting a log is not obligatory and optional.

event fulfilledRandomWords(uint256 requestId, uint256[] randomWords);
/// @notice Callback by the Secret VRF with the requested random numbers
/// @param requestId requestId of the VRF request that was initally called
/// @param randomWords Generated Random Numbers in uint256 array
function fulfillRandomWords(uint256 requestId, uint256[] calldata randomWords) external {
    // Checks if the callback was called by the VRFGateway and not by any other address
    require(msg.sender == address(VRFGateway), "only Secret Gateway can fulfill");

    // Do your custom stuff here, for example:
    emit fulfilledRandomWords(requestId, randomWords);
}

Overview

SecretVRF over SecretPath enables EVM developers to access on-chain verifiable random numbers at a fraction of the cost and block time of traditional RNG oracles such as ChainlinkVRF. With fewer than 100 lines of code, you will have access to an infinite supply of randomness.

Getting Started

To get started, clone the repo:

git clone https://github.com/SecretFoundation/evm-secretpath-rng.git

EVM Prerequisites

1. Add Polygon Amoy testnet to Metamask.

2. Fund your Amoy wallet.

Configuring Environment Variables

Install the node dependencies:

npm install

Update the env file with your EVM wallet private key and Infura API key.

Upload & Instantiate RandomnessReceiver.sol

Compile your Solidity smart contract:

npx hardhat compile

Once the contract is compiled successfully, upload the contract to Polygon testnet:

npx hardhat run scripts/deploy.js --network polygon

Note the contract address:

RandomnessReceiver deployed to: 0x08D05bC52e503C68c38A32c1fA997FB521e614C4

Add the RandomnessReceiver contract address to your env file:

RANDOMNESS_RECEIVER_CONTRACT_ADDRESS="0x08D05bC52e503C68c38A32c1fA997FB521e614C4"

Execute RandomnessReceiver.sol

Now that you've uploaded your contract, it's time to set the SecretPath gateway address for Polygon Amoy and then request on-chain verifiable random numbers!

Set Gateway Contract

First, set the gateway address for Polygon Amoy testnet. You can do this by executing set_gateway.js:

npx hardhat --network polygon run ./scripts/set_gateway.js

Create Randomness Event Listener

Next, create an event listener so you can listen to when the random numbers that you request have been fulfilled.

Create the event listener by executing fulfill_randomness_event.js:

npx hardhat --network polygon run ./scripts/fulfill_randomness_event.js

Request Random Numbers

Now it's time to request random numbers! Currently, request_random.js is configured to request 3 random numbers, but you can update how many numbers you would like to request here (up to 2000 for this example).

Once you have configured how many random numbers you want to request, execute request_random.js:

npx hardhat --network polygon run ./scripts/request_random.js

Upon successful execution, your terminal will log the following:

Current gas price: 1.500000016 gwei
Amount of gas: 202500002160000
Transaction hash: 0x47efe733c6b64a5c65fae68a5fa0f2eb39be107a7d4930325104dfcee36474c2
Random Numbers requested successfully!

Navigate to your event listener terminal to see the returned random numbers:

Random numbers fulfilled for request ID: 7
Random Numbers: 94412630379044474934232934838909700375960606882138821083837396872559692127250,113337239238407277551866961530595655396141218773986266698805816049961297644274,27422614896457590254145871678336430245204859898445275988406473498974116581231

Congrats! You've just used SecretPath to request your first verifiable on-chain random numbers! 🎉

Conclusion

Secret VRF offers an innovative and cost-effective solution for EVM developers seeking access to verifiable random numbers. By following this guide, you've successfully set up your environment, deployed the RandomnessReceiver.sol contract, and interacted with the SecretPath network to request and receive random numbers. Dive into the world of decentralized randomness with SecretPath, where security meets simplicity. 🌟

SecretVRF stands out in the competitive landscape of verifiable random functions (VRFs) by offering a significant cost and speed advantage over its principal competitors. Notably, it provides approximately a 4 times cost benefit, which is a massive saving for projects that rely on random number generation at scale. This economic efficiency is largely due to its optimized gas usage, which minimizes the on-chain transaction cost.

In addition to its cost benefits, SecretVRF is also twice as fast as its closest competitor. This speed improvement is critical for applications that require almost real-time randomness, such as gaming, lotteries, and various DeFi protocols.

To demonstrate, we have this small video here outlining all of the advantages of SecretVRF vs. its biggest competitor:

Gas Figures for SecretVRF vs Competitors

An example contract call using SecretVRF on Ethereum Sepolia which requests 20 random words is compared for its gas usage. Here, we use the example contracts provided in the documentation of Chainlink. In both cases, response time for Secret VRF is at around 1-2 blocks, so around 10s.

For calling the VRF for 20 random numbers (less is better):

94k Gas with Secretpath: Etherscan Sepolia

300k+ Gas for Chainlink VRF with their example project: Etherscan Sepolia

For the Callback (less is better):

55k gas with Secretpath: Etherscan Sepolia

200k+ gas for Chainlink VRF with their example project: Etherscan Sepolia

In total, we also do not need to pay in special LINK tokens and instead can just pay in the native gas token of the chain (here: Sepolia ETH), which saves you additional costs.

To summarize, SecretVRF's combination of cost efficiency, speed, and EVM chain compatibility makes it a compelling choice for developers and projects seeking reliable and economical verifiable random functions. Its technical innovations position it as a leader in the space, offering tangible benefits that can significantly enhance the performance and cost-effectiveness of a wide range of blockchain applications.

Install and import dependencies

First, install all of the the dependencies via NPM:

npm install @solar-republic/cosmos-grpc @solar-republic/neutrino ethers secure-random

Next, import the following into your code:

import { ethers } from "ethers"; 
import { arrayify, hexlify, SigningKey, keccak256, recoverPublicKey, computeAddress } from "ethers/lib/utils"; 
import {ecdh, chacha20_poly1305_seal} from "@solar-republic/neutrino"; 
import {bytes, bytes_to_base64, json_to_bytes, sha256, concat, text_to_bytes, base64_to_bytes} from '@blake.regalia/belt';

In your vite.config.ts in the project, you need to add the support for bigInt into the esbuildOptions:

optimizeDeps: { 
    esbuildOptions: { 
        target: "esnext", 
        supported: { 
        bigint: true 
        }, 
    } 
}

Defining variables

To start, we first define all of our variables that we need for the encryption, as well as the gateway information:

const publicClientAddress = '0x3879E146140b627a5C858a08e507B171D9E43139' //EVM gateway contract address
const routing_contract = "secret1fxs74g8tltrngq3utldtxu9yys5tje8dzdvghr" //the contract you want to call in secret
const routing_code_hash = "49ffed0df451622ac1865710380c14d4af98dca2d32342bb20f2b22faca3d00d" //its codehash

First, we define the Gateway address that is specific to each chain, which can you can look up here Supported Networks.

Second, you need to input the private contract that you are going to call, in our case the Secret VRF RNG contact on Secret Network. The code for this example contract can be found here in case you want to deploy it yourself.

Initializing the Ethereum client

Next, init the Ethereum client that you are using to call the contract with. Here, we init the chainId to use the Ethereum sepolia testnet and use ethers.js to retrieve the address.

 await (window as any).ethereum.request({
    method: 'wallet_switchEthereumChain',
    params: [{ chainId: '0xAA36A7' }], // chainId must be in hexadecimal numbers
});

// @ts-ignore
const provider = new ethers.providers.Web3Provider(window.ethereum);
const [myAddress] = await provider.send("eth_requestAccounts", []);

Generating the encryption key using ECDH

Next, you generate ephermal keys and load in the public encryption key for the Secret Gateway that you can look up in Supported Networks. Then, use ECDH to create the encryption key:

//Generating ephemeral keys
const wallet = ethers.Wallet.createRandom();
const userPrivateKeyBytes = arrayify(wallet.privateKey);
const userPublicKey: string = new SigningKey(wallet.privateKey).compressedPublicKey;
const userPublicKeyBytes = arrayify(userPublicKey)

//Gateway Encryption key for ChaCha20-Poly1305 Payload encryption
const gatewayPublicKey = "A20KrD7xDmkFXpNMqJn1CLpRaDLcdKpO1NdBBS7VpWh3";
const gatewayPublicKeyBytes = base64_to_bytes(gatewayPublicKey);

//create the sharedKey via ECDH
const sharedKey = await sha256(ecdh(userPrivateKeyBytes, gatewayPublicKeyBytes));

Define the Calldata for the secret contract & Callback information

Next, you define all of the information that you need for calling the private contract on Secret + add the callback information for the message on its way back.

We begin by defining the function that we are going to call on the private secret contract, here it's request_random . Next, we add the parameters/calldata for this function, which is ("{ numWords: Number(numWords) }"and convert it into a JSON string.

Next, we define the callback Information. In this case, we are using the gateway contract as an example callback. Here, you would typically put in your own custom callback address and callback selector in.

//the function name of the function that is called on the private contract
const handle = "request_random"

//data are the calldata/parameters that are passed into the contract 
const data = JSON.stringify({ numWords: Number(numWords) })
    
const callbackAddress = publicClientAddress.toLowerCase();
//This is an empty callback for the sake of having a callback in the sample code.
//Here, you would put your callback selector for you contract in. 
const callbackSelector = iface.getSighash(iface.getFunction("upgradeHandler"))
const callbackGasLimit = Number(callback_gas_limit)

After defining the contract call and callback, we now construct the payload:

//payload data that are going to be encrypted
const payload = {
      data: data,
      routing_info: routing_contract,
      routing_code_hash: routing_code_hash,
      user_address: myAddress,
      user_key: bytes_to_base64(userPublicKeyBytes),
      callback_address: bytes_to_base64(arrayify(callbackAddress)),
      callback_selector: bytes_to_base64(arrayify(callbackSelector)),
      callback_gas_limit: callbackGasLimit,
}

Encrypting the Payload

Next, we encrypt the payload using ChaCha20-Poly1305. Then, we hash the encrypted payload into a ciphertextHash using Keccak256.

//build a Json of the payload 
const payloadJson = JSON.stringify(payload); 
const plaintext = json_to_bytes(payload);
//generate a nonce for ChaCha20-Poly1305 encryption 
//DO NOT skip this, stream cipher encryptions are only secure with a random nonce!
const nonce = crypto.getRandomValues(bytes(12));

//Encrypt the payload using ChachaPoly1305 and concat the ciphertext+tag to fit the Rust ChaChaPoly1305 requirements
const [ciphertextClient, tagClient] = chacha20_poly1305_seal(sharedKey, nonce, plaintext);
const ciphertext = concat([ciphertextClient, tagClient]);

//get Metamask to sign the payloadhash with personal_sign
const ciphertextHash = keccak256(ciphertext)

Signing the Payload with Metamask

Next, we use Metamask to sign the ciphertextHash using personal_sign. Then, we recover the user_pubkey from this signed message, which will be also passed into the Public Gateway.

//this is what metamask really signs with personal_sign, it prepends the ethereum signed message here
const payloadHash = keccak256(concat([
      text_to_bytes("\x19Ethereum Signed Message:\n32"),
      arrayify(ciphertextHash),
]))
//this is what we provide to metamask
const msgParams = ciphertextHash;
const from = myAddress;
const params = [from, msgParams];
const method = 'personal_sign';

const payloadSignature = await provider.send(method, params)
console.log(`Payload Signature: ${payloadSignature}`)

const user_pubkey = recoverPublicKey(payloadHash, payloadSignature)
console.log(`Recovered public key: ${user_pubkey}`)

Estimate the Callback Gas

The callback gas is the amount of gas that you have to pay for the message coming on the way back. If you do pay less than the amount specified below, your Gateway TX will fail:

/// @notice Increase the task_id to check for problems 
/// @param _callbackGasLimit the Callback Gas Limit

function estimateRequestPrice(uint32 _callbackGasLimit) private view returns (uint256) {
    uint256 baseFee = _callbackGasLimit*block.basefee;
    return baseFee;
}

Since this check is dependent on the current block.basefee of the block it is included in, it is recommended that you estimate the gas fee beforehand and add some extra overhead to it. An example of how this can be implemented in your frontend can be found in this example and here:

//Then calculate how much gas you have to pay for the callback
//Forumla: callbackGasLimit*block.basefee.
//Use an appropriate overhead for the transaction, 1,5x = 3/2 is recommended since gasPrice fluctuates.

const gasFee = await provider.getGasPrice();
const amountOfGas = gasFee.mul(callbackGasLimit).mul(3).div(2);

Packing the Transaction & Send

Lastly, we pack all the information we collected during previous steps into an info struct that we send into the Gateway contract. We the encode the function data. Finally, we set the tx_params. Please make sure to set an approiate gas amount for your contract call, here we used 150k gas. For the value of the TX, we send over the estimated callback gas that we calculated above.

// function data to be abi encoded
const _userAddress = myAddress
const _routingInfo = routing_contract
const _payloadHash = payloadHash
const _info = {
        user_key: hexlify(userPublicKeyBytes),
        user_pubkey: user_pubkey, 
        routing_code_hash: routing_code_hash,
        task_destination_network: "pulsar-3",  //Destination for the task, here: pulsar-3 testnet
        handle: handle,
        nonce: hexlify(nonce),
        payload: hexlify(ciphertext),
        payload_signature: payloadSignature,
        callback_gas_limit: Number(callbackGasLimit)
}

const functionData = iface.encodeFunctionData("send",
        [
            _payloadHash,
            _userAddress,
            _routingInfo,
            _info,
        ]
    )
    
const tx_params = [
    {
            gas: hexlify(150000),
            to: publicClientAddress,
            from: myAddress,
            value: hexlify(amountOfGas), // send that extra amount of gas in to pay for the Callback Gas Limit that you set
            data: functionData, 
        },
      ];

const txHash = await provider.send("eth_sendTransaction", tx_params);

Converting from Chainlink VRF to Secret VRF is easier than you expect. Within four easy steps you can free your contract from bloat and use the lightweight and faster Secret VRF solution.

We start off with the example code from Chainlink from here:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.7;

import {VRFCoordinatorV2Interface} from "@chainlink/contracts@1.0.0/src/v0.8/vrf/interfaces/VRFCoordinatorV2Interface.sol";
import {VRFConsumerBaseV2} from "@chainlink/contracts@1.0.0/src/v0.8/vrf/VRFConsumerBaseV2.sol";

contract VRFD20 is VRFConsumerBaseV2 {
    uint256 private constant ROLL_IN_PROGRESS = 42;

    VRFCoordinatorV2Interface COORDINATOR;

    // Your subscription ID.
    uint64 s_subscriptionId;

    // Sepolia coordinator. For other networks,
    // see https://docs.chain.link/docs/vrf-contracts/#configurations
    address vrfCoordinator = 0x8103B0A8A00be2DDC778e6e7eaa21791Cd364625;

    // The gas lane to use, which specifies the maximum gas price to bump to.
    // For a list of available gas lanes on each network,
    // see https://docs.chain.link/docs/vrf-contracts/#configurations
    bytes32 s_keyHash =
        0x474e34a077df58807dbe9c96d3c009b23b3c6d0cce433e59bbf5b34f823bc56c;

    // Depends on the number of requested values that you want sent to the
    // fulfillRandomWords() function. Storing each word costs about 20,000 gas,
    // so 40,000 is a safe default for this example contract. Test and adjust
    // this limit based on the network that you select, the size of the request,
    // and the processing of the callback request in the fulfillRandomWords()
    // function.
    uint32 callbackGasLimit = 40000;

    // The default is 3, but you can set this higher.
    uint16 requestConfirmations = 3;

    // For this example, retrieve 1 random value in one request.
    // Cannot exceed VRFCoordinatorV2.MAX_NUM_WORDS.
    uint32 numWords = 1;
    address s_owner;

    // map rollers to requestIds
    mapping(uint256 => address) private s_rollers;
    // map vrf results to rollers
    mapping(address => uint256) private s_results;

    event DiceRolled(uint256 indexed requestId, address indexed roller);
    event DiceLanded(uint256 indexed requestId, uint256 indexed result);

    constructor(uint64 subscriptionId) VRFConsumerBaseV2(vrfCoordinator) {
        COORDINATOR = VRFCoordinatorV2Interface(vrfCoordinator);
        s_owner = msg.sender;
        s_subscriptionId = subscriptionId;
    }

    function rollDice(
        address roller
    ) public onlyOwner returns (uint256 requestId) {
        require(s_results[roller] == 0, "Already rolled");
        // Will revert if subscription is not set and funded.
        requestId = COORDINATOR.requestRandomWords(
            s_keyHash,
            s_subscriptionId,
            requestConfirmations,
            callbackGasLimit,
            numWords
        );

        s_rollers[requestId] = roller;
        s_results[roller] = ROLL_IN_PROGRESS;
        emit DiceRolled(requestId, roller);
    }

    function fulfillRandomWords(
        uint256 requestId,
        uint256[] memory randomWords
    ) internal override {
        uint256 d20Value = (randomWords[0] % 20) + 1;
        s_results[s_rollers[requestId]] = d20Value;
        emit DiceLanded(requestId, d20Value);
    }

    function house(address player) public view returns (string memory) {
        require(s_results[player] != 0, "Dice not rolled");
        require(s_results[player] != ROLL_IN_PROGRESS, "Roll in progress");
        return getHouseName(s_results[player]);
    }

    function getHouseName(uint256 id) private pure returns (string memory) {
        string[20] memory houseNames = [
            "Targaryen",
            "Lannister",
            "Stark",
            "Tyrell",
            "Baratheon",
            "Martell",
            "Tully",
            "Bolton",
            "Greyjoy",
            "Arryn",
            "Frey",
            "Mormont",
            "Tarley",
            "Dayne",
            "Umber",
            "Valeryon",
            "Manderly",
            "Clegane",
            "Glover",
            "Karstark"
        ];
        return houseNames[id - 1];
    }

    modifier onlyOwner() {
        require(msg.sender == s_owner);
        _;
    }
}

Removing Chainlink bloat

In the first step, we remove the imports and the inheritance of the VRFConsumerBaseV2 and add our SecretVRF interface from this. There is no

import {VRFCoordinatorV2Interface} from "@chainlink/contracts@1.0.0/src/v0.8/vrf/interfaces/VRFCoordinatorV2Interface.sol";
import {VRFConsumerBaseV2} from "@chainlink/contracts@1.0.0/src/v0.8/vrf/VRFConsumerBaseV2.sol";

contract VRFD20 is VRFConsumerBaseV2 {
    uint256 private constant ROLL_IN_PROGRESS = 42;

    VRFCoordinatorV2Interface COORDINATOR;

    // Your subscription ID.
    uint64 s_subscriptionId;

    // Sepolia coordinator. For other networks,
    // see https://docs.chain.link/docs/vrf-contracts/#configurations
    address vrfCoordinator = 0x8103B0A8A00be2DDC778e6e7eaa21791Cd364625;

    // The gas lane to use, which specifies the maximum gas price to bump to.
    // For a list of available gas lanes on each network,
    // see https://docs.chain.link/docs/vrf-contracts/#configurations
    bytes32 s_keyHash =
        0x474e34a077df58807dbe9c96d3c009b23b3c6d0cce433e59bbf5b34f823bc56c;
        
    // Depends on the number of requested values that you want sent to the
    // fulfillRandomWords() function. Storing each word costs about 20,000 gas,
    // so 40,000 is a safe default for this example contract. Test and adjust
    // this limit based on the network that you select, the size of the request,
    // and the processing of the callback request in the fulfillRandomWords()
    // function.
    uint32 callbackGasLimit = 40000;
    //...
}

to get to this:

interface ISecretVRF { 
    function requestRandomness(uint32 _numWords, uint32 _callbackGasLimit) external payable returns (uint256 requestId); 
}
contract VRFD20 {
    uint256 private constant ROLL_IN_PROGRESS = 42;
    //...
    
    // Depends on the number of requested values that you want sent to the
    // fulfillRandomWords() function. Storing each word costs about 20,000 gas,
    // so 40,000 is a safe default for this example contract. Test and adjust
    // this limit based on the network that you select, the size of the request,
    // and the processing of the callback request in the fulfillRandomWords()
    // function.
    uint32 callbackGasLimit = 40000;
    
    // Sepolia Gateway. For other networks,
    // see https://docs.chain.link/docs/vrf-contracts/#configurations
    address public VRFGateway = 0x3879E146140b627a5C858a08e507B171D9E43139;
}

Here, the behavior of the callbackGasLimit is different than in ChainlinkVRF. The callback Gas limit is simply all of the gas that you need to pay in order to make callback, which includes the verification of the result as well. The callback gas is the amount of gas that you have to pay for the message coming on the way back. We recommend at least using 100_000+ in Callback gas to ensure that enough gas is available. In case you did not pay enough gas, the contract callback execution will fail.

Simplifying the Constructor

Next, we can also simplify the constructor since we do not need to define any extra variables or subscriptionIds. Going from this:

constructor(uint64 subscriptionId) VRFConsumerBaseV2(vrfCoordinator) {
        COORDINATOR = VRFCoordinatorV2Interface(vrfCoordinator);
        s_owner = msg.sender;
        s_subscriptionId = subscriptionId;
}

to this

constructor()  {
        s_owner = msg.sender;
}

Change request randomness function

Next, we need to slightly adjust the behavior of the function rollDice(address roller) function and how it calls the Request Randomness function within Secret VRF. Here, we need to use the Secret VRF gateway and call it directly instead.

function rollDice(
        address roller
    ) public payable onlyOwner returns (uint256 requestId) {
        require(s_results[roller] == 0, "Already rolled");
        // Will revert if subscription is not set and funded.

        // Get the VRFGateway contract interface 
        ISecretVRF vrfContract = ISecretVRF(VRFGateway);
    
        // Call the VRF contract to request random numbers. 
        // Returns requestId of the VRF request. A  contract can track a VRF call that way.
        uint256 requestId = vrfContract.requestRandomness{value: msg.value}(_numWords, _callbackGasLimit);

        s_rollers[requestId] = roller;
        s_results[roller] = ROLL_IN_PROGRESS;
        emit DiceRolled(requestId, roller);
    }
}

Please make sure to actually prepay the right amount of callback gas directly as a value transfer into the contract. The callback gas is the amount of gas that you have to pay for the message coming on the way back. If you do pay less than the amount specified below, your Gateway TX will fail:

/// @notice Increase the task_id to check for problems 
/// @param _callbackGasLimit the Callback Gas Limit

function estimateRequestPrice(uint32 _callbackGasLimit) private view returns (uint256) {
    uint256 baseFee = _callbackGasLimit*block.basefee;
    return baseFee;
}

Since this check is dependent on the current block.basefee of the block it is included in, it is recommended that you estimate the gas fee beforehand and add some extra overhead to it. An example of how this can be implemented in your frontend can be found in this example and here:

//Then calculate how much gas you have to pay for the callback
//Forumla: callbackGasLimit*block.basefee.
//Use an appropriate overhead for the transaction, 1,5x = 3/2 is recommended since gasPrice fluctuates.

const gasFee = await provider.getGasPrice();
const amountOfGas = gasFee.mul(callbackGasLimit).mul(3).div(2);

Add a check for the Secret VRF Gateway

Lastly, we'll add a small check to ensure that we actually got an incoming call from the SecretVRF gateway contract. For this, remove the internal and override flags on the function and add the require:

function fulfillRandomWords(
        uint256 requestId,
        uint256[] memory randomWords
    ) external {
        require(msg.sender == address(VRFGateway), "only Secret Gateway can fulfill");

        uint256 d20Value = (randomWords[0] % 20) + 1;
        s_results[s_rollers[requestId]] = d20Value;
        emit DiceLanded(requestId, d20Value);
}

Conclusion

That's all that you need to convert your contract from ChainlinkVRF to SecretVRF.

Introduction

In this tutorial you will learn how to implement the @secret-network/share-document SDK to store, view, and share confidential documents on the EVM using Secret Network as a confidential storage layer.

By using our SDK, you will have the possibility to:

• Store a new document

• See the contents of this document

• Grant/Revoke access to the document to another wallet address

Note that when you want to share a document with another wallet address, you need to provide the Secret Network address of the person you want to share it with.

Getting Started

Create an empty wagmi project:

npm create wagmi

During the install process, wagmi will ask you to select a framework and a variant. To follow along with this tutorial, select React for framework, and Next for variant. Once you have installed your wagmi project, cd into your project:

cd <your project name>

Install the dependencies & the sdk:

npm i @secret-network/share-document

This tutorial will teach you how to use the SDK on Polygon Mainnet. Update your wagmi.ts file for Polygon Mainnet configuration like so:

import { http, createConfig } from 'wagmi'
import { polygon } from 'wagmi/chains'
import { coinbaseWallet, injected, walletConnect } from 'wagmi/connectors'

export const config = createConfig({
  chains: [polygon], // Add Polygon chain
  connectors: [
    injected(),
    coinbaseWallet({ appName: 'Create Wagmi' }),
    // walletConnect({ projectId: process.env.NEXT_PUBLIC_WC_PROJECT_ID }),
  ],
  ssr: true,
  transports: {
    [polygon.id]: http(), // Add polygon chain
  },
})

declare module 'wagmi' {
  interface Register {
    config: typeof config
  }
}

Create a .env file with the following content since we are interacting with the Polygon Mainnet contract:

ENVIRONMENT= "mainnet" 

ENVIRONMENT can use the following variables depending on which dev environment you are using:
"mainnet" | "testnet" | "local"

Custom chain

import { scroll } from "viem/chains";
import { Config, EvmChain } from "@secret-network/share-document"

const config = new Config({
  sourceChain: EvmChain.SCROLL,
  customChain: scroll  
});

Storage API Keys

Next, navigate to Pinata and generate a new API key + JWT token to use for storing documents. Make sure you save the credentials in a safe place because we will use them shortly :D

React Imports & State Variables

Navigate to /src/page.tsx.

Configure your React imports + state viarables like so:

'use client'

import { useAccount, useConnect, useDisconnect, useWalletClient } from 'wagmi'
import { Config, SecretDocumentClient, Environment, MetaMaskWallet, PinataStorage } from "@secret-network/share-document";
import { useEffect, useState } from 'react';

function App() {
  const { address } = useAccount();
  const { connectors, connect, status, error } = useConnect();
  const { disconnect } = useDisconnect();
  const { data: walletClient } = useWalletClient();
  const [client, setClient] = useState<SecretDocumentClient>();
  const [downloadFileId, setDownloadFileId] = useState('');
  const [shareFileId, setShareFileId] = useState('');
  const [secretAddress, setSecretAddress] = useState('');
}

Your environment is now configured to store confidential documents on Polygon Mainnet using Secret Network!

Initialize the Client

Configure the SDK client like so:

// Initialize user wallet for the SDK
  useEffect(() => {
    const initializeClient = async () => {
      if (!walletClient) return;

      const config = new Config({ env: Environment.MAINNET });
      config.useEvmWallet({ client: walletClient });
      console.log("config: ", config);

      const wallet = await MetaMaskWallet.create(window.ethereum, address || "");
      config.useSecretWallet(wallet);

      const gateway = "https://gateway.pinata.cloud";
      const accessToken = "Your JWT token";
      
      const pinataStorage = new PinataStorage(gateway, accessToken);
      config.useStorage(pinataStorage);

      const secretClient = new SecretDocumentClient(config);
      setClient(secretClient);
      console.log("client: ", secretClient);
    };

    initializeClient();
  }, [walletClient, address]);

Store a File

// Store File to Secret Network
  const storeFile = async () => {
    if (!client) {
      console.error('Client is not initialized');
      return;
    }
    try {
      const file = new File(["Hello, world!"], "hello.txt", { type: "text/plain" });
      const res = await client.storeDocument().fromFile(file); 
      console.log('File stored successfully:', res);
    } catch (error) {
      console.error('Error storing file:', error);
    }
  };

View a File

 // View file
  const viewFile = async () => {
    if (!client) {
      console.error('Client is not initialized');
      return;
    }
    try {
      const res = await client.viewDocument().getAllFileIds();
      console.log('File viewed successfully:', res);
    } catch (error) {
      console.error('Error viewing file:', error);
    }
  };

Download a File

// Download file
  const downloadFile = async (fileId: string) => {
    if (!client) {
      console.error('Client is not initialized');
      return;
    }
    try {
      const uint8Array = await client.viewDocument().download(fileId);

      // Convert Uint8Array to Blob
      const blob = new Blob([uint8Array], { type: 'application/octet-stream' });

      // Create a link element
      const link = document.createElement('a');
      link.href = URL.createObjectURL(blob);
      link.download = 'downloaded_file'; // Set the desired file name here

      // Append the link to the body
      document.body.appendChild(link);

      // Programmatically click the link to trigger the download
      link.click();

      // Remove the link from the document
      document.body.removeChild(link);

      console.log('File downloaded successfully');
    } catch (error) {
      console.error('Error downloading file:', error);
    }
  };

Share a File

// Share file
  const shareFile = async (fileId: string, secretAddress: string) => {
    if (!client) {
      console.error('Client is not initialized');
      return;
    }
    try {
      const shareDocument = client.shareDocument(fileId);

      // Get existing file access
      // const fileAccess = await shareDocument.getFileAccess();
      // console.log('Existing file access:', fileAccess);

      // Share viewing access to a file
      const addViewingRes = await shareDocument.addViewing([secretAddress]);
      console.log('Viewing access added:', addViewingRes);

      // Delete viewing access to a file
      // const deleteViewingRes = await shareDocument.deleteViewing([secretAddress]);
      // console.log('Viewing access deleted:', deleteViewingRes);

      // Transfer the ownership
      // const changeOwnerRes = await shareDocument.changeOwner(secretAddress);
      // console.log('Ownership transferred:', changeOwnerRes);

      // All in one share operation
      const shareRes = await shareDocument.share({
        // changeOwner: secretAddress,
        addViewing: [secretAddress],
        // deleteViewing: [secretAddress],
      });
      console.log('All-in-one share operation completed:', shareRes);

    } catch (error) {
      console.error('Error sharing file:', error);
    }
  };

Summary

This documentation provides a step-by-step guide on how to implement the @secret-network/share-document SDK to securely store, view, and share confidential documents on the EVM using Secret Network as a confidential storage layer. You learned how to create a new wagmi project, configure it for Polygon Mainnet, and integrate the Secret Network SDK. By following this guide, you can now store documents, view their content, and manage access permissions all on the EVM chain of your choosing.

Special Thanks

Special thanks to the FiftyWei team for building out this SDK as part of the Secret Network Q1 2024 grants cohort :D

An Axelar deposit address is a temporary one-time address created and monitored by Axelar’s Relayer Services.

The following tutorials will teach you how to create Axelar deposit addresses to send Axelar USDC cross-chain from EVM to Secret Network and from Secret Network to EVM.

Installing the dependencies

Create a new package.json file and install axelarjs

npm init -y && npm i @axelar-network/axelarjs-sdk

Add type "module" to package.json:

{
  "name": "evm-to-secret",
  "type" : "module",
  "version": "1.0.0",
  "main": "evm-to-secret.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "description": "",
  "dependencies": {
    "@axelar-network/axelarjs-sdk": "^0.16.1"
  }
}

Creating the deposit address

Create a new file named evm-to-secret.js (or whatever you would like to name it) and add the following code to create an Axelar deposit address:

import {
    AxelarAssetTransfer,
    CHAINS,
    Environment,
  } from "@axelar-network/axelarjs-sdk";
  
  const sdk = new AxelarAssetTransfer({ environment: "testnet" });
  
  async function createDepositAddress() {
    const fromChain = CHAINS.TESTNET.SEPOLIA,
      toChain = "secret-snip-3",
      destinationAddress = "secret1j7n3xx4sfgjea4unghd78qvnvxdz49cxmrkqlj",
      asset = "uausdc";
  
    const depositAddress = await sdk.getDepositAddress({
      fromChain,
      toChain,
      destinationAddress,
      asset,
    });
    console.log(depositAddress);
  }
  
  createDepositAddress();

Run node evm-to-secret to execute createDepositAddress:

node evm-to-secret

A deposit address will be returned in your terminal:

0x1f92fEb04737dd2aE59841a1C3806797086143Da

Sending USDC from EVM to Secret Network

Add the Sepolia USDC token to your wallet. Sepolia USDC token contract address:

0x254d06f33bDc5b8ee05b2ea472107E300226659A

Fund your wallet with testnet Sepolia USDC by bridging AXL to sepolia USDC.

First, go to the Axelar discord faucet channel and request testnet tokes from the faucet:

!faucet <your wallet address here>

Then, send testnet USDC from your Axelar wallet address to your Sepolia address using Axelar Satelite:

Now, simply send Sepolia USDC from your wallet to the deposit address that you created earlier!

Summary

Congrats! You've successfully sent cross-chain USDC from Sepolia testnet to Secret Network using Axelarjs! If you have any questions, ping dev-issues on Discord and a developer from the Secret community will assist you shortly.

To access the SecretPath gateways, please refer to the gateway contracts for testnet and mainnet here:

1. EVM Mainnet

2. EVM Testnet

To access configuration files for SecretPath, please refer to the repository here:

1. SecretPath Configuration files

The ABI for the EVM Gateway contract on version 0.2.3 is the following:

[{"type":"constructor","inputs":[],"stateMutability":"nonpayable"},{"type":"function","name":"VRF_routing_code_hash","inputs":[],"outputs":[{"name":"","type":"string","internalType":"string"}],"stateMutability":"view"},{"type":"function","name":"VRF_routing_info","inputs":[],"outputs":[{"name":"","type":"string","internalType":"string"}],"stateMutability":"view"},{"type":"function","name":"increaseTaskId","inputs":[{"name":"_newTaskId","type":"uint256","internalType":"uint256"}],"outputs":[],"stateMutability":"nonpayable"},{"type":"function","name":"initialize","inputs":[],"outputs":[],"stateMutability":"nonpayable"},{"type":"function","name":"owner","inputs":[],"outputs":[{"name":"","type":"address","internalType":"address"}],"stateMutability":"view"},{"type":"function","name":"payoutBalance","inputs":[],"outputs":[],"stateMutability":"nonpayable"},{"type":"function","name":"postExecution","inputs":[{"name":"_taskId","type":"uint256","internalType":"uint256"},{"name":"_sourceNetwork","type":"string","internalType":"string"},{"name":"_info","type":"tuple","internalType":"struct Gateway.PostExecutionInfo","components":[{"name":"payload_hash","type":"bytes32","internalType":"bytes32"},{"name":"packet_hash","type":"bytes32","internalType":"bytes32"},{"name":"callback_address","type":"bytes20","internalType":"bytes20"},{"name":"callback_selector","type":"bytes4","internalType":"bytes4"},{"name":"callback_gas_limit","type":"bytes4","internalType":"bytes4"},{"name":"packet_signature","type":"bytes","internalType":"bytes"},{"name":"result","type":"bytes","internalType":"bytes"}]}],"outputs":[],"stateMutability":"nonpayable"},{"type":"function","name":"renounceOwnership","inputs":[],"outputs":[],"stateMutability":"nonpayable"},{"type":"function","name":"requestRandomness","inputs":[{"name":"_numWords","type":"uint32","internalType":"uint32"},{"name":"_callbackGasLimit","type":"uint32","internalType":"uint32"}],"outputs":[{"name":"requestId","type":"uint256","internalType":"uint256"}],"stateMutability":"payable"},{"type":"function","name":"secret_gateway_signer_address","inputs":[],"outputs":[{"name":"","type":"address","internalType":"address"}],"stateMutability":"view"},{"type":"function","name":"send","inputs":[{"name":"_payloadHash","type":"bytes32","internalType":"bytes32"},{"name":"_userAddress","type":"address","internalType":"address"},{"name":"_routingInfo","type":"string","internalType":"string"},{"name":"_info","type":"tuple","internalType":"struct Gateway.ExecutionInfo","components":[{"name":"user_key","type":"bytes","internalType":"bytes"},{"name":"user_pubkey","type":"bytes","internalType":"bytes"},{"name":"routing_code_hash","type":"string","internalType":"string"},{"name":"task_destination_network","type":"string","internalType":"string"},{"name":"handle","type":"string","internalType":"string"},{"name":"nonce","type":"bytes12","internalType":"bytes12"},{"name":"callback_gas_limit","type":"uint32","internalType":"uint32"},{"name":"payload","type":"bytes","internalType":"bytes"},{"name":"payload_signature","type":"bytes","internalType":"bytes"}]}],"outputs":[{"name":"_taskId","type":"uint256","internalType":"uint256"}],"stateMutability":"payable"},{"type":"function","name":"taskId","inputs":[],"outputs":[{"name":"","type":"uint256","internalType":"uint256"}],"stateMutability":"view"},{"type":"function","name":"task_destination_network","inputs":[],"outputs":[{"name":"","type":"string","internalType":"string"}],"stateMutability":"view"},{"type":"function","name":"tasks","inputs":[{"name":"","type":"uint256","internalType":"uint256"}],"outputs":[{"name":"payload_hash_reduced","type":"bytes31","internalType":"bytes31"},{"name":"completed","type":"bool","internalType":"bool"}],"stateMutability":"view"},{"type":"function","name":"transferOwnership","inputs":[{"name":"newOwner","type":"address","internalType":"address"}],"outputs":[],"stateMutability":"nonpayable"},{"type":"function","name":"upgradeHandler","inputs":[],"outputs":[],"stateMutability":"nonpayable"},{"type":"event","name":"FulfilledRandomWords","inputs":[{"name":"requestId","type":"uint256","indexed":true,"internalType":"uint256"}],"anonymous":false},{"type":"event","name":"Initialized","inputs":[{"name":"version","type":"uint64","indexed":false,"internalType":"uint64"}],"anonymous":false},{"type":"event","name":"OwnershipTransferred","inputs":[{"name":"previousOwner","type":"address","indexed":true,"internalType":"address"},{"name":"newOwner","type":"address","indexed":true,"internalType":"address"}],"anonymous":false},{"type":"event","name":"TaskCompleted","inputs":[{"name":"taskId","type":"uint256","indexed":true,"internalType":"uint256"},{"name":"callbackSuccessful","type":"bool","indexed":false,"internalType":"bool"}],"anonymous":false},{"type":"event","name":"logNewTask","inputs":[{"name":"task_id","type":"uint256","indexed":true,"internalType":"uint256"},{"name":"source_network","type":"string","indexed":false,"internalType":"string"},{"name":"user_address","type":"address","indexed":false,"internalType":"address"},{"name":"routing_info","type":"string","indexed":false,"internalType":"string"},{"name":"payload_hash","type":"bytes32","indexed":false,"internalType":"bytes32"},{"name":"info","type":"tuple","indexed":false,"internalType":"struct Gateway.ExecutionInfo","components":[{"name":"user_key","type":"bytes","internalType":"bytes"},{"name":"user_pubkey","type":"bytes","internalType":"bytes"},{"name":"routing_code_hash","type":"string","internalType":"string"},{"name":"task_destination_network","type":"string","internalType":"string"},{"name":"handle","type":"string","internalType":"string"},{"name":"nonce","type":"bytes12","internalType":"bytes12"},{"name":"callback_gas_limit","type":"uint32","internalType":"uint32"},{"name":"payload","type":"bytes","internalType":"bytes"},{"name":"payload_signature","type":"bytes","internalType":"bytes"}]}],"anonymous":false},{"type":"error","name":"InvalidInitialization","inputs":[]},{"type":"error","name":"NotInitializing","inputs":[]},{"type":"error","name":"OwnableInvalidOwner","inputs":[{"name":"owner","type":"address","internalType":"address"}]},{"type":"error","name":"OwnableUnauthorizedAccount","inputs":[{"name":"account","type":"address","internalType":"address"}]}]

For the Secret Network mainnet (secret-4) side, the gateway contract information are:

• Gateway contract code id: 1533

• Gateway contract address: secret1qzk574v8lckjmqdg3r3qf3337pk45m7qd8x02a

• Gateway contract code hash: 012dd8efab9526dec294b6898c812ef6f6ad853e32172788f54ef3c305c1ecc5

• Gateway encryption key for ChaChaPoly1305: AqDWMqzQ0vXaAvw4XqMKjeq01WOdGoIaOlUmJa0PF1nQ

• Public key (uncompressed):

As Hex:

0x04a0d632acd0d2f5da02fc385ea30a8deab4d5639d1a821a3a552625ad0f1759d0d2e80ca3adb236d90caf1b12e0ddf3a351c5729b5e00505472dca6fed5c31e2a

As Base64:

BKDWMqzQ0vXaAvw4XqMKjeq01WOdGoIaOlUmJa0PF1nQ0ugMo62yNtkMrxsS4N3zo1HFcpteAFBUctym/tXDHio=

• Derived Ethereum Address from Public Key: 0x88e43F4016f8282Ea6235aC069D02BA1cE5417aB

The RNG contract that provides the Randomness is:

• RNG contract code id: 1925

• RNG contract address: secret10jyexwp4zrv50eysn3l7n4n2spf0u380lcq5nz

• RNG contract code hash: 0b9395a7550b49d2b8ed73497fd2ebaf896c48950c4186e491ded6d22e58b8c3

For the Secret Network testnet (pulsar-3) side, the gateway contract information are:

• Gateway contract code id: 3375

• Gateway contract address: secret10ex7r7c4y704xyu086lf74ymhrqhypayfk7fkj

• Gateway contract code hash: ad8ca07ffba1cb26ebf952c29bc4eced8319c171430993e5b5089887f27b3f70

• Gateway encryption key for ChaChaPoly1305: A20KrD7xDmkFXpNMqJn1CLpRaDLcdKpO1NdBBS7VpWh3

• Public key (uncompressed):

As Hex:

0x046d0aac3ef10e69055e934ca899f508ba516832dc74aa4ed4d741052ed5a568774d99d3bfed641a7935ae73aac8e34938db747c2f0e8b2aa95c25d069a575cc8b

As Base64:

BG0KrD7xDmkFXpNMqJn1CLpRaDLcdKpO1NdBBS7VpWh3TZnTv+1kGnk1rnOqyONJONt0fC8OiyqpXCXQaaV1zIs=

• Derived EVM Address from Public Key: 0x2821E794B01ABF0cE2DA0ca171A1fAc68FaDCa06

The RNG contract that provides the Randomness is:

• RNG contract code id: 10212

• RNG contract address: secret1cknezaxnzfys2w8lyyrr7fed9wxejvgq7alhqx

• RNG contract code hash: 0b9395a7550b49d2b8ed73497fd2ebaf896c48950c4186e491ded6d22e58b8c3