Sui Vanity Tools

A high-performance Sui vanity address generator with Apple Metal GPU acceleration.

Generate Sui addresses with custom prefixes and/or suffixes. Supports three modes: GPU Metal (macOS), CPU private key, and CPU mnemonic.

Performance

Benchmarked on Apple M4:

Mode	Speed	Output
GPU Metal	~248,000 addr/sec	Private key (hex)
CPU Private Key	~560,000 addr/sec	Private key (hex)
CPU Mnemonic	~9,000 addr/sec	BIP39 mnemonic phrase

Note

Why is CPU faster than GPU? See CPU vs GPU Performance below. Also see Why GPU Vanity Generation Can't Be Faster (And Why Our Approach Is Already Optimal)?.

Installation

Requirements

• Rust toolchain (1.70+)
• macOS with Apple Silicon (M1/M2/M3/M4) for GPU mode
• Any platform for CPU mode

Build

git clone https://github.com/nathanramli/sui-vanity-tools.git
cd sui-vanity-tools
cargo build --release

The first GPU run compiles the Metal shader (~115 seconds). Subsequent runs use a cached binary at ~/.cache/sui-vanity-tools/pipeline.metallib.

Usage

Quick Start

# Find address starting with "dead" using CPU (fast private key mode)
cargo run --release -- --prefix dead --key-type privkey

# Find address starting with "cafe" using GPU
cargo run --release -- --prefix cafe --gpu metal

# Find address ending with "0000"
cargo run --release -- --suffix 0000 --key-type privkey

# Find address with both prefix and suffix
cargo run --release -- --prefix ab --suffix cd --key-type privkey

CLI Options

Options:
  -p, --prefix <PREFIX>        Target prefix (without 0x)
  -s, --suffix <SUFFIX>        Target suffix (last characters of address)
  -w, --word-size <WORD_SIZE>  Word size for mnemonic: 12, 15, 18, 21, or 24 [default: 24]
      --key-type <KEY_TYPE>    Key output type for CPU mode: "mnemonic" or "privkey" [default: mnemonic]
  -t, --threads <THREADS>      Number of worker threads [default: number of CPU cores]
  -b, --batch-size <SIZE>      Keys per GPU batch [default: 10000]
  -g, --gpu <GPU>              GPU backend: auto, metal, cuda, opencl, cpu [default: cpu]
      --gpu-info               Show GPU information and exit
      --test-gpu               Run GPU Ed25519 test and exit
      --debug                  Enable debug output
  -h, --help                   Print help
  -V, --version                Print version

Modes

CPU Private Key mode (--key-type privkey) — Fastest option. Generates a random 32-byte seed per attempt, derives the Ed25519 keypair and Sui address. Outputs a hex private key.

CPU Mnemonic mode (default) — Generates a BIP39 mnemonic phrase per attempt using SLIP-0010 key derivation. Slower due to PBKDF2 (2048 HMAC-SHA512 rounds), but outputs a human-readable recovery phrase.

GPU Metal mode (--gpu metal) — Offloads Ed25519 scalar multiplication to Apple Metal GPU. Generates a secure master seed on CPU, then the GPU derives millions of keys in parallel using Blake2b(seed || counter). CPU verifies all matches.

Importing Your Key

After finding a matching address:

# Private key mode (GPU or CPU --key-type privkey)
sui keytool import <private-key-hex> ed25519

# Mnemonic mode
sui keytool import "<mnemonic phrase>" ed25519

How It Works

Sui Address Generation

A Sui address is derived from an Ed25519 public key:

Address = Blake2b-256(0x00 || ed25519_public_key)

Where 0x00 is the Ed25519 signature scheme flag byte.

The standard Ed25519 key derivation (RFC 8032):

seed (32 bytes) → SHA-512(seed) → clamp(first 32 bytes) → scalar × G → public_key

GPU Pipeline

The GPU pipeline processes keys in bulk:

1. CPU generates a 32-byte master seed using the OS cryptographic random number generator
2. GPU runs in parallel for each counter value:
   • derived_seed = Blake2b-256(master_seed || counter)
   • hash = SHA-512(derived_seed) (standard Ed25519)
   • scalar = clamp(hash[0..32])
   • public_key = scalar × G (Ed25519 base point multiplication)
   • address = Blake2b-256(0x00 || public_key)
   • Pattern match against target prefix/suffix
3. CPU verifies any match reported by the GPU using the Sui SDK

CPU Private Key Pipeline

Each thread independently:

