revanity

A cross-platform vanity address generator for Reticulum and LXMF networks.

Generate a personalized, memorable address for use with Sideband, Nomadnet, and any application built on the Reticulum Network Stack.

Works on macOS, Linux, and Windows. Comes with both a graphical interface (GUI) and a command-line interface (CLI).

---

Table of Contents

• What Is This?
• Security Considerations
• How It Works
• Installation
  • macOS
  • Linux (Ubuntu / Debian)
  • Windows
• Usage
  • Graphical Interface (GUI)
  • Command Line (CLI)
• Importing Your Vanity Address
• Difficulty Reference
• License

---

What Is This?

Every Reticulum identity is associated with a 32-character hexadecimal address (for example a4f2c9e801b73d5f6890abcdef123456). When you install Sideband, Nomadnet, or any other Reticulum application, it generates a random address for you. That address is permanent — it is tied to your cryptographic keys, and there is no way to choose it.

revanity lets you generate a customized address. You pick a pattern — for example, you want your address to start with cafe or dead — and the tool rapidly generates thousands of key pairs per second until it finds one whose address matches your desired pattern.

This is the same concept as vanity address generators in Bitcoin and Ethereum, adapted for the Reticulum network.

---

Security Considerations

Before using a vanity address, you should understand the security implications:

Your Cryptography Is NOT Weakened

revanity does not weaken your encryption in any way. Every key pair is generated using the same cryptographically secure random number generator (CSPRNG) that Reticulum uses normally. The tool simply generates many key pairs and discards the ones that don't match your pattern. The key pair you end up with is every bit as secure as one generated by Sideband or Nomadnet directly.

The Impersonation Risk

The primary risk with vanity addresses is impersonation. If your address starts with cafe, an attacker could also generate an address starting with cafe in a matter of seconds. Someone who only checks the first few characters of your address could be fooled.

Mitigation:

• A short prefix (1-4 characters) offers no meaningful protection against impersonation. It only makes your address easier to remember.
• A longer prefix (6+ characters) is exponentially harder to reproduce, but never impossible.
• Always verify the full 32-character address when communicating with someone. Never rely on just the first few characters.
• Share your full address through a trusted channel (in person, signed message, QR code, etc.).

Protect Your Private Key

When revanity finds a matching address, it saves your private key to a .identity file. Anyone who obtains this file can fully impersonate you — they can read messages intended for you, send messages as you, and access any resources tied to your identity.

• Store your .identity file securely.
• Do not share it, email it, or upload it to cloud storage.
• The file is automatically saved with restrictive permissions (owner-only read/write) on macOS and Linux.

---

How It Works

Reticulum Identity Basics

A Reticulum identity is a pair of cryptographic keys:

1. X25519 key — Used for encryption (so others can send you encrypted messages).
2. Ed25519 key — Used for digital signatures (so others can verify messages are really from you).

Together, these two keys form your identity. Each key has a private half (which you keep secret) and a public half (which you share with the world).

How Your Address Is Derived

Your address is not your public key. It is a shortened hash of your public key, computed like this:

1. Your two public keys are concatenated together (64 bytes total).
2. A SHA-256 hash is computed over those 64 bytes.
3. The hash is truncated to 16 bytes (128 bits), giving a 32-character hex string — your identity hash.

For LXMF applications (like Sideband), there is one more step:

4. A fixed "name hash" for the destination type (e.g. lxmf.delivery) is prepended to your identity hash.
5. Another SHA-256 hash is computed and truncated to 16 bytes — this is your LXMF address, the one displayed in the app.

What Brute-Forcing Means

revanity performs the following loop at high speed:

1. Generate a brand new, random X25519 + Ed25519 key pair.
2. Compute the LXMF address from the public keys (two SHA-256 hashes).
3. Check if the address matches your desired pattern.
4. If it matches, save the key pair. If not, discard it and try again.

This is a forward-only computation — there is no way to work backward from a desired address to a key. The tool must try key after key until one happens to produce a matching address. Depending on how long your pattern is, this can take anywhere from a fraction of a second to days.

revanity uses all of your CPU cores in parallel to maximize speed.

---

Installation

macOS

Step 1: Make sure Python is installed.

Open Terminal (search for "Terminal" in Spotlight) and type:

python3 --version

If you see a version number (3.10 or higher), you're good. If not, install Python:

brew install python

If you don't have Homebrew, visit brew.sh first, or download Python directly from python.org/downloads.

Step 2: Install revanity.

pip3 install customtkinter cryptography

Then clone and run:

git clone https://github.com/defidude/revanity.git
cd revanity
python3 -m revanity

This opens the graphical interface.

Step 3 (Optional): Install the RNS library for verification.

pip3 install rns

This lets revanity double-check that your generated address is correct by verifying it against the official Reticulum library.

---

Linux (Ubuntu / Debian)

Step 1: Install Python and Tkinter.

