Cardano Rust Node

High‑assurance, memory‑safe, modular Cardano node implementation in Rust focused on:

• Deterministic behavior & explicit configuration layering
• Observability (structured tracing + Prometheus metrics)
• Storage integrity & verifiable rollback safety
• Incremental protocol feature bring‑up with strict mutation guardrails

For the authoritative documentation index see: docs/INDEX.md

✨ Current Highlights

Area	Status	Notes
Storage	Append‑only engine (cardanodb)	Atomic snapshot indices + verification CLI + periodic background verify
Consensus	Advanced chain selection	Work/length/slot/hash tiebreak; bounded rollback depth & reorg metrics
Networking	Interim framed (bincode)	Handshake gating, frame size cap (512KiB), per‑peer rate guard (500 msg/s)
Mempool	Fee‑priority selection	Capacity + byte + TTL invariants; eviction metrics
Plutus	Interpreter stub + cost model	V1–V3 version gating; BLS12‑381 builtins behind version guard
Metrics	Comprehensive core set	Reorg/fork, storage verify, block validation latency, mempool saturation
Config Integrity	Manifest verification	SHA‑256 size+hash index, CLI preflight --verify-config

🔧 Quick Start

# Build
cargo build --release

# Run a local dev node (example — adjust network and paths)
./target/release/cardano-node-rust --network preprod --verify-config

# View metrics (default address configurable via NodeConfig)
curl http://127.0.0.1:9100/metrics | grep cardano_

� Crate Layering (Do Not Drift)

Crate	Responsibility (concise)
common	Domain types, hashing, epochs, defaults, shared errors
ouroboros	Consensus, chain selection, networking protocols (interim)
node	Binary wiring, config loading, runtime bootstrap only
config	Typed config structs, integrity manifest verification
client_api	External client-facing translation / (future) RPC
submit_api	Stand‑alone transaction submission surface (WIP)
scripts	Plutus execution (UPLC decode + interpreter + builtins)
tracer	Metrics & tracing facade / HTTP exporter
cardanodb	Append‑only storage engine (log + indices snapshot)

Guardrails & mutation checklist: see .github/copilot-instructions.md.

🛡 Security & Integrity Features

• Strict frame pre‑handshake gating (no non-handshake channels accepted pre-negotiation)
• Bounded rollback depth (consensus + storage alignment)
• Storage verification (structural + linkage + orphan trailing byte detection)
• Size & rate limiting on inbound frames (mitigate memory & CPU flood)
• Zero tolerance for unchecked panics in production pathways (audited; test-only panics allowed)

Planned hardening next: CBOR codec parity + mux layer, rate‑limit violation metric, binary snapshot WAL.

📊 Key Metrics (Sample)

Metric	Meaning
cardano_reorg_events_total	Reorg detections (counter)
cardano_last_reorg_depth	Depth of last reorg (gauge)
cardano_storage_verifications_total	Successful storage verification passes
cardano_block_validate_duration_seconds	Block validation latency histogram
cardano_mempool_saturation_percent	% mempool utilization

Full reference: docs/METRICS.md.

✅ Implementation Progress Snapshot

Implemented: multi-network config integrity, append‑only storage + verification, advanced chain selection, mempool invariants + fee selection, initial Plutus interpreter, metrics suite, security guardrails.

In Progress: protocol CBOR/mux migration, richer Plutus error classification, storage WAL + compaction pipeline.

Planned: full typed mini‑protocol parity (ChainSync pipelining, BlockFetch streaming), extended ledger validation, governance & on‑chain epoch config updates.

🚀 Contribution Guide (Essentials)

1. Run ./tools/quick_verify.sh 180 before committing (fast check).
2. Treat warnings as errors (clippy -D warnings).
3. Document new public types (rustdoc) + add serialization roundtrip tests for new protocol messages.
4. Never silently alter frame layout or reorder network enum variants without following the mutation checklist.
5. Reuse domain hash / ID types from common — never duplicate.

See CONTRIBUTING.md + docs/QUALITY_STANDARDS.md for full policy.

🔐 Config Integrity Quick Use

./target/release/cardano-node-rust --network mainnet --verify-config

Regenerate manifest after intentional config edits:

./tools/generate_config_manifest.sh

🛠 Troubleshooting Fast Path

Symptom	Check
Verification anomalies	Run --storage-verify-json & inspect errors[]
High reorg depth	Inspect chain selection logs (reorg span) & peer quality
Mempool full	Adjust capacity in config or inspect propagation delays
High validation latency	Review cardano_block_validate_duration_seconds histogram

More: docs/wiki/Troubleshooting.md.

📄 License

See LICENSE and NOTICE for third‑party attributions.

---

This README is part of a holistic documentation refresh. All Markdown assets are being normalized; refer to docs/INDEX.md for canonical locations.