FastBridge Contracts

Contributing

Please make sure foundry is installed:

curl -L https://foundry.paradigm.xyz | bash
foundryup

Then, run the following to make sure dependencies are installed

git submodule update --init --recursive

Testing

To run the tests, run the following:

forge test

Contents

• IAdmin
• IFastBridge
• IFastBridgeRecipient
• IFastBridgeV2
• IFastBridgeV2Errors
• IMulticallTarget

IAdmin

Git Source

Functions

setProtocolFeeRate

function setProtocolFeeRate(uint256 newFeeRate) external;

sweepProtocolFees

function sweepProtocolFees(address token, address recipient) external;

setChainGasAmount

function setChainGasAmount(uint256 newChainGasAmount) external;

Events

FeeRateUpdated

event FeeRateUpdated(uint256 oldFeeRate, uint256 newFeeRate);

FeesSwept

event FeesSwept(address token, address recipient, uint256 amount);

ChainGasAmountUpdated

event ChainGasAmountUpdated(uint256 oldChainGasAmount, uint256 newChainGasAmount);

IFastBridge

Git Source

Functions

bridge

Initiates bridge on origin chain to be relayed by off-chain relayer

function bridge(BridgeParams memory params) external payable;

Parameters

relay

Relays destination side of bridge transaction by off-chain relayer

function relay(bytes memory request) external payable;

Parameters

prove

Provides proof on origin side that relayer provided funds on destination side of bridge transaction

function prove(bytes memory request, bytes32 destTxHash) external;

Parameters

claim

Completes bridge transaction on origin chain by claiming originally deposited capital

function claim(bytes memory request, address to) external;

Parameters

dispute

Disputes an outstanding proof in case relayer provided dest chain tx is invalid

function dispute(bytes32 transactionId) external;

Parameters

refund

Refunds an outstanding bridge transaction in case optimistic bridging failed

function refund(bytes memory request) external;

Parameters

getBridgeTransaction

Decodes bridge request into a bridge transaction

function getBridgeTransaction(bytes memory request) external pure returns (BridgeTransaction memory);

Parameters

canClaim

Checks if the dispute period has passed so bridge deposit can be claimed

function canClaim(bytes32 transactionId, address relayer) external view returns (bool);

Parameters

Events

BridgeRequested

event BridgeRequested(
    bytes32 indexed transactionId,
    address indexed sender,
    bytes request,
    uint32 destChainId,
    address originToken,
    address destToken,
    uint256 originAmount,
    uint256 destAmount,
    bool sendChainGas
);

BridgeRelayed

event BridgeRelayed(
    bytes32 indexed transactionId,
    address indexed relayer,
    address indexed to,
    uint32 originChainId,
    address originToken,
    address destToken,
    uint256 originAmount,
    uint256 destAmount,
    uint256 chainGasAmount
);

BridgeProofProvided

event BridgeProofProvided(bytes32 indexed transactionId, address indexed relayer, bytes32 transactionHash);

BridgeProofDisputed

event BridgeProofDisputed(bytes32 indexed transactionId, address indexed relayer);

BridgeDepositClaimed

event BridgeDepositClaimed(
    bytes32 indexed transactionId, address indexed relayer, address indexed to, address token, uint256 amount
);

BridgeDepositRefunded

event BridgeDepositRefunded(bytes32 indexed transactionId, address indexed to, address token, uint256 amount);

Structs

BridgeTransaction

struct BridgeTransaction {
    uint32 originChainId;
    uint32 destChainId;
    address originSender;
    address destRecipient;
    address originToken;
    address destToken;
    uint256 originAmount;
    uint256 destAmount;
    uint256 originFeeAmount;
    bool sendChainGas;
    uint256 deadline;
    uint256 nonce;
}

BridgeProof

struct BridgeProof {
    uint96 timestamp;
    address relayer;
}

BridgeParams

struct BridgeParams {
    uint32 dstChainId;
    address sender;
    address to;
    address originToken;
    address destToken;
    uint256 originAmount;
    uint256 destAmount;
    bool sendChainGas;
    uint256 deadline;
}

IFastBridgeRecipient

Git Source

Functions

fastBridgeTransferReceived

function fastBridgeTransferReceived(
    address token,
    uint256 amount,
    bytes memory callParams
)
    external
    payable
    returns (bytes4);

IFastBridgeV2

Git Source

Inherits: IFastBridge

Functions

bridge

Initiates bridge on origin chain to be relayed by off-chain relayer, with the ability to provide temporary exclusivity fill rights for the quote relayer.

function bridge(BridgeParams memory params, BridgeParamsV2 memory paramsV2) external payable;

