Architecture

Knight Shield is a TypeScript monorepo built with Turbo and pnpm workspaces. Each package has a clear responsibility and well-defined interfaces.

Package Dependency Graph

mobile (React Native app)
  ├── core (wallet + ghost features)
  │     └── @midnight-ntwrk/* (Midnight SDK)
  ├── native-bridges (iOS/Android secure storage)
  └── relay-server (TLS proxy — runs separately)

contracts (Compact smart contracts — compiled independently)

Data Flow

Standard Transaction

User → Mobile App → KnightShieldWallet → TransferHelper
  → WalletFacade (Midnight SDK) → Midnight Node

Ghost Cloak Transaction

User → Mobile App → GhostCloakClient → TLS Relay Server
  → WebSocket Proxy → Midnight Node

The relay server decouples the user's IP from the Midnight node connection. Each session gets a unique sessionId, and the relay proxies all requests without logging content.

Ghost Shard Backup

User → GhostShardManager → Shamir split (5 shares, threshold 3)
  → ShardRegistry contract (on-chain hash + storage type)
  → Storage locations (DID, USB, password manager, email, cloud, device)

Package Details

core/

The wallet SDK. Exports KnightShieldWallet, TransferHelper, TokenRegistry, and the three Ghost feature clients. All classes are designed for tree-shaking — import only what you need.

Key design decisions:

• HD wallet derivation with three roles: Zswap, Dust, NightExternal
• WalletFacade pattern from @midnight-ntwrk/wallet
• Seed wiping via Uint8Array.fill(0) before shutdown

contracts/

Five Compact smart contracts compiled to JS bindings + ZK proving keys + ZKIR:

• SessionBilling — relay usage billing
• FeePool — fee normalization pool for GhostTracking
• ShardRegistry — on-chain shard hash verification
• FeeReserve — admin reserve for fee subsidies
• FungibleToken — generic token with mint/burn/transfer

native-bridges/

Platform-specific secure storage:

• iOS: SecureEnclave via Keychain + memset_s for memory wiping
• Android: AES-256-GCM via AndroidKeyStore + Arrays.fill for memory wiping

relay-server/

Node.js WebSocket server with TLS. Proxies connections to the Midnight node with session management and health monitoring. Runs as a standalone Docker container.

mobile/

React Native bare workflow app with 7 screens:

• Dashboard, Send, Receive
• GhostCloak, GhostTracking, GhostShard
• Settings

Uses WalletContext and GhostContext for state management.

Build Pipeline

turbo run build

Turbo resolves the dependency graph automatically:

1. contracts — compile Compact to JS bindings
2. core — TypeScript compilation
3. relay-server — TypeScript compilation
4. native-bridges — no build step (native code)
5. mobile — Metro bundler (dev only)
6. docs — Docusaurus build