Blockchain Kit SDK - Global Architecture

This document provides comprehensive architecture diagrams for the Blockchain Kit SDK KMP project. Each diagram is stored as a separate .mermaid file in diagrams/ for reuse and rendering flexibility.

Table of Contents

1. High-Level Overview
2. Flutter Layer
3. Blockchain Services
4. MPC & Signing
5. Bluetooth/BLE Protocol
6. Backup & Recovery
7. Passkey & WebAuthn
8. Storage Layer
9. Data Flow Diagrams

---

1. High-Level Overview

Three-tier architecture: Platform Consumers → KMP Core SDK → Platform Implementations + External Dependencies.

View interactive diagram →

Layer	Responsibility
Platform Consumers	iOS (Swift), Android (Kotlin), Flutter (Dart)
Flutter Plugin	Generated Dart API, MethodChannel/EventChannel bridge
KMP Core	Business logic, cross-platform services, expect/actual
Platform Implementations	CredentialManager (Android), ASAuthorization (iOS), Keychain, EncryptedPrefs
External Dependencies	WalletCore (address/tx), MPC SDK (Rust/UniFFI), Kable (BLE), Ktor (HTTP)
Backend Services	Guardian MPC Server, Guardian Recovery API, Blockchain RPC Nodes

---

2. Flutter Layer

The Flutter plugin wraps the KMP SDK via MethodChannel/EventChannel with auto-generated Dart models.

View interactive diagram →

State Management: InheritedNotifier + ChangeNotifier (zero external dependencies)

Navigation Flow:

• AuthPage checks hasBackup() / hasWalletInHotStorage() → routes accordingly
• First-time users: WalletSetupPage → BackupSetupPage → BleSetupPage (2of3) or HomePage (2of2)
• Returning users: LoginPage → credential auth → HomePage

---

3. Blockchain Services

Clean abstraction layer with pluggable chain implementations (currently EVM).

View interactive diagram →

Key Design Decisions:

• BlockchainSdkService is chain-agnostic — delegates to EvmBlockchainService
• On-demand address derivation via getAddress(asset, groupId) — no stored addresses
• Transaction status tracking via StateFlow with polling
• PlatformHttpClientFactory (expect/actual) — Ktor Darwin on iOS, OkHttp on Android

---

4. MPC & Signing

Multi-Party Computation layer providing 2-of-2 (local) and 2-of-3 (BLE) signing flows.

View interactive diagram →

Security Properties:

• PresignMaterial is consumed after signing (prevents replay)
• MPC keys never leave the device in plaintext
• 2-of-3 requires physical BLE device for signing
• MpcProgressTracker provides real-time StateFlow updates

Signing Comparison:

Aspect	2-of-2	2-of-3
Key material	KeygenResult	DkgResult
Signing	Local MPC	BLE + MPC Orchestrator
Presign	MpcKmpClient.presign()	BleHwTransport rounds
Devices	Mobile only	Mobile + AC device

---

5. Bluetooth/BLE Protocol

Half-duplex BLE transport with IDCP framing for MPC protocol communication.

View interactive diagram →

IDCP Frame Layers:

• Layer 0 — Fragmentation: 488-byte segment splitting
• Layer 1 — IDCP Framing: Magic ?##, encryption type, reassembly
• Layer 2 — MPC Frames: TssMessage protobuf payloads

State Machines:

• Connection: DISCONNECTED → SCANNING → CONNECTING → CONNECTED
• Protocol: IDLE → IDENTITY_EXCHANGE → DKG → PRESIGN → SIGN → COMPLETE
• Transport: IDLE ↔ AWAITING_RESPONSE (half-duplex)

---

6. Backup & Recovery

V3 backup bundle format with multi-wrapper support and DEK/KEK envelope encryption.

View Backup diagram → | View Recovery diagram →

Encryption Design:

• DEK (Data Encryption Key): Random 32 bytes, encrypts wallet shares with AES-256-GCM
• KEK (Key Encryption Key): Derived from credential (PRF/PIN/Password), wraps DEK
• Multi-wrapper: Same encrypted data, multiple KEK wrappers → multiple recovery paths

Wrapper Types:

Wrapper	KEK Derivation	Use Case
AllPasskeys	PRF extension output → HKDF	Primary, hardware-backed
SpecificPasskey	PRF extension output → HKDF	Explicit passkey selection
GuardianGatedEscrow.NoGate	Random KEK escrow/retrieve	Assisted recovery (NoGate)
Pin	PBKDF2-SHA256	User-friendly fallback
Password	PBKDF2-SHA256	Strong passphrase option
None	No encryption	Development only

---

7. Passkey & WebAuthn

Cross-platform passkey support with PRF extension for cryptographic key derivation.

View interactive diagram →

Platform Support:

Feature	Android	iOS
Passkey API	CredentialManager (14+)	ASAuthorizationController
PRF Extension	API 34+	iOS 18+
Implementation	PasskeyManager.android.kt	PasskeyManager.ios.kt

PRF Flow: Registration creates credential with PRF salt → Authentication returns 32-byte PRF output → HKDF derives KEK → KEK wraps/unwraps DEK isPrfSupported() is platform-gated via isPrfSupportedPlatform() (Android API 34+, iOS 18+).

---

8. Storage Layer

Secure storage using platform-native encrypted stores with a common KeyValueStorageInterface.

View interactive diagram →

Platform Storage:

Platform	Implementation	Backing
Android	EncryptedSharedPreferences	Android Keystore (hardware-backed)
iOS	Keychain Services	Secure Enclave (if available)

Data Categories:

• Hot Storage: MPC key material (KeygenResult, DkgResult, PresignMaterial)
• Credential Storage: Passkey credential metadata (credentialId, prfCapable, transports)
• Backup Storage: Encrypted V3 bundles in iCloud / Google Backup / local file

---

9. Data Flow Diagrams

9.1 Wallet Creation (2-of-2)

Local MPC keygen → store → backup.

View interactive diagram →

9.2 Wallet Creation (2-of-3 with BLE)

Group creation → BLE scan+auto-connect → identity exchange → DKG → backup.

View interactive diagram →

9.3 Transaction Signing (2-of-2)

PreImage → local MPC presign + sign → WalletCore compile → broadcast.

View interactive diagram →

9.4 Backup Restore

Load bundle → PRF authentication → HKDF → unwrap DEK → decrypt wallets → restore to storage.

View interactive diagram →

---

Summary

Layer	Responsibility
Flutter	UI, state management, platform communication
KMP Core	Business logic, cross-platform services
Blockchain	EVM operations, RPC, transaction building
MPC	Key generation, signing protocols (2-of-2, 2-of-3)
Bluetooth	BLE transport, IDCP protocol, half-duplex state machine
Backup	Multi-wrapper encryption, cloud storage, V3 bundles
Passkey	WebAuthn, PRF extension, credential management
Storage	Secure key material, credentials, platform-native encryption

Key Architectural Patterns:

• expect/actual for platform-specific implementations
• Lazy initialization for services and clients
• Half-duplex state machine for BLE protocol
• DEK/KEK envelope encryption for backup security
• Result<T> error handling with safe runCatchingResult
• On-demand address derivation for multi-chain flexibility