Parameters

relay

Relays destination side of bridge transaction by off-chain relayer

function relay(bytes memory request, address relayer) external payable;

Parameters

prove

Provides proof on origin side that relayer provided funds on destination side of bridge transaction

function prove(bytes32 transactionId, bytes32 destTxHash, address relayer) external;

Parameters

claim

Completes bridge transaction on origin chain by claiming originally deposited capital.

Can only send funds to the relayer address on the proof.

function claim(bytes memory request) external;

Parameters

bridgeRelays

Checks if a transaction has been relayed

function bridgeRelays(bytes32 transactionId) external view returns (bool);

Parameters

Returns

bridgeStatuses

Returns the status of a bridge transaction

function bridgeStatuses(bytes32 transactionId) external view returns (BridgeStatus);

Parameters

Returns

bridgeProofs

Returns the timestamp and relayer of a bridge proof

function bridgeProofs(bytes32 transactionId) external view returns (uint96 timestamp, address relayer);

Parameters

Returns

getBridgeTransactionV2

Decodes bridge request into a bridge transaction V2 struct used by FastBridgeV2

function getBridgeTransactionV2(bytes memory request) external view returns (BridgeTransactionV2 memory);

Parameters

Events

BridgeQuoteDetails

event BridgeQuoteDetails(bytes32 indexed transactionId, bytes quoteId);

Structs

BridgeTxDetails

struct BridgeTxDetails {
    BridgeStatus status;
    uint40 proofBlockTimestamp;
    uint48 proofBlockNumber;
    address proofRelayer;
}

BridgeRelay

struct BridgeRelay {
    uint48 blockNumber;
    uint48 blockTimestamp;
    address relayer;
}

BridgeParamsV2

New params introduced in the FastBridgeV2. We are passing fields from the older BridgeParams struct outside of this struct for backwards compatibility. Note: quoteRelayer and quoteExclusivitySeconds are either both zero (indicating no exclusivity) or both non-zero (indicating exclusivity for the given period).

struct BridgeParamsV2 {
    address quoteRelayer;
    int256 quoteExclusivitySeconds;
    bytes quoteId;
    bytes callParams;
}

BridgeTransactionV2

Updated bridge transaction struct to include parameters introduced in FastBridgeV2. Note: only exclusivityRelayer can fill such a transaction until exclusivityEndTime. TODO: consider changing the encoding scheme to prevent spending extra gas on decoding.

struct BridgeTransactionV2 {
    uint32 originChainId;
    uint32 destChainId;
    address originSender;
    address destRecipient;
    address originToken;
    address destToken;
    uint256 originAmount;
    uint256 destAmount;
    uint256 originFeeAmount;
    bool sendChainGas;
    uint256 deadline;
    uint256 nonce;
    address exclusivityRelayer;
    uint256 exclusivityEndTime;
    bytes callParams;
}

Enums

BridgeStatus

enum BridgeStatus {
    NULL,
    REQUESTED,
    RELAYER_PROVED,
    RELAYER_CLAIMED,
    REFUNDED
}

IFastBridgeV2Errors

Git Source

Errors

AmountIncorrect

error AmountIncorrect();

CallParamsLengthAboveMax

error CallParamsLengthAboveMax();

ChainIncorrect

error ChainIncorrect();

ExclusivityParamsIncorrect

error ExclusivityParamsIncorrect();

MsgValueIncorrect

error MsgValueIncorrect();

SenderIncorrect

error SenderIncorrect();

StatusIncorrect

error StatusIncorrect();

ZeroAddress

error ZeroAddress();

RecipientIncorrectReturnValue

error RecipientIncorrectReturnValue();

RecipientNoReturnValue

error RecipientNoReturnValue();

DeadlineExceeded

error DeadlineExceeded();

DeadlineNotExceeded

error DeadlineNotExceeded();

DeadlineTooShort

error DeadlineTooShort();

DisputePeriodNotPassed

error DisputePeriodNotPassed();

DisputePeriodPassed

error DisputePeriodPassed();

ExclusivityPeriodNotPassed

error ExclusivityPeriodNotPassed();

TransactionRelayed

error TransactionRelayed();

IMulticallTarget

Git Source

Interface for a contract that can be called multiple times by the same caller. Inspired by MulticallV3: https://github.com/mds1/multicall/blob/master/src/Multicall3.sol

Functions

multicallNoResults

function multicallNoResults(bytes[] calldata data, bool ignoreReverts) external;

multicallWithResults

function multicallWithResults(bytes[] calldata data, bool ignoreReverts) external returns (Result[] memory results);

