Perna/solidity step

[mpernambuco]

New binary step-log anatomy

A step log is a sparse Merkle witness of a state transition (any number of steps, or a single operation): only the touched parts of the state tree, enough to recompute the root before and after.

• Page = a 4 KiB leaf, carries the full pre-write data. e.g. p1 = uarch shadow state, p2 = uarch RAM
• Node = a subtree, carries only hash_before + hash_after (no data) — witnesses a bulk write. e.g. n1 = cmio rx buffer
• Sibling = a single hash for an untouched subtree, supplied so the root can still be folded
• Node sources: reset_uarch → uarch-state subtree (hash_after = pristine); send_cmio_response → rx-buffer subtree
• Roots: pages' pre-data + nodes' hash_before (+ siblings) → root before; mutated pages + nodes' hash_after (+ siblings) → root after
• Soundness: every node must be consumed by a real write

Wire format (header + page/node/sibling entries) is specified in src/step-log.hpp.

Cost of verifying one uarch cycle in Solidity

New binary log vs the old access-log verifier — all uarch cycles of the rv64ui-uarch-add test program measured in both formats:

                  old access-log   new binary log   delta
exec gas, worst   1.16M            1.08M            -7%
exec gas, avg     1.04M            0.90M            -14%
calldata          ~15 KB           10 KB            -32%

Cheaper to run and a third less calldata — cheaper on L1, much more so on L2.

This is one uarch cycle per log. A single log can hold many cycles, which spreads its fixed decode cost across all of them — so per-cycle cost falls as the log grows. The old per-access format can't batch like this.

CLI: cartesi-machine.lua

New / reshaped options that produce binary step logs

• --log-step-uarch=<uarch-cycle-count>,<filename>[,pretty[=<out>]]
  Log <uarch-cycle-count> microarchitecture cycles to a binary step log (was a single fixed micro-step). Logging stops early at the uarch halt, so a count at or above the per-mcycle budget records one whole mcycle. Append ,pretty to also emit a human-readable printout to stderr, or ,pretty=<out> to write it to a file.

• --log-reset-uarch=<filename>
  Reset the microarchitecture state and write a binary step log.

• --log-send-cmio-response=reason:<n>,filename:<path>,(file:<path>|hex:<0x…>|str:<text>)
  Send a CMIO response into the rx buffer and write a binary step log. Response bytes come from exactly one of file: / hex: / str:. Expects the machine yielded (iflags.Y == 1); otherwise the logged transition is a no-op.