System Architecture of x1 Firmware

This blog provides an overview of the Cypherock X1 Wallet firmware’s architecture, detailing how its core components interact to securely manage cryptocurrency operations.

System Architecture Core System Components Event Controller System Session Management Cryptocurrency Support Transaction Signing Flow Manager App System Application Startup Process Code and Memory Management Conclusion

Core System Components

The Cypherock X1 Wallet firmware is organized into several interconnected components that form a comprehensive architecture:

The system uses a layered architecture:

1. User Interface Layer: Manages user interactions through joystick input and display output

2. Communication Layer: Handles connections with the desktop application via USB

3. Core Infrastructure Layer: Provides essential services like event handling and session management

4. Cryptocurrency Layer: Implements functionality for specific cryptocurrencies

5. Security Layer: Manages authentication, transaction signing, and data encryption

6. Hardware Interface Layer: Interfaces with physical components

Event Controller System

The Event Controller is the central component of the firmware, orchestrating the device’s state and handling events from various sources:

The controller defines a hierarchical state machine with multiple levels (LEVEL_ONE through LEVEL_FIVE) managed by flow_level and counter variables. State transitions are handled through functions like mark_event_over(), mark_event_cancel(), and reset_flow_level().

Session Management

The Session Management system establishes secure communication between the device and host application:

The session system operates in three states:

SESSION_INIT: Initial state before session establishment
SESSION_AWAIT: After device key generation, waiting for server key
SESSION_LIVE: Fully established session with secure communication

Key session functions include:

core_session_parse_start_message(): Processes session initialization
session_aes_encrypt(): Encrypts data using AES-CBC mode
session_aes_decrypt(): Decrypts data using AES-CBC mode

Cryptocurrency Support

The firmware supports multiple cryptocurrencies through dedicated modules:

The cryptocurrency modules share common functionality through utility functions like:

derive_hdnode_from_path(): Derives hierarchical deterministic nodes from seed and path
hd_path_array_to_string(): Converts path arrays to human-readable strings
ui_create_display_node(): Creates display nodes for transaction information

Each cryptocurrency implements specialized functions for its specific needs, such as Ethereum’s RLP encoding and Bitcoin’s UTXO management.

Transaction Signing Flow

The transaction signing flow demonstrates how components interact during a critical operation:

This flow demonstrates the complex interaction between system components:

1. Host sends transaction signing request to device
2. Device validates and displays transaction details to user
3. User confirms transaction details
4. Device retrieves necessary keys from card
5. Device generates and sends signature back to host

Manager App System

The Manager App provides administrative functions for the device:

The Manager App provides two primary entry points:

1. manager_app_main(): Full functionality entry point
2. manager_app_restricted_main(): Limited functionality (device info, authentication, firmware updates)

Key functions include:

1. get_device_info_flow(): Retrieves device information
2. device_authentication_flow(): Handles device authentication
3. manager_confirm_firmware_update(): Manages firmware updates
4. manager_export_wallets(): Exports wallet information

Application Startup Process

The application startup process initializes the entire system:

The application startup process includes:

1. Hardware initialization (clocks, GPIO, USB, security chip)
2. System initialization (display, timers, wallet defaults)
3. Event handler registration
4. Core application registry initialization

After initialization, the main function enters an infinite loop that runs the core engine.

Code and Memory Management

The firmware implements custom memory management to ensure secure handling of sensitive data:

The system implements custom memory management through:

1. cy_malloc(): Allocates memory and tracks it in a linked list
2. cy_free(): Securely clears and frees all allocated memory
3. memzero(): Zeros out memory to prevent sensitive data leakage

This approach ensures that sensitive cryptographic data is properly cleared when no longer needed.

Conclusion

The Cypherock X1 Wallet firmware employs a modular, layered architecture to provide secure cryptocurrency management. The Event Controller serves as the central orchestration component, while specialized modules handle cryptocurrency operations, security, and hardware interfaces. The system’s design emphasizes security at every level, from secure memory management to encrypted communications and authenticated card operations.

This architecture enables the firmware to support multiple cryptocurrencies while maintaining a high level of security and providing a consistent user experience across different operations.