elemental-tokens

elemental-tokens

Human-transcribable, LLM-stable tokens built from chemical element symbols.

Fe-Au-Rn-Cu-Xe

Five symbols off the periodic table. Easy to read aloud, easy to type, easy for a language model to echo back without mangling — and backed by a cryptographically secure RNG. Each symbol is worth a clean 6.7 bits of entropy, so the whole token is just length × 6.7 bits of unpredictability with nothing to memorize.

Why element symbols?

A good short identifier has to survive being spoken, typed, dictated to a phone, or round-tripped through an LLM. Random base32 (q7f2k9) and UUIDs fail that test: l/1/I and 0/O collide, and a model has no prior for an arbitrary string.

Element symbols are different:

• A closed, formally specified set. No synonyms, no spelling variants, no "correct" value a model would prefer. Rn means Rn.
• Strong LLM priors. The periodic table is learned as a single complete artifact — including the superheavy elements — so models reproduce symbols reliably and detect typos against a known vocabulary.
• Invalid symbols are detectable before any database lookup. Xx is simply not an element.
• Uniform two-character width. Every symbol is exactly two characters, giving a transcriber positional anchors and removing drop/merge errors.

The vocabulary is the 104 two-letter symbols only. All 14 single-letter symbols (H, B, C, N, O, F, P, S, K, V, W, Y, I, U) are excluded — a lone C floating next to Fe is exactly the kind of thing that gets dropped or merged. 104 symbols is log2(104) ≈ 6.7 bits apiece.

Install

npm install elemental-tokens

Ships ESM + CommonJS + TypeScript types. Runs on Node.js ≥ 18 and in the browser (uses the Web Crypto API via globalThis.crypto).

Quick start

import { generate, validate } from "elemental-tokens";

const token = generate();        // "Fe-Au-Rn-Cu-Xe"
validate(token);                 // true
validate("fe-au-rn-cu-xe");      // false  (case-sensitive)
validate("Xx-Au-Rn-Cu-Xe");      // false  (Xx is not an element)

CommonJS:

const { generate, validate } = require("elemental-tokens");

API

generate(options?): string

Generates a token. Each symbol is drawn uniformly from the vocabulary with a CSPRNG and rejection sampling — that's the full 6.7 bits per symbol, no modulo bias shaving anything off.

Option	Type	Default	Description
length	number	5	Number of symbols. Positive integer.
delimiter	string	"-"	String placed between symbols.
symbols	string[]	the 104 elements	Override the vocabulary entirely.

generate();                                   // "Mg-Sc-Pb-Re-Nd"
generate({ length: 8 });                      // 8 symbols ≈ 53.6 bits
generate({ delimiter: "" });                  // "MgScPbReNd"
generate({ symbols: ["aa", "bb", "cc"] });    // custom vocabulary

Throws RangeError if length is not a positive integer, or if symbols is provided but not a non-empty array.

validate(token, options?): boolean

Returns true only if every delimiter-separated segment is a known symbol. Strict and case-sensitive — "Fe-Au" is valid, "fe-au" is not. No trimming, no checksum. Returns false for an empty token or any empty segment (leading, trailing, or doubled delimiters). Pass the same delimiter / symbols you generated with.

validate("Fe-Au-Rn-Cu-Xe");                       // true
validate("Fe.Au", { delimiter: "." });            // true
validate("aa-bb", { symbols: ["aa", "bb"] });     // true

Exported constants

import { ELEMENT_SYMBOLS, SYMBOL_COUNT, BITS_PER_SYMBOL } from "elemental-tokens";

SYMBOL_COUNT;     // 104
BITS_PER_SYMBOL;  // 6.700439718141092

Entropy math

The unit of account is one symbol = log2(104) ≈ **6.7 bits**. A token is just a stack of these 6.7-bit quanta, so picking a length is picking a strength:

Length	Entropy	Notes
4	≈ 26.8 bits
5	≈ 33.5 bits	default — 5 × 6.7
6	≈ 40.2 bits
8	≈ 53.6 bits
12	≈ 80.4 bits
20	≈ 134 bits	~128-bit-class secret

To hit a target strength, divide by 6.7: 128 bits ÷ 6.7 ≈ 20 symbols.

Threat model

elemental-tokens is designed as a security-load-bearing identifier for short-lived tokens under aggressive rate limiting — think a token that's valid for five minutes and gets at most a few dozen guesses before lockout.

• CSPRNG only. Randomness comes from crypto.getRandomValues (Web Crypto, present in Node ≥ 18 and browsers). Math.random is never used.
• No modulo bias. Sampling uses rejection sampling, so each of the 104 symbols is equally likely and the per-symbol entropy really is the full 6.7 bits — not "6.7 bits minus a sliver." (The 256-byte enumeration test proves each symbol is reachable from exactly two byte values.)
• The whole vocabulary is public. Observing tokens teaches an attacker nothing; the search space is fixed at 104^length.
• No checksum, by design. Error detection is the database lookup — an unknown or malformed token fails immediately. If you need offline typo detection, use a longer token or add your own check digit.
• Pick length for your threat model. The default 33.5 bits is comfortable for rate-limited, short-lived tokens (50 guesses in 5 minutes is ~50 / 2^33.5 ≈ 1 in 170 million per window). It is not sized for offline brute force — for secrets that must resist that, use length ≥ 12 (≈ 80 bits) or ≥ 20 (≈ 128 bits).

Comparison to a BIP39 wordlist

BIP39 is the closest well-known relative: a fixed vocabulary mapped to entropy.

	BIP39	elemental-tokens
Vocabulary size	2048 words	104 symbols
Entropy per unit	11 bits/word	6.7 bits/symbol
Unit length	3–8 letters	exactly 2 characters
Checksum	yes (built into seed phrase)	no (lookup is the check)
Designed for	128–256-bit seed phrases	short, dictation-friendly tokens
Units to reach ~128 bits	~12 words	~20 symbols
Autocorrect risk	high (real English words)	low (not dictionary words)

BIP39 trades shorter sequences for a much larger, English-word vocabulary and a checksum. elemental-tokens trades that for shorter, two-character atoms that are faster to read aloud, internationally recognizable, and stable through an LLM — at a tidy 6.7 bits each.

TypeScript

Types ship with the package:

import { generate, type GenerateOptions } from "elemental-tokens";

const opts: GenerateOptions = { length: 8, delimiter: "-" };
const token = generate(opts);

License

MIT © Nibs