forge-trust-chain 0.3.0

package/src/core/chain.js

@@ -0,0 +1,186 @@
+/**
+ * Chain — Temporal chain of TrustAtoms and Merkle blocks.
+ *
+ * The "page" level: atoms are letters, Merkle trees are sentences,
+ * and the chain is the full document — ordered in time, linked by hashes.
+ *
+ * This is the in-memory runtime. For persistence, see store.
+ */
+
+import { createAtom, verifyAtom, verifyChain, formatAtom } from "./trust-atom.js";
+import { treeFromAtoms, createBlock, getMerkleProof, verifyMerkleProof } from "./merkle.js";
+
+export class TrustChain {
+  constructor(identity) {
+    this.identity = identity;
+    this.atoms = [];
+    this.blocks = [];
+  }
+
+  /* ---- Record ---- */
+
+  /**
+   * Append a new state transition to the chain.
+   */
+  record({ action, from, to }) {
+    const prev =
+      this.atoms.length > 0
+        ? this.atoms[this.atoms.length - 1].proof
+        : "genesis";
+
+    const atom = createAtom({
+      who: this.identity,
+      from,
+      action,
+      to,
+      prev,
+    });
+
+    this.atoms.push(atom);
+    return atom;
+  }
+
+  /**
+   * Seal current atoms into a Merkle block.
+   * Call periodically (e.g. every N atoms or every M seconds).
+   */
+  seal() {
+    if (this.atoms.length === 0) return null;
+
+    const prevBlockHash =
+      this.blocks.length > 0
+        ? this.blocks[this.blocks.length - 1].block_hash
+        : "genesis";
+
+    // Seal only atoms not yet in a block
+    const unsealed = this.atoms.slice(this._lastSealedIndex() + 1);
+    if (unsealed.length === 0) return null;
+
+    const block = createBlock(unsealed, prevBlockHash);
+    block.atom_range = [
+      this._lastSealedIndex() + 1,
+      this.atoms.length - 1,
+    ];
+    this.blocks.push(block);
+    return block;
+  }
+
+  /* ---- Verify ---- */
+
+  /** Verify entire atom chain integrity — O(n). */
+  verify() {
+    return verifyChain(this.atoms);
+  }
+
+  /** Generate Merkle proof for a specific atom index. */
+  proveAtom(globalIndex) {
+    // Find which block contains this atom
+    const block = this.blocks.find(
+      (b) => globalIndex >= b.atom_range[0] && globalIndex <= b.atom_range[1]
+    );
+    if (!block) return null;
+
+    const localIndex = globalIndex - block.atom_range[0];
+    const proof = getMerkleProof(block.layers, localIndex);
+    return {
+      atom: this.atoms[globalIndex],
+      merkle_proof: proof,
+      merkle_root: block.root,
+      block_hash: block.block_hash,
+    };
+  }
+
+  /** Verify a Merkle proof for an atom. */
+  verifyProof(atomProofHash, merkleProof, expectedRoot) {
+    return verifyMerkleProof(atomProofHash, merkleProof, expectedRoot);
+  }
+
+  /* ---- Query ---- */
+
+  get length() {
+    return this.atoms.length;
+  }
+
+  last() {
+    return this.atoms[this.atoms.length - 1] || null;
+  }
+
+  /** Export chain as portable JSON (no raw data). */
+  export() {
+    return {
+      identity_hash: this.atoms[0]?.who || null,
+      atom_count: this.atoms.length,
+      block_count: this.blocks.length,
+      atoms: this.atoms.map(({ _raw, ...a }) => a),
+      blocks: this.blocks.map(({ layers, ...b }) => b),
+      exported_at: Date.now(),
+    };
+  }
+
+  /** Print chain summary to console. */
+  summary() {
+    const lines = [
+      `Chain: ${this.identity}`,
+      `Atoms: ${this.atoms.length}`,
+      `Blocks: ${this.blocks.length}`,
+      `Integrity: ${this.verify().valid ? "✓ VALID" : "✗ BROKEN"}`,
+      "",
+      "Recent atoms:",
+    ];
+    const recent = this.atoms.slice(-5);
+    const offset = this.atoms.length - recent.length;
+    for (let i = 0; i < recent.length; i++) {
+      lines.push("  " + formatAtom(recent[i], offset + i));
+    }
+    return lines.join("\n");
+  }
+
+  /* ---- Internal ---- */
+
+  _lastSealedIndex() {
+    if (this.blocks.length === 0) return -1;
+    return this.blocks[this.blocks.length - 1].atom_range[1];
+  }
+}
+
+/* ================================================================
+   CROSS-CHAIN DISPUTE RESOLUTION
+   ================================================================ */
+
+/**
+ * Compare two chains for the same system and find divergence.
+ * This is the "cryptographic double-entry bookkeeping" from the whitepaper.
+ */
+export function findDivergence(chainA, chainB) {
+  const minLen = Math.min(chainA.atoms.length, chainB.atoms.length);
+
+  for (let i = 0; i < minLen; i++) {
+    const a = chainA.atoms[i];
+    const b = chainB.atoms[i];
+
+    // Same action at same time should produce same from/to hashes
+    if (a.action !== b.action || a.from !== b.from || a.to !== b.to) {
+      return {
+        diverged: true,
+        at_index: i,
+        time_a: a.when,
+        time_b: b.when,
+        action_match: a.action === b.action,
+        state_match: a.from === b.from && a.to === b.to,
+      };
+    }
+  }
+
+  // Length difference = one party has operations the other doesn't
+  if (chainA.atoms.length !== chainB.atoms.length) {
+    return {
+      diverged: true,
+      at_index: minLen,
+      reason: "length_mismatch",
+      length_a: chainA.atoms.length,
+      length_b: chainB.atoms.length,
+    };
+  }
+
+  return { diverged: false };
+}

