0x0A-b: ID Specification & Account Structure

🇺🇸 English | 🇨🇳 中文

🇺🇸 English

📅 Status: Design Phase Core Objective: Define ID generation rules and account data structures.

1. ID Generation Rules

1.1 User ID (`u64`)

Semantics: Global unique user identifier.
Strategy: Auto-increment or Snowflake/ULID (for future distributed support).
Initial Value: 1024 (0-1023 reserved for system accounts).

1.2 Asset ID (`u32`)

Semantics: Asset identifier (e.g., BTC=1, USDT=2).
Strategy: Sequential allocation starting from 1.
Purpose: Maintain O(1) array indexing performance.

1.3 Symbol ID (`u32`)

Semantics: Trading Pair identifier (e.g., BTC_USDT=1).
Strategy: Sequential allocation starting from 1.

1.4 Account Identification

Semantics: User’s sub-account (distinguishing Funding vs Spot).

Strategy: Use (user_id, account_type) tuple, no composite ID needed.

#![allow(unused)]
fn main() {
struct AccountKey {
    user_id: u64,
    account_type: AccountType,  // Funding | Spot
}
}

Account Types:
- Spot = 1
- Funding = 2

1.5 Order ID / Trade ID (`u64`)

Semantics: Unique identifier for orders/trades within the Matching Engine.
Strategy: Global atomic increment.

2. Core Data Structures

2.1 `AccountType` Enum

#![allow(unused)]
fn main() {
#[repr(u8)]
pub enum AccountType {
    Funding = 0x01,
    Spot    = 0x02,
}
}

2.2 `Account` Struct (Conceptual)

#![allow(unused)]
fn main() {
pub struct Account {
    pub user_id: u64,
    pub account_type: AccountType,
    pub balances: HashMap<AssetId, Balance>,
    pub created_at: u64,
    pub status: AccountStatus,
}
}

3. System Reserved Accounts

User ID	Purpose	Description
`0`	REVENUE	Platform fee income account
`1`	INSURANCE	Insurance fund (future)
`2-1023`	Reserved	For future system use (1024 total)

This design will be updated to src/core_types.rs and src/account/mod.rs upon confirmation.

💡 Future Consideration: Alternative System ID Range

Current: System IDs use 0-1023 (1024 total), users start at 1024.

Problem: Test data might accidentally use 1, 2, 3… which conflicts with system IDs.

Alternative: Use u64::MAX downward for system accounts:

#![allow(unused)]
fn main() {
const REVENUE_ID: u64 = u64::MAX;        // 18446744073709551615
const INSURANCE_ID: u64 = u64::MAX - 1;  // 18446744073709551614
const SYSTEM_MIN: u64 = u64::MAX - 1000; // Boundary

fn is_system_account(user_id: u64) -> bool {
    user_id > SYSTEM_MIN
}
}

Benefits:

Users can start from 1, more natural
Test data never conflicts with system IDs
Clear separation: low = users, high = system

↑ Back to Top

🇨🇳 中文

📅 状态: 设计中 核心目标: 定义系统中所有关键 ID 的生成规则和账户的基础数据结构。

1. ID 生成规则

1.1 User ID (`u64`)

语义: 全局唯一的用户标识符。
生成策略: 自增序列或 Snowflake/ULID (未来支持分布式)。
初始值: 1024 (0-1023 保留给系统账户)。

1.2 Asset ID (`u32`)

语义: 资产标识符（如 BTC=1, USDT=2）。
生成策略: 顺序分配，从 1 开始。
目的: 保持 O(1) 数组索引性能。

1.3 Symbol ID (`u32`)

语义: 交易对标识符（如 BTC/USDT=1）。
生成策略: 顺序分配，从 1 开始。

1.4 账户标识

语义: 用户的子账户（区分 Funding 与 Spot）。

策略: 使用 (user_id, account_type) 元组，不需要复合 ID。

#![allow(unused)]
fn main() {
struct AccountKey {
    user_id: u64,
    account_type: AccountType,  // Funding | Spot
}
}

账户类型:
- Spot = 1
- Funding = 2

1.5 Order ID / Trade ID (`u64`)

语义: 撮合引擎内的订单/成交唯一标识。
生成策略: 全局原子递增。

2. 核心数据结构

2.1 `AccountType` 枚举

#![allow(unused)]
fn main() {
#[repr(u8)]
pub enum AccountType {
    Funding = 0x01,
    Spot    = 0x02,
}
}

2.2 `Account` 结构体 (概念)

#![allow(unused)]
fn main() {
pub struct Account {
    pub user_id: u64,
    pub account_type: AccountType,
    pub balances: HashMap<AssetId, Balance>,
    pub created_at: u64,
    pub status: AccountStatus,
}
}

3. 系统保留账户

User ID	用途	说明
`0`	REVENUE	平台手续费收入账户
`1`	INSURANCE	保险基金 (未来)
`2-1023`	保留	未来系统用途 (共 1024 个)

此设计待确认后，将同步更新至 src/core_types.rs 与 src/account/mod.rs。

💡 未来考虑: 替代系统 ID 范围

当前: 系统 ID 使用 0-1023 (共 1024 个)，用户从 1024 开始。

问题: 测试数据可能使用 1, 2, 3…，与系统 ID 冲突。

替代方案: 使用 u64::MAX 倒数作为系统账户：

#![allow(unused)]
fn main() {
const REVENUE_ID: u64 = u64::MAX;        // 18446744073709551615
const INSURANCE_ID: u64 = u64::MAX - 1;  // 18446744073709551614
const SYSTEM_MIN: u64 = u64::MAX - 1000; // 边界

fn is_system_account(user_id: u64) -> bool {
    user_id > SYSTEM_MIN
}
}

好处:

用户可以从 1 开始，更自然
测试数据永不与系统 ID 冲突
清晰分离: 低位=用户，高位=系统

Keyboard shortcuts

0xInfinity

🇺🇸 English | 🇨🇳 中文