Crumpet Media — Technical Architecture (v0 + v0.1)

0) Glossary (ELI5)

• Article package (AOM): a shoebox with an index card, the story, and pictures. Its fingerprint (CID) proves nothing inside has changed.

• CID: IPFS fingerprint; if the content changes, the fingerprint changes.

• Score: Upvotes (counted CRUMBS) minus Downvotes (25/50 CRUMBS).

• Vault: protocol treasury (downvotes, some upvote share, slashed bonds, unrefunded flags).

• Flag: a “please review” deposit. Refunded if DAO takes action; else kept by Vault.

• CIN (Layer‑3 node): a server that fetches articles, builds language search indexes, and serves fast queries. Nodes cross‑check each other so you don’t trust just one.

---

1) Article Object Model (AOM v1)

Package layout (UnixFS folder or CAR):

bashCopyEdit/crumpet.json             # DAG-CBOR manifest (also emitted as JSON for devs)
/body.md                  # Markdown (safe subset)
/preview.html             # OPTIONAL deterministic HTML, trust-but-verify
/media/<hash>.<ext>       # images; referenced by relative paths in body.md

Constraints (v0):

• Max package size: 4 MB

• ≤ 10 images, max 2560px long edge

• No embeds (no iframes/scripts). Images only, bundled locally.

Manifest (JSON view):

jsonCopyEdit{
  "schema": "crumpet.aom/1",
  "article": {
    "title": "string",
    "subtitle": "string?",
    "lang": "en-US",
    "slug": "kebab-case-slug",
    "tags": ["string", "..."],
    "license": "CC-BY-4.0",
    "canonicalUrl": "https://optional.link",
    "createdAt": 0,
    "updatedAt": 0,
    "version": 1,
    "previousCid": "cidV1-or-null",
    "author": { "address": "0xabc...", "display": "string?", "kns": "name.kasplex?" },
    "hashes": {
      "bodyMd": "sha256-hex",
      "previewHtml": "sha256-hex?",
      "assets": { "media/abc.png": "sha256-hex" }
    },
    "metrics": { "estReadingMins": 7, "wordCount": 1200 }
  }
}

Determinism: A reference Rust renderer (WASM in browser). If /preview.html mismatches a local render of /body.md, the client discards it and uses the local render.

---

2) Token‑Economics & User Actions (Single‑Action Rule)

One action per wallet per article. A wallet may perform exactly one among:

• Upvote (with optional extra tip),

• Dislike (−25),

• DownVote (−50),

• Flag (deposit for review).

Once recorded, the wallet cannot perform any other action on that article (no second vote, no flag after voting, etc.). This prevents gaming and ensures fairness.

ELI5: You get one button press per article. Choose wisely.

---

3) Voting & Scoring (Linear, capped; unlimited tips)

DAO‑tunable parameters (timelocked):

• MIN_UP = 10 CRUMBS (minimum to cast an upvote)

• MAX_UP_WEIGHT = 100 CRUMBS (per‑vote counted cap; overflow becomes tip)

• DISLIKE = 25 CRUMBS (counts −25; 100% to Vault)

• DOWNVOTE = 50 CRUMBS (counts −50; 100% to Vault)

Upvote handling (example):

• Send amount. If amount < MIN_UP, revert.

• counted = min(amount, MAX_UP_WEIGHT) → contributes +counted to score.

• tip = amount - counted → extra support, no extra weight.

• Split: of the counted part, 20% to Vault, 80% to Author; 100% of tips to Author.

Down actions:

• Dislike deducts 25 from score; 25 CRUMBS → Vault.

• DownVote deducts 50; 50 CRUMBS → Vault.

Score: score = ∑countedUp − ∑downAmounts.

Why wallet‑split is neutral: cost per counted unit is 1 CRUMBS; the cap is per vote, and you only get one vote per article. Splitting across wallets is Sybil behavior the single‑action rule removes at the origin.

---

4) Flags, Disputes, and Bonds (by time, not blocks)

DAO‑tunable:

• FLAG_FEE = 25 CRUMBS (refunded if action taken)

• FLAGS_TO_OPEN = 3

• GRACE_SECONDS = 10 days (time‑based, not block‑based)

• PUBLISH_BOND = 100 CRUMBS (posted by author on publish)

Lifecycle:

• Publish: author posts B to the contract.

• Flag: any wallet can flag (once per article) by paying F; optional noteCid for context.

  • A flag consumes the one‑action allowance for that wallet on that article.

• Dispute: when a CID has K flags, a case opens.

• Resolve (DAO):

  • Action taken = true: refund F to all flaggers in that case; slash B to Vault (if still before publish.createdAt + GRACE_SECONDS); attach Community Notes (IPFS CIDs).

  • No action: flags kept by Vault; author’s bond auto‑refundable after GRACE_SECONDS.