Structs

Result

struct Result {
    bool success;
    bytes returnData;
}

Contents

• DeadlineExceeded
• DeadlineNotExceeded
• DeadlineTooShort
• InsufficientOutputAmount
• MsgValueIncorrect
• PoolNotFound
• TokenAddressMismatch
• TokenNotContract
• TokenNotETH
• TokensIdentical
• ChainIncorrect
• AmountIncorrect
• ZeroAddress
• DisputePeriodNotPassed
• DisputePeriodPassed
• SenderIncorrect
• StatusIncorrect
• TransactionIdIncorrect
• TransactionRelayed
• UniversalTokenLib

DeadlineExceeded

Git Source

error DeadlineExceeded();

DeadlineNotExceeded

Git Source

error DeadlineNotExceeded();

DeadlineTooShort

Git Source

error DeadlineTooShort();

InsufficientOutputAmount

Git Source

error InsufficientOutputAmount();

MsgValueIncorrect

Git Source

error MsgValueIncorrect();

PoolNotFound

Git Source

error PoolNotFound();

TokenAddressMismatch

Git Source

error TokenAddressMismatch();

TokenNotContract

Git Source

error TokenNotContract();

TokenNotETH

Git Source

error TokenNotETH();

TokensIdentical

Git Source

error TokensIdentical();

ChainIncorrect

Git Source

error ChainIncorrect();

AmountIncorrect

Git Source

error AmountIncorrect();

ZeroAddress

Git Source

error ZeroAddress();

DisputePeriodNotPassed

Git Source

error DisputePeriodNotPassed();

DisputePeriodPassed

Git Source

error DisputePeriodPassed();

SenderIncorrect

Git Source

error SenderIncorrect();

StatusIncorrect

Git Source

error StatusIncorrect();

TransactionIdIncorrect

Git Source

error TransactionIdIncorrect();

TransactionRelayed

Git Source

error TransactionRelayed();

UniversalTokenLib

Git Source

State Variables

ETH_ADDRESS

address internal constant ETH_ADDRESS = 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE;

Functions

universalTransfer

Transfers tokens to the given account. Reverts if transfer is not successful.

This might trigger fallback, if ETH is transferred to the contract. Make sure this can not lead to reentrancy attacks.

function universalTransfer(address token, address to, uint256 value) internal;

universalApproveInfinity

Issues an infinite allowance to the spender, if the current allowance is insufficient to spend the given amount.

Note: this can potentially lead to executing code in to.

function universalApproveInfinity(address token, address spender, uint256 amountToSpend) internal;

universalBalanceOf

Returns the balance of the given token (or native ETH) for the given account.

function universalBalanceOf(address token, address account) internal view returns (uint256);

assertIsContract

Checks that token is a contract and not ETH_ADDRESS.

function assertIsContract(address token) internal view;

Contents

• MulticallTarget

MulticallTarget

Git Source

Inherits: IMulticallTarget

Template for a contract that supports batched calls (preserving the msg.sender). Only calls with zero msg.value could be batched.

Functions

multicallNoResults

Perform a batched call to this contract, preserving the msg.sender. The return data from each call is discarded.

The method is non-payable, so only calls with msg.value == 0 could be batched. It's possible to ignore the reverts from the calls by setting the ignoreReverts flag. Otherwise, the whole batch call will be reverted with the original revert reason.

function multicallNoResults(bytes[] calldata data, bool ignoreReverts) external;

Parameters

multicallWithResults

Perform a batched call to this contract, preserving the msg.sender. The return data from each call is preserved.

The method is non-payable, so only calls with msg.value == 0 could be batched. It's possible to ignore the reverts from the calls by setting the ignoreReverts flag. Otherwise, the whole batch call will be reverted with the original revert reason.

function multicallWithResults(bytes[] calldata data, bool ignoreReverts) external returns (Result[] memory results);

Parameters

Returns

_bubbleRevert

Bubbles the revert message from the underlying call. Note: preserves the same custom error or revert string, if one was used. Source: https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v5.0.2/contracts/utils/Address.sol#L143-L158

function _bubbleRevert(bytes memory returnData) internal pure;

Errors

MulticallTarget__UndeterminedRevert

error MulticallTarget__UndeterminedRevert();

Admin

Git Source

Inherits: IAdmin, AccessControlEnumerable

State Variables

RELAYER_ROLE

bytes32 public constant RELAYER_ROLE = keccak256("RELAYER_ROLE");

REFUNDER_ROLE

bytes32 public constant REFUNDER_ROLE = keccak256("REFUNDER_ROLE");

GUARD_ROLE

