5. Reference Documentation

5.1. Cross-chain Message Relayer

This component is responsible for handling the cross-chain contract state updates.

It is mainly used by the Agent software when resolving requests as a result of a running challenge game or for sending fill invalidation messages (L1 resolutions). However, it can also be used manually by running the CLI commands. If you haven’t read about the role of L1 Resolution in Beamer, make sure you get familiar with this concept first.

Every request fill action creates a proof on the request destination chain. Since these proofs are created on a different chain than the chain where the requests originated from, we need a way to transport these proofs from one chain to another in order to be able to prove that a certain state is correct. This is where the cross-chain relayer comes into play.

The agent utilizes these proofs if and when needed. In normal operation, agent’s claims will not be challenged so the fill proofs are not needed, therefore the agent will not invoke the relayer. However, if a challenge game occurs, the agent has to make use of the proof to ensure it wins the game. Typically, that is done by invoking the relayer at an appropriate moment, i.e. when the proof becomes available for execution on Ethereum L1.

For instructions on how to setup, compile and run the relayer, make sure you take a look at the /relayer/README.md file.

5.1.1. Command Reference

The relayer CLI currently supports the following commands:

relay relays a fill proof or a fill invalidation message from chain A to chain B.
prove-op-message proves on L1 that a message exists on L2.

Used only for messages traveling from chains that are based on the Optimism Bedrock stack.

5.1.1.1. `relay`

The relay command takes care of relaying a message from one chain to another (end-to-end). In cases where a message needs to be relayed from an “Optimism Bedrock”-like chain, then one first needs to run the prove-op-message command, for the same message that needs to be relayed, before one can run the relay command.

Command-line option	Description
`--l1-rpc-url URL`	RPC URL to be used for communicating with the base chain.
`--l2-relay-to-rpc-url URL`	RPC URL to be used for communicating with the destination chain (chain where the proof is travelling to).
`--l2-relay-from-rpc-url URL`	RPC URL to be used for communicating with the source chain (chain where the proof is travelling from).
`--keystore-file PATH`	Path to the keystore file.
`--password PASSWORD`	Password of the keystore file.
`--l2-transaction-hash TX_HASH`	Transaction hash of the submitted message that needs to be relayed.
`--network-from PATH`	Path to a file with custom network configuration. This option is mainly used for development purposes.
`--network-to PATH`	Path to a file with custom network configuration. This option is mainly used for development purposes.

5.1.1.2. `prove-op-message`

The prove-op-message command is used only when a message needs to travel from “Optimism Bedrock”-like networks. On such networks, there is a need of proving the message up front before it is treated as a message that should be included in a batch and submitted to L1 (after the proof is finalized on L2). The finality period starts only after the message was proven on L2.

Command-line option	Description
`--l1-rpc-url URL`	RPC URL to be used for communicating with the base chain.
`--l2-rpc-url URL`	RPC URL to be used for communicating with the L2 chain.
`--keystore-file PATH`	Path to the keystore file.
`--password PASSWORD`	Password of the keystore file.
`--l2-transaction-hash TX_HASH`	Transaction hash of the submitted message that needs to be proven.
`--custom-network PATH`	Path to a file with custom L2 network configuration. This option is mainly used for development purposes.

5.2. beamer Command Reference

The Beamer software currently supports these commands:

beamer agent allows to run a Beamer agent.
beamer config read reads contract configuration from the chain.
beamer config write writes contract configuration to the chain.
beamer health analyzes the Beamer protocol and agent activity.
beamer check initiate-l1-invalidations issues L1 invalidations.
beamer check verify-l1-invalidations verifies L1 invalidations.
beamer check initiate-challenges issues challenges.
beamer check verify-challenges verifies that challenges are resolved correctly.

5.2.1. `beamer agent`

