kiosk-pow-equihash 0.5.20

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6baa5d5c03c64ca19948932dd4093dcfd863d400cbee4c558bc8664d96004703
+  data.tar.gz: 3e6ae6eecbdaa8f4e13d65cdc2f887843d049b1bf89f06cba3196aa4950628b5
+SHA512:
+  metadata.gz: 8923be034745ce4856296a4ce2fe7a684c82bbd294c443b0547d2109d076e9b344ee10ae249a96e0586f2e0c8d8e53f88050678100602eb48017bdfbceb0d556
+  data.tar.gz: 386b0c5de1f4f348a496824e672eac748e3e722209bff3d9149539e899a005febfc97bc16d93042cbd644bb51f9f86ac1a89eec11ebdcf217599d482ddbb8e52

data/CHANGELOG.md

@@ -0,0 +1,136 @@
+# Changelog
+
+All notable changes follow [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [Semantic Versioning](https://semver.org/).
+
+How to write an entry, and what a release section means: `CHANGELOG-RULE.md` at
+the root of this repository —
+<https://github.com/kiosk-hq/kiosk/blob/main/CHANGELOG-RULE.md>. In short: under
+200 characters, one or two sentences, the essence rather than the content; write it
+under `## [Unreleased]`; a cut renames that heading to
+`## [MAJOR.MINOR.PATCH] — <date>` and opens a fresh empty one above it; nothing
+already written is edited.
+
+## [Unreleased]
+
+## [0.5.20] — 2026-10-20
+
+- 2026-10-20: Version 0.5.20, the tree cut that matches skill 0.5.20.
+
+## [0.5.19] — 2026-10-20
+
+- 2026-10-20: `solve.py`'s numpy error says that the solver has no path without numpy.
+
+## [0.5.18] — 2026-10-18
+
+- 2026-10-18: Version 0.5.18, the tree cut that matches skill 0.5.18.
+
+## [0.5.17] — 2026-10-18
+
+- 2026-10-18: The README gives a valid verify's memory as measured: under 3 KB live, and ~16 MB of short-lived objects that the GC frees.
+- 2026-10-18: The gemspec and README give the verify cost as measured: ~22 ms for a valid proof at n=168 k=7 in pure Ruby, ~15 ms with YJIT.
+## [0.5.16] — 2026-10-18
+
+- 2026-10-18: `Kiosk::Pow::Equihash.solver_path` is removed; a client solves with `Kiosk::Pow::Equihash.solve`.
+- 2026-10-18: Built on kiosk-pow: BLAKE2b-256 is `Kiosk::Pow::Blake2b.digest256`, and `Equihash.blake2b256` is gone. Verify results are byte-for-byte the same.
+
+## [0.5.15] — 2026-10-18
+
+- 2026-10-18: Version 0.5.15, the tree cut that matches skill 0.5.15.
+
+## [0.5.14] — 2026-10-18
+
+- 2026-10-18: Version 0.5.14, the tree cut that matches skill 0.5.14.
+
+- 2026-10-17: In a Rails app the gem registers itself as the `equihash` proof-of-work backend at boot; an app no longer registers it by hand.
+
+## [0.5.13] — 2026-10-11
+
+- 2026-10-11: Version 0.5.13, the tree cut that matches skill 0.5.13.
+
+- 2026-10-09: **`Kiosk::Pow::Equihash::Difficulty` and its `KIOSK_POW_DIFFICULTY` variable are removed**; an operator passes `(n, k)` explicitly.
+
+## [0.5.12] — 2026-10-08
+
+- 2026-10-08: Version 0.5.12, the tree cut that matches skill 0.5.12; this gem's surface is unchanged.
+
+## [0.5.11] — 2026-10-08
+
+- 2026-10-08: Version 0.5.11, the tree cut that matches skill 0.5.11; this gem's surface is unchanged.
+
+## [0.5.10] — 2026-10-08
+
+- 2026-10-08: Version 0.5.10, the tree cut that matches skill 0.5.10; this gem's surface is unchanged.
+
+## [0.5.9] — 2026-10-08
+
+- 2026-10-08: Version 0.5.9, the tree cut that matches skill 0.5.9; this gem's surface is unchanged.
+
+## [0.5.8] — 2026-10-07
+
+- 2026-10-07: Version 0.5.8, the tree cut that matches skill 0.5.8; this gem's surface is unchanged.
+
+## [0.5.7] — 2026-10-07
+
+- 2026-10-07: **The published solver drops an uncalled helper, an unsourced claim and an untested `--toy` mode**; it solves and verifies exactly as before (K-1678).
+
+- 2026-10-07: **The heavy-toll `pow_notice` points at the solver the Kiosk skill pins**, not at this gem's bundled one (K-2017).
+
+## [0.5.6] — 2026-10-07
+
+- 2026-10-07: Version 0.5.6, the tree cut that matches skill 0.5.6; this gem's surface is unchanged.
+
+## [0.5.5] — 2026-10-07
+
+- 2026-10-07: Version 0.5.5, the tree cut that matches skill 0.5.5; this gem's surface is unchanged.
+
+## [0.5.4] — 2026-10-07
+
+- 2026-10-07: Version 0.5.4, the tree cut that matches skill 0.5.4; this gem's surface is unchanged.
+
+## [0.5.3] — 2026-10-06
+
+- 2026-10-06: Version 0.5.3, the tree cut that matches skill 0.5.3; this gem's surface is unchanged.
+
+## [0.5.2] — 2026-10-06
+
+- 2026-10-05: **The package ships `requirements.txt` beside `solve.py`**, declaring the solver's `numpy` the way `kiosk-pow` declares `argon2-cffi`.
+
+## [0.5.0] — 2026-09-26
+
+### Added
+
+- `Kiosk::Pow::Equihash` — pure-Ruby Equihash (Biryukov & Khovratovich) verifier, the shipped default Kiosk PoW backend. No runtime dependencies: BLAKE2b-256 is clean-room pure Ruby from the public-domain BLAKE2 spec, and the gem depends on neither `kiosk-core` nor Rails.
+- `Kiosk::Pow::Equihash::NAME = "equihash"` — algorithm identifier for the challenge wire format.
+- `Kiosk::Pow::Equihash.params(n: 168, k: 7)` — challenge params; `DEFAULT_N` / `DEFAULT_K` carry the shipped defaults.
+- `Kiosk::Pow::Equihash.valid_params?(params)` — could a proof at these parameters ever verify? Exactly `verify`'s Step 0 parameter checks, extracted so a gate can refuse to MINT an unsatisfiable challenge instead of issuing one and blaming the client's correct proof (K-843). `verify` calls it, so the accepted set is identical by construction.
+- `Kiosk::Pow::Equihash.verify(salt:, params:, nonce:)` — recomputes the `2^k` BLAKE2b-256 leaf hashes named by the proof's indices, checks their XOR is zero over all `n` bits, and walks the Wagner collision tree (per-level XOR cancellation plus the Zcash-canonical subtree ordering). Difficulty is set by `(n, k)` alone — there is no post-hoc target check.
+- `Kiosk::Pow::Equihash.blake2b256` — public so specs can check it directly against Python `hashlib.blake2b` vectors.
+- `solve.py` — reference Python + numpy solver (a correct full-Wagner implementation, not a tuned miner), with a `--toy` `(n=24, k=3)` mode for tests.
+- `Kiosk::Pow::Equihash.solver_path` — public accessor returning the absolute path of the packaged `solve.py`, so consumers (the `kiosk-redteam` client first) shell out to the shipped solver by asking this gem instead of hardcoding a checkout-relative path that breaks in an installed gem.
+- `Kiosk::Pow::Equihash.solve(challenge)`, in `kiosk/pow/equihash/solver` — the client half of `verify`: runs the packaged solver on one challenge the provider minted and returns the proof nonce, raising `SolverError` with the solver's own message. Callers stop repeating the `Open3` invocation and the two error branches around it, and nothing outside this gem has to know where `solve.py` lives. It is a SEPARATE require on purpose: a provider verifies a proof on an unauthenticated register, and what it loads there must not be able to spawn a process.
+- `Kiosk::Pow::Equihash::Difficulty` — the operator's `KIOSK_POW_DIFFICULTY` knob: `low` (n=96, k=5, sub-second) or `high` (the gem's own `DEFAULT_N`/`DEFAULT_K`), with `params`, `level`, `high?` and a `pow_notice` for a discovery document's owner block. An unset or unrecognised value always lands on `low`, so a typo cannot price a verb out of reach. The heavy level is read off the shipped defaults rather than written out again.
+- `bench/bench.py` and `bench/README.md` — the `(n, k)` sweep behind the default, reporting p50/p95 solve time and peak RSS.
+- Known-answer tests frozen at the SHIPPED production parameters (n=168, k=7), not only at toy params — a toy-only KAT is what let a broken verifier pass, and `k=2`/`k=3` vectors now cover the tree check the old one could not see.
+- Live solver-to-verifier parity spec at 168/7 — `solve.py` produces a proof and `.verify` accepts it; CI installs numpy so the job actually runs it rather than skipping.
+- `spec/solver_pin_spec.rb` — runs `bin/check-solver-pin` from this gem's own suite, so editing `solve.py` fails here rather than silently breaking every assistant that verifies the file's SHA-256 against the pin published in the skill. Skips, stating why, in a gem-only checkout where the script is absent.
+
+### Changed
+
+- **The verifier's comments now describe the verifier (K-1679..K-1682).** They named the opposite traversal, cited nothing, skipped a step number and kept a short list.
+- The gemspec said `~17 ms` to verify where the README, the docstring and this gem's own spec all say `~18 ms`. A new example holds the two together.
+- **The README states the verify/solve split, and a guard in the repository holds it (K-1396).** Verifying is the operator's Ruby — nothing a served request loads spawns a process, and `solve.py` is here for the caller that pays the toll. `bin/check-served-pow-purity` fails if any process-spawning construct becomes reachable from the served PoW path. No code change; the property was already true.
+
+- **`.verify` now has an ANSWER for degenerate `(n, k)` — `false` — instead of a crash or a vacuous accept (K-840).** A negative `k` collapsed `1 << k` to 0, so an EMPTY indices array satisfied the length check and the root step dereferenced an empty stack (`NoMethodError`); `n = 0` (or any `n` below one byte) made every leaf the integer 0, so ANY `2^k` distinct ascending indices verified TRUE — a proof nobody supplied. `n` is now required to be `8..256` (the width a BLAKE2b-256 leaf can actually carry), `k` non-negative, and `n / (k + 1)` at least one bit per level; anything else is a malformed challenge, not an exception and not a solution. Not reachable over the wire — `Challenge.verify` re-derives the parameters from live config before the backend runs — so this is robustness against operator mis-config. The accepted set is unchanged: `n % (k + 1) == 0` is deliberately NOT required, because the hand-computed `(n=8, k=2)` KAT is a real accepted solution with `8 % 3 == 2`.
+
+- Default parameters retuned from n=192, k=7 to **n=168, k=7** after benchmarking: 192/7 measured ~155 s and ~5.4 GiB on the reference solver, too heavy for a consumer laptop; 168/7 lands at p95 ~10 s and ~1.3 GiB.
+- README and docstrings state what the gem actually is — a cheap-to-verify metered toll at ~17 ms and a few KB per verify, priced by the reputation policy's N-proofs knob. The ASIC-/GPU-resistance claims and the microsecond-verify figure are gone: Equihash was ASIC'd on Zcash, and neither claim was supportable.
+- `DEFAULT = true` removed — defaultness is established by registry wiring, not by a constant on this module.
+- `.verify` now costs a WRONG proof far less than a right one: the index checks (count, type, u64 range, distinctness, canonical subtree ordering) run before any hashing, and the leaf hashes are computed one at a time as the Wagner tree folds, so verification stops at the first node that fails. Measured at n=168 k=7: unordered rubbish 0.012 ms and well-ordered rubbish 0.30 ms, against 18.7 ms when every proof paid the full 128-hash loop; a valid proof is unchanged at ~18 ms. Which proofs verify is unchanged — `verify` is reachable unauthenticated on `POST /auth/register`, so what changes is how much an attacker can buy with a proof they did not solve (K-540).
+- An index at or above 2**64 is rejected instead of being truncated by `pack("Q<")`, which had made `idx` and `idx + 2**64` two spellings of one leaf.
+- `bench/` and everything under `lib/` ship unconditionally, so the packaged README's links to the benchmark evidence resolve inside the gem. `CHANGELOG.md` is listed the same way: the file list has no `File.exist?` guard, so a file this gemspec names and cannot find breaks the build instead of going quiet.
+- The gemspec declares a description, a homepage and the `homepage_uri` / `source_code_uri` / `bug_tracker_uri` / `changelog_uri` metadata, which it had never carried — the default PoW backend used to render on RubyGems as a bare summary line with no prose and no links.
+
+### Fixed
+
+- Verifier rewritten to the Zcash-canonical collision-tree check. The previous one checked leaf-prefix *equality* plus a global ascending sort; both are invisible at k=1, which is all the tests exercised, so it never accepted a real proof at the production parameters.
+- `verify` returns `false` instead of raising on a malformed proof — a non-Integer or negative index, a duplicate index, a wrong-length index list, or a non-numeric `header_nonce`.

data/LICENSE.txt

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.md

@@ -0,0 +1,295 @@
+# Kiosk::Pow::Equihash
+
+Memory-hard proof-of-work for Kiosk. Default PoW backend.
+
+Its job is a **cheap-to-verify metered toll**, not a hardware equaliser.
+Equihash is not ASIC- or GPU-proof — it was ASIC'd on Zcash (Antminer Z9/Z15)
+and GPUs solve it well (the Wagner sort/collide parallelises, and it is
+memory-bandwidth-bound). What it buys the provider is a few-KB, ~22 ms
+`verify` against a solve that costs the client real time and memory, plus an
+`N×PoW` count knob. Abuse resistance comes from reputation and caps
+(PoW = metered pricing, not a hardware wall).
+
+## Install
+
+> **Not on RubyGems yet** — so every `gem` line below carries `github: "kiosk-hq/kiosk"`, which is what makes it copy-pasteable today. Publication status and the canonical install are stated once, in the monorepo README's [Install](https://github.com/kiosk-hq/kiosk#install) section.
+
+Default does not mean bundled: neither `kiosk-server` nor `kiosk-all` depends
+on a PoW backend, so an origin that gates on PoW adds this gem itself.
+
+```ruby
+gem "kiosk-pow-equihash", github: "kiosk-hq/kiosk"
+```
+
+The verifier is pure Ruby. Its one runtime dependency is `kiosk-pow`, the
+pure-Ruby base that holds BLAKE2b-256. It needs no `kiosk-core`, no Rails and no
+native extension. In a Rails app the gem registers itself as the
+`equihash` backend when the app boots. The registry lives in `kiosk-reputation`,
+which an origin adds to its Gemfile the same way. Outside Rails, register it
+yourself:
+
+```ruby
+require "kiosk/pow/equihash"
+
+# Kiosk::Pow::Equihash::NAME == "equihash"
+Kiosk::Reputation::Backends.register(Kiosk::Pow::Equihash::NAME, Kiosk::Pow::Equihash)
+```
+
+That is the whole install for an **operator**, and it is deliberately this
+small: verifying is what a served request does. **Solving is the caller's
+side**, and it is the only part with a prerequisite outside Ruby — `solve.py`
+ships inside the package and needs **`python3` with `numpy`**
+(`pip install -r requirements.txt`, which ships beside it). Ask the gem for
+the file's installed location rather than hardcoding a path, and read the
+Solver section below first: numpy is not optional there, and the default
+parameters cost real time and memory to solve.
+
+## Why Equihash is the shipped default
+
+|  | Argon2id | Cuckatoo29 | **Equihash (default)** |
+|---|---|---|---|
+| Verify memory | 64 MiB ⚠️ | ~KB | **~KB** |
+| Verify time | ~ms (1 Argon2id) | 42 SipHash + walk (unbenched) | **~22 ms valid / 0.3 ms wrong (Ruby)** |
+| Lever (solve/verify) | tens× | unbenched | **~440×** (9.6 s / 22 ms) |
+| Dependencies | argon2 gem (C-ext) | Pure Ruby | **Pure Ruby (kiosk-pow only)** |
+| Difficulty tuning | D=0..256 (smooth) | edgebits | **N×PoW (discrete)** |
+
+**The lever is measured, not asserted.** `~440×` is this README's own two
+numbers divided: the p50 reference-solver solve at the shipped n=168 k=7
+(~9.6 s, *Performance* below) over a valid proof's verify (~22 ms, *Verify* above);
+p95 solve gives ~470×. With YJIT (~15 ms verify) the p50 lever is ~640×. It is a cross-language ratio — a numpy solver against a
+pure-Ruby verifier — so read it as the order of magnitude a provider actually
+buys, and note that it moves the WRONG way with a faster solver and the right way
+with a native verifier. It is not millions at any tuning in the tables below
+(192/7, at ~155 s of solve, gives ~7000×), and the number matters
+because the lever IS the economic argument for a metered toll — a price on
+abuse, not a hardware wall. Cuckatoo29's column says `unbenched` for the same
+reason its verify row does: no measurement of it exists here.
+
+The one property that actually matters for a gateway is **cheap verify**:
+
+- **Asymmetric verify.** A few KB (and ~22 ms, pure Ruby — far less for a
+  wrong proof, see below) to check — the
+  memory footprint is the point: Argon2id needs 64 MiB to _verify_, so a flood
+  of bad proofs is a DoS on the verifier itself — unacceptable for a
+  high-throughput endpoint.
+- **No native code.** Pure Ruby BLAKE2b-256 from `kiosk-pow`. Argon2id needs a C extension.
+- **Progressive difficulty via N×PoW.** Instead of a continuous dial the policy
+  asks for _N independent proofs_: "1 normally, 10 if you're scraping." Prices
+  throughput, not latency (a solver with enough memory runs them in parallel).
+
+No hardware-parity claim is made — none of Argon2id, Cuckatoo, or Equihash
+delivers it. Equihash wins on verify cost + no native code, which is what a
+provider's own machine pays on every request.
+
+## Parameters
+
+Default: **n=168, k=7** — benchmark-chosen (see [bench/](bench/README.md)):
+the largest params whose reference numpy solve stays under a ~30 s / 1–2 GiB
+consumer-laptop budget (p95 ~10 s on one M-series laptop core — the only
+hardware the seconds have ever been measured on; the ~1.3 GiB peak is THIS
+solver's sorted-nonce table, not the host's — and not a floor `(n, k)`
+imposes on every implementation, since a memory-optimised solver trades the
+table for time, which is precisely how Equihash 200/9's real footprint fell
+to ~144 MB and made it ASIC-able). Cost is driven by `n_div = n/(k+1)`.
+
+| Param | **n=168, k=7 (default)** | n=192, k=7 | Zcash (n=200, k=9) | Toy (n=24, k=3) |
+|---|---|---|---|---|
+| n_div = n/(k+1) | **21** | 24 | 20 | 6 |
+| Nonces generated | **2^22 ≈ 4.2M** | 2^25 ≈ 33.5M | 2^21 ≈ 2M | 2^7 = 128 |
+| Nonces in proof | **2^7 = 128** | 128 | 2^9 = 512 | 2^3 = 8 |
+| Reference solve (numpy, one M-series laptop core) | **~10 s, ~1.3 GiB** | ~155 s, ~5.4 GiB | — | instant |
+| Verify cost | **128 BLAKE2b** | 128 BLAKE2b | 512 BLAKE2b | 8 BLAKE2b |
+
+192/7 measures ~155 s and ~5.4 GiB on the reference numpy
+solver — too heavy for a laptop, which is why 168/7 is the default. Providers
+pick their own `(n, k)` and proof count for their own cost/latency trade-off.
+
+## Memory reuse across parallel challenges
+
+**Buffer reuse: yes. Work reuse: no.**
+
+The solver allocates one sorted-nonce-table buffer (~1.3 GiB at the default
+params). This buffer can be reused across challenges (same allocation, different
+data). However, the _computational work_ cannot be reused:
+
+- Each challenge has a unique `salt` (raw random bytes, minted by the
+  challenge issuer — `kiosk-reputation` mints 16, see its README)
+- The seed = `salt ‖ LE32(header_nonce)` is hashed with each nonce
+- Different salt → completely different BLAKE2b-256 outputs
+- The sorted nonce table must be rebuilt from scratch
+
+This is a deliberate design property: honest clients doing occasional PoWs pay the allocation cost once (buffer reuse). Attackers doing many parallel PoWs must do the full computational work for each — no amortization.
+
+## Anti-abuse strategy: N×PoW
+
+Equihash has discrete difficulty — only via (n, k) parameter changes. Instead of a continuous difficulty dial, the protocol uses **proof count**. A policy picks the count for each client, for example:
+
+```
+Normal client:   solve 1 PoW   (1× memory, 1× work)
+Suspicious:      solve 3 PoWs   (3× work; parallel if RAM allows)
+Abuser:          solve 10 PoWs  (10× work)
+```
+
+N prices _throughput_, not latency: a solver with enough memory runs the N
+independent proofs in parallel, so wall-clock need not grow 10× — but the total
+compute/energy does, which is the cost that lands on a sustained scraper.
+
+This is superior to Argon2id's `D` parameter because:
+
+1. **No verifier changes.** Same `verify()` call, just N times.
+2. **Self-documenting.** "You need 10 proofs" tells the client exactly how throttled they are.
+3. **Operator-friendly.** Adjust N per-client based on abuse score, no parameter tuning.
+4. **Predictable cost.** Each proof is independent — the solver knows exactly how much work is needed.
+
+## Wire format
+
+Challenge (as issued by the gate — `Kiosk::Reputation::Challenge.issue`):
+```json
+{
+  "id":     "<opaque id>",
+  "alg":    "equihash",
+  "params": { "n": 168, "k": 7 },
+  "salt":   "<base64 salt>",
+  "exp":    1751846400,
+  "sig":    "<HMAC-SHA256 hex>"
+}
+```
+
+Proof:
+```json
+{
+  "indices": [128 u64 integers in Zcash-canonical tree order],
+  "header_nonce": 0
+}
+```
+
+The solver accepts the salt under either key — the gate/challenge wire key
+`salt` or the alias `salt_b64`. `header_nonce` is a solver-chosen field of the
+*proof*, not a wire-challenge field.
+
+`indices` are **not** globally sorted — they are in canonical Wagner-tree
+order (see "Verification contract" below).
+
+## Verification (Ruby)
+
+```ruby
+Kiosk::Pow::Equihash.verify(
+  salt:   raw_bytes,
+  params: { n: 168, k: 7 },
+  nonce:  { indices: [/* 128 u64 */] }
+)
+# => true / false
+```
+
+Checks performed (in order):
+1. Exactly 2^k distinct non-negative indices below 2^64 (no floats)
+2. Collision tree — at each level j, every group of 2^(j+1) leaves:
+   - is in **canonical order**: the left half's first index < the right half's, and
+   - has its **XOR cancel** the top (j+1)×n_div bits (Wagner cancellation)
+3. Global XOR of all 2^k leaf hashes = 0 on n bits
+
+Verification cost: **~22 ms for a valid proof** (128 BLAKE2b-256 hashes, pure
+Ruby; measured median at n=168 k=7 on one Apple M3 core, Ruby 4.0.1). Live
+memory stays under 3 KB: 1.8 KB at most inside one hash, 0.8 KB between hashes.
+The hashes allocate ~16 MB of short-lived objects, and the GC frees them.
+With YJIT, which a Rails app enables, it is ~15 ms. A native verifier would be
+sub-millisecond. Verify scales with 2^k, not with n: at n=96 k=5 a valid proof
+costs ~5.6 ms (32 hashes, same machine) — cheaper to verify, but cheaper to
+solve by far more.
+
+**A wrong proof costs far less, deliberately.** The list above is also the
+evaluation ORDER, cheapest first, and the leaf hashes are computed one at a
+time as the tree folds — so verification stops at the first tree node that does
+not cancel. Rubbish indices are rejected without a single hash (0.012 ms
+measured); rubbish that is at least well-ordered stops after two hashes
+(0.30 ms), against ~22 ms for a complete one. That gap is the point, because
+`verify` is reachable unauthenticated on `POST /auth/register`: an attacker who
+wants the whole hash loop has to hand over an almost-complete solution, against
+a salt that is fresh per challenge.
+
+### Verification contract (why it is XOR-cancellation, not prefix-equality)
+
+Equihash is a *generalized-birthday* PoW: a valid solution is a binary tree of
+2^k leaf hashes where **sibling XORs cancel** one n_div-bit block per level.
+The leaves in a group do **not** share a common prefix — only their XOR is
+zero on that block. Two consequences the verifier must respect:
+
+- **Tree check = XOR, not equality.** Checking "all 2^(j+1) leaves share the
+  top (j+1)×n_div bits" is wrong for groups larger than 2 (it is satisfiable
+  only by an astronomically rare all-equal cluster — at n=168,k=7 it asks 128
+  leaves to share 147 bits, expected count ≈ 2^22/2^147 ≈ 0). The correct
+  check is that the group's **XOR** cancels those bits.
+- **Order = canonical, not a global sort.** A real solution's tree order is
+  not ascending (pair (a,b)+(c,d) may interleave when flattened). Requiring a
+  global sort rejects every genuine k≥2 solution. We use Zcash "algorithm
+  binding": at each node the left subtree's first index precedes the right's.
+
+## Solver (Python + numpy)
+
+**Verifying is the operator's Ruby; solving is the caller's problem.** Nothing
+an operator's server loads to serve a request ever executes a subprocess — the
+`verify` above is pure Ruby with no shell-out anywhere in its reach, and
+`solve.py` is here for the CALLER that pays the toll, run by the caller's own
+process. No process-spawning construct — `Open3`, `system`, backticks,
+`IO.popen`, `spawn`, `exec`, `%x` — is reachable from the served set, and no
+served file names the solver. The example below is what a CLIENT does, and that is why it is safe.
+
+```bash
+pip install numpy          # REQUIRED — see performance note below
+python3 solve.py '{"salt_b64":"...", "params":{"n":168,"k":7}}'
+# => {"indices": [...128 u64 in canonical tree order...], "header_nonce": 0}
+```
+
+`solve.py` ships inside the gem package. From Ruby, a client solves through it
+with one call; it raises `SolverError` when the solver refuses:
+
+```ruby
+require "kiosk/pow/equihash/solver"
+Kiosk::Pow::Equihash.solve(challenge)
+# => {"indices" => [...], "header_nonce" => 0}
+```
+
+The solver runs full Wagner's algorithm (all pairs within each collision
+bucket, not greedy adjacent pairs) and emits the solution in Zcash-canonical
+tree order. Every hot step is vectorised in numpy: leaf hashes are packed into
+a uint64 array, each level sorts by the n_div-bit collision block, and
+collisions/XORs run as whole-array ops. Deep Wagner levels grow degenerate
+"megabuckets" of index-reusing entries; the solver caps bucket participation
+(`BUCKET_CAP`) to keep work and memory bounded — the real solution comes from
+the healthy small buckets, and unsolved seeds retry with the next
+`header_nonce`.
+
+**Performance (measured, reference numpy solver, one M-series laptop core):**
+
+| params | p50 solve | p95 solve | peak RSS |
+|---|---|---|---|
+| n=96, k=5 | ~0.2 s | ~0.3 s | ~44 MiB |
+| **n=168, k=7 (default)** | ~9.6 s | ~10.3 s | ~1.3 GiB |
+| n=192, k=7 | ~155 s | ~155 s | ~5.4 GiB |
+
+Full grid in [bench/README.md](bench/README.md). This is a REFERENCE
+implementation — correct and dependency-light, not a miner. **numpy is not
+optional**: the Wagner sort/collide steps are vectorised, and without numpy
+`solve.py` refuses to run (exit 3). These numbers are the honest-client
+*floor* (slowest participant): a native or GPU solver is faster, since Equihash
+parallelises well — which is exactly why the security story is verify-asymmetry
++ reputation, not hardware parity. A provider that needs faster
+honest solves lowers `n`; the Ruby verifier stays ~22 ms either way.
+
+See `solve.py` for the implementation.
+
+## Algorithm
+
+Equihash (Biryukov & Khovratovich, 2016). Birthday-collision proof-of-work.
+
+1. Generate 2^(n/(k+1) + 1) nonces
+2. For each nonce `i`: `hash_i = BLAKE2b-256(salt ‖ header_nonce ‖ LE64(i))[:n/8]`
+3. Wagner's algorithm: k levels of collision search
+   - Level j: group entries by top (j+1)×n_div bits, pair within groups
+   - Each pair's XOR zeroes those bits
+4. Solution: 2^k nonces where XOR of all hashes = 0 on n bits AND the collision tree is valid
+
+## License
+
+Apache-2.0. See `LICENSE.txt`.