@rolly-dev/wasm-signer 1.27.0 → 1.28.1

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,148 @@
1
+ # @rolly-dev/wasm-signer
2
+
3
+ Client-side Poseidon2 hashing and bet authentication for the Rolly ZK-Rollup casino.
4
+
5
+ Built with Rust → WebAssembly (via `wasm-pack`), using the same Poseidon2 hasher
6
+ and Goldilocks field as the plonky2 proving circuit.
7
+
8
+ ## Build
9
+
10
+ ```bash
11
+ # requires: cargo, wasm-pack
12
+ npm run build
13
+ # → dist/node/ (Node.js, CJS, sync init)
14
+ # → dist/web/ (Browser, ESM, async init)
15
+ ```
16
+
17
+ ## Usage
18
+
19
+ ### Node.js (CommonJS)
20
+
21
+ ```javascript
22
+ const {
23
+ poseidon2_hash,
24
+ derive_session_key,
25
+ session_public_key,
26
+ } = require('@rolly-dev/wasm-signer');
27
+
28
+ const hash = poseidon2_hash(BigUint64Array.from([1n, 2n, 3n]));
29
+ // → BigUint64Array(4)
30
+ ```
31
+
32
+ ### Node.js (ESM)
33
+
34
+ ```javascript
35
+ import {
36
+ poseidon2_hash,
37
+ derive_session_key,
38
+ session_public_key,
39
+ } from '@rolly-dev/wasm-signer';
40
+
41
+ const sessionKey = derive_session_key(metamaskSignatureBytes);
42
+ const pkHash = session_public_key(sessionKey, BigInt(expiryTimestamp));
43
+ ```
44
+
45
+ ### React
46
+
47
+ ```jsx
48
+ import { useRollyWasm } from '@rolly-dev/wasm-signer/react';
49
+
50
+ function SessionInfo({ sessionKey, expiry }) {
51
+ const { ready, session_public_key } = useRollyWasm();
52
+
53
+ if (!ready) return <span>Loading...</span>;
54
+
55
+ const pkHash = session_public_key(sessionKey, BigInt(expiry));
56
+ // register pkHash on-chain via key_register tx...
57
+
58
+ return <div>Session active until {new Date(Number(expiry) * 1000).toLocaleString()}</div>;
59
+ }
60
+ ```
61
+
62
+ ### Browser (vanilla ESM)
63
+
64
+ ```html
65
+ <script type="module">
66
+ import { init, poseidon2_hash } from '@rolly-dev/wasm-signer';
67
+
68
+ await init(); // loads .wasm, must be called once
69
+ const h = poseidon2_hash(BigUint64Array.from([1n, 2n]));
70
+ </script>
71
+ ```
72
+
73
+ ### Manual init (advanced)
74
+
75
+ ```javascript
76
+ import init, { poseidon2_hash } from '@rolly-dev/wasm-signer/init';
77
+
78
+ // custom wasm URL or ArrayBuffer
79
+ await init('/assets/rolly_wasm_signer_bg.wasm');
80
+ poseidon2_hash(BigUint64Array.from([1n]));
81
+ ```
82
+
83
+ ## API
84
+
85
+ | Function | Input | Output | Description |
86
+ |----------------------------|--------------------------------|-------------------|------------------------------------------------|
87
+ | `poseidon2_hash` | `BigUint64Array` | `BigUint64Array(4)` | Hash N field elements |
88
+ | `poseidon2_two_to_one` | `BigUint64Array(4)` × 2 | `BigUint64Array(4)` | Merkle hash: H(left‖right) |
89
+ | `derive_session_key` | `Uint8Array(32)` | `BigUint64Array(4)` | MetaMask sig → session key |
90
+ | `session_public_key` | `(BigUint64Array(4), bigint)` | `BigUint64Array(4)` | pk_hash = Poseidon2(session_key, expiry) |
91
+ | `compute_server_seed_hash` | `BigUint64Array(8)` | `BigUint64Array(4)` | Full hash of server seed |
92
+ | `seed_hash_truncated` | `BigUint64Array(8)` | `BigUint64Array(3)` | First 3 elements (circuit leaf format, 192-bit commitment) |
93
+ | `goldilocks_modulus` | — | `bigint` | Returns p = 2^64 - 2^32 + 1 |
94
+ | `goldilocks_reduce` | `bigint` | `bigint` | Reduce mod p |
95
+
96
+ ## Bundler notes
97
+
98
+ **Vite** — add to `optimizeDeps.exclude`:
99
+ ```js
100
+ optimizeDeps: { exclude: ['@rolly-dev/wasm-signer'] }
101
+ ```
102
+
103
+ **Webpack 5** — enable WASM experiments:
104
+ ```js
105
+ module.exports = { experiments: { asyncWebAssembly: true } };
106
+ ```
107
+
108
+ **Next.js** — conditional exports auto-resolve: Node.js entry on server, browser entry on client.
109
+
110
+ ## Dice — range constraints
111
+
112
+ Roll number: `[0, 999]` (TOTAL_RANGE = 1000).
113
+ win_numbers (wn): `[1, 950]` (MIN_RANGE..=MAX_RANGE).
114
+
115
+ ### prediction_range constraints per mode
116
+
117
+ | Mode | wn formula | prediction\[0\] | prediction\[1\] | wn range |
118
+ |-------|-------------------------------------------------|-----------------|-----------------|------------|
119
+ | Under | `prediction[0]` | `[1, 950]` | unused (0) | `[1, 950]` |
120
+ | Over | `999 − prediction[0]` | `[49, 998]` | unused (0) | `[1, 950]` |
121
+ | In | `prediction[1] − prediction[0] + 1` | `[0, 999]` | `[0, 999]` | `[1, 950]` |
122
+ | Out | `1000 − (prediction[1] − prediction[0] + 1)` | `[0, 999]` | `[0, 999]` | `[1, 950]` |
123
+
124
+ **Under** — `prediction[0]` ∈ `[1, 950]` (= wn directly). Win: `roll < prediction[0]`.
125
+
126
+ **Over** — `prediction[0]` ∈ `[49, 998]` (lower: `999 − 950 = 49`, upper: `999 − 1 = 998`). Win: `roll > prediction[0]`.
127
+
128
+ **In** — `prediction[0] <= prediction[1]`, span ∈ `[1, 950]`. Win: `prediction[0] <= roll <= prediction[1]`.
129
+
130
+ **Out** — `prediction[0] <= prediction[1]`, inner span ∈ `[50, 999]` (wn = `1000 − inner` ∈ `[1, 950]`). Win: `roll < prediction[0] || roll > prediction[1]`.
131
+
132
+ ### Multiplier
133
+
134
+ `multiplier = floor(9_900_000 / wn)` (scaled ×10000).
135
+
136
+ | wn | multiplier | display |
137
+ |-----|-----------|-----------|
138
+ | 1 | 9_900_000 | 990.0000x |
139
+ | 500 | 19_800 | 1.9800x |
140
+ | 950 | 10_421 | 1.0421x |
141
+
142
+ ### RTP
143
+
144
+ Theoretical: **98.998%** (floor-division costs ~0.002%). House edge: **~1.002%**. Max win cap: 10,000 USDT (business rule, not formula).
145
+
146
+ ## License
147
+
148
+ MIT
@@ -0,0 +1 @@
1
+ {"type":"commonjs"}
@@ -0,0 +1,487 @@
1
+ /* tslint:disable */
2
+ /* eslint-disable */
3
+
4
+ /**
5
+ * Split a u64 amount into (lo, hi) u32 pair matching the circuit representation.
6
+ *
7
+ * Returns `[amount_lo, amount_hi]` as a `Uint32Array` of length 2.
8
+ *
9
+ * ```js
10
+ * const [lo, hi] = amount_split(123456789n);
11
+ * ```
12
+ */
13
+ export function amount_split(amount: bigint): Uint32Array;
14
+
15
+ /**
16
+ * Aviato RTP percent (99). Canonical source for backend/frontend.
17
+ */
18
+ export function aviato_rtp_percent(): number;
19
+
20
+ /**
21
+ * CoinFlip multiplier × 10000 (19800 = 1.98×). Canonical source for backend/frontend.
22
+ */
23
+ export function coinflip_multiplier_x10000(): number;
24
+
25
+ /**
26
+ * CoinFlip RTP percent (99). Canonical source for backend/frontend.
27
+ */
28
+ export function coinflip_rtp_percent(): number;
29
+
30
+ /**
31
+ * Compute address_hash = Poseidon2(addr_byte_0, ..., addr_byte_19).
32
+ * Takes a hex address string (with or without 0x prefix), returns [u64; 4].
33
+ */
34
+ export function compute_address_hash(address_hex: string): BigUint64Array;
35
+
36
+ /**
37
+ * Extract aviato point (×100) from raw server seed fields.
38
+ *
39
+ * `random` must be exactly 4 elements (first 4 fields of server_seed).
40
+ * Returns the clamped aviato multiplier ×100 (100..=1_000_000, i.e. 1.00x..10000.00x).
41
+ */
42
+ export function compute_aviato_point(random: BigUint64Array): number;
43
+
44
+ /**
45
+ * Extract the 10 drawn numbers from Poseidon2 random output using
46
+ * the combinatorial number system: `combo_index = random[0] % C(40,10)`.
47
+ *
48
+ * `random` must be exactly 4 elements.
49
+ * Returns `Uint8Array` of length 10 (sorted ascending, each in [0, 39]).
50
+ */
51
+ export function compute_drawn_keno(random: BigUint64Array): Uint8Array;
52
+
53
+ /**
54
+ * Compute dice multiplier × 10000 from win_numbers count.
55
+ *
56
+ * Formula: `9_900_000 / win_numbers` (integer division = floor).
57
+ * `win_numbers` must be in [1, 950].
58
+ */
59
+ export function compute_multi_dice(win_numbers: number): bigint;
60
+
61
+ /**
62
+ * Full aviato payout computation — pure integer arithmetic, zero floats.
63
+ *
64
+ * `random`: 4 Goldilocks field elements (first 4 fields of raw server_seed).
65
+ * `bet_atomic`: bet in atomic units (1 USDT = 1_000_000).
66
+ * `cashout_x100`: multiplier at which the user cashed out (×100).
67
+ * - 0 = user did NOT cash out (loss).
68
+ * - 100..=1_000_000 = user stopped at this multiplier.
69
+ *
70
+ * Returns `BigUint64Array[4]`: `[win_amount, aviato_x100, is_win (0|1), multiplier×10000]`.
71
+ */
72
+ export function compute_payout_aviato(random: BigUint64Array, bet_atomic: bigint, cashout_x100: number): BigUint64Array;
73
+
74
+ /**
75
+ * Full coinflip payout computation — pure integer arithmetic, zero floats.
76
+ *
77
+ * `random`: 4 Goldilocks field elements (Poseidon2 output).
78
+ * `bet_atomic`: bet in atomic units (1 USDT = 1_000_000).
79
+ * `prediction`: 0 or 1.
80
+ *
81
+ * Returns `BigUint64Array[4]`: `[win_amount, roll (0|1), is_win (0|1), multiplier×10000]`.
82
+ */
83
+ export function compute_payout_coinflip(random: BigUint64Array, bet_atomic: bigint, prediction: number): BigUint64Array;
84
+
85
+ /**
86
+ * Full dice payout computation — pure integer arithmetic, zero floats.
87
+ *
88
+ * `random`: 4 Goldilocks field elements (Poseidon2 output).
89
+ * `bet_atomic`: bet in atomic units (1 USDT = 1_000_000).
90
+ * `game_mode`: 0=Under, 1=Over, 2=In, 3=Out.
91
+ * `prediction_lo` / `prediction_hi`: prediction range bounds (0..999).
92
+ *
93
+ * Returns `BigUint64Array[4]`: `[win_amount, roll_number, is_win (0|1), multiplier×10000]`.
94
+ */
95
+ export function compute_payout_dice(random: BigUint64Array, bet_atomic: bigint, game_mode: number, prediction_lo: number, prediction_hi: number): BigUint64Array;
96
+
97
+ /**
98
+ * Full keno payout computation — pure integer arithmetic, zero floats.
99
+ *
100
+ * `random`: 4 Goldilocks field elements (Poseidon2 output).
101
+ * `bet_atomic`: bet in atomic units (1 USDT = 1_000_000).
102
+ * `risk`: 0=low, 1=medium, 2=high.
103
+ * `selected`: player-chosen numbers (0-indexed, each in [0, 39]).
104
+ *
105
+ * Returns `BigUint64Array[4]`: `[win_amount, match_count, is_win (0|1), multiplier×10000]`.
106
+ */
107
+ export function compute_payout_keno(random: BigUint64Array, bet_atomic: bigint, risk: number, selected: Uint8Array): BigUint64Array;
108
+
109
+ /**
110
+ * Full limbo payout computation — pure integer arithmetic, zero floats.
111
+ *
112
+ * `random`: 4 Goldilocks field elements (Poseidon2 output).
113
+ * `bet_atomic`: bet in atomic units (1 USDT = 1_000_000).
114
+ * `prediction_x100`: target multiplier x 100 (101..999999, i.e. 1.01x-9999.99x).
115
+ *
116
+ * Returns `BigUint64Array[4]`: `[win_amount, multiplier_x100, is_win (0|1), payout_multiplier x10000]`.
117
+ */
118
+ export function compute_payout_limbo(random: BigUint64Array, bet_atomic: bigint, prediction_x100: number): BigUint64Array;
119
+
120
+ /**
121
+ * Full plinko payout computation — pure integer arithmetic, zero floats.
122
+ *
123
+ * `random`: 4 Goldilocks field elements (Poseidon2 output).
124
+ * `bet_atomic`: bet in atomic units (1 USDT = 1_000_000).
125
+ * `sector`: risk profile (0=low, 1=medium, 2=high).
126
+ * `rows`: number of pin rows (8..16).
127
+ * `is_extreme`: whether extreme mode is active.
128
+ *
129
+ * Returns `BigUint64Array[4]`: `[win_amount, bucket_index, is_win (0|1), multiplier×10000]`.
130
+ */
131
+ export function compute_payout_plinko(random: BigUint64Array, bet_atomic: bigint, sector: number, rows: number, is_extreme: boolean): BigUint64Array;
132
+
133
+ /**
134
+ * Compute prediction hash: `Poseidon2(game_id, p0, p1, p2)` → 4 field elements.
135
+ *
136
+ * Matches `compute_prediction_hash_native` in the circuit (`games/shared.rs`)
137
+ * and the in-circuit `build_prediction_hash`.
138
+ *
139
+ * Semantics of p0–p2 depend on the game:
140
+ * Limbo: `(98, prediction_x100, 0)` — RTP hardcoded at 98
141
+ * Dice: `(mode, pred_lo, pred_hi)`
142
+ * Plinko: `(sector, rows, is_extreme)`
143
+ * CoinFlip: `(prediction, 0, 0)`
144
+ */
145
+ export function compute_prediction_hash(game_id: number, p0: number, p1: number, p2: number): BigUint64Array;
146
+
147
+ /**
148
+ * Compute Keno prediction hash with extended 13-input format:
149
+ * `Poseidon2(game_id, risk, pick_count, selected[0], …, selected[9])`.
150
+ *
151
+ * Selected numbers are sorted internally for deterministic output.
152
+ * Unused slots (when pick_count < 10) are filled with 0.
153
+ *
154
+ * Returns `BigUint64Array` of length 4 (one `HashOut`).
155
+ */
156
+ export function compute_prediction_hash_keno(game_id: number, risk: number, pick_count: number, selected: Uint8Array): BigUint64Array;
157
+
158
+ /**
159
+ * Extract coinflip roll (0 or 1) from Poseidon2 random output.
160
+ *
161
+ * `random` must be exactly 4 elements. Returns `random[0] % 2`.
162
+ */
163
+ export function compute_roll_coinflip(random: BigUint64Array): number;
164
+
165
+ /**
166
+ * Extract dice roll number [0, 1000) from Poseidon2 random output.
167
+ *
168
+ * `random` must be exactly 4 elements. Returns `random[0] % 1000`.
169
+ */
170
+ export function compute_roll_dice(random: BigUint64Array): number;
171
+
172
+ /**
173
+ * Extract limbo result multiplier x 100 from Poseidon2 random output.
174
+ *
175
+ * `random` must be exactly 4 elements.
176
+ * Returns the clamped multiplier x 100 (101..999999).
177
+ */
178
+ export function compute_roll_limbo(random: BigUint64Array): number;
179
+
180
+ /**
181
+ * Extract plinko bucket index from Poseidon2 random output.
182
+ *
183
+ * `random` must be exactly 4 elements.
184
+ * `rows` must be in [8, 16].
185
+ * Returns the bucket index (0..=rows) = popcount of first `rows` bits of random[0].
186
+ */
187
+ export function compute_roll_plinko(random: BigUint64Array, rows: number): number;
188
+
189
+ /**
190
+ * Full Poseidon2 hash of an 8-element server seed.
191
+ *
192
+ * Returns all 4 hash elements. Note: the circuit stores only the
193
+ * **first 3 elements** as the leaf commitment (see `seed_hash_truncated`).
194
+ * This full variant is useful for client-side verification where all
195
+ * 4 elements may be needed.
196
+ *
197
+ * `server_seed` must be exactly 8 elements.
198
+ */
199
+ export function compute_server_seed_hash(server_seed: BigUint64Array): BigUint64Array;
200
+
201
+ /**
202
+ * Compute user seed with bet-parameter binding:
203
+ * `Poseidon2(game_id, bet, pred_hash[4], secret[4])` → 4 field elements.
204
+ *
205
+ * Matches the circuit constraint in `slot/fairness.rs`.
206
+ * Prevents the operator from swapping bet parameters after the user commits.
207
+ *
208
+ * `bet` is the full bet amount in atomic units (u64).
209
+ * `pred_hash` must be 4 elements (output of `compute_prediction_hash`).
210
+ * `secret` must be 4 elements (output of `generate_user_secret`).
211
+ */
212
+ export function compute_user_seed_binding(game_id: number, bet: bigint, pred_hash: BigUint64Array, secret: BigUint64Array): BigUint64Array;
213
+
214
+ /**
215
+ * Derive a session key from 32 bytes of entropy (e.g. MetaMask signature).
216
+ *
217
+ * **Algorithm**: split 32 bytes into 4 × 8 bytes, interpret each chunk as
218
+ * little-endian u64, reduce mod p, then hash:
219
+ * `session_key = Poseidon2(reduced_chunks)`
220
+ *
221
+ * The reduction via `from_noncanonical_u64` is necessary because raw
222
+ * signature bytes can produce values >= p.
223
+ *
224
+ * ```js
225
+ * const sig = ethers.getBytes(metaMaskSignature).slice(0, 32);
226
+ * const sk = derive_session_key(new Uint8Array(sig));
227
+ * // sk.length === 4
228
+ * ```
229
+ */
230
+ export function derive_session_key(sig_bytes: Uint8Array): BigUint64Array;
231
+
232
+ /**
233
+ * Dice RTP percent (99). Canonical source for backend/frontend.
234
+ */
235
+ export function dice_rtp_percent(): number;
236
+
237
+ /**
238
+ * Encode 1-indexed Keno selected numbers into a bitmask pair `[lo, hi]`.
239
+ *
240
+ * `selected_1indexed`: player-chosen numbers as they come from the frontend (1..40).
241
+ * Returns `Uint32Array[2]`: `[lo, hi]` where `lo` covers numbers 0..29 and `hi` covers 30..39
242
+ * (0-indexed bit positions).
243
+ */
244
+ export function encode_keno_selected(selected_1indexed: Uint8Array): Uint32Array;
245
+
246
+ /**
247
+ * Generate a cryptographically random user secret — 4 Goldilocks field elements.
248
+ *
249
+ * Each element is reduced mod p for canonical representation (safe for circuit use).
250
+ * Uses `getrandom` (`crypto.getRandomValues` in browser, OS entropy in Node.js).
251
+ *
252
+ * ```js
253
+ * const secret = generate_user_secret();
254
+ * // secret.length === 4, each < GOLDILOCKS_P
255
+ * ```
256
+ */
257
+ export function generate_user_secret(): BigUint64Array;
258
+
259
+ /**
260
+ * Generate a random user seed — 10 alphanumeric characters.
261
+ *
262
+ * Uses `getrandom` (backed by `crypto.getRandomValues` in the browser
263
+ * and OS entropy on Node.js) for cryptographically secure randomness.
264
+ *
265
+ * ```js
266
+ * const seed = generate_user_seed();
267
+ * // e.g. "k7Qm2xW9aB"
268
+ * ```
269
+ */
270
+ export function generate_user_seed(): string;
271
+
272
+ /**
273
+ * Convert any Goldilocks field elements to a hex string.
274
+ *
275
+ * Each u64 is encoded as 8 little-endian bytes → 16 hex chars.
276
+ * For 4 elements: 64 hex chars (32 bytes).
277
+ *
278
+ * ```js
279
+ * const hex = goldilocks_fields_to_hex(BigUint64Array.from([1n, 2n, 3n, 4n]));
280
+ * ```
281
+ */
282
+ export function goldilocks_fields_to_hex(fields: BigUint64Array): string;
283
+
284
+ /**
285
+ * Returns the Goldilocks prime: p = 2^64 - 2^32 + 1.
286
+ */
287
+ export function goldilocks_modulus(): bigint;
288
+
289
+ /**
290
+ * Reduce an arbitrary u64 to its canonical representative mod p.
291
+ *
292
+ * Values already < p are returned unchanged. Values >= p are reduced.
293
+ * This uses `from_noncanonical_u64` internally (no panic on large values).
294
+ */
295
+ export function goldilocks_reduce(value: bigint): bigint;
296
+
297
+ /**
298
+ * Hash a raw 7-element balance leaf → 4-element Merkle node.
299
+ *
300
+ * Raw layout: `[balance_lo, balance_hi, seed_hash_0, seed_hash_1, seed_hash_2, credit_lo, credit_hi]`
301
+ *
302
+ * Identical to `hash_balance_leaf` in `prover/circuit/src/helpers/leaf_ops.rs`.
303
+ *
304
+ * **Input** : `BigUint64Array` of exactly 7 elements (each < `GOLDILOCKS_P`).
305
+ * **Output**: `BigUint64Array` of length 4 (one `HashOut`).
306
+ *
307
+ * ```js
308
+ * const raw = BigUint64Array.from([balLo, balHi, seed0, seed1, seed2, credLo, credHi]);
309
+ * const balanceHash = hash_balance_leaf(raw); // length 4
310
+ * ```
311
+ */
312
+ export function hash_balance_leaf(raw: BigUint64Array): BigUint64Array;
313
+
314
+ /**
315
+ * RTP × 100 for ALL valid Keno configs.
316
+ * Returns JS object: `{ "0_1": 9450, "0_2": 9712, ..., "2_10": 9580 }`
317
+ * Keys: `"{risk}_{pick_count}"`.
318
+ */
319
+ export function keno_all_rtp_x100(): any;
320
+
321
+ export function keno_draw_count(): number;
322
+
323
+ /**
324
+ * Whether a (risk, pick_count) pair is a valid Keno config.
325
+ */
326
+ export function keno_is_valid_config(risk: number, pick_count: number): boolean;
327
+
328
+ export function keno_max_picks(): number;
329
+
330
+ /**
331
+ * Returns the multiplier table (×10000) for the given Keno config.
332
+ * `risk`: 0=low, 1=medium, 2=high. `pick_count`: 1..10.
333
+ * Length = pick_count + 1. Returns empty vec for invalid combos.
334
+ */
335
+ export function keno_multiplier_table(risk: number, pick_count: number): BigUint64Array;
336
+
337
+ export function keno_numbers_range(): number;
338
+
339
+ /**
340
+ * RTP × 100 for a Keno config (e.g. 9800 = 98.00%). Returns 0 for invalid combos.
341
+ */
342
+ export function keno_rtp_x100(risk: number, pick_count: number): bigint;
343
+
344
+ /**
345
+ * Limbo RTP percent (98). Canonical source for backend/frontend.
346
+ */
347
+ export function limbo_rtp_percent(): number;
348
+
349
+ /**
350
+ * Build a main Merkle tree leaf from balance_hash, pk_hash, and address_hash.
351
+ *
352
+ * `main_leaf = Poseidon2(balance_hash[4] || pk_hash[0..2] || address_hash[0..2])`
353
+ *
354
+ * Uses truncated (128-bit) pk/address hashes to keep the preimage at 8 elements
355
+ * (single Poseidon2 permutation round). Identical to `make_main_leaf` in
356
+ * `prover/circuit/src/helpers/leaf_ops.rs`.
357
+ *
358
+ * All three inputs must be exactly 4 elements.
359
+ * **Output**: `BigUint64Array` of length 4 (the Merkle leaf hash).
360
+ *
361
+ * ```js
362
+ * const leaf = make_main_leaf(balanceHash, pkHash, addressHash);
363
+ * ```
364
+ */
365
+ export function make_main_leaf(balance_hash: BigUint64Array, pk_hash: BigUint64Array, address_hash: BigUint64Array): BigUint64Array;
366
+
367
+ /**
368
+ * RTP × 100 for ALL valid Plinko configs.
369
+ * Returns JS object: `{ "0_8_normal": 9799, "1_12_extreme": 9881, ... }`
370
+ */
371
+ export function plinko_all_rtp_x100(): any;
372
+
373
+ /**
374
+ * Whether a (sector, rows, is_extreme) triple is a valid Plinko config.
375
+ */
376
+ export function plinko_is_valid_config(sector: number, rows: number, is_extreme: boolean): boolean;
377
+
378
+ /**
379
+ * Whether rows is within the valid Plinko range [8, 16].
380
+ */
381
+ export function plinko_is_valid_rows(rows: number): boolean;
382
+
383
+ export function plinko_max_rows(): number;
384
+
385
+ export function plinko_min_rows(): number;
386
+
387
+ /**
388
+ * Returns the multiplier table (×10000) for the given Plinko config.
389
+ * Length = rows + 1. Returns empty vec for invalid combos.
390
+ */
391
+ export function plinko_multiplier_table(sector: number, rows: number, is_extreme: boolean): BigUint64Array;
392
+
393
+ export function plinko_num_sectors(): number;
394
+
395
+ /**
396
+ * RTP × 100 for a Plinko config (e.g. 9799 = 97.99%). Returns 0 for invalid combos.
397
+ */
398
+ export function plinko_rtp_x100(sector: number, rows: number, is_extreme: boolean): bigint;
399
+
400
+ /**
401
+ * Poseidon2 hash of an arbitrary number of Goldilocks field elements.
402
+ *
403
+ * Mirrors `builder.hash_n_to_hash_no_pad::<Poseidon2Hash>(...)` inside
404
+ * the circuit and `Poseidon2Hash::hash_no_pad` in `src/block_builder`.
405
+ *
406
+ * **Input** : `BigUint64Array` — each element must be < `GOLDILOCKS_P`.
407
+ * **Output**: `BigUint64Array` of length 4 (one `HashOut`).
408
+ *
409
+ * ```js
410
+ * const h = poseidon2_hash(BigUint64Array.from([1n, 2n, 3n]));
411
+ * // h.length === 4
412
+ * ```
413
+ */
414
+ export function poseidon2_hash(input: BigUint64Array): BigUint64Array;
415
+
416
+ /**
417
+ * Merkle-tree hash: Poseidon2(left[4] ‖ right[4]).
418
+ *
419
+ * Identical to `poseidon_hash(left, right)` in `src/merkletree/hash.rs`.
420
+ * Input ordering is critical — `left` concatenated before `right`.
421
+ *
422
+ * Both arrays **must** have exactly 4 elements (one `HashOut` each).
423
+ */
424
+ export function poseidon2_two_to_one(left: BigUint64Array, right: BigUint64Array): BigUint64Array;
425
+
426
+ /**
427
+ * Truncated seed hash — first 3 elements of `Poseidon2(server_seed)`.
428
+ *
429
+ * 192 bits of commitment → ~96-bit collision resistance, which closes the
430
+ * multi-preimage grinding vector that an earlier 128-bit truncation left open.
431
+ * This is the exact format stored in the Merkle-tree leaf and verified
432
+ * by the circuit. Matches `seed_hash_truncated` in
433
+ * `src/block_builder/builder.rs` and `src/circuit/slot/fairness.rs`.
434
+ *
435
+ * Returns `BigUint64Array` of length 3: `[h[0], h[1], h[2]]`.
436
+ */
437
+ export function seed_hash_truncated(server_seed: BigUint64Array): BigUint64Array;
438
+
439
+ /**
440
+ * Compute the public key for a session: `pk_hash = Poseidon2(session_key[4], expiry)`.
441
+ *
442
+ * The public key hash is stored in the user-asset Merkle leaf and verified
443
+ * inside the circuit (the prover must know the preimage `session_key` + `expiry`).
444
+ *
445
+ * `session_key` must be exactly 4 elements (output of `derive_session_key`).
446
+ * `session_expiry` is the Unix timestamp after which the session is invalid.
447
+ */
448
+ export function session_public_key(session_key: BigUint64Array, session_expiry: bigint): BigUint64Array;
449
+
450
+ /**
451
+ * Convert a user seed string to 4 Goldilocks field elements.
452
+ *
453
+ * `SHA-256(str)` → split into 4 × 8 LE bytes → reduce each mod p.
454
+ *
455
+ * This matches the backend's `stringToUserSeed` and produces the exact
456
+ * field elements used in the provably-fair random computation:
457
+ * `random = Poseidon2(server_seed ‖ user_seed)`
458
+ *
459
+ * ```js
460
+ * const fields = string_to_user_seed("my-seed-123");
461
+ * // fields.length === 4, each < GOLDILOCKS_P
462
+ * ```
463
+ */
464
+ export function string_to_user_seed(input: string): BigUint64Array;
465
+
466
+ /**
467
+ * Convert a user seed string directly to a hex representation.
468
+ *
469
+ * Equivalent to `goldiLocksFieldsToHex(stringToUserSeed(str))`.
470
+ * Returns a 64-character lowercase hex string (32 bytes).
471
+ *
472
+ * ```js
473
+ * const hex = string_to_user_seed_hex("my-seed-123");
474
+ * // hex === "a1b2c3..." (64 chars)
475
+ * ```
476
+ */
477
+ export function string_to_user_seed_hex(input: string): string;
478
+
479
+ /**
480
+ * Re-check every per-slot circuit constraint on a candidate witness, returning
481
+ * the post-tx effects on success or a typed rejection reason on failure.
482
+ *
483
+ * Input: a JS object matching `tx_validator::SlotInput` (serde-compatible).
484
+ * Output on success: `{ ok: true, effects: SlotEffects }`.
485
+ * Output on failure: `{ ok: false, reason: string }`.
486
+ */
487
+ export function validate_slot(input: any): any;