Command-line option	Description
`--account-path PATH`	Path to the account keyfile.
`--account-password PASSWORD`	The password needed to unlock the account.
`--artifacts-dir DIR`	The directory containing deployment artifact files.
`--abi-dir DIR`	The directory containing contract abi files.
`--fill-wait-time TIME`	Time in seconds to wait for a fill event before challenging a false claim. Default: `120`.
`--confirmation-blocks BLOCKS`	Number of confirmation blocks to consider the block ready for processing. Default: `0`.
`--unsafe-fill-time TIME`	Time in seconds before request expiry, during which the agent will consider it unsafe to fill and ignore the request. Default: `600`. For more info: Unsafe Fill Time
`--log-level LEVEL`	Logging level, one of `debug`, `info`, `warning`, `error`, `critical`. Default: `info`.
`--metrics-prometheus-port PORT`	Provide Prometheus metrics on the specified port.
`--source-chain NAME`	Name of the source chain. Deprecated and will be removed. No longer needed because the agent supports multiple chain pairs.
`--target-chain NAME`	Name of the target chain. Deprecated and will be removed. No longer needed because the agent supports multiple chain pairs.
`--chain NAME=URL`	Associate a JSON-RPC endpoint URL with chain NAME. May be given multiple times. Example: --chain foo=http://foo.bar:8545
`--poll-period`	Time in seconds which is waited before new events are fetched from the chains after the last fetch. If a value for a specific chain is provided in the config file, it takes precedence for this chain. Default: `5.0`.

5.2.2. `beamer config read`

beamer config read --rpc-file RPC-FILE --abi-dir DIR --artifact CHAIN_ID-CHAIN_NAME.deployment.json STATE_PATH

The command reads the latest contract configuration state from the chain and store it into STATE_PATH. If STATE_PATH already exists, it is used as the starting point to fetch contract events from. Otherwise, contracts events are fetched from the deployment block.

Command-line option	Description
`--abi-dir DIR`	The directory containing contract ABI files.
`--artifact CHAIN_ID-CHAIN_NAME.deployment.json`	Path to the deployment artifact.
`--rpc-file`	Path to the JSON file containing RPC information.

5.2.3. `beamer config write`

beamer config write --rpc-file RPC-FILE --abi-dir DIR --artifact CHAIN_ID-CHAIN_NAME.deployment.json CURRENT_STATE_PATH DESIRED_STATE_PATH

The command reads current contract configuration from CURRENT_STATE_PATH and the desired contract configuration from DESIRED_STATE_PATH and then issues appropriate transactions to the chain to make the contract configuration match the desired configuration.

Command-line option	Description
`--abi-dir DIR`	The directory containing contract ABI files.
`--artifact CHAIN_ID-CHAIN_NAME.deployment.json`	Path to the deployment artifact.
`--rpc-file`	Path to the JSON file containing RPC information.
`--keystore-file PATH`	Path to the keystore file.
`--password TEXT`	The password needed to unlock the keystore file.

5.2.4. `beamer health`

The health-check command scans the contracts for the emitted events and analyzes whether there is a missed fill, unclaimed transaction or a challenge game going on. In addition to this, if an agent-address is provided in the config file, the final notification will also include the liquidity on all chains for all the tokens specified inside the configuration file for the provided agent address. The command will notify the user by sending everything either to Telegram or RocketChat.

Command-line option	Description
`--config PATH`	Path to the config file with chains configuration. See Health-check configuration file for available options.
`--log-level LEVEL`	Logging level, one of `debug`, `info`, `warning`, `error`, `critical`. Default: `error`.

5.2.5. `beamer check initiate-l1-invalidations`

beamer check initiate-l1-invalidations [OPTIONS] PROOF_SOURCE PROOF_TARGET...

The command initiates L1 invalidations from PROOF_SOURCE to each PROOF_TARGET (there must be at least one proof target, but also multiple ones can be specified). PROOF_SOURCE and PROOF_TARGET are chain IDs. By default, one invalidation will be sent per (source, target) pair, however this may be changed via the --count option. If the output file (specified via the --output option) already contains invalidations for a particular (source, target) pair, the command will only send as many new invalidations for the same pair as is necessary to reach the specified invalidation count per pair. This also means that if the number of invalidations found for a given pair is equal or greater to the count, no new invalidations will be sent.

Command-line option	Description
`--abi-dir DIR`	The directory containing contract ABI files.
`--artifacts-dir DIR`	The directory containing deployment artifact files.
`--rpc-file`	Path to the JSON file containing RPC information.
`--keystore-file PATH`	Path to the keystore file.
`--password TEXT`	The password needed to unlock the keystore file.
`--output PATH`	Path to store the invalidation info at, which can be later used for verification.
`--count INTEGER`	Number of invalidations to create, per (PROOF_SOURCE, PROOF_TARGET) pair. Has to be greater or equal to 1. Default: 1.

