aristo: fork support via layers/txframes (#2960)

* aristo: fork support via layers/txframes

This change reorganises how the database is accessed: instead holding a
"current frame" in the database object, a dag of frames is created based
on the "base frame" held in `AristoDbRef` and all database access
happens through this frame, which can be thought of as a consistent
point-in-time snapshot of the database based on a particular fork of the
chain.

In the code, "frame", "transaction" and "layer" is used to denote more
or less the same thing: a dag of stacked changes backed by the on-disk
database.

Although this is not a requirement, in practice each frame holds the
change set of a single block - as such, the frame and its ancestors
leading up to the on-disk state represents the state of the database
after that block has been applied.

"committing" means merging the changes to its parent frame so that the
difference between them is lost and only the cumulative changes remain -
this facility enables frames to be combined arbitrarily wherever they
are in the dag.

In particular, it becomes possible to consolidate a set of changes near
the base of the dag and commit those to disk without having to re-do the
in-memory frames built on top of them - this is useful for "flattening"
a set of changes during a base update and sending those to storage
without having to perform a block replay on top.

Looking at abstractions, a side effect of this change is that the KVT
and Aristo are brought closer together by considering them to be part of
the "same" atomic transaction set - the way the code gets organised,
applying a block and saving it to the kvt happens in the same "logical"
frame - therefore, discarding the frame discards both the aristo and kvt
changes at the same time - likewise, they are persisted to disk together
- this makes reasoning about the database somewhat easier but has the
downside of increased memory usage, something that perhaps will need
addressing in the future.

Because the code reasons more strictly about frames and the state of the
persisted database, it also makes it more visible where ForkedChain
should be used and where it is still missing - in particular, frames
represent a single branch of history while forkedchain manages multiple
parallel forks - user-facing services such as the RPC should use the
latter, ie until it has been finalized, a getBlock request should
consider all forks and not just the blocks in the canonical head branch.

Another advantage of this approach is that `AristoDbRef` conceptually
becomes more simple - removing its tracking of the "current" transaction
stack simplifies reasoning about what can go wrong since this state now
has to be passed around in the form of `AristoTxRef` - as such, many of
the tests and facilities in the code that were dealing with "stack
inconsistency" are now structurally prevented from happening. The test
suite will need significant refactoring after this change.

Once this change has been merged, there are several follow-ups to do:

* there's no mechanism for keeping frames up to date as they get
committed or rolled back - TODO
* naming is confused - many names for the same thing for legacy reason
* forkedchain support is still missing in lots of code
* clean up redundant logic based on previous designs - in particular the
debug and introspection code no longer makes sense
* the way change sets are stored will probably need revisiting - because
it's a stack of changes where each frame must be interrogated to find an
on-disk value, with a base distance of 128 we'll at minimum have to
perform 128 frame lookups for *every* database interaction - regardless,
the "dag-like" nature will stay
* dispose and commit are poorly defined and perhaps redundant - in
theory, one could simply let the GC collect abandoned frames etc, though
it's likely an explicit mechanism will remain useful, so they stay for
now

More about the changes:

* `AristoDbRef` gains a `txRef` field (todo: rename) that "more or less"
corresponds to the old `balancer` field
* `AristoDbRef.stack` is gone - instead, there's a chain of
`AristoTxRef` objects that hold their respective "layer" which has the
actual changes
* No more reasoning about "top" and "stack" - instead, each
`AristoTxRef` can be a "head" that "more or less" corresponds to the old
single-history `top` notion and its stack
* `level` still represents "distance to base" - it's computed from the
parent chain instead of being stored
* one has to be careful not to use frames where forkedchain was intended
- layers are only for a single branch of history!

* fix layer vtop after rollback

* engine fix

* Fix test_txpool

* Fix test_rpc

* Fix copyright year

* fix simulator

* Fix copyright year

* Fix copyright year

* Fix tracer

* Fix infinite recursion bug

* Remove aristo and kvt empty files

* Fic copyright year

* Fix fc chain_kvt

* ForkedChain refactoring

* Fix merge master conflict

* Fix copyright year

* Reparent txFrame

* Fix test

* Fix txFrame reparent again

* Cleanup and fix test

* UpdateBase bugfix and fix test

* Fixe newPayload bug discovered by hive

* Fix engine api fcu

* Clean up call template, chain_kvt, andn txguid

* Fix copyright year

* work around base block loading issue

* Add test

* Fix updateHead bug

* Fix updateBase bug

* Change func commitBase to proc commitBase

* Touch up and fix debug mode crash

---------

Co-authored-by: jangko <[email protected]>

hive_integration/nodocker/consensus/consensus_sim.nim

@@ -27,7 +27,7 @@ proc processChainData(cd: ChainData, taskPool: Taskpool): TestStatus =
       cd.params
     )
 
