AZ-012 — Reference Node Architecture v1

Status

Acest document definește arhitectura nodului de referință pentru ATLAS ZERO.

Până aici, suitele AZ-001 până la AZ-011 au fixat:

conceptul protocolului,
obiectele canonice,
regulile de validare,
consensul,
BVM,
witness/proof,
economia,
agenții,
guvernanța,
modelul de securitate,
conformitatea.

AZ-012 răspunde la întrebarea practică: cum arată un nod real care implementează toate acestea fără amestec de responsabilități și fără puncte ascunse de divergență?

Scopul lui este să definească:

componentele nodului;
frontierele dintre ele;
fluxurile de date;
stările locale și cele consensuale;
interfețele interne critice;
locurile unde se aplică determinism, safe mode și recovery.

Acest document se bazează pe:

AZ-002 până la AZ-011.

Termeni:

MUST = obligatoriu
MUST NOT = interzis
SHOULD = recomandat puternic
MAY = opțional

1. Obiectiv

AZ-012 răspunde la 10 întrebări de arhitectură:

Care sunt subsistemele unui nod ATLAS ZERO?
Cum comunică ele fără a rupe determinismul?
Ce date sunt consensuale și ce date sunt locale?
Cum intră tranzacțiile în nod?
Cum sunt validate, ordonate și executate?
Cum se compun consensul, state engine-ul și BVM?
Cum se integrează witness/proof, economie și agenți?
Cum se activează upgrade-urile și parametrii noi?
Cum se tratează safe mode, halt și recovery în nod?
Cum se construiește un nod care poate fi auditat și testat?

2. Principii de arhitectură

2.1 Deterministic core, nondeterministic shell

Nodul MUST separa clar:

un core determinist care influențează consensul;
un shell operațional care poate fi flexibil, dar nu poate schimba semantic rezultatul.

2.2 Explicit boundaries

Orice frontieră dintre:

networking,
mempool,
validation,
state transition,
consensus,
BVM,
governance activation MUST fi clară și auditable.

2.3 No hidden coupling

Subsistemele MUST NOT depinde de:

ordine accidentală de thread scheduling;
cache-uri secrete;
call-uri externe pentru verdictul consensual;
UI/explorer assumptions.

2.4 Replayable execution

Orice verdict consensual SHOULD putea fi reconstruit din:

obiecte canonice;
state fixtures;
parameter state;
code hashes;
notarizations; fără acces la stări locale opace.

2.5 Safe degradation

Nodul SHOULD putea intra în:

degraded mode,
safe mode,
recovery mode, fără a inventa semantici noi.

3. Node role model

3.1 Un nod poate rula unul sau mai multe roluri:

full validation node
proposer node
verifier node
notary node
light verification node
observer/indexer adjunct

3.2 Same binary, different enabled roles

Este recomandat ca o implementare de referință să poată rula mai multe roluri prin configurație, dar MUST păstra separarea logică a responsabilităților.

3.3 Consensus-critical vs optional services

Nodul MUST distinge între:

consensus-critical services
support services
observability/indexing services

O cădere într-un serviciu suport MUST NOT altera verdictul de consens.

4. High-level component map

Arhitectura de referință SHOULD conține cel puțin următoarele componente:

P2P Network Layer
Ingress / Admission Layer
Object Store
Canonical Decoder & Hash Engine
Policy Engine
Validation Engine
State Engine
BVM Runtime Subsystem
Witness / Proof Subsystem
Economic Engine
Mempool / Candidate Pool
Front Builder
Consensus Engine (ENDC)
Finality / Notarization Engine
Governance Activation Engine
Agent Control Hooks
Telemetry / Audit Log
Recovery / Safe Mode Controller
API / RPC Layer
Snapshot / Persistence Layer

5. Consensus-critical boundary

5.1 Components inside consensus-critical boundary

Aceste subsisteme MUST fi tratate ca parte din „adevărul protocolului”:

canonical decoding
hash derivation
policy evaluation
tx validation
state transition logic
BVM execution semantics
witness/proof validation semantics
fee/rent/slash calculations
front compatibility and scoring
notarization validation
governance activation rules care schimbă parametrii activi