• Refunds:

  • autoRefundBond(cid) callable by anyone once now ≥ publish.createdAt + GRACE_SECONDS and there’s no upheld action.

  • Flag refunds (on action taken) are pull‑based: each flagger calls claimFlagRefund(caseId).

ELI5: You leave a small deposit when you publish. If a valid complaint is upheld, your deposit is taken. If not, you get it back after ~10 days. Flaggers get their deposit back only if the DAO acts.

---

5) Contracts (Kasplex EVM) — Key Interfaces

Modular, with a separate Config contract (DAO‑timelocked). Events are explicit for indexers and analytics.

5.1 ArticlesRegistry

solidityCopyEditevent ArticlePublished(address indexed author, bytes32 cid, uint256 version, bytes32 prevCid, uint256 createdAt);

function publish(bytes32 cid, uint256 version, bytes32 prevCid) external; // requires PUBLISH_BOND

5.2 Actions (Upvote/Down/Flag) with Single‑Action Enforcement

solidityCopyEditenum Action { None, Upvote, Dislike, Downvote, Flag } // exactly one per (wallet, cid)

mapping(bytes32 => mapping(address => Action)) public actionOf; // cid => wallet => action

event Upvoted(bytes32 indexed cid, address indexed voter, uint256 amount, uint256 counted, uint256 tip, uint256 toAuthor, uint256 toVault);
event Downvoted(bytes32 indexed cid, address indexed voter, uint256 amount);    // amount ∈ {DISLIKE, DOWNVOTE}
event Flagged(bytes32 indexed cid, address indexed by, bytes32 noteCid);

function upvote(bytes32 cid, uint256 amount) external;    // require actionOf[cid][msg.sender]==None
function dislike(bytes32 cid) external;                   // require None
function downvote(bytes32 cid) external;                  // require None
function flag(bytes32 cid, bytes32 noteCid) external;     // require None

function scoreOf(bytes32 cid) external view returns (int256);
function upWeightOf(bytes32 cid) external view returns (uint256);
function downWeightOf(bytes32 cid) external view returns (uint256);

5.3 Disputes & Bonds (time‑based grace)

solidityCopyEditevent DisputeOpened(bytes32 indexed cid, uint256 caseId);
event DisputeResolved(uint256 caseId, bool actionTaken, bytes32[] notes);
event BondRefunded(bytes32 indexed cid, address to, uint256 amount);
event BondSlashed(bytes32 indexed cid, uint256 amount);

function resolveDispute(uint256 caseId, bool actionTaken, bytes32[] calldata notes) external; // DAO
function autoRefundBond(bytes32 cid) external;
function claimFlagRefund(uint256 caseId) external;

5.4 Vault & Node Rewards

• Vault accrues: 20% counted upvotes, 100% downvotes, unrefunded flags, slashed bonds.

• DAO allocates up to 40% of Vault net inflows to Node Rewards Pool.

5.5 Config (DAO‑timelocked)

• Parameters: MIN_UP, MAX_UP_WEIGHT, DISLIKE, DOWNVOTE, FLAG_FEE, FLAGS_TO_OPEN, GRACE_SECONDS, PUBLISH_BOND, NodeRewards splits/percentages.

• Emits ConfigChanged(...).

---

6) Layer‑3: CIN Nodes (Storage + Indexing + Serving)

6.1 Protocols & Transport (low‑latency, modern)

• Node↔Node (control/data):

  • gRPC over HTTP/2 (Rust tonic) for control plane (snapshots, health, attestations).

  • libp2p (Noise) over QUIC for P2P gossip (language snapshot announcements) and fast peer discovery.

  • HTTP/3 (QUIC) and IPFS for snapshot/package transfers (concurrent range fetches).

• Node↔UI (client apps):

  • HTTP/2 JSON API (search/article/trending).

  • WebSocket streams for live updates (/ws/events), low latency.

  • Optional gRPC‑Web (via Envoy) if you prefer a single RPC stack in the browser.

ELI5: We use the fast lanes on the internet (HTTP/2, QUIC, WebSockets, gRPC) so searches feel instant and nodes share data quickly.

6.2 Federation & Integrity (language‑sharded)

• Each node builds per‑language index segments for its primary languages (en, de, …).

• Nodes fetch signed snapshots for other languages from peers, requiring 2‑of‑3 matching Merkle roots.

• Regular CID spot checks verify fetched segments aren’t lying.

• Snapshots record renderer/analyzer versions; mismatches are rejected.

6.3 Incentives (from Vault)

• Node Rewards Pool gets up to 40% of Vault net inflows (DAO‑tunable).

