How lugondev/ord works
Project Type and Purpose
• Type: A Rust‑based open‑source command‑line tool and service.
• Purpose:
• Index Bitcoin blocks/transactions and build an “ordinals” index of satoshi ownership and inscriptions.
• Provide a CLI wallet for managing ordinals (including subcommands like mint, send, inscribe, etc.).
• Serve a web‑based block explorer (“ord server”) with HTML templates and static assets.
• Offer auxiliary utilities (benchmarking, fuzz testing, audits, contributor updates) via workspace crates.
File Structure Analysis
• Root
• Cargo.toml, Cargo.lock: workspace definition.
• src/: main ord binary entrypoint and subcommand modules (indexer, server, wallet, misc).
• templates/ + static/: HTML templates and CSS/JS for the web UI.
• crates/: reusable libraries and command‑line utilities
– crates/ordinals: core logic for ordinal numbers, inscriptions, runes, etc.
– crates/mockcore: mocked Bitcoin Core for tests.
– crates/audit-* and update-contributors: CLI helpers.
• tests/ and fuzz/: integration, unit, and fuzz tests.
• bin/: shell helpers and packaging scripts.
• Configuration & Deploy
• deploy/: systemd units and bitcoind config for production.
• Dockerfile, shell.nix, justfile, CI workflows (.github/workflows).
Key Insights from README
• Dependencies: Bitcoin Core (RPC + txindex), Rust (≥1.79).
• Subcommands:
• ord index: build/read the ordinals index.
• ord server: HTTP API + web UI.
• ord wallet: delegate Bitcoin Core wallet + inscription‑aware commands.
• Security Warning: untrusted HTML/JS in explorer → XSS risk.
• Testing: TDD with unit, integration, fuzz using mockcore.
a. Main Components
• ord CLI Binary (Rust)
• Subcommand modules: indexer, server, wallet, decode, find, etc.
• Linked internal crates: ordinals, mockcore (tests), audit-*.
• Bitcoin Core Node
• External service accessed via RPC (cookie or credentials).
• Provides UTXO data, block/tx fetching, key management, signing.
• Ordinals Index Store
• Local data files (on‑disk DB or custom serialized formats) containing satoshi index, inscriptions, UTXO states.
• HTTP Server & UI
• Reads index store.
• Renders HTML via templates/ + serves static assets (static/).
• Exposes JSON/HTML endpoints under ord server.
• Clients
• CLI users, browser users of explorer, integration tests, external scripts.
b. Interactions & Data Flows
• Indexing Flow
1. ord index subcommand → Bitcoin Core RPC → fetch blocks/txs → process via ordinals crate → write to Index Store.
• Server Flow
1. ord server → load Index Store → HTTP requests → handlers in src/subcommand/server → render with templates & static assets → respond to browser.
• Wallet Flow
1. ord wallet <action> → Bitcoin Core RPC wallet commands → optionally update Index Store (e.g., new inscriptions).
• Testing & Mocking
• mockcore crate simulates Bitcoin Core for fast unit and integration tests.
• Fuzz targets in fuzz/ probe critical encoding/decoding modules.
c. Architectural Patterns & Principles
• Modular CLI with Subcommands (separation of concerns: indexing, serving, wallet, tools).
• Cargo Workspace: shared libraries (ordinals, mockcore) and standalone utilities.
• Template‑Driven Web UI: clear separation of presentation (templates/, static/) from logic (src/templates.rs, src/subcommand/server).
• External Service Integration: reliance on Bitcoin Core RPC for blockchain data and signing.
• Test‑Driven & Fuzz‑Safe: mocks and fuzz harnesses for reliability.