gnosischain / specs

Specs for Gnosis Chain

Gnosis Chain specs

WIP ⚠️ 🚧 the format and structure of this repo is not final

This repository hosts the current specifications for Gnosis chain and Gnosis beacon chain. Both specs are based on Ethereum's specifications, and only specify the differences.

• Consensus: Gnosis Beacon Chain specifications
• Execution: Gnosis Chain specifications

specs's Issues

Setting EIP-4788 `HISTORY_BUFFER_LENGTH`

There are two options:

	Increase HISTORY_BUFFER_LENGTH	Same HISTORY_BUFFER_LENGTH
Requires to edit audited smart contract	Yes	No
Max age of retrieved beacon block root	1.14 days (Same as Ethereum)	0.47 days
Value	19661	8191

Cost of editing smart contract

Beacon block roots contract bytecode has been audited 3 times as of October 1st 2023. The contract is written directly in bytecode. The modification requires to change the byte highest byte of the HISTORY_BUFFER_LENGTH constant on all the places it's used

def is_prime(n):
    if n <= 1:
        return False
    for i in range(2, int(n ** 0.5) + 1):
        if n % i == 0:
            return False
    return True

n = round(12/5 * 8191)
print(n)
while not is_prime(n):
    n += 1
print(n)

start: 19658
prime: 19661 = 0x4ccd

Contract source code: https://github.com/lightclient/4788asm/blob/main/src/main.etk

UX cost for consumer applications

If the same HISTORY_BUFFER_LENGTH value is used to Ethereum, consumer applications won't have access to roots of age between 0.47 and 1.17 days. This change can have two effects:

• May require more operations per unit of time, if the consumer has frequency of > 0.47 days. Given Gnosis fees are likely to remain at least 2x cheaper than Ethereum, this should not incur extra operational costs.
• Additional customizable parameters. If a consumer application has a hard-coded limit of 1 day to trigger a beacon block root update, it must either change the hard-coded constant for a Gnosis chain deployment or make that value customizable.

Setting EIP-4844 `TARGET`/`MAX_BLOB_GAS_PER_BLOCK`

Gnosis chain has slots significantly faster than Ethereum. Bigger blocks could have a higher cost to the network than Ethereum so we may price blobs differently. Ethereum mainnet has chosen a target of 3 blobs from real live experiments on mainnet with big blocks. Consecuently this parameters may not be adecuate.

Add shapella fork details

• Explicitly list the EIPs included in Gnosis shapella fork
• Link existing withdrawals spec

List confirmed in May 3rd core devs call:

• EIP-170: Contract code size limit. Activated in Gnosis at a latter fork than Ethereum
• EIP-3651: Warm COINBASE. Makes it a bit less expensive to access the coinbase address. Useful for flashbots for example
• EIP-3855: PUSH0 instruction. Slight gas optimization when pushing a 0 to the stack
• EIP-3860: Limit and meter initcode. Limits the size of deployed contracts and makes deployments a bit more expensive
• EIP-4895: Beacon chain push withdrawals as operations** Gnosis modified
• EIP-6049: Deprecate SELFDESTRUCT. Deprecates the SELFDESTRUCT opcode. Doesn’t actually change its behavior yet

Safety of MAX_BLOBS_PER_BLOCK, BLOB_SIDECAR_SUBNET_COUNT = 6

Gnosis has reduced the MAX_BLOB_GAS_PER_BLOCK = 2 blobs EIP-4844 param due to its faster slot times.

specs/network-upgrades/dencun.md

Line 35 in a249f7d

| MAX_BLOB_GAS_PER_BLOCK | 262144 |

However the consensus specs define two independent variables that limit blobs in different ways. When possible we prefer not to modify consensus variables that would require custom code in consensus implementations, so the same codebase can work for Ethereum and Gnosis networks. This variables are:

variable	value	type
`MAX_BLOBS_PER_BLOCK	6	CL preset
`BLOB_SIDECAR_SUBNET_COUNT	6	CL config

So: Is it safe to have NOT reduce MAX_BLOBS_PER_BLOCK, BLOB_SIDECAR_SUBNET_COUNT?

Current usage

1. MAX_BLOBS_PER_BLOCK is used in state transition to enforce the maximum of blobs, independent of MAX_BLOB_GAS_PER_BLOCK

def process_execution_payload(state: BeaconState, body: BeaconBlockBody, execution_engine: ExecutionEngine) -> None:
    ...
    # [New in Deneb:EIP4844] Verify commitments are under limit
    assert len(body.blob_kzg_commitments) <= MAX_BLOBS_PER_BLOCK

2. MAX_BLOBS_PER_BLOCK is used in ReqResp to compute MAX_REQUEST_BLOB_SIDECARS = MAX_REQUEST_BLOCKS_DENEB * MAX_BLOBS_PER_BLOCK. MAX_REQUEST_BLOB_SIDECARS is used to limit /eth2/beacon_chain/req/blob_sidecars_by_root/1/ and /eth2/beacon_chain/req/blob_sidecars_by_range/1/ protocol requests:

The response MUST contain no more than count * MAX_BLOBS_PER_BLOCK blob sidecars.

