@safe-vanity-blockie/core 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 safe-vanity-blockie contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,49 @@
+# @safe-vanity-blockie/core
+
+Pure, isomorphic building blocks for mining a Safe `saltNonce` whose resulting address renders a
+chosen two-color face as a [`blo`](https://github.com/bpierre/blo) identicon.
+
+No Node built-ins and no DOM — it runs unchanged in Node, in a browser, and in a Web Worker. This
+package is the engine behind the [`safe-vanity-blockie`](https://www.npmjs.com/package/safe-vanity-blockie)
+CLI and the project's web app.
+
+> [!CAUTION]
+> A matching identicon is cosmetic and must never be trusted as proof of an address. Blockie
+> look-alikes are a known phishing vector. Always verify the full address, never the picture.
+
+## Install
+
+Requires Node.js >= 22.
+
+```
+npm install @safe-vanity-blockie/core
+```
+
+## What's in it
+
+| Area | Exports |
+| --- | --- |
+| Identicon | `bloData`, `bloDataInto`, `bloImage`, `bloSvg`, `randSeed`, `seedInto`, `randomColor`, `nextRandom` |
+| Address derivation | `createAddressDeriver`, `AddressDeriver`, `SafeConstants` |
+| Mining | `createMiner`, `Leaderboard`, `compareCandidates`, `Candidate`, `MineOptions`, `MineResult` |
+| Scoring | `makeScorer`, `compileFace`, `describeMatch`, `isTwoColor`, `colorContrast`, `apportion`, `hslToRgb` |
+| Result selection | `selectReported`, `filterCandidates`, `formatScore`, `scorePercent`, `SelectReportedResult` |
+| Templates | `TEMPLATES`, `getTemplate`, `parseFaceSpec`, `faceWithMouths`, `BASE_TARGET`, `BASE_WEIGHTS`, `MOUTHS`, `MOUTH_INDICES`, `MOUTH_BUDGET`, `MOUTH_BG_WEIGHT`, `MOUTH_STROKE_WEIGHT` |
+| Types | `FaceSpec`, `CompiledFace`, `FaceRegion`, `RegionAlternative`, `FixedCell`, `BloImage`, `Palette`, `Hsl` |
+| Primitives | `createKeccak256`, `Keccak256`, `bytesToHex`, `hexToBytes` |
+
+`bloDataInto` and `seedInto` write into a caller-supplied buffer, which is what makes a tight mining
+loop allocation-free.
+
+## Why a `blo` port
+
+The identicon has to be computed millions of times per run, from raw bytes, with no DOM. This
+package reimplements `blo`'s algorithm against that constraint while producing byte-identical output
+to the original for the same address.
+
+## Links
+
+- [Repository](https://github.com/tmjssz/safe-vanity-blockie)
+- [`safe-vanity-blockie`](https://www.npmjs.com/package/safe-vanity-blockie) — the CLI
+
+MIT

package/dist/address.d.ts

@@ -0,0 +1,26 @@
+import type { Keccak256 } from './keccak.js';
+/**
+ * The three values that are constant for a given (owners, threshold, safeVersion) and therefore
+ * precomputed once on the main thread. Only the saltNonce varies per iteration.
+ */
+export interface SafeConstants {
+    /** keccak256 of the ABI-encoded setup() calldata. 32 bytes. */
+    readonly initializerHash: Uint8Array;
+    /** SafeProxyFactory address. 20 bytes. */
+    readonly factory: Uint8Array;
+    /** keccak256(proxyCreationCode ++ abi.encode(address, singleton)). 32 bytes. */
+    readonly initCodeHash: Uint8Array;
+}
+export interface AddressDeriver {
+    /** Fast path for saltNonce < 2^53. Returns a lowercase 0x address. */
+    derive(saltNonce: number): string;
+    /** Full uint256 path, for verification and huge nonces. Returns a lowercase 0x address. */
+    deriveBig(saltNonce: bigint): string;
+}
+/**
+ * Builds a deriver whose buffers are allocated once. Each derive() is exactly two keccaks:
+ *   salt = keccak256(initializerHash ++ uint256(saltNonce))
+ *   address = keccak256(0xff ++ factory ++ salt ++ initCodeHash)[12..32)
+ */
+export declare function createAddressDeriver(constants: SafeConstants, keccak256: Keccak256): AddressDeriver;
+//# sourceMappingURL=address.d.ts.map

package/dist/address.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"address.d.ts","sourceRoot":"","sources":["../src/address.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAE5C;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,+DAA+D;IAC/D,QAAQ,CAAC,eAAe,EAAE,UAAU,CAAA;IACpC,0CAA0C;IAC1C,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAA;IAC5B,gFAAgF;IAChF,QAAQ,CAAC,YAAY,EAAE,UAAU,CAAA;CAClC;AAED,MAAM,WAAW,cAAc;IAC7B,sEAAsE;IACtE,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAA;IACjC,2FAA2F;IAC3F,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAA;CACrC;AAID;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,aAAa,EACxB,SAAS,EAAE,SAAS,GACnB,cAAc,CAuDhB"}

package/dist/address.js

@@ -0,0 +1,61 @@
+import { bytesToHex } from './hex.js';
+const MAX_UINT256 = (1n << 256n) - 1n;
+/**
+ * Builds a deriver whose buffers are allocated once. Each derive() is exactly two keccaks:
+ *   salt = keccak256(initializerHash ++ uint256(saltNonce))
+ *   address = keccak256(0xff ++ factory ++ salt ++ initCodeHash)[12..32)
+ */
+export function createAddressDeriver(constants, keccak256) {
+    const { initializerHash, factory, initCodeHash } = constants;
+    if (initializerHash.length !== 32) {
+        throw new Error(`initializerHash must be 32 bytes, got ${initializerHash.length}`);
+    }
+    if (factory.length !== 20)
+        throw new Error(`factory must be 20 bytes, got ${factory.length}`);
+    if (initCodeHash.length !== 32) {
+        throw new Error(`initCodeHash must be 32 bytes, got ${initCodeHash.length}`);
+    }
+    // Bytes 32..64 are the big-endian uint256 saltNonce. Bytes 32..56 stay zero for derive(),
+    // so the fast path only writes the low 8 bytes.
+    const saltPreimage = new Uint8Array(64);
+    saltPreimage.set(initializerHash, 0);
+    const saltView = new DataView(saltPreimage.buffer);
+    const create2Preimage = new Uint8Array(85);
+    create2Preimage[0] = 0xff;
+    create2Preimage.set(factory, 1);
+    create2Preimage.set(initCodeHash, 53);
+    function finish() {
+        const salt = keccak256(saltPreimage);
+        create2Preimage.set(salt, 21);
+        return bytesToHex(keccak256(create2Preimage), 12, 32);
+    }
+    return {
+        derive(saltNonce) {
+            if (!Number.isSafeInteger(saltNonce) || saltNonce < 0) {
+                throw new Error(`derive() needs a non-negative safe integer, got ${saltNonce}`);
+            }
+            const high = Math.floor(saltNonce / 4294967296);
+            saltView.setUint32(56, high);
+            saltView.setUint32(60, saltNonce - high * 4294967296);
+            return finish();
+        },
+        deriveBig(saltNonce) {
+            if (saltNonce < 0n || saltNonce > MAX_UINT256) {
+                throw new Error(`deriveBig() needs a uint256, got ${saltNonce}`);
+            }
+            let remaining = saltNonce;
+            for (let i = 63; i >= 32; i--) {
+                saltPreimage[i] = Number(remaining & 0xffn);
+                remaining >>= 8n;
+            }
+            try {
+                return finish();
+            }
+            finally {
+                // Restore the invariant derive() relies on: bytes 32..56 are zero.
+                saltPreimage.fill(0, 32, 56);
+            }
+        },
+    };
+}
+//# sourceMappingURL=address.js.map

package/dist/address.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"address.js","sourceRoot":"","sources":["../src/address.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAuBrC,MAAM,WAAW,GAAG,CAAC,EAAE,IAAI,IAAI,CAAC,GAAG,EAAE,CAAA;AAErC;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAClC,SAAwB,EACxB,SAAoB;IAEpB,MAAM,EAAE,eAAe,EAAE,OAAO,EAAE,YAAY,EAAE,GAAG,SAAS,CAAA;IAC5D,IAAI,eAAe,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CAAC,yCAAyC,eAAe,CAAC,MAAM,EAAE,CAAC,CAAA;IACpF,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,KAAK,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,iCAAiC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;IAC7F,IAAI,YAAY,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CAAC,sCAAsC,YAAY,CAAC,MAAM,EAAE,CAAC,CAAA;IAC9E,CAAC;IAED,0FAA0F;IAC1F,gDAAgD;IAChD,MAAM,YAAY,GAAG,IAAI,UAAU,CAAC,EAAE,CAAC,CAAA;IACvC,YAAY,CAAC,GAAG,CAAC,eAAe,EAAE,CAAC,CAAC,CAAA;IACpC,MAAM,QAAQ,GAAG,IAAI,QAAQ,CAAC,YAAY,CAAC,MAAM,CAAC,CAAA;IAElD,MAAM,eAAe,GAAG,IAAI,UAAU,CAAC,EAAE,CAAC,CAAA;IAC1C,eAAe,CAAC,CAAC,CAAC,GAAG,IAAI,CAAA;IACzB,eAAe,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAA;IAC/B,eAAe,CAAC,GAAG,CAAC,YAAY,EAAE,EAAE,CAAC,CAAA;IAErC,SAAS,MAAM;QACb,MAAM,IAAI,GAAG,SAAS,CAAC,YAAY,CAAC,CAAA;QACpC,eAAe,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAA;QAC7B,OAAO,UAAU,CAAC,SAAS,CAAC,eAAe,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAA;IACvD,CAAC;IAED,OAAO;QACL,MAAM,CAAC,SAAiB;YACtB,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,SAAS,CAAC,IAAI,SAAS,GAAG,CAAC,EAAE,CAAC;gBACtD,MAAM,IAAI,KAAK,CAAC,mDAAmD,SAAS,EAAE,CAAC,CAAA;YACjF,CAAC;YACD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,UAAU,CAAC,CAAA;YAC/C,QAAQ,CAAC,SAAS,CAAC,EAAE,EAAE,IAAI,CAAC,CAAA;YAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,EAAE,SAAS,GAAG,IAAI,GAAG,UAAU,CAAC,CAAA;YACrD,OAAO,MAAM,EAAE,CAAA;QACjB,CAAC;QAED,SAAS,CAAC,SAAiB;YACzB,IAAI,SAAS,GAAG,EAAE,IAAI,SAAS,GAAG,WAAW,EAAE,CAAC;gBAC9C,MAAM,IAAI,KAAK,CAAC,oCAAoC,SAAS,EAAE,CAAC,CAAA;YAClE,CAAC;YACD,IAAI,SAAS,GAAG,SAAS,CAAA;YACzB,KAAK,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC9B,YAAY,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,SAAS,GAAG,KAAK,CAAC,CAAA;gBAC3C,SAAS,KAAK,EAAE,CAAA;YAClB,CAAC;YACD,IAAI,CAAC;gBACH,OAAO,MAAM,EAAE,CAAA;YACjB,CAAC;oBAAS,CAAC;gBACT,mEAAmE;gBACnE,YAAY,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAA;YAC9B,CAAC;QACH,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/blo.d.ts

@@ -0,0 +1,15 @@
+import type { BloImage, Hsl } from './types.js';
+export declare function seedInto(seed: string, rseed: Uint32Array): void;
+export declare function randSeed(seed: string): Uint32Array;
+export declare function nextRandom(rseed: Uint32Array): number;
+export declare function randomColor(rseed: Uint32Array): Hsl;
+export declare function bloImage(address: string): BloImage;
+/**
+ * Hot-path grid generation. `lowercaseAddress` MUST already be lowercased and 0x-prefixed —
+ * the caller owns that so the loop never allocates a string. Writes 32 values into `data`
+ * and reuses `rseed` as scratch. Identical output to `bloImage(address).data`.
+ */
+export declare function bloDataInto(lowercaseAddress: string, data: Uint8Array, rseed: Uint32Array): void;
+export declare function bloData(address: string): Uint8Array;
+export declare function bloSvg(address: string, size?: number): string;
+//# sourceMappingURL=blo.d.ts.map

package/dist/blo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blo.d.ts","sourceRoot":"","sources":["../src/blo.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAW,MAAM,YAAY,CAAA;AAQxD,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI,CAS/D;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAIlD;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAOrD;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,WAAW,GAAG,GAAG,CAQnD;AAED,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,CASlD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,gBAAgB,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI,CAIhG;AAED,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,CAInD;AAED,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,SAAK,GAAG,MAAM,CA2BzD"}

package/dist/blo.js

@@ -0,0 +1,86 @@
+/** = 1 / 2147483648. Parenthesise as ((1 << 31) >>> 0); `1 << (31 >>> 0)` is negative. */
+const RANDOM_SCALE = 1 / ((1 << 31) >>> 0);
+/** Number of nextRandom() draws consumed by the three randomColor() calls before the grid. */
+const COLOR_DRAWS = 18;
+export function seedInto(seed, rseed) {
+    rseed[0] = 0;
+    rseed[1] = 0;
+    rseed[2] = 0;
+    rseed[3] = 0;
+    for (let i = 0; i < seed.length; i++) {
+        const slot = i & 3;
+        rseed[slot] = (rseed[slot] << 5) - rseed[slot] + seed.charCodeAt(i);
+    }
+}
+export function randSeed(seed) {
+    const rseed = new Uint32Array(4);
+    seedInto(seed, rseed);
+    return rseed;
+}
+export function nextRandom(rseed) {
+    const t = rseed[0] ^ (rseed[0] << 11);
+    rseed[0] = rseed[1];
+    rseed[1] = rseed[2];
+    rseed[2] = rseed[3];
+    rseed[3] = (rseed[3] ^ (rseed[3] >> 19) ^ t ^ (t >> 8)) >>> 0;
+    return rseed[3] * RANDOM_SCALE;
+}
+export function randomColor(rseed) {
+    return [
+        Math.floor(nextRandom(rseed) * 360),
+        Math.floor(40 + nextRandom(rseed) * 60),
+        Math.floor((nextRandom(rseed) + nextRandom(rseed) + nextRandom(rseed) + nextRandom(rseed)) * 25),
+    ];
+}
+export function bloImage(address) {
+    const rseed = randSeed(address.toLowerCase());
+    // blo assigns these to c, b, s in this order but returns them as [b, c, s].
+    const c = randomColor(rseed);
+    const b = randomColor(rseed);
+    const s = randomColor(rseed);
+    const data = new Uint8Array(32);
+    for (let i = 0; i < 32; i++)
+        data[i] = Math.floor(nextRandom(rseed) * 2.3);
+    return { data, colors: [b, c, s] };
+}
+/**
+ * Hot-path grid generation. `lowercaseAddress` MUST already be lowercased and 0x-prefixed —
+ * the caller owns that so the loop never allocates a string. Writes 32 values into `data`
+ * and reuses `rseed` as scratch. Identical output to `bloImage(address).data`.
+ */
+export function bloDataInto(lowercaseAddress, data, rseed) {
+    seedInto(lowercaseAddress, rseed);
+    for (let i = 0; i < COLOR_DRAWS; i++)
+        nextRandom(rseed);
+    for (let i = 0; i < 32; i++)
+        data[i] = Math.floor(nextRandom(rseed) * 2.3);
+}
+export function bloData(address) {
+    const data = new Uint8Array(32);
+    bloDataInto(address.toLowerCase(), data, new Uint32Array(4));
+    return data;
+}
+export function bloSvg(address, size = 64) {
+    const { data, colors: [b, c, s], } = bloImage(address);
+    const paths = ['', ''];
+    for (let i = 0; i < 32; i++) {
+        if (data[i] === 0)
+            continue;
+        const x = i & 3;
+        const y = i >> 2;
+        const square = ',' + y + 'h1v1h-1z';
+        paths[data[i] - 1] += 'M' + x + square + 'M' + (7 - x) + square;
+    }
+    const path = (color, d) => '<path fill="hsl(' + color[0] + ' ' + color[1] + '% ' + color[2] + '%)" d="' + d + '"/>';
+    return ('<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 8 8" shape-rendering="optimizeSpeed" ' +
+        'width="' +
+        size +
+        '" height="' +
+        size +
+        '">' +
+        path(b, 'M0,0H8V8H0z') +
+        path(c, paths[0]) +
+        path(s, paths[1]) +
+        '</svg>');
+}
+//# sourceMappingURL=blo.js.map

package/dist/blo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"blo.js","sourceRoot":"","sources":["../src/blo.ts"],"names":[],"mappings":"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"}

package/dist/hex.d.ts

@@ -0,0 +1,4 @@
+/** Lowercase 0x-prefixed hex for `bytes[start..end)`. */
+export declare function bytesToHex(bytes: Uint8Array, start?: number, end?: number): string;
+export declare function hexToBytes(hex: string): Uint8Array;
+//# sourceMappingURL=hex.d.ts.map

package/dist/hex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hex.d.ts","sourceRoot":"","sources":["../src/hex.ts"],"names":[],"mappings":"AAEA,yDAAyD;AACzD,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,SAAI,EAAE,GAAG,SAAe,GAAG,MAAM,CAInF;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAelD"}

package/dist/hex.js

@@ -0,0 +1,26 @@
+const HEX_BYTES = Array.from({ length: 256 }, (_, i) => i.toString(16).padStart(2, '0'));
+/** Lowercase 0x-prefixed hex for `bytes[start..end)`. */
+export function bytesToHex(bytes, start = 0, end = bytes.length) {
+    let out = '0x';
+    for (let i = start; i < end; i++)
+        out += HEX_BYTES[bytes[i]];
+    return out;
+}
+export function hexToBytes(hex) {
+    const body = hex.startsWith('0x') || hex.startsWith('0X') ? hex.slice(2) : hex;
+    if (body.length % 2 !== 0) {
+        throw new Error(`hexToBytes: odd-length hex string (${body.length} characters)`);
+    }
+    if (!/^[0-9a-fA-F]*$/.test(body)) {
+        throw new Error(`hexToBytes: invalid hex characters`);
+    }
+    const out = new Uint8Array(body.length / 2);
+    for (let i = 0; i < out.length; i++) {
+        const byte = Number.parseInt(body.slice(i * 2, i * 2 + 2), 16);
+        if (Number.isNaN(byte))
+            throw new Error(`hexToBytes: invalid hex at byte ${i}`);
+        out[i] = byte;
+    }
+    return out;
+}
+//# sourceMappingURL=hex.js.map

package/dist/hex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hex.js","sourceRoot":"","sources":["../src/hex.ts"],"names":[],"mappings":"AAAA,MAAM,SAAS,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAA;AAExF,yDAAyD;AACzD,MAAM,UAAU,UAAU,CAAC,KAAiB,EAAE,KAAK,GAAG,CAAC,EAAE,GAAG,GAAG,KAAK,CAAC,MAAM;IACzE,IAAI,GAAG,GAAG,IAAI,CAAA;IACd,KAAK,IAAI,CAAC,GAAG,KAAK,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE;QAAE,GAAG,IAAI,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;IAC5D,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,GAAW;IACpC,MAAM,IAAI,GAAG,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAA;IAC9E,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,sCAAsC,IAAI,CAAC,MAAM,cAAc,CAAC,CAAA;IAClF,CAAC;IACD,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAA;IACvD,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;IAC3C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACpC,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;QAC9D,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,EAAE,CAAC,CAAA;QAC/E,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAA;IACf,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { type AddressDeriver, createAddressDeriver, type SafeConstants } from './address.js';
+export { bloData, bloDataInto, bloImage, bloSvg, nextRandom, randomColor, randSeed, seedInto, } from './blo.js';
+export { bytesToHex, hexToBytes } from './hex.js';
+export { createKeccak256, type Keccak256 } from './keccak.js';
+export { type Candidate, compareCandidates, createMiner, Leaderboard, type MineOptions, type MineResult, } from './miner.js';
+export { apportion, colorContrast, compileFace, describeMatch, hslToRgb, isTwoColor, makeScorer, } from './scoring.js';
+export { filterCandidates, formatScore, type SelectReportedResult, scorePercent, selectReported, } from './select.js';
+export { BASE_TARGET, BASE_WEIGHTS, faceWithMouths, getTemplate, MOUTH_BG_WEIGHT, MOUTH_BUDGET, MOUTH_INDICES, MOUTH_STROKE_WEIGHT, MOUTHS, parseFaceSpec, TEMPLATES, } from './templates.js';
+export type { BloImage, CompiledFace, FaceRegion, FaceSpec, FixedCell, Hsl, Palette, RegionAlternative, } from './types.js';
+//# 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":"AAAA,OAAO,EAAE,KAAK,cAAc,EAAE,oBAAoB,EAAE,KAAK,aAAa,EAAE,MAAM,cAAc,CAAA;AAC5F,OAAO,EACL,OAAO,EACP,WAAW,EACX,QAAQ,EACR,MAAM,EACN,UAAU,EACV,WAAW,EACX,QAAQ,EACR,QAAQ,GACT,MAAM,UAAU,CAAA;AACjB,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AACjD,OAAO,EAAE,eAAe,EAAE,KAAK,SAAS,EAAE,MAAM,aAAa,CAAA;AAC7D,OAAO,EACL,KAAK,SAAS,EACd,iBAAiB,EACjB,WAAW,EACX,WAAW,EACX,KAAK,WAAW,EAChB,KAAK,UAAU,GAChB,MAAM,YAAY,CAAA;AACnB,OAAO,EACL,SAAS,EACT,aAAa,EACb,WAAW,EACX,aAAa,EACb,QAAQ,EACR,UAAU,EACV,UAAU,GACX,MAAM,cAAc,CAAA;AACrB,OAAO,EACL,gBAAgB,EAChB,WAAW,EACX,KAAK,oBAAoB,EACzB,YAAY,EACZ,cAAc,GACf,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,WAAW,EACX,YAAY,EACZ,cAAc,EACd,WAAW,EACX,eAAe,EACf,YAAY,EACZ,aAAa,EACb,mBAAmB,EACnB,MAAM,EACN,aAAa,EACb,SAAS,GACV,MAAM,gBAAgB,CAAA;AACvB,YAAY,EACV,QAAQ,EACR,YAAY,EACZ,UAAU,EACV,QAAQ,EACR,SAAS,EACT,GAAG,EACH,OAAO,EACP,iBAAiB,GAClB,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,9 @@
+export { createAddressDeriver } from './address.js';
+export { bloData, bloDataInto, bloImage, bloSvg, nextRandom, randomColor, randSeed, seedInto, } from './blo.js';
+export { bytesToHex, hexToBytes } from './hex.js';
+export { createKeccak256 } from './keccak.js';
+export { compareCandidates, createMiner, Leaderboard, } from './miner.js';
+export { apportion, colorContrast, compileFace, describeMatch, hslToRgb, isTwoColor, makeScorer, } from './scoring.js';
+export { filterCandidates, formatScore, scorePercent, selectReported, } from './select.js';
+export { BASE_TARGET, BASE_WEIGHTS, faceWithMouths, getTemplate, MOUTH_BG_WEIGHT, MOUTH_BUDGET, MOUTH_INDICES, MOUTH_STROKE_WEIGHT, MOUTHS, parseFaceSpec, TEMPLATES, } from './templates.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,oBAAoB,EAAsB,MAAM,cAAc,CAAA;AAC5F,OAAO,EACL,OAAO,EACP,WAAW,EACX,QAAQ,EACR,MAAM,EACN,UAAU,EACV,WAAW,EACX,QAAQ,EACR,QAAQ,GACT,MAAM,UAAU,CAAA;AACjB,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AACjD,OAAO,EAAE,eAAe,EAAkB,MAAM,aAAa,CAAA;AAC7D,OAAO,EAEL,iBAAiB,EACjB,WAAW,EACX,WAAW,GAGZ,MAAM,YAAY,CAAA;AACnB,OAAO,EACL,SAAS,EACT,aAAa,EACb,WAAW,EACX,aAAa,EACb,QAAQ,EACR,UAAU,EACV,UAAU,GACX,MAAM,cAAc,CAAA;AACrB,OAAO,EACL,gBAAgB,EAChB,WAAW,EAEX,YAAY,EACZ,cAAc,GACf,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,WAAW,EACX,YAAY,EACZ,cAAc,EACd,WAAW,EACX,eAAe,EACf,YAAY,EACZ,aAAa,EACb,mBAAmB,EACnB,MAAM,EACN,aAAa,EACb,SAAS,GACV,MAAM,gBAAgB,CAAA"}

package/dist/keccak.d.ts

@@ -0,0 +1,8 @@
+export type Keccak256 = (input: Uint8Array) => Uint8Array;
+/**
+ * Creates a keccak-256 function backed by WebAssembly. Real WASM, so the identical module works
+ * in Node worker_threads and browser Web Workers. Call once per worker at startup — instantiation
+ * is the expensive part, hashing afterwards is not.
+ */
+export declare function createKeccak256(): Promise<Keccak256>;
+//# sourceMappingURL=keccak.d.ts.map

package/dist/keccak.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keccak.d.ts","sourceRoot":"","sources":["../src/keccak.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,UAAU,KAAK,UAAU,CAAA;AAEzD;;;;GAIG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,SAAS,CAAC,CAO1D"}

package/dist/keccak.js

@@ -0,0 +1,15 @@
+import { createKeccak } from 'hash-wasm';
+/**
+ * Creates a keccak-256 function backed by WebAssembly. Real WASM, so the identical module works
+ * in Node worker_threads and browser Web Workers. Call once per worker at startup — instantiation
+ * is the expensive part, hashing afterwards is not.
+ */
+export async function createKeccak256() {
+    const hasher = await createKeccak(256);
+    return (input) => {
+        hasher.init();
+        hasher.update(input);
+        return hasher.digest('binary');
+    };
+}
+//# sourceMappingURL=keccak.js.map

package/dist/keccak.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keccak.js","sourceRoot":"","sources":["../src/keccak.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAIxC;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe;IACnC,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,GAAG,CAAC,CAAA;IACtC,OAAO,CAAC,KAAiB,EAAc,EAAE;QACvC,MAAM,CAAC,IAAI,EAAE,CAAA;QACb,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QACpB,OAAO,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;IAChC,CAAC,CAAA;AACH,CAAC"}

package/dist/miner.d.ts

@@ -0,0 +1,45 @@
+import { type SafeConstants } from './address.js';
+import type { Keccak256 } from './keccak.js';
+import type { CompiledFace } from './types.js';
+export interface Candidate {
+    /** Decimal string: a saltNonce is a uint256 and may exceed 2^53. */
+    saltNonce: string;
+    address: string;
+    score: number;
+    maxScore: number;
+    twoColor: boolean;
+    contrast: number;
+    /** Winning alternative per region, e.g. `{ mouth: 'smile' }`. */
+    regions: Record<string, string>;
+}
+/** Ranking from spec §5.6: score desc, two-colour first, contrast desc, then saltNonce for stability. */
+export declare function compareCandidates(a: Candidate, b: Candidate): number;
+export declare class Leaderboard {
+    readonly capacity: number;
+    private items;
+    private seen;
+    constructor(capacity: number);
+    /** Score a candidate must reach to be worth building. -1 until the board is full. */
+    get threshold(): number;
+    offer(candidate: Candidate): boolean;
+    merge(candidates: Candidate[]): void;
+    entries(): Candidate[];
+}
+export interface MineOptions {
+    start: number;
+    count: number;
+    /** Leaderboard size. Default 20. */
+    keep?: number;
+    /** Iterations between onProgress callbacks. Default 250_000. */
+    chunkSize?: number;
+    /** Return false to stop early. `scanned` is cumulative for this call. */
+    onProgress?: (scanned: number, best: Candidate[]) => boolean | void;
+}
+export interface MineResult {
+    scanned: number;
+    candidates: Candidate[];
+}
+export declare function createMiner(constants: SafeConstants, face: CompiledFace, keccak256: Keccak256): {
+    mine(options: MineOptions): MineResult;
+};
+//# sourceMappingURL=miner.d.ts.map

package/dist/miner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"miner.d.ts","sourceRoot":"","sources":["../src/miner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,cAAc,CAAA;AAEvE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAE5C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9C,MAAM,WAAW,SAAS;IACxB,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,OAAO,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAChC;AAED,yGAAyG;AACzG,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,GAAG,MAAM,CAMpE;AAED,qBAAa,WAAW;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,OAAO,CAAC,KAAK,CAAkB;IAC/B,OAAO,CAAC,IAAI,CAAoB;gBAEpB,QAAQ,EAAE,MAAM;IAO5B,qFAAqF;IACrF,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,KAAK,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO;IAWpC,KAAK,CAAC,UAAU,EAAE,SAAS,EAAE,GAAG,IAAI;IAIpC,OAAO,IAAI,SAAS,EAAE;CAGvB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,oCAAoC;IACpC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,yEAAyE;IAEzE,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,OAAO,GAAG,IAAI,CAAA;CACpE;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,SAAS,EAAE,CAAA;CACxB;AAED,wBAAgB,WAAW,CACzB,SAAS,EAAE,aAAa,EACxB,IAAI,EAAE,YAAY,EAClB,SAAS,EAAE,SAAS,GACnB;IAAE,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,UAAU,CAAA;CAAE,CA+C5C"}

package/dist/miner.js

@@ -0,0 +1,97 @@
+import { createAddressDeriver } from './address.js';
+import { bloDataInto, bloImage } from './blo.js';
+import { colorContrast, describeMatch, isTwoColor, makeScorer } from './scoring.js';
+/** Ranking from spec §5.6: score desc, two-colour first, contrast desc, then saltNonce for stability. */
+export function compareCandidates(a, b) {
+    if (a.score !== b.score)
+        return b.score - a.score;
+    if (a.twoColor !== b.twoColor)
+        return a.twoColor ? -1 : 1;
+    if (a.contrast !== b.contrast)
+        return b.contrast - a.contrast;
+    if (a.saltNonce === b.saltNonce)
+        return 0;
+    return a.saltNonce.length - b.saltNonce.length || (a.saltNonce < b.saltNonce ? -1 : 1);
+}
+export class Leaderboard {
+    capacity;
+    items = [];
+    seen = new Set();
+    constructor(capacity) {
+        if (!Number.isInteger(capacity) || capacity < 1) {
+            throw new Error(`Leaderboard capacity must be a positive integer, got ${capacity}`);
+        }
+        this.capacity = capacity;
+    }
+    /** Score a candidate must reach to be worth building. -1 until the board is full. */
+    get threshold() {
+        return this.items.length < this.capacity ? -1 : this.items[this.items.length - 1].score;
+    }
+    offer(candidate) {
+        if (this.seen.has(candidate.address))
+            return false;
+        if (this.items.length >= this.capacity && candidate.score < this.threshold)
+            return false;
+        this.seen.add(candidate.address);
+        this.items.push(candidate);
+        this.items.sort(compareCandidates);
+        if (this.items.length > this.capacity)
+            this.items.length = this.capacity;
+        this.seen = new Set(this.items.map((item) => item.address));
+        return true;
+    }
+    merge(candidates) {
+        for (const candidate of candidates)
+            this.offer(candidate);
+    }
+    entries() {
+        return this.items.slice();
+    }
+}
+export function createMiner(constants, face, keccak256) {
+    const deriver = createAddressDeriver(constants, keccak256);
+    const score = makeScorer(face);
+    /** Off the hot path — only runs when a candidate reaches the leaderboard. */
+    function buildCandidate(nonce, address, value) {
+        const { data, colors } = bloImage(address);
+        return {
+            saltNonce: String(nonce),
+            address,
+            score: value,
+            maxScore: face.maxScore,
+            twoColor: isTwoColor(data),
+            contrast: Math.round(colorContrast(colors[0], colors[1])),
+            regions: describeMatch(face, data).regions,
+        };
+    }
+    return {
+        mine(options) {
+            const chunkSize = options.chunkSize ?? 250_000;
+            if (!Number.isInteger(chunkSize) || chunkSize <= 0) {
+                throw new Error(`chunkSize must be a positive integer, got ${chunkSize}`);
+            }
+            // keep is validated by the Leaderboard constructor below.
+            const board = new Leaderboard(options.keep ?? 20);
+            // Allocated once for the whole run; the hot loop allocates nothing else.
+            const data = new Uint8Array(32);
+            const rseed = new Uint32Array(4);
+            let scanned = 0;
+            while (scanned < options.count) {
+                const from = options.start + scanned;
+                const to = from + Math.min(chunkSize, options.count - scanned);
+                for (let nonce = from; nonce < to; nonce++) {
+                    const address = deriver.derive(nonce);
+                    bloDataInto(address, data, rseed);
+                    const value = score(data);
+                    if (value >= board.threshold)
+                        board.offer(buildCandidate(nonce, address, value));
+                }
+                scanned = to - options.start;
+                if (options.onProgress?.(scanned, board.entries()) === false)
+                    break;
+            }
+            return { scanned, candidates: board.entries() };
+        },
+    };
+}
+//# sourceMappingURL=miner.js.map

package/dist/miner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"miner.js","sourceRoot":"","sources":["../src/miner.ts"],"names":[],"mappings":"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"}

package/dist/scoring.d.ts

@@ -0,0 +1,27 @@
+import type { CompiledFace, FaceSpec, Hsl } from './types.js';
+/**
+ * Largest-remainder apportionment: split `budget` across `rawWeights` proportionally using
+ * integers that sum to exactly `budget`.
+ *
+ * The spec's `Math.round(raw / total * budget)` does not do this — it yields 57 for a 3-stroke
+ * mouth and 62 for a 2-stroke one, silently making some expressions worth more than others.
+ */
+export declare function apportion(rawWeights: number[], budget: number): number[];
+export declare function compileFace(spec: FaceSpec): CompiledFace;
+/**
+ * Builds the hot-path scorer. Everything is hoisted into locals so the returned closure is
+ * monomorphic: integer-only, no allocation, no division, no property lookups per candidate.
+ */
+export declare function makeScorer(face: CompiledFace): (data: Uint8Array) => number;
+/** Off the hot path: which alternative won in each region, plus the total score. */
+export declare function describeMatch(face: CompiledFace, data: Uint8Array): {
+    score: number;
+    regions: Record<string, string>;
+};
+/** True when the grid never uses blo's spot colour, i.e. the blockie renders in two colours. */
+export declare function isTwoColor(data: Uint8Array): boolean;
+/** blo emits h 0-360, s 0-100, l 0-100. Returns r/g/b in 0-255. */
+export declare function hslToRgb(h: number, s: number, l: number): [number, number, number];
+/** Euclidean RGB distance between two HSL colours. 0 = identical, ~441.7 = black vs white. */
+export declare function colorContrast(a: Hsl, b: Hsl): number;
+//# sourceMappingURL=scoring.d.ts.map

package/dist/scoring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scoring.d.ts","sourceRoot":"","sources":["../src/scoring.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,YAAY,CAAA;AAE7D;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAYxE;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,GAAG,YAAY,CAgFxD;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,YAAY,GAAG,CAAC,IAAI,EAAE,UAAU,KAAK,MAAM,CAyC3E;AAED,oFAAoF;AACpF,wBAAgB,aAAa,CAC3B,IAAI,EAAE,YAAY,EAClB,IAAI,EAAE,UAAU,GACf;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CA6BpD;AAED,gGAAgG;AAChG,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAGpD;AAED,mEAAmE;AACnE,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAOlF;AAED,8FAA8F;AAC9F,wBAAgB,aAAa,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,GAAG,MAAM,CAIpD"}