Where the two clients differ structurally in how a block is executed — not in a rule, but in the shape of the machinery. Most of it is invisible to consensus. The parts that are not are the interesting ones, and they are listed here because each was found by a block that diverged rather than by reading the spec.
Companion to the compatibility catalogue indexed in
java-compatibility.md: that catalogue is about
rules, this is about architecture.
Both clients accumulate a whole block in memory and write the trie once. This is worth stating because the layering looks so different that it is easy to assume otherwise.
| rskj | rustock | |
|---|---|---|
| per-call-frame isolation | nested Repository tracks |
revm journal checkpoints |
| per-transaction boundary | txSubTrack.commit() → cache |
none |
| block accumulation | MutableTrieCache (an in-memory map) |
EvmState from evm.finalize() |
| trie materialised | track.save(), block end |
apply_state_changes, block end |
rskj (co.rsk.core.bc.BlockExecutor):
420: Repository track = repositoryLocator.startTrackingAt(parent); // one per block
752: Repository txSubTrack = track.startTracking(); // one per transaction
787: txSubTrack.commit(); // after each transaction
916: track.save(); // once, at block endtxSubTrack.commit() merges into the block-level track, which is a
MutableTrieCache holding
Map<ByteArrayWrapper, Map<ByteArrayWrapper, Optional<byte[]>>> in memory
(MutableTrieCache.java:44). Nothing reaches the trie store until save().
rustock: revm holds one journal for the whole block; each transaction commits
into it; evm.finalize() collapses it to an EvmState, and
processor.rs calls apply_state_changes exactly once.
A REVERT therefore never touches the trie. There is nothing to roll back
at the storage layer — the reverted writes are simply absent from the
EvmState that reaches apply_state_changes. Gas burned by a reverted call
does survive, because it moves balances, and balances are state.
rustock has no per-transaction commit, and that is fine except for one consequence, which it has to manufacture.
rskj's TransactionExecutor.finalization deletes self-destructed accounts at
the end of each transaction (track.delete). A later transaction in the
same block therefore sees the address as nonexistent and re-creates a fresh
(0, 0) account merely by calling it — frontier transfer / addBalance(0)
creates the record.
revm keeps one journal for the block and wipes a destroyed account lazily, on
the next cold load, leaving sticky SelfDestructed and Touched flags. At
block end that state cannot distinguish "destroyed" from "destroyed, then
re-created by a later transaction".
rustock closes the gap in executor.rs (the loop after each transaction
commits): wipe info and storage, clear Touched, clear the local
selfdestruct/created marks. A later transaction touching the address re-marks
Touched, which apply_state_changes reads as "alive again at block end".
Found by mainnet #3,173,807. Regression tests:
executor.rs::selfdestruct_then_recreate_in_same_block— the exact shape: destroy, re-create by calling, then top up; asserts the old subtree (code, marker, storage) is gone and the fresh account has nonce 0 and only the later balance.executor.rs::selfdestruct_in_last_tx_deletes_account_entirelyexecutor.rs::selfdestruct_to_self_burns_balanceexecutor.rs::selfdestruct_recreate_via_create2_then_selfdestruct_againstate.rs::test_selfdestructed_then_recreated_account_rewritten_fresh— the same case seen fromapply_state_changes, where the account arrives bothSelfDestructedandTouched.
Some rskj writes do not correspond to any EVM operation — they are direct
addStorageBytes calls from Java. revm has no way to represent them, so
rustock carries a second channel: evm.ctx.chain_mut().raw_storage, with its
own begin_tx() per transaction, drained into markers.raw_storage at block
end and applied alongside everything else.
The case that forced it is REMASC's siblings cell —
RemascStorageProvider.saveSiblings() runs on every REMASC save() with no
guard, writing a single 0xc0 byte. The cell is created at block #1, never
changes value, and is part of the state root from then on
(quirks-frozen-bugs.md §9c).
The overlay follows the same rule as everything else: accumulated in memory, written once at block end.
RSK is Byzantium from genesis (hardfork.rs: genesis–orchid → BYZANTIUM), so
postTxState in a receipt is the 1-byte status indicator — 0x01 for success,
empty for failure — and never a 32-byte root.
This is load-bearing for §1: a pre-Byzantium chain would need the state root after every transaction, which would force a per-transaction trie materialisation on both clients. RSK never does, which is why accumulating the whole block is viable at all.
BlockProcessor::execute_block validates nothing; process_block validates
transactions root, ommers hash, gas used, state root, receipts root and logs
bloom. A tool that calls the former and compares only the state root proves the
state transition and nothing else — see
trie-segments-design.md §8 for a case where
exactly that distinction mattered.
RSKIP-144 splits a block's transactions into sublists that rskj executes in
parallel, one thread each, plus a sequential set that runs afterwards on the
main thread. The split is declared by the header's txExecutionSublistsEdges.
rustock executes every transaction in order, on one thread.
That is a performance difference and not a consensus one — but only because of a rule that is easy to miss, and that rustock did not implement until #305. The sublists must be independent, and the validator has to establish it:
- If a key belongs to a
writeMapand areadMapof another parallel sublist, then the block is considered invalid.- If a key belongs to a
writeMapand awriteMapof another parallel sublist, then the block is also invalid.
The tempting shortcut — "we execute sequentially, so we get a valid answer either way" — is wrong twice over. A sequential executor computes one of the interleavings; where sublists conflict, that interleaving is the parallel result sometimes and not others, so the two clients agree by luck. And the rule is a condition on the block, not a property a validator may assume the miner established: a block whose sublists conflict is invalid, and a node that skips the check accepts it, computes a state root nobody else reaches, and forks.
Read against read is not a collision. Only a write makes an ordering observable.
collision.rs holds a CollisionTracker keyed by sublist index — rskj keys
its ReadWrittenKeysTracker by thread id, which is the same thing said with
reference to how execution happens to be scheduled. processor.rs starts it
only for a block that actually splits, so a chain where RSKIP-144 is
unscheduled (mainnet) or active-but-unused pays nothing.
Reads come out of revm's journal after each transaction, using the
per-transaction stamp it keeps on every account and slot (transaction_id,
updated on first access, including a read —
JournalInner::load_account_mut_optional). That evidence survives a rollback:
reverting an entry restores values and flips flags but never removes the
account or the slot, and Account::mark_cold leaves transaction_id alone.
Which is what we want, because reads are never netted: the value a sublist
read determined what it computed, including whether a frame reverted at all.
Writes are the attempted ones, not the surviving ones, because that is the
deployed rule — see below. revm records a write by pushing a journal entry and
undoes it by popping that entry, so the entries are read off immediately
before every point that can revert a checkpoint: the two
frame_return_result calls in rsk_handler's run_exec_loop, and the direct
Bridge call's two revert branches in executor.rs. A mark tracks how far the
entry log has been read and comes back down with it after a revert, so each
entry is read once.
Two things the journal cannot show, each handled where it happens:
- an
SSTOREthat stores the value a cell already holds is not journalled (sstore_concrete_error:if slot.present_value != new), while rskj'sProgram.storageSaverecords it regardless. Hooked inside rustock's ownSSTOREinrsk_instructions, after the gas is spent — rskj spends gas beforestorageSave, so an out-of-gasSSTOREwrites nothing; - the Bridge's byte-array cells bypass the journal entirely (§3), so they come
from
RawStorage::tx_writes.
A write a transaction reverted cannot make parallel execution differ from
sequential execution. Each sublist runs against the parent state on an
isolated repository; detectCollision runs before any of them is merged; the
commits follow in sublist order. No sublist observes another's uncommitted
work, and a reverted write is not in its own sublist's commit either.
rskj counts it anyway — its tracker lives in MutableRepository,
startTracking() hands the same tracker to every nested repository, and a
rollback discards only the state cache. RSKIP-144 does not mention reverts at
all, so this is not a simplification the specification chose; it is where the
tracker happened to be placed.
So the rule rejects valid blocks, and we implement it, because being right is
not being compatible. collision::WriteSemantics carries both readings and
collision::write_semantics returns the deployed one. The other,
NetChanges, is complete and tested and unreachable: activating it is a
consensus change and must be gated on a fork, which is why that function takes
a block number. The proposal is in RSKIP-sublist-net-writes.md, outside this
repository.
Two addresses are excluded, because rustock writes them from inside a transaction and rskj does not:
- REMASC. rustock credits the fee beneficiary per transaction; rskj builds
every sublist executor with
postponeFeePayment = true(TransactionListExecutor), accumulating fees per sublist and settling them afterwards. Without the exclusion every sublist writes REMASC's account cell and every split block collides — which is what happened: testnet #7,690,880 onwards were all rejected until the exclusion was right. - Precompiles maintained at an activation block. rskj's
maintainPrecompiledContractStorageRootsruns on the block's repository before any sublist starts, so those writes belong to no sublist.
The sequential set is not recorded either, which is not an omission:
BlockExecutor.executeParallel calls detectCollision() before it runs,
and the sequential set is exactly where a miner puts the transactions that do
conflict.
- Reads of Bridge byte-array state are not recorded, only writes: the raw-storage overlay's read path has no hook.
- Code and storage-prefix cells are not recorded as reads. rskj reads them
in
getCode/getCodeLengthandisContract; we record only the account cell, whichgetCodeLengthreads first anyway and which is what a second sublist would collide on.
Both miss a collision rather than inventing one, which is the direction to err in: the first leaves a block accepted, the second forks the node off a chain everyone else considers valid.
Testnet is the only chain where this fires: reed810 is unscheduled on mainnet, so no mainnet header has ever carried a non-empty edges field. Of 1,020,420 canonical testnet headers above the activation height, 203,419 split — the first at #7,690,876, and the widest into two parallel sublists plus the sequential set, so the check always compares exactly one pair.
Five ranges of 301 blocks, spread from the first splitting block to the chain head, replay against rskj's own state with zero divergences and zero collisions: 1,505 blocks, of which 685 split. Re-run after the switch to attempted writes, with the same result — the stricter rule invents nothing on real blocks.
| range | blocks | of which split |
|---|---|---|
| #7,690,870–#7,691,170 | 301 | 165 |
| #7,800,000–#7,800,300 | 301 | 153 |
| #7,950,000–#7,950,300 | 301 | 137 |
| #8,050,000–#8,050,300 | 301 | 151 |
| #8,159,700–#8,160,000 | 301 | 79 |
This matters more than the unit tests do. The REMASC exclusion above was found here and nowhere else: every unit test passed while every splitting block on the chain was being rejected.