A seasonal Nakamoto-style chain with deterministic Proof-of-Bloom issuance, an auditable JSONL ledger, and craftable scarcity.

---

About

Crocus is a research chain about time-shaped money. Most blockchains halve their block reward on a fixed schedule until it asymptotes to zero. Crocus halves, too — but only during Blooms, finite windows of intense issuance that punctuate long stretches of dormancy. Between Blooms, new supply trickles; during a Bloom, it rains. The result is a monetary cadence that mirrors a crocus flower: long sleep, short vivid bloom.

The chain is built to be small enough to hold in one head and auditable line-by-line:

• One Rust workspace. A hardened node, a thin mempoold HTTP bridge, a deterministic devnet simulator, the WalletX CLI, and a handful of replay / repair / stats utilities — all in a single Cargo workspace you can cargo build --release in under a minute.
• An append-only JSONL ledger. blocks.jsonl, utxo.jsonl, and mempool.jsonl are the sources of truth. Every consensus-relevant event is a single JSON line; anything missing can be re-derived from these three files with crocus_replay.
• A written consensus specification. Every block-validity, difficulty, issuance, chain-selection, and mempool rule is documented in docs/consensus-spec.md with src/<path>:<line> citations. What the spec says, the code enforces — and every known gap is catalogued, not glossed.
• Craftable scarcity. Three denominations — FLWR (base), gSAF (gold saffron, 1 gSAF = 165 FLWR), and pSAF (purple saffron, 1 pSAF = 75 000 FLWR) — represent the chain's policy-layer narrative: mining mints petals, crafting burns them into saffron.

Crocus is explicitly devnet-only. The purpose is to make every design decision legible, testable, and easy to poke holes in — not to move value.

Table of contents

• Architecture at a glance
• Quickstart
• What's in the box
• Issuance model
• Documentation
• Sister protocols
• Development
• Status & security
• Roadmap
• Contributing
• License

---

Architecture at a glance

          ┌────────────────────┐                  ┌──────────────────────┐
  CLI ───►│   WalletX          │   POST /submit   │   mempoold           │
  SDK ───►│   (key-derive,     │─────────────────►│   (HTTP bridge,      │
  curl ──►│    canonicalize,   │                  │    policy, RBF,      │
          │    sign, post)     │                  │    rate limit, GC)   │
          └────────────────────┘                  └──────────┬───────────┘
                                                             │  headers /
                                                             │  tx IDs (gossip)
                                                             ▼
                         ┌──────────────────────────────────────────────┐
                         │   node (HTTP + P2P + SSE + KV index)         │
                         │   block producer · chain selector · miner    │
                         │   Proof-of-Bloom PoW · seasonal issuance     │
                         └──────────────────┬───────────────────────────┘
                                            │
                                            ▼
                 ┌───────────────────────────────────────────┐
                 │   JSONL ledger (source of truth)          │
                 │   blocks.jsonl · utxo.jsonl · mempool.jsonl│
                 │   + redb key/value index for fast lookup   │
                 └───────────────────────────────────────────┘

1. WalletX derives keys locally, canonicalizes the transaction JSON, signs, and POSTs.
2. mempoold validates JSON policy (fee floor, size caps, RBF), rate-limits, and writes to mempool.jsonl. Headers and tx-IDs can be gossiped over a length-prefixed JSON P2P frame.
3. node mines new blocks via Proof-of-Bloom, reaches chain selection on cumulative work, streams /events (SSE), exposes /metrics (Prometheus), and maintains a redb key/value index rebuildable from the JSONL log.
4. Data lives in plain JSONL for transparency; indices are cache on top.

---

Quickstart

Prerequisites. Rust stable (rustup default stable), git, bash or PowerShell 7, optional jq.

# 1. Build the workspace (release profile)
cargo build --release --workspace

# 2. Start the node in one terminal
target/release/node --http 127.0.0.1:18080 --root devnet