5.2 Components outside but adjacent

Acestea nu sunt direct consensuale, dar influențează operarea:

peer scoring
mempool eviction heuristics locale
telemetry aggregation
dashboarding
historical indexing
tracing
admin tooling

5.3 Rule

Orice componentă din afara boundary-ului MUST NOT schimba:

accept/reject consensus verdict,
state root,
effect digest,
front selection result,
activation epoch effect.

6. P2P Network Layer

6.1 Responsabilități

peer discovery
connection management
transport security
message propagation
peer role announcements
anti-spam and basic admission filtering
replay protection at message layer

6.2 Message families

P2P layer SHOULD transport:

object announcements
object requests/responses
block proposals
verifier votes
fraud proofs
notarization messages
governance object propagation
emergency notices
snapshot requests/responses

6.3 Rule

Network Layer MUST treat payloads as opaque until they reach decoder/validation. Transport MUST NOT decide consensus semantics.

7. Ingress / Admission Layer

7.1 Rol

Acest strat primește obiectele din:

P2P
local submit
RPC și le supune unor filtre preliminare ieftine.

7.2 Admission checks

Poate verifica:

size bounds
supported top-level version
known object family
trivial malformed envelopes
duplicate ingress suppression
rate limits / peer quotas

7.3 Rule

Admission Layer MUST NOT marca un obiect ca „consensus valid”. Poate doar:

accepta pentru procesare,
respinge ca evident corupt/inadmisibil,
sau pune în quarantine pentru analiză ulterioară.

8. Object Store

8.1 Rol

Stochează obiectele canonice și metadatele lor de procesare.

8.2 Obiecte tipice

transactions
cells snapshots or references
block candidates
notarization objects
witness records
proof bundles
governance proposals/outcomes/activations
machine deploy bodies
BVM bytecode modules
fraud proofs

8.3 Properties

Object Store SHOULD fi:

content-addressed where possible
deduplicated
append-friendly
auditable
separabil în hot and cold storage

8.4 Rule

Obiectele consensus-relevante MUST fi stocate într-o formă care permite reconstructibilitate exactă.

9. Canonical Decoder & Hash Engine

9.1 Rol

Convertește bytes -> obiecte canonice validate structural și derivă hash-urile standard.

9.2 Responsibilities

AZ-CBOR canonical parsing
schema selection by object family/version
duplicate key detection
canonical ordering validation
hash derivation with domain separation
minimal structural errors

9.3 Rule

Acest subsistem MUST fi identic semantic cu vectorii AZ-011. Orice divergență aici poate produce split.

10. Policy Engine

10.1 Rol

Evaluează PolicyRef și PolicyObject.

10.2 Responsibilities

resolve policy references
verify signatures
verify thresholds
verify expiry/fallback
verify witness-guarded conditions
verify machine-authorized conditions
expose exact satisfaction result

10.3 Rule

Policy Engine MUST fi pur deterministic pentru același input canonical.

11. Validation Engine

11.1 Rol

Implementează AZ-003 pentru toate obiectele și tranzacțiile relevante.

11.2 Responsibilities

validate object families
validate txs by type
classify errors
check references
check temporal conditions
check conflicts against local candidate context
derive or validate receipts
call State Engine where transition required

11.3 Internal phases

Validation Engine SHOULD păstra fazele logice:

decode/integrity
reference existence
temporal checks
authorization
semantic checks
resource/risk bound checks
post-invariant checks

11.4 Rule

Error precedence SHOULD urma AZ-003.

12. State Engine

12.1 Rol

Este sursa locală de adevăr pentru starea activă și istoric relevant.

12.2 Responsibilities

maintain utxo_set
maintain machine_registry
maintain machine_state_index
maintain witness_index
maintain intent_index
maintain halted object sets
maintain policy index
maintain protocol parameter state
derive and persist state roots
support snapshots and replay

12.3 Core property

State Engine MUST:

be deterministic in transition application;
be auditable;
support rollback of speculative candidate fronts before finality;
preserve finalized states immutably once notarized.

12.4 State partitions

State Engine SHOULD separa:

finalized state
speculative candidate state
archival history
pruning metadata

