stepper-sdk 0.1.0

package/lib/chain/verify.js

@@ -0,0 +1,128 @@
+/**
+ * verify.js — replay a chip's whole history and check the chain agrees.
+ *
+ * This is the one function in the package that is worth installing it for.
+ *
+ * A STEPPER chip is deterministic and its inputs are all public. `program()`
+ * returns the ROM. Every `step()` emits `Stepped(sponsor, cycle, outPort,
+ * inValue)`, so the log carries the byte that went in and the cycle it went in
+ * on. ROM plus those events is the complete tape a deterministic machine ran
+ * on — which means the entire history can be recomputed from scratch by
+ * anybody, on their own machine, and compared against what the contract now
+ * says about itself.
+ *
+ * Two claims are checked, and the second is the stronger one:
+ *
+ *   The end state matches. Cycle, program counter, output port and all three
+ *   flags, against `snapshot()`.
+ *
+ *   Every intermediate step matches. The output port the contract logged on
+ *   cycle N is compared with the output port this netlist produces on cycle N,
+ *   for every N. A chip whose final state happened to agree but whose history
+ *   did not would fail here, and that is exactly the chip worth catching.
+ *
+ * Nothing in here trusts us. The netlist is in the package, the events come
+ * from whatever node the caller names, and the arithmetic happens locally. A
+ * false answer would require the reader's own copy of the processor to be
+ * wrong, which is what `npm run silicon` exists to rule out.
+ */
+
+"use strict";
+
+var machine = require("../netlist/machine.js");
+var chain = require("./chain.js");
+
+/**
+ * @param {string} address  the chip
+ * @param {object} [opts]   { rpc, window, fromBlock }
+ * @returns {Promise<object>} the verdict, with everything it rests on
+ */
+async function verify(address, opts) {
+  var o = opts || {};
+
+  var chip = await chain.readChip(address, o);
+  var logs = await chain.history(address, {
+    rpc: o.rpc,
+    window: o.window,
+    fromBlock: o.fromBlock,
+    expect: chip.cycle,
+  });
+
+  var problems = [];
+
+  /* A machine that has taken N cycles emitted N events. Fewer means the scan
+     did not reach far enough back or the chain is missing something; more
+     means something is emitting events that are not cycles. Either way the
+     replay below would be running on the wrong tape, so it is refused rather
+     than reported as a mismatch. */
+  if (logs.length !== chip.cycle) {
+    problems.push(chip.cycle + " cycles on chain but " + logs.length +
+      " Stepped events found");
+  }
+
+  /* The cycles must be 1..N with nothing missing and nothing twice. */
+  for (var i = 0; i < logs.length; i++) {
+    if (logs[i].cycle !== i + 1) {
+      problems.push("cycle " + (i + 1) + " is missing or out of order");
+      break;
+    }
+  }
+
+  if (problems.length) {
+    return {
+      ok: false, address: address, onChain: chip,
+      cyclesReplayed: 0, events: logs.length, problems: problems,
+    };
+  }
+
+  /* The replay. One event, one clock edge, in the order they were mined. */
+  var D = machine.loadNetlist();
+  var m = new machine.Machine(D, chip.rom);
+  var firstMismatch = null;
+
+  for (i = 0; i < logs.length; i++) {
+    m.inPort = logs[i].inValue;
+    m.step();
+    if (firstMismatch === null && m.out() !== logs[i].outPort) {
+      firstMismatch = {
+        cycle: logs[i].cycle,
+        chain: logs[i].outPort,
+        replay: m.out(),
+        tx: logs[i].tx,
+      };
+    }
+  }
+
+  if (firstMismatch) {
+    problems.push("cycle " + firstMismatch.cycle + ": the chain logged output " +
+      firstMismatch.chain + ", this netlist produces " + firstMismatch.replay);
+  }
+
+  /* And the state the contract reports right now. */
+  var ended = {
+    cycle: m.cycle, pc: m.pc(), out: m.out(),
+    carry: !!m.carry(), zero: !!m.zero(), halted: m.halted(),
+  };
+  ["cycle", "pc", "out", "carry", "zero", "halted"].forEach(function (k) {
+    if (ended[k] !== chip[k]) {
+      problems.push("final " + k + ": chain says " + chip[k] + ", replay says " + ended[k]);
+    }
+  });
+
+  return {
+    ok: problems.length === 0,
+    address: address,
+    cyclesReplayed: logs.length,
+    events: logs.length,
+    gates: D.gateCount,
+    onChain: {
+      cycle: chip.cycle, pc: chip.pc, out: chip.out,
+      carry: chip.carry, zero: chip.zero, halted: chip.halted,
+    },
+    replayed: ended,
+    firstMismatch: firstMismatch,
+    problems: problems,
+  };
+}
+
+module.exports = { verify: verify };

