Code Map

Quick reference to key files and their responsibilities in the Blockchain Kit SDK.

Module Tier System

The SDK follows a tiered dependency architecture. Higher tiers may depend on lower tiers, but never the reverse.

TIER 3 (Facade)       sdk/          BlockchainKitSdk, MpcService, BlockchainSdkService
                          │
TIER 2 (Features)     blockchain/   EVM operations, signing, tx tracking
                      transport/    Transport abstraction (BLE, future: USB)
                          │
TIER 1 (Domain)       mpc/          Protocol orchestration (DKG, presign, sign)
                      backup/       Backup bundle, encryption, unlock strategies
                      auth/         Passkey, credential management
                          │
TIER 0 (Core)         util/         Logger, Result helpers, JSON config
                      crypto/       Encryption, hashing, key derivation
                      idcp/         Frame parsing (transport-agnostic)
                      internal/     SDK config, storage container, UniFFI init

Dependency rules:

Tier 0 has zero internal dependencies
Tier 1 depends only on Tier 0
Tier 2 depends on Tier 0 + Tier 1
Tier 3 (facade) wires everything together

Visibility rules:

@PublicApi marks classes/models intended for SDK consumers
internal marks implementation details hidden from consumers
All @FlutterModule classes are public API (Tier 3)
All @Serializable model classes used in @FlutterMethod signatures are public API

Core SDK

File	Description
`BlockchainKitSdk.kt`	Main SDK entry point with `@FlutterModule`
`MpcService.kt`	MPC submodule — transport-agnostic scan/connect/disconnect, MPC protocol orchestration, reactive `connectionInfo` stream (`@FlutterSubmodule`)
`BlockchainSdkService.kt`	Blockchain service facade (accessed via `@FlutterSubmodule`)
`platform/PlatformContext.kt`	Platform-specific context (expect/actual pattern)

Blockchain Services (`blockchain/`)

File	Description
`EvmBlockchainService.kt`	EVM query operations (balance, nonce, fee, status, broadcast, preImageHash)
`EvmSigningService.kt`	MPC signing operations (sign, signWithHw, assembleAndCompileSignedTx)
`EvmTransactionBuilder.kt`	WalletCore integration for preImageHash/signing
`EvmAbi.kt`	ERC-20 ABI encoding (balanceOf, transfer) via WalletCore
`EthereumRpcClient.kt`	EVM JSON-RPC client

Models

File	Description
`Fee.kt`	Fee sealed class hierarchy
`Asset.kt`	Asset sealed class (NativeCoin, Token)
`Transaction.kt`	Transaction sealed class (Transfer)
`Network.kt`	Network configuration model
`Balance.kt`	Balance data class with BalanceResult typealias
`Broadcast.kt`	Broadcast data class with BroadcastResult typealias
`TransactionStatus.kt`	TransactionStatus sealed class (Pending, Confirmed, Failed, NotFound)

Passkey/WebAuthn (`passkey/`)

File	Platform	Description
`PasskeyManager.kt`	commonMain	expect declaration for passkey operations
`PasskeyManager.android.kt`	androidMain	Android Credential Manager integration
`PasskeyManager.ios.kt`	iosMain	iOS AuthenticationServices integration with PRF support (iOS 18+)
`PasskeyAuthorizationController.kt`	iosMain	iOS ASAuthorizationController wrapper
`PrfSupport.kt`	commonMain	expect `isPrfSupportedPlatform()` declaration
`PrfSupport.android.kt`	androidMain	Android PRF support (API 34+)
`PrfSupport.ios.kt`	iosMain	iOS 18+ version check via `NSProcessInfo.operatingSystemVersion`
`PrfAuthResult.kt`	commonMain	PRF authentication result with credentialId, prfSecret, credentialInfo

PasskeyAuthorizationController Methods (iOS)

createAuthenticationRequestWithPrf() - Configure PRF extension on assertion request
performAuthenticationWithPrf() - Suspend function for PRF authentication
PrfAuthenticationResult - Data class holding assertion + PRF output

IDCP Frame Parsing (`idcp/frame/`)

Transport-agnostic IDCP protocol parsing, usable with BLE, WebSocket, USB, or any other transport.

