@rolly-dev/wasm-signer 0.9.1 → 0.9.5

package/dist/node-inline/README.md

@@ -0,0 +1,115 @@
+# @rolly-dev/wasm-signer
+
+Client-side Poseidon2 hashing and bet authentication for the Rolly ZK-Rollup casino.
+
+Built with Rust → WebAssembly (via `wasm-pack`), using the same Poseidon2 hasher
+and Goldilocks field as the plonky2 proving circuit.
+
+## Build
+
+```bash
+# requires: cargo, wasm-pack
+npm run build
+# → dist/node/  (Node.js, CJS, sync init)
+# → dist/web/   (Browser, ESM, async init)
+```
+
+## Usage
+
+### Node.js (CommonJS)
+
+```javascript
+const {
+  poseidon2_hash,
+  derive_session_key,
+  session_public_key,
+  create_bet_auth,
+} = require('@rolly-dev/wasm-signer');
+
+const hash = poseidon2_hash(BigUint64Array.from([1n, 2n, 3n]));
+// → BigUint64Array(4)
+```
+
+### Node.js (ESM)
+
+```javascript
+import {
+  poseidon2_hash,
+  derive_session_key,
+  create_bet_auth,
+} from '@rolly-dev/wasm-signer';
+
+const hash = poseidon2_hash(BigUint64Array.from([1n, 2n, 3n]));
+```
+
+### React
+
+```jsx
+import { useRollyWasm } from '@rolly-dev/wasm-signer/react';
+
+function BetButton({ sessionKey, amount, nonce }) {
+  const { ready, create_bet_auth } = useRollyWasm();
+
+  if (!ready) return <span>Loading...</span>;
+
+  const handleBet = () => {
+    const auth = create_bet_auth(sessionKey, BigInt(amount), BigInt(nonce));
+    // send auth to server...
+  };
+
+  return <button onClick={handleBet}>Place Bet</button>;
+}
+```
+
+### Browser (vanilla ESM)
+
+```html
+<script type="module">
+  import { init, poseidon2_hash } from '@rolly-dev/wasm-signer';
+
+  await init();  // loads .wasm, must be called once
+  const h = poseidon2_hash(BigUint64Array.from([1n, 2n]));
+</script>
+```
+
+### Manual init (advanced)
+
+```javascript
+import init, { poseidon2_hash } from '@rolly-dev/wasm-signer/init';
+
+// custom wasm URL or ArrayBuffer
+await init('/assets/rolly_wasm_signer_bg.wasm');
+poseidon2_hash(BigUint64Array.from([1n]));
+```
+
+## API
+
+| Function                   | Input                          | Output            | Description                                    |
+|----------------------------|--------------------------------|-------------------|------------------------------------------------|
+| `poseidon2_hash`           | `BigUint64Array`               | `BigUint64Array(4)` | Hash N field elements                        |
+| `poseidon2_two_to_one`     | `BigUint64Array(4)` × 2        | `BigUint64Array(4)` | Merkle hash: H(left‖right)                   |
+| `derive_session_key`       | `Uint8Array(32)`               | `BigUint64Array(4)` | MetaMask sig → session key                   |
+| `session_public_key`       | `BigUint64Array(4)`            | `BigUint64Array(4)` | session_pk = H(session_key)                  |
+| `create_bet_auth`          | `(BigUint64Array(4), bigint, bigint)` | `BigUint64Array(4)` | MAC = H(sk‖amount_lo‖amount_hi‖nonce)  |
+| `compute_server_seed_hash` | `BigUint64Array(8)`            | `BigUint64Array(4)` | Full hash of server seed                     |
+| `seed_hash_truncated`      | `BigUint64Array(8)`            | `BigUint64Array(2)` | First 2 elements (circuit leaf format)       |
+| `goldilocks_modulus`       | —                              | `bigint`          | Returns p = 2^64 - 2^32 + 1                   |
+| `goldilocks_reduce`        | `bigint`                       | `bigint`          | Reduce mod p                                   |
+
+## Bundler notes
+
+**Vite** — add to `optimizeDeps.exclude`:
+```js
+optimizeDeps: { exclude: ['@rolly-dev/wasm-signer'] }
+```
+
+**Webpack 5** — enable WASM experiments:
+```js
+module.exports = { experiments: { asyncWebAssembly: true } };
+```
+
+**Next.js** — conditional exports auto-resolve: Node.js entry on server, browser entry on client.
+
+## License
+
+MIT

