If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/ordinals/ord shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 5w ago
• 25+ active contributors
• CC0-1.0 licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 65% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live ordinals/ord repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/ordinals/ord.

What it runs against: a local clone of ordinals/ord — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in ordinals/ord | Confirms the artifact applies here, not a fork | | 2 | License is still CC0-1.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 65 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of ordinals/ord. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/ordinals/ord.git
#   cd ord
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of ordinals/ord and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "ordinals/ord(\\.git)?\\b" \\
  && ok "origin remote is ordinals/ord" \\
  || miss "origin remote is not ordinals/ord (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(CC0-1\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"CC0-1\\.0\"" package.json 2>/dev/null) \\
  && ok "license is CC0-1.0" \\
  || miss "license drift — was CC0-1.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "crates/ordinals/src/lib.rs" \\
  && ok "crates/ordinals/src/lib.rs" \\
  || miss "missing critical file: crates/ordinals/src/lib.rs"
test -f "crates/ordinals/src/sat.rs" \\
  && ok "crates/ordinals/src/sat.rs" \\
  || miss "missing critical file: crates/ordinals/src/sat.rs"
test -f "crates/ordinals/src/runestone.rs" \\
  && ok "crates/ordinals/src/runestone.rs" \\
  || miss "missing critical file: crates/ordinals/src/runestone.rs"
test -f "crates/ordinals/src/rune.rs" \\
  && ok "crates/ordinals/src/rune.rs" \\
  || miss "missing critical file: crates/ordinals/src/rune.rs"
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 65 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~35d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/ordinals/ord"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

ord is a Bitcoin indexer, block explorer, and command-line wallet that implements Ordinal theory—a numbering scheme for satoshis that assigns and tracks serial numbers across transactions. It enables satoshis to be collected, traded, and inscribed with arbitrary data, turning individual sats into collectible digital artifacts with provenance tracking. Monorepo with Cargo workspace: main crate is /. under crates/ordinals/ (core ordinal logic: artifact.rs, cenotaph.rs, charm.rs, etching.rs), crates/mockcore/ (Bitcoin Core mock for testing), and specialized audit crates. Binary tools in bin/ (benchmark, flamegraph, forbid, graph, package, replicate, swap). Frontend HTML/CSS/JS assets alongside Rust backend.

Bitcoin developers and users interested in ordinal inscriptions, NFT-like artifacts on Bitcoin, and sat collectors who need indexing and wallet functionality without relying on centralized services. Contributors are typically Rust developers familiar with Bitcoin Core RPC and blockchain indexing.

Actively developed and experimental (v0.27.1). Has CI/CD pipelines (ci.yaml, release.yaml), robust test infrastructure via mockcore, and regular releases, but the README explicitly warns 'experimental software with no warranty'. Single lead maintainer (raphjaph) funded by donations suggests community backing but potential bus-factor risk.

Single lead maintainer creates sustainability risk; relies heavily on Bitcoin Core wallet integration with explicit warnings that misuse can lose inscriptions. Large dependency tree (bitcoincore-rpc, axum, reqwest) means transitive vulnerability surface. No evidence of formal security audits visible in repo structure, though crates/audit-* packages suggest some security tooling.

Visible from the structure: active maintenance of the ordinals theory implementation (crates/ordinals/src/ has recent additions like charm.rs for charm enumeration), wallet functionality, and block explorer. The batch.yaml and bin/batch suggest batch transaction processing is being refined. Discord community and project board indicate ongoing feature prioritization.

git clone https://github.com/ordinals/ord.git
cd ord
cargo build --release
cargo run -- --help

Requires Rust 1.89.0+ (from workspace config) and a running Bitcoin Core node for wallet/indexing commands.

Daily commands:

cargo run --bin ord -- server --http-port 80

Alternatively with Docker: docker build -t ord . && docker run -p 80:80 ord. Requires a synced Bitcoin Core node accessible via RPC (typically localhost:8332). Wallet commands require Bitcoin Core wallet named 'ord' to be loaded.