package/src/core/merkle.js

@@ -0,0 +1,131 @@
+/**
+ * Merkle Tree — Efficient batch verification for TrustAtoms.
+ *
+ * Single atom in batch: O(log n) via Merkle proof
+ * Entire batch:         O(1) via root hash
+ *
+ * This is the "paragraph" level: atoms are letters, Merkle tree is the sentence.
+ */
+
+import { hash } from "./trust-pixel.js";
+
+/* ================================================================
+   BUILD
+   ================================================================ */
+
+/**
+ * Build a Merkle tree from an array of TrustAtom proof hashes.
+ *
+ * Returns { root, layers } where:
+ *   root   = single hash representing the entire batch
+ *   layers = array of arrays, from leaves (bottom) to root (top)
+ */
+export function buildMerkleTree(proofs) {
+  if (proofs.length === 0) return { root: hash("empty"), layers: [[]] };
+  if (proofs.length === 1) return { root: proofs[0], layers: [proofs] };
+
+  const layers = [proofs.slice()]; // layer 0 = leaves
+
+  let current = proofs.slice();
+  while (current.length > 1) {
+    const next = [];
+    for (let i = 0; i < current.length; i += 2) {
+      if (i + 1 < current.length) {
+        next.push(hash(current[i] + current[i + 1]));
+      } else {
+        // Odd node: promote as-is (self-pair)
+        next.push(hash(current[i] + current[i]));
+      }
+    }
+    layers.push(next);
+    current = next;
+  }
+
+  return { root: current[0], layers };
+}
+
+/* ================================================================
+   PROOF — Selective disclosure (ZKP application)
+   ================================================================ */
+
+/**
+ * Generate a Merkle proof for a leaf at given index.
+ *
+ * Returns an array of { hash, direction } pairs.
+ * "direction" tells the verifier which side to concatenate on.
+ */
+export function getMerkleProof(layers, leafIndex) {
+  const proof = [];
+  let idx = leafIndex;
+
+  for (let layer = 0; layer < layers.length - 1; layer++) {
+    const nodes = layers[layer];
+    const isRight = idx % 2 === 1;
+    const siblingIdx = isRight ? idx - 1 : idx + 1;
+
+    if (siblingIdx < nodes.length) {
+      proof.push({
+        hash: nodes[siblingIdx],
+        direction: isRight ? "left" : "right",
+      });
+    } else {
+      // No sibling (odd node), paired with itself
+      proof.push({
+        hash: nodes[idx],
+        direction: isRight ? "left" : "right",
+      });
+    }
+
+    idx = Math.floor(idx / 2);
+  }
+
+  return proof;
+}
+
+/**
+ * Verify a Merkle proof — O(log n).
+ *
+ * Proves that a specific leaf hash belongs to the tree
+ * WITHOUT revealing any other leaves.
+ */
+export function verifyMerkleProof(leafHash, proof, expectedRoot) {
+  let current = leafHash;
+
+  for (const step of proof) {
+    if (step.direction === "left") {
+      current = hash(step.hash + current);
+    } else {
+      current = hash(current + step.hash);
+    }
+  }
+
+  return current === expectedRoot;
+}
+
+/* ================================================================
+   CONVENIENCE
+   ================================================================ */
+
+/**
+ * Build tree from atoms (extracts proof hashes automatically).
+ */
+export function treeFromAtoms(atoms) {
+  return buildMerkleTree(atoms.map((a) => a.proof));
+}
+
+/**
+ * Create a time-block: a Merkle tree with metadata.
+ */
+export function createBlock(atoms, prevBlockHash = "genesis") {
+  const tree = treeFromAtoms(atoms);
+  const blockHash = hash(tree.root + prevBlockHash + Date.now());
+
+  return {
+    root: tree.root,
+    layers: tree.layers,
+    atom_count: atoms.length,
+    prev_block: prevBlockHash,
+    block_hash: blockHash,
+    created_at: Date.now(),
+  };
+}

