🧬 Plasmid

Decentralized Genomic Wiki & Merkle Range Slicing Engine

English • 한국어

---

🏛️ What is Plasmid?

Plasmid (plasmid.wiki) is an open-source, decentralized genomic knowledge mesh and streaming engine engineered to solve the three core crises facing modern human genomics:

1. The Privacy & Corporate Bankruptcy Crisis: In the wake of consumer DTC platform bankruptcies and genomic database auctions, users need a zero-network, air-gapped local interpreter where private WGS/VCF files never touch cloud servers.
2. The Knowledge Decay Crisis: Following the commercial acquisition and subsequent freeze of SNPedia, the scientific community lacks an immutable, censorship-resistant, community-driven variant interpretation wiki.
3. The Egress Cost Wall: Academic labs struggle with astronomical AWS S3 egress costs when hosting massive BAM/CRAM genome browsers. Plasmid's PMTiles-inspired single-container format (.plasmid) combined with BitTorrent v2 (BEP 52) WebRTC swarming reduces origin bandwidth costs by over 90%.

---

⚡ Key Architectural Pillars

┌────────────────────────────────────────────────────────────────────────┐
│                        Plasmid Hybrid Mesh System                      │
├──────────────────────────────────┬─────────────────────────────────────┤
│     Public Swarm Layer (P2P)     │     Air-Gapped Local Vault (OPFS)   │
├──────────────────────────────────┼─────────────────────────────────────┤
│ • ClinVar/ACMG Immutable SSOT    │ • User Raw WGS / BAM / CRAM / VCF   │
│ • 16KB Merkle Leaf Chunks        │ • In-Browser WASM Sequence Aligner  │
│ • BitTorrent v2 BEP 52 Swarms    │ • Zero Network Egress Guarantee     │
│ • Cloudflare R2 Fast Viewport    │ • Local-First Variant Interpretation│
└──────────────────────────────────┴─────────────────────────────────────┘

• 16KB Merkle Range Slicing: Fetches genomic sub-regions on demand via HTTP Range Requests and WebRTC P2P chunk exchange, eliminating full file downloads.
• Byzantine-Resilient WebRTC Swarm: Verifies every 16KB leaf chunk against SHA-256 Merkle root proofs before handing bytes to the WASM decoder.
• Physical Air-Gap Isolation (plasmid-vault): User genetic data is pinned to browser-isolated local storage (OPFS / IndexedDB). Outbound network traffic is mathematically restricted to fetching public variant annotation blocks.
• Immutable Clinical Baseline: Pathogenicity classifications from NCBI ClinVar and ACMG guidelines are cryptographically pinned as read-only SSOT tiers, shielding against wiki vandalism.

---

📁 Workspace Crates & Modules

Path	Crates / App	Description
crates/plasmid-format	plasmid-format	128-byte header, SHA-256 Merkle tree (BEP 52), and 32-byte index directory parser.
crates/plasmid-core	plasmid-core	Genomic coordinate query planner, Range Slicing coordinator, and noodles VCF decoder.
crates/plasmid-swarm	plasmid-swarm	WebRTC P2P chunk protocol, RTT-based peer selection, and Byzantine defense engine.
crates/plasmid-cli	plasmid-cli	Official CLI compiler, container inspector, Merkle verifier, and slice query tool.
apps/web	plasmid-web	React 19 + Vite 6 ultra-lightweight client for plasmid.wiki (Pure White monochrome UI).
docs/rfc	RFC Specifications	Formal binary container and air-gap privacy specifications.

---

🚀 Quick Start

1. Build and Test Rust Workspace

# Clone repository
git clone https://github.com/epgeno/plasmid.git
cd plasmid

# Run workspace tests
cargo test --workspace

# Check formatting and clippy
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings

2. Run React 19 Web Client Locally

cd apps/web
pnpm install
pnpm dev

Open http://localhost:5173 in your browser.

3. Using the Plasmid CLI

# Build .plasmid container from VCF, FASTA, and annotations
cargo run -p plasmid-cli -- build --vcf sample.vcf --fasta ref.fa --annotation notes.md -o sample.plasmid

# Inspect container 128B header, metadata, and index entries
cargo run -p plasmid-cli -- inspect sample.plasmid --entries

# Verify cryptographic SHA-256 Merkle tree and 16KB chunk integrity
cargo run -p plasmid-cli -- verify sample.plasmid --verbose

# Perform coordinate range slicing and generate HTTP Range header byte plans
cargo run -p plasmid-cli -- query sample.plasmid --chr chr7 --start 140453100 --end 140453200

---

📜 RFC Specifications

• RFC-0001: .plasmid Single-Container Archive Format: Specification for the PMTiles-like single container packaging genomic indices, 16KB Merkle chunks, and interleaved reference blocks.
• RFC-0002: Privacy, Air-Gap Isolation & Byzantine Defense: Threat modeling, local-first sandbox architecture, and coordinate drift mitigation.
• RFC-0003: Biomedical Data Licensing, IP Governance & Swarm Privacy Safeguards: Public domain whitelisting, proprietary DB exclusion, ODbL copyleft isolation, and k-anonymity coarse pack swarming.

---

🔬 Citation

If you use Plasmid in your academic research or clinical genomics pipelines, please cite:

@software{plasmid2026,
  author = {epgeno contributors},
  title = {Plasmid: Decentralized Genomic Wiki & Merkle Range Slicing Engine},
  url = {https://github.com/epgeno/plasmid},
  version = {0.1.0-alpha},
  year = {2026}
}

---

⚖️ License

Dual-licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.