# Plutia — Verifiable PLC Mirror

Repository: [https://github.com/Fuwn/plutia](https://github.com/Fuwn/plutia)
License: MIT OR Apache-2.0

## Project Overview

Plutia is a high-performance, verifiable alternative mirror for plc.directory.

It must support two configurable operating modes:

1. Resolver Mode (lightweight, state-only)
2. Mirror Mode (full historical archive + verifiable proofs)

Plutia is intended to be a production-grade, decentralization-focused infrastructure component capable of becoming a trusted first-choice mirror to plc.directory.

The implementation must prioritize:

* Deterministic data handling
* Cryptographic correctness
* Append-only integrity guarantees
* Efficient disk usage (single-digit GB footprint for full mirror)
* Static Go binaries
* Clean modular architecture
* Reproducibility
* Long-term maintainability

The implementation language is Go.

---

## Design Goals

1. Eliminate Postgres/WAL/index overhead seen in existing plc-mirror implementations.
2. Store historical operations in compressed append-only block files.
3. Maintain a minimal KV state store for current DID resolution.
4. Provide verifiable proofs of inclusion and integrity.
5. Allow configurable verification policy.
6. Produce signed checkpoints to prevent equivocation.
7. Be able to operate on modest VPS instances (20–40GB disk).
8. Be horizontally extensible later (replication / gossip optional future).

---

## Operating Modes

Configurable via YAML OR environment variables:

mode: resolver | mirror

### Resolver Mode

Stores only:

* did -> latest operation reference
* did -> materialized DID document
* did -> chain tip hash

Does not retain full historical chain.

Intended footprint: 1–3GB.

### Mirror Mode

Stores:

* Full operation history
* Compressed append-only operation blocks
* Minimal index mapping op sequence and DID chains
* Signed checkpoints
* State KV store (same as resolver mode)

Intended footprint: ~4–6GB total.

---

## Storage Architecture

### 1) Append-Only Operation Log (Mirror Mode Only)

Directory layout:

data/
ops/
000001.zst
000002.zst
index/
state/
checkpoints/

Each block file:

* Contains multiple operations
* Each operation is canonicalized JSON bytes
* Stored as:
  [varint length][operation bytes]
* Block compressed with zstd
* Block hash recorded in index

Block size target: 4–16MB uncompressed before compression.

Compression: zstd level configurable (default level 9).

### 2) KV State Store

Use Pebble (github.com/cockroachdb/pebble).

Keys:

did:{did} -> serialized current state struct
opseq:{global_seq} -> block_ref (block_id, offset, length)
chain:{did} -> latest op sequence
block:{block_id} -> block hash
meta:global_seq -> uint64
meta:mode -> resolver | mirror

Value structures must be versioned.

### 3) Canonicalization

Operations must be:

* Deterministically encoded
* Signature-verifiable
* Stored exactly as received except whitespace normalization

No reordering of fields that would invalidate signature material.

---

## Verification Policy

Configurable:

verify: full | lazy | state-only

full:

* Verify each operation upon ingestion.
* Validate signature chain.
* Validate prev CID linkage.

lazy:

* Store raw ops.
* Verify on-demand and in background.

state-only:

* Verify only latest operation for each DID.

Verification must use ed25519 via standard Go crypto libraries.

---

## Checkpoint System

Every N operations (configurable, default 100000):

Produce checkpoint:

{
sequence: uint64,
timestamp: RFC3339,
did_merkle_root: hash,
block_merkle_root: hash,
previous_checkpoint_hash: hash
}

Checkpoint is:

* Serialized deterministically
* Signed with mirror private key
* Stored under data/checkpoints/
* Exposed via API

Merkle tree:

* Leaves = hash(did + chain_tip_hash)
* Tree hash = sha256

Purpose:

* Allow external clients to verify inclusion.
* Detect equivocation.
* Enable mirror-to-mirror comparison.

---

## API Surface

HTTP server using net/http.

Endpoints:

GET /health
GET /metrics
GET /did/{did}
GET /did/{did}/proof
GET /checkpoints/latest
GET /checkpoints/{sequence}
GET /status

Resolver response includes:

{
did_document,
chain_tip_hash,
checkpoint_reference
}

Proof endpoint includes:

* Chain proof or chain tip reference
* Merkle inclusion proof
* Checkpoint signature

---

## Ingestion

Source: [https://plc.directory](https://plc.directory)

Plutia must support:

* Poll-based ingestion
* Replay from genesis
* Resume from stored sequence
* Graceful recovery

Concurrency model:

* Single ingestion pipeline
* Buffered channel for block assembly
* Background checkpointing

---

## Configuration

config.yaml:

mode: mirror
data_dir: ./data
plc_source: [https://plc.directory](https://plc.directory)
verify: full
zstd_level: 9
block_size_mb: 8
checkpoint_interval: 100000
listen_addr: :8080
mirror_private_key_path: ./mirror.key

---

## Project Structure

plutia/
cmd/plutia/main.go
internal/config/
internal/ingest/
internal/storage/
internal/state/
internal/checkpoint/
internal/merkle/
internal/api/
internal/verify/
internal/types/
pkg/proof/
go.mod

Clean separation:

* Storage interface
* Verification logic
* API layer
* Merkle logic
* Ingestion logic

---

## Performance Requirements

* Memory footprint under 1GB for mirror mode.
* No relational database.
* Efficient sequential disk writes.
* Minimal random IO.
* Backpressure-aware ingestion.
* Safe shutdown with flush.

---

## Security Requirements

* No unsafe deserialization.
* Deterministic hashing.
* Signature verification strict.
* Refuse malformed operations.
* No silent chain truncation.
* Checkpoint signing key rotation supported.

---

## CLI

plutia serve --config=config.yaml
plutia verify --did=did:plc:xyz
plutia snapshot
plutia replay

---

## Testing Requirements

* Unit tests for:

  * Canonical encoding
  * Signature verification
  * Merkle tree correctness
  * Block encoding/decoding
* Integration test:

  * Replay small PLC sample dataset
  * Verify final state correctness

---

## Deliverables

The Codex agent must:

1. Initialize Go module.
2. Implement storage layer with Pebble.
3. Implement append-only block writer with zstd.
4. Implement state KV logic.
5. Implement verification engine.
6. Implement Merkle + checkpoint system.
7. Implement HTTP API.
8. Provide README explaining usage.
9. Provide sample config.yaml.
10. Ensure build via:
    go build ./cmd/plutia

---

## Non-Goals (for v1)

* Gossip between mirrors
* Distributed clustering
* UI
* Advanced analytics
* Horizontal sharding

---

## Core Principle

Plutia must be:

* Smaller than Postgres-based mirrors
* Deterministic
* Tamper-evident
* Efficient
* Trustworthy

It should be credible as a first-choice alternative to plc.directory.

---

End of specification.