package/src/core/trust-atom.js

@@ -0,0 +1,125 @@
+/**
+ * TrustAtom — One verifiable state transition.
+ *
+ * A Turing machine's minimum operation: State A → Action → State B
+ * A TrustAtom records exactly this, with identity and chain integrity.
+ *
+ * Structure:
+ *   who     hash(identity)       — who did it
+ *   from    hash(state_before)   — starting state
+ *   action  hash(operation)      — what was done
+ *   to      hash(state_after)    — ending state
+ *   when    timestamp            — when
+ *   prev    previous atom hash   — chain link (array for DAG)
+ *   proof   hash(all above)      — the atom's fingerprint
+ *
+ * Every field is a TrustPixel's hash. The atom itself is a composition.
+ */
+
+import { hash, hashMany, selfWitness } from "./trust-pixel.js";
+
+/* ================================================================
+   CREATE
+   ================================================================ */
+
+/**
+ * @param {object} params
+ * @param {string} params.who       - Identity string (will be hashed)
+ * @param {any}    params.from      - Pre-state (will be hashed)
+ * @param {string} params.action    - Operation description (will be hashed)
+ * @param {any}    params.to        - Post-state (will be hashed)
+ * @param {string|string[]} [params.prev] - Previous atom proof(s), or "genesis"
+ * @returns {object} TrustAtom
+ */
+export function createAtom({ who, from, action, to, prev = "genesis" }) {
+  const when = Date.now();
+
+  // Normalise prev to array (DAG-ready)
+  const prevArr = Array.isArray(prev) ? prev : [prev];
+
+  const atom = {
+    who: hash(who),
+    from: hash(from),
+    action: hash(action),
+    to: hash(to),
+    when,
+    prev: prevArr,
+  };
+
+  // Proof = hash of all fields concatenated in deterministic order
+  atom.proof = hashMany(
+    atom.who,
+    atom.from,
+    atom.action,
+    atom.to,
+    atom.when,
+    ...atom.prev
+  );
+
+  // Keep raw values for debugging / local use (not transmitted)
+  atom._raw = { who, action, when };
+
+  return atom;
+}
+
+/* ================================================================
+   VERIFY
+   ================================================================ */
+
+/** Verify a single atom's self-consistency — O(1). */
+export function verifyAtom(atom) {
+  const expected = hashMany(
+    atom.who,
+    atom.from,
+    atom.action,
+    atom.to,
+    atom.when,
+    ...atom.prev
+  );
+  return expected === atom.proof;
+}
+
+/** Verify a chain of atoms — O(n). */
+export function verifyChain(atoms) {
+  if (atoms.length === 0) return { valid: true, broken_at: -1 };
+
+  for (let i = 0; i < atoms.length; i++) {
+    // 1. Self-consistency
+    if (!verifyAtom(atoms[i])) {
+      return { valid: false, broken_at: i, reason: "proof_mismatch" };
+    }
+
+    // 2. Chain link (skip genesis)
+    if (i > 0) {
+      if (!atoms[i].prev.includes(atoms[i - 1].proof)) {
+        return { valid: false, broken_at: i, reason: "chain_break" };
+      }
+    }
+
+    // 3. Temporal order
+    if (i > 0 && atoms[i].when < atoms[i - 1].when) {
+      return { valid: false, broken_at: i, reason: "time_reversal" };
+    }
+  }
+
+  return { valid: true, broken_at: -1 };
+}
+
+/* ================================================================
+   UTILITY
+   ================================================================ */
+
+/** Strip raw data for transmission (only hashes travel). */
+export function stripAtom(atom) {
+  const { _raw, ...clean } = atom;
+  return clean;
+}
+
+/** Pretty-print an atom for CLI. */
+export function formatAtom(atom, index = 0) {
+  const who = atom._raw?.who || atom.who.slice(0, 12) + "…";
+  const act = atom._raw?.action || atom.action.slice(0, 12) + "…";
+  const time = new Date(atom.when).toISOString();
+  const proof = atom.proof.slice(0, 16) + "…";
+  return `#${index} [${time}] ${who} → ${act}  proof:${proof}`;
+}