sudo apt update
sudo apt install python3 python3-pip python3-tk git

Step 2: Install revanity.

pip3 install customtkinter cryptography

Then clone and run:

git clone https://github.com/defidude/revanity.git
cd revanity
python3 -m revanity

If you prefer CLI-only (no GUI):

python3 -m revanity --prefix dead

Step 3 (Optional): Install RNS for verification.

pip3 install rns

---

Windows

Step 1: Install Python.

1. Go to python.org/downloads and download the latest Python 3 installer.
2. Important: During installation, check the box that says "Add Python to PATH".
3. Complete the installation.

Step 2: Open Command Prompt.

Press Win + R, type cmd, and press Enter.

Step 3: Install revanity.

pip install customtkinter cryptography

Then clone and run:

git clone https://github.com/defidude/revanity.git
cd revanity
python -m revanity

If you don't have Git, you can download the repository as a ZIP from GitHub and extract it instead.

Step 4 (Optional): Install RNS for verification.

pip install rns

---

Usage

Graphical Interface (GUI)

Launch the GUI by running:

python3 -m revanity

1. Choose your destination type. The default lxmf.delivery is what Sideband and Nomadnet use for messaging. If you're generating an address for a Nomadnet node, select nomadnetwork.node.

2. Choose a match mode:

   • Prefix — Your address will start with your pattern (most common).
   • Suffix — Your address will end with your pattern.
   • Contains — Your pattern can appear anywhere in the address.
   • Regex — Use a regular expression for advanced matching.

3. Enter your pattern. Only hexadecimal characters are valid: 0-9 and a-f. For example: dead, cafe, beef, abc.

4. Adjust worker count if desired. More workers = faster search, but uses more CPU.

5. Click Start Search. The tool will show real-time progress (keys checked, speed, elapsed time).

6. When a match is found, click Save .identity to save your key pair. Click Copy Address to copy the address to your clipboard. Optionally click Verify with RNS to confirm the address against the official Reticulum library.

Command Line (CLI)

# Find an address starting with "dead"
python3 -m revanity --prefix dead

# Find an address ending with "cafe", using 8 workers
python3 -m revanity --suffix cafe --workers 8

# Find an address containing "beef" anywhere
python3 -m revanity --contains beef

# Use regex matching
python3 -m revanity --regex "^(dead|beef)"

# Generate for a Nomadnet node
python3 -m revanity --prefix abc --dest nomadnetwork.node

# Just show the difficulty estimate
python3 -m revanity --prefix deadbeef --dry-run

# Quiet mode (outputs only the address, useful for scripting)
python3 -m revanity --prefix dead --quiet

Each successful search produces two files:

• <address>.identity — The raw 64-byte identity file. This is the file you import into your Reticulum application.
• <address>.txt — A human-readable file containing your address, identity hash, private key in multiple formats (hex, Base32, Base64), and step-by-step import instructions.

---

Importing Your Vanity Address

After generating your vanity address, you need to import it into your Reticulum application. Make sure to back up any existing identity before replacing it.

Sideband (Desktop - Linux)

# Back up your current identity first
cp ~/.config/sideband/storage/identity ~/.config/sideband/storage/identity.backup

# Copy your new identity
cp <address>.identity ~/.config/sideband/storage/identity

# Restart Sideband

Sideband (Desktop - macOS)

# Back up your current identity first
cp ~/Library/Application\ Support/Sideband/storage/identity ~/Library/Application\ Support/Sideband/storage/identity.backup

# Copy your new identity
cp <address>.identity ~/Library/Application\ Support/Sideband/storage/identity

# Restart Sideband

Sideband (Android)

Open the .txt file that was saved alongside your .identity file. Copy the Base32 string. In Sideband, go to Settings and import your identity using the Base32 key.

Nomadnet

# Back up your current identity first
cp ~/.nomadnetwork/storage/identity ~/.nomadnetwork/storage/identity.backup

# Copy your new identity
cp <address>.identity ~/.nomadnetwork/storage/identity

# Restart Nomadnet

Any RNS Application (Python)

import RNS
identity = RNS.Identity.from_file("path/to/<address>.identity")

---

Difficulty Reference

Each hexadecimal character in your pattern multiplies the difficulty by 16. Longer patterns take exponentially longer to find.

Pattern Length	Expected Attempts	Approximate Time (8 cores)
1 character	16	Instant
2 characters	256	Instant
3 characters	4,096	Under 1 second
4 characters	65,536	A few seconds
5 characters	1,048,576	Under a minute
6 characters	16,777,216	Several minutes
7 characters	268,435,456	A few hours
8 characters	4,294,967,296	A day or more

Times are rough estimates and vary significantly based on your CPU, number of cores, and luck. A "suffix" match has the same difficulty as a "prefix" match of the same length. A "contains" match is slightly easier because the pattern can appear anywhere in the 32-character address.

---

License

MIT License. See LICENSE for details.