How plutonomicon/plutarch-plutus works
Project type and purpose
• This is a multi-package Haskell monorepo whose centerpiece is Plutarch, a typed embedded DSL (eDSL) for writing efficient Plutus Core validators.
• Subpackages provide:
• Core eDSL implementation (Plutarch/…)
• Ledger API adapters (plutarch-ledger-api/…)
• Orphan instances & QuickCheck helpers (plutarch-orphanage/…)
• Test harness & golden benchmarks (plutarch-testlib/…)
• Documentation site (plutarch-docs/…)
File structure
• Top‐level: configuration (Cabal, Nix, CI keys), then each subdirectory is a self‐contained Cabal package.
• Core package (Plutarch/…) is organized into layers:
• Public façade modules (BitString.hs, Pair.hs, etc.)
• Built-in symbols & primitive types (Plutarch/Builtin/…)
• Data representation & generic machinery (Plutarch/DataRepr/…)
• Internal combinators & type-level plumbing (Plutarch/Internal/…)
• Pretty-printing & code generation (Plutarch/Pretty/…)
• plutarch-ledger-api: adapters that map Plutarch types to on-chain ledger API types (V1, V2, V3).
• plutarch-orphanage: implements orphan instances for Plutus Ledger types and QuickCheck instances.
• plutarch-testlib: benchmarking, golden tests, QuickCheck laws, scripts generation and evaluation.
• plutarch-docs: markdown sources and literate Haskell examples to build the user/developer guide.
README for additional insights
• Confirms eDSL purpose, efficiency gains versus PlutusTx, and points to benchmarks.
• Encourages reading the guide under plutarch-docs.
Main components & relationships
a. Core eDSL Library (Plutarch)
b. Ledger‐API Adapter (plutarch-ledger-api)
c. Orphan Instances & Test Helpers (plutarch-orphanage)
d. Test & Benchmark Suite (plutarch-testlib)
e. Documentation Generator (plutarch-docs)
f. Build & CI (Cabal, Nix, Hercules)
• Core → produces an AST of UPLC terms and a code generator that emits Plutus Core scripts.
• Ledger‐API Adapter depends on Core to map eDSL types to on-chain types (Address, Tx, Value, etc.).
• Orphanage builds on Ledger‐API Adapter to supply missing instances and QuickCheck utilities.
• Testlib pulls in Core + Ledger‐API + Orphanage to generate, benchmark, and golden-test UPLC output.
• Docs import Core (and sometimes examples from Adapter) to render API docs and tutorials.
Key architectural patterns
• Layered modular design (Core → Adapter → Orphan → Tests)
• eDSL to AST to code generation pipeline
• Separation of concerns: language core vs. on-chain bindings vs. testing vs. docs
• Heavy use of Haskell’s type classes, generic programming, and type-level guarantees
Detail
• Decompose Core into sub-layers to show its internal architecture
• Call out package interdependencies so a reader can trace how new features propagate
• Don’t hesitate to show all four packages plus build infrastructure as distinct nodes