13. Snapshot / Persistence Layer

13.1 Rol

Persistă:

state snapshots
finalized checkpoints
journals
indexes
recovery artifacts

13.2 Snapshot types

full snapshot
finalized checkpoint snapshot
state delta journal
machine-state-local snapshot
governance parameter snapshot

13.3 Rule

Snapshot-urile folosite pentru consensus replay MUST fi canonicale și hash-addressed.

14. BVM Runtime Subsystem

14.1 Rol

Execută TX_MACHINE_CALL și verifică MachineDeploy.

14.2 Responsibilities

bytecode verification
static manifest checking
execution sandbox
host call mediation
exec units accounting
effect accumulator derivation
state write validation
result canonicalization

14.3 Integration with State Engine

BVM MUST NOT modifica direct starea persistentă globală. Trebuie să producă:

execution result
effect digest
next state root candidate pe care State Engine le aplică normativ.

14.4 Rule

BVM runtime SHOULD putea rula:

in deterministic single-threaded consensus mode
și eventual în optimized local mode, dar semantic MUST rămâne identic.

15. Witness / Proof Subsystem

15.1 Rol

Validează și indexează Witness Records și Proof Bundles.

15.2 Responsibilities

statement schema validation
issuer policy validation
proof verifier dispatch
TTL/revocation/supersession tracking
contradiction detection hooks
bounded query support for policies/contracts
witness status derivation

15.3 Rule

Witness status evaluation MUST fi deterministic și version-aware.

16. Economic Engine

16.1 Rol

Aplică AZ-007.

16.2 Responsibilities

compute fees
compute rent due / prepaid state
compute bond requirements
compute slash amounts
compute reward splits
compute congestion multipliers
expose active economic parameter set

16.3 Integration points

Economic Engine este chemat de:

Validation Engine
State Engine
Finality Engine
Governance Activation Engine
Recovery Controller

16.4 Rule

Toate calculele economice consensus-relevante MUST fi integer-deterministic.

17. Mempool / Candidate Pool

17.1 Rol

Păstrează obiecte admise dar nefinalizate.

17.2 Subpools

Este recomandată separarea în:

tx pool
witness/proof pending pool
block candidate pool
governance pending pool
fraud proof pool

17.3 Responsibilities

admission after cheap checks
dependency tracking
conflict tracking
expiry handling
fee/risk-based prioritization where relevant
candidate packaging hints

17.4 Rule

Mempool state este locală și nondeterministă. Nu trebuie confundată cu consensul.

18. Front Builder

18.1 Rol

Construiește fronturi candidate compatibile din DAG + obiecte valide.

18.2 Responsibilities

build candidate DAG views
detect conflicting blocks/txs
topologically order dependencies
derive compatible fronts
prepare front commitment candidates
feed scoring inputs to Consensus Engine

18.3 Rule

Algoritmul de selecție finală a frontului MUST urmeze ENDC și să fie deterministic pentru același set de inputuri. Heuristici locale pot decide ce candidaturi se explorează mai întâi, dar nu verdictul final.

19. Consensus Engine (ENDC)

19.1 Rol

Implementează logica de epocă, round, slot și rolurile de proposer/verifier/notary.

19.2 Responsibilities

derive committees
manage role eligibility
process block proposals
process verifier votes
score candidate fronts
coordinate notarization candidates
verify finality thresholds
produce/consume ENDC messages

19.3 Internal modules

Consensus Engine SHOULD conține:

committee selector
slot/epoch scheduler
verifier vote processor
front scorer
tie-breaker module
quorum tracker
notarization assembler

19.4 Rule

Consensus Engine MUST NOT „trusta” outputs neverificate ale altor subsisteme. Reexecutabilitatea este obligatorie înainte de finalitate.

20. Finality / Notarization Engine

20.1 Rol

Transformă un front selectat în finalitate hard.

20.2 Responsibilities

validate selected front
reexecute finalized candidate
verify finalized roots
assemble notarization object
validate notary signatures and thresholds
commit finalized checkpoint
expose finality events to rest of node

20.3 Rule

Nicio finalitate locală nu trebuie marcată drept hard înainte ca Notarization Engine să confirme toate condițiile.

