Deploy an EVM <-> SVM Warp Route

Prerequisites

Ensure you have the following installed and configured:

Hyperlane Monorepo
Rust (latest stable version)
Yarn and Node.js (latest stable version)
Solana CLI tools

Walkthrough

Step 1: Create the Warp Route Directory

In ./rust/sealevel/environments/${environment}, create a directory called warp-routes
Inside warp-routes, create a new directory for your Warp Route deployment, e.g., e.g. environments/mainnet3/warp-routes/pzeth
Optional: If you want to, open a PR to the hyperlane-registry with metadata to associate with the synthetic token in the Warp Route. Example here.
- Tip: Although not critical, for the image field try to pick a source that is unlikely to break the URL

Step 2: Deploy on the SVM Side

From here on, to deploy on the SVM side you can also follow our official guide for tips: Deploy SVM Warp Route

Create token-config.json for the SVM configuration, e.g.

{
  "solana": {
    "type": "synthetic",
    "decimals": 9,
    "name": "Renzo Restaked LST",
    "symbol": "pzETH",
    "uri": "<https://raw.githubusercontent.com/hyperlane-xyz/hyperlane-registry/12660fd34d30e960a748d87408a8d88f634f7454/deployments/warp_routes/pzETH/ethereum-solana-metadata.json>",
    "interchainGasPaymaster": "5FG1TUuhXGKdMbbH8uHEnUghazD4aVfEPAgKLNGNx3SL",
    "remoteDecimals": 18
  }
}

Often EVM tokens have 18 decimals, which are too large for the SVM. The pattern is to bridge them into SOL as 9 decimals. This can be done using remoteDecimals: 18.

Run the deployment command:

cargo run -- -k ~/solana-mainnet-deployer-keypair.json warp-route deploy \
--warp-route-name pzeth  \
--environment mainnet3  \
--environments-dir ../environments  \
--built-so-dir ../../target/deploy  \
--token-config-file ../environments/mainnet3/warp-routes/pzeth/token-config.json  \
--chain-config-file ../environments/mainnet3/chain-config.json  \
--ata-payer-funding-amount 50000000

Step 3: Deploy on the Ethereum Side

Deploy the Ethereum Warp Route contract, which will also enroll the SVM router based on the yaml token config.
1. Check out the monorepo branch from this PR#4447
2. Build the TS code from project root: yarn && yarn build
3. Run the CLI from source: yarn workspace @hyperlane-xyz/cli hyperlane
4. Create a YAML Warp Route configuration file using this template and steps:
  - Set interchainSecurityModule: "0x0000000000000000000000000000000000000000" to use the default ISM set in the destination chain Mailbox
  - Set the gas to a ceiling of the compute units you expect the SVM message delivery transaction to take. For instance, Hyperlane Warp Routes have gas set to 300. It's important for this to be an upper limit - the relayer will not deliver Warp Route transfer messages otherwise, because senders would pay an insufficient amount to have them delivered.
```
ethereum:
  interchainSecurityModule: "0x0000000000000000000000000000000000000000"
  isNft: false
  mailbox: "0xc005dc82818d67AF737725bD4bf75435d065D239"
  owner: "0xa7ECcdb9Be08178f896c26b7BbD8C3D4E844d9Ba"
  token: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
  type: collateral
  gas: 300000
eclipsemainnet:
  foreignDeployment: "D6k6T3G74ij6atCtBiWBs5TbFa1hFVcrFUSGZHuV7q3Z"
  mailbox: "EitxJuv2iBjsg2d7jVy2LDC1e2zBrx4GB5Y9h2Ko3A9Y"
  owner: "9bRSUPjfS3xS6n5EfkJzHFTRDa4AHLda8BU2pP4HoWnf"
  interchainSecurityModule: "0x0000000000000000000000000000000000000000"
  type: synthetic
  gas: 300000
```
5. Deploy using the Hyperlane CLI:
  - Run the deploy command, pointing to your YAML Warp Route config: yarn workspace @hyperlane-xyz/cli hyperlane warp deploy --config /path/to/config/warp-route-deployment.yaml
  - You’ll have the deployment artifact logged by the command, and also stored in your filesystem registry (currently ~/.hyperlane).
6. Confirm the deployment using the Hyperlane CLI:
```
$ cast call 0x1D622da2ce4C4D9D4B0611718cb3BcDcAd008DD4 'routers(uint32)(bytes32)' $DESTINATION_DOMAIN --rpc-url $(rpc ethereum) 1399811149
0xe9792265ec273ffc17731af890d3e9963e9d744e7b99f02491911ce1bb75b8cb
```

Step 4: Update the SVM token-config.json

Back to Solana tooling now, update the token-config.json with the foreign deployment:

The fields for ethereum should be set to values from the Warp Route contract artifact. token should be set to collateralAddressOrDenom (the address of the token being bridge), and foreignDeployment should be set to addressOrDenom (the address of the Warp Route contract, like HypERC20Collateral).

{
  "solana": {
    "type": "synthetic",
    "decimals": 9,
    "name": "Renzo Restaked LST",
    "symbol": "pzETH",
    "uri": "<https://raw.githubusercontent.com/hyperlane-xyz/hyperlane-registry/12660fd34d30e960a748d87408a8d88f634f7454/deployments/warp_routes/pzETH/ethereum-solana-metadata.json>",
    "interchainGasPaymaster": "5FG1TUuhXGKdMbbH8uHEnUghazD4aVfEPAgKLNGNx3SL",
    "remoteDecimals": 18
  },
  "ethereum": {
    "type": "collateral",
    "decimals": 18,
    "token": "0x8c9532a60e0e7c6bbd2b2c1303f63ace1c3e9811",
    "foreignDeployment": "0x1D622da2ce4C4D9D4B0611718cb3BcDcAd008DD4"
  }
}

Step 5: Deployment

Run the final deployment command:

cargo run -- -k ~/solana-mainnet-deployer-keypair.json warp-route deploy  \
--warp-route-name pzeth \
--environment mainnet3 \
--environments-dir ../environments \
--built-so-dir ../../target/deploy \
--token-config-file ../environments/mainnet3/warp-routes/pzeth/token-config.json  \
--chain-config-file ../environments/mainnet3/chain-config.json  \
--ata-payer-funding-amount 50000000

Deploy an EVM <-> SVM Warp Route

Prerequisites​

Walkthrough​

Step 1: Create the Warp Route Directory​

Step 2: Deploy on the SVM Side​

Step 3: Deploy on the Ethereum Side​

Step 4: Update the SVM token-config.json​

Step 5: Deployment​