fci4096 0.1.5

BIP39-inspired mnemonic wordlist using 4096 standard Chinese four-character idioms (chengyu). 12 bits/word, SHA-256 checksum, PBKDF2-SHA512 seed derivation, no_std + WASM support, offline local-only key generation.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158

# fci4096 — Chinese Idiom Mnemonic Wordlist (成语助记词)

A BIP39-inspired mnemonic wordlist and seed-derivation library built on 4096 standard Chinese four-character idioms (成语). Offline, local-only, `no_std` + WASM compatible.

> 中文说明见下方 [中文简介](#中文简介) 章节。

## Overview

fci4096 is a mnemonic system inspired by BIP39, replacing the English word list with 4096 standard four-character Chinese idioms (chengyu). Each idiom encodes 12 bits of information (2^12 = 4096), providing higher information density than BIP39's 2048-word list (11 bits/word) for the same number of words.

**Key advantages:**

- **Offline & local-only** — zero network requests, zero configuration, no cloud services
- **`no_std` compatible** — runs on bare-metal embedded devices and hardware wallets
- **WASM ready** — browser-based key derivation via the `wasm` feature
- **Low latency** — O(log N) idiom lookup via compile-time binary search array
- **Lightweight** — core dependency stack is `sha2` + `pbkdf2` + `hmac`

### Differences from BIP39

| Feature | BIP39 | fci4096 |
|---------|-------|---------|
| Wordlist size | 2048 | 4096 |
| Bits per word | 11 | 12 |
| Entropy (12 items) | 128 bits | 128 bits |
| Checksum bits | 4 bits | 16 bits |
| Wordlist language | English | Chinese idioms |

## Encoding Scheme

With a 4096-word list, each idiom encodes 12 bits. The checksum is 1/8 of the entropy length:

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

The checksum is the leading N bits of SHA-256(entropy).

## Installation

```toml
[dependencies]
fci4096 = "0.1"
```

### Feature Flags

| Feature | Default | Description |
|---------|---------|-------------|
| `std` | Yes | Standard library support |
| `rand` | Yes | Random number generation (mnemonic generation) |
| `serde` | No | Serialize/Deserialize support |
| `wasm` | No | WASM bindings |

## Usage

### Generate a Mnemonic

```rust
use fci4096::{generate, IdiomMnemonicSize};

let mnemonic = generate(IdiomMnemonicSize::Idioms12).unwrap();
println!("{}", mnemonic.phrase());
// e.g. 哀而不伤 按部就班 草木皆兵 ...
```

### From Entropy

```rust
use fci4096::from_entropy;

let entropy = [0x00u8; 16]; // 128 bits of entropy
let mnemonic = from_entropy(&entropy).unwrap();
```

### Parse and Validate

```rust
use fci4096::{from_phrase, validate};

let phrase = "哀而不伤 按部就班 草木皆兵 ...";
if validate(phrase) {
    let mnemonic = from_phrase(phrase).unwrap();
    let entropy = mnemonic.to_entropy().unwrap();
}
```

### Generate a Seed

```rust
let seed = mnemonic.to_seed("passphrase");
// Returns [u8; 64], using PBKDF2-SHA512 with 4096 iterations
```

### CLI Examples

```bash
# Generate a 12-word mnemonic
cargo run --example generate 12

# Recover the seed
cargo run --example recover "idiom1 idiom2 idiom3 ..." [passphrase]
```

## Use Cases

- **Cryptocurrency wallets** — Chinese-localized mnemonic generation and recovery
- **Hardware wallets** — `no_std` embedded key derivation with O(log N) idiom lookup
- **Web applications** — WASM-based browser key generation without server round-trips
- **Encrypted backup systems** — Human-readable idiom phrases for offline key backup
- **Identity / DID systems** — Deterministic 64-byte seed derivation from memorable phrases

## Performance

| Metric | Value |
|--------|-------|
| Idiom lookup | O(log N) binary search (≈ 12 comparisons) |
| Index storage | 2 bytes/idiom (`Vec<u16>`) |
| Seed derivation | PBKDF2-HMAC-SHA512, 4096 iterations |
| Dependencies | `sha2` + `pbkdf2` + `hmac` + `unicode-normalization` |
| `no_std` | Yes (bare-metal, embedded, hardware wallets) |
| WASM | Yes (`wasm32` target with `getrandom/js`) |

## Security

- **Entropy source**: Uses the `getrandom` crate for OS-level cryptographically secure random numbers
- **Checksum**: 128-bit entropy with 16-bit checksum (BIP39 uses only 4 bits), providing stronger error detection
- **Seed derivation**: PBKDF2-SHA512, 4096 iterations, passphrase is NFKD-normalized
- **Wordlist**: 4096 standard four-character idioms, sorted by pinyin, systematically reviewed to remove derogatory idioms

## Documentation

- [docs.rs](https://docs.rs/fci4096) — Full API documentation with examples
- [CHANGELOG.md](CHANGELOG.md) — Version history

## 中文简介

一套借鉴 BIP39 规范、基于中文四字成语构建的密钥助记词方案，词库选用 4096 条规范标准成语。方案面向中文使用场景打造，大幅提升助记词记忆、读写与备份的本土易用性，实现自主可控的本地化助记词体系。

每条成语承载 12 比特熵信息（2¹² = 4096）；在助记词条数相同的前提下，相较原生 BIP39 的 2048 词词表（单词仅承载 11 比特）拥有更高信息密度，同等数量助记词可容纳更多随机熵，安全冗余更强。校验和长度为原始熵长度的 1/8。

**核心特性：**

- **离线本地运行** — 无网络请求，零配置，无第三方云服务
- **`no_std` 兼容** — 支持裸机嵌入式设备和硬件钱包
- **WASM 支持** — 通过 `wasm` feature 实现浏览器端密钥派生
- **低延迟** — 编译期生成的二分查找数组，O(log N) 成语查找
- **轻量级** — 核心依赖仅 `sha2` + `pbkdf2` + `hmac`

**适用场景：** 加密货币钱包（中文本地化）、硬件钱包、Web 应用、加密备份系统、身份/DID 系统。

## License

MIT