21. Governance Activation Engine

21.1 Rol

Gestionează obiectele de guvernanță care schimbă parametrii sau regulile active.

21.2 Responsibilities

track proposals, reviews, votes, outcomes
derive admissibility
enforce timelocks
enforce challenge windows
activate approved changes at exact epoch boundary
expose active governance parameter state to consensus-critical components

21.3 Rule

Activation Engine MUST fi parte din consensus-critical boundary dacă schimbările sale afectează validarea și finalitatea.

22. Agent Control Hooks

22.1 Rol

Expun funcții standardizate pentru mandate, caps, journaling și control operațional.

22.2 Responsibilities

mandate lookup
effective cap computation
mandate lifecycle state
halt/safe/exit-only state
required witness/log checks
aggregate portfolio scope hooks
violation status queries

22.3 Position in architecture

Aceste hook-uri pot fi folosite de:

BVM runtime
Validation Engine
external agent tooling through RPC dar verdictul normativ relevant MUST rămâne ancorat în obiecte protocolare.

23. Recovery / Safe Mode Controller

23.1 Rol

Coordonează modurile defensive ale nodului fără a inventa reguli noi.

23.2 Responsibilities

enter degraded mode
enter safe mode
enforce active emergency restrictions
restrict risky subsystems if emergency actions active
surface incident state
coordinate replay/rebuild from finalized checkpoints

23.3 Rule

Recovery Controller MUST aplica doar mecanisme permise de protocol și de obiectele de guvernanță/emergency active.

24. Telemetry / Audit Log

24.1 Rol

Produce observabilitate și trasabilitate operațională.

24.2 Responsibilities

structured logs
consensus event logs
state root transitions
BVM execution traces (non-consensus)
anomaly events
governance activation trail
recovery mode trail
key incident markers

24.3 Rule

Telemetry MAY fi bogată, dar MUST NOT influența verdictul de consens.

25. API / RPC Layer

25.1 Rol

Interfața nodului cu:

wallets
agents
tooling
observers
governance dashboards
admin consoles

25.2 Responsibilities

object submission
state queries
notarization queries
witness status queries
mandate status queries
governance status queries
conformance/debug endpoints unde permis

25.3 Rule

RPC MUST distinge clar între:

finalized truth
speculative local view
advisory/local telemetry

26. Internal data flow — transaction path

26.1 Canonical path

Pentru o tranzacție obișnuită, fluxul SHOULD fi:

Network/RPC ingress
Admission checks
Object Store ingest
Canonical decode + hash derivation
Validation Engine phase checks
Policy Engine calls
Witness/Proof validation dacă e cazul
Economic Engine fee/rent computation
BVM call dacă e cazul
Candidate Pool insert
Front Builder consideration
Inclusion in block candidate
Consensus processing
Finality reexecution
State commit
Receipt/audit exposure

26.2 Rule

Această ordine logică nu trebuie inversată în mod care schimbă semantica.

27. Internal data flow — machine call path

27.1 Canonical path

decode TX_MACHINE_CALL
resolve machine descriptor and prior state
validate caller authorization
validate attached refs (cells/witnesses/proofs)
check economic preconditions
invoke BVM runtime
obtain canonical execution result
validate effect bound / permission surface / loss envelope
derive state delta
insert candidate result
finalize through normal consensus path

27.2 Rule

BVM runtime MUST NOT bypass Validation Engine post-checks.

28. Internal data flow — governance activation path

28.1 Canonical path

proposal ingest
proposal validation
review ingestion/validation
vote ingestion/validation
outcome derivation
challenge window tracking
activation scheduling
effective epoch boundary application
parameter registry update
activation audit event

28.2 Rule

Activarea MUST occur exactly at protocol boundary defined by governance object, not by local clock drift or admin trigger.

29. Consensus-critical databases

29.1 Required stores

Reference node SHOULD separa explicit:

canonical object DB
finalized state DB
speculative state DB
witness/proof DB
governance DB
economic parameter DB
consensus message journal
snapshot store

29.2 Rule

Finalized data MUST fi separată logic și protejată de speculative churn.

30. Speculative vs finalized execution

30.1 Need