package/lib/netlist/asm.js

@@ -0,0 +1,184 @@
+/**
+ * asm.js — the ST-8 assembler, and the two programs the site ships.
+ *
+ * A word is 25 bits: [24:20] op · [19:16] rd · [15:12] rs · [11:0] imm/addr.
+ * Nothing clever happens here — one line becomes one word — but the listing
+ * it produces is what the ROM panel on the site renders, so the assembler is
+ * also the thing that keeps the listing honest about what is executing.
+ */
+
+"use strict";
+
+var OP = require("./st8.js").OP;
+
+var FORMS = {
+  nop: "none", hlt: "none",
+  not: "rd", shl: "rd", shr: "rd", rol: "rd", ror: "rd",
+  inc: "rd", dec: "rd", in: "rd", out: "rd",
+  mov: "rr", add: "rr", adc: "rr", sub: "rr", sbb: "rr",
+  and: "rr", or: "rr", xor: "rr", nand: "rr", cmp: "rr",
+  ldi: "imm",
+  ld: "load", st: "store",
+  jmp: "addr", jz: "addr", jnz: "addr", jc: "addr", jnc: "addr",
+  tst: "rr", swap: "rd", jmpr: "rd",
+};
+
+function reg(tok, line) {
+  var m = /^r(\d{1,2})$/i.exec(String(tok).trim());
+  if (!m) throw new Error("line " + line + ": expected a register, got '" + tok + "'");
+  var n = +m[1];
+  if (n > 15) throw new Error("line " + line + ": r" + n + " does not exist");
+  return n;
+}
+
+function imm(tok, line, max) {
+  var t = String(tok).trim().replace(/^#/, "");
+  var n = /^0x/i.test(t) ? parseInt(t, 16) : parseInt(t, 10);
+  if (!Number.isFinite(n)) throw new Error("line " + line + ": bad number '" + tok + "'");
+  if (n < 0 || n > max) throw new Error("line " + line + ": " + n + " out of range 0.." + max);
+  return n;
+}
+
+/**
+ * Two passes: collect labels, then encode. A label may be used before it is
+ * defined, which is the only reason a forward jump is writable at all.
+ */
+function assemble(source) {
+  var raw = source.split("\n");
+  var labels = {};
+  var stmts = [];
+
+  raw.forEach(function (text, n) {
+    var line = text.replace(/;.*$/, "").trim();
+    while (line) {
+      var lm = /^([A-Za-z_][A-Za-z0-9_]*)\s*:\s*/.exec(line);
+      if (!lm) break;
+      labels[lm[1]] = stmts.length;
+      line = line.slice(lm[0].length).trim();
+    }
+    if (line) stmts.push({ text: line, line: n + 1 });
+  });
+
+  if (stmts.length > 1024) throw new Error("program exceeds 1,024 words of ROM");
+
+  var rom = new Array(1024).fill(0);
+  var listing = [];
+
+  stmts.forEach(function (st, pc) {
+    var m = /^([A-Za-z]+)\s*(.*)$/.exec(st.text);
+    if (!m) throw new Error("line " + st.line + ": cannot parse '" + st.text + "'");
+    var mn = m[1].toLowerCase();
+    var rest = m[2].trim();
+    var form = FORMS[mn];
+    if (!form) throw new Error("line " + st.line + ": unknown instruction '" + mn + "'");
+
+    var op = OP[mn.toUpperCase()];
+    var rd = 0, rs = 0, field = 0, mm;
+
+    if (form === "rd") {
+      rd = reg(rest, st.line);
+    } else if (form === "rr") {
+      mm = rest.split(",");
+      if (mm.length !== 2) throw new Error("line " + st.line + ": expected 'rd, rs'");
+      rd = reg(mm[0], st.line);
+      rs = reg(mm[1], st.line);
+    } else if (form === "imm") {
+      mm = rest.split(",");
+      if (mm.length !== 2) throw new Error("line " + st.line + ": expected 'rd, #imm'");
+      rd = reg(mm[0], st.line);
+      field = imm(mm[1], st.line, 255);
+    } else if (form === "load") {
+      mm = /^(r\d{1,2})\s*,\s*\[\s*(r\d{1,2})\s*\]$/i.exec(rest);
+      if (!mm) throw new Error("line " + st.line + ": expected 'ld rd, [rs]'");
+      rd = reg(mm[1], st.line);
+      rs = reg(mm[2], st.line);
+    } else if (form === "store") {
+      mm = /^\[\s*(r\d{1,2})\s*\]\s*,\s*(r\d{1,2})$/i.exec(rest);
+      if (!mm) throw new Error("line " + st.line + ": expected 'st [rd], rs'");
+      rd = reg(mm[1], st.line);
+      rs = reg(mm[2], st.line);
+    } else if (form === "addr") {
+      if (Object.prototype.hasOwnProperty.call(labels, rest)) field = labels[rest];
+      else field = imm(rest, st.line, 1023);
+    }
+
+    var word = ((op & 0x1f) << 20) | ((rd & 0xf) << 16) | ((rs & 0xf) << 12) | (field & 0xfff);
+    rom[pc] = word >>> 0;
+    listing.push({
+      pc: pc,
+      hex: word.toString(16).padStart(7, "0"),
+      src: st.text.replace(/\s+/g, " "),
+    });
+  });
+
+  return { rom: rom, labels: labels, listing: listing };
+}
+
+/* --------------------------------------------------------------- programs */
+
+/**
+ * ledger — what chip #1 carries, and it runs forever.
+ *
+ * The output port shows whatever byte the sponsor of this cycle sent, r2 holds
+ * the sum of every byte the chip was ever given, and RAM keeps the trace. So
+ * what the machine accumulates is a record of who has been paying to run it,
+ * which is the reason it is called a ledger rather than an echo.
+ *
+ * It must never halt, so there is no `hlt` in it and every path returns to
+ * the loop. The build refuses to ship if it ever stops.
+ */
+var LEDGER = [
+  "        ldi r2, #0        ; running sum of every byte ever sent",
+  "        ldi r3, #0        ; where in RAM the next sample lands",
+  "loop:   in  r0            ; the byte whoever paid for this step sent",
+  "        out r0            ; echo it straight back to the output port",
+  "        add r2, r0        ; fold it into the sum",
+  "        mov r1, r2",
+  "        st  [r3], r1      ; keep a trace of it in RAM",
+  "        inc r3            ; wrap at 256 and start overwriting",
+  "        jmp loop",
+].join("\n");
+
+/**
+ * selftest — exercises the ALU, both flags, the shifter and a RAM round trip,
+ * then halts on purpose. Any failure jumps to `fail`, which puts 255 on the
+ * output port, so a wrong answer is visible on the LEDs rather than silent.
+ */
+var SELFTEST = [
+  "        ldi r0, #200",
+  "        ldi r1, #100",
+  "        add r0, r1        ; 300 wraps to 44 and sets carry",
+  "        jnc fail",
+  "        out r0",
+  "        ldi r2, #44",
+  "        cmp r0, r2        ; equal, so Z",
+  "        jnz fail",
+  "        ldi r3, #0xf0",
+  "        ldi r4, #0x0f",
+  "        or  r3, r4        ; 0xff",
+  "        out r3",
+  "        not r3            ; 0x00, so Z",
+  "        jnz fail",
+  "        ldi r5, #1",
+  "        shl r5",
+  "        shl r5            ; 4",
+  "        ldi r6, #4",
+  "        cmp r5, r6",
+  "        jnz fail",
+  "        ldi r7, #16",
+  "        ldi r8, #123",
+  "        st  [r7], r8      ; write it",
+  "        ld  r9, [r7]      ; read it back — two honest cycles",
+  "        cmp r9, r8",
+  "        jnz fail",
+  "        out r9",
+  "        hlt",
+  "fail:   ldi r0, #255",
+  "        out r0",
+  "        hlt",
+].join("\n");
+
+module.exports = {
+  assemble: assemble,
+  sources: { ledger: LEDGER, selftest: SELFTEST },
+};

package/lib/netlist/machine.js

@@ -0,0 +1,116 @@
+/**
+ * machine.js — the ST-8 netlist, evaluated.
+ *
+ * This is the processor as a library: load the gate table, drive the inputs,
+ * evaluate every gate in topological order, latch every flip-flop at once.
+ * Nothing here prints, exits, or reads an argument.
+ *
+ * It lives on its own rather than inside the runner because three things need
+ * it now — the terminal runner, the published CLI and the SDK — and a
+ * processor that exists in three copies is three processors. Only one of them
+ * would be the one `npm run silicon` verified.
+ */
+
+"use strict";
+
+var fs = require("node:fs");
+var path = require("node:path");
+
+/**
+ * st8-data.js is written for a browser, so it assigns to `window`. Handing it
+ * an object called window is the whole of the port.
+ *
+ * It is looked for in every place this file is ever installed: under public/
+ * in the repository, and beside lib/ in a published package. Searching costs
+ * one stat per candidate and saves keeping a second loader in step.
+ */
+function loadNetlist() {
+  var places = [
+    path.join(__dirname, "..", "..", "public", "scripts", "st8-data.js"),
+    path.join(__dirname, "..", "st8-data.js"),
+    path.join(__dirname, "st8-data.js"),
+  ];
+  var file = places.filter(function (p) { return fs.existsSync(p); })[0];
+  if (!file) {
+    throw new Error("st8-data.js is missing. Run `npm run silicon` first.");
+  }
+  var win = {};
+  new Function("window", fs.readFileSync(file, "utf8"))(win);
+  return win.ST8_DATA;
+}
+/* ------------------------------------------------------------- the machine
+ *
+ * Identical in behaviour to public/scripts/machine.js: drive the inputs,
+ * evaluate every gate in the order the topological sort fixed, then latch
+ * every flip-flop at once. Kept as a separate copy on purpose: if the two
+ * ever disagree, one of them is wrong, and `npm run silicon` checks them
+ * against a third independent model on every build.
+ */
+
+function Machine(D, rom) {
+  this.D = D;
+  this.rom = rom;
+  this.v = new Uint8Array(D.nets);
+  this.next = new Uint8Array(D.flopCount);
+  this.ram = new Uint8Array(256);
+  this.inPort = 0;
+  this.cycle = 0;
+  this.switched = 0;
+  this.v[D.one] = 1;
+}
+
+Machine.prototype.flop = function (i) { return this.v[this.D.flops[2 * i + 1]]; };
+Machine.prototype.field = function (bits) {
+  let n = 0;
+  for (let i = 0; i < bits.length; i++) n |= this.flop(bits[i]) << i;
+  return n;
+};
+Machine.prototype.pc = function () { return this.field(this.D.pc); };
+Machine.prototype.out = function () { return this.field(this.D.out); };
+Machine.prototype.reg = function (r) { return this.field(this.D.regs[r]); };
+Machine.prototype.carry = function () { return this.flop(this.D.cf); };
+Machine.prototype.zero = function () { return this.flop(this.D.zf); };
+Machine.prototype.halted = function () { return this.flop(this.D.halt) === 1; };
+
+Machine.prototype.step = function () {
+  const D = this.D, v = this.v;
+  const word = this.rom[this.pc()] || 0;
+  let i;
+
+  for (i = 0; i < 25; i++) v[D.instr[i]] = (word >> i) & 1;
+  for (i = 0; i < 8; i++) v[D.inPort[i]] = (this.inPort >> i) & 1;
+
+  // The address is the one latched on the previous edge, which is exactly why
+  // a load costs two honest cycles.
+  const addr = this.field(D.ramAddr);
+  const rdata = this.ram[addr];
+  for (i = 0; i < 8; i++) v[D.ramRdata[i]] = (rdata >> i) & 1;
+
+  const g = D.gates;
+  let flipped = 0;
+  for (let j = 0; j < g.length; j += 3) {
+    const y = g[j + 2];
+    const val = 1 - (v[g[j]] & v[g[j + 1]]);
+    if (v[y] !== val) { v[y] = val; flipped++; }
+  }
+  this.switched = flipped;
+
+  const f = D.flops, nx = this.next;
+  for (i = 0; i < D.flopCount; i++) nx[i] = v[f[2 * i]];
+  for (i = 0; i < D.flopCount; i++) v[f[2 * i + 1]] = nx[i];
+
+  if (this.flop(D.ramWe) === 1) {
+    this.ram[this.field(D.ramAddr)] = this.field(D.ramWdata);
+  }
+
+  this.cycle++;
+  return word;
+};
+
+/* ----------------------------------------------------------- the assembler
+ *
+ * The node assembler already exists for the build. Reusing it here means the
+ * terminal and the browser workbench cannot accept different source.
+ */
+
+module.exports = { Machine: Machine, loadNetlist: loadNetlist };