Getting started

⚠️ JavaScript SDK is in beta

Install module

Using NPM:

npm install @hop-protocol/v2-sdk

Using Yarn:

yarn add @hop-protocol/v2-sdk

CDN

jsDeliver CDN:

<script src="https://cdn.jsdelivr.net/npm/@hop-protocol/v2-sdk@latest/hop.js"></script>

unpkg CDN:

<script src="https://unpkg.com/@hop-protocol/v2-sdk@latest/hop.js"></script>

Import module

Import as ES6 module (e.g. Using TypeScript, babel, webpack):

import { Hop } from '@hop-protocol/v2-sdk'

Import as commonJS module (e.g. Using Node.js directly or no ES6 modules):

const { Hop } = require('@hop-protocol/v2-sdk')

Instantiate SDK

import { Hop } from '@hop-protocol/v2-sdk'

const hop = new Hop('goerli')

Avaiable networks are only goerli at this time.

Send Message

Send a message from one chain to another chain.

Use this method to get the populated transaction for sending a message.

Method: getSendMessagePopulatedTx

Parameters

Name	Type	Description	Example
fromChainId	number	The origin chain the message will be sent from.	eg. 420
toChainId	number	This is the destination chain where the message should be received.	eg. 5
toAddress	string	The address to call at the destination.	eg. 0x5f335A890bbB5Cd1a4a7f7A1C8F9F6F75efDCA89
toCalldata	string	The tx calldata to execute at the destination address.	eg. 0x812448a5000000000000000000000000000000000000000000000000000000000000002a

Response

Name	Type	Description	Example
data	string	Calldata	eg. 0x7056f41f00...
to	string	Address	eg. 0xeA35E10f763ef2FD5634dF9Ce9ad00434813bddB
chainId	number	Chain ID	eg. 420
value	string	Message fee value as wei	eg. 1000000000000

Example

import { Hop } from '@hop-protocol/v2-sdk'

async function main() {
  const fromChainId = 420
  const toChainId = 5
  const toAddress = "0x5f335A890bbB5Cd1a4a7f7A1C8F9F6F75efDCA89"
  const toCalldata = "0x812448a5000000000000000000000000000000000000000000000000000000000000002a"

  const hop = new Hop('goerli')
  const txData = await hop.getSendMessagePopulatedTx({
    fromChainId,
    toChainId,
    toAddress,
    toCalldata
  })
  console.log(txData)
}

main().catch(console.error)

Get Bundle Proof

Get bundle proof needed to relay message at destination chain.

Use this method to get the bundle proof JSON.

Method: getBundleProofFromMessageId

Parameters

Name	Type	Description	Example
fromChainId	number	The origin chain the message was sent from.	eg. 420
toChainId	number	The destination chain specified for the message.	eg. 5
messageId	string	The message ID hash. This is emitted in the MessageSent event.	eg. 0xe8e4885871d370ef17693db9fc0f34bda218c8685a9bb3ab40648cf8d2a5358e

Response

Name	Type	Description	Example
bundleId	string	Bundle ID	eg. 0x5e26c4282d410e7e0c892561566ce0a6522f4762de1fc59d9bfba068890d9f7d
treeIndex	number	Message tree index	eg. 2
siblings	string[]	Proof sibling nodes	eg. ["0xf672a68db7...", "0xb93f64fa40..."]
totalLeaves	number	Total leaves that make up root	eg. 4

Example

import { Hop } from '@hop-protocol/v2-sdk'

async function main() {
  const fromChainId = 420
  const toChainId = 5
  const messageId = "0xe8e4885871d370ef17693db9fc0f34bda218c8685a9bb3ab40648cf8d2a5358e"

  const hop = new Hop('goerli')
  const bundleProof = await hop.getBundleProofFromMessageId({
    fromChainId,
    messageId
  })
  console.log(bundleProof)
}

main().catch(console.error)

Relay Message

Relay and execute message at the destination

Use this method to get the populated transaction for relaying a message.

Method: getRelayMessagePopulatedTx

Parameters

Name	Type	Description	Example
fromChainId	number	The origin chain the message was sent from.	eg. 420
toChainId	number	The destination chain specified for the message.	eg. 5
from	string	The sender address that sent the original message.	eg. 0x9997da3de3ec197C853BCC96CaECf08a81dE9D69
toCalldata	string	The destination calldata specified when sending the message.	eg. 0x812448a5000000000000000000000000000000000000000000000000000000000000002a
bundleProof	object	The bundle proof JSON which can be generated by calling the getBundleProofFromMessageId method.	eg. { "bundleId": "0x5e26c4282d4...", "treeIndex": 2, "siblings": [ "0xb93f64fa4...." ], "totalLeaves": 3 }

Response

Name	Type	Description	Example
data	string	Calldata	eg. 0x7ad7be77000000000...
to	string	Address	eg. 0xE3F4c0B210E7008ff5DE92ead0c5F6A5311C4FDC
chainId	number	Chain ID	eg. 5

Example

import { Hop } from '@hop-protocol/v2-sdk'

