Generate Ethereum Vanity Address

Instructions

Implementation Reference

• src/vanity-address/generator.ts:21-75 (registration)

  Registers the 'generate-vanity-address' tool with the MCP server, including title, description, input schema, and the handler function.

        "generate-vanity-address",
        {
          title: "Generate Ethereum Vanity Address",
          description: "Generate Ethereum addresses matching specified prefix and suffix patterns with concurrent computation",
          inputSchema: {
            prefix: z.string().optional().describe("Address prefix (without 0x), e.g., '1234'"),
            suffix: z.string().optional().describe("Address suffix, e.g., 'abcd'"),
            workers: z.number().min(1).max(16).default(4).describe("Number of concurrent worker threads, default 4"),
            caseSensitive: z.boolean().default(false).describe("Whether to match case-sensitively, default false")
          }
        },
        async ({ prefix, suffix, workers = 4, caseSensitive = false }) => {
          if (!prefix && !suffix) {
            return {
              content: [{
                type: "text",
                text: "Error: Must specify at least one of prefix or suffix"
              }],
              isError: true
            };
          }
  
          try {
            const result = await this.generateVanityAddress({
              prefix: prefix?.toLowerCase(),
              suffix: suffix?.toLowerCase(),
              workers,
              caseSensitive
            });
  
            return {
              content: [{
                type: "text",
                text: `✅ Successfully generated vanity address!
  
  🔹 Address: ${result.address}
  🔹 Private Key: ${result.privateKey}
  🔹 Attempts: ${result.attempts.toLocaleString()}
  🔹 Time Taken: ${(result.timeMs / 1000).toFixed(2)} seconds
  🔹 Hash Rate: ${Math.round(result.attempts / (result.timeMs / 1000)).toLocaleString()} addresses/sec
  
  ⚠️  Please keep the private key secure and never share it with others!`
              }]
            };
          } catch (error) {
            return {
              content: [{
                type: "text",
                text: `Error generating vanity address: ${error instanceof Error ? error.message : String(error)}`
              }],
              isError: true
            };
          }
        }
      );

• src/vanity-address/generator.ts:113-170 (handler)

  Orchestrates multiple worker threads to generate a vanity address matching the specified prefix and/or suffix patterns, collects statistics, and returns the result.

  private async generateVanityAddress(options: {
    prefix?: string;
    suffix?: string;
    workers: number;
    caseSensitive: boolean;
  }): Promise<VanityResult> {
    const startTime = Date.now();
    const workers: Worker[] = [];
    let totalAttempts = 0;
    let found = false;
    let result: VanityResult | null = null;
  
    return new Promise((resolve, reject) => {
      for (let i = 0; i < options.workers; i++) {
        const worker = new Worker(join(__dirname, 'worker.js'), {
          workerData: {
            prefix: options.prefix,
            suffix: options.suffix,
            caseSensitive: options.caseSensitive,
            workerId: i
          }
        });
  
        worker.on('message', (data) => {
          if (data.type === 'found' && !found) {
            found = true;
            result = {
              address: data.address,
              privateKey: data.privateKey,
              attempts: totalAttempts + data.attempts,
              timeMs: Date.now() - startTime
            };
            
            workers.forEach(w => w.terminate());
            resolve(result);
          } else if (data.type === 'progress') {
            totalAttempts += data.attempts;
          }
        });
  
        worker.on('error', (error) => {
          if (!found) {
            workers.forEach(w => w.terminate());
            reject(error);
          }
        });
  
        workers.push(worker);
      }
  
      setTimeout(() => {
        if (!found) {
          workers.forEach(w => w.terminate());
          reject(new Error('Generation timeout, try reducing difficulty or increasing worker threads'));
        }
      }, 300000);
    });
  }

• src/vanity-address/worker.ts:34-58 (helper)

  Core logic in worker thread: continuously generates random Ethereum wallets using ethers.Wallet.createRandom() until an address matches the prefix/suffix patterns, then sends result to parent.

  function generateAndCheck(): void {
    while (true) {
      const wallet = ethers.Wallet.createRandom();
      attempts++;
      
      if (matchesPattern(wallet.address, prefix, suffix, caseSensitive)) {
        parentPort?.postMessage({
          type: 'found',
          address: wallet.address,
          privateKey: wallet.privateKey,
          attempts: attempts
        });
        break;
      }
      
      if (attempts % progressInterval === 0) {
        parentPort?.postMessage({
          type: 'progress',
          attempts: progressInterval,
          workerId: workerId
        });
        attempts = 0;
      }
    }
  }

• src/vanity-address/worker.ts:16-32 (helper)

  Utility function to check if an Ethereum address matches the given prefix and suffix patterns (case-sensitive option).

  function matchesPattern(address: string, targetPrefix?: string, targetSuffix?: string, isCaseSensitive?: boolean): boolean {
    const addr = isCaseSensitive ? address : address.toLowerCase();
    const addrWithoutPrefix = addr.slice(2);
    
    let prefixMatch = true;
    let suffixMatch = true;
    
    if (targetPrefix) {
      prefixMatch = addrWithoutPrefix.startsWith(targetPrefix);
    }
    
    if (targetSuffix) {
      suffixMatch = addrWithoutPrefix.endsWith(targetSuffix);
    }
    
    return prefixMatch && suffixMatch;
  }

• src/index.ts:13-17 (registration)

  Instantiates VanityAddressGenerator and calls registerWithServer to register its tools with the main MCP server.

  const vanityGenerator = new VanityAddressGenerator();
  const castCommands = new CastCommands();
  const rpcService = new RpcService();
  
  vanityGenerator.registerWithServer(server);