1. Generate a random 32-byte seed using the OS CSPRNG
2. Construct Ed25519KeyPair from the seed (via fastcrypto)
3. Wrap in SuiKeyPair and derive SuiAddress (identical to wallet import path)
4. Check address against target pattern

CPU Mnemonic Pipeline

Each thread independently:

1. Generate a BIP39 mnemonic phrase
2. Derive an Ed25519 keypair via PBKDF2 + SLIP-0010
3. Compute the Sui address
4. Check address against target pattern

CPU vs GPU Performance

A natural question: why is CPU private key mode (~560K/sec) faster than GPU Metal (~248K/sec)?

GPU overhead costs:

• Kernel dispatch latency — each batch requires CPU-GPU synchronization
• Complex shader pipeline — the Metal shader implements the full Ed25519 scalar multiplication (including SHA-512, field arithmetic, and group operations) in ~1100 lines of Metal Shading Language, operating under register pressure constraints
• Conservative threadgroup sizing — threadgroup size is limited to 64 threads (instead of 1024) because the Ed25519 kernel uses many registers per thread; larger groups cause register spilling and incorrect results
• Atomic synchronization — GPU threads coordinate via atomic compare-exchange to report matches

CPU advantages:

• Optimized native libraries — fastcrypto uses highly optimized, platform-specific Ed25519 implementations compiled with native CPU instructions
• No dispatch overhead — each thread runs independently with zero synchronization (except an atomic flag check per key)
• Full core utilization — 10 threads on M4 (10 CPU cores), each running optimized native code
• No data transfer — all computation stays in CPU cache/registers

When GPU wins:

• GPU mode uses a single master seed, producing a deterministic key sequence. This avoids per-key CSPRNG overhead
• For algorithms with higher arithmetic intensity and lower register pressure (e.g., secp256k1), GPU parallelism would dominate
• Future optimizations (larger threadgroups, reduced register usage) could improve GPU throughput

Note

"Can't you just add G to the previous public key instead of recomputing from scratch?" This is the increment-and-add trick that gives Ethereum vanity generators a ~200x speedup — but it's mathematically impossible for Ed25519 with wallet-importable keys. Ed25519's mandatory SHA-512 step destroys all structure between consecutive seeds. See docs/GPU_PERFORMANCE.md for a full explanation of this limitation and why the current approach is already optimal.

Security

Key Generation

Master seed generation (GPU mode): The 32-byte master seed is generated on the CPU using rand::thread_rng(), which is backed by the OS cryptographic random number generator (e.g., getrandom() on macOS/Linux). The GPU never generates random numbers — it only derives keys deterministically from the CPU-provided seed.

Per-key seed generation (CPU mode): Each key uses a fresh 32-byte random seed from the OS CSPRNG.

Key Derivation

GPU key derivation: Blake2b-256(master_seed || counter) produces each derived seed. Blake2b is a cryptographic hash function (RFC 7693) widely used in blockchain systems (including Sui itself). The counter is a sequential 32-bit integer, ensuring each derived seed is unique and deterministic.

Ed25519 compliance: Both GPU and CPU follow the standard Ed25519 derivation (RFC 8032): SHA-512(seed) → clamp → scalar × base_point. The GPU implements this in Metal shader code; the CPU uses fastcrypto (the same library used by the Sui blockchain).

CPU Verification

The GPU occasionally produces incorrect Ed25519 results due to register pressure in the Metal shader. To prevent false matches:

1. Every GPU match is verified on CPU using the Sui SDK (SuiKeyPair::Ed25519)
2. This uses the exact same code path as sui keytool import — guaranteeing the output key actually produces the claimed address
3. False positives are silently discarded and the search continues

Wallet Compatibility

The output private key (32-byte hex seed) is the standard Ed25519 seed format. Import with:

sui keytool import <hex-private-key> ed25519

This runs the identical derivation: Ed25519KeyPair::from_bytes(seed) → SuiKeyPair → SuiAddress. The address you see in the tool output will match exactly.

Debug Mode Warning

The --debug flag prints the master seed to stderr. Do not use --debug in production — anyone who sees the master seed can derive all private keys generated in that session (GPU mode).

Project Structure

sui-vanity-tools/
├── Cargo.toml
├── src/
│   ├── main.rs              # CLI, CPU search modes, GPU orchestration
│   ├── gpu/
│   │   ├── mod.rs           # GPU trait and backend detection
│   │   └── metal.rs         # Apple Metal backend + Ed25519 test suite
│   └── shaders/
│       └── ed25519_simple.metal  # Metal GPU shader (~1100 lines)

License

See LICENSE for details.