Wormhole Gateway Onboarding Instructions

This page is for any Cosmos chain developer who wants to enable bridging from Gateway. Gateway is Wormhole's Cosmos chain that leverages the Wormhole Guardian network for easy bridging from Ethereum to Cosmos. For an overview of Gateway, see The Gateway to Cosmos.

Propose Adding Your Chain to the Wormhole Guardians

1. Open a new GitHub governance discussion under Wormhole Gateway by filling out the Cosmos Chain Governance Proposal Template
2. Allow 96 hours for discussion and governance vote

Join the Wormhole Discord

1. Join the Wormhole Discord
2. Ping the moderator, Susu (susu.wormhole), to get added to the #guardian-cosmos channel

Establish an IBC Connection

1. Allowlist your IBC relayer on Wormhole Gateway

   1. The IBC relayer should generate an address via the wormchaind CLI

   2. Fill out the IBC relayer allowlist request template below and post the request in the #guardian-cosmos channel

      View IBC relayer allowlist request template

      Hey @Guardians! Thank you for passing governance to support **[Cosmos Chain]** via Wormhole Gateway. We are very excited to integrate with Wormhole!
      
      We will be using **[Relayer Provider]** as our IBC relayer to support the connection to Wormhole Gateway. Their address is **[Wormhole Gateway address].** 
      
      Could one of the Guardians please allowlist this address so that it can submit transactions to Wormhole Gateway?
      
      We understand that if this address misbehaves, the sponsoring Guardian can remove it from the allowlist at any time, which would effectively shut down IBC bridging to/from our chain and Gateway.
      
      Thank you!
      

2. Establish the IBC connection

   1. Please ensure that the parameters trusting_period and trust_threshold are set to the safest values. For example:
      1. Trust_threshold should be 2/3
      2. Trusting_period should be 2/3 of the unbonding period of your chain
   2. Please see Wormchain Syncing documentation to learn how to set up your own Wormhole Gateway node to connect your IBC relayer to. Alternatively, you can browse and connect to available public nodes on the Cosmos chain registry

   3. Below, you'll find an example IBC relayer configuration for Wormhole Gateway

      View example IBC relayer configuration for Wormhole Gateway

      [global]
      log_level = "info"
      
      [mode.clients]
      enabled = true
      refresh = true
      misbehaviour = false
      
      [mode.connections]
      enabled = false
      
      [mode.channels]
      enabled = false
      
      [mode.packets]
      enabled = true
      clear_interval = 50
      clear_on_start = true
      tx_confirmation = true
      auto_register_counterparty_payee = false
      
      [rest]
      enabled = true
      host = "127.0.0.1"
      port = 3000
      
      [telemetry]
      enabled = true
      host = "127.0.0.1"
      port = 3001
      
      [telemetry.buckets.latency_submitted]
      start = 500
      end = 20000
      buckets = 10
      
      [telemetry.buckets.latency_confirmed]
      start = 1000
      end = 30000
      buckets = 10
      
      [[chains]]
      id = "wormchain"
      type = "CosmosSdk"
      rpc_addr = "..."
      grpc_addr = "..."
      rpc_timeout = "10s"
      trusted_node = true
      account_prefix = "wormhole"
      key_name = "default"
      key_store_type = "Test"
      store_prefix = "ibc"
      default_gas = 1000000
      max_gas = 9000000
      gas_multiplier = 1.2
      max_msg_num = 30
      max_tx_size = 180000
      max_grpc_decoding_size = 33554432
      clock_drift = "5s"
      max_block_time = "30s"
      ccv_consumer_chain = false
      memo_prefix = ""
      sequential_batch_tx = false
      trusting_period = '14days'
      
      [chains.event_source]
      mode = "push"
      url = "..."
      batch_delay = "500ms"
      
      [chains.trust_threshold]
      numerator = "2"
      denominator = "3"
      
      [chains.gas_price]
      price = 0.0
      denom = "utest"
      
      [chains.packet_filter]
      policy = 'allow'
      list = [
      ['transfer', 'channel-3'], # Osmosis transfer
      ]
      
      [chains.address_type]
      derivation = "cosmos"
      

3. Share the IBC connection details in the #guardian-cosmos channel along with a request to the Wormhole contributors to prepare governance for the IBC connection. Allow 48 hours for governance vote on accepting this IBC channel

Optional UI Integration with Wormhole Connect

Wormhole Connect is a seamless way to embed bridging directly to your app with three lines of code. Integrating Connect is fast, customizable, and brings all the functionality and utility of Wormhole right into your own application.

If you'd like to add your Cosmos chain into Wormhole Connect, please refer to these reference PRs. Wormhole core contributors will need to review your PRs prior to merging them.

1. Add your Cosmos chain ID to the Wormhole SDK
2. Add your Cosmos chain to Wormhole Connect

Register Assets

This final step involves registering bridged assets with the Cosmos Chain Registry and other relevant wallet and frontend registries.

1. Permissionlessly attest the assets you want to bridge into your chain (if not already attested) to Wormhole Gateway
2. Raise relevant PRs to ensure that explorers, wallets, and other UIs recognize the Wormhole assets when they are bridged to your chain. Here is an example PR adding Wormhole assets to Osmosis Mintscan

Congratulations! You’ve successfully connected your Cosmos chain to Gateway. If you have any questions or concerns, please contact Susu on the Wormhole Discord.