package/src/core/trust-pixel.js

@@ -0,0 +1,81 @@
+/**
+ * TrustPixel — The smallest indivisible unit of trust.
+ *
+ * First principle:  Trust = Certainty × Existence
+ *
+ *   Certainty  → SHA-256 hash  (mathematical: deterministic, irreversible)
+ *   Existence  → Witness        (physical: an independent copy survives deletion)
+ *
+ * A hash without a witness can be silently deleted.
+ * A witness without a hash can be forged.
+ * Together they produce an undeniable fact.
+ */
+
+import { createHash } from "node:crypto";
+
+/* ================================================================
+   CERTAINTY  —  the mathematical half
+   ================================================================ */
+
+export function hash(input) {
+  if (input === undefined || input === null) input = "";
+  if (typeof input === "object")
+    input = JSON.stringify(input, Object.keys(input).sort());
+  return createHash("sha256").update(String(input)).digest("hex");
+}
+
+export function hashMany(...parts) {
+  return hash(
+    parts
+      .map((p) =>
+        typeof p === "object" ? JSON.stringify(p, Object.keys(p).sort()) : String(p)
+      )
+      .join("|")
+  );
+}
+
+/* ================================================================
+   EXISTENCE  —  the physical / social half
+   ================================================================ */
+
+export function selfWitness(loc = "local") {
+  return { type: "self", location: loc, at: Date.now() };
+}
+
+export function bilateralWitness(counterparty, loc = "remote") {
+  return { type: "bilateral", counterparty, location: loc, at: Date.now() };
+}
+
+export function publicWitness(service, receipt = null) {
+  return { type: "public", service, receipt, at: Date.now() };
+}
+
+export function anchoredWitness(chain, txid) {
+  return { type: "anchored", chain, txid, at: Date.now() };
+}
+
+/* ================================================================
+   TRUST PIXEL  —  Certainty × Existence
+   ================================================================ */
+
+export function createPixel(content, witnesses) {
+  const h = hash(content);
+  if (!witnesses || witnesses.length === 0) witnesses = [selfWitness()];
+  return { hash: h, witnesses, created_at: Date.now() };
+}
+
+export function verifyPixel(pixel, content) {
+  const certain = hash(content) === pixel.hash;
+  const exists = pixel.witnesses && pixel.witnesses.length > 0;
+  return { valid: certain && exists, certain, exists, strongest: bestWitness(pixel) };
+}
+
+export function bestWitness(pixel) {
+  const rank = { anchored: 4, public: 3, bilateral: 2, self: 1 };
+  let best = { level: 0, label: "none" };
+  for (const w of pixel.witnesses || []) {
+    const r = rank[w.type] || 0;
+    if (r > best.level) best = { level: r, label: w.type };
+  }
+  return best;
+}