• crates/ordinals/src/lib.rs — Core ordinals library exporting the fundamental types (Sat, SatPoint, Rune, Runestone) that all indexing and wallet logic depends on.
• crates/ordinals/src/sat.rs — Defines the Sat type representing individual satoshis and their ordinal numbering—the conceptual foundation of the entire project.
• crates/ordinals/src/runestone.rs — Implements the Runestone protocol (rune issuance and transfers), a major feature for handling digital artifacts beyond ordinals.
• crates/ordinals/src/rune.rs — Defines the Rune type and protocol mechanics; essential for understanding the rune (fungible token) system layered on ordinals.
• Cargo.toml — Workspace configuration and dependency manifest; contributors must understand the crate structure and dependency versions.
• crates/mockcore/src/lib.rs — Mock Bitcoin Core API for testing; required to understand how the indexer simulates blockchain state in tests.
• build.rs — Build script that may perform code generation or configuration; reviewers must understand pre-compilation steps.

Add a new Sat attribute (charm or rarity metric)

1. Define the new attribute type in a new file (e.g., crates/ordinals/src/my_attribute.rs) or extend crates/ordinals/src/charm.rs (crates/ordinals/src/charm.rs)
2. Export the new type from crates/ordinals/src/lib.rs (crates/ordinals/src/lib.rs)
3. Implement calculation logic in the Sat struct or related helper functions (crates/ordinals/src/sat.rs)
4. Add comprehensive unit tests in the same file or in tests/ (crates/ordinals/src/sat.rs)

Add a new Runestone message field or protocol feature

1. Add a new variant to the Tag enum in crates/ordinals/src/runestone/tag.rs (crates/ordinals/src/runestone/tag.rs)
2. Update the Runestone parsing logic in crates/ordinals/src/runestone.rs to handle the new tag (crates/ordinals/src/runestone.rs)
3. Add a corresponding field to the Runestone struct in crates/ordinals/src/runestone.rs (crates/ordinals/src/runestone.rs)
4. Write unit tests for parsing and serialization in crates/ordinals/src/runestone.rs (crates/ordinals/src/runestone.rs)

Add a new Rune protocol constraint or validation rule

1. Define the constraint type (e.g., new field in Etching) in crates/ordinals/src/etching.rs or crates/ordinals/src/terms.rs (crates/ordinals/src/etching.rs)
2. Implement validation logic in the parsing/construction methods of Rune or related types (crates/ordinals/src/rune.rs)
3. Add error handling via the Flaw enum in crates/ordinals/src/flaw.rs if the constraint is violated (crates/ordinals/src/flaw.rs)
4. Add test cases in crates/ordinals/src/rune.rs to validate both valid and invalid scenarios (crates/ordinals/src/rune.rs)

Add a new test scenario using MockCore

1. Understand MockCore server API by reviewing crates/mockcore/src/api.rs (crates/mockcore/src/api.rs)
2. Set up blockchain state using crates/mockcore/src/state.rs in your test (crates/mockcore/src/state.rs)
3. Spawn a MockCore server instance in your test or integration test harness (crates/mockcore/src/server.rs)
4. Query the mock server like you would Bitcoin Core and assert results (crates/mockcore/src/lib.rs)

• Rust — Memory safety without GC, performance-critical for blockchain indexing, and enforces correct handling of numeric types (sats as u64).
• Bitcoin 0.32.5 crate — undefined

Bitcoin Core RPC endpoint must be accessible (defaults to localhost:8332); wallet commands auto-load the 'ord' wallet and can corrupt non-ordinal-aware wallets—never use with hot wallets. Satoshi numbering is deterministic but depends on complete blockchain history; indexing can be slow on first sync. CBOR encoding for inscriptions is sensitive to field ordering. The mockcore crate must stay in sync with Bitcoin Core RPC API for tests to remain valid. No obvious env var configuration file in the listing—check documentation for required vars like BITCOIN_RPC_USER, BITCOIN_RPC_PASSWORD.

