@clonegod/ttd-core 2.0.1

package/types/index.d.ts

@@ -0,0 +1,709 @@
+/*********************************************************************
+ *           CONFIG - COMMON SERVICE CONFIG TYPE                     *
+ * *******************************************************************/
+export interface CommonServiceType {
+    config_center: ConfigCenterServiceType
+    quote: QuoteServiceType[]
+    orderbook: OrderbookServiceType
+    trade_proxy: TradeProxyServiceType
+}
+
+// Service
+export interface ConfigCenterServiceType {
+    http_port: number
+}
+
+// Service
+export interface QuoteServiceType {
+    dex_id: string
+    http_port: number
+    ws_port: number
+    enable: boolean
+}
+
+// Service
+export interface OrderbookServiceType {
+    http_port: number
+    ws_port: number
+}
+
+// Service
+export interface TradeProxyServiceType {
+    http_port: number
+    ws_port: number
+}
+
+
+
+/*********************************************************************
+ *                  CONFIG - TOKEN CONFIG TYPE                       *
+ * *******************************************************************/
+export interface StandardTokenConfigType {
+    desc: string
+    version: string
+    url: string
+    token_list: StandardTokenInfoType[]
+}
+
+export interface StandardTokenInfoType {
+    symbol: string
+    address: string
+    address_hex: string
+    decimals: number
+    name: string
+    is_token2022?: boolean
+    enable: boolean
+    market_price?: string
+    reserve?: string // 某个时刻，token在POOL中的储备数量
+    update_time?: string
+    alias?: string // cex上的名称
+}
+
+/*********************************************************************
+ *                       CONFIG - POOL CONFIG TYPE                   *
+ * *******************************************************************/
+export interface StandardPoolConfigType {
+    desc: string
+    url: string
+    dex_list: StandardDexPoolConfigType[]
+}
+
+export interface StandardDexPoolConfigType {
+    dex_id: string
+    pool_list: StandardPoolInfoType[]
+}
+
+export interface StandardPoolInfoType {
+    program_id?: string // Raydium Liquidity Pool V4
+    authority?: string  // Vault owner
+    subscribe_type?: string // ws, grpc
+
+    dex_id: string
+    pool_name: string
+    pool_address: string
+    pool_address_hex: string
+    tokenA: StandardTokenInfoType
+    tokenB: StandardTokenInfoType
+    vaultA?: string
+    vaultB?: string
+    router_id: string
+    fee_rate: number
+    quote_token: string
+    quote_amount_usd: number
+    quote_price_decimals?: number
+    pair: string
+    is_reverse_token: boolean
+    enable: boolean
+    cu_limit?: number
+    tvl?: string|number
+    vol_24h?: string|number
+    update_time?: string
+}
+
+
+/*********************************************************************
+ *                          TOKEN PAIR                               *
+ * *******************************************************************/
+export interface StandardPairType {
+    pair: string
+    price_decimals: number      // 价格的精度（注意：跟token的精度不同！）
+    tokenA?: StandardTokenInfoType
+    tokenB?: StandardTokenInfoType
+    pool_list: string[]
+}
+
+
+
+/*********************************************************************
+ *            CONFIG - TRADE SERVICE CONFIG TYPE                     *
+ * *******************************************************************/
+export interface TradeServiceConfigType {
+    group: TradeGroupType
+    pair_list: TradePairType[]
+    settings: TradeSettingsType
+}
+
+export interface TradeGroupType {
+    id: string
+    desc: string
+    enable: boolean
+    wallet: string
+}
+
+export interface TradePairType {
+    name: string,
+    enable: boolean
+    auto_approve: boolean
+    settings: TradeSettingsType
+    dex_list: TradePairDexPoolsType[]
+}
+
+export interface TradePairDexPoolsType {
+    pair: string
+    dex_id: string
+    pool_list: string[]
+    pool_info_list: StandardPoolInfoType[]
+}
+
+export interface TradeSettingsType {
+    trade_process_count: number
+    slippage_bps: number
+    rpc: RpcInfoType
+    strategy: TradeStrategyType
+}
+
+export interface RpcInfoType {
+    read: string    // 查询使用的RPC
+    write: string   // 提交交易使用的RPC
+}
+
+
+export interface TradeStrategyType {
+    broadcast_type: 'rpc' | 'jito' | 'mixed'   // 提交交易的通道
+    speed: 'fast' | 'turbo' | 'ultra'          // fee_mode='MAX_CAP' 模式下，费用：x1, x2, x4
+    fee_mode: 'exact' | 'max_cap'              // GAS支出模式
+    fee_exact: number,                         // 固定GAS
+    fee_max_cap: number,                       // 动态GAS的上限
+    tip_ratio: number                          // tip 占总gas的比例（gas=priority_fee + tip_fee）
+    tip_up_ratio: number                       // tip上浮比例
+}
+
+
+/*********************************************************************
+ *                   TRADE INSTANCE TYPE                             *
+ * *******************************************************************/
+
+export interface TradeCommandLineArgs {
+    // chain_id 在 .env 中设置
+    chain_id: string
+
+    // 通过命令行参数传入
+    input_dex_id: string
+    input_pair: string
+    input_group_id: string
+
+
+}
+
+// 构建Group 单币对的运行环境
+// ${chain_id}_${group_id}_${dex_id}_${pair}
+export interface TradeRuntimeType {
+    group: TradeGroupType
+    wallet: WalletInfoType
+
+    wallet_token_accounts?: Map<string,string>
+
+    chain_id: string
+    dex_id: string
+    pair_name: string
+    auto_approve: boolean
+    pair_dex: TradePairDexPoolsType
+    settings: TradeSettingsType
+}
+
+
+export interface TradeProcessInstanceType {
+    instance_id: number,
+    pair: string,
+    http_port: number,
+    start_time: string,
+    tx_count: number,
+    tx_time_min: number,
+    tx_time_max: number
+}
+
+//-------------------------------------------------------------------//
+//-------------------------------------------------------------------//
+//-------------------------------------------------------------------//
+
+
+
+/*********************************************************************
+ *                            QUOTE PRICE TYPE                       *
+ * *******************************************************************/
+export declare class EstimateAmountInToken {
+    // market_price => amount_in_token
+    static estimate_amount_in_token(
+        arb_cache: ArbCache,
+        token: StandardTokenInfoType,
+        amount_in_usd: number,
+        query_token_price_url?: string
+    ): Promise<string>
+}
+
+
+export interface TokenPriceWithAmountType {
+    token_info: StandardTokenInfoType
+    market_price: string
+    amount_in_usd: number
+    amount_in_token: number
+}
+
+export interface QuoteResultType {
+    inputToken: StandardTokenInfoType
+    outputToken: StandardTokenInfoType
+    slippageBps: number
+    amountIn: number
+    amountOut: number
+    amountOutMin: number
+    priceImpact: number  // 当前quote size对pool价格的影响程度
+    price: string
+}
+
+
+/*********************************************************************
+ *                          PRICE MESSAGE TYPE                       *
+ * *******************************************************************/
+export interface PriceMessageType {
+    chain_id: string
+    dex_id: string
+    pool_id: string
+    pool_name: string
+    fee_rate: number
+    pair: string              // 标准化的币对名称
+    unique_orderbook_id: string     // ${chain_id}_${dex_id}_${pool_id}_${fee_rate}
+    is_reverse_token: boolean       // 是否反转币对进行交易（按USDT，SOL，TRX等作为计价币）
+    tokenA?: StandardTokenInfoType
+    tokenB?: StandardTokenInfoType
+    price_id: string                // 价格消息的唯一id
+    tx_price?: string               // 链上交易的执行价格
+    quote_amount_usd: number        // quote size，按多少U价值的Token数量进行询价
+    ask: PriceType
+    bid: PriceType
+    time: QuoteTimeInfoType         // quote 耗时数据
+    slot: string                    // 询价生成的价格，所对应的slot (account, vaultA, vaultB)
+    quote_source?: QuoteSourceType  // 触发本次询价的事件源信息
+}
+
+export interface QuoteSourceType {
+    slot: string
+    block: string
+    txid: string
+}
+
+export interface UniqueOrderbookIdType {
+    chain_id: string,
+    dex_id: string,
+    pool_id: string,
+    fee_rate: string
+}
+
+export interface PriceType {
+    price: string
+    quantity: number // ask: baseToken的挂单数量     bid: quoteToken的挂单数量
+}
+
+export interface QuoteTimeInfoType {
+    block_time: number,         // 触发本次quote询价的交易，链上的出块时间
+    stream_time: number,        // 接收到链上发生交易的时间（stream, webhook）
+    quote_start_time: number    // 询价开始时间
+    quote_end_time: number      // 询价结束时间
+    price_time: number          // 生成价格的时间
+    total_quote_time: number    // 询价总耗时：price_time - stream_time
+}
+
+/*********************************************************************
+ *                           ORDERBOOK PRICE TYPE                    *
+ * *******************************************************************/
+export interface OrderbookPriceType {
+    chain_id: string
+    pair: string
+    quote_amount_usd: number
+    asks: Ladder[]
+    bids: Ladder[]
+}
+
+export interface Ladder {
+    unique_orderbook_id: string
+    price: string
+    quantity: string
+
+    // 询价生成的价格，所对应的slot (account, vaultA, vaultB)
+    slot: string
+
+    // unique_orderbook_id 价格更新时间
+    price_id: string
+    price_time: string
+}
+
+
+/*********************************************************************
+ *                           ORDER MESSAGE TYPE                      *
+ * *******************************************************************/
+export interface OrderMessageType {
+    c_id: string // cex order id
+    pair?: string   // 新增：新模式不传unique_orderbook_id，改传标准币对名称
+
+    // 下单参数
+    group_id: string            // 分组编号
+    chain_id: string
+    unique_orderbook_id: string
+    price_id: string
+    aToB: boolean               // 交易方向，相对USDT/SOL/TRX等标准代币而言，买/卖
+    amount: string              // 交易的币的数量
+    order_send_time: number     // cex 发送下单消息的时间
+    price?:string                // cex 提供的下单参考价格
+
+    // 兼容运营操作
+    order_source?: string     // 下单来源 - admin
+    order_action?: string  // 交易方向 - buy/sell
+
+    // 以下字段在dex赋值
+    unique_order_msg_id: string                 // order msg 唯一标识
+    order_recv_time: number                     // trade-proxy 接收到下单消息的时间
+    order_trace_id: string                      // trade-proxy (price_id + order_trace_id -> unique_order_msg_id)
+    order_submit_time: number                   // trade 提交交易的时间
+    order_submit_result: OrderSubmitResultType  // trade 提交交易的结果：txid
+}
+
+
+export interface OrderSubmitResultType {
+    success: boolean
+    msg: 'SUCCESS' | 'FAILED'
+    txid: string
+}
+
+// 返回Order提交结果
+export interface OrderSubmitResponseType {
+    chain_id: string,
+    group_id: string,
+    pair: string,
+    txid: string
+}
+
+/*********************************************************************
+ *                            TRADE RESULT TYPE                      *
+ * *******************************************************************/
+// 返回Trade执行结果
+export interface TradeResponseType {
+    code: 100 | 200 | 404 | 500
+    msg: 'PROCESSING' | 'SUCCESS' | 'NOT_FOUND' | 'FAILED'
+    data: TradeResultType,
+    error_code?: string
+}
+
+export interface TradeResultType {
+    success: boolean
+    error_code: string
+
+    start_time: number
+    end_time: number
+    total_time: number
+
+    group_id: string
+    wallet: string
+
+    chain_id: string
+    pair: string
+    dex_id: string
+    txid: string
+
+    unique_orderbook_id: string
+    unique_order_msg_id: string
+
+    aToB: boolean
+    order_price: string
+    tx_price: string
+
+    balance: TradeResultBalanceChangeType
+
+    execution: TradeExecutionInfoType
+
+    c_id: string // cex order id
+}
+
+// 余额变化
+export interface TradeResultBalanceChangeType {
+    tokenA: TokenBalanceChangeType
+    tokenB: TokenBalanceChangeType
+}
+
+// Token的余额变化
+export interface TokenBalanceChangeType {
+    symbol: string
+    address: string
+    pre_bal: number
+    post_bal: number
+    change: number
+    decimals: number
+}
+
+// 交易执行附加信息
+export interface TradeExecutionInfoType {
+    broadcast: TradeBroadcastType[]
+    time: TradeTimeFlowType
+    server_info: ServerInfoType
+}
+
+
+// 耗时
+export interface TradeTimeFlowType extends QuoteTimeInfoType {
+    order_send_time: number     // cex 发送下单消息的时间
+    order_recv_time: number     // dex 接收到下单消息的时间
+    order_submit_time: number   // dex 提交交易时间
+    order_end_time: number      // dex 解析得到交易结果的时间
+    order_block_time: number    // dex 交易所在区块的出块时间
+    total_order_time: number    // dex 交易耗时： order_end_time - order_recv_time
+}
+
+// TRANSACTION BROADCASTING
+export interface TradeBroadcastType {
+    rpc: RpcInfoType            // quicknode | helius
+    type: string                // main-net | jito | mixed
+    fee: TradeGasFeeType        // gas
+}
+
+// GAS
+export interface TradeGasFeeType {
+    base_fee: number            // 上链基础费用 - 固定收
+    priority_fee: number        // 优先级费用   - 自愿给
+    total_fee: number
+}
+
+// 执行环境
+export interface ServerInfoType {
+    ip: string
+    name: string
+    region: string
+}
+
+// 发送交易的日志，分析限流用
+export interface SendTxLogType {
+    server_id: string          // 服务器id
+    send_time: number|string   // 发送交易的时间
+    txid: string               // transaction id
+    index: number              // 第几次发送（retry的index）
+    ip: string                 // 发送交易使用的IP
+    region: string             // jito的region
+    res_time: number|string    // 响应时间
+    res_code: number           // http 响应码
+    res_data: string           // jito bundle id
+    duration: number           // 发送交易 -> 获取到响应码的耗时
+}
+
+/*********************************************************************
+ *                           WALLET TYPE                             *
+ * *******************************************************************/
+export interface WalletInfoType {
+    public_key: string
+    private_key: string
+}
+
+export interface WalletTokenBalanceInfoType {
+    symbol: string
+    address: string
+    uiAmount: string
+    price?: string
+    balance?: string
+}
+
+
+/*********************************************************************
+ *                          REDIS EVENT TYPE                         *
+ * *******************************************************************/
+export interface RedisConfigChangeEventMessageType {
+    event_type: string
+    event_time: number
+    group_id?: string,
+    data?: any
+}
+
+export interface RedisOrderEventMessageType {
+    event_type: string
+    event_time: number
+    group_id: string,
+    data: OrderMessageType
+}
+
+
+export interface RedisQuoteEventMessageType {
+    event_type: string
+    event_time: number
+    chain_id: string,
+    data: PriceMessageType
+}
+
+/*********************************************************************
+ *                           Cache TYPE                              *
+ * *******************************************************************/
+export declare class ArbCache {
+    chain_id: CHAIN_ID;
+    loading_cache: LoadingCache;
+    redis_cmd: RedisCommand;
+    redis_event_publisher: ArbEventPublisher;
+    token_list: StandardTokenInfoType[];
+    token_symbol_map: Map<string, StandardTokenInfoType>;
+    token_address_map: Map<string, StandardTokenInfoType>;
+    token_list_cache_last_update_time: string;
+    pool_list: StandardPoolInfoType[];
+    pool_address_map: Map<string, StandardPoolInfoType>;
+    pool_list_cahce_last_update_time: string;
+    trade_config_list: TradeServiceConfigType[];
+    trade_config_map: Map<string, TradeServiceConfigType>;
+    trade_config_cache_last_update_time: string;
+    event_emitter: EventEmitter;
+    constructor(env_args: any);
+    init(): Promise<void>;
+    init_configs(): Promise<void>;
+    get_config_filepath(suffix: string): string;
+    get_bak_config_filepath(suffix: string): string;
+    refresh_local_cache_token_list(token_list: StandardTokenInfoType[]): void;
+    refresh_local_cache_pool_list(pool_list: StandardPoolInfoType[]): void;
+    refresh_local_cache_group_map(trade_config: TradeServiceConfigType): void;
+    cache_token_list(): Promise<void>;
+    update_token_list(input_token_list: StandardTokenInfoType[]): Promise<void>;
+    get_token_list(): Promise<StandardTokenInfoType[]>;
+    get_token_list_no_cache(): Promise<StandardTokenInfoType[]>;
+    get_one_token_info_by_symbol(symbol: string): Promise<StandardTokenInfoType>;
+    publish_token_change_event(): Promise<void>;
+    cache_pool_list(): Promise<void>;
+    set_pool_token_info(pool: StandardPoolInfoType, token_info_list: StandardTokenInfoType[]): void;
+    set_pool_extra(pool: StandardPoolInfoType): void;
+    update_pool_list(input_dex_pool_list: StandardDexPoolConfigType[]): Promise<void>;
+    get_pool_list_by_pair(pair: string): Promise<StandardPoolInfoType[]>;
+    get_pool_list(): Promise<StandardPoolInfoType[]>;
+    get_pool_list_no_cache(): Promise<StandardPoolInfoType[]>;
+    get_one_pool_info(pool_address: string, refresh_cache_if_not_found?: boolean): Promise<StandardPoolInfoType>;
+    publish_pool_change_event(): Promise<void>;
+    get_one_pair(input_pair: string): Promise<StandardPairType>;
+    get_pair_list(input_pair?: string): Promise<StandardPairType[]>;
+    cache_common_service(): Promise<void>;
+    get_common_service(): Promise<CommonServiceType>;
+    cache_trade_group(update_group_id?: string): Promise<void>;
+    update_trade_group(input_trade_config: TradeServiceConfigType): Promise<void>;
+    get_trade_group_id_list(): Promise<string[]>;
+    get_trade_service_by_group_id(group_id: string): Promise<TradeServiceConfigType>;
+    get_trade_service_by_group_id_no_cache(group_id: string): Promise<TradeServiceConfigType>;
+    create_trade_runtime(chain_id: string, group_id: string, dex_id: string, pair_name: string): Promise<TradeRuntimeType>;
+    find_pair_in_trade_config(pair_name: string, trade_config: TradeServiceConfigType): TradePairType;
+    find_pair_dex_in_trade_config(dex_id: string, pair_config: TradePairType): TradePairDexPoolsType;
+    cache_token_market_price(token_with_price: StandardTokenInfoType, ttl?: number): Promise<void>;
+    get_token_market_price(symbol: string): Promise<StandardTokenInfoType>;
+    cache_price_message(price_msg: PriceMessageType, ttl?: number): Promise<void>;
+    get_price_message(price_id: string): Promise<PriceMessageType>;
+    cache_order_message(order_msg: OrderMessageType, ttl?: number): Promise<{
+        key: string;
+        field: string;
+        res: number[];
+        ttl: number;
+    }>;
+    get_order_message(group_id: string, price_id: string, order_trace_id: string): Promise<OrderMessageType>;
+    cache_trade_result(trade_result: TradeResponseType, ttl?: number): Promise<{
+        key: string;
+        field: string;
+        res: number[];
+        ttl: number;
+    }>;
+    get_trade_result(group_id: string, txid: string): Promise<TradeResponseType>;
+    listen_trade_result(event_emitter: EventEmitter): void;
+    get_pair_dex_pool_list(quote_pair_list: string[], dex_id_list: string[]): Promise<StandardPoolInfoType[]>;
+    get_trade_dex_pool_list(dex_id_list: string[], trade_runtime: TradeRuntimeType): Promise<StandardPoolInfoType[]>;
+    get_group_trade_pair_info(chain_id: CHAIN_ID, group_id: string, pair: string): Promise<Map<string, StandardPairType>>;
+    get_all_trade_tokens(): Promise<StandardTokenInfoType[]>;
+    get_all_trade_pools(group_id?: string): Promise<StandardPoolInfoType[]>;
+}
+
+export declare class ArbEventPublisher {
+    arb_cache: ArbCache;
+    chain_id: CHAIN_ID;
+    redis_cmd: RedisCommand;
+    constructor(arb_cache: ArbCache);
+    publish_config_change_event(message: RedisConfigChangeEventMessageType): Promise<void>;
+    publish_quote_price_event(chain_id: string, message: RedisQuoteEventMessageType): Promise<void>;
+    publish_order_event(group_id: string, pair: string, dex_id: DEX_ID, message: RedisOrderEventMessageType): Promise<void>;
+    publish_wallet_raw_tx_event(group_id: string, wallet: string, message: any): Promise<void>;
+    publish_tx_result_event(group_id: string, pair: string, message: TradeResponseType): Promise<void>;
+}
+
+export declare class ArbEventSubscriber {
+    arb_cache: ArbCache;
+    chain_id: CHAIN_ID;
+    redis_cmd: RedisCommand;
+    constructor(arb_cache: ArbCache);
+    pre_load_config_cache(): Promise<void>;
+    subscribe_config_change_event(callback?: Function): Promise<void>;
+    on_config_token_change_event(message: RedisConfigChangeEventMessageType): Promise<boolean>;
+    on_config_pool_change_event(message: RedisConfigChangeEventMessageType): Promise<boolean>;
+    on_config_group_change_event(message: RedisConfigChangeEventMessageType): Promise<boolean>;
+    subscribe_quote_event(chain_id: string, callback: Function): Promise<void>;
+    subscribe_order_event(group_id: string, pair: string, dex_id: DEX_ID, callback: Function): Promise<void>;
+    subscribe_wallet_raw_tx_result(group_id: string, wallet: string, callback: Function): Promise<void>;
+    subscribe_tx_result(group_id: string, pair: string, callback: Function): Promise<void>;
+}
+
+export declare class LoadingCache {
+    redis_client: RedisClientType;
+    local_cache: Map<string, string>;
+    refresh_cache_timer: Map<string, any>;
+    constructor();
+    init(): Promise<void>;
+    get_key(chain_id: CHAIN_ID, cache_type: string, id: string): string;
+    set(chain_id: CHAIN_ID, cache_type: string, id: string, value: string): Promise<{
+        key: string;
+        res: string;
+    }>;
+    get(chain_id: CHAIN_ID, cache_type: string, id: string, skip_local?: boolean, auto_refresh?: boolean, refresh_interval_seconds?: number): Promise<{
+        key: string;
+        value: string;
+    }>;
+    refresh(key: string, interval_seconds: number): Promise<void>;
+    set_ex(chain_id: CHAIN_ID, cache_type: string, id: string, value: string, ttl: number): Promise<{
+        key: string;
+        res: string;
+        ttl: number;
+    }>;
+    get_hash_key(chain_id: CHAIN_ID, cache_type: string): string;
+    hset(chain_id: CHAIN_ID, cache_type: string, field: string, value: string): Promise<{
+        key: string;
+        field: string;
+        res: number[];
+        ttl: number;
+    }>;
+    hset_ex(chain_id: CHAIN_ID, cache_type: string, field: string, value: string, ttl?: number): Promise<{
+        key: string;
+        field: string;
+        res: number[];
+        ttl: number;
+    }>;
+    hdel(chain_id: CHAIN_ID, cache_type: string, field: string): Promise<number>;
+    hlen(chain_id: CHAIN_ID, cache_type: string): Promise<{
+        key: string;
+        value: number;
+    }>;
+    hkeys(chain_id: CHAIN_ID, cache_type: string): Promise<{
+        key: string;
+        value: string[];
+    }>;
+    hget(chain_id: CHAIN_ID, cache_type: string, field: string): Promise<{
+        key: string;
+        field: string;
+        value: string;
+    }>;
+    hmget(chain_id: CHAIN_ID, cache_type: string, fields: string[]): Promise<{
+        key: string;
+        fields: string[];
+        value: string[];
+    }>;
+    hget_all(chain_id: CHAIN_ID, cache_type: string): Promise<{
+        key: string;
+        value: {
+            [x: string]: string;
+        };
+    }>;
+}
+
+export declare class RedisCommand {
+    redis_client: RedisClientType;
+    constructor();
+    init(): Promise<void>;
+    exists(key: string): Promise<number>;
+    ttl(key: string): Promise<number>;
+    expire(key: string, ttl: number): Promise<boolean>;
+    del(key: string): Promise<number>;
+    set_nx(key: string, value: string): Promise<boolean>;
+    hinc(key: string, field: string, ttl?: number): Promise<number[]>;
+    subscribe(channel: string, listener: any): Promise<void>;
+    publish(channel: string, message: string): Promise<void>;
+}
+
+