bytes32 public constant GUARD_ROLE = keccak256("GUARD_ROLE");

GOVERNOR_ROLE

bytes32 public constant GOVERNOR_ROLE = keccak256("GOVERNOR_ROLE");

FEE_BPS

uint256 public constant FEE_BPS = 1e6;

FEE_RATE_MAX

uint256 public constant FEE_RATE_MAX = 0.01e6;

protocolFeeRate

Protocol fee rate taken on origin amount deposited in origin chain

uint256 public protocolFeeRate;

protocolFees

Protocol fee amounts accumulated

mapping(address => uint256) public protocolFees;

chainGasAmount

Chain gas amount to forward as rebate if requested

uint256 public chainGasAmount;

Functions

constructor

constructor(address _owner);

setProtocolFeeRate

function setProtocolFeeRate(uint256 newFeeRate) external onlyRole(GOVERNOR_ROLE);

sweepProtocolFees

function sweepProtocolFees(address token, address recipient) external onlyRole(GOVERNOR_ROLE);

setChainGasAmount

function setChainGasAmount(uint256 newChainGasAmount) external onlyRole(GOVERNOR_ROLE);

FastBridge

Git Source

Inherits: IFastBridge, Admin

State Variables

DISPUTE_PERIOD

Dispute period for relayed transactions

uint256 public constant DISPUTE_PERIOD = 30 minutes;

REFUND_DELAY

Delay for a transaction after which it could be permisionlessly refunded

uint256 public constant REFUND_DELAY = 7 days;

MIN_DEADLINE_PERIOD

Minimum deadline period to relay a requested bridge transaction

uint256 public constant MIN_DEADLINE_PERIOD = 30 minutes;

bridgeStatuses

Status of the bridge tx on origin chain

mapping(bytes32 => BridgeStatus) public bridgeStatuses;

bridgeProofs

Proof of relayed bridge tx on origin chain

mapping(bytes32 => BridgeProof) public bridgeProofs;

bridgeRelays

Whether bridge has been relayed on destination chain

mapping(bytes32 => bool) public bridgeRelays;

nonce

to prevent replays

uint256 public nonce;

deployBlock

uint256 public immutable deployBlock;

Functions

constructor

constructor(address _owner) Admin(_owner);

_pullToken

Pulls a requested token from the user to the requested recipient.

Be careful of re-entrancy issues when msg.value > 0 and recipient != address(this)

function _pullToken(address recipient, address token, uint256 amount) internal returns (uint256 amountPulled);

getBridgeTransaction

Decodes bridge request into a bridge transaction

function getBridgeTransaction(bytes memory request) public pure returns (BridgeTransaction memory);

Parameters

bridge

Initiates bridge on origin chain to be relayed by off-chain relayer

function bridge(BridgeParams memory params) external payable;

Parameters

relay

Relays destination side of bridge transaction by off-chain relayer

function relay(bytes memory request) external payable onlyRole(RELAYER_ROLE);

Parameters

prove

Provides proof on origin side that relayer provided funds on destination side of bridge transaction

function prove(bytes memory request, bytes32 destTxHash) external onlyRole(RELAYER_ROLE);

Parameters

_timeSince

Calculates time since proof submitted

proof.timestamp stores casted uint96(block.timestamp) block timestamps for gas optimization _timeSince(proof) can accomodate rollover case when block.timestamp > type(uint96).max but proof.timestamp < type(uint96).max via unchecked statement

function _timeSince(BridgeProof memory proof) internal view returns (uint256 delta);

Parameters

Returns

canClaim

Checks if the dispute period has passed so bridge deposit can be claimed

function canClaim(bytes32 transactionId, address relayer) external view returns (bool);

Parameters

claim

Completes bridge transaction on origin chain by claiming originally deposited capital

function claim(bytes memory request, address to) external onlyRole(RELAYER_ROLE);

Parameters

dispute

Disputes an outstanding proof in case relayer provided dest chain tx is invalid

function dispute(bytes32 transactionId) external onlyRole(GUARD_ROLE);

Parameters

refund

Refunds an outstanding bridge transaction in case optimistic bridging failed

function refund(bytes memory request) external;

Parameters

Enums

BridgeStatus

enum BridgeStatus {
    NULL,
    REQUESTED,
    RELAYER_PROVED,
    RELAYER_CLAIMED,
    REFUNDED
}

FastBridgeV2

Git Source

Inherits: Admin, IFastBridgeV2, IFastBridgeV2Errors

FastBridgeV2 is a contract for bridging tokens across chains.

State Variables

DISPUTE_PERIOD

Dispute period for relayed transactions