# 3. Start the mempool bridge in another
target/release/mempoold --http 127.0.0.1:18081 --root devnet

# 4. Mine a handful of deterministic blocks (writes JSONL under ./devnet)
target/release/devnet --blocks 20 --root devnet

# 5. Explore the WalletX CLI
cargo run --release -q --bin crocus_walletx -- help

One-command quickstarts build, mine funding blocks, submit a sample transaction through mempoold, and print the resulting tip:

bash scripts/quickstart.sh         # macOS / Linux
pwsh -File scripts/quickstart.ps1  # Windows

Locking down write endpoints once you take the node off loopback:

export CROCUS_API_TOKEN='use-a-real-value-here'
target/release/node --http 0.0.0.0:18080 --root devnet
# /tx and /mine/once now require: Authorization: Bearer <token>

---

What's in the box

Binary	Role
node	HTTP + P2P + SSE + key/value index; block producer, chain selector, miner.
mempoold	HTTP submission bridge with JSON policy, RBF, rate limits, mempool GC.
devnet	Deterministic block generator for reproducible Proof-of-Bloom scenarios.
crocus_walletx	Key derivation, canonicalization, signing, address tools.
crocus_replay	Rebuild utxo.jsonl or the chain index from block envelopes.
crocus_repair	Rebuild the redb key/value index from blocks.jsonl.
crocus_snapshot	Take and verify a consistent snapshot of <root>.
crocus_stats	Walk the ledger and summarise issuance, fees, supply, and policy state.

Cargo features (--features full enables them all):

• p2p — length-prefixed JSON gossip, ban-score, token-bucket rate limiting.
• metrics — Prometheus /metrics + /events SSE stream.
• walletx — build the crocus_walletx CLI.

---

Issuance model

Crocus follows a three-level periodicity:

Unit	Duration	Behaviour
Block	~10 min target	Deterministic per-height subsidy inside a Bloom; zero outside.
Bloom	2 016 blocks (~14 days)	Reward window inside each Cycle. Three per Cycle.
Cycle	26 weeks (~half year)	Contains one Bloom plus ~24 weeks of dormancy.
Era	8 Blooms	Halves the per-Bloom pool.

The per-Bloom pool is ERA0_BLOOM_POOL_FLWR / 2^era, starting at 56 250 000 FLWR. Asymptote cap is 900 000 000 FLWR. Craft ratios are fixed: 165 FLWR → 1 gSAF and 75 000 FLWR → 1 pSAF.

Full derivation, edge cases, and the exact line where each rule is enforced live in docs/consensus-spec.md §3. The numbers are not marketing — they come from src/consensus/constants.rs.

---

Documentation

Doc	What it covers
docs/consensus-spec.md	Block validity, difficulty retarget, issuance, chain selection, mempool policy — with src/<path>:<line> citations on every rule and a catalogued gap table.
docs/architecture.md	One-page reference for the source tree, binaries, tx lifecycle, data structures, and the consensus-vs-policy boundary.
docs/runbook.md	Operator guide: install, deploy, monitor, snapshot/restore, upgrade, hardening off-loopback, incident response.
docs/storage.md	On-disk ownership: which file writes which bytes, recovery procedures, atomic-rename primitives.
docs/security/threat-model.md	Per-class threat model (T1 consensus forging through T9 node-authored block invalidity). Names adversary, mitigation with file citations, and residual risk for each.
SECURITY.md	Reporting process, response targets, API authentication, hardening tips.
docs/POLICY.md	Mempool admission policy, fee floor, RBF rules.
docs/OBSERVABILITY.md	Prometheus metrics catalogue, SSE event schema, Grafana dashboard.
docs/WHITEPAPER-v0.44.md	Design rationale and monetary-policy narrative.
docs/INVARIANTS.md	Safety properties the test suite targets.
CHANGELOG.md	Tagged release history.

---

Sister protocols

Crocus is part of a broader set of verifiable economic and identity primitives under @SativusCrocus. Each sister project explores a different thin layer between cryptographic assurance and real economic flow.