async function main() {
  const fromChainId = 420
  const toChainId = 5
  const fromAddress = "0x9997da3de3ec197C853BCC96CaECf08a81dE9D69"
  const toAddress = "0x5f335A890bbB5Cd1a4a7f7A1C8F9F6F75efDCA89"
  const toCalldata = "0x812448a5000000000000000000000000000000000000000000000000000000000000002a"
  const bundleProof = {
    "bundleId": "0x5e26c4282d410e7e0c892561566ce0a6522f4762de1fc59d9bfba068890d9f7d",
    "treeIndex": 2,
    "siblings": [
      "0xb93f64fa408f10085138ba6ea27c42d5832869d6c1c6667c25c022cdeaf03390"
    ],
    "totalLeaves": 3
  }

  const hop = new Hop('goerli')
  const txData = await hop.getRelayMessagePopulatedTx({
    fromChainId,
    toChainId,
    fromAddress,
    toAddress,
    toCalldata,
    bundleProof
  })
  console.log(txData)
}

main().catch(console.error)

Exit Bundle

Exit bundle at the destination.

Use this method to get the populated transaction for exiting a bundle.

Method: getBundleExitPopulatedTx

Parameters

Name	Type	Description	Example
fromChainId	number	The origin chain of the message route.	eg. 420
bundleCommittedTransactionHash	string	The transaction hash that has the BundleCommitted event of the bundleId to exit.	eg. 0xf7aa4bccf0ffe34d76ceb1f18864a2dbfd590bdfca44ad29a316079559327020

Response

Name	Type	Description	Example
data	string	Calldata	eg. 0x7ad7be77000000000...
to	string	Address	eg. 0xE3F4c0B210E7008ff5DE92ead0c5F6A5311C4FDC
chainId	number	Chain ID	eg. 5

Example

import { Hop } from '@hop-protocol/v2-sdk'

async function main() {
  const fromChainId = 420
  const bundleCommittedTransactionHash = "0xf7aa4bccf0ffe34d76ceb1f18864a2dbfd590bdfca44ad29a316079559327020"

  const hop = new Hop('goerli')
  const txData = await hop.getBundleExitPopulatedTx({
    fromChainId,
    bundleCommittedTransactionHash
  })
  console.log(txData)
}

main().catch(console.error)

Get Message ID

Get Message ID from transaction hash.

Method: getMessageIdFromTransactionHash

Parameters

Name	Type	Description	Example
fromChainId	number	The origin chain of the message.	eg. 420
transactionHash	string	The tx hash that contains the MessageSent event.	eg. 0xdccaf2fc42186d66f72869ecb12b0be1f9b9c018a43a13f4ff32ee3eaa0d943c

Response

Name	Type	Description	Example
messageId	string	Message ID	eg. 0xf672a68db7ebbac6e28bc217967a83d5fc63f0f185a9c25b1693a3afb445a696

Example

import { Hop } from '@hop-protocol/v2-sdk'

async function main() {
  const fromChainId = 420
  const transactionHash = "0xdccaf2fc42186d66f72869ecb12b0be1f9b9c018a43a13f4ff32ee3eaa0d943c"

  const hop = new Hop('goerli')
  const messageId = await hop.getMessageIdFromTransactionHash({
    fromChainId,
    transactionHash
  })
  console.log(messageId)
}

main().catch(console.error)

Get Message Calldata

Get calldata of message given message ID

Method: getMessageCalldata

Parameters

Name	Type	Description	Example
fromChainId	number	The origin chain of the message.	eg. 420
messageId	string	The messageId from the MessageSent event	eg. 0xf672a68db7ebbac6e28bc217967a83d5fc63f0f185a9c25b1693a3afb445a696

Response

Name	Type	Description	Example
calldata	string	Calldata of message	eg. 0x812448a5000000000000000000000000000000000000000000000000000000000000002a

Example

import { Hop } from '@hop-protocol/v2-sdk'

async function main() {
  const fromChainId = 420
  const messageId = "0xf672a68db7ebbac6e28bc217967a83d5fc63f0f185a9c25b1693a3afb445a696"

  const hop = new Hop('goerli')
  const calldata = await hop.getMessageCalldata({
    fromChainId,
    messageId
  })
  console.log(calldata)
}

main().catch(console.error)

Get Message Sent Event

Get full event log from message ID

Method: getMessageSentEventFromMessageId

Parameters

Name	Type	Description	Example
fromChainId	number	From chain ID	eg. 420
messageId	string	The messageId from the MessageSent event	eg. 0xf672a68db7ebbac6e28bc217967a83d5fc63f0f185a9c25b1693a3afb445a696

Response

Name	Type	Description	Example
event	object	Message event log	eg. {"messageId": "0xf672a68d...", "from": "0x651...", "toChainId": 5, ...}

Example

import { Hop } from '@hop-protocol/v2-sdk'

