futu_backend/

crypto_trade.rs

//! Crypto trade backend wire helpers.
//!
//! Crypto trade support added by C++ OpenD 10.5.6508 uses several different
//! server-side request shapes, but they all start from the same account facts:
//! public long account id, optional native intra account id, broker id, and
//! trade cipher. Keep that extraction here so handlers do not re-invent it.

#[cfg(test)]
mod tests;

use futu_cache::trd_cache::{CachedTrdAcc, TrdCache};
use futu_core::error::{FutuError, Result};

use crate::{
    msg_header,
    proto_internal::{odr_sys_cmn, trade_cmn},
};

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CryptoAccountContext {
    pub acc_id: u64,
    pub intra_acc_id: Option<u64>,
    pub broker_id: Option<u32>,
    pub customer_id: Option<u64>,
    pub cipher: Vec<u8>,
}

impl CryptoAccountContext {
    /// Build the `odr_sys_cmn::MsgHeader` used by crypto asset reads.
    ///
    /// C++ `NNProto_Trd_AccCrypto.cpp:197-215` sends
    /// `asset_pl::AccountInfoReq` through `M_SendProto_SetReqMsgHeader`;
    /// `NNProtoCenter_Inner_Macro_Send.h:16-24` always sets `cipher` bytes
    /// even when the cipher length is zero.
    ///
    /// v1.4.110 P0-1: delegate to [`crate::msg_header::build_real`].
    /// `_op` 参数保留作 caller-side 语义标注 (test fixture / log key 可能用),
    /// 当前实现忽略 (与 v1.4.110 之前 `self.req_id(op)` 的 `_op` 行为一致).
    pub fn build_asset_msg_header(&self, _op: &str) -> odr_sys_cmn::MsgHeader {
        msg_header::build_real(self.acc_id, Some(self.cipher.clone()), None, None)
    }

    /// Build the `trade_cmn::CryptoMsgHeader` used by crypto order paths.
    ///
    /// C++ `NNProto_Trd_OrderOpCrypto.cpp:40-48,94-102` sets `req_id` and
    /// `account_id`, but only writes `cipher` when `GetAccCipher` returned a
    /// non-empty buffer. Keep that distinction because backend crypto order
    /// services use this lighter header rather than `odr_sys_cmn::MsgHeader`.
    ///
    /// v1.4.110 P0-1: delegate to [`crate::msg_header::build_crypto`].
    pub fn build_crypto_msg_header(&self, _op: &str) -> trade_cmn::CryptoMsgHeader {
        msg_header::build_crypto(self.acc_id, self.cipher.clone())
    }

    pub fn require_intra_acc_id(&self, op: &str) -> Result<u64> {
        self.intra_acc_id.ok_or_else(|| {
            crypto_context_error(format!(
                "Crypto {op}: account {} missing intra_acc_id",
                self.acc_id
            ))
        })
    }

    pub fn require_broker_id(&self, op: &str) -> Result<u32> {
        self.broker_id.ok_or_else(|| {
            crypto_context_error(format!(
                "Crypto {op}: account {} missing broker_id",
                self.acc_id
            ))
        })
    }

    pub fn require_customer_id(&self, op: &str) -> Result<u64> {
        self.customer_id.ok_or_else(|| {
            crypto_context_error(format!(
                "Crypto {op}: account {} missing customer_id",
                self.acc_id
            ))
        })
    }
}

pub fn lookup_crypto_account_context(
    cache: &TrdCache,
    acc_id: u64,
) -> Result<CryptoAccountContext> {
    let acc = cache.lookup_account(acc_id).ok_or_else(|| {
        crypto_context_error(format!("Crypto account {acc_id} not found in trade cache"))
    })?;
    crypto_account_context_from_acc(cache, &acc)
}

/// Lookup the C++ read-only Crypto context used by startup warmup.
///
/// C++ asset reads always serialize the cipher field, including zero bytes,
/// while Crypto order reads omit the field when the buffer is empty. Both wire
/// shapes are produced by [`CryptoAccountContext`] from the same empty vector.
/// Strict/write callers must continue using [`lookup_crypto_account_context`].
pub fn lookup_crypto_read_account_context(
    cache: &TrdCache,
    acc_id: u64,
) -> Result<CryptoAccountContext> {
    let acc = cache.lookup_account(acc_id).ok_or_else(|| {
        crypto_context_error(format!("Crypto account {acc_id} not found in trade cache"))
    })?;
    if !acc.is_crypto_account() {
        return Err(crypto_context_error(format!(
            "Account {} is not a crypto account",
            acc.acc_id
        )));
    }
    // C++ read-only startup accepts a missing cipher as a zero-length buffer;
    // the two header builders below preserve present-empty vs absent on wire.
    let cipher = cache.get_cipher(acc.acc_id).unwrap_or_default();
    Ok(crypto_account_context_from_parts(&acc, cipher))
}