• Ordinal Numbers — The fundamental numbering scheme this entire project implements; understanding how satoshis are serially numbered and preserved across transactions is prerequisite to understanding ord's data structures
• Inscription Protocol — ord uses CBOR-encoded data embedded in witness scripts to store arbitrary content (artifacts); understanding witness malleability and taproot scripting is essential for artifact handling
• Satoshi Control (Sat-Controlled UTXO Tracking) — ord's critical differentiator: it tracks individual satoshis within UTXOs, enabling sat-aware transaction construction that other wallets ignore; this is why Bitcoin Core integration is risky
• Cenotaph (Burnt/Invalid Inscriptions) — crates/ordinals/src/cenotaph.rs handles malformed inscriptions; understanding how invalid inscriptions are marked and excluded prevents data corruption in the index
• CBOR Serialization — ord uses ciborium for CBOR encoding of artifact metadata; different from JSON, CBOR is compact binary and order-sensitive—critical for inscription parsing
• Bitcoin Core RPC Wallet Integration — ord relies entirely on Bitcoin Core's wallet for key management and signing, not its own key storage; understanding this trust boundary and its limitations prevents fund loss
• Charm (Sat Properties/Rarity) — crates/ordinals/src/charm.rs enumerates special satoshi properties (first of type, lucky, vintage, etc.); these properties drive collection value and are computed deterministically from ordinal position

• ordinals/ordinals-com — Official ordinals.com documentation and web presence; companion resource explaining ordinal theory to end users
• stacks-network/stacks-blockchain — Alternative smart contract platform on Bitcoin that competes for similar user base; demonstrates alternate approach to Bitcoin extensibility
• bitcoin/bitcoin — Bitcoin Core itself; ord is entirely dependent on its RPC interface and wallet functionality
• casey/ord-old — Original ordinals implementation by Casey Rodarmor; historical reference and potential inspiration for design patterns
• unisat-wallet/extension — Popular Unisat wallet that competes in the ordinal/inscription wallet space; exemplifies alternative wallet UX for the same ecosystem

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive integration tests for runestone parsing and validation

The crates/ordinals/src/runestone/ module contains complex parsing logic for runestone messages (Flag, Message, Tag). Currently, there are likely minimal tests for edge cases in runestone serialization/deserialization. This is critical for an ordinals indexer since runestones are core to the protocol. New tests should cover malformed messages, boundary conditions, and tag validation.

• [ ] Create crates/ordinals/src/runestone/tests.rs or add test modules to each runestone file
• [ ] Write tests for runestone/flag.rs covering all flag combinations and invalid inputs
• [ ] Write tests for runestone/tag.rs covering tag parsing, unknown tags, and ordering
• [ ] Write tests for runestone/message.rs covering varint edge cases and message reconstruction
• [ ] Add integration tests in crates/ordinals/ that construct complete runestones and validate round-trip encoding/decoding

Add GitHub Actions workflow for security audit of dependencies

The repo has crates/audit-cache/ and crates/audit-content-security-policy/ audit tools but no CI workflow that runs them automatically. Given the financial nature of ordinals (wallet, indexing satoshis), automated dependency audits should run on each PR. The .github/workflows/ directory shows ci.yaml and release.yaml exist, but no audit workflow.

• [ ] Create .github/workflows/audit.yaml that runs on push to main and all PRs
• [ ] Configure the workflow to run cargo audit to check for known vulnerabilities
• [ ] Add step to run crates/audit-cache/ to validate build cache integrity
• [ ] Add step to run crates/audit-content-security-policy/ for CSP violations
• [ ] Set up workflow to fail the CI if any audit issues are found, with clear error messages

Add unit tests for Rune ID generation and SpacedRune parsing edge cases

The files crates/ordinals/src/rune.rs, crates/ordinals/src/rune_id.rs, and crates/ordinals/src/spaced_rune.rs handle core rune protocol logic but likely lack exhaustive test coverage for edge cases like invalid spacing, boundary conditions on rune IDs, and name collision handling. This is critical since runes are a major feature of the ordinals protocol.

• [ ] Add tests to crates/ordinals/src/rune.rs for rune name validation (invalid characters, length bounds, reserved names)
• [ ] Add tests to crates/ordinals/src/rune_id.rs for ID construction, comparison, and overflow conditions
• [ ] Add tests to crates/ordinals/src/spaced_rune.rs for parsing spaced rune strings with various spacing patterns and invalid formats
• [ ] Write property-based tests using quickcheck or proptest for rune name generation to ensure all valid names are accepted
• [ ] Add tests that verify rune uniqueness constraints and collision detection