5.2.6. `beamer check verify-l1-invalidations`

beamer check verify-l1-invalidations [OPTIONS] FILE

The command verifies L1 invalidations contained in FILE. In case of multiple invalidations for the same pair (proof_source, proof_target), if an invalidation is verified successfully, remaining invalidations for the same chain pair will be skipped as they are then not considered necessary. If a verification fails for any invalidation, for whatever reason, an error will be emitted and the process will continue with the next invalidation. The command will exit with a success code only if all chain pairs had at least one successful invalidation.

Command-line option	Description
`--abi-dir DIR`	The directory containing contract ABI files.
`--artifacts-dir DIR`	The directory containing deployment artifact files.
`--rpc-file`	Path to the JSON file containing RPC information.
`--keystore-file PATH`	Path to the keystore file.
`--password TEXT`	The password needed to unlock the keystore file.

5.2.7. `beamer check initiate-challenges`

beamer check initiate-challenges [OPTIONS] FILL_CHAIN REQUEST_CHAIN...

The command creates a transfer from each REQUEST_CHAIN to FILL_CHAIN and challenges agent’s claims on those transfers so that the agent is forced to prove its fills on L1. There must be at least one REQUEST_CHAIN, but also multiple ones can be specified.

If the output file (specified via the --output option) already contains challenges for a particular (source, target) pair, the command will perform only actions that are necessary to complete the set of challenges. For example, if transfer requests, as well as and challenge transactions have already been done for all chain pairs, no additional transactions will be made.

Command-line option	Description
`--abi-dir DIR`	The directory containing contract ABI files.
`--artifacts-dir DIR`	The directory containing deployment artifact files.
`--rpc-file`	Path to the JSON file containing RPC information.
`--keystore-file PATH`	Path to the keystore file.
`--password TEXT`	The password needed to unlock the keystore file.
`--output PATH`	Path to store the challenges info at, which can be later used for verification.
`--stake FLOAT`	Stake amount for each challenge, in ETH. Has to be greater or equal to 0.1. Default: 0.1.
`--token TEXT`	Symbol of the token to be used for challenges (e.g. USDC).

5.2.8. `beamer check verify-challenges`

beamer check verify-challenges [OPTIONS] FILE

The command verifies that each challenge stored in FILE was resolved correctly via L1.

Command-line option	Description
`--abi-dir DIR`	The directory containing contract ABI files.
`--artifacts-dir DIR`	The directory containing deployment artifact files.
`--rpc-file`	Path to the JSON file containing RPC information.

5.3. Configuration File Reference

5.3.1. Agent configuration file

Configuration section / key	Description
[account] path = PATH	Path to the account keyfile.
[account] password = PASSWORD	The password needed to unlock the account.
artifacts-dir = DIR	The directory containing deployment artifact files.
abi-dir = DIR	The directory containing contract abi files.
fill-wait-time = TIME	Time in seconds to wait for a fill event before challenging a false claim. Default: `120`.
confirmation-blocks = BLOCKS	Number of confirmation blocks to consider the block ready for processing. Default: `0`.
unsafe-fill-time = TIME	Time in seconds before request expiry, during which the agent will consider it unsafe to fill and ignore the request. Default: `600`. For more info: Unsafe Fill Time
log-level = LEVEL	Logging level, one of `debug`, `info`, `warning`, `error`, `critical`. Default: `info`.
[metrics] prometheus-port = PORT	Provide Prometheus metrics on the specified port.
source-chain = NAME	Name of the source chain. Deprecated and will be removed. No longer needed because the agent supports multiple chain pairs.
target-chain = NAME	Name of the target chain. Deprecated and will be removed. No longer needed because the agent supports multiple chain pairs.
[base-chain] rpc-url = URL	Associate a JSON-RPC endpoint URL with base chain.
[chains.NAME] rpc-url = URL	Associate a JSON-RPC endpoint URL with chain NAME. May be given multiple times. Example: [chains.foo] rpc-url = "http://foo.bar:8545"
poll-period = TIME	Time in seconds to wait between two consecutive RPC requests for new events. The value applies to all chains that don’t have the chain-specific poll period defined. Default: `5.0`.
[chains.NAME] poll-period = TIME	Time in seconds to wait between two consecutive RPC requests for new events. The value applies only to chain NAME, taking precedence over the global poll period.
min-source-balance = ETH	Minimum ETH balance on source chain to fill requests on target chain.. The value applies to all chains that don’t have the chain-specific min-source-balance defined. Default: `0.1`.
[chains.NAME] min-source-balance = ETH	Minimum ETH balance on chain NAME to fill requests originating from it. The value applies only to chain NAME, taking precedence over the global min-source-balance.

