User Docs

Configuration

Bonder configuration examples

The bonder configuration will prepare the networks and assets supported by your bonder. The config is very custom to your bonder, so please read through each item carefully.

Below is an example of a USDC bonder running on Ethereum, Gnosis, Polygon, Optimism, and Arbitrum.

Configuration example

{
  "network": "mainnet",
  "chains": {
    "ethereum": {
      "rpcUrl": "https://mainnet.infura.io/v3/84842078b09946638c03157f83405213",
      "maxGasPrice": 500
    },
    "gnosis": {
      "rpcUrl": "https://rpc.gnosischain.com",
      "customSyncType": "threshold",
      "maxGasPrice": 90
    },
    "polygon": {
      "rpcUrl": "https://polygon-rpc.com",
      "customSyncType": "threshold",
      "maxGasPrice": 5000
    },
    "optimism": {
      "rpcUrl": "https://mainnet.optimism.io",
      "customSyncType": "threshold",
      "maxGasPrice": 500
    },
    "arbitrum": {
      "rpcUrl": "https://arb1.arbitrum.io/rpc",
      "customSyncType": "threshold",
      "maxGasPrice": 500
    }
  },
  "tokens": {
    "USDC": true
  },
  "routes": {
    "ethereum": {
      "polygon": true,
      "gnosis": true,
      "arbitrum": true,
      "optimism": true
    },
    "polygon": {
      "ethereum": true,
      "gnosis": true,
      "arbitrum": true,
      "optimism": true
    },
    "gnosis": {
      "ethereum": true,
      "polygon": true,
      "arbitrum": true,
      "optimism": true
    },
    "arbitrum": {
      "ethereum": true,
      "polygon": true,
      "gnosis": true,
      "optimism": true
    },
    "optimism": {
      "ethereum": true,
      "polygon": true,
      "gnosis": true,
      "arbitrum": true
    }
  },
  "db": {
    "location": "/root/.hop/db"
  },
  "logging": {
    "level": "debug"
  },
  "keystore": {
    "location": "/root/.hop/keystore.json",
    "parameterStore": "/Hop/Bonder/Keystore/Pass",
    "awsRegion": "us-east-1"
  },
  "watchers": {
    "bondTransferRoot": true,
    "bondWithdrawal": true,
    "commitTransfers": true,
    "settleBondedWithdrawals": true,
    "confirmRoots": true,
    "L1ToL2Relay": true
  },
  "commitTransfers": {
    "minThresholdAmount": {
      "USDC": {
        "polygon": {
          "ethereum": 170000,
          "gnosis": 50000,
          "optimism": 130000,
          "arbitrum": 130000
        },
        "gnosis": {
          "ethereum": 170000,
          "polygon": 130000,
          "optimism": 130000,
          "arbitrum": 130000
        },
        "optimism": {
          "ethereum": 170000,
          "polygon": 130000,
          "gnosis": 50000,
          "arbitrum": 130000
        },
        "arbitrum": {
          "ethereum": 170000,
          "polygon": 130000,
          "gnosis": 50000,
          "optimism": 130000
        }
      }
    }
  },
  "fees": {
    "USDC": {
      "ethereum": 14,
      "polygon": 14,
      "gnosis": 25,
      "optimism": 14,
      "arbitrum": 14
    }
  }
}

Properties

Key
Value

network