ENDC permite fronturi candidate și execuție speculativă.

30.2 Model

Nodul SHOULD menține:

finalized state
one or more speculative branches
conflict metadata
reversible candidate receipts

30.3 Rule

Only Notarization Engine may promote speculative state to finalized state.

31. Threading model

31.1 Recommendation

Implementarea MAY folosi paralelism pentru performanță, dar SHOULD asigura:

deterministic merge points
stable ordering at consensus boundaries
no race-dependent verdicts

31.2 Safe pattern

Parallelize:

decoding
independent signature checks
proof verification queues
telemetry
candidate analysis But serialize:
consensus-critical state transitions
final front selection decision
final state commitment
governance activation at epoch boundary

31.3 Rule

Dacă paralelismul poate schimba verdictul observabil, designul este greșit.

32. Time source model

32.1 Need

Nodul are nevoie de timp pentru sloturi, epoci și TTL logic.

32.2 Rule

Time-dependent decisions consensus-relevante MUST folosi sursa/procedura protocolară standardizată, nu arbitrar local wall-clock logic.

32.3 Local clock role

Ceasul local poate fi folosit pentru:

scheduling intern
alerting
metrics dar MUST fi normalizat prin toleranțele protocolului când afectează verdictul.

33. Parameter state model

33.1 Active parameter state

Nodul MUST menține:

protocol version state
feature flags
economic parameters
governance-active changes
committee selection parameters
emergency restrictions active

33.2 Snapshotting

Parameter state SHOULD fi inclus în snapshots și reproducible replays.

33.3 Rule

Validation, BVM, Economics și Consensus MUST interoga aceeași parameter state activă pentru același punct de timp protocolar.

34. Safe mode integration

34.1 Node-local safe mode

Nodul MAY intra local în safe mode pentru:

operator protection
partial service exposure reduction
RPC restriction without changing consensus semantics.

34.2 Protocol-driven safe mode

Dacă există EmergencyAction activă, nodul MUST aplica restricțiile protocolare relevante.

34.3 Rule

Trebuie diferențiat clar între:

local safe mode
protocol emergency restriction ca să nu existe confuzii în audit.

35. Halt integration

35.1 Types

machine/domain halt from protocol objects
agent mandate halt
feature/domain freeze from emergency governance
node-local admin halt for RPC/services

35.2 Rule

Nodul MUST aplica doar halt-urile protocolare la nivel de verdict consensual. Node-local admin halt nu trebuie să pretindă că schimbă protocolul.

36. Recovery integration

36.1 Recovery capabilities

Reference node SHOULD support:

replay from finalized checkpoint
rebuild speculative branches
quarantine corrupted local indexes
rehydrate governance/parameter state
validate emergency restriction continuity

36.2 Rule

Recovery MUST never create finalized state that was not already derivable from valid notarizations and activations.

37. Fraud proof pipeline

37.1 Rol

Nodul SHOULD avea flux dedicat pentru fraud proofs.

37.2 Steps

ingest proof
decode and classify
verify cryptographic and semantic sufficiency
attach to relevant object set
inform consensus/recovery/slashing flows
persist audit artifact

37.3 Rule

Fraud proof verification MUST fi deterministic and version-aware.

38. Slashing evidence pipeline

38.1 Responsibilities

detect slashable events
package canonical evidence
validate evidence
expose to slashing execution logic
persist evidence trail
avoid duplicate slashing

38.2 Rule

Slash execution SHOULD depend only on canonical evidence and active rules, not admin discretion.

39. Reference node security hardening recommendations

39.1 Recommended separations

separate signing processes for proposer/verifier/notary
isolated key stores
bounded RPC privileges
read-only observer paths
audit logging on role-critical actions

39.2 Recommended runtime guards

canonicalization assertions
deterministic mode assertions
feature activation assertions
state root cross-check hooks
BVM effect digest cross-checks

39.3 Recommended operations

reproducible builds
signed release artifacts
snapshot verification
conformance CI
fault injection test runs

40. Reference node deployment profiles

40.1 Full validator profile

Runs:

network
admission
validation
state
mempool
consensus
finality
governance activation
telemetry

40.2 BVM-capable validator profile

