Solidity and Contract Architecture
Introduction
Solidity is used here to encode auditable state machines. The emphasis is on small interfaces, explicit transitions, accounting ownership, external-call boundaries, storage evolution, and failure behavior.
Why It Matters
Most serious contract failures are design failures expressed in valid syntax: missing states, ambiguous authority, unsafe composition, unbounded work, incorrect accounting, or upgrades that reinterpret storage.
Mental Model
A contract module owns a bounded slice of state and exposes transitions guarded by authorization, preconditions, effects, external interactions, and postconditions. Events describe outcomes but never replace state.
Questions This Branch Answers
- How is a protocol specification converted into storage and transitions?
- Where should external control enter, and how is it contained?
- When are factories, clones, libraries, inheritance, or immutability justified?
Scope
Types/data locations/errors, interfaces and composition, CEI and pull payments, layout, factories/clones/CREATE2, Signed Escrow, and Commit-Reveal Auction design.
Out of Scope
Syntax encyclopedias, copy-paste production templates, upgradeability by default, UI implementation, and claims that a library removes the need for a protocol threat model.
Dependencies
EVM execution, adversarial transactions, and basic state-machine testing.
Candidate Note Roadmap
solidity-state-machine-architecture— Turn actors, states, transitions, and forbidden edges into code structure.signed-escrow-specification— Specify deposits, approvals, disputes, timeouts, and withdrawals before coding.types-data-locations-and-errors— Choose representation and failure channels intentionally.interfaces-libraries-and-composition— Bound dependencies and make external assumptions reviewable.checks-effects-interactions-and-pull-payments— Contain external control and failed recipient behavior.storage-layout-and-namespaces— Inspect slots and plan safe evolution without collision.factories-clones-and-create2— Compare deployment patterns, initialization, and deterministic addressing.commit-reveal-auction-design— Model commitments, reveal windows, settlement, and non-reveal outcomes.
Future Project
Signed Escrow and Commit-Reveal Auction modules, each beginning as a written transition table and ending with traces, invariant tests, and a minimal client.
Initial Invariants
Terminal states cannot reopen; value is accounted exactly once; withdrawals cannot replay; timeouts move only along declared edges; auction reveal requires a matching prior commitment.
Initial Threat Model
Reentrancy, forced Ether, denial of service by recipients, timeout races, signature replay, initialization mistakes, inheritance ambiguity, storage collision, and griefing through unbounded collections.
Primary Sources
Solidity documentation, Foundry documentation, OpenZeppelin Contracts documentation, and sources curated in SOURCES.md.
Connects to: standards and signatures, testing, and governance/upgrades.