uint256 public constant DISPUTE_PERIOD = 30 minutes;

REFUND_DELAY

Delay for a transaction after which it could be permisionlessly refunded

uint256 public constant REFUND_DELAY = 7 days;

MIN_DEADLINE_PERIOD

Minimum deadline period to relay a requested bridge transaction

uint256 public constant MIN_DEADLINE_PERIOD = 30 minutes;

MAX_CALL_PARAMS_LENGTH

Maximum length of accepted callParams

uint256 public constant MAX_CALL_PARAMS_LENGTH = 2 ** 16 - 1;

bridgeTxDetails

Status of the bridge tx on origin chain

mapping(bytes32 => BridgeTxDetails) public bridgeTxDetails;

bridgeRelayDetails

Relay details on destination chain

mapping(bytes32 => BridgeRelay) public bridgeRelayDetails;

senderNonces

Unique bridge nonces tracked per originSender

mapping(address => uint256) public senderNonces;

nonce

This is deprecated and should not be used.

Replaced by senderNonces

uint256 public immutable nonce = 0;

deployBlock

the block the contract was deployed at

uint256 public immutable deployBlock;

Functions

constructor

constructor(address _owner) Admin(_owner);

bridge

Initiates bridge on origin chain to be relayed by off-chain relayer

function bridge(BridgeParams memory params) external payable;

Parameters

relay

Relays destination side of bridge transaction by off-chain relayer

function relay(bytes memory request) external payable;

Parameters

prove

Provides proof on origin side that relayer provided funds on destination side of bridge transaction

function prove(bytes memory request, bytes32 destTxHash) external;

Parameters

claim

Completes bridge transaction on origin chain by claiming originally deposited capital.

function claim(bytes memory request) external;

Parameters

dispute

Disputes an outstanding proof in case relayer provided dest chain tx is invalid

function dispute(bytes32 transactionId) external onlyRole(GUARD_ROLE);

Parameters

refund

Refunds an outstanding bridge transaction in case optimistic bridging failed

function refund(bytes memory request) external;

Parameters

canClaim

Checks if the dispute period has passed so bridge deposit can be claimed

function canClaim(bytes32 transactionId, address relayer) external view returns (bool);

Parameters

getBridgeTransaction

Decodes bridge request into a bridge transaction

function getBridgeTransaction(bytes memory request) external pure returns (BridgeTransaction memory);

Parameters

bridge

Initiates bridge on origin chain to be relayed by off-chain relayer, with the ability to provide temporary exclusivity fill rights for the quote relayer.

function bridge(BridgeParams memory params, BridgeParamsV2 memory paramsV2) public payable;

Parameters

relay

Relays destination side of bridge transaction by off-chain relayer

function relay(bytes memory request, address relayer) public payable;

Parameters

prove

Provides proof on origin side that relayer provided funds on destination side of bridge transaction

function prove(bytes32 transactionId, bytes32 destTxHash, address relayer) public onlyRole(RELAYER_ROLE);

Parameters

claim

Completes bridge transaction on origin chain by claiming originally deposited capital

function claim(bytes memory request, address to) public;

Parameters

bridgeStatuses

function bridgeStatuses(bytes32 transactionId) public view returns (BridgeStatus status);

bridgeProofs

function bridgeProofs(bytes32 transactionId) public view returns (uint96 timestamp, address relayer);

bridgeRelays

Checks if a transaction has been relayed

function bridgeRelays(bytes32 transactionId) public view returns (bool);

Parameters

Returns

getBridgeTransactionV2

Decodes bridge request into a bridge transaction V2 struct used by FastBridgeV2

function getBridgeTransactionV2(bytes memory request) public pure returns (BridgeTransactionV2 memory);

Parameters

_pullToken

Pulls a requested token from the user to the requested recipient.

Be careful of re-entrancy issues when msg.value > 0 and recipient != address(this)

function _pullToken(address recipient, address token, uint256 amount) internal returns (uint256 amountPulled);

_checkedCallRecipient

Calls the Recipient's hook function with the specified callParams and performs all the necessary checks for the returned value.

function _checkedCallRecipient(
    address recipient,
    uint256 msgValue,
    address token,
    uint256 amount,
    bytes memory callParams
)
    internal;

_timeSince

Calculates time since proof submitted

proof.timestamp stores casted uint40(block.timestamp) block timestamps for gas optimization _timeSince(proof) can accomodate rollover case when block.timestamp > type(uint40).max but proof.timestamp < type(uint40).max via unchecked statement

function _timeSince(uint40 proofBlockTimestamp) internal view returns (uint256 delta);

Parameters

Returns