Reference · Reference
Repository map
Start from the behavior you need to understand, then follow its caller into execution, state and tests. The maintained node is the Rust 2021 crate in runtime/; runtime/src/lib.rs exposes library modules and runtime/src/bin/svm_vm.rs constructs the production node. A module export establishes availability to Rust callers, not that the running node installs every optional path.
This map is source lookup, organized by reader question and ownership boundary. For the connected design, read the system overview; for the procedure to change and validate an implementation, use the contribution guide.
Follow a reader question
| Question | Implementation starting points | Documentation |
|---|---|---|
| How does a node start, recover and shut down? | runtime/src/bin/svm_vm.rs, config_snapshot.rs | Node runtime, build/configuration |
| How does submitted work reach a block? | runtime/src/rpc/, vm/mempool.rs, vm/turbo_ingest.rs, consensus/automaton.rs | Transaction lifecycle |
| Which result becomes ordered state? | hiperf/turbo_executor.rs, consensus/reporter.rs, programs/cross_vm_tx.rs | Execution pipeline, composition |
| What survives a crash? | qmdb_state.rs, real_qmdb_state.rs, block_wal.rs, consensus/epoch_boundary.rs | Persistence, recovery workflow |
| How are validators selected and synchronized? | consensus/, programs/validator_registry.rs, rpc/validator_admin.rs | Consensus, validator lifecycle |
| How do foreign facts become useful local evidence? | runtime/src/hilsa/, runtime/crates/hilsa/src/ | HILSA, verified reads |
| What pays an external recipient? | hilsa/bridge/, its watchers/relay, contracts/evm/ | HILSA writes, asset bridge |
| What does the public client actually do? | sdk/singularity-web3/src/, sdk/singularity-cli/src/ | SDK/RPC, CLI reference |
| Which production files does deployment own? | infra/DEPLOY-CONTRACT.md, infra/environments/, infra/scripts/ | Deployments |
The node/library entrypoints and path dependencies are declared in the runtime manifest and library surface.
Execution environments share state, not every interface
| Environment | Where its contract lives |
|---|---|
| SVM/native programs | programs/, sealevel/, solana_compat.rs, BPFCC adapter/syscall modules and runtime/deps/bpfcc/ |
| EVM | runtime/src/evm/ and first-party runtime/deps/gevm/; the host boundary remains part of node execution |
| WASM | runtime/src/wasm/; check the actual linker and transaction wrapper before relying on a helper |
| Move | runtime/src/move_vm/; inspect publication/call encoding and the native table installed by the caller |
| ZK | runtime/src/zk/ plus native program and RPC dispatch |
| Bombil | runtime/src/onebook/, orderbook/ and the native adapter in hiperf/turbo_executor.rs |
Bombil is the current public name; one-book remains a Cargo dependency name and onebook remains the Rust module. docs/onebook-vm-plan.md explains the intended VM-level financial environment. Read it alongside current dispatch and engine installation, since the design's record formats and full pipeline are not automatically the implemented contract. See Bombil architecture and exact identifiers and admission.
Shared token and identity mechanisms live in token_standard/, identity_standard/ and cap/; native product protocols live under programs/. The native capabilities chapter distinguishes dispatched programs from standalone models and incomplete host-side integrations.
HILSA has a core, a node integration and destinations
runtime/crates/hilsa/ contains reusable verification, proof, root and attestation logic. runtime/src/hilsa/ connects artifacts, feeds, read views, outbox and bridge behavior to the node. runtime/src/rpc/ owns public request parsing and response behavior. Destination contracts under contracts/evm/ enforce their own thresholds, replay protection and custody semantics.
The library preserves cil as an alias for hilsa and reexports its bridge module. Older CIL paths therefore do not necessarily identify a second implementation. Check the actual module alias before following an obsolete design diagram. See the aliases.
The design and positioning files under docs/ are useful leads. In particular, HILSA universal-read/write and comparison notes explain intended jobs, but current trust, message execution and release claims require source and deployment evidence. Alternatives compares the broader interoperability landscape using current primary material.
Tests are organized by the boundary they exercise
| Location | What to expect |
|---|---|
Colocated runtime/src/** test modules | Focused invariants and failure behavior near implementation |
runtime/tests/ | Cross-module, simulation and integration scenarios |
runtime/tests/bpfcc_lib/ | Selected fixtures also included in library tests under feature gates |
runtime/fuzz/fuzz_targets/ | Local fuzz targets; not a promised GitHub Actions fuzz gate |
contracts/evm/test/ | Foundry contract verification and custody/gateway behavior |
| SDK and CLI test directories | Serialization, configuration, command behavior and mocked integration |
infra/tests/, infra test scripts | Configuration and release-policy checks |
.github/workflows/ci.yml, gpu-verify.yml, sdk-ci.yml | Which suites, features and artifacts the automation actually runs |
Some files under runtime/tests/ are compiled through lib.rs using explicit paths. A filename or directory alone does not determine its Cargo test target. Feature-gated GPU tests may be absent from a CPU-only run. See library test inclusion and validation strategy.
Tooling and ownership boundaries
scripts/eto-build wraps controlled builds; scripts/hilsa-check offers a narrower HILSA check. scripts/eto-ops delegates inventory, configuration rendering/bundling and drift auditing to the Python configuration tool. These do different jobs from testnet/run.sh, which launches a disposable local testnet and resets its temporary node directories.
infra/ includes Terraform, systemd, nginx, edge-worker and operational scripts. Presence of a template does not prove it is installed. A legacy single-host backup script and the current multi-host deployment coordinator have different service names and data paths.
runtime/deps/gevm/ is first-party source imported in-tree; it is not a Git submodule to initialize. deps/commonware-rohu-paplet/ is vendored third-party source. Keep dependency provenance and formatting boundaries straight: the repository requires plain cargo fmt, because cargo fmt --all can rewrite vendored files.
The generated openwiki/ pages and evidence index are a navigation aid. Source and tests remain authoritative; Claims/indexes/run metadata belong to OpenWiki's lifecycle. For a change, follow the contribution guide from the relevant execution boundary to its narrowest meaningful validation.