• Add integration tests for crates/audit-content-security-policy/ and crates/audit-cache/ to cover the audit tools more thoroughly (they currently lack visible test coverage in the repo structure)
• Extend crates/ordinals/src/charm.rs with additional charm types and add property-based tests using proptest to ensure charm enumeration is exhaustive across sat ranges
• Document the BIP implementation in code comments within crates/ordinals/src/artifact.rs and cenotaph.rs, mapping BIP.mediawiki sections to struct definitions for new contributors

• High · Outdated Rust Compiler Version in Dockerfile — Dockerfile (line 1). The Dockerfile uses Rust 1.85.0 as the builder image, while the workspace specifies rust-version = "1.89.0" in Cargo.toml. This mismatch means the build uses an older compiler that may lack recent security patches and bug fixes. Fix: Update the Dockerfile to use Rust 1.89.0 or later to match the workspace rust-version requirement: FROM rust:1.89.0-bookworm AS builder
• High · Missing Security Headers in Axum Web Server — Main application dependencies and configuration. The application uses Axum web framework (version 0.8.1) for serving a block explorer and wallet interface. The Dockerfile and provided snippets show no evidence of security headers (CSP, HSTS, X-Frame-Options, etc.) being configured, which could expose users to XSS, clickjacking, and other web-based attacks. Fix: Implement middleware to add security headers. Consider using tower-http's SecurityHeadersLayer or similar to set Content-Security-Policy, Strict-Transport-Security, X-Frame-Options, and X-Content-Type-Options headers.
• Medium · Insufficient Input Validation on Runestone and Bitcoin Transaction Parsing — crates/ordinals/src/runestone/, crates/ordinals/src/varint.rs. The codebase includes complex parsing logic for ordinals (runestones, etchings, edicts) and Bitcoin transactions. The presence of files like varint.rs, runestone.rs, and edict.rs suggests custom parsing logic that could be vulnerable to malformed input, buffer overflows, or integer overflow attacks if not properly validated. Fix: Ensure all parsing functions use safe Rust patterns, validate input sizes before allocation, use checked arithmetic for integer operations, and add fuzzing tests for parser functions to detect edge cases.
• Medium · RPC Communication to Bitcoin Core Without TLS Verification — Dependencies: bitcoincore-rpc = "0.19.0". The bitcoincore-rpc dependency (version 0.19.0) is used to communicate with Bitcoin nodes. There is no visible configuration for TLS certificate pinning or hostname verification in the provided code, which could allow MITM attacks if the Bitcoin Core node is accessed over a network. Fix: Enforce TLS verification when connecting to remote Bitcoin nodes. Implement certificate pinning or at minimum require valid certificates. For local connections, ensure the RPC socket is bound to localhost only (127.0.0.1).
• Medium · Hardcoded Edition 2024 May Have Stability Issues — Cargo.toml (workspace.package). The workspace uses edition = "2024" which is bleeding-edge and may not have the same level of stability and security vetting as stable editions (2021, 2018). Production systems should use well-tested editions. Fix: Consider downgrading to edition "2021" for production deployments unless 2024-specific features are critical. Ensure adequate testing on all targets before using bleeding-edge editions in production.
• Medium · Minimal Dockerfile Security Hardening — Dockerfile. The Dockerfile uses debian:bookworm-slim as the runtime base and only installs openssl. There are no AppArmor profiles, seccomp filters, non-root user setup, or read-only filesystem configurations. Additionally, the image lacks common security best practices like removing package manager cache. Fix: Implement Docker security best practices: (1) Create and use a non-root user, (2) Use RUN apt-get clean && rm -rf /var/lib/apt/lists/*, (3) Mark filesystem as read-only where possible with --security-opt=no-new-privileges, (4) Consider using distroless base image, (5) Add security labels and health checks.
• Low · Logging Configuration May Expose Sensitive Data — Dockerfile (ENV variables). The Dockerfile sets RUST_LOG=info which enables logging. If the application logs transaction details, wallet information, or RPC credentials, this could expose sensitive information. The use of RUST_BACKTRACE=1 in production may also leak information. Fix: Set RUST_LOG to warn or error in production. Implement structured logging with sensitive data masking. Remove RUST

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.