Developer Docs v2

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

NameTypeDescriptionExample

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

NameTypeDescriptionExample

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

NameTypeDescriptionExample

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

NameTypeDescriptionExample

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

NameTypeDescriptionExample

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

NameTypeDescriptionExample

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

NameTypeDescriptionExample

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

NameTypeDescriptionExample

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

NameTypeDescriptionExample

fromChainId

number

The origin chain of the message.

eg. 420

transactionHash

string

The tx hash that contains the MessageSent event.

eg. 0xdccaf2fc42186d66f72869ecb12b0be1f9b9c018a43a13f4ff32ee3eaa0d943c

Response

NameTypeDescriptionExample

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

NameTypeDescriptionExample

fromChainId

number

The origin chain of the message.

eg. 420

messageId

string

The messageId from the MessageSent event

eg. 0xf672a68db7ebbac6e28bc217967a83d5fc63f0f185a9c25b1693a3afb445a696

Response

NameTypeDescriptionExample

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

NameTypeDescriptionExample

fromChainId

number

From chain ID

eg. 420

messageId

string

The messageId from the MessageSent event

eg. 0xf672a68db7ebbac6e28bc217967a83d5fc63f0f185a9c25b1693a3afb445a696

Response

NameTypeDescriptionExample

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

NameTypeDescriptionExample

fromChainId

number

The origin chain the message will be sent from.

eg. 420

toChainId

number

The destination chain for the message.

eg. 5

Response

NameTypeDescriptionExample

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

NameTypeDescriptionExample

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

NameTypeDescriptionExample

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

NameTypeDescriptionExample

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

NameTypeDescriptionExample

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

NameTypeDescriptionExample

<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

Last updated