docs(evm): explain how the contracts process a transaction - #2181
Open
atharrva01 wants to merge 5 commits into
Open
docs(evm): explain how the contracts process a transaction#2181atharrva01 wants to merge 5 commits into
atharrva01 wants to merge 5 commits into
Conversation
adecaro
force-pushed
the
feature/evm-network-driver
branch
from
August 12, 2026 13:15
90020d1 to
a68d31d
Compare
The implementation guide described the contracts as they were sketched, not as they were built. It named an entry point that does not exist, emitted an event that does not exist, and showed one contract doing work that is split across two. Replaces that with a walkthrough written for somebody meeting the contracts for the first time. It opens with the thing that confuses newcomers most, that the chain validates nothing and verifies no proofs, then covers the StateDelta field by field, the three contracts and why they are separate, the sequence of one transaction, and the checks in the order they run. Failures are a table rather than a diagram. Thirteen errors, what each means and what usually causes it, because somebody holding a reverted receipt wants to look up a name, not trace a flowchart. Design section 3 gains a pointer to it, per rule R5. Signed-off-by: atharrva01 <atharvaborade568@gmail.com>
Says which of the six sources actually reach an address, then walks the deployment phase and the processing phase separately. Clones is production code used by the factory, not test scaffolding, so say that too. Also corrects the processing picture: the clone delegatecalls the implementation, so three addresses take part rather than two, and StateCommitted is emitted at the clone's address, which is what the finality layer filters eth_getLogs on. Signed-off-by: atharrva01 <atharvaborade568@gmail.com>
atharrva01
force-pushed
the
evm-contract-flow-docs
branch
from
August 12, 2026 13:47
3214768 to
1e0337c
Compare
The initiator no longer builds a StateDelta (LFDT-Panurus#2229): only the endorser's DeltaFactory does, and that is where the aligned metadata lists actually come from. "The driver" was accurate before that change and misleading after it. Signed-off-by: atharrva01 <atharvaborade568@gmail.com>
Contributor
Author
|
One line here (the |
The v0.17.0 upgrade updated the tracked modules and missed this one, so nothing under x/token/services/network/evm builds until go.mod is tidy. Signed-off-by: atharrva01 <atharvaborade568@gmail.com>
LFDT-Panurus#2180 enabled containedctx and fixed the ttx occurrence. The evm module is a separate Go module and was not linted in that pass, so make lint has been failing on it since. Neither field can be dropped. Ledger.ctx exists because driver.GetStateFnc passes no context to GetState, and fakeContext.ctx exists because it implements view.Context, whose Context() method has to return one. Signed-off-by: atharrva01 <atharvaborade568@gmail.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The implementation guide described the contracts as they were sketched rather than as they were built. It named an entry point that does not exist (
applyStateUpdate), emitted an event that does not exist (StateUpdateEvent), and drew one contract doing work that is actually split across two.This replaces that with a walkthrough aimed at somebody meeting the contracts for the first time:
StateDelta, which the guide never showed even though every diagram referred to itcontracts/src, and which of them actually reach an addressFailures are a table instead of a diagram: thirteen errors, what each means and what usually causes it. Somebody holding a reverted receipt wants to look up a name, not trace a flowchart.
The phase split came out of Angelo's question on which contracts are involved in processing versus deployment, and whether
Clonesis only there for the tests. It is not:TokenStateFactory.createcalls it for every clone.Writing that up caught two things the first draft had wrong. The clone is an EIP-1167 proxy, so it
delegatecalls the implementation on every call and three addresses take part in processing rather than two. AndStateCommittedis emitted at the clone's address, which is the address the finality layer filterseth_getLogson.Design section 3 gets a pointer to it, per rule R5.
The diffs show mermaid as source, so the diagrams are easier to judge rendered:
https://github.com/atharrva01/panurus/blob/evm-contract-flow-docs/docs/services/network-ethereum.md#how-the-contracts-interact