Crate fci4096 

fci4096

A BIP39-inspired mnemonic wordlist and seed-derivation library built on 4096 standard Chinese four-character idioms (chengyu). Each idiom encodes 12 bits of entropy (2¹² = 4096), delivering higher information density than BIP39’s 2048-word list (11 bits/word). The checksum length is 1/8 of the raw entropy.

Designed for offline, local-only key derivation — no network requests, zero configuration, no third-party cloud services. Runs on native desktop, embedded devices, hardware wallets (no_std), and WebAssembly targets. The idiom-based wordlist improves memorability, readability, and backup usability for Chinese-language users while maintaining a self-contained, locally-controlled mnemonic system.

Quick Start

use fci4096::{generate, IdiomMnemonicSize};

// Generate a 12-idiom mnemonic (128 bits of entropy)
let mnemonic = generate(IdiomMnemonicSize::Idioms12).unwrap();
println!("{}", mnemonic.phrase());

// Derive a 64-byte seed via PBKDF2-SHA512
let seed = mnemonic.to_seed("my_passphrase");

Core Parameters

Parameter	Value
Wordlist size	4096 (2¹²)
Bits per idiom	12
Idiom length	4 Chinese characters (uniform)
Checksum ratio	1/8 of entropy length
Seed derivation	PBKDF2-HMAC-SHA512
Default iterations	4096 (BIP39 uses 2048)
Lookup complexity	O(log N) binary search
Index storage	Vec<u16> (2 bytes/idiom)
Supported entropy	128 / 160 / 192 / 224 / 256 bits
Supported word counts	12 / 15 / 18 / 21 / 24 idioms

Entropy & Word Count Mapping

Idioms	Entropy	Checksum	Total Bits
12	128	16	144
15	160	20	180
18	192	24	216
21	224	28	252
24	256	32	288

Feature Flags

Feature	Default	Description
std	Yes	Standard library support
rand	Yes	OS random source for entropy generation (via getrandom)
serde	No	Serialize / Deserialize for IdiomMnemonic
wasm	No	WebAssembly bindings (auto-enables rand)

Modules

• entropy — Bit-level encoding/decoding: entropy ↔ idiom indices, SHA-256 checksum.
• mnemonic — Core IdiomMnemonic type and IdiomMnemonicSize enum.
• seed — PBKDF2-HMAC-SHA512 seed derivation with NFKD normalization.
• idiom_list — Compile-time validated 4096-idiom wordlist with O(log N) binary search.
• error — Error enum (Error) and Result alias.

Top-level API

Function	Description
generate	Generate a random mnemonic from OS entropy source
from_entropy	Build a mnemonic from raw entropy bytes
from_phrase	Parse & validate a space-separated idiom phrase
validate	Check phrase validity (wordlist + checksum)
idiom_to_index	Binary-search an idiom’s index (O(log N))
index_to_idiom	Look up an idiom by index (O(1))
get_pinyin	Get the pinyin of an idiom by index
IDIOM_COUNT	Constant: total idiom count (4096)

Runtime Characteristics

• Offline: All operations are local; zero network I/O.
• Lightweight: No heavy dependencies; core stack is sha2 + pbkdf2 + hmac.
• no_std compatible: Usable on bare-metal embedded devices and hardware wallets.
• WASM ready: Enable the wasm feature for browser-based key derivation.
• Low latency: O(log N) idiom lookup via Unicode-codepoint-sorted binary search array.

Re-exports

pub use crate::error::Error;

pub use crate::error::Result;

pub use crate::idiom_list::ChineseIdiomList;

pub use crate::mnemonic::IdiomMnemonic;

pub use crate::mnemonic::IdiomMnemonicSize;

pub use crate::seed::PBKDF2_ITERATIONS;

Modules

entropy

Bit-level entropy encoding/decoding: entropy ↔ idiom index conversion, SHA-256 checksum calculation, and OS random entropy generation.

error

Error enum (Error) and Result type alias for all fallible operations.

idiom_list

Compile-time validated 4096-idiom wordlist with O(log N) Unicode-codepoint binary search and pinyin lookup.

mnemonic

Core mnemonic types: IdiomMnemonic and IdiomMnemonicSize.

seed

Seed derivation via PBKDF2-HMAC-SHA512 with NFKD Unicode normalization.

Constants

IDIOM_COUNT

Total number of idioms in the wordlist, fixed at 4096 (2¹²). Each idiom encodes 12 bits of entropy.

Functions

from_entropy

Build a mnemonic from raw entropy bytes.

from_phrase

Parse and validate a mnemonic from a space-separated idiom phrase.

generate

Generate a cryptographically secure random mnemonic from the OS entropy source.

get_pinyin

Get the pinyin (romanization) of an idiom by its index.

idiom_to_index

Look up an idiom’s 0-based index in the wordlist via binary search.

index_to_idiom

Look up an idiom by its 0-based index (direct array access, O(1)).

validate

Validate a mnemonic phrase without constructing an IdiomMnemonic.