5.3.2. Health-check configuration file

Configuration section / key	Description
agent-address = ADDRESS	Address of the agent account.
artifacts-dir = PATH	The directory that stores deployment artifact files.
abi-dir = PATH	Path to the contract abi files directory.
notification-system = SYSTEM	The notification system to use, either `telegram` or `rocketchat`.
[notification.rocketchat] url = URL	URL of the RocketChat server where the notifications should be sent to.
[notification.rocketchat] channel = NAME	Name of the RocketChat channel where the notifications should be sent to.
[notification.telegram] token = TOKEN	Specifies the Telegram authentication token.
[notification.telegram] chat-id = ID	The ID of the chat where the notification should be sent to.
[notification.SYSTEM] request-throttling-in-sec = TIME	Throttles the notifications to the specified number of seconds.
[chains.NAME] rpc-url = URL	Associate a JSON-RPC endpoint URL with chain NAME. May be given multiple times. Example: [chains.foo] rpc-url = "http://foo.bar:8545"
[chains.NAME] explorer = URL	Specifies the transaction URL path of a block explorer for the chain NAME.
[chains.NAME] chain-id = CHAIN_ID	The chain id for chain NAME.
[tokens] NAME = [ [CHAIN_ID, TOKEN_ADDRESS], [CHAIN_ID, TOKEN_ADDRESS] ]	Specifies the token NAME. For each chain a pair [CHAIN_ID, TOKEN_ADDRESS] is added to the list.

5.4. Contracts API Reference

contract FillManager is Ownable, LpWhitelist

The fill manager.

This contract is responsible for keeping track of filled requests. In addition to allowing agents to (eventually) prove that they filled requests, it also allows anyone to invalidate a claim that a request was filled.

It is the only contract that agents need to interact with on the target chain.

event RequestFilled(bytes32 indexed requestId, bytes32 fillId, uint256 indexed sourceChainId, address indexed targetTokenAddress, address filler, uint256 amount): Emitted when a request has been filled.

See also

fillRequest

event FillInvalidated(bytes32 indexed requestId, bytes32 indexed fillId): Emitted when a fill has been invalidated.

See also

invalidateFill

IMessenger public immutable messenger

address public l1Resolver: The L1 Resolver contract to be used for L1 resolution.

mapping (bytes32requestID => bytes32fillId) public fills: Maps request IDs to fill IDs.

constructor(address _messenger)

Constructor.

Parameters:

_messenger – The messenger.

function setResolver(address _l1Resolver) public onlyOwner

Set the resolver’s address

Can only ever be set once. Before it is set, no fills or invalidations are possible

Parameters:

_l1Resolver – The L1 resolver address

function fillRequest(uint256 sourceChainId, address targetTokenAddress, address targetReceiverAddress, uint256 amount, uint96 nonce) external onlyAllowed(msg . sender) returns (bytes32)

Fill the specified request.

The caller must have approved at least amount tokens for FillManager with the ERC20 token contract at targetTokenAddress. The tokens will be immediately sent to targetReceiverAddress and a fill proof will be generated, which can later be used to trigger L1 resolution, if needed.

Parameters:

sourceChainId – The source chain ID.
targetTokenAddress – Address of the token contract on the target chain.
targetReceiverAddress – Recipient address on the target chain.
amount – Amount of tokens to transfer. Does not include fees.
nonce – The nonce used to create the request ID.

Return:

The fill ID.

function invalidateFill(uint256 sourceChainId, address targetTokenAddress, address targetReceiverAddress, uint256 amount, uint96 nonce, bytes32 fillId) external

Invalidate the specified fill.

In cases that a claim has been made on the source chain, but without a corresponding fill actually happening on the target chain, anyone can call this function to mark the fill as invalid. This is typically followed by a challenge game on the source chain, which the dishonest claimer is guaranteed to lose as soon as the information about the invalid fill (so called “non-fill proof”) is propagated to the source chain via L1 resolution.

Parameters:

sourceChainId – The source chain ID.
targetTokenAddress – Address of the token contract on the target chain.
targetReceiverAddress – Recipient address on the target chain.
amount – Amount of tokens to transfer. Does not include fees.
nonce – The nonce used to create the request ID.
fillId – The fill ID.

contract RequestManager is Ownable, LpWhitelist, RestrictedCalls, Pausable

The request manager.

This contract is responsible for keeping track of transfer requests, implementing the rules of the challenge game and holding deposited tokens until they are withdrawn. The information passed by L1 resolution will be stored with the respective requests.

It is the only contract that agents need to interact with on the source chain. .. note:

The functions resolveRequest and invalidateFill can only be called by
the :sol:contract:`Resolver` contract, via a chain-dependent messenger contract.

event RequestCreated(bytes32 indexed requestId, uint256 targetChainId, address sourceTokenAddress, address targetTokenAddress, address indexed sourceAddress, address targetAddress, uint256 amount, uint96 nonce, uint32 validUntil, uint256 lpFee, uint256 protocolFee): Emitted when a new request has been created.

See also

createRequest

event DepositWithdrawn(bytes32 requestId, address receiver)

Emitted when the token deposit for request requestId has been transferred to the receiver.

This can happen in two cases:

the request expired and the request submitter called withdrawExpiredRequest

a claim related to the request has been resolved successfully in favor of the claimer

See also

withdraw

event FeesUpdated(uint32 minFeePPM, uint32 lpFeePPM, uint32 protocolFeePPM): Emitted when fees are updated.

See also

updateFees

event TokenUpdated(address indexed tokenAddress, uint256 transferLimit, uint256 ethInToken): Emitted when token object of a token address is updated.

See also

updateToken

event ChainUpdated(uint256 indexed chainId, uint256 finalityPeriod, uint256 transferCost, uint256 targetWeightPPM): Emitted when chain object of a chain id is updated.

See also

updateChain

event RequestResolved(bytes32 requestId, address filler, bytes32 fillId): Emitted when a request has been resolved via L1 resolution.

See also

resolveRequest

event FillInvalidatedResolved(bytes32 requestId, bytes32 fillId): Emitted when an invalidated fill has been resolved.

See also

invalidateFill

uint96 public immutable claimStake: The minimum amount of source chain’s native token that the claimer needs to provide when making a claim, as well in each round of the challenge game.

uint256 public immutable claimRequestExtension: The additional time given to claim a request. This value is added to the validity period of a request.

uint256 public immutable claimPeriod: The period for which the claim is valid.

uint256 public immutable challengePeriodExtension

The period by which the termination time of a claim is extended after each round of the challenge game. This period should allow enough time for the other parties to counter-challenge.

Note

The claim’s termination time is extended only if it is less than the extension time.

Note that in the first challenge round, i.e. the round initiated by the first challenger, the termination time is extended additionally by the finality period of the target chain. This is done to allow for L1 resolution.

uint32 public minFeePPM: PPM to determine the minLpFee profit for liquidity providers.

uint32 public lpFeePPM: PPM from transfer amount to determine the LP’s fee

uint32 public protocolFeePPM: PPM from transfer amount to determine the protocol’s fee

uint256 public constant MIN_VALIDITY_PERIOD: The minimum validity period of a request.

uint256 public constant MAX_VALIDITY_PERIOD: The maximum validity period of a request.

uint96 public constant CLAIM_ID_WITHDRAWN_EXPIRED: withdrawClaimId is set to this value when an expired request gets withdrawn by the sender

uint96 public currentNonce: A counter used to generate request and claim IDs. The variable holds the most recently used nonce and must be incremented to get the next nonce

mapping (uint256chainId => Chain) public chains: Maps target rollup chain IDs to chain information.

mapping (bytes32requestId => Request) public requests: Maps request IDs to requests.

mapping (uint96claimId => Claim) public claims: Maps claim IDs to claims.

mapping (addresstokenAddress => Token) public tokens: Maps ERC20 token address to tokens

function minLpFee(uint256 targetChainId, address tokenAddress) public view returns (uint256): Compute the minimum liquidity provider fee that needs to be paid for a token transfer.

function lpFee(uint256 targetChainId, address tokenAddress, uint256 amount) public view returns (uint256): Compute the liquidity provider fee that needs to be paid for a given transfer amount.

