3. Running an Agent
3.2. Configuring the Agent
An agent can be configured via a configuration file or command line options, or a
combination of both. One can specify a TOML configuration file via the
An example configuration:
log-level = "debug" artifacts-dir = "deployments/artifacts/goerli" abi-dir = "deployments/abis/goerli" fill-wait-time = 120 unsafe-fill-time = 600 poll-period = 5.0 confirmation-blocks = 0 min-source-balance = 0.1 [account] path = "account.json" password = "test" [metrics] prometheus-port = 9101 [base-chain] rpc-url = "GOERLI_TESTNET_RPC_URL" [chains.goerli-arbitrum] rpc-url = "GOERLI_ARBITRUM_RPC_URL" confirmation-blocks = 1 poll-period = 60.0 min-source-balance = 0.2 [chains.goerli-optimism] rpc-url = "GOERLI_OPTIMISM_RPC_URL" [tokens] # Each token is represented by a pair [chain-id, token-address]. # All tokens within the same list are considered equivalent and # transfers between them are allowed. # A third value per token representation is optional, which defines # the allowance amount, the agent will approve to the fill manager contract. # [chain-id, token-address, allowance] # Allowed values are: # - Any value > 0, which defines the exact allowance given # - -1, the agent will approve type(uint256).max # If no value is given, the requested amount will be approved TST = [ ["421613", "0x2644292EE5aed5c17BDcc6EDF1696ba802351cf6"], ["420", "0xAcF5e964b76773166F69d6E53C1f7A9114a8E01D"] ] USDC = [ ["421613", "0x1a65113Fb92916EF0D3043D651b469b653763F16"], ["420", "0x6bCE0F297a204E1374860E0259EC31047a87B50F"] ]
In addition to the configuration file, one can specify command-line options which then override settings from the configuration file. Details on available options can be found in the beamer agent command reference.
3.2.1. Base Chain
Base chain can be defined via the command-line options or configuration file, or both. This chain is assumed to be the layer 1 chain used for L1 resolution.
Chains can be defined via the command-line options or configuration file, or both.
The configuration file section
[tokens] determines the set of ERC-20 tokens
that the agent will consider filling requests for. In other words, requests for
transferring tokens that are not in the set will be ignored.
A token definition looks like the following:
NAME = [ [CHAIN_ID_1, TOKEN_ADDRESS_1, ALLOWANCE], [CHAIN_ID_2, TOKEN_ADDRESS_2], ... ]
Each token is represented by a pair
[CHAIN_ID, TOKEN_ADDRESS]. All tokens
within the same list are considered equivalent and are part of the same class
named NAME. Only transfers between tokens of the same class are allowed.
A third value per token representation is optional, which defines
the allowance amount, the agent will approve to the fill manager contract.
The representation would look like
[CHAIN_ID, TOKEN_ADDRESS, ALLOWANCE].
Allowed values are:
Any value > 0, which defines the exact allowance given
-1, the agent will approve with type(uint256).max (maximum allowance)
If no value is given, the requested amount will be approved.
[tokens] TST = [ ["11", "0x2644292EE5aed5c17BDcc6EDF1696ba802351cf6", "-1"], ["22", "0xAcF5e964b76773166F69d6E53C1f7A9114a8E01D", "100000000000"] ] USDC = [ ["11", "0x1a65113Fb92916EF0D3043D651b469b653763F16"], ["22", "0x6bCE0F297a204E1374860E0259EC31047a87B50F"] ]
The above configuration says that the TST token contract on chain with ID
0x2644292EE5aed5c17BDcc6EDF1696ba802351cf6, while the TST token contract
on chain with ID
22 has address
3.3. Configuring the Health Check
The beamer health command is configured by a TOML configuration file
which is specified by the
An example configuration:
agent-address="" artifacts-dir="../deployments/artifacts/mainnet" abi-dir="../deployments/abis/mainnet" notification-system="telegram" [notification.rocketchat] url="" channel="" request-throttling-in-sec=60 [notification.telegram] token="" chat-id="" request-throttling-in-sec=0 [chains.arbitrum] rpc-url="" explorer="https://arbiscan.io/tx/" chain-id=42161 [chains.optimism] rpc-url="" explorer="https://optimistic.etherscan.io/tx/" chain-id=10 [tokens] # Each token is represented by a pair [chain-id, token-address]. # All tokens within the same list are considered equivalent and # transfers between them are allowed. USDC = [ ["10", "0x7F5c764cBc14f9669B88837ca1490cCa17c31607"], ["42161", "0xff970a61a04b1ca14834a43f5de4533ebddb5cc8"] ]
3.3.1. Notification system
Depending on the notification system you want to use, you will have to set
notification-system is set to
rocketchat provide the following keys:
notification.rocketchat.url: The RocketChat webhook url where the message should be posted
notification.rocketchat.channel: The RocketChat channel where the message should be posted
notification.rocketchat.request-trottling-in-sec: Some RocketChat servers have a limit on how many messages can be posted in a given time. This parameter allows you to configure the time between messages.
notification-system is set to
telegram provide the following keys:
notification.telegram.token: The Telegram bot token
notification.telegram.chat-id: The Telegram chat id
To get a Telegram bot token, you need to contact the @BotFather on Telegram and first create a
bot that will receive the notifications. When in chat with the BotFather, type
/newbot and follow the instructions. Once
you’ve created the bot, the BotFather will give you a token. Copy that token and add it to the
Now, start a chat with the bot you just created and send a message to it. After that forward that message to the @myidbot.
The myidbot will reply with your chat-id. Copy that id and add it to the
That’s it! Now you should have all the keys necessary to send notifications to Telegram.
3.4. Getting the Contract Deployment Information
During the Beamer contracts’ deployment process, a directory with deployment information is created. The directory typically looks like this:
deployments/ └── artifacts/ └── goerli/ ├── base.deployment.json ├── 5-ethereum.deployment.json ├── 420-optimism.deployment.json ├── 421613-arbitrum.deployment.json └── 84531-base.deployment.json
The above shows contract artifacts on Goerli.
<chain-id>-<chain-name>.deployment.json files contain information on specific chain that the
contracts have been deployed on, the contracts’ addresses, as well as the block
number at the time of deployment.
The rest of the files contain contract ABI information which is needed by the agent.
3.5. Starting an agent
3.5.1. Running an agent container
To run an agent container simply do:
docker run --name beamer_agent ghcr.io/beamer-bridge/beamer agent --account-path <path> \ --account-password <password> \ --base-chain <l1-rpc-url> \ --chain source=<source-l2-rpc-url> \ --chain target=<target-l2-rpc-url> \ --artifacts-dir <artifacts-dir> \ --abi-dir <abi-dir> \ --source-chain source \ --target-chain target
3.5.2. Running directly from source
First clone the Beamer repository:
git clone https://github.com/beamer-bridge/beamer.git
Make sure you have Python 3.10.x and Poetry installed.
Enter the virtual environment:
cd beamer poetry shell
While still inside the virtual environment, run:
beamer agent --account-path <path> \ --account-password <password> \ --base-chain <l1-rpc-url> \ --chain source=<source-l2-rpc-url> \ --chain target=<target-l2-rpc-url> \ --artifacts-dir <artifacts-dir> \ --abi-dir <abi-dir> \ --source-chain source \ --target-chain target
3.6. Stopping an agent
You may want to stop your agent when there is an update to the software.
To describe how to update an agent, it is worth to have a look on Beamer’s versioning scheme. As described in The branching strategy, each major version describes a different mainnet deployment thus a different set of contracts. Please note, that if you update your agent to a new major version, it will run on different contracts. Updating to a new major version requires different steps for you to safely transition to a new major contract version. A minor (e.g. 1.X.0 -> 1.Y.0) or a patch (e.g. 1.2.X -> 1.2.Y) version upgrade typically brings with it a set of fixes and it is recommended to switch to a newer version sooner rather than later. The difference between the minor and patch version updates is that the former may bring a change in command line options, configuration file settings or similar things where some user attention may be required, while the patch version update should be completely painless.
3.6.1. Update to a new agent release
Running your agent in a container, it is as easy as updating your image in the docker-compose.yml to the latest version. The repo https://github.com/beamer-bridge/run-your-own-agent is actively maintained and will provide you with the most up-to-date agent version. Alternatively you will find the latest version under https://github.com/beamer-bridge/beamer/releases.
3.6.2. Update to a new major version
When updating to a new major version (i.e. X.0.0 -> Y.0.0) and thus to a new contract deployment, it is recommended to setup a fresh agent instance following the guidelines from https://github.com/beamer-bridge/run-your-own-agent. Please keep the old agent running and leave it temporarily untouched. As soon as the contracts are paused, the old agent should run for at least another 24 hours to ensure withdrawal of outstanding funds. The old agent can then be shut down safely.
When there is a problem, you can get the logs via:
docker logs beamer_agent -f