High-Level Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The MBBank library is a lightweight Python SDK designed to interface with the Military Commercial Joint Stock Bank (MBBank) personal account API. It provides both synchronous and asynchronous implementations for account management, transaction history retrieval, and fund transfers. The architecture is built upon a base layer that handles shared configuration and state, while specialized modules manage captcha OCR, WebAssembly-based request encryption, and Pydantic-driven data modeling.
Sources: mbbank/__init__.py:1-10, mbbank/sync/mbbank.py:44-55
Core Component Structure
The library follows a hierarchical class structure where a base class defines common utilities, and inherited classes implement specific execution modes (Sync vs. Async).
Base and Client Layers
The MBBankBase class serves as the foundation, storing common attributes like credentials, device IDs, and session management logic. MBBank (Sync) and MBBankAsync (Async) extend this base to provide the high-level API methods used by developers.
The architecture separates the request logic from the data models. All API responses are validated into structured objects using Pydantic models defined in the mbbank.modals package.
Sources: mbbank/base/mbbank.py:7-50, mbbank/sync/mbbank.py:44-60, mbbank/aio/mbbank.py:44-65
Security and Encryption Subsystem
A critical component of the architecture is the handling of MBBank's proprietary encryption. The bank requires certain payloads (like login credentials) to be encrypted using a WebAssembly (WASM) module.
WASM Integration Flow
The wasm_helper module utilizes wasmtime to execute the bank's main.wasm file. This allows the Python library to replicate the JavaScript-based encryption logic found in the official web portal.
The wasm_encrypt function instantiates a Go-based WASM environment, providing the necessary imports and memory management to run the encryption algorithm.
Sources: mbbank/wasm_helper/__init__.py:293-318, mbbank/sync/mbbank.py:97-105, mbbank/aio/mbbank.py:110-120
Authentication and Session Management
Authentication is a multi-step process involving automated captcha solving and session persistence.
| Component | Responsibility |
|---|---|
| Captcha OCR | Processes image bytes into text using CapchaProcessing implementations. |
| Session Tracking | Maintains sessionId and deviceIdCommon for stateful API calls. |
| Auto-Reauthentication | The _req method automatically triggers _authenticate if a session expires (GW200 error). |
| Biometric Verification | A mandatory NFC/Biometric check-in is performed immediately after login. |
Data Modeling and Modals
The library uses Pydantic for rigorous schema enforcement. The UserInfoResponseModal is one of the most complex structures, aggregating customer details, account lists, and device configurations.
Key Data Structures
| Model Class | Source File | Description |
|---|---|---|
UserInfoResponseModal | mbbank/modals/userinfo.py | Contains CustModel with account, card, and menu information. |
TransferResponseModal | mbbank/modals/transfer.py | Defines details for completed or pending transfers. |
BalanceResponseModal | mbbank/modals/balance.py | Maps current balances and account aliases. |
TransactionHistory | mbbank/modals/transaction_history.py | Represents individual ledger entries. |
The CustModel inside userinfo.py includes nested dictionaries for acct_list and cardList, allowing for efficient lookup of user assets.
Sources: mbbank/modals/userinfo.py:145-215, mbbank/modals/transfer.py:15-38, mbbank/modals/__init__.py:1-40
Transfer Execution Flow
Transfers are managed through a TransferContext (Sync) or TransferContextAsync (Async). This context-based approach ensures that the multi-stage transfer process (Inquiry -> Authentication -> Execution) maintains consistent state.
The TransferContextBase class handles the formatting of the authentication string, which combines the OTP, timestamp, and a transaction-specific ID.
Sources: mbbank/base/transfer.py:46-95, mbbank/sync/mbbank.py:488-510, mbbank/aio/mbbank.py:500-520
Summary
The high-level architecture of MBBank emphasizes a clean separation between the user-facing API and the complex underlying mechanics of bank communication. By abstracting WASM-based encryption, automated captcha solving, and Pydantic validation, the library provides a simplified interface for developers while maintaining the security requirements of the MBBank infrastructure.
Sources: mbbank/__init__.py:1-40, mbbank/sync/mbbank.py:44-60