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

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`

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`

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`

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`

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

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

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`

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

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`

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

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

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

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

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

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`

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

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`

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

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`

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`

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

Last modified 8mo ago