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.
- zeropx_poseidon2_goldilocks-0.2.0/.gitignore +11 -0
- zeropx_poseidon2_goldilocks-0.2.0/CHANGELOG.md +50 -0
- zeropx_poseidon2_goldilocks-0.2.0/LICENSE +21 -0
- zeropx_poseidon2_goldilocks-0.2.0/PKG-INFO +154 -0
- zeropx_poseidon2_goldilocks-0.2.0/README.md +124 -0
- zeropx_poseidon2_goldilocks-0.2.0/pyproject.toml +44 -0
- zeropx_poseidon2_goldilocks-0.2.0/src/poseidon2_goldilocks/__init__.py +88 -0
- zeropx_poseidon2_goldilocks-0.2.0/src/poseidon2_goldilocks/constants.py +95 -0
- zeropx_poseidon2_goldilocks-0.2.0/src/poseidon2_goldilocks/goldilocks.py +71 -0
- zeropx_poseidon2_goldilocks-0.2.0/src/poseidon2_goldilocks/merkle.py +207 -0
- zeropx_poseidon2_goldilocks-0.2.0/src/poseidon2_goldilocks/permutation.py +159 -0
- zeropx_poseidon2_goldilocks-0.2.0/src/poseidon2_goldilocks/sponge.py +91 -0
- zeropx_poseidon2_goldilocks-0.2.0/tests/test_merkle.py +199 -0
- zeropx_poseidon2_goldilocks-0.2.0/tests/test_permutation.py +157 -0
|
@@ -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)
|