pub fn crypto_account_context_from_acc(
    cache: &TrdCache,
    acc: &CachedTrdAcc,
) -> Result<CryptoAccountContext> {
    if !acc.is_crypto_account() {
        return Err(crypto_context_error(format!(
            "Account {} is not a crypto account",
            acc.acc_id
        )));
    }
    // v1.4.111 P2-1 follow-through: cipher missing → fail-closed Err (mirror P2-1
    // trade handler check_cipher_or_short_circuit pattern). 之前 unwrap_or_default
    // 让 cipher empty Vec 进 CryptoMsgHeader.cipher → 发 backend → crypto trade
    // auth fail → 浪费 backend round-trip + 错误信息泛化. 改为早 reject 让 caller
    // 通过 `?` propagate Err 转 ret_type=-1 + 清晰 hint "Crypto cipher 未解锁".
    // 对应 v1.4.111-prep merge 后 audit 11 D 桶 verify 后剩 1 真 D 桶, pitfall #45
    // silent-success polish.
    let cipher = cache.get_cipher(acc.acc_id).ok_or_else(|| {
        crypto_context_error(format!(
            "Crypto account {} cipher 未解锁 — 先调 /api/unlock-trade",
            acc.acc_id
        ))
    })?;
    Ok(crypto_account_context_from_parts(acc, cipher))
}

fn crypto_account_context_from_parts(acc: &CachedTrdAcc, cipher: Vec<u8>) -> CryptoAccountContext {
    CryptoAccountContext {
        acc_id: acc.acc_id,
        intra_acc_id: acc.intra_acc_id,
        broker_id: broker_id_from_account(acc),
        // C++ `NNProto_Trd_MaxQtyCrypto.cpp:49-54` writes `m_nUserID`
        // into `crypto_risk_comm::Account.cid`. Rust account projection keeps
        // the same user id in owner_uid/opr_uid.
        customer_id: acc
            .owner_uid
            .filter(|uid| *uid != 0)
            .or_else(|| acc.opr_uid.filter(|uid| *uid != 0)),
        cipher,
    }
}

/// Crypto native account requests need broker ids such as 1001/1007.
///
/// Prefer the C++ sort key `(BrokerID << 48) | (TrdMkt << 32) | IntraAccID`
/// stored by `bridge/account/real_projection.rs:323-326`. If a historical
/// cache entry lacks that key, fall back to `Trd_Common.SecurityFirm` mapping
/// used by C++ `NetCallback::BrokerIDToTcpCategory`.
pub fn broker_id_from_account(acc: &CachedTrdAcc) -> Option<u32> {
    let from_sort_key = (acc.sort_key >> 48) as u32;
    if from_sort_key != 0 {
        return Some(from_sort_key);
    }
    acc.security_firm.and_then(security_firm_to_broker_id)
}

pub fn security_firm_to_broker_id(sf: i32) -> Option<u32> {
    futu_core::trade_broker::broker_id_for_security_firm_like_cpp(sf)
}

/// v1.4.110 codex audit P1 #3: 用户唯一已开户 crypto account 的 broker_id.
///
/// 对齐 C++ `INNData_Trd_MainBrokerage::GetCryptoSupportedDefaultMainBroker`
/// (line 70-123) 优先级 1: 如果只开了一个 crypto account, 直接取该 account 的 broker.
///
/// 返:
/// - `Some(broker_id)`: trd_cache 恰好 1 个 `is_crypto_account()`, 取其 broker
/// - `None`: 0 个或 ≥ 2 个 crypto account, caller 走 9419 crypto_brokers / fallback 路径
///
/// 此值作 `resolve_qot_broker_for_request` / `resolve_or_reject_broker` 第 5
/// 参数注入, QOT handler `securityFirm=Unknown(0)` 时决定 default broker.
pub fn single_crypto_account_broker(trd_cache: &futu_cache::trd_cache::TrdCache) -> Option<u32> {
    let crypto_brokers: std::collections::HashSet<u32> = trd_cache
        .accounts
        .iter()
        .filter(|r| r.value().is_crypto_account())
        .filter_map(|r| broker_id_from_account(r.value()))
        .collect();
    if crypto_brokers.len() == 1 {
        crypto_brokers.into_iter().next()
    } else {
        None
    }
}

fn crypto_context_error(msg: String) -> FutuError {
    FutuError::ServerError { ret_type: -1, msg }
}