The Ethereum network to use. (e.g. "mainnet', "goerli")

chains

Chain configuration such as RPC URLs and max gas prices to use. See chains section below for details.

tokens

List of tokens and their bridges that bonder will interact with. See tokens section below for details.

routes

Desired routes to bond withdrawals.

db

Cache db options. See db section below for details.

logging

Logging options. See logging section below for details.

keystore

Keystore options. See keystores section below for details.

watchers

List of watchers.

commitTransfers

Configuration for committing transfers.

fees

bonders

List of other bonders, used for calculating total available liquidity. See bonders section below for details.

signer

Signer options. See signer section below for details.

chains

Specify configuration options for each chain.

The RPC URL is optional and a default will be used if not specified. The redundant RPC URLs are optional. If supplied, these URLs will be utilized to confirm data on the source chain before proceeding with a transaction on the destination chain."

Note: If the selected network doesn't support a chain, it will be ignored.

"chains": {
  "<chain-slug>": {
    "rpcUrl": "<chain-rpc-url>",
    "customSyncType": "<custom-sync-type", // Not applicable if `chain-slug` is `ethereum`
    "maxGasPrice": "<max-gas-price>",
    "redundantRpcUrls": ["<chain-rpc-url>, ..."]
  },
  ...
}

Chain slug options:

Chain slug
Description

ethereum

Ethereum

gnosis

Gnosis Chain (formerly xDai)

arbitrum

Arbitrum One

optimism

Optimism

polygon

Polygon (formerly Matic)

nova

Arbitrum Nova

base

Base

linea

Linea

polygonzk

Polygon zkEVM

tokens

Specify which tokens and their token bridges to interactive with:

"tokens": {
  "USDC": true,
  ...
}

routes

Specify which routes to bond:

"routes": {
  "ethereum": {
    "polygon": true,
    "gnosis": true,
    "arbitrum": true,
    "optimism": true
  },
  "polygon": {
    "ethereum": true,
    "gnosis": true,
    "arbitrum": true,
    "optimism": true
  },
  ...
}

The structure is source -> destination, for example:

"routes": {
  "polygon": {
    "gnosis": true
  },
  ...
}

The above example means that the bonder will bond transfers at the destination sent from polygon->gnosis.

db

Configure options for leveldb database used for caching:

Key
Default value
Description

location

~/.hop/db

Location for cache db.

logging

Configure logging levels:

Key
Default value
Description

level

debug

Logging level. Options are "debug", "info", "warn", "error"

keystore

Configure options for keystore:

Key
Default value
Example
Description

location

~/.hop/keystore.json

~/.hop/keystore.json

Location of keystore to use.

pass

mysecret

Passphrase for encrypted keystore.

parameterStore

/Hop/Bonder/Keystore/Pass

Use AWS SSM Parameter Store for keystore password.

awsRegion

us-east-1

us-east-1

AWS region to use when using SSM Parameter Store.

watchers

Watchers are like services in the Hop Node.

Watcher
Description

bondTransferRoot

Bond transfer roots leaving ORUs

bondWithdrawal

Bond withdrawals sent across chains

commitTransfers

Commit transfers to create a transfer root

settleBondedWithdrawals

Settle individual transfers

confirmRoots

Confirm transfer roots on L1

L1ToL2Relay

Relay messages sent from L1 to L2

They should all be enabled unless there's a specific reason not to enable certain watchers.

commitTransfers

The minThresholdAmount is used to determine when to commit the bundle of transfers.

The format is token: { source: { destination: amount } }

This example will commit transfers when a total of at least 20,000 MATIC are pending commit in the bundle, going either from gnosis->ethereum or polygon->ethereum, and a 10,000 threshold for the direction gnosis->polygon or polygon->gnosis.

"commitTransfers": {
  "minThresholdAmount": {
    "USDC": {
      "gnosis": {
        "ethereum": 20000,
        "polygon": 10000
      },
      "polygon": {
        "ethereum": 20000,
        "gnosis": 10000
      }
    }
  }
}

fees

Configure fee options. The fees are in basis points:

"fees": {
  "USDC": {
    "ethereum": 14,
    "polygon": 14,
    "gnosis": 25,
    "optimism": 14,
    "arbitrum": 14
  },
    ...
}

bonders

List of bonders, used for calculating total available liquidity.

The format is

"[TOKEN]": {
  "[SOURCE_CHAIN]": {
    "[DESTINATION_CHAIN]": "[BONDER_ADDRESS]"
  }
}

Full example:

  "bonders": {
    "ETH": {
      "ethereum": {
        "optimism": "0x710bDa329b2a6224E4B44833DE30F38E7f81d564",
        "arbitrum": "0x710bDa329b2a6224E4B44833DE30F38E7f81d564",
        "gnosis": "0x710bDa329b2a6224E4B44833DE30F38E7f81d564",
        "polygon": "0x710bDa329b2a6224E4B44833DE30F38E7f81d564"
      },
      "optimism": {
        "ethereum": "0x710bDa329b2a6224E4B44833DE30F38E7f81d564",
        "arbitrum": "0x710bDa329b2a6224E4B44833DE30F38E7f81d564",
        "gnosis": "0x710bDa329b2a6224E4B44833DE30F38E7f81d564",
        "polygon": "0x710bDa329b2a6224E4B44833DE30F38E7f81d564"
      },
      "arbitrum": {
        "ethereum": "0x710bDa329b2a6224E4B44833DE30F38E7f81d564",
        "optimism": "0x710bDa329b2a6224E4B44833DE30F38E7f81d564",
        "gnosis": "0x710bDa329b2a6224E4B44833DE30F38E7f81d564",
        "polygon": "0x710bDa329b2a6224E4B44833DE30F38E7f81d564"
      },
      "gnosis": {
        "ethereum": "0x710bDa329b2a6224E4B44833DE30F38E7f81d564",
        "arbitrum": "0x710bDa329b2a6224E4B44833DE30F38E7f81d564",
        "optimism": "0x710bDa329b2a6224E4B44833DE30F38E7f81d564",
        "polygon": "0x710bDa329b2a6224E4B44833DE30F38E7f81d564"
      },
      "polygon": {
        "ethereum": "0x710bDa329b2a6224E4B44833DE30F38E7f81d564",
        "arbitrum": "0x710bDa329b2a6224E4B44833DE30F38E7f81d564",
        "gnosis": "0x710bDa329b2a6224E4B44833DE30F38E7f81d564",
        "optimism": "0x710bDa329b2a6224E4B44833DE30F38E7f81d564"
      }
    },
    ...
  }

blocklist

Configure a blocklist of addresses for bonder to not bond transfers.

Using local blocklist file of addresses:

"blocklist": {
  "path": "/root/.hop/blocklist.txt"
}

Using remote blocklist file of addresses:

"blocklist": {
  "path": "https://example.com/blocklist.txt"
}

Using inline list of blocklisted addresses:

"blocklist": {
  "addresses": {
    "0x123...": true,
    "0xabc...": true
  }
}

Note: The Hop Node will need to be restarted whenever updating local, remote, or inline blocklist of addresses.

OFAC list: https://www.treasury.gov/ofac/downloads/sdnlist.txt

signer

Configure options for signer:

Key
Default value
Example
Description

type

lambda

Type of signer to use. Either kms or lambda.

keyId

11223344

AWS KMS keyId.

awsRegion

us-east-1

AWS region to use when using KMS or Lambda.

lambdaFunctionName

myFunction

Name fo the Lambda function to call.

Environment variables

Key
Value

BONDER_PRIVATE_KEY

Private key to use for signing transactions if not using an encrypted keystore.

KEYSTORE_PASS

Keystore passphrase if using encrypted keystore and not using password file or AWS Parameter Store option.

Notifications

Slack

The Hop Node can post to Slack when an error occurs or when it sends transactions.

To set it up, configure the following environment variables:

Key
Example Value
Description

SLACK_AUTH_TOKEN

xoxb-123...890

Slack Bot Auth Token

SLACK_CHANNEL

mychannel

Channel ID or name to post to

SLACK_USERNAME

"Hop Node"

Username to give to bot

More granular options for Slack channels:

Key
Example Value
Description

SLACK_WARN_CHANNEL

warning-logs

(optional) Channel for posting warning logs

SLACK_ERROR_CHANNEL

error-logs

(optional) Channel for posting error logs

SLACK_INFO_CHANNEL

info-logs

(optional) Channel for posting info logs

SLACK_LOG_CHANNEL

debug-logs

(optional) Channel for posting debug logs

SLACK_SUCCESS_CHANNEL

success-logs

(optional) Channel for posting success logs

GAS_BOOST_WARN_SLACK_CHANNEL

gasboost-warning-logs

(optional) Channel for wallet signer warning logs

GAS_BOOST_ERROR_SLACK_CHANNEL

gasboost-error-logs

(optional) Channel for wallet signer error logs

Last updated