function protocolFee(uint256 amount) public view returns (uint256): Compute the protocol fee that needs to be paid for a given transfer amount.

function totalFee(uint256 targetChainId, address tokenAddress, uint256 amount) public view returns (uint256): Compute the total fee that needs to be paid for a given transfer amount. The total fee is the sum of the liquidity provider fee and the protocol fee.

function transferableAmount(uint256 targetChainId, address tokenAddress, uint256 amount) public view returns (uint256)

Return the transferable amount excluding fees.

It takes the given amount and calculates the actual transferable amount without fees based on the token address and its current fees.

Parameters:

targetChainId – ID of the target chain.
tokenAddress – Address of the token contract on the source chain.
amount – Amount of tokens to transfer including fees.

Return:

transferable amount excluding fees.

modifier validRequestId(bytes32 requestId): Check whether a given request ID is valid.

modifier validClaimId(uint96 claimId): Check whether a given claim ID is valid.

constructor(uint96 _claimStake, uint256 _claimRequestExtension, uint256 _claimPeriod, uint256 _challengePeriodExtension)

Constructor.

Parameters:

_claimStake – Claim stake amount.
_claimRequestExtension – Extension to claim a request after validity period ends.
_claimPeriod – Claim period, in seconds.
_challengePeriodExtension – Challenge period extension, in seconds.

function createRequest(uint256 targetChainId, address sourceTokenAddress, address targetTokenAddress, address targetAddress, uint256 amount, uint256 validityPeriod) external whenNotPaused returns (bytes32)

Create a new transfer request.

Parameters:

targetChainId – ID of the target chain.
sourceTokenAddress – Address of the token contract on the source chain.
targetTokenAddress – Address of the token contract on the target chain.
targetAddress – Recipient address on the target chain.
amount – Amount of tokens to transfer. Does not include fees.
validityPeriod – The number of seconds the request is to be considered valid. Once its validity period has elapsed, the request cannot be claimed anymore and will eventually expire, allowing the request submitter to withdraw the deposited tokens if there are no active claims.

Return:

ID of the newly created request.

function withdrawExpiredRequest(bytes32 requestId) external validRequestId(requestId)

Withdraw funds deposited with an expired request.

No claims must be active for the request.

Parameters:

requestId – ID of the expired request.

function claimRequest(bytes32 requestId, bytes32 fillId) external payable validRequestId(requestId) onlyAllowed(msg . sender) returns (uint96)

Claim that a request was filled by the caller.

The request must still be valid at call time. The caller must provide the claimStake amount of source rollup’s native token.

Parameters:

requestId – ID of the request.
fillId – The fill ID.

Return:

The claim ID.

function claimRequest(address claimer, bytes32 requestId, bytes32 fillId) public payable validRequestId(requestId) onlyAllowed(claimer) returns (uint96)

Claim that a request was filled.

The request must still be valid at call time. The caller must provide the claimStake amount of source rollup’s native token. Only the claimer may get the stake back later.

Parameters:

claimer – Address of the claimer.
requestId – ID of the request.
fillId – The fill ID.

Return:

The claim ID.

function challengeClaim(uint96 claimId) external payable validClaimId(claimId)

Challenge an existing claim.

The claim must still be valid at call time. This function implements one round of the challenge game. The original claimer is allowed to call this function only after someone else made a challenge, i.e. every second round. However, once the original claimer counter-challenges, anyone can join the game and make another challenge.

The caller must provide enough native tokens as their stake. For the original claimer, the minimum stake is challengerStakeTotal - claimerStake + claimStake.

For challengers, the minimum stake is claimerStake - challengerStakeTotal + 1.

An example (time flows downwards, claimStake = 10):

claimRequest() by Max [stakes 10]
challengeClaim() by Alice [stakes 11]
challengeClaim() by Max [stakes 11]
challengeClaim() by Bob [stakes 16]

In this example, if Max didn’t want to lose the challenge game to Alice and Bob, he would have to challenge with a stake of at least 16.

Parameters:

claimId – The claim ID.

function withdraw(uint96 claimId) external validClaimId(claimId) returns (address)

Withdraw the deposit that the request submitter left with the contract, as well as the staked native tokens associated with the claim.

In case the caller of this function is a challenger that won the game, they will only get their staked native tokens plus the reward in the form of full (sole challenger) or partial (multiple challengers) amount of native tokens staked by the dishonest claimer.