-  let c = newForkedChain(com, com.genesisHeader)
+  let c = ForkedChainRef.init(com)
 
   for bytes in cd.blocksRlp:
     # ignore return value here

hive_integration/nodocker/engine/node.nim

@@ -1,5 +1,5 @@
 # Nimbus
-# Copyright (c) 2024 Status Research & Development GmbH
+# Copyright (c) 2024-2025 Status Research & Development GmbH
 # Licensed under either of
 #  * Apache License, version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
 #    http://www.apache.org/licenses/LICENSE-2.0)
@@ -42,8 +42,6 @@ proc processBlock(
   ## implementations (but can be savely removed, as well.)
   ## variant of `processBlock()` where the `header` argument is explicitely set.
   template header: Header = blk.header
-  var dbTx = vmState.com.db.ctx.txFrameBegin()
-  defer: dbTx.dispose()
 
   let com = vmState.com
   if com.daoForkSupport and
@@ -61,61 +59,55 @@ proc processBlock(
       vmState.ledger.addBalance(withdrawal.address, withdrawal.weiAmount)
 
   if header.ommersHash != EMPTY_UNCLE_HASH:
-    discard com.db.persistUncles(blk.uncles)
+    discard vmState.ledger.txFrame.persistUncles(blk.uncles)
 
   # EIP-3675: no reward for miner in POA/POS
-  if com.proofOfStake(header):
+  if com.proofOfStake(header, vmState.ledger.txFrame):
     vmState.calculateReward(header, blk.uncles)
 
   vmState.mutateLedger:
     let clearEmptyAccount = com.isSpuriousOrLater(header.number)
     db.persist(clearEmptyAccount)
 
-  dbTx.commit()
+  vmState.ledger.txFrame.commit()
 
   ok()
 
-proc getVmState(c: ChainRef, header: Header):
-                 Result[BaseVMState, void] =
-  let vmState = BaseVMState()
-  if not vmState.init(header, c.com, storeSlotHash = false):
-    debug "Cannot initialise VmState",
-      number = header.number
-    return err()
-
+proc getVmState(c: ChainRef, header: Header, txFrame: CoreDbTxRef):
+                 Result[BaseVMState, string] =
+  let
+    parent  = ?txFrame.getBlockHeader(header.parentHash)
+    vmState = BaseVMState()
+  vmState.init(parent, header, c.com, txFrame, storeSlotHash = false)
   return ok(vmState)
 
 # A stripped down version of persistBlocks without validation
 # intended to accepts invalid block
 proc setBlock*(c: ChainRef; blk: Block): Result[void, string] =
   template header: Header = blk.header
-  let dbTx = c.db.ctx.txFrameBegin()
-  defer: dbTx.dispose()
+  let txFrame = c.db.ctx.txFrameBegin(nil)
+  defer: txFrame.dispose()
 
   # Needed for figuring out whether KVT cleanup is due (see at the end)
   let
-    vmState = c.getVmState(header).valueOr:
-      return err("no vmstate")
+    vmState = ? c.getVmState(header, txFrame)
   ? vmState.processBlock(blk)
 
-  ? c.db.persistHeaderAndSetHead(header, c.com.startOfHistory)
+  ? txFrame.persistHeaderAndSetHead(header, c.com.startOfHistory)
 
-  c.db.persistTransactions(header.number, header.txRoot, blk.transactions)
-  c.db.persistReceipts(header.receiptsRoot, vmState.receipts)
+  txFrame.persistTransactions(header.number, header.txRoot, blk.transactions)
+  txFrame.persistReceipts(header.receiptsRoot, vmState.receipts)
 
   if blk.withdrawals.isSome:
-    c.db.persistWithdrawals(header.withdrawalsRoot.get, blk.withdrawals.get)
+    txFrame.persistWithdrawals(header.withdrawalsRoot.get, blk.withdrawals.get)
 
   # update currentBlock *after* we persist it
   # so the rpc return consistent result
   # between eth_blockNumber and eth_syncing
   c.com.syncCurrent = header.number
 
-  dbTx.commit()
+  txFrame.commit()
 
-  # The `c.db.persistent()` call is ignored by the legacy DB which
-  # automatically saves persistently when reaching the zero level transaction.
-  #
   # For the `Aristo` database, this code position is only reached if the
   # the parent state of the first block (as registered in `headers[0]`) was
   # the canonical state before updating. So this state will be saved with

hive_integration/nodocker/pyspec/test_env.nim

@@ -1,5 +1,5 @@
 # Nimbus
-# Copyright (c) 2023-2024 Status Research & Development GmbH
+# Copyright (c) 2023-2025 Status Research & Development GmbH
 # Licensed under either of
 #  * Apache License, version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
 #    http://www.apache.org/licenses/LICENSE-2.0)
@@ -37,9 +37,9 @@ proc genesisHeader(node: JsonNode): Header =
 proc initializeDb(memDB: CoreDbRef, node: JsonNode): Hash32 =
   let
     genesisHeader = node.genesisHeader
-    ledger = LedgerRef.init(memDB)
+    ledger = LedgerRef.init(memDB.baseTxFrame())
 
-  memDB.persistHeaderAndSetHead(genesisHeader).expect("persistHeader no error")
+  ledger.txFrame.persistHeaderAndSetHead(genesisHeader).expect("persistHeader no error")
   setupLedger(node["pre"], ledger)
   ledger.persist()
   doAssert ledger.getStateRoot == genesisHeader.stateRoot

nimbus/beacon/api_handler/api_exchangeconf.nim

@@ -1,5 +1,5 @@
 # Nimbus
-# Copyright (c) 2023-2024 Status Research & Development GmbH
+# Copyright (c) 2023-2025 Status Research & Development GmbH
 # Licensed under either of
 #  * Apache License, version 2.0, ([LICENSE-APACHE](LICENSE-APACHE))
 #  * MIT license ([LICENSE-MIT](LICENSE-MIT))
@@ -43,15 +43,15 @@ proc exchangeConf*(ben: BeaconEngineRef,
     terminalBlockHash   = conf.terminalBlockHash
 
   if terminalBlockHash != default(Hash32):
-    let headerHash = db.getBlockHash(terminalBlockNumber).valueOr:
+    let headerHash = db.baseTxFrame().getBlockHash(terminalBlockNumber).valueOr:
       raise newException(ValueError, "cannot get terminal block hash, number $1, msg: $2" %
         [$terminalBlockNumber, error])
 
     if terminalBlockHash != headerHash:
       raise newException(ValueError, "invalid terminal block hash, got $1 want $2" %
         [$terminalBlockHash, $headerHash])
 
-    let header = db.getBlockHeader(headerHash).valueOr:
+    let header = db.baseTxFrame().getBlockHeader(headerHash).valueOr:
       raise newException(ValueError, "cannot get terminal block header, hash $1, msg: $2" %
         [$terminalBlockHash, error])
 

nimbus/beacon/api_handler/api_forkchoice.nim

@@ -76,7 +76,7 @@ proc forkchoiceUpdated*(ben: BeaconEngineRef,
                              ForkchoiceUpdatedResponse =
   let
     com   = ben.com
-    db    = com.db
+    txFrame = ben.chain.latestTxFrame()
     chain = ben.chain
     blockHash = update.headBlockHash
 
@@ -127,8 +127,8 @@ proc forkchoiceUpdated*(ben: BeaconEngineRef,
     let blockNumber = header.number
     if header.difficulty > 0.u256 or blockNumber ==  0'u64:
       let
-        td  = db.getScore(blockHash)
-        ptd = db.getScore(header.parentHash)
+        td  = txFrame.getScore(blockHash)
+        ptd = txFrame.getScore(header.parentHash)
         ttd = com.ttd.get(high(UInt256))
 
       if td.isNone or (blockNumber > 0'u64 and ptd.isNone):
@@ -162,21 +162,22 @@ proc forkchoiceUpdated*(ben: BeaconEngineRef,
 
   # If the beacon client also advertised a finalized block, mark the local
   # chain final and completely in PoS mode.
+  let baseTxFrame = ben.chain.baseTxFrame
   let finalizedBlockHash = update.finalizedBlockHash
   if finalizedBlockHash != default(Hash32):
     if not ben.chain.isCanonical(finalizedBlockHash):
       warn "Final block not in canonical chain",
         hash=finalizedBlockHash.short
       raise invalidForkChoiceState("finalized block not canonical")
-    db.finalizedHeaderHash(finalizedBlockHash)
+    baseTxFrame.finalizedHeaderHash(finalizedBlockHash)
 
   let safeBlockHash = update.safeBlockHash
   if safeBlockHash != default(Hash32):
     if not ben.chain.isCanonical(safeBlockHash):
       warn "Safe block not in canonical chain",
         hash=safeBlockHash.short
       raise invalidForkChoiceState("safe head not canonical")
-    db.safeHeaderHash(safeBlockHash)
+    baseTxFrame.safeHeaderHash(safeBlockHash)
 
   chain.forkChoice(blockHash, finalizedBlockHash).isOkOr:
     return invalidFCU(error, chain, header)

nimbus/beacon/api_handler/api_newpayload.nim

@@ -137,7 +137,7 @@ proc newPayload*(ben: BeaconEngineRef,
 
   let
     com = ben.com
-    db  = com.db
+    txFrame = ben.chain.latestTxFrame()
     timestamp = ethTime payload.timestamp
     version = payload.version
     requestsHash = calcRequestsHash(executionRequests)
@@ -185,9 +185,9 @@ proc newPayload*(ben: BeaconEngineRef,
   let ttd = com.ttd.get(high(UInt256))
 
   if version == Version.V1:
-    let ptd  = db.getScore(header.parentHash).valueOr:
+    let ptd  = txFrame.getScore(header.parentHash).valueOr:
       0.u256
-    let gptd  = db.getScore(parent.parentHash)
+    let gptd  = txFrame.getScore(parent.parentHash)
     if ptd < ttd:
       warn "Ignoring pre-merge payload",
         number = header.number, hash = blockHash.short, ptd, ttd
@@ -216,7 +216,7 @@ proc newPayload*(ben: BeaconEngineRef,
     warn "State not available, ignoring new payload",
       hash   = blockHash,
       number = header.number
-    let blockHash = latestValidHash(db, parent, ttd)
+    let blockHash = latestValidHash(txFrame, parent, ttd)
     return acceptedStatus(blockHash)
 
   trace "Inserting block without sethead",
@@ -229,7 +229,7 @@ proc newPayload*(ben: BeaconEngineRef,
       parent = header.parentHash.short,
       error = vres.error()
     ben.setInvalidAncestor(header, blockHash)
-    let blockHash = latestValidHash(db, parent, ttd)
+    let blockHash = latestValidHash(txFrame, parent, ttd)
     return invalidStatus(blockHash, vres.error())
 
   ben.txPool.removeNewBlockTxs(blk, Opt.some(blockHash))

nimbus/beacon/api_handler/api_utils.nim

@@ -1,5 +1,5 @@
 # Nimbus
-# Copyright (c) 2022-2024 Status Research & Development GmbH
+# Copyright (c) 2022-2025 Status Research & Development GmbH
 # Licensed under either of
 #  * Apache License, version 2.0, ([LICENSE-APACHE](LICENSE-APACHE))
 #  * MIT license ([LICENSE-MIT](LICENSE-MIT))
@@ -172,12 +172,13 @@ proc tooLargeRequest*(msg: string): ref InvalidRequest =
     msg: msg
   )
 
-proc latestValidHash*(db: CoreDbRef,
+proc latestValidHash*(txFrame: CoreDbTxRef,
                       parent: Header,
                       ttd: DifficultyInt): Hash32 =
   if parent.isGenesis:
     return default(Hash32)
-  let ptd = db.getScore(parent.parentHash).valueOr(0.u256)
+  # TODO shouldn't this be in forkedchainref?
+  let ptd = txFrame.getScore(parent.parentHash).valueOr(0.u256)
   if ptd >= ttd:
     parent.blockHash
   else:
@@ -192,6 +193,6 @@ proc invalidFCU*(validationError: string,
     return invalidFCU(validationError)
 
   let blockHash =
-    latestValidHash(chain.db, parent, chain.com.ttd.get(high(UInt256)))
+    latestValidHash(chain.latestTxFrame, parent, chain.com.ttd.get(high(UInt256)))
 
   invalidFCU(validationError, blockHash)

nimbus/common/chain_config_hash.nim

@@ -66,11 +66,6 @@ func update[T: ref](ctx: var sha256, val: T) =
   for f in fields(val[]):
     ctx.update(f)
 
-func update(ctx: var sha256, list: openArray[Opt[BlobSchedule]]) =
-  mixin update
-  for val in list:
-    ctx.update(val)
-
 # ------------------------------------------------------------------------------
 # Public functions
 # ------------------------------------------------------------------------------

nimbus/common/common.nim

@@ -131,10 +131,10 @@ func daoCheck(conf: ChainConfig) =
     conf.daoForkBlock = conf.homesteadBlock
 
 proc initializeDb(com: CommonRef) =
-  let kvt = com.db.ctx.getKvt()
-  proc contains(kvt: CoreDbKvtRef; key: openArray[byte]): bool =
-    kvt.hasKeyRc(key).expect "valid bool"
-  if canonicalHeadHashKey().toOpenArray notin kvt:
+  let txFrame = com.db.baseTxFrame()
+  proc contains(txFrame: CoreDbTxRef; key: openArray[byte]): bool =
+    txFrame.hasKeyRc(key).expect "valid bool"
+  if canonicalHeadHashKey().toOpenArray notin txFrame:
     info "Writing genesis to DB",
       blockHash = com.genesisHeader.rlpHash,
       stateRoot = com.genesisHeader.stateRoot,
@@ -144,23 +144,23 @@ proc initializeDb(com: CommonRef) =
       nonce = com.genesisHeader.nonce
     doAssert(com.genesisHeader.number == 0.BlockNumber,
       "can't commit genesis block with number > 0")
-    com.db.persistHeaderAndSetHead(com.genesisHeader,
+    txFrame.persistHeaderAndSetHead(com.genesisHeader,
       startOfHistory=com.genesisHeader.parentHash).
       expect("can persist genesis header")
-    doAssert(canonicalHeadHashKey().toOpenArray in kvt)
+    doAssert(canonicalHeadHashKey().toOpenArray in txFrame)
 
   # The database must at least contain the base and head pointers - the base
   # is implicitly considered finalized
   let
-    baseNum = com.db.getSavedStateBlockNumber()
-    base = com.db.getBlockHeader(baseNum).valueOr:
+    baseNum = txFrame.getSavedStateBlockNumber()
+    base = txFrame.getBlockHeader(baseNum).valueOr:
       fatal "Cannot load base block header",
         baseNum, err = error
       quit 1
-    finalized = com.db.finalizedHeader().valueOr:
+    finalized = txFrame.finalizedHeader().valueOr:
       debug "No finalized block stored in database, reverting to base"
       base
-    head = com.db.getCanonicalHead().valueOr:
+    head = txFrame.getCanonicalHead().valueOr:
       fatal "Cannot load canonical block header",
         err = error
       quit 1
@@ -201,10 +201,12 @@ proc init(com         : CommonRef,
         time: Opt.some(genesis.timestamp)
       )
       fork = toHardFork(com.forkTransitionTable, forkDeterminer)
+      txFrame = db.baseTxFrame()
 
     # Must not overwrite the global state on the single state DB
-    com.genesisHeader = db.getBlockHeader(0.BlockNumber).valueOr:
-      toGenesisHeader(genesis, fork, com.db)
+
+    com.genesisHeader = txFrame.getBlockHeader(0.BlockNumber).valueOr:
+      toGenesisHeader(genesis, fork, txFrame)
 
     com.setForkId(com.genesisHeader)
 
@@ -213,13 +215,13 @@ proc init(com         : CommonRef,
 
   com.initializeDb()
 
-proc isBlockAfterTtd(com: CommonRef, header: Header): bool =
+proc isBlockAfterTtd(com: CommonRef, header: Header, txFrame: CoreDbTxRef): bool =
   if com.config.terminalTotalDifficulty.isNone:
     return false
 
   let
     ttd = com.config.terminalTotalDifficulty.get()
-    ptd = com.db.getScore(header.parentHash).valueOr:
+    ptd = txFrame.getScore(header.parentHash).valueOr:
       return false
     td  = ptd + header.difficulty
   ptd >= ttd and td >= ttd
@@ -331,15 +333,15 @@ func isCancunOrLater*(com: CommonRef, t: EthTime): bool =
 func isPragueOrLater*(com: CommonRef, t: EthTime): bool =
   com.config.pragueTime.isSome and t >= com.config.pragueTime.get
 
-proc proofOfStake*(com: CommonRef, header: Header): bool =
+proc proofOfStake*(com: CommonRef, header: Header, txFrame: CoreDbTxRef): bool =
   if com.config.posBlock.isSome:
     # see comments of posBlock in common/hardforks.nim
     header.number >= com.config.posBlock.get
   elif com.config.mergeNetsplitBlock.isSome:
     header.number >= com.config.mergeNetsplitBlock.get
   else:
     # This costly check is only executed from test suite
-    com.isBlockAfterTtd(header)
+    com.isBlockAfterTtd(header, txFrame)
 
 func depositContractAddress*(com: CommonRef): Address =
   com.config.depositContractAddress.get(default(Address))