File	Description
`Layer1FrameParser.kt`	Parse Layer 1 IDCP frames (magic detection, header config, size extraction)
`FrameReassembler.kt`	Reassemble fragmented frames (duplicate detection, overflow protection)
`IdcpFrameBuilder.kt`	Build Layer 1 frames for transmission (TssMessage encoding, Layer 2 wrapping)

Signing Protocol (`signing/`)

Transport-agnostic signing protocol encoders (TX25, future FROST support).

File	Description
`TssMessageEncoder.kt`	TX25 TssMessage protobuf wire format encoding
`MessageTypeRegistry.kt`	Data-driven TX25 message type resolution

Transport Abstraction (`transport/`)

Transport-agnostic interfaces for hardware device discovery, connection, and communication. All transports (BLE, future USB) implement these interfaces so MpcService and protocol code never depend on a specific transport.

File	Description
`HwTransportProvider.kt`	Interface: `scan()`, `connect(deviceId)`, `disconnect()`, `connectionState`
`HwTransport.kt`	Interface: extends `KmpHwTransport` (UniFFI) + `close()`, `deviceInfo`, `transportType`
`DeviceInfo.kt`	Transport-agnostic device model (id, name, transportType, rssi)
`TransportType.kt`	Enum: `BLUETOOTH`, `USB`
`ConnectionState.kt`	Enum: `DISCONNECTED`, `SCANNING`, `CONNECTING`, `CONNECTED`
`ConnectionInfo.kt`	Reactive state model (state, transportType, deviceInfo) — exposed via `@FlutterFlow`
`ProtocolStateMachine.kt`	Thread-safe half-duplex state machine (IDLE ↔ AWAITING_RESPONSE), moved from `bluetooth/`

BLE Transport (`bluetooth/`)

BLE-specific implementation of the transport interfaces using the Kable library.

File	Description
`BleTransportProvider.kt`	Implements `HwTransportProvider` — BLE scan/connect via Kable, peripheral state monitoring for unexpected disconnects
`BleHwTransport.kt`	Implements `HwTransport` — BLE read/write with MTU fragmentation, notification listener, write mutex
`BleTransportExecutor.kt`	Synchronous bridge for UniFFI callbacks (Rust MPC SDK expects blocking I/O)
`BleConstants.kt`	BLE protocol constants (UUIDs, MTU, timeouts, device name patterns)
`encoding/ByteArrayUtils.kt`	KMP byte manipulation (replaces JVM ByteBuffer/ByteArrayOutputStream)

MPC Protocol (`mpc/`)

File	Description
`MpcConstants.kt`	Party topology (P1=HW, P2=Server, P3=Mobile), message types
`MpcProtocolModels.kt`	IdentityExchangeResult, DkgResult, PresignResult, SignResult, MpcPhase, MpcProtocolState
`IdentityExchangeProtocol.kt`	9-step identity key exchange (AC ↔ Mobile ↔ Server)
`DkgProtocol.kt`	Threshold DKG orchestration via `keygenThresholdWithHw()`
`PresignProtocol.kt`	Threshold presign orchestration via `presignThresholdWithHw()`
`SignProtocol.kt`	Threshold sign orchestration via `signThresholdWithHw()`
`MpcProtocolOrchestrator.kt`	Facade with StateFlow progress — accepts `HwTransport` (transport-agnostic)
`P256KeyPair.kt`	expect/actual P-256 keypair generation for identity exchange

MPC Wallet Storage (`storage/`)

Unified storage for 2-of-2 and 2-of-3 MPC wallet shares with multi-algorithm support.

Architecture Note: See hot-storage-architecture.md for comprehensive architecture documentation with diagrams.

Storage Models (`MpcStorageModels.kt`)

Model	Description
`StoredWalletInfo`	Wallet-level metadata (groupId, displayName, walletType, createdAt)
`StoredDkgResult`	2-of-3 DKG result with `extendedDataBytes`, `shareBytes`, `combinedPublicKey`, `sessionId`
`StoredPresignResult`	Presign material (consumed after signing)
`StoredKeygenResult`	2-of-2 keygen result with `algorithmId`, `shareBytes`, `publicKeyBytes`
`StoredShareResult`	Sealed class: `Keygen` (2-of-2), `Dkg` (2-of-3), `Frost` (future)

