@safe-vanity-blockie/core 0.3.0

package/src/address.ts

@@ -0,0 +1,89 @@
+import { bytesToHex } from './hex.js'
+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
+}
+
+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: SafeConstants,
+  keccak256: Keccak256,
+): AddressDeriver {
+  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(): string {
+    const salt = keccak256(saltPreimage)
+    create2Preimage.set(salt, 21)
+    return bytesToHex(keccak256(create2Preimage), 12, 32)
+  }
+
+  return {
+    derive(saltNonce: number): string {
+      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: bigint): string {
+      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)
+      }
+    },
+  }
+}

package/src/blo.ts

@@ -0,0 +1,100 @@
+import type { BloImage, Hsl, Palette } from './types.js'
+
+/** = 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: string, rseed: Uint32Array): void {
+  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: string): Uint32Array {
+  const rseed = new Uint32Array(4)
+  seedInto(seed, rseed)
+  return rseed
+}
+
+export function nextRandom(rseed: Uint32Array): number {
+  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: Uint32Array): Hsl {
+  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: string): BloImage {
+  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] as Palette }
+}
+
+/**
+ * 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: string, data: Uint8Array, rseed: Uint32Array): void {
+  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: string): Uint8Array {
+  const data = new Uint8Array(32)
+  bloDataInto(address.toLowerCase(), data, new Uint32Array(4))
+  return data
+}
+
+export function bloSvg(address: string, size = 64): string {
+  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: Hsl, d: string) =>
+    '<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>'
+  )
+}

package/src/hex.ts

@@ -0,0 +1,25 @@
+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: Uint8Array, start = 0, end = bytes.length): string {
+  let out = '0x'
+  for (let i = start; i < end; i++) out += HEX_BYTES[bytes[i]]
+  return out
+}
+
+export function hexToBytes(hex: string): Uint8Array {
+  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
+}

package/src/index.ts

@@ -0,0 +1,60 @@
+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'

package/src/keccak.ts

@@ -0,0 +1,17 @@
+import { createKeccak } from 'hash-wasm'
+
+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 async function createKeccak256(): Promise<Keccak256> {
+  const hasher = await createKeccak(256)
+  return (input: Uint8Array): Uint8Array => {
+    hasher.init()
+    hasher.update(input)
+    return hasher.digest('binary')
+  }
+}

package/src/miner.ts

@@ -0,0 +1,133 @@
+import { createAddressDeriver, type SafeConstants } from './address.js'
+import { bloDataInto, bloImage } from './blo.js'
+import type { Keccak256 } from './keccak.js'
+import { colorContrast, describeMatch, isTwoColor, makeScorer } from './scoring.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 function compareCandidates(a: Candidate, b: Candidate): number {
+  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 {
+  readonly capacity: number
+  private items: Candidate[] = []
+  private seen = new Set<string>()
+
+  constructor(capacity: number) {
+    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(): number {
+    return this.items.length < this.capacity ? -1 : this.items[this.items.length - 1].score
+  }
+
+  offer(candidate: Candidate): boolean {
+    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: Candidate[]): void {
+    for (const candidate of candidates) this.offer(candidate)
+  }
+
+  entries(): Candidate[] {
+    return this.items.slice()
+  }
+}
+
+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. */
+  // biome-ignore lint/suspicious/noConfusingVoidType: deliberate union with void so callers may return nothing; narrowing to `boolean | undefined` breaks consumers of the published package whose callback bodies infer a `void` return.
+  onProgress?: (scanned: number, best: Candidate[]) => boolean | void
+}
+
+export interface MineResult {
+  scanned: number
+  candidates: Candidate[]
+}
+
+export function createMiner(
+  constants: SafeConstants,
+  face: CompiledFace,
+  keccak256: Keccak256,
+): { mine(options: MineOptions): MineResult } {
+  const deriver = createAddressDeriver(constants, keccak256)
+  const score = makeScorer(face)
+
+  /** Off the hot path — only runs when a candidate reaches the leaderboard. */
+  function buildCandidate(nonce: number, address: string, value: number): Candidate {
+    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: MineOptions): MineResult {
+      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() }
+    },
+  }
+}

