SIP-167 Introduces an L2 governance bridge

[eternauta1337]

Overview

This is an implementation of SIP 167 "L2 Bridged Governance".

The basic idea is to own the system contracts on L2 via a contract, that is controlled from L1. This L2 owner contract only responds to transactions relayed from its L1 counterpart, which in turn only responds to the L1 owner.

L2 contract: OwnerRelayOnOptimism.sol
L1 counterpart: OwnerRelayOnEthereum.sol

Thus, L2 system contracts need to nominate OwnerRelayOnOptimism as their new owner. This effectively makes OwnerRelayOnOptimism the owner of the L2 instance 😮

The L1 owner (the pDAO) will then be able to use OwnerRelayOnEthereum to relay arbitrary messages to OwnerRelayOnOptimism, which will accept the messages as long as the L1 tx originator was effectively the OwnerRelayOnEthereum. It will then forward these messages to any contract on L2, with owner access.

E.g. changing a SystemSetting on L2, via this owner relay:

• Optimistic etherscan is used to get the encoded calldata for changing the setting on L2 (or the CLI can be used as well).
• A call to OwnerRelayOnEthereum.initiateRelay(SystemSettings address on L2, encoded calldata) is staged in the pDAO
• The pDAO signs and executes the tx
• 5-8 minutes later, the tx will be relayed to L2
• OwnerRelayOnEthereum.finalizeRelay(...) will be called by Optimism's messenger, pass all checks, and change the owner protected setting. Yay 🎉

Batching

Similarly, txs can be relayed in batches via OwnerRelayOnEtherem.initiateRelayBatch(...) and OwnerRelayOnOptimisim.finalizeRelayBatch(...). This is handy for when the pDAO needs to relay multiple txs at once, like for example when accepting ownership after all contracts on L2 have nominated OwnerRelayOnOptimism as their new owner.

Gas limits on L1 and L2

Both OwnerRelayOnEthereum.initiateRelay(...) and OwnerRelayOnEthereum.initiateBatchRelay(...) accept a crossDomainGasLimit parameter, which ultimately determines the gas limit of the L2 relayed transaction. If the value used is zero, the default system setting will be used (currently 8m gas).

In practice, we've found that accepting ownership on more than 25 contracts runs out of gas on L2 if the crossDomainGasLimit is 8m.

Temporary fallback mechanism

Since this is a novel mechanism controlling a very critical aspect of the system on L2, a temporary fallback mechanism on L2 is implemented: OwnerRelayOnOptimism.directRelay(...).

This allows an EOA to directly control the contract owner on L2, but this functionality expires after a certain amount of time. The EOA that has access to this functionality and the amount of time it lasts for has to be set on contract deployment and cannot be changed.

Ownership control in the new contracts is as follows:

• OwnerRelayOnEthereum => Owned => The pDAO
• OwnerRelayOnOptimism => TemporarilyOwned => an EOA

New settings and defaults

Adds SystemSettings.CROSS_DOMAIN_RELAY_GAS_LIMIT.

Adds default values in index.js for

• TEMP_OWNER_DEFAULT_DURATION: 60 days
• CROSS_DOMAIN_RELAY_GAS_LIMIT: 8000000

New scripts

connect-bridge.js is updated to also connect the owner relay contracts.

nominate-relay.js is added, similar to nominate.js but specialized for the relay. This should NOT be used to nominate all contracts to OwnerRelayOnOptimism when the current owner is an EOA, but when the current owner is the relay, and a new relay or EOA is to be nominated.

owner-relay.js is added, similar to owner.js but specialized for the relay. This should be used to (a) accept owner ship for OwnerRelayOnOptimism after nomination, or to stage owner actions to the pDAO multisig.

Tests

New unit tests:

• OwnerRelayOnEthereum.js
• OwnerRelayOnOptimism.js
• TemporarilyOwned.js
• SystemSettings.js (partial addition)

New integration tests:

• relay.integration.js - dual test changing an L2 SystemSetting from L1
• relayBatch.integration.js - dual test changing ownership of all L2 contracts and accepting it via L1
• directRelay.l2.integration.js - L2 test on the temporary fallback mechanism

Deployment runsheet

To deploy this feature in production, contracts need to be deployed both on mainnet and optimistic-mainnet networks, and the contracts then need to be connected (i.e. each instance needs to know of the addresses of its counterparts in the opposite network).

L1 deployment:

• Deploy OwnerRelayOnEthereum and SystemSettings

L2 deployment

• Deploy OwnerRelayOnOptimism

Connection

• On L1, Stage AddressResolver.importAddresses("ovm:OwnerRelayOnOptimism", address) and execute it on the pDAO.
• On L1, call OwnerRelayOnEthereum.rebuildCache()
• On L2, run AddressResolver.importAddresses("base:OwnerRelayOnEthereum", address).
• On L1, call OwnerRelayOnOptimism.rebuildCache()

Ownership transfer on L2