Adds:

full BVM runtime
machine deploy/call execution

40.3 Notary-heavy profile

Adds:

hardened signing process
notarization quorum monitoring
enhanced finality checks

40.4 Observer / archival profile

Runs:

object store
finalized state
witness/governance indexes
telemetry/indexing without producing consensus role actions.

41. Failure containment in architecture

41.1 Principle

A bug or overload in one subsystem SHOULD not automatically corrupt the rest.

41.2 Examples

telemetry failure should not alter state
indexer corruption should not alter finalized truth
RPC overload should not alter validation semantics
speculative branch corruption should not overwrite finalized snapshots

41.3 Rule

Reference architecture SHOULD enforce containment by process and storage separation where feasible.

42. Canonical internal interfaces

42.1 Need

Internal APIs between critical components SHOULD be explicit and typed.

42.2 Required internal interfaces

decoder -> validation
validation -> policy engine
validation -> BVM
validation -> economic engine
validation -> state engine
front builder -> consensus
consensus -> finality engine
governance activation -> parameter registry
recovery controller -> state/safe mode gates

42.3 Rule

Critical interfaces SHOULD exchange canonical or schema-strict objects, not loosely typed blobs.

43. Reference implementation conformance hooks

43.1 The reference node SHOULD expose hooks for:

AZ-011 vector execution
deterministic replay
receipt reconstruction
BVM execution trace export
state root verification
governance activation boundary checks

43.2 Goal

A reference node is not only a production artifact. It is also the first conformance oracle.

44. Upgrade-aware architecture

44.1 Need

Protocol versions and feature activations change behavior at boundaries.

44.2 Rule

Node architecture MUST centralize:

active protocol version
active feature set
effective epoch transitions
old/new schema compatibility handling

44.3 Anti-pattern

Different subsystems caching version state independently without coordination is dangerous and SHOULD be avoided.

45. Observability boundaries

45.1 Finalized truth API

Should return only finalized data by default.

45.2 Speculative view API

May return candidate state, but MUST label it explicitly as speculative.

45.3 Governance future state API

May show scheduled activations, but MUST distinguish:

proposed
approved
timelocked
active

46. Minimal internal event bus

46.1 Recommendation

Node MAY use an internal event bus for non-consensus orchestration.

46.2 Event families

object admitted
tx validated
candidate front updated
epoch advanced
notarization finalized
governance activation scheduled
governance activation applied
safe mode entered
halt applied
recovery initiated
fraud proof accepted

46.3 Rule

Event bus delivery ordering MUST NOT be the hidden source of consensus truth. It is coordination, not law.

47. Architectural anti-patterns

Reference node SHOULD avoid:

consensus engine reading raw network objects without canonical decode layer
BVM mutating global state directly
governance activation scattered across multiple modules
mempool heuristics deciding final front implicitly
telemetry/indexer data used as consensus truth
speculative state overwriting finalized state
role keys sharing one hot key path
local wall-clock deciding activation or finality
witness status cached without invalidation on revocation/supersession
emergency restrictions implemented only in UI or ops layer instead of protocol layer

48. Architectural formula

Reference Node = deterministic validation core + replayable state engine + isolated BVM + explicit consensus/finality pipeline + governed parameter activation + recoverable operational shell

49. Relația cu restul suitei

AZ-012 este puntea dintre specificație și implementare.

Pe scurt:

AZ-002 până la AZ-011 spun ce trebuie să existe și cum trebuie să se comporte.
AZ-012 spune cum construiești un nod care poate face asta fără să amestece adevărul protocolului cu detalii locale de operare.

50. Ce urmează

După AZ-012, documentul corect este:

AZ-013 — BVM Bytecode Format and Opcode Tables

Acolo trebuie fixate:

secțiunile bytecode;
opcode-urile exacte;
encoding-ul lor;
cost model per opcode;
verificarea statică la nivel de instrucțiune;
formatele canonicale pentru execution results.

Închidere

Un protocol poate avea reguli corecte și totuși o implementare greșită dacă nodul nu este construit cu frontiere clare între transport, validare, execuție, consens, finalitate și guvernanță.

Acolo începe arhitectura serioasă a nodului.