Methodology
How NOME creates reliable environments for onchain development.
NOME exists to make one thing true: what you observe in an environment is what you should expect from the chain. This document describes the principles that make that possible, and the boundaries where they stop.
Environment Design
An environment is defined declaratively. The specification names every account, asset, contract, and network parameter the environment contains. There is no implicit state: if it is not in the specification or produced by a recorded run, it does not exist.
Materialization is deterministic. Addresses are derived from the environment seed, reference contracts deploy to fixed locations, and the genesis snapshot of two environments created from the same specification is byte-identical.
Isolation boundary
Environments do not share state, execution, or network access. An environment cannot observe another environment, and nothing executed inside an environment is broadcast to any public network. Importing state from a public network is a read-only, point-in-time operation.
State & Determinism
State in NOME is a first-class object. A snapshot is a content-addressed capture of every balance, nonce, code blob, and storage slot in an environment. Two snapshots with the same hash are identical; a differing hash means the state differs.
Execution is deterministic with respect to inputs. Given a snapshot and an ordered list of operations, NOME produces the same resulting snapshot every time. Sources of nondeterminism that exist on live networks — mempool ordering, timestamp drift, validator behavior — are replaced by explicit parameters.
Same snapshot. Same operations. Same state root.
This guarantee is enforced rather than assumed. Every run records its inputs and outputs, and re-executing a run against its source snapshot is a first-class operation whose result is compared against the original.
nome run replay run_0419 --verify
# replaying run_0419 from snap_0014 … ok
# result snap_0015 (0x9c1e…a41f)
# expected snap_0015 (0x9c1e…a41f)
# verified: identicalScenario Construction
A scenario is a versioned description of a situation: a sequence of operations, changes to network conditions, and assertions about the result. Scenarios are written once and replayed against any environment that satisfies their requirements.
Good scenarios share a few properties:
- Explicit preconditions. A scenario declares which assets and contracts it needs, so it fails early against an incompatible environment rather than producing a misleading result.
- Small, ordered steps. Each step is a single operation with an observable effect, so a failing assertion points to a specific cause.
- Assertions on outcomes, not mechanisms. Assert on state, events, and reverts — the things a user or integrator would observe — rather than on internal call paths that may legitimately change.
name: permission-change
version: 2
requires:
contracts: [Vault]
steps:
- call: { to: Vault, fn: setOperator, from: deployer, args: [relayer] }
- call: { to: Vault, fn: sweep, from: relayer }
- call: { to: Vault, fn: sweep, from: user_1 }
expect: { revert: Unauthorized }
- assert:
event: OperatorChanged(deployer, relayer)
state: Vault.operator == relayerExecution & Observation
Every execution is a run. A run starts from a known snapshot, applies operations in order, and produces a new snapshot together with a complete record of what happened in between: the structured diff, the decoded events, and the call trace of every operation.
Observation is designed to be lossless. Undecoded data is retained alongside every decoded view. Reverts are recorded with the same fidelity as successes. Gas accounting follows the modeled network's rules, so numbers observed in an environment are the numbers to expect in production under the same conditions.
What a run records
| Artifact | Contents |
|---|---|
| inputs | Source snapshot, ordered operations, network parameters in effect. |
| diff | Every storage write, balance change, nonce increment, and code change. |
| events | All logs, indexed and decoded where an ABI is registered. |
| trace | Call tree with inputs, outputs, gas, and revert reasons per frame. |
| result | Resulting snapshot hash and run status. |
Reset & Reproducibility
Reset is exact. Returning an environment to a snapshot discards every change made after it, regardless of how many runs occurred. Because snapshots are immutable and content-addressed, a reset environment is indistinguishable from one that never left the snapshot.
Run records survive reset. This separates two things that are often conflated: the current state of an environment, and the history of what has been tried against it. You can reset freely and still compare every past run.
Reproducibility across environments
Reproducibility is not limited to a single environment. A specification plus a scenario is sufficient to reproduce a result on any workspace, in CI, or on a colleague's machine. Sharing a result means sharing those two documents — not a running instance.
Limitations
A controlled environment is a model. It is faithful where it matters for application correctness and deliberately simplified elsewhere. The boundaries worth knowing:
- Consensus and networking are parameterized, not simulated. Block time, base fee, and reorg depth are inputs you set. NOME does not model validator economics, peer-to-peer propagation, or MEV behavior.
- Imported state is a point-in-time copy. State imported from a public network reflects that block. It does not track subsequent changes.
- External systems are outside the boundary. Oracles, bridges, and off-chain services must be represented explicitly inside the environment if a scenario depends on them.
- A passing scenario is evidence, not proof. NOME shows how a system behaves under the conditions you described. It cannot show behavior under conditions you did not.
We publish these limits so that results from NOME are interpreted correctly. The most reliable development practice is to treat the environment as the place where assumptions are made explicit — and production as the place they are confirmed.
Put the methodology to work.