package/src/scoring.ts

@@ -0,0 +1,209 @@
+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 function apportion(rawWeights: number[], budget: number): number[] {
+  if (rawWeights.length === 0) return []
+  const total = rawWeights.reduce((a, b) => a + b, 0)
+  if (total <= 0) throw new Error('apportion: raw weights must sum to a positive number')
+  const exact = rawWeights.map((weight) => (weight * budget) / total)
+  const shares = exact.map((value) => Math.floor(value))
+  const remainder = budget - shares.reduce((a, b) => a + b, 0)
+  const order = exact
+    .map((value, index) => ({ index, fraction: value - Math.floor(value) }))
+    .sort((a, b) => b.fraction - a.fraction || a.index - b.index)
+  for (let i = 0; i < remainder; i++) shares[order[i].index] += 1
+  return shares
+}
+
+export function compileFace(spec: FaceSpec): CompiledFace {
+  const used = new Set<number>()
+  const claim = (index: number, where: string) => {
+    if (!Number.isInteger(index) || index < 0 || index > 31) {
+      throw new Error(`${where}: cell index ${index} must be an integer between 0 and 31`)
+    }
+    if (used.has(index)) throw new Error(`${where}: cell index ${index} is used more than once`)
+    used.add(index)
+  }
+
+  const fixedIndex = new Uint8Array(spec.fixed.length)
+  const fixedTarget = new Uint8Array(spec.fixed.length)
+  const fixedWeight = new Int32Array(spec.fixed.length)
+  let maxScore = 0
+  spec.fixed.forEach((cell, i) => {
+    claim(cell.index, `fixed cell ${i}`)
+    fixedIndex[i] = cell.index
+    fixedTarget[i] = cell.value
+    fixedWeight[i] = cell.weight
+    maxScore += cell.weight
+  })
+
+  const regionIndexStart = new Int32Array(spec.regions.length)
+  const regionLength = new Int32Array(spec.regions.length)
+  const regionAltCount = new Int32Array(spec.regions.length)
+  const regionCellStart = new Int32Array(spec.regions.length)
+  const indices: number[] = []
+  const cells: number[] = []
+  const weights: number[] = []
+  const regionNames: string[] = []
+  const regionAltNames: string[][] = []
+
+  spec.regions.forEach((region, r) => {
+    regionIndexStart[r] = indices.length
+    regionCellStart[r] = cells.length
+    regionLength[r] = region.indices.length
+    regionAltCount[r] = region.alternatives.length
+    regionNames.push(region.name)
+    regionAltNames.push(region.alternatives.map((alternative) => alternative.name))
+
+    if (region.alternatives.length === 0) {
+      throw new Error(`region "${region.name}": needs at least one alternative`)
+    }
+    for (const index of region.indices) claim(index, `region "${region.name}"`)
+    indices.push(...region.indices)
+
+    for (const alternative of region.alternatives) {
+      if (alternative.cells.length !== region.indices.length) {
+        throw new Error(
+          `region "${region.name}", alternative "${alternative.name}": expected ` +
+            `${region.indices.length} cells, got ${alternative.cells.length}`,
+        )
+      }
+      const raw = alternative.cells.map((cell) =>
+        cell === 1 ? region.strokeWeight : region.bgWeight,
+      )
+      cells.push(...alternative.cells)
+      weights.push(...apportion(raw, region.budget))
+    }
+    maxScore += region.budget
+  })
+
+  return {
+    name: spec.name,
+    maxScore,
+    nFixed: spec.fixed.length,
+    fixedIndex,
+    fixedTarget,
+    fixedWeight,
+    nRegions: spec.regions.length,
+    regionIndexStart,
+    regionLength,
+    regionAltCount,
+    regionCellStart,
+    regionIndex: Uint8Array.from(indices),
+    regionCells: Uint8Array.from(cells),
+    regionWeights: Int32Array.from(weights),
+    regionNames,
+    regionAltNames,
+  }
+}
+
+/**
+ * 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 function makeScorer(face: CompiledFace): (data: Uint8Array) => number {
+  const {
+    nFixed,
+    fixedIndex,
+    fixedTarget,
+    fixedWeight,
+    nRegions,
+    regionIndexStart,
+    regionLength,
+    regionAltCount,
+    regionCellStart,
+    regionIndex,
+    regionCells,
+    regionWeights,
+  } = face
+
+  return function score(data: Uint8Array): number {
+    let total = 0
+    for (let i = 0; i < nFixed; i++) {
+      if (data[fixedIndex[i]] === fixedTarget[i]) total += fixedWeight[i]
+    }
+    for (let r = 0; r < nRegions; r++) {
+      const indexBase = regionIndexStart[r]
+      const length = regionLength[r]
+      const altCount = regionAltCount[r]
+      const cellBase = regionCellStart[r]
+      let best = 0
+      for (let a = 0; a < altCount; a++) {
+        const offset = cellBase + a * length
+        let got = 0
+        for (let j = 0; j < length; j++) {
+          if (data[regionIndex[indexBase + j]] === regionCells[offset + j]) {
+            got += regionWeights[offset + j]
+          }
+        }
+        if (got > best) best = got
+      }
+      total += best
+    }
+    return total
+  }
+}
+
+/** Off the hot path: which alternative won in each region, plus the total score. */
+export function describeMatch(
+  face: CompiledFace,
+  data: Uint8Array,
+): { score: number; regions: Record<string, string> } {
+  let total = 0
+  for (let i = 0; i < face.nFixed; i++) {
+    if (data[face.fixedIndex[i]] === face.fixedTarget[i]) total += face.fixedWeight[i]
+  }
+  const regions: Record<string, string> = {}
+  for (let r = 0; r < face.nRegions; r++) {
+    const indexBase = face.regionIndexStart[r]
+    const length = face.regionLength[r]
+    const cellBase = face.regionCellStart[r]
+    let best = -1
+    let bestAlt = 0
+    for (let a = 0; a < face.regionAltCount[r]; a++) {
+      const offset = cellBase + a * length
+      let got = 0
+      for (let j = 0; j < length; j++) {
+        if (data[face.regionIndex[indexBase + j]] === face.regionCells[offset + j]) {
+          got += face.regionWeights[offset + j]
+        }
+      }
+      if (got > best) {
+        best = got
+        bestAlt = a
+      }
+    }
+    total += best
+    regions[face.regionNames[r]] = face.regionAltNames[r][bestAlt]
+  }
+  return { score: total, regions }
+}
+
+/** True when the grid never uses blo's spot colour, i.e. the blockie renders in two colours. */
+export function isTwoColor(data: Uint8Array): boolean {
+  for (let i = 0; i < data.length; i++) if (data[i] === 2) return false
+  return true
+}
+
+/** blo emits h 0-360, s 0-100, l 0-100. Returns r/g/b in 0-255. */
+export function hslToRgb(h: number, s: number, l: number): [number, number, number] {
+  const saturation = s / 100
+  const lightness = l / 100
+  const k = (n: number) => (n + h / 30) % 12
+  const a = saturation * Math.min(lightness, 1 - lightness)
+  const f = (n: number) => lightness - a * Math.max(-1, Math.min(k(n) - 3, 9 - k(n), 1))
+  return [f(0) * 255, f(8) * 255, f(4) * 255]
+}
+
+/** Euclidean RGB distance between two HSL colours. 0 = identical, ~441.7 = black vs white. */
+export function colorContrast(a: Hsl, b: Hsl): number {
+  const [r1, g1, b1] = hslToRgb(a[0], a[1], a[2])
+  const [r2, g2, b2] = hslToRgb(b[0], b[1], b[2])
+  return Math.hypot(r1 - r2, g1 - g2, b1 - b2)
+}