Parameters:

claimId – The claim ID.

Return:

The claim stakes receiver.

function withdraw(address participant, uint96 claimId) public validClaimId(claimId) returns (address)

Withdraw the deposit that the request submitter left with the contract, as well as the staked native tokens associated with the claim.

This function is called on behalf of a participant. Only a participant may receive the funds if he is the winner of the challenge or the claim is valid.

Parameters:

claimId – The claim ID.
participant – The participant.

Return:

The claim stakes receiver.

function isWithdrawn(bytes32 requestId) public view validRequestId(requestId) returns (bool)

Returns whether a request’s deposit was withdrawn or not

This can be true in two cases: 1. The deposit was withdrawn after the request was claimed and filled. 2. The submitter withdrew the deposit after the request’s expiry. .. seealso:: withdraw .. seealso:: withdrawExpiredRequest

Parameters:

requestId – The request ID

Return:

Whether the deposit corresponding to the given request ID was withdrawn

function withdrawProtocolFees(address tokenAddress, address recipient) external onlyOwner

Withdraw protocol fees collected by the contract.

Protocol fees are paid in token transferred.

Note

This function can only be called by the contract owner.

Parameters:

tokenAddress – The address of the token contract.
recipient – The address the fees should be sent to.

function updateFees(uint32 _minFeePPM, uint32 _lpFeePPM, uint32 _protocolFeePPM) external onlyOwner

Update fees

Note

This function can only be called by the contract owner.

Parameters:

_minFeePPM – Margin which is going to be applied to the minLpFee
_lpFeePPM – LP percentage fee applied on transfer amount denominated in parts per million
_protocolFeePPM – Protocol fee applied on transfer amount denominated in parts per million

function updateToken(address tokenAddress, uint256 transferLimit, uint256 ethInToken) external onlyOwner

function updateChain(uint256 chainId, uint256 finalityPeriod, uint256 transferCost, uint256 targetWeightPPM) external onlyOwner

Update chain information for a given chain ID.

Note

This function can only be called by the contract owner.

Parameters:

chainId – The chain ID of the chain.
finalityPeriod – The finality period of the chain in seconds.
transferCost – The transfer cost (fill, claim, withdraw) on the chain in WEI.
targetWeightPPM – The share of the target chain costs (fill) in parts per million.

function isInvalidFill(bytes32 requestId, bytes32 fillId) public view returns (bool)

Returns whether a fill is invalidated or not

Calling invalidateFill() will set this boolean to true, marking that the fillId for the corresponding requestId was invalidated. Calling resolveRequest will validate it again, setting request.invalidatedFills[fillId] to false. .. seealso:: invalidateFill .. seealso:: resolveRequest

Parameters:

requestId – The request ID
fillId – The fill ID

Return:

Whether the fill ID is invalid for the given request ID

function resolveRequest(bytes32 requestId, bytes32 fillId, uint256 resolutionChainId, address filler) external restricted(resolutionChainId)

Mark the request identified by requestId as filled by filler.

Note

This function is a restricted call function. Only callable by the added caller.

Parameters:

requestId – The request ID.
fillId – The fill ID.
resolutionChainId – The resolution (L1) chain ID.
filler – The address that filled the request.

function invalidateFill(bytes32 requestId, bytes32 fillId, uint256 resolutionChainId) external restricted(resolutionChainId)

Mark the fill identified by requestId and fillId as invalid.

Note

This function is a restricted call function. Only callable by the added caller.

Parameters:

requestId – The request ID.
fillId – The fill ID.
resolutionChainId – The resolution (L1) chain ID.

function pause() external onlyOwner

Pauses the contract.

Once the contract is paused, it cannot be used to create new requests anymore. Withdrawing deposited funds and claim stakes still works, though.

Note

This function can only be called when the contract is not paused.

Note

This function can only be called by the contract owner.

function unpause() external onlyOwner

Unpauses the contract.

Once the contract is unpaused, it can be used normally.

Note

This function can only be called when the contract is paused.

Note

This function can only be called by the contract owner.

contract Resolver is Ownable, RestrictedCalls

The resolver.

This contract resides on the L1 chain and is tasked with receiving the fill or non-fill proofs from the target L2 chain and forwarding them to the RequestManager on the source L2 chain.