• Use nominate.js on L2 (with --use-ovm) to nominate all L2 contracts to the deployed address of OwnerRelayOnOptimism. Note that nominate-relay.js is only needed in the future, after ownership is the relay and not an EOA.
• Accept L2 relay ownership by OwnerRelayOnOptimism using the bridge. Use the new command owner-relay. It will use OwnerRelayOnEthereum.initiateRelayBatch and will be done via an EOA if you are on a test network or staging a transaction on Gnosis Safe if you are deploying for mainnet. This should be repeated at least twice (until you confirm there's no more contracts pending) since it's a batch execution with a limit in the number of contracts per batch to prevent a revert due to exceeding the gas limit.
• Verify OwnerRelayOnOptimism is the owner of the contracts on L2.

Command examples

Connect the relay contracts (only works on instances owned by EOAs, i.e. testnets)

In this example we deployed a brand new system on kovan (#1467).

node publish connect-bridge \
    --l1-network kovan \
    --l2-network kovan \
    --l1-provider-url https://kovan.infura.io/v3/1xxxxxxba1 \
    --l2-provider-url https://kovan.optimism.io/ \
    --l1-deployment-path ./publish/deployed/kovan-test \
    --l2-deployment-path ./publish/deployed/kovan-test-ovm \
    --l1-private-key 0x479xxxxxxxxxxxda0 \
    --l2-private-key 0x479xxxxxxxxxxxda0 \
    --l1-messenger 0x4361d0F75A0186C05f971c566dC6bEa5957483fD \
    --l2-messenger 0x4200000000000000000000000000000000000007 \
    --l1-gas-price 2 \
    --l1-gas-limit 8000000 --dry-run

Nominate OwnerRelayOnOptimism

Using the nominate command set the --new-owner to the OwnerRelayOnOptimism address.

node publish nominate --network kovan --deployment-path ./publish/deployed/kovan-test-o
vm  --new-owner 0x41e5175CD6eB75a96b50D9935a6E534A5B1559B2 --use-ovm --provider-url https://kovan.optimism.io

Accept L2 relay ownership by OwnerRelayOnOptimism using the bridge

In this case it was necessary to run this twice, to cover all the contracts. Note that before running the second time you should confirm the first batch succeeded.
You can use https://kovan-optimistic.etherscan.io/txsEnqueued (or https://optimistic.etherscan.io/txsEnqueued for mainnet) to check if the transaction was sent to L2 by Optimism network.

node publish  owner-relay \
    --l1-network kovan \
    --l2-network kovan \
    --l1-deployment-path ./publish/deployed/kovan-test \
    --l2-deployment-path ./publish/deployed/kovan-test-ovm \
    --l1-provider-url https://kovan.infura.io/v3/1xxxxxxba1 \
    --l2-provider-url https://kovan.optimism.io/ \
    --l1-private-key 0x479xxxxxxxxxxxda0 \
    --gas-price 2 \
    --gas-limit 8000000

This example was run using a EOA on L1 to accept ownership via Relay on L2. In case a Gnosis Safe is used as owner on L1, the command should include the flag --is-contract in the same way as it's done with node publish owner command.

Change ownership on L2 (back to EOA or other OwnerRelayOnOptimism)

In case something went wrong, there are two alternatives to regain ownership of the L2 contracts. One using the relay itself or another, that is only available for a period of time, directly using OwnerRelayOnOptimism with the designated temporary owner.

Using the Relay
Once the relay is configured, OwnerRelayOnOptimism will be the owner of all L2 contracts. You can change it to a new owner (a new contract or an EOA) using the new command nominate-relay to nominate a new owner in batches for all L2 contracts.
An example of how to use this new contract can be seen here:

node publish  nominate-relay \
    --l1-network kovan \
    --l2-network kovan \
    --l1-deployment-path ./publish/deployed/kovan-test \
    --l2-deployment-path ./publish/deployed/kovan-test-ovm \
    --l1-provider-url https://kovan.infura.io/v3/1xxxxxxba1 \
    --l2-provider-url https://kovan.optimism.io/ \
    --l1-private-key 0x479xxxxxxxxxxxda0 \
    --gas-price 2 \
    --gas-limit 8000000 \
    --new-owner 0x23e78AaC93254a858c1bA7F6fE92468fE367B3f1

The same note mentioned on owner-relay using an EOA or Gnosis Safe on L1 are valid here, you can set the same parameters like --is-contract to indicate the command to stage a transaction instead of executing it as an EOA.

Using the temporary owner
In order to nominate a new owner and there was something wrong setting up the relay, you can use the temporary owner to act on that situation using the function OwnerRelayOnOptimism.directRelay(address target, bytes calldata payload)

[codecov]

Codecov Report

Merging #1402 (31dbf74) into develop (682a2ef) will increase coverage by 0.08%.
The diff coverage is 100.00%.

@@             Coverage Diff             @@
##           develop    #1402      +/-   ##
===========================================
+ Coverage    95.58%   95.67%   +0.08%     
===========================================
  Files           79       82       +3     
  Lines         1882     1917      +35     
  Branches       586      598      +12     
===========================================
+ Hits          1799     1834      +35     
  Misses          83       83              

Impacted Files	Coverage Δ
contracts/SynthetixBridgeEscrow.sol	100.00% <ø> (ø)
contracts/MixinSystemSettings.sol	100.00% <100.00%> (ø)
contracts/OwnerRelayOnEthereum.sol	100.00% <100.00%> (ø)
contracts/OwnerRelayOnOptimism.sol	100.00% <100.00%> (ø)
contracts/TemporarilyOwned.sol	100.00% <100.00%> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 682a2ef...31dbf74. Read the comment docs.