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

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

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

Connecting Metamask to Secret Network

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

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.

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.

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 ✨

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 😊

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.

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.