# control-owl/eq architecture

> Architecture diagram of the GitHub repository control-owl/eq, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/control-owl/eq
- Repository: https://github.com/control-owl/eq

## Overview

#### 1. Purpose and executable boundary
eQ is a native Rust desktop application for generating cryptocurrency wallets/keys across 284 coins. Its executable entry point is `src/main.rs`; reusable application modules are exposed through `src/lib.rs`. The UI is built with `egui`/`eframe`, not a web service.

#### 2. Application/UI orchestration
The desktop event loop, user selections, generation actions, wallet presentation, file-save interactions, and optional on-screen keyboard are expected to be coordinated at the application layer in:
- `src/main.rs`
- `src/lib.rs`
- `src/dev.rs`

This is the main trust boundary: user-entered passphrases and generated secrets must remain in-process and be cleared after use.

#### 3. Key-generation and derivation core
Cryptographic generation and coin-specific key/address derivation are concentrated in:
- `src/keys.rs`
- `src/crypt.rs`
- `src/test_vectors.rs`

The core supports secp256k1 and ed25519 ecosystems plus BIP32/BIP39/BIP44 and BIP86 paths. Entropy feeds mnemonic/private-key material; derivation produces coin-specific keys and encoded addresses. `src/test_vectors.rs` provides deterministic reference material for validating this sensitive pipeline.

#### 4. Entropy sources and network boundary
Normal generation uses local/system randomness and is designed to work offline. An optional entropy path requests quantum randomness from the external ANU QRNG service via HTTP (`ureq`), creating the repository’s principal runtime network boundary. Crypto/entropy handling belongs in:
- `src/crypt.rs`
- `src/keys.rs`

External QRNG input should be treated as supplemental untrusted transport data until validated, while no wallet-generation dependency should require network availability.

#### 5. Wallet protection and export
Generated wallet information is serialized into SVG-based wallet artifacts, encrypted with AES-256-GCM, and can optionally be split using Shamir secret sharing. The relevant encryption/export implementation is likely split between:
- `src/crypt.rs`
- `src/keys.rs`
- `res/doc/wallet.md`

The UI/file-dialog layer selects the destination, while cryptographic code owns encryption, secret handling, and zeroization. Exported SVG is the durable boundary; plaintext keys should not cross it.

#### 6. Embedded coin and language data
Coin definitions and assets are repository resources rather than an online catalog:
- `res/coin/ECDB.csv`
- `res/wordlists/english.txt`
- `res/wordlists/japanese.txt`

Build-time/resource embedding is configured by `build.rs`, likely together with `include_dir`. BIP39 language wordlists and coin metadata flow into the derivation/UI layers, enabling offline operation and multi-language mnemonic support.

#### 7. Runtime, packaging, and release infrastructure
The material runtime is a cross-platform native Rust binary: Windows, Linux, and macOS. Cargo defines crate features/dependencies in `Cargo.toml`; Windows-specific application metadata is under `res/app.manifest` and likely incorporated by `build.rs`. Platform release artifacts are built by:
- `.github/workflows/release-linux-gnu.yml`
- `.github/workflows/release-macos-aarch64.yml`
- `.github/workflows/release-windows_x86_64.yml`

Release integrity also includes GPG-signature verification in `.github/workflows/verify-gpg-signature.yml`.

