# Kiến trúc

> Cách QR Wallet được xây dựng bên trong — dành cho những người tò mò và nhà phát triển.

***

## Ngăn xếp công nghệ

| Thành phần             | Công nghệ                         |
| ---------------------- | --------------------------------- |
| **Ứng dụng di động**   | React Native + Expo               |
| **Quản lý trạng thái** | Zustand                           |
| **Web3**               | viem, permissionless.js           |
| **Điều hướng**         | expo-router                       |
| **Blockchain**         | Trừu tượng hóa Tài khoản ERC-4337 |
| **Cơ sở hạ tầng**      | Alchemy (RPC, Bundler, Paymaster) |
| **Bảo mật**            | Sinh trắc học + Secure Enclave    |

***

## Kiến trúc mô-đun

QR Wallet được xây dựng trên một **kiến trúc mô-đun** — mỗi tính năng được cô lập trong mô-đun riêng với các lớp rõ ràng:

```
modules/{feature}/
├── domain/          ← Logic nghiệp vụ thuần và kiểu
├── infrastructure/  ← API, lưu trữ, dịch vụ bên ngoài
├── application/     ← Quản lý trạng thái và façade
└── ui/              ← Các thành phần React (Giao diện người dùng)
```

### Các lớp

| Lớp               | Trách nhiệm                           | Ví dụ                                  |
| ----------------- | ------------------------------------- | -------------------------------------- |
| **Domain**        | Kiểu, interface, quy tắc nghiệp vụ    | `Swap.entity.ts`, `StakingPool`        |
| **Cơ sở hạ tầng** | Các cuộc gọi API và dịch vụ bên ngoài | `SwapApi.ts`, `AlchemyPaymaster`       |
| **Application**   | Trạng thái, logic UI, façade          | `useSwapFacade.ts`, `SponsoredTxStore` |
| **UI**            | Thành phần hình ảnh                   | `SwapScreen.tsx`, nút, thẻ             |

### Quy tắc nhập

```
UI → Application → Domain & Infrastructure → Domain
```

UI không bao giờ giao tiếp trực tiếp với Infrastructure — chỉ thông qua lớp Application. Domain là thuần túy, không có phụ thuộc.

***

## Trừu tượng hóa Chuỗi

Làm việc với các blockchain khác nhau được thống nhất thông qua một lớp trừu tượng:

```
┌──────────────────────────────────────┐
│            Chain Core                 │
│                                      │
│  ┌──────────┐ ┌──────┐ ┌──────────┐ │
│  │   EVM    │ │Solana│ │   Tron   │ │
│  │ Provider │ │Provid│ │ Provider │ │
│  └──────────┘ └──────┘ └──────────┘ │
│                                      │
│  ChainRegistry → ChainConfigProvider │
│                                      │
│  Giao diện thống nhất cho mọi thao tác │
└──────────────────────────────────────┘
```

* **ChainRegistry** — đăng ký tất cả các mạng được hỗ trợ
* **ChainConfigProvider** — cấu hình và khả năng theo từng chuỗi
* **TransactionService** — gửi TX thống nhất (EVM, Solana, Tron)

***

## Ngăn xếp Trừu tượng hóa Tài khoản

```
┌──────────────────────────────────────────────┐
│                Người dùng                     │
│          (sinh trắc học → chữ ký)             │
└──────────────────┬───────────────────────────┘
                   ↓
┌──────────────────┴───────────────────────────┐
│          IAccountProvider                     │
│    Xây dựng UserOperation                     │
│    (sender, nonce, callData, initCode)        │
└──────────────────┬───────────────────────────┘
                   ↓
┌──────────────────┴───────────────────────────┐
│          IPaymaster                           │
│    Tài trợ gas                                │
│    (paymasterAndData, ước tính gas)           │
└──────────────────┬───────────────────────────┘
                   ↓
┌──────────────────┴───────────────────────────┐
│          IBundler                             │
│    Nộp lên blockchain                         │
│    (sendUserOperation → waitForReceipt)       │
└──────────────────┬───────────────────────────┘
                   ↓
┌──────────────────┴───────────────────────────┐
│          EntryPoint (trên chuỗi)               │
│    Xác thực → Thực thi → Trả gas              │
└──────────────────────────────────────────────┘
```

Ba interface (`IAccountProvider`, `IPaymaster`, `IBundler`) trừu tượng hóa nhà cung cấp cụ thể. Hiện đang sử dụng Alchemy, nhưng kiến trúc cho phép chuyển sang bất kỳ nhà cung cấp nào mà không thay đổi logic nghiệp vụ.

***

## Đăng ký Token

Một đăng ký duy nhất cho tất cả token trong hệ thống:

```typescript
// Mỗi token được mô tả một lần
{
  symbol: 'USDC',
  name: 'USD Coin',
  addresses: { base: '0x...', arbitrum: '0x...', polygon: '0x...' },
  decimals: { default: 6 },
  flags: { swappable: true, collateral: true, borrowable: true, stakable: true }
}
```

Các mô-đun lấy token họ cần thông qua **flags**:

* `swappable: true` → Hoán đổi token
* `collateral: true` → Mượn token làm tài sản thế chấp
* `borrowable: true` → Token có thể vay
* `stakable: true` → Token để staking

Điều này loại bỏ sự trùng lặp — dữ liệu token được mô tả **một lần** và được sử dụng ở mọi nơi.

***

## 18 Ngôn ngữ

Ứng dụng được bản địa hóa bằng 18 ngôn ngữ:

EN, RU, ES, FR, HI, ID, JA, KO, MS, PT, TH, TL, TR, UR, VI, ZH, AR, BN