• Epoch payouts (e.g., weekly):

  • 40% Uptime share — pass SLA probes.

  • 40% Build share — # of language snapshots built that achieved majority/committee acceptance.

  • 20% Serve share — optional, via hashed “served” receipts (rate‑limited to prevent gaming).

6.4 Hardware targets

• Builder (2 languages): 2 vCPU, 4–8 GB RAM, 100 GB SSD, local IPFS node.

• Fetcher/serve‑only: 2 vCPU, 4 GB RAM, 50 GB SSD.

• Pruning: retain last N snapshots; older on IPFS.

6.5 Node APIs

HTTP/2 JSON:

bashCopyEditGET /v1/search?q=...&lang=en&sort=top|trending|new&from=0&size=20
GET /v1/article/{cid}
GET /v1/trending?lang=en&window=24h|7d
GET /v1/snapshot/{lang}/latest
GET /v1/health
WS  /v1/ws/events    # live article/vote/flag feed

gRPC (excerpt, proto sketch):

protoCopyEditservice CrumpetControl {
  rpc Health(HealthRequest) returns (HealthResponse);
  rpc AnnounceSnapshot(AnnounceReq) returns (AnnounceAck); // includes lang, root, range, ipfsCid, sig
  rpc GetSnapshotMeta(SnapshotMetaReq) returns (SnapshotMeta);
  rpc AttestSnapshot(AttestReq) returns (AttestAck);       // peer cross-check attestations
}

---

7) Frontend & UX

• Next.js + TypeScript, wagmi/RainbowKit on Kasplex EVM.

• Renderer: Rust→WASM; Sanitizer: strict allow‑list.

• Service Worker: cache AOM packages; multi‑source fetch race (local IPFS → node cache → gateways).

• Publish UX: require 3 IPFS pin‑acks before enabling on‑chain publish.

• Vote UX: show one chooser (Upvote/Dislike/DownVote/Flag). After selection, lock UI.

• Dispute UX: show label and Community Notes if action taken; do not remove content.

---

8) Internationalization

• lang required in manifest.

• Day‑1 analyzers: EN, DE, ES, FR, PT, IT, NL, PL, TR, RU, ZH‑Hans, ZH‑Hant, JA, KO, AR, HI.

• Browsers’ built‑in translation works (plain HTML).

• Adding languages = add analyzer + tests (no AOM change).

---

9) Security & Best Practices

• Contracts: Reentrancy guards, Checks‑Effects‑Interactions, SafeERC20, pull refunds (flags).

• Governance: Timelock on Config; multisig; parameter change rate limits.

• Time sources: use block.timestamp as wall‑clock for GRACE_SECONDS. Avoid assuming fixed block cadence.

• Indexers: reject snapshots with renderer/analyzer major version mismatches; keep a denylist of malicious peers.

• Content: validate image types/sizes; strip scripts/event handlers; forbid external‐scheme links.

---

10) Examples & Edge Cases

Single‑action constraint:

• If a wallet Upvoted, it cannot later Dislike, DownVote, or Flag.

• If a wallet Flagged, it cannot later Upvote or DownVote.

• Attempts revert with AlreadyActed().

Upvote overflow:

• Send 120 CRUMBS → counted 100, tip 20; one vote recorded; can’t vote again.

Flags & refunds:

• Case opened at 3 flags.

• DAO action taken: flaggers each call claimFlagRefund (25 back).

• No action within 10 days: author’s autoRefundBond succeeds; flags stay in Vault.

Article updates:

• New edition = new CID; previousCid links history. Scores are per‑edition; UI may aggregate.

---

11) Parameter Table (initial defaults)

Parameter	Default	Notes
MIN_UP	10 CRUMBS	per vote minimum
MAX_UP_WEIGHT	100 CRUMBS	per vote cap for counted weight
DISLIKE	25 CRUMBS	−25; 100% to Vault
DOWNVOTE	50 CRUMBS	−50; 100% to Vault
Upvote split	20% of counted → Vault	80% counted + 100% tips → Author
FLAG_FEE	25 CRUMBS	refunded iff action taken
FLAGS_TO_OPEN	3	threshold to open case
GRACE_SECONDS	10 days	time‑based
PUBLISH_BOND	100 CRUMBS	slashed on action within grace
Node Rewards Pool	up to 40% Vault net inflow	DAO‑tunable
Node split	40% uptime / 40% build / 20% serve	DAO‑tunable

---

12) Repo Skeleton