AletheiaProtocol Base Sepolia · TypeScript Permissionless validity ledger for scientific claims. ForgeGuard ZK-proven exploit challenges, sandboxed mirage instances, security attestation minting.	ARC-Protocol Bitcoin · TypeScript Bitcoin-native identity, provenance, and economic settlement for autonomous AI agents. BIP-340 Schnorr, inscriptions, Lightning settlement.	Inflara Solana · TypeScript Purchasing-power flatcoin pegged to real CPI/inflation via Pyth — not a fake $1 nominal peg. Permissionless, over-collateralized.
SkillRoot Base · Solidity Zero-knowledge skill proofs. 24 h fraud-proof window, bonded challengers, auto-finalizing decayed on-chain scores.	energywork-miner Ethereum · HTML Thermodynamic money primitive. Fair-launched, browser-mineable PoW token. No premine, Bitcoin-style halving.	Sovereign-Economy Docker / Akash · Python Four-layer decentralized autonomous economic system: GraphRAG agent swarm → MCP tool exec → multi-sig bridge → deploy.

The complete pinned set — including TIN, Mycelium-Kit, and the SativusCrocus OS portfolio — is at github.com/SativusCrocus.

---

Development

# format, lint, test
cargo fmt --all
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace

# fuzz targets (requires nightly + cargo-fuzz)
cargo +nightly fuzz run json_parse
cargo +nightly fuzz run p2p_frame
cargo +nightly fuzz run mempool_policy

# security scanners (local)
just scan                          # gitleaks + semgrep (optional trivy)

# reproducible build check
bash scripts/repro-build.sh

Useful utilities:

• crocus_repair — rebuild the redb key/value index from blocks.jsonl.
• crocus_replay --from-blocks — restore utxo.jsonl from block envelopes.
• scripts/validate-json.py — JSON-schema validation (also runs in CI).

---

Status & security

Crocus is a devnet-only research chain. Do not use it for real funds or production value transfer. Consensus rules, APIs, and network behaviour change without notice between releases.

Response targets. Security reports acknowledged within 72 h; triage within 7 business days; patch or mitigation ETA within 30 business days. See SECURITY.md.

Preferred disclosure channel. Open a private GitHub Security Advisory against this repository. GHSA is the encrypted channel.

Hardening defaults when exposing the node beyond loopback:

• Set CROCUS_API_TOKEN — write endpoints (/tx, /mine/once) now require Authorization: Bearer <token>.
• Tune P2P caps: P2P_RATE_BURST, P2P_RATE_REFILL, P2P_BAN_THRESHOLD.
• Tune mempool caps: CROCUS_TX_MAX_JSON, CROCUS_MEMPOOL_MAX_ITEMS, CROCUS_GC_MAX_BYTES.
• Run behind a firewall or reverse proxy; bind to loopback by default.

Known gaps — all catalogued in docs/consensus-spec.md §6 — include: PoW is not verified on the P2P receive path, cumulative work is not recomputed on receive, and the node-authored /mine/once path does not perform real PoW search. These are tracked for Phase 5/6 hardening.

---

Roadmap

• Phase 3.2 — redb-based key/value index replaces sled
• Phase 4 — written consensus specification with gap catalogue
• Phase 5.1 — SECURITY.md + threat-model extension to consensus
• Phase 5.4 — CROCUS_API_TOKEN Bearer auth on write endpoints
• Phase 5.2 — PoW verification on P2P block receive
• Phase 5.3 — ed25519 P2P peer authentication
• Phase 6 — fuzz expansion (chain index, SSE parser) + property tests for consensus-critical code

---

Contributing

Contributions welcome. See CONTRIBUTING.md for the workflow, commit-message format (Conventional Commits), and review checklists. Issues labelled good first issue or help wanted are a useful starting point.

---

License

MIT. See LICENSE.

---

_{Built in Rust · Proof of Bloom · Part of the SativusCrocus protocol family}