# GC Bellatrix-Capella Roadmap

## Bellatrix

The Merge of the GC with the GBC requires a coordination between majority of the node runners, however it is designed to have minimal impact on the end users.

### Configuration

Parameters:

BELLATRIX_FORK_VERSION: 0x02000064
BELLATRIX_FORK_EPOCH: TBD
TERMINAL_TOTAL_DIFFICULTY: TBD

EXPECTED_TERMINAL_BLOCK_NUMBER: TBD

`TERMINAL_TOTAL_DIFFICULTY` is approximated from the desired block number by the following formula: `TD(X) + (EXPECTED_TERMINAL_BLOCK_NUMBER - X) * (2**128 - 2) - 2**127`, where `X` is some recent block already known at the moment of creating EL client releases, `TD(X)` is a total difficulty of block `X`.

Expected timestamp of `EXPECTED_TERMINAL_BLOCK_NUMBER` should be higher than timestamp of `BELLATRIX_FORK_EPOCH`. (e.g. few hours?).

### Process
1) The Merge transition should first happen in the GBC network, at this moment all GBC validators are expected to be already connected to the local EL node. Transition starts in the GBC at epoch `BELLATRIX_FORK_EPOCH`. Each beacon slot after that will to contain empty `ExecutionPayload`.
2) After some time, some GBC proposer detects that `TERMINAL_TOTAL_DIFFICULTY` is reached in the head block (at block with number `EXPECTED_TERMINAL_BLOCK_NUMBER`) of the chain, it includes it's block hash in the parent hash of the `ExecutionPayload` of the first proposed PoS block.
3) GC nodes halts AuRa consensus for all further blocks.
4) GBC nodes verify that included `parent_hash` in the first PoS block satisfies terminal block conditions.
5) Further GC blocks are being proposed based on the latest available execution payload in the GBC.

### Coordination

#### GBC Validators

Every validator should run their own EL GC node next to its CL counterpart, before reaching the `BELLATRIX_FORK_EPOCH` in the GBC.

**TBD:** Confirm that GBC validator can still function, while connected to remote GC node after the `BELLATRIX_FORK_EPOCH`, but before terminal block is reached.

##### Steps:
1) Update GBC client.
2) Launch local GC client.
3) Configure fee recipient in the GC.
4) Connect GBC client to GC client engine API and regular JSON RPC.

#### POSDAO validators

POSDAO validators that are **not** running GBC validators will no be able to participate in the consensus after the PoS transition. After the trasition block is reached, their node will not be able to mine new blocks, and will not be able to sync with the rest of the network by itself (i.e. it will halt).

POSDAO validators that are running their GBC validators will be able to participate in the consensus after the PoS transition, based on their GBC stake.
Assuming that the current setup of such POSDAO validators use separate isolated environments for running GC and GBC, they will need to perform some manipulation on those and bring them together in the same private network.
After the `BELLATRIX_FORK_EPOCH` in the GBC, we expect that such POSDAO validator will already have their GBC and GC node running in the same environment. However, prior to reaching terminal block, the block mining process will be only handled by the EL alone.
During the PoS transition, we expect that EL consensus will be halted, and the next blocks will start to arrive smoothly through the GBC, without manual intervention.

We will ensure that all POSDAO validators upgraded their node to the sufficient version, therefore AuRa block proposals will completely halt after reaching `TERMINAL_TOTAL_DIFFICULTY`. The only way to propose new blocks will be through the GBC.

##### Steps:
1) Update GC client.
2) Update GBC client.
3) Bring GC and GBC together (i.e. into a common private network, or into a single VM)
4) Configure fee recipient in the GC.
5) Connect GBC client to GC client engine API and regular JSON RPC.

#### GC node providers

Third parties running non-validator GC nodes, will need to update their setup to the two-client one.
GC node alone won't be able to securely sync the network after the PoS transition. If they would like to smoothly migrate to the PoS setup, they will need to start GBC node nearby, before `TERMINAL_BLOCK` is reached.
During the transition, we simply expect that the p2p block propagation will switch from EL to CL.

