Hop Docs
Developer Docs v2
Search
K

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

Contract addresses