package/dist/node-inline/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/node-inline/rolly_wasm_signer.d.ts

@@ -0,0 +1,302 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * Split a u64 amount into (lo, hi) u32 pair matching the circuit representation.
+ *
+ * Returns `[amount_lo, amount_hi]` as a `Uint32Array` of length 2.
+ *
+ * ```js
+ * const [lo, hi] = amount_split(123456789n);
+ * ```
+ */
+export function amount_split(amount: bigint): Uint32Array;
+
+/**
+ * Compute address_hash = Poseidon2(addr_byte_0, ..., addr_byte_19).
+ * Takes a hex address string (with or without 0x prefix), returns [u64; 4].
+ */
+export function compute_address_hash(address_hex: string): BigUint64Array;
+
+/**
+ * Full Poseidon2 hash of an 8-element server seed.
+ *
+ * Returns all 4 hash elements.  Note: the circuit stores only the
+ * **first 2 elements** as the leaf commitment (see `seed_hash_truncated`).
+ * This full variant is useful for client-side verification where all
+ * 4 elements may be needed.
+ *
+ * `server_seed` must be exactly 8 elements.
+ */
+export function compute_server_seed_hash(server_seed: BigUint64Array): BigUint64Array;
+
+/**
+ * Compute the transaction message hash (for debugging / verification).
+ *
+ * Returns `BigUint64Array` of length 4 — the same hash the circuit computes.
+ *
+ * ```js
+ * const hash = compute_tx_msg_hash(5, userId, 0, amountLo, amountHi);
+ * ```
+ */
+export function compute_tx_msg_hash(tx_type: number, user_id: number, currency_id: number, amount_lo: number, amount_hi: number, session_expiry: bigint): BigUint64Array;
+
+/**
+ * Create a `bet_auth` MAC that proves the user authorized this specific bet.
+ *
+ * ```text
+ * bet_auth = Poseidon2(
+ *     session_key[0..4],   // 4 field elements (private)
+ *     amount_lo,           // lower  32 bits of bet_amount
+ *     amount_hi,           // upper  32 bits of bet_amount
+ *     nonce,               // monotonic counter, prevents replay
+ * )
+ * ```
+ *
+ * The circuit verifies two things:
+ *   1. `session_pk == Poseidon2(session_key)` — knowledge of key
+ *   2. `bet_auth  == Poseidon2(session_key ‖ amount_lo ‖ amount_hi ‖ nonce)`
+ *
+ * The lo/hi split matches `src/circuit/main_circuit.rs` witness assignment:
+ *   `amount as u32` / `(amount >> 32) as u32`, both via `from_canonical_u32`.
+ *
+ * **Parameters**
+ * - `session_key` : 4 × u64  (private, from `derive_session_key`)
+ * - `bet_amount`  : u64      (in smallest currency units)
+ * - `nonce`       : u64      (incrementing per-session counter)
+ *
+ * **Returns**: 4 × u64 (`bet_auth` hash)
+ */
+export function create_bet_auth(session_key: BigUint64Array, bet_amount: bigint, nonce: bigint): BigUint64Array;
+
+/**
+ * Derive a session key from 32 bytes of entropy (e.g. MetaMask signature).
+ *
+ * **Algorithm**: split 32 bytes into 4 × 8 bytes, interpret each chunk as
+ * little-endian u64, reduce mod p, then hash:
+ *   `session_key = Poseidon2(reduced_chunks)`
+ *
+ * The reduction via `from_noncanonical_u64` is necessary because raw
+ * signature bytes can produce values >= p.
+ *
+ * ```js
+ * const sig = ethers.getBytes(metaMaskSignature).slice(0, 32);
+ * const sk  = derive_session_key(new Uint8Array(sig));
+ * // sk.length === 4
+ * ```
+ */
+export function derive_session_key(sig_bytes: Uint8Array): BigUint64Array;
+
+/**
+ * Generate a random user seed — 10 alphanumeric characters.
+ *
+ * Uses `getrandom` (backed by `crypto.getRandomValues` in the browser
+ * and OS entropy on Node.js) for cryptographically secure randomness.
+ *
+ * ```js
+ * const seed = generate_user_seed();
+ * // e.g. "k7Qm2xW9aB"
+ * ```
+ */
+export function generate_user_seed(): string;
+
+/**
+ * Convert any Goldilocks field elements to a hex string.
+ *
+ * Each u64 is encoded as 8 little-endian bytes → 16 hex chars.
+ * For 4 elements: 64 hex chars (32 bytes).
+ *
+ * ```js
+ * const hex = goldilocks_fields_to_hex(BigUint64Array.from([1n, 2n, 3n, 4n]));
+ * ```
+ */
+export function goldilocks_fields_to_hex(fields: BigUint64Array): string;
+
+/**
+ * Returns the Goldilocks prime: p = 2^64 - 2^32 + 1.
+ */
+export function goldilocks_modulus(): bigint;
+
+/**
+ * Reduce an arbitrary u64 to its canonical representative mod p.
+ *
+ * Values already < p are returned unchanged.  Values >= p are reduced.
+ * This uses `from_noncanonical_u64` internally (no panic on large values).
+ */
+export function goldilocks_reduce(value: bigint): bigint;
+
+/**
+ * Poseidon2 hash of an arbitrary number of Goldilocks field elements.
+ *
+ * Mirrors `builder.hash_n_to_hash_no_pad::<Poseidon2Hash>(...)` inside
+ * the circuit and `Poseidon2Hash::hash_no_pad` in `src/block_builder`.
+ *
+ * **Input** : `BigUint64Array` — each element must be < `GOLDILOCKS_P`.
+ * **Output**: `BigUint64Array` of length 4 (one `HashOut`).
+ *
+ * ```js
+ * const h = poseidon2_hash(BigUint64Array.from([1n, 2n, 3n]));
+ * // h.length === 4
+ * ```
+ */
+export function poseidon2_hash(input: BigUint64Array): BigUint64Array;
+
+/**
+ * Merkle-tree hash: Poseidon2(left[4] ‖ right[4]).
+ *
+ * Identical to `poseidon_hash(left, right)` in `src/merkletree/hash.rs`.
+ * Input ordering is critical — `left` concatenated before `right`.
+ *
+ * Both arrays **must** have exactly 4 elements (one `HashOut` each).
+ */
+export function poseidon2_two_to_one(left: BigUint64Array, right: BigUint64Array): BigUint64Array;
+
+/**
+ * Derive a Schnorr secret key from entropy bytes (e.g. MetaMask signature).
+ *
+ * Takes at least 32 bytes, uses `Scalar::decode_reduce` to map them into
+ * the ECgFp5 scalar field. Returns hex-encoded secret key (80 chars = 40 bytes).
+ *
+ * ```js
+ * const skHex = schnorr_keygen(sigBytes.slice(0, 32));
+ * ```
+ */
+export function schnorr_keygen(entropy: Uint8Array): string;
+
+/**
+ * Get the w-encoding of a public key as 5 Goldilocks field elements (for circuit witness).
+ *
+ * Returns `BigUint64Array` of length 5.
+ *
+ * ```js
+ * const encode = schnorr_pk_encode(pkHex);
+ * // encode.length === 5
+ * ```
+ */
+export function schnorr_pk_encode(pk_hex: string): BigUint64Array;
+
+/**
+ * Compute pk_hash = Poseidon2(w_encoding[5]) from a hex-encoded public key.
+ *
+ * The w-encoding is the 40-byte (80 hex) representation returned by `schnorr_pubkey`.
+ * pk_hash is stored in the Merkle tree to bind the Schnorr key to an account.
+ *
+ * Returns `BigUint64Array` of length 4.
+ *
+ * ```js
+ * const pkHash = schnorr_pk_hash(pkHex);
+ * ```
+ */
+export function schnorr_pk_hash(pk_hex: string): BigUint64Array;
+
+/**
+ * Compute pk_hash as a hex string (for convenience).
+ *
+ * ```js
+ * const pkHashHex = schnorr_pk_hash_hex(pkHex);
+ * ```
+ */
+export function schnorr_pk_hash_hex(pk_hex: string): string;
+
+/**
+ * Compute the Schnorr public key from a hex-encoded secret key.
+ *
+ * Returns hex-encoded w-encoding of the ECgFp5 point (80 chars = 40 bytes).
+ *
+ * ```js
+ * const pkHex = schnorr_pubkey(skHex);
+ * ```
+ */
+export function schnorr_pubkey(sk_hex: string): string;
+
+/**
+ * Sign a ChangePubKey (tx_type=9) transaction in (s, e) format.
+ *
+ * msg_hash = Poseidon2(9, user_id, new_pk_hash[0..4])
+ *
+ * The old key signs this message to authorize key rotation.
+ *
+ * Returns a JS object: `{ pubkey: "hex", sig_s: "hex", sig_e: "hex" }`
+ *
+ * ```js
+ * const sig = schnorr_sign_cpk(oldSkHex, userId, newPkHashArray);
+ * ```
+ */
+export function schnorr_sign_cpk(old_sk_hex: string, user_id: number, new_pk_hash: BigUint64Array): any;
+
+/**
+ * Sign a transaction with Schnorr (ECgFp5) in (s, e) format.
+ *
+ * msg_hash = Poseidon2(tx_type, user_id, currency_id, amount_lo, amount_hi)
+ *
+ * Returns a JS object: `{ pubkey: "hex", sig_s: "hex", sig_e: "hex" }`
+ *
+ * ```js
+ * const sig = schnorr_sign_tx(skHex, 5, userId, 0, amountLo, amountHi);
+ * // sig.pubkey (80 hex), sig.sig_s (80 hex), sig.sig_e (80 hex)
+ * ```
+ */
+export function schnorr_sign_tx(sk_hex: string, tx_type: number, user_id: number, currency_id: number, amount_lo: number, amount_hi: number, session_expiry: bigint): any;
+
+/**
+ * Verify a Schnorr signature (s, e) for a transaction.
+ *
+ * Algorithm: R_v = s·G + e·pk, e_v = H(R_v‖pk‖msg), check e == e_v.
+ *
+ * Returns `true` if signature is valid, `false` otherwise.
+ *
+ * ```js
+ * const ok = schnorr_verify_tx(pubkeyHex, sigSHex, sigEHex, 5, userId, 0, amountLo, amountHi);
+ * ```
+ */
+export function schnorr_verify_tx(pk_hex: string, sig_s_hex: string, sig_e_hex: string, tx_type: number, user_id: number, currency_id: number, amount_lo: number, amount_hi: number, session_expiry: bigint): boolean;
+
+/**
+ * Truncated seed hash — first 2 elements of `Poseidon2(server_seed)`.
+ *
+ * This is the exact format stored in the Merkle-tree leaf and verified
+ * by the circuit.  Matches `seed_hash_truncated` in
+ * `src/block_builder/builder.rs` and `src/circuit/main_circuit.rs`.
+ *
+ * Returns `BigUint64Array` of length 2: `[h[0], h[1]]`.
+ */
+export function seed_hash_truncated(server_seed: BigUint64Array): BigUint64Array;
+
+/**
+ * Compute the public key for a session: `session_pk = Poseidon2(session_key)`.
+ *
+ * The public key is stored in the user-asset Merkle leaf and verified
+ * inside the circuit (the prover must know the preimage `session_key`).
+ *
+ * `session_key` must be exactly 4 elements (output of `derive_session_key`).
+ */
+export function session_public_key(session_key: BigUint64Array): BigUint64Array;
+
+/**
+ * Convert a user seed string to 4 Goldilocks field elements.
+ *
+ * `SHA-256(str)` → split into 4 × 8 LE bytes → reduce each mod p.
+ *
+ * This matches the backend's `stringToUserSeed` and produces the exact
+ * field elements used in the provably-fair random computation:
+ *   `random = Poseidon2(server_seed ‖ user_seed)`
+ *
+ * ```js
+ * const fields = string_to_user_seed("my-seed-123");
+ * // fields.length === 4, each < GOLDILOCKS_P
+ * ```
+ */
+export function string_to_user_seed(input: string): BigUint64Array;
+
+/**
+ * Convert a user seed string directly to a hex representation.
+ *
+ * Equivalent to `goldiLocksFieldsToHex(stringToUserSeed(str))`.
+ * Returns a 64-character lowercase hex string (32 bytes).
+ *
+ * ```js
+ * const hex = string_to_user_seed_hex("my-seed-123");
+ * // hex === "a1b2c3..." (64 chars)
+ * ```
+ */
+export function string_to_user_seed_hex(input: string): string;