event Resolution(uint256 sourceChainId, uint256 fillChainId, bytes32 requestId, address filler, bytes32 fillId): Emitted when a fill or a non-fill proof is received and sent to the request manager.

Note

In case of a non-fill proof, the filler will be zero.

mapping (uint256sourceChainId => SourceChainInfo) public sourceChainInfos: Maps source chain IDs to source chain infos.

function resolve(bytes32 requestId, bytes32 fillId, uint256 fillChainId, uint256 sourceChainId, address filler) external restricted(fillChainId)

Resolve the specified request.

This marks the request identified by requestId as filled by filler. If the filler is zero, the fill will be marked invalid.

Information about the fill will be sent to the source chain’s RequestManager, using the messenger responsible for the source chain.

Note

This function is callable only by the native L1 messenger contract, which simply delivers the message sent from the target chain by the Beamer’s L2 messenger contract.

Parameters:

requestId – The request ID.
fillId – The fill ID.
fillChainId – The fill (target) chain ID.
sourceChainId – The source chain ID.
filler – The address that filled the request, or zero to invalidate the fill.

function addRequestManager(uint256 chainId, address requestManager, address messenger) external onlyOwner

Add a request manager.

In order to be able to send messages to the RequestManager, the resolver contract needs to know the address of the request manager on the source chain, as well as the address of the messenger contract responsible for transferring messages to the L2 chain.

Note

This function can only be called by the contract owner.

Parameters:

chainId – The source L2 chain ID.
requestManager – The request manager.
messenger – The messenger contract responsible for chain chainId. Must implement IMessenger.

5.4.1. Helper contracts

contract RestrictedCalls is Ownable

A helper contract that provides a way to restrict callers of restricted functions to a single address. This allows for a trusted call chain, as described in contracts’ architecture.

mapping (uint256callerChainId => address[2]) public callers

Maps caller chain IDs to tuples [caller, messenger].

For same-chain calls, the messenger address is 0x0.

function addCaller(address caller) external onlyOwner

Allow calls from an address on the same chain.

Parameters:

caller – The caller.

function addCaller(uint256 callerChainId, address caller, address messenger) external onlyOwner

Allow calls from an address on another chain.

Parameters:

callerChainId – The caller’s chain ID.
caller – The caller.
messenger – The messenger.

modifier restricted(uint256 callerChainId)

Mark the function as restricted.

Calls to the restricted function can only come from an address that was previously added by a call to addCaller.

Example usage:

restricted(block.chainid)   // expecting calls from the same chain
restricted(otherChainId)    // expecting calls from another chain

5.4.2. Interfaces

interface IMessenger

The messenger interface.

Implementations of this interface are expected to transport messages across the L1 <-> L2 boundary. For instance, if an implementation is deployed on L1, the sendMessage would send a message to a L2 chain, as determined by the implementation. In order to do this, a messenger implementation may use a native messenger contract. In such cases, nativeMessenger must return the address of the native messenger contract.

function sendMessage(address target, bytes calldata message) external

Send a message across the L1 <-> L2 boundary.

Parameters:

target – The message recipient.
message – The message.

function callAllowed(address caller, address courier) external view returns (bool)

Return whether the call is allowed or not.

Parameters:

caller – The caller.
courier – The contract that is trying to deliver the message.

5. Reference Documentation

5.1. Cross-chain Message Relayer

5.1.1. Command Reference

5.1.1.1. relay

5.1.1.2. prove-op-message

5.2. beamer Command Reference

5.2.1. beamer agent

5.2.2. beamer config read

5.2.3. beamer config write

5.2.4. beamer health

5.2.5. beamer check initiate-l1-invalidations

5.2.6. beamer check verify-l1-invalidations

5.2.7. beamer check initiate-challenges

5.2.8. beamer check verify-challenges

5.3. Configuration File Reference

5.3.1. Agent configuration file

5.3.2. Health-check configuration file

5.4. Contracts API Reference

5.4.1. Helper contracts

5.4.2. Interfaces

5.1.1.1. `relay`

5.1.1.2. `prove-op-message`

5.2.1. `beamer agent`

5.2.2. `beamer config read`

5.2.3. `beamer config write`

5.2.4. `beamer health`

5.2.5. `beamer check initiate-l1-invalidations`

5.2.6. `beamer check verify-l1-invalidations`

5.2.7. `beamer check initiate-challenges`

5.2.8. `beamer check verify-challenges`