3. MAX_BLOBS_PER_BLOCK is used in gossip topic beacon_block to limit the count of blob_kzg_commitments:

[REJECT] The length of KZG commitments is less than or equal to the limitation defined in Consensus Layer -- i.e. validate that len(body.signed_beacon_block.message.blob_kzg_commitments) <= MAX_BLOBS_PER_BLOCK

4. MAX_BLOBS_PER_BLOCK is used in gossip topic blob_sidecar_{subnet_id} to upper bound the index field:

[REJECT] The sidecar's index is consistent with MAX_BLOBS_PER_BLOCK -- i.e. blob_sidecar.index < MAX_BLOBS_PER_BLOCK.

5. BLOB_SIDECAR_SUBNET_COUNT is used to compute at which subnet each block_sidecar.index has to be published to:

def compute_subnet_for_blob_sidecar(blob_index: BlobIndex) -> SubnetID:
    return SubnetID(blob_index % BLOB_SIDECAR_SUBNET_COUNT)

Consequences of MAX_BLOBS_PER_BLOCK > MAX_BLOB_GAS_PER_BLOCK:

1. A block with too much commitments will be accepted by this initial consensus condition. If the block has too much blobs it will be rejected by execution validation. If the length of versioned_hashes does not match the count of blobs, the block is rejected.

2. 3x more blobs may be requested and returned. Slightly higher bandwidth cost to nodes but not a concern.

3. A block that will become invalid on 2) may be initially accepted and propagated. Slightly higher DoS vector but not a concern?

4. One could publish a blob sidecar with index > 2, and it will pass the condition highlighted in 5). However to pass the second condition of the topic, the actual index in the blob sidecar has to also be > 2. Then the condition checking verify_blob_sidecar_inclusion_proof would fail unless the proposer has published a block that includes too many blobs. The proposer can temporarily increase the count of blobs being propagated in the network from 2 to 6 at the expense of losing a block proposal.

5. Nodes may subscribe to 4 subnet topics that will never publish or broadcast any messages. Could be a problem for scoring? No, since blob publication is a function of demand, nodes can't expect a specific throughput per subnet. Thus a situation where a blob is never propagated on subnet 3 is indistinguishable from a network period of no blob activity.

Conclusions

Not reducing MAX_BLOBS_PER_BLOCK will allow to broadcast invalid data over p2p, but at the cost of the proposer not having its block accepted. There are not other concerns.

Setting EIP-4844 `MIN_BLOB_GASPRICE`

Gnosis chain has significantly cheaper fees than mainnet, so blob spam is a concern. Ethereum's MIN_BLOB_GASPRICE makes blob space free (1e-18 USD / blob) if usage is under the target for a sustained period of time. The same concern applies to Ethereum, but consensus is that choosing a specific value that may apply to only some market conditions and not others. Gnosis however has chosen a min gas price of 1 GWei, so a similar decision can be made here.

Setting EIP-4788 `BEACON_ROOTS_ADDRESS`

Contract deployment is currently spec'ed as https://eips.ethereum.org/EIPS/eip-4788#deployment

The beacon roots contract is deployed like any other smart contract. A special synthetic address is generated by working backwards from the desired deployment transaction:

Given this deployment style, it's impossible to re-use the same BEACON_ROOTS_ADDRESS as Ethereum mainnet. If Gnosis adopts the same deployment style, this issue is blocked by finalizing the contract's bytecode, see

• #15

How to compute the deployer address

const EthereumTx = require('ethereumjs-tx').Transaction;
const assert = require('assert');

const txData = {
  nonce: '0x00',
  gasPrice: '0xe8d4a51000',
  gasLimit: '0x3d090',
  to: null,  // contract creation
  value: '0x00',
  data: '0x60618060095f395ff33373fffffffffffffffffffffffffffffffffffffffe14604d57602036146024575f5ffd5b5f35801560495762001fff810690815414603c575f5ffd5b62001fff01545f5260205ff35b5f5ffd5b62001fff42064281555f359062001fff015500',
  v: '0x1b',
  r: '0x539',
  s: '0x1b9b6eb1f0'
};

const tx = new EthereumTx(txData, { chain: 'mainnet', hardfork: 'petersburg' });
const senderAddress = '0x' + tx.getSenderAddress().toString('hex');
assert.equal(senderAddress, '0x0B799C86a49DEeb90402691F1041aa3AF2d3C875'.toLowerCase());

Setting EIP-7514 `MAX_PER_EPOCH_CHURN_LIMIT`

Gnosis chain was started with very aggressive churn parameters. The chain size can change widely due to a very low CHURN_LIMIT_QUOTIENT of 4096. Having similar concerns to Ethereum's fast state growth, this value should be set considering the trade-off

	High churn	Low churn
Time for adversarial take-over	Low	High ✅
Max possible state size after N time	High	Low ✅
Max possible week over week growth	High ✅	Low
Expected queue times under heavy demand	Low ✅	High

Today, Gnosis chain churn limit is 27.5 validators / min, while Ethereum will have a max of 1.25 validators / min once EIP-7514 activates.