Lux Wallet

Overview

Lux Wallet is a multi-platform HD wallet application built as a Yarn Berry monorepo (@luxwallet/monorepo v1.0.0). It ships Desktop (Electron), Web, Mobile (iOS/Android), and Browser Extension from a single TypeScript codebase. Fork of OneKey v5, extensively customized with @luxfi/* packages for Lux Network integration, supporting 27 blockchain families and hardware wallet signing.

Quick Reference

Architecture

@luxwallet/monorepo
|
+-- apps/
|   +-- ext/           @luxwallet/x v0.92.79  (Chrome/Firefox/Safari extension)
|   +-- desktop/       @onekeyhq/desktop      (Electron 27)
|   +-- mobile/        @onekeyhq/mobile       (React Native + Expo)
|   +-- web/           @onekeyhq/web          (SPA, webpack, port 3000)
|   +-- web-embed/     @onekeyhq/web-embed    (Embedded webview, port 3008)
|
+-- packages/
    +-- core/          @onekeyhq/core          (Chain APIs, crypto, HD derivation)
    +-- kit/           @onekeyhq/kit           (UI views, Redux state, navigation)
    +-- kit-bg/        @onekeyhq/kit-bg        (Background services, vaults, DB)
    +-- shared/        @onekeyhq/shared        (Constants, config, utils, platform)
    +-- components/    @onekeyhq/components    (Tamagui UI component library)
    +-- qr-wallet-sdk/ @onekeyhq/qr-wallet-sdk (Air-gapped QR signing, Keystone)

Layer Diagram

+---------------------------------------------------------+
|                    App Layer (apps/*)                     |
|   ext | desktop | mobile | web | web-embed              |
+---------------------------------------------------------+
|                    UI Layer (packages/kit)                |
|   Views: Home, Send, Receive, Swap, Staking, DApp, ...  |
|   State: Redux Toolkit + jotai + redux-persist           |
+---------------------------------------------------------+
|              Background Layer (packages/kit-bg)          |
|   Services: 40+ background services                     |
|   Vaults:   Per-chain keyring + vault implementations    |
|   DB:       IndexedDB (web) / Realm (native)            |
+---------------------------------------------------------+
|              Core Layer (packages/core)                  |
|   Chains:   27 chain implementations                    |
|   Secret:   BIP-32/39/340, AES-256-CBC, curves          |
|   Base:     CoreChainApiBase, ChainSigner               |
+---------------------------------------------------------+
|              Shared Layer (packages/shared)              |
|   Config, constants, preset networks, platform env      |
+---------------------------------------------------------+

Core Concepts

HD Key Derivation

The wallet implements BIP-32 (SLIP-0010 variant) hierarchical deterministic key derivation with three elliptic curves:

Key derivation flow:

Mnemonic (BIP-39, English wordlist)
    |
    v
mnemonicToSeedSync(mnemonic, passphrase?)  -- 512-bit seed
    |
    v
HMAC-SHA512(curve_seed_key, seed)  -- master key + chain code
    |
    v
CKDPriv(parent, index)  -- child key derivation
    |                       hardened: index  >= 2^31
    |                       ed25519: hardened only (SLIP-0010)
    v
Per-chain address generation

Master key generation follows SLIP-0010 retry logic: if the derived key is invalid ( >= group order or zero), re-derive using HMAC-SHA512(key, I) recursively.

Entropy storage: Mnemonic entropy is stored with a 2-byte prefix (language code + length) padded to 32 bytes with random data, then encrypted. Supports 12/15/18/21/24-word mnemonics (entropy lengths 16/20/24/28/32 bytes).

BIP Path Templates by Chain

Supported Chains (27 Families)

Production-enabled chain implementations with vault + keyring + core API:

EVM networks include: Ethereum, Lux C-Chain, BSC, Polygon, Arbitrum, Optimism, Fantom, Mantle, Manta Pacific, Blast, and many more via the preset networks configuration.

Key Management and Encryption

At-rest encryption: All private keys and seed material are encrypted with AES-256-CBC before storage.

Encryption: AES-256-CBC
KDF:        PBKDF2-HMAC-SHA256 (5000 iterations, 32-byte salt)
Key length: 256-bit (32 bytes)
IV:         128-bit (16 bytes, random per encrypt)
Storage:    salt(32) || iv(16) || ciphertext

Password encoding: Passwords are never passed as raw strings in non-production builds. A SENSITIVE_ENCODE prefix mechanism encrypts passwords with a per-session random key (UUID-based) so they cannot be read from debugger breakpoints.

Credential types:

• |RP| prefix: HD credential (recovery phrase -- encrypted \{entropyWithLangPrefixed, seed\} JSON)
• |PK| prefix: Imported credential (encrypted \{privateKey\} JSON)
• |VS| prefix: Verify string (encrypted known plaintext for password verification)

Additional encryptors:

• RSA (1024-bit, PKCS8) for inter-process secure key exchange
• BIP-340 Schnorr (Taproot tagged hashes: TapLeaf, TapBranch, TapSighash, TapTweak)

Keyring Architecture

Each chain vault has 6 keyring types:

All keyrings implement:

• prepareAccounts() -- derive or import accounts
• signTransaction() -- sign and return ISignedTxPro
• signMessage() -- sign arbitrary messages
• getPrivateKeys() / exportAccountSecretKeys() (HD/imported only)

Hardware Wallet Integration

Hardware support via @onekeyfe/hd-core v1.0.3 SDK:

Hardware signing flow (EVM example):

1. KeyringHardware.signTransaction() gets SDK instance and account path
2. Encodes transaction as EVMTransaction or EVMTransactionEIP1559
3. Calls sdk.evmSignTransaction(connectId, deviceId, \{path, transaction\})
4. Receives \{v, r, s\} signature from device
5. buildSignedTxFromSignatureEvm() assembles and serializes the signed tx
6. Returns \{txid, rawTx, encodedTx\}

Transaction Building

The wallet uses a typed transaction system:

IUnsignedTxPro = {
  encodedTx: IEncodedTx;     // Chain-specific encoded transaction
  feeInfo?: IFeeInfoUnit;    // Gas/fee estimation
  swapInfo?: ISwapTxInfo;    // DEX swap metadata
  stakingInfo?: IStakingInfo; // Staking operation metadata
  transfersInfo?: ITransferInfo[];
}

ISignedTxPro = {
  txid: string;
  rawTx: string;
  encodedTx: IEncodedTx | null;
  signature?: string;
  publicKey?: string;
}

Each chain's CoreChainSoftware handles:

1. packUnsignedTxForSign() -- serialize tx to signing digest
2. signer.sign(digest) -- ECDSA/EdDSA signature with recovery
3. buildSignedTx() -- attach signature, compute txid

DApp Connection

The wallet supports DApp interaction via:

• Injected provider: @onekeyfe/cross-inpage-provider-* packages inject window.ethereum (EVM), window.solana, etc.
• WalletConnect v2: @walletconnect/universal-provider v2.11.2, @walletconnect/web3wallet v1.10.2
• Coinbase Wallet SDK: @coinbase/wallet-sdk v3.8.x
• Gnosis Safe: @gnosis.pm/safe-core-sdk v1.1.1, @luxfi/eth-gnosis-keyring v0.0.2

The ServiceDApp (946 lines) manages connection lifecycle, permission grants, and method routing.

Database Layer

Account types stored:

• SIMPLE -- single address (EVM, SOL, etc.)
• UTXO -- multi-address (BTC, DOGE, LTC, BCH)
• VARIANT -- address varies by network (Cosmos, NEAR)

Store names include: Wallet, Account, Device, Credential, SignedMessage, SignedTransaction, ConnectedSite, and more.

Lux-Specific Packages

The browser extension (apps/ext) uses @luxfi/* packages for Lux Network integration:

Platforms

Background Services (40+)

Key services in packages/kit-bg/src/services/:

UI Views

Primary views in packages/kit/src/views/:

Home | Send | Receive | Swap | Staking | Market | Discovery (DApp browser) | AssetList | AssetDetails | AccountManagerStacks | Setting | Onboarding | FirmwareUpdate | LightningNetwork | ScanQrCode | AddressBook | FiatCrypto | CloudBackup | KeyTag | LiteCard | UniversalSearch

Development

# Install (requires Node  >= 20, git-lfs)
yarn

# Development
yarn app:web              # Web on port 3000
yarn app:ext              # Browser extension (MV3 dev build)
yarn app:desktop          # Electron desktop
yarn app:ios              # iOS via USB
yarn app:android          # Android

# Building
yarn app:ext:build        # Production extension
yarn app:web:build        # Production web

# Testing
yarn test                 # Jest test suite

# Linting
yarn lint                 # TSC + ESLint + folder lint + i18n check

# Clean
yarn clean                # Full workspace clean
yarn reinstall            # Clean + install

Security Model

1. Mnemonic never stored in plaintext -- encrypted as IBip39RevealableSeed with AES-256-CBC
2. Private keys encrypted at rest -- PBKDF2 KDF with 5000 iterations
3. Password verification -- encrypted known string (DEFAULT_VERIFY_STRING) used to check password correctness without storing the password
4. Session encoding -- passwords encoded with per-session random key to prevent debugger interception
5. Extension isolation -- decodePassword() throws if called from extension UI process (must use background)
6. Hardware signing -- private keys never leave the hardware device
7. QR air-gap -- Keystone SDK for fully offline signing via animated QR codes

Patches

15 patch-package patches maintained in /patches/:

• @kaspa/core-lib, coinselect (UTXO selection fix)
• @tamagui/animate, @tamagui/switch (UI fixes)
• @walletconnect/modal-react-native (RN compat)
• react-native-* (various RN fixes)
• expo-camera, metro (build fixes)
• protobufjs (serialization fix)

Related Skills

• lux/lux-crypto.md -- Cryptographic primitives and curves
• lux/lux-safe.md -- Multisig wallets (Gnosis Safe fork)
• lux/lux-sdk.md -- Go SDK wallet utilities
• lux/lux-ledger.md -- Ledger hardware integration