.///. .///. //. .// `/////////////-
`++:++` .++:++` :++` `++: `++:......---.`
`/+: -+/` `++- :+/` /+/ `/+/ `++.
/+/ :+/ /+: /+/ `/+/ /+/` `++.
-::/++::` /+: -::/++::` `/+: `++: :++` `++/:::::::::.
-:+++::-` `/+: --++/---` `++- .++- -++. `++/:::::::::.
-++. .++- -++` .++. .++. .++- `++.
.++- -++. .++. -++. -++``++- `++.
`++: :++` .++- :++` :+//+: `++:----------`
-/: :/- -/: :/. ://: `/////////////-
This repository contains smart contracts and related code for Aave cross-chain bridge executors. This is intended to extend Aave Governance on Ethereum to other networks. This repository currently contains contracts to support bridging to Polygon, Arbitrum and Optimism.
The core contract is the BridgeExecutorBase, an abstract contract that contains the logic to facilitate the queueing, delay, and execution of sets of actions on downstream networks. This base contract needs to be extended with the functionality required for cross-chain transactions on a specific downstream network.
The BridgeExecutorBase contract is implemented to facilitate the execution of arbitrary actions after governance approval on Ethereum. Once the Ethereum proposal is executed, a cross-chain transaction can queue sets of actions for execution on the downstream chain. Once queued, these actions cannot be executed until a certain delay has passed, though a specified (potentially zero) guardian address has the power to cancel the execution of these actions. If the delay period passes and the actions are not cancelled, the actions can be executed during the grace period time window by anyone on the downstream chain.
The BridgeExecutorBase is abstract and intentionally leaves the _queue function internal. This requires another contract to extend the BridgeExecutorBase to handle network specific logic, cross-chain transaction validation, and permissioning, prior to calling the internal _queue function.
The L2BridgeExecutor abstract contract extends BridgeExecutorBase in order to make it ready for Layer 2 networks. It stores the address of the Ethereum Governance Executor on the Ethereum network, so each inheriting L2 implementation is aware of the address it should accept transactions from.
- 12/08/2021 MixBytes - Bridge contracts for Polygon
- 26/06/2022 Certora - Formal Verification of Arbitrum, Optimism and Polygon
- 26/07/2022 ChainSecurity - Bridge contracts for Optimism and Arbitrum
- 15/08/2022 Oxorio - Bridge contracts for Optimism and Arbitrum
| Contract Name | Address | Code | Network |
|---|---|---|---|
| PolygonBridgeExecutor | 0xdc9A35B16DB4e126cFeDC41322b3a36454B1F772 | 1.0.0 | Polygon |
| ArbitrumBridgeExecutor | 0x7d9103572be58ffe99dc390e8246f02dcae6f611 | 1.0.1 | Arbitrum |
| OptimismBridgeExecutor | 0x7d9103572be58ffe99dc390e8246f02dcae6f611 | 1.0.1 | Opitmism |
- Clone the repository
- run
npm install
Follow the next steps to setup the repository:
- Install
dockeranddocker-compose - Create an environment file named
.envand fill out the environment variables perexample.env
Terminal Window 1: docker-compose up
Once Terminal Window 1 Loaded - in a separate terminal window - Terminal Window 2:
docker-compose exec contracts-env bash
In Terminal Window 2, run desired scripts from npm package file (i.e npm run compile)
npm run compile
This will compile the available smart contracts.
npm run test
Run the full suite of unit tests.
npm run test-fork
Run an end to end test of these contracts on an Ethereum mainnet fork. This makes the assumption that all contracts are on Ethereum, which is an inaccurate assumption but helps for testing smart contract functionality in one script.
npm run coverage
Get the coverage report.
Additional documentation around the Polygon Bridging setup can be found at the links below:
- The proposal is an encoded function call to the function
sendMessageToChild()inFxRoot. The calldata for this proposal contains two encoded variables:- The first variable is the address of the contract that will decode and process this message on the Polygon chain. In this case, the receiver is the
PolygonBridgeExecutorcontract address. - The second variable is the data that will be decoded on the Polygon chain. This field contains encoded bytes for the following fields:
targets[],values[],signatures[],calldatas[], andwithDelegatecall[].
- The first variable is the address of the contract that will decode and process this message on the Polygon chain. In this case, the receiver is the
- When the proposal is executed,
sendMessageToChild()in theFxRoottriggerssyncState()on theStateSendercontract which emits aStateSyncevent. - Validators listening for this
StateSyncevent then trigger theonStateReceived()in theFxChildcontract on Polygon. - In
onStateReceivedthe encoded data is passed along to a contract that implements the functionprocessMessageFromRoot- which in this case is in thePolygonBridgeExecutorcontract. InprocessMessageFromRootthePolygonBridgeExecutorcalls_queue()in theBridgeExecutorBasecontract to queue the proposed actions for the appropriate execution time
fxRootSender- the address that can send messages to thisPolygonBridgeExecutorthrough the FxPortal. This should be the Aave Governance Executor.fxChild- the fxChild contract from the FxPortaldelay- the time required to pass after the ActionsSet is queued, before executiongracePeriod- once execution time passes, you can execute this until the grace period endsminimumDelay- minimum allowed delaymaximumDelay- maximum allowed delayguardian- the admin address of this contract with the permission to cancel ActionsSets
This repository uses the FxPortal developed and designed by the Polygon team to support bridging from Ethereum to Polygon. The intent of the FxPortal is to help users avoid the step of registering their own sender and receiver contracts within Polygon's StateSender contract. The FxPortal contains two contracts - FxRoot and FxChild. The FxRoot contract has been deployed on Ethereum and the FxChild contract has been deployed on Polygon. The FxRoot contract is mapped to the FxChild contract via Polygon's StateSender contract on Ethereum. By calling the sendMessageToChild(address _receiver, bytes calldata _data) function in the FxRoot, the msg.sender is encoded, along with the provided _receiver and _data. This encoded message is sent to the StateSender contract and a StateSynced event is emitted with this data.
Polygon validators listen for StateSynced events from the StateSender - upon identifying one of these events from the FxRoot, they will call the function onStateReceive(uint256 stateId, bytes calldata _data) in FxChild. The encoded data message is decoded in FxChild and forwarded to the receiver contract via the function processMessageFromRoot(stateId, rootMessageSender, data). The rootMessageSender that is passed along is the original msg.sender that called FxRoot which in this case is the Aave Governance Executor contract.
The PolygonBridgeExecutor implements the function processMessageFromRoot(stateId, rootMessageSender, data);. In this function, requiring that the msg.sender is the FxChild should ensure this is a legitimate transaction stemming from the Ethereum bridge. By confirming that the rootMessageSender is the Aave Governance Executor contract, the PolygonBridgeExecutor can conclude this bridge transaction was triggered by the Aave Governance process and should in fact be queued for execution.
Polygon Protocol Ownership Change
In order to change the ownership of the Aave Polygon Market, the current owner must call transferOwnership(address) on Ownable contracts within the protocol. The address parameter provided to transferOwnership(address) should be the address of the deployed PolygonBridgeExecutor contract on Polygon. Once ownership of the Aave Polygon Market contracts is transferred to the PolygonBridgeExecutor, the PolygonBridgeExecutor will have the authorization to make updates to the Aave Polygon Market. Updates are only possible if they have completed the end-to-end, cross-chain governance process, passing Aave governance on Ethereum and going through the timelock on Polygon without being cancelled.
In the future, if a change is needed in the PolygonBridgeExecutor contract, a new version can be deployed, and transferOwnership(address) should be called on Ownable contracts within the Aave Polygon Market, through the original version of the PolygonBridgeExecutor contract in order to pass ownership to the new PolygonBridgeExecutor version.
Aave Governance Executor Update
Aave's governance contracts on Ethereum are upgradable and because the PolygonBridgeExecutor is dependent on knowing the address of the Aave Governance Executor contract on Ethereum, the PolygonBridgeExecutor will also have to be updated as part of this upgrade.
In order to update the PolygonBridgeExecutor - the function updateFxRootSender(address) should be called on the PolygonBridgeExecutor. This function should be executed via the cross-chain governance process using the original Aave Governance Executor. A proposal should be created on the Ethereum based Aave governance, once passed and executed, the transaction will be sent to the PolygonBridgeExecutor contract. Once queued and executed, the PolygonBridgeExecutor will call updateFxRootSender(address) on itself and update the expected Aave Governance Executor address. Once that transaction executes, the PolygonBridgeExecutor will only queue ActionsSets that originate from the new Aave Governance Executor.
Additional documentation around the Arbitrum Bridging setup can be found at the links below:
After going through the Aave governance, the proposal payload will be a call to the following function in the Arbitrum Inbox contract on Ethereum:
/**
* @notice Put a message in the L2 inbox that can be reexecuted for some fixed amount of time if it reverts
* @dev all msg.value will deposited to callValueRefundAddress on L2
* @param destAddr destination L2 contract address
* @param l2CallValue call value for retryable L2 message
* @param maxSubmissionCost Max gas deducted from user's L2 balance to cover base submission fee
* @param excessFeeRefundAddress maxgas x gasprice - execution cost gets credited here on L2 balance
* @param callValueRefundAddress l2Callvalue gets credited here on L2 if retryable txn times out or gets cancelled
* @param maxGas Max gas deducted from user's L2 balance to cover L2 execution
* @param gasPriceBid price bid for L2 execution
* @param data ABI encoded data of L2 message
* @return unique id for retryable transaction (keccak256(requestID, uint(0) )
*/
function createRetryableTicket(
address destAddr,
uint256 l2CallValue,
uint256 maxSubmissionCost,
address excessFeeRefundAddress,
address callValueRefundAddress,
uint256 maxGas,
uint256 gasPriceBid,
bytes calldata data
) external payable returns (uint256)
From the function above, the key (non-gas related) bridging fields are destAddr, data, and l2CallValue. destAddr is the contract that will be called on Arbitrum. In this case, it is the ArbitrumBridgeExecutor contract. The data is the encoded data for the cross-chain transaction. In this case, the data should be the encoded data for queue(targets, values, signatures, calldatas, withDelegatecalls). l2CallValue is what will be sent over as the msg.value on L2. The rest of the fields pertain to gas management on Arbitrum and should be defined per Arbitrum documentation.
When this transaction is sent cross-chain, the msg.sender that send the message to the Arbitrum Inbox is aliased. This means that the so-called "L2 Alias" of the Aave Governance Executor contract will be the msg.sender when the ArbitrumBridgeExecutor is called on Arbitrum. For this reason, the Aave Governance Executor contract address should be provided to the ArbitrumBridgeExecutor contract in the constructor. This address will be saved, transformed to its alias, and used to permit the queue function so that only calls from this address can successfully queue the ActionsSet in the BridgeExecutorBase.
ethereumGovernanceExecutor- the address that will have permission to queue ActionSets. This should be the Aave Governance Executor.delay- the time required to pass after the ActionsSet is queued, before executiongracePeriod- once execution time passes, you can execute this until the grace period endsminimumDelay- minimum allowed delaymaximumDelay- maximum allowed delayguardian- the admin address of this contract with the permission to cancel ActionsSets
This repository contains a set of handy scripts for retryable tickets management.
Once a retryable ticket is created in L1, the ticket is redeemable for about a week on L2. Arbitrum will try to auto-redeem it. If the action succeeds, a receipt is issued for it and the ticket is canceled and cannot be used anymore. If the action fails, the redemption reports failure and the ticket remains available for redemption.
Anyone can redeem a retryable ticket while the ticket is valid. The validity of a retyable ticket can be extended by anyone, so the ticket can be kept alive forever. However, a retyable ticket can be canceled by the callValueRefundAddress address, making its redemption impractical.
- Get Ticket Id of Retryable Ticket
npm run hardhat:main arbitrum:get-ticket-id -- --txhash [L1_TX_HASH]
- Redeem a Retryable Ticket on L2
npm run hardhat:arbitrum arbitrum:redeem-retryable -- --ticketid [TICKET_ID]
- Extend lifetime of a Retryable Ticket on L2
npm run hardhat:arbitrum arbitrum:extend-retryable -- --ticketid [TICKET_ID]
- Cancel a Retryable Ticket on L2
npm run hardhat:arbitrum arbitrum:cancel-retryable -- --ticketid [TICKET_ID]
Additional documentation around the Optimism Bridging setup can be found at the links below:
After going through the Aave governance, the proposal payload will be a call to the following function in the OVM L1 Cross Domain Messenger contract on Ethereum:
/**
* Sends a cross domain message to the target messenger.
* @param _target Target contract address.
* @param _message Message to send to the target.
* @param _gasLimit Gas limit for the provided message.
*/
function sendMessage(
address _target,
bytes memory _message,
uint32 _gasLimit
) public
From the function above, the target is the contract that will be called on Optimism (in this case it is the OptimismBridgeExecutor contract). The _message is the encoded data for the cross-chain transaction: the encoded data for queue(targets, values, signatures, calldatas, withDelegatecalls). The _gasLimit field pertain to gas management on Optimism and should be defined per Optimism documentation.
When this transaction is sent cross-chain, the msg.sender that sends the message to the Optimism Messenger is stored at the OVM L2 Cross Domain Messenger and queryable using the following function:
function xDomainMessageSender() external view returns (address);
Therefore, the msg.sender of the cross-chain transaction on Optimism is the OVM L2 Cross Domain Messenger contract, and the L1 sender is the Aave Governance Executor contract. For this reason, the Aave Governance Executor contract address should be provided to the OptimismBridgeExecutor contract in the constructor. This address will be saved and used to permit the queue function so that only calls from this address can successfully queue the ActionsSet in the BridgeExecutorBase.
ovmL2CrossDomainMessenger- the address of the OVM L2 Cross Domain Messenger contractethereumGovernanceExecutor- the address that will have permission to queue ActionSets. This should be the Aave Governance Executor.delay- the time required to pass after the ActionsSet is queued, before executiongracePeriod- once execution time passes, you can execute this until the grace period endsminimumDelay- minimum allowed delaymaximumDelay- maximum allowed delayguardian- the admin address of this contract with the permission to cancel ActionsSets