zeropx-poseidon2-goldilocks 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,11 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ .pytest_cache/
4
+ .venv/
5
+ build/
6
+ dist/
7
+ *.egg-info/
8
+ dist_bin/
9
+ build_pyi/
10
+ landing/
11
+ uv.lock
@@ -0,0 +1,50 @@
1
+ # Changelog
2
+
3
+ ## 0.2.0 — 2026-08-17
4
+
5
+ - New `merkle` module: binary Merkle tree over Poseidon2 digests.
6
+ - `hash_pair(left, right)` — 4-felt + 4-felt → 4-felt via `hash_no_pad`.
7
+ - `merkle_root(leaves)` — root of a tree padded to the next power of
8
+ two with `EMPTY_DIGEST` (all-zero 4-tuple).
9
+ - `merkle_proof(leaves, index)` — authentication path as a list of
10
+ `(sibling_digest, "L"|"R")` pairs; empty path for a single-leaf
11
+ tree, so `verify_merkle_proof(root, leaf, [], 0)` recovers the
12
+ leaf-is-root convention.
13
+ - `verify_merkle_proof(root, leaf, proof, index)` — replays the
14
+ hash chain, cross-checks each sibling's `L`/`R` label against the
15
+ corresponding bit of `index`, so a proof generated for a
16
+ different position rejects even if it coincidentally hashes to
17
+ the announced root.
18
+ - 21 new tests exercising: pow-of-two padding, hash-pair asymmetry,
19
+ round-trip through 8-leaf and 5-leaf (non-power-of-2) trees, four
20
+ distinct tamper cases (wrong leaf, wrong root, wrong index, mutated
21
+ sibling), swapped `L`/`R` labels, malformed side character, empty
22
+ tree, out-of-range index, single-leaf identity, and an end-to-end
23
+ path from raw bytes via `hash_bytes` through Merkle build and
24
+ verify. Full suite: 37/37 passing.
25
+ - Public API adds `hash_pair`, `merkle_root`, `merkle_proof`,
26
+ `verify_merkle_proof`, `EMPTY_DIGEST`.
27
+
28
+ ## 0.1.0 — 2026-08-17
29
+
30
+ Initial public release.
31
+
32
+ - Pure-Python Poseidon2 permutation over the Goldilocks field
33
+ (`p = 2^64 - 2^32 + 1`), width=12, rate=8, capacity=4, S-box d=7,
34
+ RF=8, RP=22. **Byte-for-byte compatible with qp-poseidon-core v3.1.0**
35
+ as used by Plonky2 and the Quantus Substrate runtime.
36
+ - `permute` / `permute_mut` — full permutation on a 12-element state.
37
+ - `hash_no_pad` — plonky2-style variable-length sponge hash, 4-element
38
+ digest.
39
+ - `hash_bytes` — bytes → 32-byte digest via 8-bytes-per-felt LE routing.
40
+ - `external_linear_layer`, `internal_linear_layer` — exposed for
41
+ intermediate-value cross-checks.
42
+ - All Poseidon2 round constants, matrix-diagonal, and external round
43
+ constants copied verbatim from the reference (originally generated
44
+ by `qp-poseidon-constants` from seed `0x3141592653589793`).
45
+ - 16 tests: two exact-match vectors against reference `P3_ZERO_RESULT`
46
+ / `P3_SEQ_RESULT`, S-box vs. `pow(x, 7, p)` cross-check, canonical
47
+ reduction, in-place vs. functional equivalence, width validation,
48
+ hash-no-pad determinism, hash-bytes round-trip, empty-input, and
49
+ cross-block sponge distinction.
50
+ - Zero runtime dependencies. MIT license. Python 3.10+.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Dr. Vander Geraldo Rodrigues da Cunha Júnior
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,154 @@
1
+ Metadata-Version: 2.5
2
+ Name: zeropx-poseidon2-goldilocks
3
+ Version: 0.2.0
4
+ Summary: Pure-Python Poseidon2 permutation and hash over the Goldilocks field (2^64 - 2^32 + 1). Byte-for-byte compatible with the Plonky2 / qp-poseidon-core reference. Zero runtime dependencies.
5
+ Project-URL: Homepage, https://github.com/NixEngine/zeropx-poseidon2-goldilocks
6
+ Project-URL: Repository, https://github.com/NixEngine/zeropx-poseidon2-goldilocks
7
+ Project-URL: Issues, https://github.com/NixEngine/zeropx-poseidon2-goldilocks/issues
8
+ Author-email: "Dr. Vander Geraldo Rodrigues da Cunha Júnior" <vgrcjr@gmail.com>
9
+ License: MIT
10
+ License-File: LICENSE
11
+ Keywords: cryptography,goldilocks,hash,plonky2,poseidon,poseidon2,zero-knowledge
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Intended Audience :: Science/Research
15
+ Classifier: License :: OSI Approved :: MIT License
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3 :: Only
18
+ Classifier: Programming Language :: Python :: 3.10
19
+ Classifier: Programming Language :: Python :: 3.11
20
+ Classifier: Programming Language :: Python :: 3.12
21
+ Classifier: Programming Language :: Python :: 3.13
22
+ Classifier: Programming Language :: Python :: 3.14
23
+ Classifier: Topic :: Security :: Cryptography
24
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
25
+ Classifier: Typing :: Typed
26
+ Requires-Python: >=3.10
27
+ Provides-Extra: dev
28
+ Requires-Dist: pytest>=7; extra == 'dev'
29
+ Description-Content-Type: text/markdown
30
+
31
+ # zeropx-poseidon2-goldilocks
32
+
33
+ Pure-Python Poseidon2 permutation and hash over the Goldilocks field
34
+ (`p = 2^64 - 2^32 + 1`). **Byte-for-byte compatible** with the
35
+ [qp-poseidon-core](https://crates.io/crates/qp-poseidon-core)
36
+ reference used by [Plonky2](https://github.com/mir-protocol/plonky2)
37
+ and the [Quantus Substrate runtime](https://github.com/Quantus-Network/chain).
38
+
39
+ **Zero runtime dependencies.** Python 3.10+, standard library only.
40
+
41
+ ## What is this for
42
+
43
+ - **ZK-circuit debugging.** You have a Rust prover emitting Poseidon2
44
+ hashes and you want to sanity-check a witness or a public input in
45
+ Python without pulling a Rust toolchain.
46
+ - **Audit cross-check.** Someone hands you a Poseidon2 digest allegedly
47
+ computed by Plonky2 — you can verify it here without trusting their
48
+ build.
49
+ - **Teaching / reproducing.** The Poseidon2 paper spec (eprint 2023/323)
50
+ maps to concrete code in `permutation.py`, next to the round-count
51
+ and matrix definitions from the same paper.
52
+ - **Small tools** that need Poseidon2 without a heavyweight FFI stack.
53
+
54
+ **Not a production prover backend.** Pure Python is 100x-1000x slower
55
+ than an optimised Rust/C implementation. Use it to verify someone
56
+ else's output, not to prove your own.
57
+
58
+ ## Install
59
+
60
+ ```bash
61
+ pip install zeropx-poseidon2-goldilocks
62
+ ```
63
+ *(Python import module: `poseidon2_goldilocks`)*
64
+
65
+ ## Use
66
+
67
+ ```python
68
+ from poseidon2_goldilocks import (
69
+ permute, hash_no_pad, hash_bytes,
70
+ GOLDILOCKS_PRIME, SPONGE_WIDTH, POSEIDON2_OUTPUT,
71
+ )
72
+
73
+ # 12-element field state -> 12-element field state
74
+ out = permute([0] * SPONGE_WIDTH)
75
+
76
+ # Variable-length field-element input -> 4-element digest
77
+ digest = hash_no_pad([1, 2, 3, 4, 5])
78
+
79
+ # Arbitrary bytes -> 32-byte digest (8 bytes/felt, little-endian).
80
+ # This is the same composition Quantus uses for header preimages.
81
+ d32 = hash_bytes(b"hello world")
82
+ ```
83
+
84
+ ### Binary Merkle tree (v0.2+)
85
+
86
+ ```python
87
+ from poseidon2_goldilocks import (
88
+ hash_no_pad, merkle_root, merkle_proof, verify_merkle_proof,
89
+ )
90
+
91
+ # Each leaf is a 4-element digest — hash your data first
92
+ leaves = [tuple(hash_no_pad([i])) for i in range(5)]
93
+ root = merkle_root(leaves)
94
+
95
+ # Produce and verify an inclusion proof for leaf index 2
96
+ proof = merkle_proof(leaves, 2)
97
+ assert verify_merkle_proof(root, leaves[2], proof, 2)
98
+
99
+ # Tamper detection: a proof for index 2 will not verify at index 3
100
+ assert not verify_merkle_proof(root, leaves[2], proof, 3)
101
+ ```
102
+
103
+ Trees are padded to the next power of two with `EMPTY_DIGEST` (all
104
+ zeros). A proof is a list of `(sibling_digest, "L"|"R")` pairs. The
105
+ verifier cross-checks each `L`/`R` label against the corresponding
106
+ bit of the leaf index, so a proof cannot be replayed at the wrong
107
+ position even if it accidentally hashes to the same root.
108
+
109
+ ## Compatibility
110
+
111
+ This package produces identical output to `qp-poseidon-core v3.1.0`
112
+ for its default configuration (width=12, rate=8, capacity=4, S-box
113
+ d=7, RF=8, RP=22). The round constants and matrix-diagonal values are
114
+ copied verbatim from that reference (originally generated by
115
+ `qp-poseidon-constants` from seed `0x3141592653589793`).
116
+
117
+ Test vectors from the reference implementation's own test suite are
118
+ in `tests/test_permutation.py` — the `P3_ZERO_RESULT` and
119
+ `P3_SEQ_RESULT` constants are the expected output of
120
+ `permute([0]*12)` and `permute([0,1,2,...,11])` respectively.
121
+
122
+ ## Non-canonical input caveat
123
+
124
+ `hash_bytes` reads its input 8 bytes per field element as
125
+ little-endian u64. If any of those chunks decode to a value ≥
126
+ GOLDILOCKS_PRIME, it will be silently reduced. This matches the
127
+ reference `bytes_to_digest`, but it means the bytes→hash mapping is
128
+ not injective at the field boundary. Guards at higher layers (e.g.
129
+ `BytesDigest::try_from` in `qp-wormhole-inputs`) reject non-canonical
130
+ input before calling this. If you need injectivity, do the same
131
+ check yourself.
132
+
133
+ ## Related packages
134
+
135
+ - **[qp-poseidon-core](https://crates.io/crates/qp-poseidon-core)** —
136
+ the Rust reference this package tracks.
137
+ - **[poseidon-hash](https://pypi.org/project/poseidon-hash/)** —
138
+ reference implementation of the *original* Poseidon (not Poseidon2)
139
+ by Ingonyama. Requires `galois` and `numpy`. Different algorithm,
140
+ different constants.
141
+ - **[Poseidon Cryptanalysis Initiative](https://www.poseidon-initiative.info/)** —
142
+ Ethereum Foundation bounty program (2024-2026) targeting round-reduced
143
+ Poseidon and Poseidon2 instances, including this exact `Poseidon-64
144
+ over Goldilocks (d=7, t=8)` family.
145
+
146
+ ## Author & Provenance
147
+
148
+ **Sole Author:** Dr. Vander Geraldo Rodrigues da Cunha Júnior (`vgrcjr@gmail.com`).
149
+
150
+ *Technical & AI-Assisted Provenance Disclosure:* Auxiliary computational/LLM tooling was used strictly for boilerplate and test-harness scaffolding under 1:1 human architectural design, code review, deterministic reference-vector verification (`qp-poseidon-core` / `Plonky2`), and sole human authorship. Zero runtime third-party or AI dependencies.
151
+
152
+ ## License
153
+
154
+ MIT.
@@ -0,0 +1,124 @@
1
+ # zeropx-poseidon2-goldilocks
2
+
3
+ Pure-Python Poseidon2 permutation and hash over the Goldilocks field
4
+ (`p = 2^64 - 2^32 + 1`). **Byte-for-byte compatible** with the
5
+ [qp-poseidon-core](https://crates.io/crates/qp-poseidon-core)
6
+ reference used by [Plonky2](https://github.com/mir-protocol/plonky2)
7
+ and the [Quantus Substrate runtime](https://github.com/Quantus-Network/chain).
8
+
9
+ **Zero runtime dependencies.** Python 3.10+, standard library only.
10
+
11
+ ## What is this for
12
+
13
+ - **ZK-circuit debugging.** You have a Rust prover emitting Poseidon2
14
+ hashes and you want to sanity-check a witness or a public input in
15
+ Python without pulling a Rust toolchain.
16
+ - **Audit cross-check.** Someone hands you a Poseidon2 digest allegedly
17
+ computed by Plonky2 — you can verify it here without trusting their
18
+ build.
19
+ - **Teaching / reproducing.** The Poseidon2 paper spec (eprint 2023/323)
20
+ maps to concrete code in `permutation.py`, next to the round-count
21
+ and matrix definitions from the same paper.
22
+ - **Small tools** that need Poseidon2 without a heavyweight FFI stack.
23
+
24
+ **Not a production prover backend.** Pure Python is 100x-1000x slower
25
+ than an optimised Rust/C implementation. Use it to verify someone
26
+ else's output, not to prove your own.
27
+
28
+ ## Install
29
+
30
+ ```bash
31
+ pip install zeropx-poseidon2-goldilocks
32
+ ```
33
+ *(Python import module: `poseidon2_goldilocks`)*
34
+
35
+ ## Use
36
+
37
+ ```python
38
+ from poseidon2_goldilocks import (
39
+ permute, hash_no_pad, hash_bytes,
40
+ GOLDILOCKS_PRIME, SPONGE_WIDTH, POSEIDON2_OUTPUT,
41
+ )
42
+
43
+ # 12-element field state -> 12-element field state
44
+ out = permute([0] * SPONGE_WIDTH)
45
+
46
+ # Variable-length field-element input -> 4-element digest
47
+ digest = hash_no_pad([1, 2, 3, 4, 5])
48
+
49
+ # Arbitrary bytes -> 32-byte digest (8 bytes/felt, little-endian).
50
+ # This is the same composition Quantus uses for header preimages.
51
+ d32 = hash_bytes(b"hello world")
52
+ ```
53
+
54
+ ### Binary Merkle tree (v0.2+)
55
+
56
+ ```python
57
+ from poseidon2_goldilocks import (
58
+ hash_no_pad, merkle_root, merkle_proof, verify_merkle_proof,
59
+ )
60
+
61
+ # Each leaf is a 4-element digest — hash your data first
62
+ leaves = [tuple(hash_no_pad([i])) for i in range(5)]
63
+ root = merkle_root(leaves)
64
+
65
+ # Produce and verify an inclusion proof for leaf index 2
66
+ proof = merkle_proof(leaves, 2)
67
+ assert verify_merkle_proof(root, leaves[2], proof, 2)
68
+
69
+ # Tamper detection: a proof for index 2 will not verify at index 3
70
+ assert not verify_merkle_proof(root, leaves[2], proof, 3)
71
+ ```
72
+
73
+ Trees are padded to the next power of two with `EMPTY_DIGEST` (all
74
+ zeros). A proof is a list of `(sibling_digest, "L"|"R")` pairs. The
75
+ verifier cross-checks each `L`/`R` label against the corresponding
76
+ bit of the leaf index, so a proof cannot be replayed at the wrong
77
+ position even if it accidentally hashes to the same root.
78
+
79
+ ## Compatibility
80
+
81
+ This package produces identical output to `qp-poseidon-core v3.1.0`
82
+ for its default configuration (width=12, rate=8, capacity=4, S-box
83
+ d=7, RF=8, RP=22). The round constants and matrix-diagonal values are
84
+ copied verbatim from that reference (originally generated by
85
+ `qp-poseidon-constants` from seed `0x3141592653589793`).
86
+
87
+ Test vectors from the reference implementation's own test suite are
88
+ in `tests/test_permutation.py` — the `P3_ZERO_RESULT` and
89
+ `P3_SEQ_RESULT` constants are the expected output of
90
+ `permute([0]*12)` and `permute([0,1,2,...,11])` respectively.
91
+
92
+ ## Non-canonical input caveat
93
+
94
+ `hash_bytes` reads its input 8 bytes per field element as
95
+ little-endian u64. If any of those chunks decode to a value ≥
96
+ GOLDILOCKS_PRIME, it will be silently reduced. This matches the
97
+ reference `bytes_to_digest`, but it means the bytes→hash mapping is
98
+ not injective at the field boundary. Guards at higher layers (e.g.
99
+ `BytesDigest::try_from` in `qp-wormhole-inputs`) reject non-canonical
100
+ input before calling this. If you need injectivity, do the same
101
+ check yourself.
102
+
103
+ ## Related packages
104
+
105
+ - **[qp-poseidon-core](https://crates.io/crates/qp-poseidon-core)** —
106
+ the Rust reference this package tracks.
107
+ - **[poseidon-hash](https://pypi.org/project/poseidon-hash/)** —
108
+ reference implementation of the *original* Poseidon (not Poseidon2)
109
+ by Ingonyama. Requires `galois` and `numpy`. Different algorithm,
110
+ different constants.
111
+ - **[Poseidon Cryptanalysis Initiative](https://www.poseidon-initiative.info/)** —
112
+ Ethereum Foundation bounty program (2024-2026) targeting round-reduced
113
+ Poseidon and Poseidon2 instances, including this exact `Poseidon-64
114
+ over Goldilocks (d=7, t=8)` family.
115
+
116
+ ## Author & Provenance
117
+
118
+ **Sole Author:** Dr. Vander Geraldo Rodrigues da Cunha Júnior (`vgrcjr@gmail.com`).
119
+
120
+ *Technical & AI-Assisted Provenance Disclosure:* Auxiliary computational/LLM tooling was used strictly for boilerplate and test-harness scaffolding under 1:1 human architectural design, code review, deterministic reference-vector verification (`qp-poseidon-core` / `Plonky2`), and sole human authorship. Zero runtime third-party or AI dependencies.
121
+
122
+ ## License
123
+
124
+ MIT.
@@ -0,0 +1,44 @@
1
+ [build-system]
2
+ requires = ["hatchling>=1.24"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "zeropx-poseidon2-goldilocks"
7
+ version = "0.2.0"
8
+ description = "Pure-Python Poseidon2 permutation and hash over the Goldilocks field (2^64 - 2^32 + 1). Byte-for-byte compatible with the Plonky2 / qp-poseidon-core reference. Zero runtime dependencies."
9
+ readme = "README.md"
10
+ requires-python = ">=3.10"
11
+ license = { text = "MIT" }
12
+ authors = [{ name = "Dr. Vander Geraldo Rodrigues da Cunha Júnior", email = "vgrcjr@gmail.com" }]
13
+ keywords = ["poseidon2", "poseidon", "goldilocks", "zero-knowledge", "plonky2", "hash", "cryptography"]
14
+ classifiers = [
15
+ "Development Status :: 4 - Beta",
16
+ "Intended Audience :: Developers",
17
+ "Intended Audience :: Science/Research",
18
+ "License :: OSI Approved :: MIT License",
19
+ "Programming Language :: Python :: 3",
20
+ "Programming Language :: Python :: 3 :: Only",
21
+ "Programming Language :: Python :: 3.10",
22
+ "Programming Language :: Python :: 3.11",
23
+ "Programming Language :: Python :: 3.12",
24
+ "Programming Language :: Python :: 3.13",
25
+ "Programming Language :: Python :: 3.14",
26
+ "Topic :: Security :: Cryptography",
27
+ "Topic :: Software Development :: Libraries :: Python Modules",
28
+ "Typing :: Typed",
29
+ ]
30
+ dependencies = []
31
+
32
+ [project.optional-dependencies]
33
+ dev = ["pytest>=7"]
34
+
35
+ [project.urls]
36
+ Homepage = "https://github.com/NixEngine/zeropx-poseidon2-goldilocks"
37
+ Repository = "https://github.com/NixEngine/zeropx-poseidon2-goldilocks"
38
+ Issues = "https://github.com/NixEngine/zeropx-poseidon2-goldilocks/issues"
39
+
40
+ [tool.hatch.build.targets.wheel]
41
+ packages = ["src/poseidon2_goldilocks"]
42
+
43
+ [tool.hatch.build.targets.sdist]
44
+ include = ["/src", "/tests", "/README.md", "/LICENSE", "/CHANGELOG.md"]
@@ -0,0 +1,88 @@
1
+ """poseidon2-goldilocks — pure-Python Poseidon2 over the Goldilocks field (width=12).
2
+
3
+ Byte-for-byte compatible with the qp-poseidon-core v3.1.0 reference
4
+ used by Plonky2 and the Quantus Substrate runtime. Zero runtime
5
+ dependencies. Pure Python — no C extensions, no `galois`, no
6
+ `numpy`. Intended for auditors, cross-check tooling, ZK-circuit
7
+ debugging, and light Poseidon2 use where a heavyweight FFI stack is
8
+ overkill.
9
+
10
+ Not intended as a production prover backend: pure Python is 100x-1000x
11
+ slower than an optimised Rust/C implementation. Use it to verify
12
+ someone else's output, not to prove your own.
13
+
14
+ Public API:
15
+
16
+ from poseidon2_goldilocks import permute, hash_no_pad, GOLDILOCKS_PRIME
17
+
18
+ # 12-element field state -> 12-element field state
19
+ out = permute([0] * 12)
20
+
21
+ # arbitrary field-element input -> 4-element digest
22
+ digest = hash_no_pad([1, 2, 3, 4, 5])
23
+
24
+ # arbitrary bytes -> 32-byte digest (8 bytes/felt, little-endian)
25
+ from poseidon2_goldilocks import hash_bytes
26
+ d32 = hash_bytes(b"hello world")
27
+ """
28
+
29
+ from __future__ import annotations
30
+
31
+ __version__ = "0.2.0"
32
+
33
+ from .goldilocks import (
34
+ GOLDILOCKS_PRIME,
35
+ canonical,
36
+ exp7,
37
+ to_canonical_u64,
38
+ )
39
+ from .permutation import (
40
+ permute,
41
+ permute_mut,
42
+ external_linear_layer,
43
+ internal_linear_layer,
44
+ )
45
+ from .constants import (
46
+ SPONGE_WIDTH,
47
+ SPONGE_RATE,
48
+ SPONGE_CAPACITY,
49
+ )
50
+ from .sponge import (
51
+ hash_no_pad,
52
+ hash_bytes,
53
+ POSEIDON2_OUTPUT,
54
+ )
55
+ from .merkle import (
56
+ hash_pair,
57
+ merkle_root,
58
+ merkle_proof,
59
+ verify_merkle_proof,
60
+ EMPTY_DIGEST,
61
+ )
62
+
63
+ __all__ = [
64
+ "__version__",
65
+ # field
66
+ "GOLDILOCKS_PRIME",
67
+ "canonical",
68
+ "exp7",
69
+ "to_canonical_u64",
70
+ # permutation
71
+ "permute",
72
+ "permute_mut",
73
+ "external_linear_layer",
74
+ "internal_linear_layer",
75
+ "SPONGE_WIDTH",
76
+ "SPONGE_RATE",
77
+ "SPONGE_CAPACITY",
78
+ # sponge / hashing
79
+ "hash_no_pad",
80
+ "hash_bytes",
81
+ "POSEIDON2_OUTPUT",
82
+ # binary merkle tree
83
+ "hash_pair",
84
+ "merkle_root",
85
+ "merkle_proof",
86
+ "verify_merkle_proof",
87
+ "EMPTY_DIGEST",
88
+ ]
@@ -0,0 +1,95 @@
1
+ """Poseidon2 constants for width=12 over the Goldilocks prime field.
2
+
3
+ Values are the ones used by Plonky2 / qp-poseidon-core / the Quantus
4
+ runtime as of qp-poseidon-core v3.1.0. They were originally generated
5
+ by qp-poseidon-constants from seed `0x3141592653589793`. See the
6
+ Poseidon2 paper (eprint 2023/323) for the algorithm; see the reference
7
+ Rust implementation for the exact numeric values, which are
8
+ reproduced verbatim here so this package produces byte-for-byte
9
+ identical permutation output to Plonky2.
10
+
11
+ If a downstream user needs a different width or a different set of
12
+ constants (different seed, different security level, a different
13
+ target field like BLS12-381 or M31), they should build a separate
14
+ module — mixing constants silently is the fastest way to produce a
15
+ permutation that runs and validates but disagrees with everyone
16
+ else's Poseidon2.
17
+ """
18
+
19
+ from __future__ import annotations
20
+
21
+ SPONGE_WIDTH: int = 12
22
+ SPONGE_RATE: int = 8
23
+ SPONGE_CAPACITY: int = SPONGE_WIDTH - SPONGE_RATE
24
+ POSEIDON2_OUTPUT: int = 4
25
+ INTERNAL_ROUNDS: int = 22
26
+ EXTERNAL_ROUNDS: int = 8
27
+ HALF_EXTERNAL_ROUNDS: int = EXTERNAL_ROUNDS // 2
28
+
29
+
30
+ INTERNAL_CONSTANTS: tuple[int, ...] = (
31
+ 10950354654605269091, 15119356940911695088, 7612059357007237638,
32
+ 12236395664799796772, 2977570947024676277, 6373970340753430342,
33
+ 9946283046412846796, 4463022581802230821, 4150295645638148407,
34
+ 4490915162115027274, 10829504123483496140, 4597224039659100030,
35
+ 10266435449820638573, 9552757317149730134, 17182064290885366998,
36
+ 2165695174462817354, 1097317823465564870, 1947274085218180819,
37
+ 1813898247148918694, 17786016722733367904, 4522584789973874566,
38
+ 6140884543838897619,
39
+ )
40
+
41
+ MATRIX_DIAG: tuple[int, ...] = (
42
+ 14102670999874605824, 15585654191999307702, 940187017142450255,
43
+ 8747386241522630711, 6750641561540124747, 7440998025584530007,
44
+ 6136358134615751536, 12413576830284969611, 11675438539028694709,
45
+ 17580553691069642926, 892707462476851331, 15167485180850043744,
46
+ )
47
+
48
+
49
+ INITIAL_EXTERNAL_CONSTANTS: tuple[tuple[int, ...], ...] = (
50
+ (13835875475997267463, 13593300247443167546, 8256098654959761401,
51
+ 16497527840820049068, 15411522637299147849, 17020150177669596865,
52
+ 5219051110225758042, 7790297870083302641, 16425486905783891643,
53
+ 15683309641931586601, 16544887301834777006, 3043822364766212060),
54
+ (12511554865575947557, 2815218757487154454, 5397191216188696727,
55
+ 6263167237941024378, 2268298353185649950, 3891183183650783080,
56
+ 16503280268681069520, 18218637884622147757, 14810472806729743006,
57
+ 4746652143794040382, 17167206695294637949, 15175925601089995781),
58
+ ( 9033104775021388674, 9921017235607945260, 12923798861715797527,
59
+ 15786281414702354803, 8714540470225280152, 2761431909488453770,
60
+ 11068269652872909615, 7255476598362472915, 17152841886271966136,
61
+ 5752572615743285230, 6296806204286062663, 17660184115874751421),
62
+ ( 2188234123236287607, 7071885762696490733, 12261132718627234478,
63
+ 7190250995558642684, 4297991823969990112, 2588908926796910813,
64
+ 12309391821249485402, 16850936440481388618, 14821697447947797068,
65
+ 10388886288248231395, 6579267572940231471, 16030945643832113911),
66
+ )
67
+
68
+
69
+ TERMINAL_EXTERNAL_CONSTANTS: tuple[tuple[int, ...], ...] = (
70
+ ( 8895389066387410030, 1460701038096849270, 9232424000661355656,
71
+ 7869694012000561090, 11674967405510647539, 17791439039604636207,
72
+ 3816678204163591524, 12701925137758912458, 7268169701857820838,
73
+ 1067589902488001943, 2070308862709674891, 7382496027314534074),
74
+ ( 6944427652715851265, 4599841608850341455, 16721906878468876749,
75
+ 17856999528157411150, 17553134374929059977, 7890458318273453558,
76
+ 17906430202258692747, 6331829681132802170, 1650501125073619501,
77
+ 2395319349875521589, 12750456425164666614, 15628562918670685207),
78
+ (16472031182362063631, 8519479891090086696, 650980590610947853,
79
+ 8543868547028952308, 1027758676635423666, 10647516517072103279,
80
+ 11022005145419959786, 16418258577134197184, 2230831754333088463,
81
+ 802979627989531812, 7080627001952875303, 6853960081492534406),
82
+ (18303760418668938283, 8239306592877361155, 16622244490604654200,
83
+ 6274074331584152849, 17886681876111343804, 3231554205214632021,
84
+ 9020704674996646513, 9632659917939292177, 5954679916794327224,
85
+ 5786083536133615252, 13610804294834768633, 16186843687143828937),
86
+ )
87
+
88
+ # Sanity check the shapes at import time — a length mismatch here means
89
+ # someone edited the tables and forgot to regenerate the sibling.
90
+ assert len(INTERNAL_CONSTANTS) == INTERNAL_ROUNDS
91
+ assert len(MATRIX_DIAG) == SPONGE_WIDTH
92
+ assert len(INITIAL_EXTERNAL_CONSTANTS) == HALF_EXTERNAL_ROUNDS
93
+ assert all(len(row) == SPONGE_WIDTH for row in INITIAL_EXTERNAL_CONSTANTS)
94
+ assert len(TERMINAL_EXTERNAL_CONSTANTS) == HALF_EXTERNAL_ROUNDS
95
+ assert all(len(row) == SPONGE_WIDTH for row in TERMINAL_EXTERNAL_CONSTANTS)
@@ -0,0 +1,71 @@
1
+ """Arithmetic over the Goldilocks prime field.
2
+
3
+ The Goldilocks prime is p = 2^64 - 2^32 + 1 = 0xFFFFFFFF00000001.
4
+
5
+ This module implements just enough field arithmetic to run the
6
+ Poseidon2 permutation: addition, multiplication, seventh power,
7
+ double, and a canonical-form projection. Everything is expressed as
8
+ plain Python ints and uses `% GOLDILOCKS_PRIME` for reduction. No
9
+ external dependencies, no assumptions beyond Python's arbitrary
10
+ precision ints.
11
+
12
+ Values used inside the permutation are ALWAYS reduced to
13
+ `[0, GOLDILOCKS_PRIME)` before being returned or stored, so
14
+ `poseidon2` observers can compare with the reference implementation's
15
+ canonical-u64 output without additional normalisation.
16
+ """
17
+
18
+ from __future__ import annotations
19
+
20
+ GOLDILOCKS_PRIME: int = (1 << 64) - (1 << 32) + 1 # 0xFFFFFFFF00000001
21
+
22
+
23
+ def canonical(x: int) -> int:
24
+ """Return the canonical representative of `x` mod GOLDILOCKS_PRIME."""
25
+ r = x % GOLDILOCKS_PRIME
26
+ if r < 0:
27
+ r += GOLDILOCKS_PRIME
28
+ return r
29
+
30
+
31
+ def add(a: int, b: int) -> int:
32
+ return (a + b) % GOLDILOCKS_PRIME
33
+
34
+
35
+ def sub(a: int, b: int) -> int:
36
+ return (a - b) % GOLDILOCKS_PRIME
37
+
38
+
39
+ def mul(a: int, b: int) -> int:
40
+ return (a * b) % GOLDILOCKS_PRIME
41
+
42
+
43
+ def double(a: int) -> int:
44
+ return (a + a) % GOLDILOCKS_PRIME
45
+
46
+
47
+ def exp7(a: int) -> int:
48
+ """Compute a^7 mod p. The Poseidon2 S-box.
49
+
50
+ Implemented as `a * a` cubed then multiplied by `a` — six field
51
+ multiplications total. Matches the reference `Goldilocks::exp7`.
52
+ """
53
+ a2 = (a * a) % GOLDILOCKS_PRIME
54
+ a4 = (a2 * a2) % GOLDILOCKS_PRIME
55
+ a6 = (a4 * a2) % GOLDILOCKS_PRIME
56
+ return (a6 * a) % GOLDILOCKS_PRIME
57
+
58
+
59
+ def from_u64(x: int) -> int:
60
+ """Interpret an arbitrary 64-bit integer as a field element.
61
+
62
+ Follows the reference `Goldilocks::new(u64)` behaviour — no range
63
+ check on the input; caller supplies a value that already fits a
64
+ u64. Reduction to canonical form happens lazily during arithmetic.
65
+ """
66
+ return x & 0xFFFFFFFFFFFFFFFF
67
+
68
+
69
+ def to_canonical_u64(a: int) -> int:
70
+ """Project a field element to its canonical `u64` representative."""
71
+ return canonical(a)