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	Set bonder fees for each asset in terms of basis points (BPS).
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.

pageKeystore

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.

urlhttps://github.com/hop-protocol/docs/blob/master/hop-node/running/signer.md

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