Skip to content

Add an interactive explainer below the demo - #11

Merged
KPreisner merged 1 commit into
mainfrom
explainer
Nov 2, 2026
Merged

KPreisner merged 1 commit into
mainfrom
explainer

Conversation

@KPreisner

Copy link
Copy Markdown
Owner

Add an interactive explainer below the demo

Summary

The demo page now continues past the demo into a step-by-step explainer of how CHIP works,
in the style of the Sagittal MSM walkthrough. It has ten numbered sections: why password
hashes are slow on purpose, the PHC's three levers, low bits, the birthday paradox, the chain
itself, why the XOR forces memory, salts and bounds, cost, attacks and limitations, and a
2026 retrospective. Methodology and terms follow. Each section opens with a one-line
takeaway, and most have an interactive widget. The widgets hash with the browser's SHA-256,
so they respond instantly while Pyodide loads for the demo.

The page also now runs the demo's Hash button once on load. A few numbers in the README and
paper were corrected to match measured results.

Changes

  • demo/index.html: page break, explainer sections 1–10, methodology, and terms below
    the demo; a "How it works" link in the header; color tokens for charts; the first hash runs
    automatically when Python is ready.
  • demo/explainer.js: the widgets:
    • same password with different salts;
    • GPU lanes waiting for the slowest guess (section 2), with the attacker's counter-moves
      (section 9);
    • low bits of a digest;
    • the birthday paradox, with 1,000 trials;
    • a step-through of a real CHIP chain;
    • three perturbation choices;
    • the upper-bound histogram;
    • a b × C heatmap (hover, click to pin);
    • iterations by C and memory line charts;
    • checkpoint replay;
    • checkpoint spacing.
  • demo/chain.js: CHIP's chain in JavaScript (WebCrypto), mirroring Chip.compute. On
    load it checks a pinned example chain and logs to the console if it disagrees.
  • tests/test_core.py: pins that example chain (b = 4, C = 3), so Python and
    JavaScript must agree.
  • benchmarks/distribution.py, benchmarks/results/distribution.csv: every chain's
    iteration count at the defaults (1,000 chains). The lane and upper-bound widgets use it.
  • demo/build.sh: copies the new scripts and distribution.csv and memory.csv.
  • Taskfile.yml: task site (task demo kept as an alias) and task bench-distribution.
  • README.md: mentions the explainer, lists the new files and tasks, and gives about
    230,000 iterations per hash including retries.
  • docs/paper.md, src/chip/core.py: about 230,000 iterations including retries
    (measured: 229,540), and the paper no longer says scrypt sets memory independently of time.
  • .gitignore: ignores tmp/.

Testing

  • task py-lint: passes.
  • task py-test: 66 passed.
  • sh demo/build.sh _site: builds.
  • uv run python benchmarks/distribution.py: 1,000 chains, mean 200,502, std 45,477.
  • uv run chip verify '<string from the chain widget>' hunter2: match.
  • Browser (Chrome, task site): every widget checked in light and dark mode with no console
    errors. At 390px (in an iframe) nothing overflows sideways. The demo's first hash runs on
    load.

Continue the demo page into a ten-section, step-by-step explainer of how
CHIP works, with widgets that hash using the browser's SHA-256: low bits,
the birthday paradox, a step-through chain, perturbation, upper bounds,
GPU lanes, a b × C heatmap, memory, and the time–memory tradeoff.

- demo/chain.js mirrors Chip.compute in JavaScript; tests/test_core.py
  pins an example chain so the two must agree
- benchmarks/distribution.py records every chain's length at the defaults
- The demo runs its first hash on page load
- task site (task demo kept as an alias) and task bench-distribution
- README and paper: about 230,000 iterations per hash including retries
  (measured), and drop the claim that scrypt sets memory independently
  of time
- Ignore tmp/
@KPreisner
KPreisner merged commit bdb22ef into main Nov 2, 2026
6 checks passed
@KPreisner
KPreisner deleted the explainer branch November 2, 2026 22:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant