deterministic-dice 1.0.0

package/README.md

@@ -0,0 +1,34 @@
+# deterministic-dice
+
+Deterministic random number generator seeded by a bytes32 hash.
+
+## Install
+
+```bash
+npm install deterministic-dice
+```
+
+## Usage
+
+```typescript
+import { DeterministicDice } from "deterministic-dice";
+
+const dice = new DeterministicDice(
+  "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
+);
+
+dice.roll(15); // 0-15
+dice.roll(6); // 0-6
+dice.roll(100); // 0-100
+```
+
+## How It Works
+
+1. Initialize with a bytes32 hash (with or without `0x` prefix)
+2. Call `roll(max)` to get a random number from 0 to max (inclusive)
+3. Entropy is automatically rehashed with SHA256 when exhausted
+4. Same hash always produces the same sequence of rolls
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Deterministic random number generator seeded by a bytes32 hash.
+ */
+export declare class DeterministicDice {
+    private entropy;
+    private position;
+    constructor(randomHash: string);
+    /**
+     * Roll a random number from 0 to max (inclusive).
+     */
+    roll(max: number): number;
+    private consumeHex;
+}
+export default DeterministicDice;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAS;gBAEb,UAAU,EAAE,MAAM;IAO9B;;OAEG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAezB,OAAO,CAAC,UAAU;CAYnB;AAED,eAAe,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,41 @@
+import { sha256 } from "@noble/hashes/sha256";
+import { bytesToHex } from "@noble/hashes/utils";
+/**
+ * Deterministic random number generator seeded by a bytes32 hash.
+ */
+export class DeterministicDice {
+    constructor(randomHash) {
+        this.entropy = randomHash.startsWith("0x")
+            ? randomHash.slice(2)
+            : randomHash;
+        this.position = 0;
+    }
+    /**
+     * Roll a random number from 0 to max (inclusive).
+     */
+    roll(max) {
+        const range = max + 1;
+        const bitsNeeded = Math.ceil(Math.log2(range));
+        const hexCharsNeeded = Math.max(1, Math.ceil(bitsNeeded / 4));
+        const maxValue = Math.pow(16, hexCharsNeeded);
+        const threshold = maxValue - (maxValue % range);
+        let value;
+        do {
+            value = this.consumeHex(hexCharsNeeded);
+        } while (value >= threshold);
+        return value % range;
+    }
+    consumeHex(count) {
+        let result = 0;
+        for (let i = 0; i < count; i++) {
+            if (this.position >= this.entropy.length) {
+                this.entropy = bytesToHex(sha256(this.entropy));
+                this.position = 0;
+            }
+            result = (result << 4) + parseInt(this.entropy[this.position], 16);
+            this.position++;
+        }
+        return result;
+    }
+}
+export default DeterministicDice;

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "deterministic-dice",
+  "version": "1.0.0",
+  "description": "Deterministic random number generator seeded by a bytes32 hash",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "deterministic",
+    "random",
+    "dice",
+    "prng",
+    "ethereum",
+    "blockchain",
+    "hash",
+    "seed"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@noble/hashes": "^1.3.3"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.3"
+  }
+}
+