async function main() {
  const fromChainId = 420
  const messageId = "0xf672a68db7ebbac6e28bc217967a83d5fc63f0f185a9c25b1693a3afb445a696"

  const hop = new Hop('goerli')
  const event = await hop.getMessageSentEventFromMessageId({
    fromChainId,
    messageId
  })
  console.log(event)
}

main().catch(console.error)

Get Message Fee

Get fee in wei required to send message

Method: getMessageFee

Parameters

Name	Type	Description	Example
fromChainId	number	The origin chain the message will be sent from.	eg. 420
toChainId	number	The destination chain for the message.	eg. 5

Response

Name	Type	Description	Example
value	string	Message fee in wei	eg. 1000000000000

Example

import { Hop } from '@hop-protocol/v2-sdk'

async function main() {
  const hop = new Hop('goerli')
  const fromChainId = 420
  const toChainId = 5

  const fee = await hop.getMessageFee({
    fromChainId,
    toChainId
  })
  console.log(fee)
}

main().catch(console.error)

Get Events

Get decoded events for hub and spoke contracts.

Method: getEvents

Parameters

Name	Type	Description	Example
eventNames	string[]	List of event names to fetch. Options are: ["BundleCommitted","BundleForwarded","BundleReceived","BundleSet","FeesSentToHub","MessageBundled","MessageRelayed","MessageReverted","MessageSent"]	eg. ["MessageSent", "MessageBundled"]
chainId	number	Chain ID	eg. 420
fromBlock	number	From block number	eg. 4554675
toBlock	number	To block number	eg. 4555675

Response

Name	Type	Description	Example
events	object[]	Event logs	eg. [{"eventName": "MessageSent", ... }]

Example

import { Hop } from '@hop-protocol/v2-sdk'

async function main() {
  const eventNames = ["MessageSent", "MessageBundled"]
  const chainId = 420
  const fromBlock = 4554675
  const toBlock = 4555675

  const hop = new Hop('goerli')
  const events = await hop.getEvents({
    eventNames,
    chainId,
    fromBlock,
    toBlock
  })
  console.log(events)
}

main().catch(console.error)

Set Contract Addresses

Set contract addresses config for sdk

Method: setContractAddresses

Parameters

Name	Type	Description	Example
chainId	number	Chain ID of messenger contract.	eg. 420
startBlock	number	Block contract was deployed at. This is used as start block when fetching events.	eg. 420
spokeCoreMessenger	string	The address of the SpokeCoreMessenger contract.	eg. 0xE3F4c0B210E7008ff5DE92ead0c5F6A5311C4FDC

Response

void

Example

import { Hop } from '@hop-protocol/v2-sdk'

async function main() {
  const contractAddresses = {
  "5": {
    "chainId": 5,
    "startBlock": 8095954,
    "hubCoreMessenger": "0xE3F4c0B210E7008ff5DE92ead0c5F6A5311C4FDC",
    "spokeCoreMessenger": "0xE3F4c0B210E7008ff5DE92ead0c5F6A5311C4FDC",
    "ethFeeDistributor": "0xf6eED903Ac2A34E115547874761908DD3C5fe4bf"
  },
  "420": {
    "chainId": 420,
    "startBlock": 3218800,
    "spokeCoreMessenger": "0xeA35E10f763ef2FD5634dF9Ce9ad00434813bddB",
    "connector": "0x6be2E6Ce67dDBCda1BcdDE7D2bdCC50d34A7eD24"
  }
}

  const hop = new Hop('goerli')
  hop.setContractAddresses(contractAddresses)
}

main().catch(console.error)

Get Contract Addresses

Get hub and spoke contract addresses sdk is using.

Method: getContractAddresses

Parameters

None

Response

Name	Type	Description	Example
chainId	number	Chain ID of messenger contract.	eg. 420
startBlock	number	Block contract was deployed at. This is used as start block when fetching events.	eg. 420
spokeCoreMessenger	string	The address of the SpokeCoreMessenger contract.	eg. 0xE3F4c0B210E7008ff5DE92ead0c5F6A5311C4FDC

Example

import { Hop } from '@hop-protocol/v2-sdk'

async function main() {
  const hop = new Hop('goerli')
  const contractAddresses = await hop.getContractAddresses()
  console.log(contractAddresses)
}

main().catch(console.error)

Set RPC Providers

Set custom RPC Providers config

Method: setRpcProviders

Parameters

Name	Type	Description	Example
<chainId>	string	Chain ID	eg. "420"
<rpcUrl>	string	RPC URL	eg. "https://goerli.optimism.io"

Response

void

Example

import { Hop } from '@hop-protocol/v2-sdk'

async function main() {
  const rpcProviders = {
  "5": "https://goerli.infura.io/v3/84842078b09946638c03157f83405213",
  "420": "https://goerli.optimism.io"
}

  const hop = new Hop('goerli')
  hop.setRpcProviders(rpcProviders)
}

main().catch(console.error)

More examples

If you'd like to see more examples or have any feedback, message us on Discord!

SDK API Reference

API Reference

Contract addresses

https://github.com/hop-protocol/v2-docs/blob/master/smart-contracts/contract-addresses.md