Main entry points: [`src/keys.rs`](https://github.com/control-owl/eq/blob/stable/src/keys.rs) (Key derivation), [`src/lib.rs`](https://github.com/control-owl/eq/blob/stable/src/lib.rs) (Application modules), [`build.rs`](https://github.com/control-owl/eq/blob/stable/build.rs) (Resource embedding), [`src/crypt.rs`](https://github.com/control-owl/eq/blob/stable/src/crypt.rs) (Entropy and protection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop application"]
  node_main["Native executable<br/>Rust entry point<br/>[main.rs]"]
  node_lib["Application modules<br/>Rust library<br/>[lib.rs]"]
  node_dev["On-screen keyboard<br/>UI module<br/>[dev.rs]"]
  node_file_export["Save destination<br/>desktop file dialog"]
end

subgraph group_core["Wallet core"]
  node_keys{{"Key derivation<br/>wallet derivation<br/>[keys.rs]"}}
  node_crypt{{"Entropy and protection<br/>crypto module<br/>[crypt.rs]"}}
  node_vectors["Deterministic vectors<br/>reference data<br/>[test_vectors.rs]"]
  node_wallet_doc["Wallet export format<br/>documentation<br/>[wallet.md]"]
end

subgraph group_resources["Embedded offline data"]
  node_coin_db[("Coin definitions<br/>embedded CSV<br/>[ECDB.csv]")]
  node_english_words["English wordlist<br/>embedded BIP39 data<br/>[english.txt]"]
  node_japanese_words["Japanese wordlist<br/>embedded BIP39 data<br/>[japanese.txt]"]
end

subgraph group_release["Build and release"]
  node_build["Resource embedding<br/>build script<br/>[build.rs]"]
  node_cargo["Crate definition<br/>Cargo manifest<br/>[Cargo.toml]"]
  node_manifest["Windows metadata<br/>application manifest<br/>[app.manifest]"]
  node_linux_release["Linux release build<br/>GitHub Actions workflow"]
  node_macos_release["macOS release build<br/>GitHub Actions workflow"]
  node_windows_release["Windows release build<br/>GitHub Actions workflow"]
  node_gpg_verify["GPG verification<br/>GitHub Actions workflow"]
end

node_qrng(("ANU QRNG<br/>external HTTP service"))
node_wallet_svg["Encrypted wallet SVG<br/>export artifact"]

node_main -->|"runs"| node_lib
node_lib -->|"optional keyboard"| node_dev
node_lib -->|"generation actions"| node_keys
node_lib -->|"protects secrets"| node_crypt
node_lib -->|"selects destination"| node_file_export
node_keys -->|"entropy and encryption"| node_crypt
node_crypt -.->|"optional HTTP entropy"| node_qrng
node_keys -->|"coin parameters"| node_coin_db
node_keys -->|"BIP39 mnemonics"| node_english_words
node_keys -->|"BIP39 mnemonics"| node_japanese_words
node_vectors -.->|"validates derivation"| node_keys
node_crypt -->|"AES-256-GCM export"| node_wallet_svg
node_keys -->|"serialized wallet data"| node_wallet_svg
node_file_export -->|"writes"| node_wallet_svg
node_wallet_doc -.->|"documents"| node_wallet_svg
node_build -->|"embeds"| node_coin_db
node_build -->|"embeds"| node_english_words
node_build -->|"embeds"| node_japanese_words
node_build -->|"incorporates"| node_manifest
node_cargo -->|"builds binary"| node_main
node_linux_release -->|"builds"| node_cargo
node_macos_release -->|"builds"| node_cargo
node_windows_release -->|"builds"| node_cargo
node_gpg_verify -.->|"verifies releases"| node_linux_release
node_gpg_verify -.->|"verifies releases"| node_macos_release
node_gpg_verify -.->|"verifies releases"| node_windows_release

click node_main "https://github.com/control-owl/eq/blob/stable/src/main.rs"
click node_lib "https://github.com/control-owl/eq/blob/stable/src/lib.rs"
click node_dev "https://github.com/control-owl/eq/blob/stable/src/dev.rs"
click node_keys "https://github.com/control-owl/eq/blob/stable/src/keys.rs"
click node_crypt "https://github.com/control-owl/eq/blob/stable/src/crypt.rs"
click node_vectors "https://github.com/control-owl/eq/blob/stable/src/test_vectors.rs"
click node_wallet_doc "https://github.com/control-owl/eq/blob/stable/res/doc/wallet.md"
click node_coin_db "https://github.com/control-owl/eq/blob/stable/res/coin/ECDB.csv"
click node_english_words "https://github.com/control-owl/eq/blob/stable/res/wordlists/english.txt"
click node_japanese_words "https://github.com/control-owl/eq/blob/stable/res/wordlists/japanese.txt"
click node_build "https://github.com/control-owl/eq/blob/stable/build.rs"
click node_cargo "https://github.com/control-owl/eq/blob/stable/Cargo.toml"
click node_manifest "https://github.com/control-owl/eq/blob/stable/res/app.manifest"
click node_linux_release "https://github.com/control-owl/eq/blob/stable/.github/workflows/release-linux-gnu.yml"
click node_macos_release "https://github.com/control-owl/eq/blob/stable/.github/workflows/release-macos-aarch64.yml"
click node_windows_release "https://github.com/control-owl/eq/blob/stable/.github/workflows/release-windows_x86_64.yml"
click node_gpg_verify "https://github.com/control-owl/eq/blob/stable/.github/workflows/verify-gpg-signature.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_lib,node_dev,node_file_export toneBlue
class node_keys,node_crypt,node_vectors,node_wallet_doc toneAmber
class node_coin_db,node_english_words,node_japanese_words toneMint
class node_build,node_cargo,node_manifest,node_linux_release,node_macos_release,node_windows_release,node_gpg_verify toneRose
class node_qrng,node_wallet_svg toneNeutral
```

## Components

### Desktop application

- [Native executable](https://github.com/control-owl/eq/blob/stable/src/main.rs): Rust entry point · Starts the eframe desktop event loop. · `src/main.rs`
- [Application modules](https://github.com/control-owl/eq/blob/stable/src/lib.rs): Rust library · Coordinates UI actions, secret lifecycle, and wallet presentation. · `src/lib.rs`
- [On-screen keyboard](https://github.com/control-owl/eq/blob/stable/src/dev.rs): UI module · `src/dev.rs`
- **Save destination**: desktop file dialog · Chooses the durable export location.

### Wallet core

- [Key derivation](https://github.com/control-owl/eq/blob/stable/src/keys.rs): wallet derivation · Builds coin-specific keys and addresses across BIP paths. · `src/keys.rs`
- [Entropy and protection](https://github.com/control-owl/eq/blob/stable/src/crypt.rs): crypto module · Handles local entropy, QRNG validation, encryption, and zeroization. · `src/crypt.rs`
- [Deterministic vectors](https://github.com/control-owl/eq/blob/stable/src/test_vectors.rs): reference data · Validates sensitive generation and derivation behavior. · `src/test_vectors.rs`
- [Wallet export format](https://github.com/control-owl/eq/blob/stable/res/doc/wallet.md): documentation · `res/doc/wallet.md`

### Embedded offline data

- [Coin definitions](https://github.com/control-owl/eq/blob/stable/res/coin/ECDB.csv): embedded CSV · Offline metadata for supported coins. · `res/coin/ECDB.csv`
- [English wordlist](https://github.com/control-owl/eq/blob/stable/res/wordlists/english.txt): embedded BIP39 data · `res/wordlists/english.txt`
- [Japanese wordlist](https://github.com/control-owl/eq/blob/stable/res/wordlists/japanese.txt): embedded BIP39 data · `res/wordlists/japanese.txt`

### Build and release

- [Resource embedding](https://github.com/control-owl/eq/blob/stable/build.rs): build script · Embeds application resources and Windows metadata. · `build.rs`
- [Crate definition](https://github.com/control-owl/eq/blob/stable/Cargo.toml): Cargo manifest · Defines Rust dependencies and feature selection. · `Cargo.toml`
- [Windows metadata](https://github.com/control-owl/eq/blob/stable/res/app.manifest): application manifest · `res/app.manifest`
- [Linux release build](https://github.com/control-owl/eq/blob/stable/.github/workflows/release-linux-gnu.yml): GitHub Actions workflow · `.github/workflows/release-linux-gnu.yml`
- [macOS release build](https://github.com/control-owl/eq/blob/stable/.github/workflows/release-macos-aarch64.yml): GitHub Actions workflow · `.github/workflows/release-macos-aarch64.yml`
- [Windows release build](https://github.com/control-owl/eq/blob/stable/.github/workflows/release-windows_x86_64.yml): GitHub Actions workflow · `.github/workflows/release-windows_x86_64.yml`
- [GPG verification](https://github.com/control-owl/eq/blob/stable/.github/workflows/verify-gpg-signature.yml): GitHub Actions workflow · Verifies release integrity signatures. · `.github/workflows/verify-gpg-signature.yml`

### Other components

- **ANU QRNG**: external HTTP service · Optional supplemental quantum-randomness source.
- **Encrypted wallet SVG**: export artifact · Durable wallet artifact; plaintext keys must not cross this boundary.

## Connections

- Native executable → Application modules: runs
- Application modules → On-screen keyboard: optional keyboard
- Application modules → Key derivation: generation actions
- Application modules → Entropy and protection: protects secrets
- Application modules → Save destination: selects destination
- Key derivation → Entropy and protection: entropy and encryption
- Entropy and protection → ANU QRNG: optional HTTP entropy
- Key derivation → Coin definitions: coin parameters
- Key derivation → English wordlist: BIP39 mnemonics
- Key derivation → Japanese wordlist: BIP39 mnemonics
- Deterministic vectors → Key derivation: validates derivation
- Entropy and protection → Encrypted wallet SVG: AES-256-GCM export
- Key derivation → Encrypted wallet SVG: serialized wallet data
- Save destination → Encrypted wallet SVG: writes
- Wallet export format → Encrypted wallet SVG: documents
- Resource embedding → Coin definitions: embeds
- Resource embedding → English wordlist: embeds
- Resource embedding → Japanese wordlist: embeds
- Resource embedding → Windows metadata: incorporates
- Crate definition → Native executable: builds binary
- Linux release build → Crate definition: builds
- macOS release build → Crate definition: builds
- Windows release build → Crate definition: builds
- GPG verification → Linux release build: verifies releases
- GPG verification → macOS release build: verifies releases
- GPG verification → Windows release build: verifies releases