Setting up the repository

Clone the repository:

git clone --recurse-submodules

If you already have a repository, make sure the submodules are up to date:

git submodule update


First make sure that the node dependencies are installed:

yarn install

Then, install python dependencies:

poetry install

Then enter the virtual environment:

poetry shell

Compile the contracts:

ape compile

Build the relayers:

make relayers

Start ganache:

ganache --wallet.totalAccounts 10 --chain.hardfork london --miner.blockGasLimit 12000000 \
        --wallet.mnemonic brownie --server.port 8545 --chain.chainId 1337

Create a JSON keyfile corresponding to one of the accounts pre-funded by ganache:

python scripts/ --key 0x3ff6c8dfd3ab60a14f2a2d4650387f71fe736b519d990073e650092faaa621fa \
                                   --password '' \

Deploy the contracts on the local ganache test chain:

python scripts/deployment/ --keystore-file 0x1CEE82EEd89Bd5Be5bf2507a92a755dcF1D8e8dc.json \
                                  --password '' \
                                  --output-dir deployments/ganache-local \
                                  --config-file scripts/deployment/ganache-local.json \

Generate a config file with token definition:

TOKEN_ADDR=$(jq -r '.L2."1337".MintableToken.address' < deployments/ganache-local/deployment.json)
echo -e "[tokens]\nTST = [[\"1337\", \"$TOKEN_ADDR\"]]"  > agent-ganache-local.conf

Mint some test tokens:

python scripts/ --keystore-file 0x1CEE82EEd89Bd5Be5bf2507a92a755dcF1D8e8dc.json \
                                 --password '' \
                                 --eth-rpc http://localhost:8545 \
                                 --deployment-dir deployments/ganache-local \

Whitelist the agent’s address:

python scripts/ --keystore-file 0x1CEE82EEd89Bd5Be5bf2507a92a755dcF1D8e8dc.json \
                                 --password '' \
                                 --eth-rpc http://localhost:8545 \
                                 --deployment-dir deployments/ganache-local \
                                 whitelist 0x1CEE82EEd89Bd5Be5bf2507a92a755dcF1D8e8dc

Start beamer-agent:

beamer agent --account-path 0x1CEE82EEd89Bd5Be5bf2507a92a755dcF1D8e8dc.json \
             --account-password '' \
             --config agent-ganache-local.conf \
             --chain l1=http://localhost:8545 \
             --source-chain=l1 \
             --target-chain=l1 \
             --deployment-dir deployments/ganache-local \
             --log-level debug

Submit a request:

python scripts/ --deployment-dir deployments/ganache-local \
                                 --keystore-file 0x1CEE82EEd89Bd5Be5bf2507a92a755dcF1D8e8dc.json \
                                 --password '' \
                                 --eth-rpc http://localhost:8545 \
                                 request \
                                 --amount 1 \
                                 --target-address 0x1CEE82EEd89Bd5Be5bf2507a92a755dcF1D8e8dc \
                                 --target-chain-id 1337 \
                                 --target-token-address $TOKEN_ADDR

Working with a local Optimism instance

To start a local Optimism instance, run:

sh ./docker/optimism/ up

This will start all the required containers. Note that it takes a while (~1 minute) for all the services to become ready. Next, deploy the Beamer contracts and start the end-to-end test:

sh ./docker/optimism/ deploy-beamer
sh ./docker/optimism/ e2e-test

To stop and remove all the containers, simply run:

sh ./docker/optimism/ down

To list Optimism contracts’ addresses, run:

sh ./docker/optimism/ addresses

Running the frontend


  • Node.js

  • yarn

First install the dependencies:

cd frontend
yarn install

Run the development server:

yarn dev

To configure the used deployment, make your changes to the frontend/.env.development file and rerun the development server.

Measuring gas costs

To measure gas costs, simply invoke the following command:

ape test --gas beamer/tests/contracts

A difference between two ape gas profiles can be shown by using the following command:

python scripts/ <path-to-profile1> <path-to-profile2>

Building documentation

To build Beamer documentation, make sure to have Sphinx and Graphviz installed. Documentation can be built by running:

make docs

and the resulting HTML will be available at docs/build/index.html.

Using live networks

Depending on the networks you intend to use, some or all of these environment variables should be set:


After setting the variables, it should be possible to connect to a specific network by running ape console –network <ecosystem>:<network>:<provider> (e.g. arbitrum:goerli:alchemy).