MpcWalletStorage Methods

Wallet Info (metadata):

storeWalletInfo(groupId, displayName, walletType) - Store wallet metadata
loadWalletInfo(groupId) - Load wallet metadata
getDisplayName(groupId) - Get display name for a wallet

Keygen (2-of-2):

storeKeygenResult(groupId, algorithmId, shareBytes, publicKeyBytes) - Store 2-of-2 share
loadKeygenResult(groupId, algorithmId) - Load 2-of-2 share

DKG (2-of-3):

storeDkgResult(groupId, ...) - Store 2-of-3 DKG result
storeDkgResultWithAlgorithm(groupId, algorithmId, ...) - Store with algorithm suffix

Multi-algorithm:

loadAllShares(groupId) - Load all algorithm shares for backup (Map<String, StoredShareResult>)
getPublicKey(groupId, algorithmId) - Get public key for address derivation

Group management:

listGroups() - List all wallet group IDs
deleteGroup(groupId) - Delete all data for a group (shares, wallet info, index)

Storage Key Patterns

Pattern	Example	Description
`mpc_wallet_{groupId}`	`mpc_wallet_abc123`	Wallet info
`mpc_keygen_{groupId}_{algorithmId}`	`mpc_keygen_abc123_ecdsa_secp256k1`	2-of-2 share
`mpc_dkg_{groupId}_{algorithmId}`	`mpc_dkg_abc123_ecdsa_secp256k1`	2-of-3 share
`mpc_presign_{groupId}`	`mpc_presign_abc123`	Presign (consumed after signing)
`mpc_groups_index`	-	JSON array of groupIds

Wallet Backup System (`storage/backup/`)

PIN-encrypted backup system for wallet recovery. Uses V2 format with two-layer DEK/KEK encryption.

Data Models

File	Description
`BackupCredential.kt`	Sealed class for credential types (None, Pin, Password, Passkey)
`WalletBackupPayload.kt`	V2 backup format structures
`WalletRestoreResult.kt`	Restore result model (address, groupId, walletType, displayName)

WalletBackupPayload Structure

WalletBackupPayload - Root: format_version: 2, salt, ciphertext_dek, wallet, checksum
BackupMetadata - credential_type, kek_derivation, encryption, algorithms list
WalletData - groupId, displayName, walletType, address, shares: Map<AlgorithmId, String>
AlgorithmId enum - ECDSA_SECP256K1, FROST_ED25519
ShareData sealed interface - EcdsaShareData, FrostShareData

Cryptography (expect/actual)

File	Android	iOS
`KeyDerivation.kt`	`SecretKeyFactory` PBKDF2WithHmacSHA256	`CommonCrypto.CCKeyDerivationPBKDF`
`AesGcm.kt`	JCE `AES/GCM/NoPadding`	libsodium `SecretBox.easy()`
`BackupEncryption.kt`	Two-layer: DEK encrypts shares, KEK wraps DEK

Storage Providers

File	Description
`WalletBackupProvider.kt`	Interface for modular backup storage backends
`LocalFileBackupProvider.kt`	Local file storage (Android: `context.filesDir`, iOS: Documents)

Services

File	Description
`WalletBackupService.kt`	Unified backup/restore orchestration

Methods:

addWallet(groupId, displayName, walletType, credential) - Add wallet to backup
restoreWallet(credential) - Restore all wallets from backup

Shared Utilities (`util/`)

File	Description
`ResultExt.kt`	`runCatchingResult` (wraps `T` → `Result<T>`) and `resultCatching` (guards `Result<T>` blocks)
`SdkLogger.kt`	`SdkLogger` interface + `PrintSdkLogger` (stdout) + `NoOpSdkLogger` (silent)
`CurrentTimeMillis.kt`	expect/actual cross-platform timestamp

Platform Expect/Actual Summary

