kiosk-pow-cuckoo 0.5.20

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3ee38fdb1050afecc47067237db209eb98f648e5b57936098e3e4fa2b8f45175
+  data.tar.gz: 78e5c7cf7f2fbf198e26e9345d34b56fa58190d1b67f08b398fc6c8405a7b099
+SHA512:
+  metadata.gz: a171853ddb0e41273bf6fd6856b5082a29110a8e8de852d3e984520fb86bf088e2008617b4d747be94ebd4bcc5d7b9fc4cc23111d74b3fbae6ff0a301d084d8a
+  data.tar.gz: 373d473dc85980ccb8c5402c0b7c42aa2ea9a2be08ae87edff957821725a20ef3d618e5de852acfbf812598d443eea7e270ecc0a6b1e65944268a97db37deaa4

data/CHANGELOG.md

@@ -0,0 +1,106 @@
+# Changelog
+
+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: Version 0.5.19, the tree cut that matches skill 0.5.19.
+
+## [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 the bundled solver's memory as measured, ~118 bytes per edge (~59 GiB at edgebits=29), and names no native-solver figure.
+- 2026-10-18: The solver's memory guard predicts the measured peak, 120 bytes per edge, so edgebits 24 is refused under the default 1.5 GiB cap.
+
+## [0.5.16] — 2026-10-18
+
+- 2026-10-18: Built on kiosk-pow: BLAKE2b-256 is `Kiosk::Pow::Blake2b.digest256`, and `Cuckoo.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; this gem's surface is unchanged.
+
+## [0.5.13] — 2026-10-11
+
+- 2026-10-11: Version 0.5.13, the tree cut that matches skill 0.5.13; this gem's surface is unchanged.
+
+## [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: Version 0.5.7, the tree cut that matches skill 0.5.7; this gem's surface is unchanged.
+
+## [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-06: Version 0.5.2, the tree cut that matches skill 0.5.2; this gem's surface is unchanged.
+
+## [0.5.0] — 2026-09-26
+
+### Changed
+
+- **Three sentences priced the toy solve at «~1 second» with no machine named (K-1698).** The figure is gone; `rake solve_parity` prints its own timing.
+- **The packaged solver drops a scalar SipHash and a parameter nothing called, and stops narrating a version that no longer exists (K-1685, K-1686).**
+- **Two comments stated a salt length the base64 literal beside them refutes (K-1684).** The numbers are removed rather than corrected.
+- **`verify` answers false for seven more malformed-input shapes where it used to raise (K-1683).** Its own comment and the sibling Equihash backend already promised that.
+- The gemspec stops labelling itself with private roadmap phases (T1, T2/T3) that nothing an adopter can open resolves.
+
+### Added
+- Clean-room Cuckatoo-Cycle verifier
+- Pure-Ruby BLAKE2b-256 (from public-domain BLAKE2 spec)
+- Pure-Ruby SipHash-2-4 with Cuckatoo non-standard initialization
+- Cuckatoo cycle walk verifier
+- Optional blake2b-256 difficulty target check
+- Validated against Grin's Cuckatoo29 CI known-answer vector (nonce=20)

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,214 @@
+# kiosk-pow-cuckoo
+
+Cuckatoo-Cycle proof-of-work backend for [Kiosk](https://kiosk.tech).
+
+> **Shelved / optional.** The shipped default PoW backend is
+> [`kiosk-pow-equihash`](https://github.com/kiosk-hq/kiosk/tree/main/kiosk-pow-equihash) — one PoW backend, Equihash.
+> Cuckatoo meets the asymmetric-verify bar, but its production parameters need
+> a native solver (this gem ships only a toy solver),
+> so it is not the default. It stays in the repo as an opt-in backend and may
+> return as a first-class extension; no demo, harness or deploy runbook wires it.
+
+## What this is
+
+An optional (shelved) PoW backend with a large solve:verify asymmetry — solving
+requires finding a cycle in a large random bipartite graph (gigabytes of RAM,
+seconds of CPU), while verifying is a handful of operations: `proofsize` SipHash
+evaluations plus a cycle-walk (no wall-clock verify figure is benchmarked here).
+
+**This gem ships the VERIFIER only.**  The verifier is production-correct,
+validated against Grin's Cuckatoo29 L=42 known-answer test vector.
+
+The included Python solver (`solve_cuckoo.py`) is a **REFERENCE/TOY solver**
+for small edgebits and reduced proofsize only — see Solver section below.
+
+## 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.
+
+This backend is shelved and opt-in (see the note at the top): nothing installs
+it for you.
+
+```ruby
+gem "kiosk-pow-cuckoo", 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. Requiring it defines the backend; registering
+it is a separate, explicit step, because no PoW gem self-registers on require.
+The registry lives in `kiosk-reputation`, which an origin adds to its Gemfile
+the same way:
+
+```ruby
+require "kiosk/pow/cuckoo"
+
+# Kiosk::Pow::Cuckoo::NAME == "cuckatoo"
+Kiosk::Reputation::Backends.register(Kiosk::Pow::Cuckoo::NAME, Kiosk::Pow::Cuckoo)
+```
+
+The reference solver `solve_cuckoo.py` ships inside the package and is the one
+part with a prerequisite outside Ruby: **`python3` with `numpy`**
+(`pip install -r requirements.txt`, which ships beside it). A provider only
+ever verifies, so a provider never needs it — read the Solver section below
+for what that solver can and cannot do before you reach for it.
+
+## Algorithm: Cuckatoo Cycle
+
+- Graph size: `N = 2^edgebits` edges in a random bipartite graph
+- Edge `i` connects `U(i) = siphash(2i) mod N` to `V(i) = siphash(2i+1) mod N`
+- Proof: `proofsize` strictly-ascending edge indices forming a single cycle
+  on node-pairs (`node >> 1`)
+- Keys: `blake2b-256(salt ‖ LE32(header_nonce))` split into four LE-u64 words
+
+SipHash uses Cuckatoo's **non-standard initialization** (keys feed directly into
+`v0..v3` without XOR-ing the 0x736f6d65... magic constants from the standard
+SipHash spec).
+
+## Implementation
+
+- **BLAKE2b-256**: `Kiosk::Pow::Blake2b` from `kiosk-pow`, pure Ruby from the public-domain [BLAKE2 spec](https://www.blake2.net/blake2.pdf).
+- **SipHash-2-4**: pure Ruby from the [public-domain SipHash spec](https://131002.net/siphash/siphash.pdf),
+  with Cuckatoo's non-standard init.
+- No native extensions, no GPL code, no Tromp repository code.
+- License: Apache-2.0.
+
+## Known-answer validation
+
+The verifier is validated against Grin's Cuckatoo29 CI test vector:
+- `edgebits=29`, header = 80 zero bytes keyed with `nonce=20`, `proofsize=42`
+- 42-cycle accepted; five categories of bad inputs rejected
+
+Run: `bundle exec rspec` — all green.
+
+## API
+
+```ruby
+# Challenge params (proofsize defaults to 42; pass proofsize: 12 for the toy demo)
+params = Kiosk::Pow::Cuckoo.params(edgebits: 29, proofsize: 42)
+# => { edgebits: 29, proofsize: 42, target: nil }
+
+# Verify a proof (composite nonce: header_nonce + cycle)
+# -- This is the ONE deviation from kiosk-pow-argon2id's scalar nonce: --
+# The wire proof is { header_nonce: <u32>, cycle: [proofsize ints, ascending] }
+# kiosk-reputation passes this composite object unchanged to .verify.
+Kiosk::Pow::Cuckoo.verify(
+  salt:   raw_salt_bytes,
+  params: params,
+  nonce:  { header_nonce: 20, cycle: [e0, e1, ..., e41] }
+)
+# => true / false
+
+# Lower-level: verify cycle with pre-derived keys
+keys = Kiosk::Pow::Blake2b.digest256(header).unpack("Q<4")
+Kiosk::Pow::Cuckoo.verify_cycle(keys: keys, edgebits: 29, cycle: cycle, proofsize: 42)
+```
+
+## Wire interface: composite nonce
+
+Unlike `kiosk-pow-argon2id` (Argon2id, scalar nonce), Cuckatoo proofs are composite:
+
+```json
+{
+  "challenge": { "id": "...", "alg": "cuckatoo", "params": {...}, "salt": "...", "exp": ..., "sig": "..." },
+  "nonce":     { "header_nonce": 1, "cycle": [12, 362, 383, ...] }
+}
+```
+
+`kiosk-server`'s PoW gate passes the proof's `nonce` object unchanged to
+`kiosk-reputation`'s `Challenge.verify`. `Challenge.verify` passes it unchanged
+to the backend's `.verify(salt:, params:, nonce:)`. So `nonce` is an object,
+not a String.
+
+## Solver
+
+### Shipped Python solver (`solve_cuckoo.py`) — REFERENCE/TOY ONLY
+
+`solve_cuckoo.py` is a **pure-Python + numpy reference solver for small
+edgebits and reduced proofsize only**.
+
+| Property | Value |
+|----------|-------|
+| Language | Python 3 + numpy |
+| Status   | Reference/toy — NOT production |
+| Purpose  | Mechanism demonstration at small sizes |
+| Tested at | edgebits=10, proofsize=12 |
+| Memory guard | Built-in `_enforce_memory_budget`: refuses oversized edgebits |
+| Safety wrapper | `KIOSK_POW_MAX_BYTES=536870912 timeout 30 nice -n 19 python3 solve_cuckoo.py` |
+
+**Why edgebits=10 for proofsize=12:**
+A valid Cuckatoo proofsize=12 cycle exists in the bipartite pair-graph only when
+the pair-graph girth ≤ 12. With N/2 = 2^(edgebits-1) pair values per side and
+mean pair-degree 2, the expected girth is approximately log₂(N/2). For
+proofsize=12, this requires edgebits ≤ 12-13. At edgebits=10 (N/2=512) cycles
+exist and the bundled `solve_cuckoo.py` finds them. At edgebits ≥ 14,
+12-cycles essentially vanish.
+
+**Cannot solve production Cuckatoo** (L=42, edgebits≥29). Pure Python cannot
+hold the graph: the bundled solver uses ~118 bytes per edge (peak RSS at
+edgebits 22 and 24, one Apple M3 core), so edgebits=29 needs ~59 GiB, and its
+memory guard refuses it. Production requires a native solver (C/C++ like
+Tromp's `lean`/`mean` miner). No native solver's memory is measured here.
+
+### Cross-impl parity gate
+
+```bash
+cd kiosk-pow-cuckoo
+bundle exec rake solve_parity
+```
+
+Runs `solve_cuckoo.py` at the toy demo params (edgebits=10, proofsize=12) under
+the safety wrapper, then calls the Ruby `Kiosk::Pow::Cuckoo.verify` and asserts
+the proof is accepted.  This proves solver output is accepted by the validated
+verifier.
+
+### Production solver (out of scope for this gem)
+
+Production Cuckatoo (edgebits≥29, proofsize=42) requires clients with a native
+solver.  Options:
+- **Tromp's C miner** (`lean`/`mean`, `simple`): fast, FAIR-MINING/GPLv2+ license
+- **GPU solvers**: faster still; CUDA-only
+- Provider mandates the algorithm; clients that cannot solve are denied
+
+## Difficulty target
+
+An optional `target` (Integer, 256-bit) can be added to params to tighten
+difficulty beyond the base cycle requirement:
+
+```ruby
+params = Kiosk::Pow::Cuckoo.params(edgebits: 29, target: (2**256 - 1) / 100)
+```
+
+When set, the verifier additionally checks:
+```
+blake2b-256(sorted_cycle_edges_as_LE_u64) < target
+```
+
+## Toy mechanism demo
+
+**TOY MECHANISM DEMO — proofsize 12 at edgebits 10; NOT production difficulty.**
+
+No demo app wires Cuckatoo. The solve → verify loop at the
+toy params is exercised by this gem's cross-impl parity gate (see the Solver
+section above):
+
+```bash
+cd kiosk-pow-cuckoo
+bundle exec rake solve_parity
+```
+
+Runs the Python reference solver, then asserts the Ruby verifier accepts its
+proof.
+
+## Caveats
+
+- Cuckatoo is NOT ASIC-proof (1 GB-SRAM ASICs exist for edgebits=31+). The
+  provider mandates it; clients that cannot solve are denied. This is
+  intentional: it raises the cost of abuse.
+- **Equihash** (`kiosk-pow-equihash`) is the shipped default.
+  Argon2id (`kiosk-pow-argon2id`) remains as a legacy backend. Use Cuckatoo only when the
+  extreme solve:verify asymmetry (GB-RAM solver vs. a few-hash verifier) is
+  specifically required.
+- `proofsize < 42` is a deviation from production Cuckatoo (L=42 per Grin/Tromp
+  spec). The toy demo (L=12) demonstrates the mechanism only.
+- `edgebits < 29` is suitable only for testing; production Grin uses edgebits 29.

data/lib/kiosk/pow/cuckoo/sip_hash.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Pow
+    module Cuckoo
+      # SipHash-2-4 as Cuckatoo uses it: the four keys are NOT XORed with the
+      # standard magic constants.
+      module SipHash
+        MASK64 = (1 << 64) - 1
+        private_constant :MASK64
+
+        def self.digest(keys, nonce)
+          state = keys.dup
+          state[3] ^= nonce
+          2.times { round(state) }
+          state[0] ^= nonce
+          state[2] ^= 0xff
+          4.times { round(state) }
+          state.reduce(:^)
+        end
+
+        # One SipRound as two half rounds. Each half updates two independent
+        # lane pairs: (a, b) and (c, d).
+        def self.round(state)
+          half_round(state, [0, 1, 2, 3], 13, 16)
+          half_round(state, [2, 1, 0, 3], 17, 21)
+        end
+
+        def self.half_round(state, lanes, rotate_b, rotate_d)
+          a, b, c, d = lanes
+          add_rotate_xor(state, a, b, rotate_b)
+          state[a] = rotl64(state[a], 32)
+          add_rotate_xor(state, c, d, rotate_d)
+        end
+
+        # Adds lane `src` into lane `dst`, then rotates `src` and XORs `dst` into it.
+        def self.add_rotate_xor(state, dst, src, bits)
+          state[dst] = (state[dst] + state[src]) & MASK64
+          state[src] = rotl64(state[src], bits) ^ state[dst]
+        end
+
+        def self.rotl64(word, bits) = ((word << bits) | (word >> (64 - bits))) & MASK64
+
+        private_class_method :round, :half_round, :add_rotate_xor, :rotl64
+      end
+    end
+  end
+end

data/lib/kiosk/pow/cuckoo/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Pow
+    module Cuckoo
+      VERSION = '0.5.20'
+    end
+  end
+end

data/lib/kiosk/pow/cuckoo.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require 'kiosk/pow'
+require 'kiosk/pow/cuckoo/version'
+require 'kiosk/pow/cuckoo/sip_hash'
+
+module Kiosk
+  module Pow
+    # Cuckatoo Cycle proof-of-work verifier, clean-room from Tromp's spec.
+    # The proof `nonce` is { header_nonce: <u32>, cycle: [42 ascending edge indices] };
+    # the solver is `solve_cuckoo.py`, packaged beside this file.
+    module Cuckoo
+      NAME = 'cuckatoo'
+
+      def self.siphash(key0, key1, key2, key3, nonce)
+        SipHash.digest([key0, key1, key2, key3], nonce)
+      end
+
+      def self.verify_cycle(keys:, edgebits:, cycle:, proofsize: 42) # rubocop:disable Naming/PredicateMethod -- public verifier step, named like the PoW backend interface method verify.
+        return false unless cycle.length == proofsize
+
+        uvs = endpoints(keys, edgebits, cycle)
+        !uvs.nil? && closed_walk_length(uvs) == proofsize
+      end
+
+      # `target` is a 256-bit Integer the sorted cycle's BLAKE2b-256 must stay below; nil accepts any cycle.
+      def self.params(edgebits:, proofsize: 42, target: nil)
+        { edgebits:, proofsize:, target: }
+      end
+
+      def self.verify(salt:, params:, nonce:)
+        proof = coerce_proof(nonce)
+        edgebits, proofsize, target = coerce_params(params)
+        return false if proof.nil? || edgebits.nil?
+
+        header_nonce, cycle = proof
+        keys = Blake2b.digest256(salt.b + [header_nonce].pack('V')).unpack('Q<4')
+        verify_cycle(keys:, edgebits:, cycle:, proofsize:) && below_target?(cycle, target)
+      end
+
+      # The two node endpoints of each edge, in cycle order. Nil when an edge is
+      # not an Integer, is out of range, or breaks the ascending order.
+      def self.endpoints(keys, edgebits, cycle)
+        n_nodes = 1 << edgebits
+        return nil unless ascending_edges?(cycle, n_nodes)
+
+        mask = n_nodes - 1
+        cycle.flat_map { |edge| [siphash(*keys, 2 * edge) & mask, siphash(*keys, (2 * edge) + 1) & mask] }
+      end
+
+      def self.ascending_edges?(cycle, limit)
+        cycle.each_with_index.all? do |edge, index|
+          edge.is_a?(Integer) && edge < limit && (index.zero? || edge > cycle[index - 1])
+        end
+      end
+
+      # Walks the cycle from endpoint 0: go to the one other same-parity
+      # endpoint on the same node (>> 1), cross that edge (j ^ 1), and count the
+      # steps back to 0. Nil when an endpoint has no partner or more than one.
+      def self.closed_walk_length(uvs)
+        i = 0
+        steps = 0
+        loop do
+          j = partner(uvs, i)
+          return nil if j.nil? || uvs[j] == uvs[i]
+
+          i = j ^ 1
+          steps += 1
+          return steps if i.zero?
+        end
+      end
+
+      def self.partner(uvs, from)
+        node = uvs[from] >> 1
+        matches = (1...(uvs.size / 2)).map { |step| (from + (2 * step)) % uvs.size }
+                                      .select { |k| (uvs[k] >> 1) == node }
+        matches.one? ? matches.first : nil
+      end
+
+      # [header_nonce, cycle] from a proof Hash; nil when it is unreadable.
+      def self.coerce_proof(nonce)
+        return nil unless nonce.is_a?(Hash)
+
+        header_nonce = Pow.param(nonce, :header_nonce)
+        cycle = Pow.param(nonce, :cycle)
+        return nil if header_nonce.nil? || !cycle.is_a?(Array)
+
+        [Integer(header_nonce), cycle]
+      rescue ArgumentError, TypeError
+        nil
+      end
+
+      # All-nil when unreadable, so {.verify} answers false instead of raising.
+      def self.coerce_params(params)
+        return [nil, nil, nil] unless params.is_a?(Hash)
+
+        target = Pow.param(params, :target)
+        [Integer(Pow.param(params, :edgebits)), Integer(Pow.param(params, :proofsize) || 42), target && Integer(target)]
+      rescue ArgumentError, TypeError
+        [nil, nil, nil]
+      end
+
+      # The sorted cycle's BLAKE2b-256, read as a big-endian integer, must be
+      # below `target`. A nil target accepts any cycle.
+      def self.below_target?(cycle, target)
+        target.nil? || Blake2b.digest256(cycle.sort.pack('Q<*')).unpack1('H*').to_i(16) < target
+      end
+
+      private_class_method :endpoints, :ascending_edges?, :closed_walk_length, :partner,
+                           :coerce_proof, :coerce_params, :below_target?
+    end
+  end
+end

data/requirements.txt

@@ -0,0 +1 @@
+numpy

data/solve_cuckoo.py

@@ -0,0 +1,435 @@
+#!/usr/bin/env python3
+"""
+Clean-room Cuckatoo-Cycle proof-of-work solver.
+CPU-only, pure Python + numpy (no GPU, no CUDA, no C/C++ toolchain required).
+Runs in an assistant sandbox (Mac mini / DigitalOcean VDS / AWS EC2).
+
+Dependencies: numpy  (pip install numpy)
+
+Algorithm: Cuckatoo variant of Cuckoo Cycle by John Tromp.
+Clean-room implementation from the public algorithm spec — no GPL/FAIR-MINING
+source code copied or adapted.
+
+SipHash-2-4 non-standard init (Cuckatoo variant):
+    v0=k0, v1=k1, v2=k2, v3=k3^nonce
+    SIPROUND×2; v0^=nonce; v2^=0xff; SIPROUND×4
+    return (v0^v1)^(v2^v3)
+
+Keys: blake2b-256(header) → 4 LE-u64 words.
+Header: salt_bytes ‖ struct.pack("<I", header_nonce)
+
+Edge endpoints (N = 1<<edgebits, mask = N-1):
+    U(i) = siphash(2*i)   & mask
+    V(i) = siphash(2*i+1) & mask
+
+A valid proof is 42 strictly-ascending edge indices forming a single 42-cycle
+on node-pairs (node>>1), accepted by Kiosk::Pow::Cuckoo.verify.
+
+Key implementation note:
+    Cuckatoo trimming operates on NODE-PAIRS (node >> 1), NOT raw node values.
+    Each of the N=2^edgebits edges has U[e]∈[0,N-1]; U-pair = U[e]>>1 ∈ [0,N/2-1].
+    Mean pair degree = N / (N/2) = 2, which keeps ~20% of edges after trimming.
+    Using raw-node trimming instead (mean degree 1) incorrectly destroys all cycles.
+
+Usage:
+    python3 solve_cuckoo.py '<challenge json>'
+    python3 solve_cuckoo.py  # reads from stdin
+
+Challenge JSON:
+    {"salt": "<base64>", "params": {"edgebits": <int>, "proofsize": 42, "target": null}}
+
+Output (one JSON line):
+    {"header_nonce": <int>, "cycle": [42 ints ascending]}
+
+Honest performance note (edgebits and proofsize are coupled):
+    A proofsize=L cycle only exists once the pair-graph girth ≤ L, and the
+    expected girth is ~log2(N/2) = edgebits-1. So the solvable pairing is a
+    proofsize matched to the graph size, NOT edgebits varied under the
+    default proofsize=42:
+      edgebits=10, proofsize=12  → ~1 s on a modern CPU  (demo-safe; the
+                                   tested / parity-gate combo)
+      edgebits=12, proofsize=12  → ~seconds (12-cycles thin out by edgebits 14)
+    The default proofsize=42 needs girth ~42 (edgebits ~43): at production
+    edgebits (29+) with proofsize=42 the graph is far too large for pure
+    numpy, and at small edgebits a 42-cycle essentially never exists. Either
+    way, proofsize=42 is infeasible here and requires a native C miner.
+"""
+
+import base64
+import hashlib
+import json
+import os
+import struct
+import sys
+from collections import defaultdict
+
+# Keep numpy single-threaded — this solver is elementwise uint64, not BLAS, and
+# uncapped threads were part of the runaway that pinned all cores. Set BEFORE numpy.
+for _v in ("OMP_NUM_THREADS", "OPENBLAS_NUM_THREADS", "MKL_NUM_THREADS",
+           "VECLIB_MAXIMUM_THREADS", "NUMEXPR_NUM_THREADS"):
+    os.environ.setdefault(_v, "1")
+
+import numpy as np
+
+# ---------------------------------------------------------------------------
+# HARD memory guard (safety-critical).
+#
+# The measured peak (ru_maxrss, build and trim) is 104, 119 and 118 bytes per
+# edge at edgebits 20, 22 and 24. An uncapped run at high edgebits can exhaust
+# memory and swap. macOS ignores `ulimit -v`, so the solver limits itself: it
+# predicts the peak from edgebits and REFUSES before it allocates.
+#
+# Cap is configurable via KIOSK_POW_MAX_BYTES (default 1.5 GiB). This makes the
+# solver safe to invoke at ANY edgebits regardless of how it's called.
+# ---------------------------------------------------------------------------
+_BYTES_PER_EDGE_PEAK = 120         # measured numpy peak, rounded up
+_DEFAULT_MAX_BYTES = 1536 * 1024 * 1024   # 1.5 GiB
+
+
+def _max_bytes() -> int:
+    raw = os.environ.get("KIOSK_POW_MAX_BYTES")
+    return int(raw) if raw else _DEFAULT_MAX_BYTES
+
+
+def _predicted_peak_bytes(edgebits: int) -> int:
+    return _BYTES_PER_EDGE_PEAK * (1 << edgebits)
+
+
+def _enforce_memory_budget(edgebits: int) -> None:
+    predicted = _predicted_peak_bytes(edgebits)
+    cap = _max_bytes()
+    if predicted > cap:
+        msg = (
+            f"refusing edgebits={edgebits}: predicted peak "
+            f"~{predicted / 1024 / 1024:.0f} MiB exceeds cap "
+            f"{cap / 1024 / 1024:.0f} MiB (set KIOSK_POW_MAX_BYTES to override). "
+            f"This pure-numpy reference solver is for small/demo edgebits only; "
+            f"production sizes (29+) need a native solver."
+        )
+        print(json.dumps({"error": "edgebits_too_large", "message": msg}))
+        sys.exit(2)
+    # Best-effort OS guard on top (often a no-op on macOS, real on Linux).
+    try:
+        import resource
+        soft, hard = resource.getrlimit(resource.RLIMIT_AS)
+        want = cap + 256 * 1024 * 1024  # cap + headroom
+        new_hard = want if hard == resource.RLIM_INFINITY else min(hard, want)
+        resource.setrlimit(resource.RLIMIT_AS, (want, new_hard))
+    except (ImportError, ValueError, OSError):
+        pass
+
+# ---------------------------------------------------------------------------
+# Constants (numpy uint64)
+# ---------------------------------------------------------------------------
+ROT13 = np.uint64(13)
+ROT16 = np.uint64(16)
+ROT17 = np.uint64(17)
+ROT21 = np.uint64(21)
+ROT32 = np.uint64(32)
+XFF   = np.uint64(0xFF)
+ONE   = np.uint64(1)
+
+# ---------------------------------------------------------------------------
+# Vectorized SipHash-2-4 (Cuckatoo non-standard init) via numpy.
+# Speed-critical: computes all N edge endpoints in parallel.
+# ---------------------------------------------------------------------------
+
+def _rotl64_vec(x, n):
+    return (x << n) | (x >> (np.uint64(64) - n))
+
+
+def _sipround_vec(v0, v1, v2, v3):
+    v0 = v0 + v1
+    v1 = _rotl64_vec(v1, ROT13) ^ v0
+    v0 = _rotl64_vec(v0, ROT32)
+    v2 = v2 + v3
+    v3 = _rotl64_vec(v3, ROT16) ^ v2
+    v0 = v0 + v3
+    v3 = _rotl64_vec(v3, ROT21) ^ v0
+    v2 = v2 + v1
+    v1 = _rotl64_vec(v1, ROT17) ^ v2
+    v2 = _rotl64_vec(v2, ROT32)
+    return v0, v1, v2, v3
+
+
+def siphash_vec(k0: int, k1: int, k2: int, k3: int, nonces: np.ndarray) -> np.ndarray:
+    """
+    Vectorized Cuckatoo SipHash-2-4.
+    nonces: 1-D numpy array of dtype uint64.
+    Returns: uint64 array of same length.
+    """
+    K0 = np.uint64(k0)
+    K1 = np.uint64(k1)
+    K2 = np.uint64(k2)
+    K3 = np.uint64(k3)
+
+    v0 = np.full(len(nonces), K0, dtype=np.uint64)
+    v1 = np.full(len(nonces), K1, dtype=np.uint64)
+    v2 = np.full(len(nonces), K2, dtype=np.uint64)
+    v3 = np.full(len(nonces), K3, dtype=np.uint64) ^ nonces
+
+    v0, v1, v2, v3 = _sipround_vec(v0, v1, v2, v3)
+    v0, v1, v2, v3 = _sipround_vec(v0, v1, v2, v3)
+
+    v0 ^= nonces
+    v2 ^= XFF
+
+    for _ in range(4):
+        v0, v1, v2, v3 = _sipround_vec(v0, v1, v2, v3)
+
+    return (v0 ^ v1) ^ (v2 ^ v3)
+
+
+# ---------------------------------------------------------------------------
+# Key derivation
+# ---------------------------------------------------------------------------
+
+def derive_keys(header: bytes):
+    digest = hashlib.blake2b(header, digest_size=32).digest()
+    k0, k1, k2, k3 = struct.unpack_from("<QQQQ", digest)
+    return k0, k1, k2, k3
+
+
+# ---------------------------------------------------------------------------
+# Build all edge endpoints (vectorized, the speed-critical step).
+# Returns U[N] and V[N] as uint64 arrays (values masked to edgebits).
+# ---------------------------------------------------------------------------
+
+def build_endpoints(k0, k1, k2, k3, edgebits: int):
+    N    = 1 << edgebits
+    mask = np.uint64(N - 1)
+    i    = np.arange(N, dtype=np.uint64)
+    U    = siphash_vec(k0, k1, k2, k3, np.uint64(2) * i)                 & mask
+    V    = siphash_vec(k0, k1, k2, k3, np.uint64(2) * i + np.uint64(1))  & mask
+    return U, V
+
+
+# ---------------------------------------------------------------------------
+# Edge trimming via numpy bincount — Cuckatoo-correct version.
+#
+# CRITICAL: degree is counted on NODE-PAIRS (node >> 1), not raw node values.
+#
+# Why: a valid Cuckatoo 42-cycle has 42 UNIQUE U-endpoints (raw degree 1 each)
+# but 21 UNIQUE U-PAIRS (pair degree 2 each).  Raw-degree trimming destroys
+# all valid cycles at the first round; pair-degree trimming preserves them.
+# Mean pair degree = N / (N/2) = 2, so ~20% of edges survive after trimming.
+# ---------------------------------------------------------------------------
+
+def trim_edges(U: np.ndarray, V: np.ndarray, edgebits: int, rounds: int = 20) -> np.ndarray:
+    N      = 1 << edgebits
+    NPAIRS = N >> 1           # number of node-pair values per side
+    alive  = np.ones(len(U), dtype=bool)
+
+    # Pre-compute pair arrays (they don't change, only alive changes).
+    UP = (U >> ONE).astype(np.intp)   # U-pair indices
+    VP = (V >> ONE).astype(np.intp)   # V-pair indices
+
+    for _ in range(rounds):
+        prev_count = alive.sum()
+
+        deg_up  = np.bincount(UP[alive], minlength=NPAIRS)
+        alive  &= deg_up[UP] >= 2
+
+        deg_vp  = np.bincount(VP[alive], minlength=NPAIRS)
+        alive  &= deg_vp[VP] >= 2
+
+        if alive.sum() == prev_count:
+            break
+
+    return alive
+
+
+# ---------------------------------------------------------------------------
+# Cuckatoo cycle verifier — Python mirror of the Ruby verifier (cuckoo.rb).
+#
+# Agreement here ↔ Ruby verify() returns true.
+# Takes sorted cycle_edges (list of edge indices, length proofsize).
+# ---------------------------------------------------------------------------
+
+def verify_cuckatoo_cycle(U_arr, V_arr, cycle_edges) -> bool:
+    """Returns True iff cycle_edges is a valid Cuckatoo proofsize-cycle.
+
+    Works for any proofsize (not just 42).  The cycle-walk algorithm is
+    identical regardless of length; only `ps` changes.
+    """
+    ps = len(cycle_edges)
+    if ps < 2:
+        return False   # degenerate: need at least 2 edges for a cycle
+
+    uvs = []
+    for ei in cycle_edges:
+        uvs.append(int(U_arr[ei]))
+        uvs.append(int(V_arr[ei]))
+
+    uvs_size = 2 * ps
+    i = 0
+    n = 0
+
+    while True:
+        j = i
+        k = i
+        branch = False
+
+        while True:
+            k = (k + 2) % uvs_size
+            if k == i:
+                break
+            if (uvs[k] >> 1) == (uvs[i] >> 1):
+                if j != i:
+                    branch = True
+                    break
+                j = k
+
+        if branch:
+            return False
+        if j == i:
+            return False
+        if uvs[j] == uvs[i]:
+            return False
+
+        i = j ^ 1
+        n += 1
+        if i == 0:
+            break
+        if n > ps:
+            return False
+
+    return n == ps
+
+
+# ---------------------------------------------------------------------------
+# Cycle finder using recursive DFS on the quotient (node-pair) graph.
+#
+# After pair-degree trimming, surviving nodes have pair-degree ≥ 2.
+# We run a recursive DFS that correctly backtracks (path_depth is cleaned up
+# on every unwind), so back-edge depths are exact.  When a back-edge closes
+# a cycle of EXACTLY proofsize edges we validate it with verify_cuckatoo_cycle
+# and return immediately.
+#
+# Depth is bounded at proofsize so recursion never exceeds proofsize frames
+# (≤ 42 for production, ≤ 12 for the toy demo) — safe against Python's
+# recursion limit.  We restart DFS from each node so every component is
+# searched even when part of it was visited on a non-cycle path earlier.
+#
+# Each node leaves path_depth exactly on unwind, so the depth recorded for a
+# node is always its depth on the CURRENT path — a stale depth left behind by
+# an abandoned branch would corrupt every cycle length computed after it.
+# ---------------------------------------------------------------------------
+
+def find_cycle(U: np.ndarray, V: np.ndarray, alive_mask: np.ndarray, proofsize: int = 42):
+    edge_idx = np.where(alive_mask)[0]
+    if len(edge_idx) < proofsize:
+        return None
+
+    # Build adjacency on node-pairs.
+    # Node key: (side, pair_value), side ∈ {0=U, 1=V}.
+    adj: dict = defaultdict(list)
+    for ei in edge_idx:
+        up = (0, int(U[ei]) >> 1)
+        vp = (1, int(V[ei]) >> 1)
+        adj[up].append((vp, int(ei)))
+        adj[vp].append((up, int(ei)))
+
+    for start_node in list(adj.keys()):
+        # Fresh path state per start (ensures clean backtracking across starts).
+        path_depth: dict = {}   # node -> depth on the CURRENT path only
+        path_edges: list = []   # edges on the current path (len == current depth)
+
+        # Recursive DFS.  parent_ei is the edge index we arrived on (−1 at root)
+        # so we don't immediately traverse back on the same edge.
+        #
+        # Invariant entering dfs(node, depth, parent_ei):
+        #   path_edges has exactly `depth` elements.
+        #   path_depth holds exactly the nodes on the path from start to
+        #   the CALLER of this function (not including `node` yet).
+        def dfs(node, depth, parent_ei):
+            # --- Back-edge check (done before the depth limit so we always
+            #     detect cycles even at the maximum allowed depth) ---
+            if node in path_depth:
+                anc_depth = path_depth[node]
+                cycle_len = depth - anc_depth  # #edges = depth - anc_depth
+                # path_edges[anc_depth:] is the back-edge included (it was
+                # appended by our caller before this call).
+                if cycle_len == proofsize:
+                    cycle = path_edges[anc_depth:]   # already has proofsize elements
+                    sc = sorted(cycle)
+                    if verify_cuckatoo_cycle(U, V, sc):
+                        return sc
+                return None
+
+            # --- Depth limit: don't add nodes beyond proofsize levels ---
+            if depth >= proofsize:
+                return None
+
+            # --- Enter this node ---
+            path_depth[node] = depth
+
+            for nbr, ei in adj[node]:
+                if ei == parent_ei:
+                    continue           # skip the edge we arrived on
+                path_edges.append(ei)  # include edge before recursing
+                result = dfs(nbr, depth + 1, ei)
+                path_edges.pop()       # restore on unwind
+                if result is not None:
+                    del path_depth[node]
+                    return result
+
+            # --- Leave this node (backtrack) ---
+            del path_depth[node]
+            return None
+
+        result = dfs(start_node, 0, -1)
+        if result is not None:
+            return result
+
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Main solve loop
+# ---------------------------------------------------------------------------
+
+def solve(challenge: dict) -> dict:
+    salt      = base64.b64decode(challenge["salt"])
+    params    = challenge["params"]
+    edgebits  = int(params["edgebits"])
+    proofsize = int(params.get("proofsize", 42))
+    target    = params.get("target")
+
+    _enforce_memory_budget(edgebits)   # refuse oversized edgebits before allocating
+
+    header_nonce = 0
+    while True:
+        header          = salt + struct.pack("<I", header_nonce)
+        k0, k1, k2, k3 = derive_keys(header)
+
+        U, V   = build_endpoints(k0, k1, k2, k3, edgebits)
+        alive  = trim_edges(U, V, edgebits)
+        cycle  = find_cycle(U, V, alive, proofsize)
+
+        if cycle is not None:
+            if target is not None:
+                cycle_packed = struct.pack(f"<{len(cycle)}Q", *sorted(cycle))
+                cycle_hash   = hashlib.blake2b(cycle_packed, digest_size=32).digest()
+                hash_int     = int.from_bytes(cycle_hash, "big")
+                target_int   = int(target) if isinstance(target, int) else int.from_bytes(target, "big")
+                if hash_int >= target_int:
+                    header_nonce += 1
+                    continue
+            return {"header_nonce": header_nonce, "cycle": cycle}
+
+        header_nonce += 1
+
+
+def main():
+    if len(sys.argv) > 1:
+        challenge = json.loads(sys.argv[1])
+    else:
+        challenge = json.load(sys.stdin)
+
+    result = solve(challenge)
+    print(json.dumps(result))
+
+
+if __name__ == "__main__":
+    main()

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification
+name: kiosk-pow-cuckoo
+version: !ruby/object:Gem::Version
+  version: 0.5.20
+platform: ruby
+authors:
+- Phil Pirozhkov
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: kiosk-pow
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.0
+description: |
+  kiosk-pow-cuckoo is an optional Cuckatoo-Cycle (Cuckoo Cycle variant)
+  proof-of-work backend for the Kiosk framework.
+
+  Ships the provider-side Ruby VERIFIER only.  The verifier is cheap
+  (a handful of hash evaluations; no wall-clock figure is benchmarked),
+  security-critical, and validated against Grin's Cuckatoo29 CI test
+  vector.  A reference Python solver (solve_cuckoo.py) ships alongside for
+  parity testing; production solving is the client's concern.
+
+  The implementation is clean-room from Tromp's public-domain algorithm
+  spec (doc/spec, doc/mathspec) — no GPL/FAIR-MINING code is included.
+  BLAKE2b-256 comes from kiosk-pow, the base of every Kiosk PoW backend.
+  SipHash-2-4 is pure Ruby from the public-domain SipHash spec with
+  Cuckatoo's non-standard initialization (keys feed directly into v0..v3
+  without XOR-ing the 0x736f6d65... magic constants).
+
+  Does not depend on kiosk-core or Rails — pure Ruby, no native extensions.
+email:
+- hello@fili.pp.ru
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/kiosk/pow/cuckoo.rb
+- lib/kiosk/pow/cuckoo/sip_hash.rb
+- lib/kiosk/pow/cuckoo/version.rb
+- requirements.txt
+- solve_cuckoo.py
+homepage: https://kiosk.tech
+licenses:
+- Apache-2.0
+metadata:
+  homepage_uri: https://kiosk.tech
+  source_code_uri: https://github.com/kiosk-hq/kiosk
+  changelog_uri: https://github.com/kiosk-hq/kiosk/blob/main/kiosk-pow-cuckoo/CHANGELOG.md
+  bug_tracker_uri: https://github.com/kiosk-hq/kiosk/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Cuckatoo-Cycle proof-of-work backend for Kiosk
+test_files: []