bashCopyEditcrumpet/
├─ contracts/
│  ├─ ArticlesRegistry.sol
│  ├─ Actions.sol                 # Upvote/Dislike/Downvote/Flag (single-action rule)
│  ├─ Disputes.sol                # flags, cases, resolve, refunds, bonds
│  ├─ Vault.sol                   # inflows/outflows (Node Rewards)
│  ├─ NodeRewards.sol             # epoch accounting & payouts
│  ├─ Config.sol                  # DAO-timelocked parameters
│  └─ interfaces/                 # I* interfaces
│
├─ schemas/
│  ├─ aom-v1.schema.json
│  └─ examples/
│     ├─ minimal/
│     └─ images-heavy/
│
├─ crates/                        # Rust workspace
│  ├─ renderer/                   # deterministic Markdown→HTML + sanitizer (WASM target)
│  ├─ aom/                        # package verify (hashes, constraints), CAR/UnixFS helpers
│  ├─ indexer/                    # Tantivy + analyzers; build per-language segments
│  ├─ node/                       # CIN daemon: ingest, gossip, snapshots, HTTP/gRPC servers
│  └─ proto/                      # .proto files + tonic build
│
├─ apps/
│  └─ web/                        # Next.js 15, wagmi, IPFS client, SW cache
│     ├─ src/
│     │  ├─ lib/ipfs.ts
│     │  ├─ lib/crumpet-sdk.ts    # client for node HTTP/gRPC-Web
│     │  ├─ components/
│     │  └─ pages/
│     └─ public/
│
├─ packages/
│  └─ sdk-js/                     # TypeScript SDK: search, article, trending, snapshots
│
├─ infra/
│  ├─ docker/                     # Dockerfiles for node, renderer-build, indexer
│  ├─ helm/                       # K8s charts
│  └─ compose/                    # docker-compose for local multi-node
│
├─ tests/
│  ├─ contracts/                  # hardhat/foundry tests
│  ├─ renderer/                   # golden vectors
│  ├─ indexer/                    # determinism, perf
│  └─ e2e/                        # full publish→search flows
│
├─ CONTRIBUTING.md
├─ README.md
└─ LICENSE

Example proto (snippet)

protoCopyEditsyntax = "proto3";
package crumpet.v1;

service CrumpetControl {
  rpc Health(HealthRequest) returns (HealthResponse);
  rpc AnnounceSnapshot(AnnounceReq) returns (AnnounceAck);
  rpc GetSnapshotMeta(SnapshotMetaReq) returns (SnapshotMeta);
  rpc AttestSnapshot(AttestReq) returns (AttestAck);
}

message HealthRequest {}
message HealthResponse { string status = 1; string version = 2; }

message AnnounceReq {
  string lang = 1;
  string ipfsCid = 2;
  bytes  merkleRoot = 3;
  string blockRange = 4;     // e.g., "t0..tN" or anchoring tx ids
  string analyzerVer = 5;
  string rendererVer = 6;
  bytes  nodeSignature = 7;  // ed25519 over (lang|root|cid|range|vers)
}
message AnnounceAck { bool accepted = 1; string reason = 2; }

---

13) CONTRIBUTING.md (short)

Coding standards

• Contracts: Solidity ^0.8.24, NatSpec, events for all state changes, Foundry tests (unit/fuzz/invariant), Slither/Static analysis in CI.

• Rust: stable toolchain, clippy clean, rustfmt, property tests where applicable, no unsafe unless justified.

• TypeScript: strict TS, ESLint+Prettier, never ignore types for chain amounts; use BigInt/ethers.js BigNumber.

Testing

• Contracts: 100% branch coverage targets for Actions/Disputes/Vault; reentrancy + refund invariants.

• Renderer: golden vectors, sanitizer adversarial cases (XSS payload corpus).

• Indexer: determinism checks (same inputs → identical snapshot roots), multilingual tokenizer tests, p95 latency benchmarks.

Security

• No external calls before state changes (CEI).

• Use pull patterns for refunds (flags).

• Limit parameter change rates in Config.

• Document threat models (Sybil, brigading, snapshot forgery).

CI

• Lint, build, test (contracts, Rust, web).

• Snapshot reproducibility check on deterministic inputs.

• Container image builds & SBOM.

---

14) Engineer Hand‑off Checklist

• Deploy Config with initial parameters (table above).

• Deploy ArticlesRegistry, Actions, Disputes, Vault, NodeRewards.

• Spin up 3+ pinning peers (multiaddrs published).

• Launch 2–3 CIN nodes (different operators) with different primary languages; enable gossip & attest.

• Publish renderer test vectors and verify /preview.html round‑trip.

• Frontend: wire publish flow (3 pin‑acks gate), the single‑action chooser, and dispute labels.

---

Final notes

• Single‑action rule is enforced on‑chain and reflected in UI (buttons lock after an action).

• Grace periods are time‑based (GRACE_SECONDS) so they work with a based rollup.

• Connectivity uses gRPC/HTTP2/WebSockets/QUIC for speed; libp2p gossip advertises snapshots; IPFS (HTTP/3 where available) moves the bytes.

• Everything is DAO‑tunable with a timelock; indexers include the active parameter set in snapshot metadata.