Many cloud setups for EL include some kind of load balancing between multiple nodes. Hopefully, there is no need to run a GBC node next to each EL instance in such case. It should be quite easy to setup a 1-to-N setup, in which single beacon node can drive multiple EL nodes. (**TBD:** client configuration example)

##### Steps:
1) Update GC client.
2) Launch >= 1 GBC clients.
3) Connect GBC client to >= 1 GC clients engine API and regular JSON RPC.

#### GBC node providers

We do not have such. However, if there are any, they are not required to have local EL node nearby. They can continue to use remote EL node endpoint.

The only requirement is to update their node to the version with the correct `BELLATRIX_FORK_EPOCH` specified, in order to be able to correctly validate GBC.

(**TBD:** can we run a GBC node without connecting it to any GC nodes?)

##### Steps:
1) Update GBC client.

#### Dapps and external users

From the users point of view, we expect few minor JSON RPC changes to happen after the PoS transition:
1) Block structure is changed to fully comply with the Ethereum mainnet block structure. `step` and `signature` fields are going to be deprecated and replaced by the `mixHash` and `nonce` empty fields. If your Dapp somehow rely on the manual block hash calculation or particular set of fields when parsing raw blocks, make sure that such changes will not break because of such changes.
2) Usage of blocks confirmations and `latest` block tag. We suggest that Dapps should switch from `latest` and `latest - N blocks` schemes to a PoS like schemes: `safe`/`finalized`. (**TBD:** clarify final decision on `safe` block meaning)

##### Steps:
1) Review dapp code
2) Replace required block confirmations with `finalized`/`safe` block tags
3) Replace any specific AuRa block structure handling logic

## Capella

Hardfork for enabling withdrawals.

Preliminary specs: https://github.com/ethereum/consensus-specs/blob/dev/specs/capella/beacon-chain.md

### Configuration

CAPELLA_FORK_VERSION: 0x03000064
CAPELLA_FORK_EPOCH: TBD

### GC Adoption
New field `withdrawals`/`withdrawals_root` is added to the Execution block structure, so it is good that we will a fully Ethereum compatible block structure after the Merge.

When EL receives a block with withdrawals, during `notify_new_payload` / `notify_forkchoice_updated`, it must process a list of given withdrawals. In our case, the withdrawals processing will be done in the block reward contract, as we cannot just increase the native token balance, as in the Mainnet.

We propose to integrate GBC withdrawals distribution inside the existing block reward contract, by adding a new system function to it:

interface BlockReward {
    function reward(address[] benefactors, uint16[] kind)
        external returns (address[], uint256[]);
        
    function rewardGBC(address[] recipients, uint256[] values) external;
}

Each withdrawal contains receiver address in GC and the withdrawn amount in Gwei.

`rewardGBC` is then called by the block proposer each times a new block is created, similar to how it is done with a regular `reward` call.

Then, there are two possible technical implementations:
#### Full push
Block reward contract receives rights to withdraw from deposit contract and unlock/mint mGNO/GNO tokens in the GC. GNO tokens transfer happens inside block reward contract.

Pros:
* fully automatic, no user-intervention required

Cons:
* ERC20 event is not emitted, since transfer happens inside block reward. This will cause some accounting problems
* increased complexity of the block reward contract
* shared responsibility for GNO tokens between deposit contract and block reward contract.

#### Push + pull
Block reward contract records a set of performed withdrawals inside its storage. Once withdrawal is recorded in the contract state, anyone (user/permissionless bot) can claim this withdrawal by usual transaction in the EL.

Pros:
* simple block reward contract, no need in giving extra permissins to it
* keep full responsibility inside a deposit contract (unlock/mint rights for bridged GNO)
* ERC20 transfers are fully accountable, no missing events
* should be easier to track inside block explorers'

Cons:
* extra transactions from users/bots are required
* expecting extra delay of 1-2 blocks for withdrawals processing
* development and maintenance of a simple oracle for claiming user withdrawals

**TBD:** partial withdrawals, once defined in the original spec

#### GNO rewards

At some point, the system can reach a situation in which existing locked GNO balance inside the deposit contract is not enough to cover the desired withdrawal amount. In this case, we will ensure that a sufficient amount of extra GNO liqudity is being bridged from the Mainnet by the GnosisDAO, which will be directed towards covering all requested withdrawals.