Declaration	Android	iOS
`currentTimeMillis()`	`System.currentTimeMillis()`	`NSDate`
`configurePeripheralBuilder()`	`requestMtu(512)`	no-op (auto-negotiated)
`generateP256KeyPair()`	`KeyPairGenerator("EC")`	`SecKeyCreateRandomKey`
`deriveKeyFromPassword()`	JCE PBKDF2WithHmacSHA256	CommonCrypto CCKeyDerivationPBKDF
`aesGcmEncrypt()`/`aesGcmDecrypt()`	JCE AES-256-GCM	libsodium SecretBox
`LocalFileBackupProvider`	`context.filesDir`	Documents directory

Build Logic (`build-logic/`)

Gradle convention plugins providing standardized configuration for KMP modules.

Module Structure

Module	Plugin ID	Description
`common`	-	Shared utilities (`pluginId()` helper function)
`kmp`	`kmpLibraryWrapper`	KMP library configuration (targets, source sets, frameworks)
`open-api`	`openApiWrapper`	OpenAPI code generation wrapper

KMP Plugin Components (`build-logic/kmp/`)

Primitives (primitives/):

File	Description
`BuildMode.kt`	`DEBUG`/`RELEASE` enum with resolution from env vars and `development.config`
`TargetPlatform.kt`	Platform combinations (AndroidOnly, IosOnly, AndroidAndSimulator, All, etc.)

Extensions (extensions/):

File	Description
`KMPLibWrapperExtension.kt`	Main DSL extension (`configureKmpLibrary { ... }`)
`ConfigurationScope.kt`	Dependency scope interface (`api`, `implementation`, `ksp`, `testImplementation`)
`AndroidConfigurationScope.kt`	Android-specific scope (adds `instrumentedTestImplementation`, etc.)
`ProjectExtensions.kt`	Extension properties for `Project` (`targetPlatform`, `buildMode`)

Configurations (configurations/):

File	Description
`ConfigureKMPKotlinExt.kt`	Kotlin multiplatform configuration (targets, source sets, XCFramework)
`ConfigureKMPAndroidExt.kt`	Android library configuration (SDK versions, packaging, test runners)

Configuration File (`development.config`)

Required file in project root controlling local builds:

# Target platform for local development
# Options: device, mac, arm64Simulator, intelX64Simulator
iTestLocallyOnAndroidAnd=arm64Simulator

# Build mode: debug or release
buildMode=debug

Environment Variable Overrides

Variable	Values	Description
`TARGET_PLATFORM`	`Android`, `Ios`, `IosArm64`, `IosX64`, `IosSimulatorArm64`, `All`	Override target platform
`BUILD_MODE`	`Debug`, `Release`	Override build mode

Native MPC SDK (`native/mpc-sdk/`)

UniFFI-based Rust bindings for MPC cryptography.

Directory	Description
`mpc-sdk-rs/`	Rust MPC library (git submodule)
`wrapper/`	Gradle module for UniFFI Kotlin bindings

Build dependency: Unit tests depend on native:mpc-sdk:wrapper:build to ensure JNI bindings are available.

Sample Apps (`sample/`)

Sample applications for testing and development.

Directory	Description
`androidApp/`	Android sample app
`composeApp/`	Compose Multiplatform sample (shared UI)
`iosApp/`	iOS sample app (SwiftUI)

Module Tier System​

Core SDK​

Blockchain Services (blockchain/)​

Models​

Passkey/WebAuthn (passkey/)​

PasskeyAuthorizationController Methods (iOS)​

IDCP Frame Parsing (idcp/frame/)​

Signing Protocol (signing/)​

Transport Abstraction (transport/)​

BLE Transport (bluetooth/)​

MPC Protocol (mpc/)​

MPC Wallet Storage (storage/)​

Storage Models (MpcStorageModels.kt)​

MpcWalletStorage Methods​

Storage Key Patterns​

Wallet Backup System (storage/backup/)​

Data Models​

WalletBackupPayload Structure​

Cryptography (expect/actual)​

Storage Providers​

Services​

Shared Utilities (util/)​

Platform Expect/Actual Summary​

Build Logic (build-logic/)​

Module Structure​

KMP Plugin Components (build-logic/kmp/)​

Configuration File (development.config)​

Environment Variable Overrides​

Native MPC SDK (native/mpc-sdk/)​

Sample Apps (sample/)​