nahualli

Vanity stealth key grinder for ERC-5564 stealth addresses. Brute-forces secp256k1 key generation until the compressed public key's X coordinate starts with your chosen hex prefix.

Uses Web Workers in browsers for parallel grinding. Falls back to a single-threaded loop in Node.js.

Install

npm install nahualli @noble/curves

@noble/curves is a peer dependency.

Usage

Grind a vanity prefix

import { createGrindingSession } from "nahualli";

const session = createGrindingSession({ pattern: "dead" });

session.subscribe((state) => {
  if (state.status === "running") {
    console.log(`${state.totalAttempts} attempts, ${state.attemptsPerSecond | 0} keys/s`);
  }
  if (state.status === "found") {
    console.log(`match: ${state.result.spendingKey.publicKeyHex}`);
  }
});

await session.start();

const { result } = session.getState();
// result.spendingKey  -- vanity-matched key pair
// result.viewingKey   -- independent random key pair

Check difficulty first

import { estimateGrindTime } from "nahualli";

const est = estimateGrindTime(4); // 4 hex chars
// { expectedAttempts: 65536, expectedSeconds: 1.6, difficulty: "seconds" }

Generate random keys (no vanity matching)

import { generateRandomKeys } from "nahualli";

const keys = generateRandomKeys();
// keys.spendingKey, keys.viewingKey

API

createGrindingSession(input): GrindingSession

Option	Type	Default	Description
pattern	string	--	Hex prefix to match (with or without 0x)
workers	number	navigator.hardwareConcurrency or 4	Worker thread count

Returns a GrindingSession:

• start() -- begins grinding, resolves when a match is found or the session is stopped
• stop() -- signals all workers to stop
• getState() -- returns current GrindingSessionState
• subscribe(listener) -- observe state changes, returns an unsubscribe function

estimateGrindTime(patternLength, workers?): GrindDifficulty

Returns { expectedAttempts, expectedSeconds, difficulty } where difficulty is "instant", "seconds", "minutes", "hours", or "impractical".

generateRandomKeys(): StealthKeyResult

Returns a spending/viewing key pair with no vanity matching.

Difficulty

Each hex character multiplies the search space by 16x.

Prefix length	Expected attempts	Time (4 workers)
1	16	instant
2	256	instant
3	4,096	instant
4	65,536	~2s
5	1,048,576	~26s
6	16,777,216	~7min
7	268,435,456	~2hr
8+	4,294,967,296+	impractical

Related

• erc-xochi-zkp -- ZK compliance proofs for stealth transactions
• ERC-5564 -- stealth addresses
• ERC-6538 -- stealth meta-address registry

License

MIT