@clonegod/ttd-sol-common 2.0.67 → 2.0.69

package/dist/quote/verify/quote_price_verify.js

@@ -0,0 +1,247 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QuotePriceVerify = void 0;
+const trade_direction_1 = require("../../utils/trade_direction");
+const ttd_core_1 = require("@clonegod/ttd-core");
+function pickMatchingTier(tiers, actualAmountIn) {
+    if (!tiers || tiers.length === 0)
+        return null;
+    if (tiers.length === 1)
+        return { tier: tiers[0], mode: 'single_tier', lo_pct: tiers[0].pct, hi_pct: tiers[0].pct };
+    const sorted = [...tiers].sort((a, b) => a.amount_in - b.amount_in);
+    const top = sorted[sorted.length - 1];
+    if (actualAmountIn < sorted[0].amount_in) {
+        return { tier: sorted[0], mode: 'extrapolated_low', lo_pct: null, hi_pct: sorted[0].pct };
+    }
+    if (actualAmountIn > top.amount_in) {
+        return { tier: top, mode: 'extrapolated_high', lo_pct: top.pct, hi_pct: null };
+    }
+    for (let i = 0; i < sorted.length - 1; i++) {
+        const lower = sorted[i];
+        const upper = sorted[i + 1];
+        if (actualAmountIn >= lower.amount_in && actualAmountIn <= upper.amount_in) {
+            if (actualAmountIn === lower.amount_in)
+                return { tier: lower, mode: 'exact', lo_pct: lower.pct, hi_pct: lower.pct };
+            if (actualAmountIn === upper.amount_in)
+                return { tier: upper, mode: 'exact', lo_pct: upper.pct, hi_pct: upper.pct };
+            const span = upper.amount_in - lower.amount_in;
+            if (span <= 0)
+                return { tier: lower, mode: 'exact', lo_pct: lower.pct, hi_pct: lower.pct };
+            const ratio = (actualAmountIn - lower.amount_in) / span;
+            const lerp = (a, b) => a + ratio * (b - a);
+            return {
+                tier: {
+                    pct: lerp(lower.pct, upper.pct),
+                    price: lerp(lower.price, upper.price),
+                    amount: lerp(lower.amount, upper.amount),
+                    amount_in: actualAmountIn,
+                    amount_in_usd: lerp(lower.amount_in_usd, upper.amount_in_usd),
+                    fee: lerp(lower.fee, upper.fee),
+                    fee_usd: lerp(lower.fee_usd, upper.fee_usd),
+                },
+                mode: 'interpolated',
+                lo_pct: lower.pct,
+                hi_pct: upper.pct,
+            };
+        }
+    }
+    return { tier: top, mode: 'extrapolated_high', lo_pct: top.pct, hi_pct: null };
+}
+class QuotePriceVerify {
+    constructor() {
+        this.quoteCache = new Map();
+    }
+    get enabled() {
+        return process.env.VERIFY_QUOTE_PRICE === 'true';
+    }
+    cacheQuote(poolAddress, priceId, source, askPrice, bidPrice, blockNumber, quoteAmountUsd, token0PriceUsd = 0, token1PriceUsd = 0, tiers) {
+        if (!this.enabled)
+            return;
+        if (!source)
+            return;
+        let sourceMap = this.quoteCache.get(poolAddress);
+        if (!sourceMap) {
+            sourceMap = new Map();
+            this.quoteCache.set(poolAddress, sourceMap);
+        }
+        const existing = sourceMap.get(source);
+        const verifiedReferenceBlock = (existing && existing.referenceBlock === blockNumber)
+            ? existing.verifiedReferenceBlock
+            : 0;
+        sourceMap.set(source, {
+            priceId, source, askPrice, bidPrice,
+            askTiers: tiers?.askTiers,
+            bidTiers: tiers?.bidTiers,
+            referenceBlock: blockNumber,
+            verifiedReferenceBlock,
+            quoteAmountUsd,
+            token0PriceUsd, token1PriceUsd,
+        });
+    }
+    checkSwap(params) {
+        if (!this.enabled)
+            return;
+        const { poolAddress, blockNumber, txHash, poolInfo, token0Address } = params;
+        const sourceMap = this.quoteCache.get(poolAddress);
+        if (!sourceMap || sourceMap.size === 0)
+            return;
+        const swapData = this.deriveSwapDirection(params);
+        if (!swapData)
+            return;
+        const direction = (0, trade_direction_1.resolveTradeDirection)(poolInfo, true);
+        const inputIsQuoteToken = swapData.inputTokenAddress.toLowerCase() === direction.quoteToken.address.toLowerCase();
+        const isBuy = inputIsQuoteToken;
+        const execPriceStr = (0, trade_direction_1.calculateStandardPrice)(swapData.inputAmountUi, swapData.outputAmountUi, isBuy);
+        const execPrice = Number(execPriceStr);
+        if (execPrice <= 0)
+            return;
+        const verifiable = [];
+        for (const [source, cached] of sourceMap) {
+            if (blockNumber <= cached.referenceBlock)
+                continue;
+            if (cached.verifiedReferenceBlock === cached.referenceBlock)
+                continue;
+            const tiers = isBuy ? cached.askTiers : cached.bidTiers;
+            let refPrice;
+            let tierInfo;
+            if (tiers && tiers.length > 0) {
+                const match = pickMatchingTier(tiers, swapData.inputAmountUi);
+                if (!match)
+                    continue;
+                refPrice = match.tier.price;
+                tierInfo = {
+                    matched_pct: parseFloat(match.tier.pct.toFixed(4)),
+                    mode: match.mode,
+                    tier_amount_in: match.tier.amount_in,
+                    lo_pct: match.lo_pct,
+                    hi_pct: match.hi_pct,
+                };
+            }
+            else {
+                refPrice = isBuy ? cached.askPrice : cached.bidPrice;
+            }
+            if (refPrice <= 0)
+                continue;
+            cached.verifiedReferenceBlock = cached.referenceBlock;
+            const diff_bps = (refPrice - execPrice) / refPrice * 10000;
+            verifiable.push({ source, cached, refPrice, diff_bps, tierInfo });
+        }
+        if (verifiable.length === 0)
+            return;
+        verifiable.sort((a, b) => b.cached.referenceBlock - a.cached.referenceBlock);
+        const primary = verifiable[0];
+        const sources = {};
+        for (const r of verifiable) {
+            sources[r.source] = {
+                ask: r.cached.askPrice,
+                bid: r.cached.bidPrice,
+                matched_ref_price: r.refPrice,
+                diff_bps: parseFloat(r.diff_bps.toFixed(1)),
+                quote_block: r.cached.referenceBlock,
+                ...(r.tierInfo && {
+                    matched_pct: r.tierInfo.matched_pct,
+                    tier_mode: r.tierInfo.mode,
+                    tier_amount_in: r.tierInfo.tier_amount_in,
+                }),
+            };
+        }
+        return this.compareAndLog(poolAddress, params.poolName, poolInfo, primary.cached, swapData.inputTokenAddress, swapData.outputTokenAddress, swapData.inputAmountUi, swapData.outputAmountUi, primary.refPrice, execPrice, primary.cached.token0PriceUsd, primary.cached.token1PriceUsd, token0Address, blockNumber, txHash, sources, primary.tierInfo);
+    }
+    deriveSwapDirection(params) {
+        const { amount0, amount1, token0Address, token1Address, token0Decimals, token1Decimals } = params;
+        const sign = params.swapperDeltaConvention ? -1n : 1n;
+        const amt0 = BigInt(amount0) * sign;
+        const amt1 = BigInt(amount1) * sign;
+        if (amt0 === 0n && amt1 === 0n)
+            return null;
+        if (amt0 > 0n && amt1 < 0n) {
+            return {
+                inputTokenAddress: token0Address,
+                outputTokenAddress: token1Address,
+                inputAmountUi: Number(amt0) / Math.pow(10, token0Decimals),
+                outputAmountUi: Number(-amt1) / Math.pow(10, token1Decimals),
+            };
+        }
+        else if (amt0 < 0n && amt1 > 0n) {
+            return {
+                inputTokenAddress: token1Address,
+                outputTokenAddress: token0Address,
+                inputAmountUi: Number(amt1) / Math.pow(10, token1Decimals),
+                outputAmountUi: Number(-amt0) / Math.pow(10, token0Decimals),
+            };
+        }
+        return null;
+    }
+    compareAndLog(poolAddress, poolName, poolInfo, cached, inputTokenAddress, outputTokenAddress, inputAmountUi, outputAmountUi, refPrice, execPriceNum, token0PriceUsd, token1PriceUsd, token0Address, swapBlockNumber, txHash, sources, primaryTierInfo) {
+        if (inputAmountUi <= 0 || outputAmountUi <= 0)
+            return;
+        let swapUsd = 0;
+        if (token0PriceUsd && token1PriceUsd && token0Address) {
+            const inputIsToken0 = inputTokenAddress.toLowerCase() === token0Address.toLowerCase();
+            swapUsd = inputIsToken0
+                ? inputAmountUi * token0PriceUsd
+                : inputAmountUi * token1PriceUsd;
+        }
+        const direction = (0, trade_direction_1.resolveTradeDirection)(poolInfo, true);
+        const baseToken = direction.baseToken;
+        const quoteToken = direction.quoteToken;
+        const inputIsQuoteToken = inputTokenAddress.toLowerCase() === quoteToken.address.toLowerCase();
+        const isBuy = inputIsQuoteToken;
+        const side = isBuy ? 'BUY' : 'SELL';
+        if (refPrice <= 0 || execPriceNum <= 0)
+            return;
+        const diffBps = (refPrice - execPriceNum) / refPrice * 10000;
+        const absDiffBps = Math.abs(diffBps);
+        const status = absDiffBps < 5 ? '✅' : absDiffBps < 10 ? '⚠️' : '❌';
+        const usdStr = swapUsd > 0 ? `$${swapUsd.toFixed(0)}` : '$?';
+        const maxUsd = cached.quoteAmountUsd * 2;
+        const inRange = swapUsd <= 0 || swapUsd <= maxUsd;
+        const rangeTag = inRange ? '' : ' [out]';
+        const tradeFlow = isBuy
+            ? `${inputAmountUi.toFixed(4)} ${quoteToken.symbol} -> ${outputAmountUi.toFixed(4)} ${baseToken.symbol}`
+            : `${inputAmountUi.toFixed(4)} ${baseToken.symbol} -> ${outputAmountUi.toFixed(4)} ${quoteToken.symbol}`;
+        const quoteSrc = cached.source || '?';
+        const quoteTag = `quote[${quoteSrc} blk:${cached.referenceBlock}]`;
+        const swapBlk = swapBlockNumber || '?';
+        const swapTx = txHash ? ` ${txHash.slice(0, 10)}` : '';
+        const swapTag = `swap[blk:${swapBlk}${swapTx}]`;
+        const priceLabel = isBuy ? 'ask' : 'bid';
+        const msg = `  ↳ [Verify] ${side} ${usdStr} (${tradeFlow}) ${quoteTag} ${priceLabel}=${refPrice.toFixed(12)} vs ${swapTag} exec=${execPriceNum.toFixed(12)} diff=${diffBps > 0 ? '+' : ''}${diffBps.toFixed(1)}bps ${status}${rangeTag}`;
+        try {
+            (0, ttd_core_1.report_data_to_analyze)('QuoteVerify', {
+                pool_address: poolAddress,
+                pool_name: poolName,
+                price_id: cached.priceId,
+                source: cached.source,
+                quote_amount_usd: cached.quoteAmountUsd,
+                quote_block: cached.referenceBlock,
+                swap_block: swapBlockNumber,
+                tx_hash: txHash || '',
+                side,
+                ref_price: refPrice,
+                exec_price: execPriceNum,
+                diff_bps: parseFloat(diffBps.toFixed(1)),
+                swap_usd: parseFloat(swapUsd.toFixed(0)),
+                in_range: inRange,
+                input_amount: inputAmountUi,
+                output_amount: outputAmountUi,
+                input_symbol: isBuy ? quoteToken.symbol : baseToken.symbol,
+                output_symbol: isBuy ? baseToken.symbol : quoteToken.symbol,
+                status,
+                time: Date.now(),
+                sources: sources || undefined,
+                ...(primaryTierInfo && {
+                    matched_tier_pct: primaryTierInfo.matched_pct,
+                    matched_tier_mode: primaryTierInfo.mode,
+                    matched_tier_amount_in: primaryTierInfo.tier_amount_in,
+                    matched_tier_lo_pct: primaryTierInfo.lo_pct,
+                    matched_tier_hi_pct: primaryTierInfo.hi_pct,
+                }),
+            });
+        }
+        catch (_) {
+        }
+        return msg;
+    }
+}
+exports.QuotePriceVerify = QuotePriceVerify;

package/dist/trade/index.d.ts

@@ -1,6 +1,5 @@
 export * from './tx_result_check';
 export * from './tx_result_parse';
-export * from '../config/SolanaTradeAppConfig';
 export * from './tx_builder';
 export * from './send';
 export * from './jito_tip_wallets';

package/dist/trade/index.js

@@ -16,7 +16,6 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./tx_result_check"), exports);
 __exportStar(require("./tx_result_parse"), exports);
-__exportStar(require("../config/SolanaTradeAppConfig"), exports);
 __exportStar(require("./tx_builder"), exports);
 __exportStar(require("./send"), exports);
 __exportStar(require("./jito_tip_wallets"), exports);

package/dist/trade/tx_builder.d.ts

@@ -1,6 +1,6 @@
 import { TradeContext } from "@clonegod/ttd-core/dist";
 import { Connection, Keypair, Transaction, TransactionInstruction } from "@solana/web3.js";
-import { SolanaTradeAppConfig } from "../config/SolanaTradeAppConfig";
+import { SolanaTradeAppConfig } from "../appconfig/SolanaTradeAppConfig";
 import { JitoTipWalletManager } from "./jito_tip_wallets";
 export declare class SolTransactionBuilder {
     appConfig: SolanaTradeAppConfig;

package/dist/trade/tx_result_parse.js

@@ -64,6 +64,7 @@ class TransactionResultParser {
             wallet: owner,
             block_time: blockTime,
             block_number: slot,
+            tx_index: 0,
             txid,
             pool_address,
             tokenA: {

package/dist/types/index.d.ts

@@ -1,7 +1,9 @@
 export declare enum SolanaPoolAccountType {
     POOL = "pool",
     VAULT_A = "vaultA",
-    VAULT_B = "vaultB"
+    VAULT_B = "vaultB",
+    TICK_ARRAY = "tickArray",
+    BIN_ARRAY = "binArray"
 }
 export interface SolanaAccountUpdateEvent {
     recvTimeMs: number;
@@ -35,6 +37,7 @@ export interface SolanaPoolAccountUpdateEventData {
     pool_name: string;
     data: {
         slot: number;
+        write_version?: number;
         tx_hash: string;
         pool_account: string;
         pool_account_data: string;
@@ -42,5 +45,10 @@ export interface SolanaPoolAccountUpdateEventData {
         vaultA_account_data?: string;
         vaultB_account?: string;
         vaultB_account_data?: string;
+        sub_account?: {
+            role: string;
+            account: string;
+            account_data: string;
+        };
     };
 }

package/dist/types/index.js

@@ -6,4 +6,6 @@ var SolanaPoolAccountType;
     SolanaPoolAccountType["POOL"] = "pool";
     SolanaPoolAccountType["VAULT_A"] = "vaultA";
     SolanaPoolAccountType["VAULT_B"] = "vaultB";
+    SolanaPoolAccountType["TICK_ARRAY"] = "tickArray";
+    SolanaPoolAccountType["BIN_ARRAY"] = "binArray";
 })(SolanaPoolAccountType || (exports.SolanaPoolAccountType = SolanaPoolAccountType = {}));

package/dist/utils/index.d.ts

@@ -0,0 +1 @@
+export * from './trade_direction';

package/dist/utils/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./trade_direction"), exports);

package/dist/utils/trade_direction.d.ts

@@ -0,0 +1,14 @@
+export interface TradeDirectionResult<T = any> {
+    isBuy: boolean;
+    inputToken: T;
+    outputToken: T;
+    baseToken: T;
+    quoteToken: T;
+}
+export declare function resolveTradeDirection<T = any>(poolInfo: {
+    tokenA: T;
+    tokenB: T;
+    quote_token: string;
+    [key: string]: any;
+}, isBuy: boolean): TradeDirectionResult<T>;
+export declare function calculateStandardPrice(inputAmount: number, outputAmount: number, isBuy: boolean): string;

package/dist/utils/trade_direction.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveTradeDirection = resolveTradeDirection;
+exports.calculateStandardPrice = calculateStandardPrice;
+function resolveTradeDirection(poolInfo, isBuy) {
+    const { tokenA, tokenB, quote_token } = poolInfo;
+    const quoteToken = [tokenA, tokenB].find(t => t.symbol === quote_token);
+    const baseToken = [tokenA, tokenB].find(t => t.symbol !== quote_token);
+    if (!quoteToken || !baseToken) {
+        throw new Error(`Cannot resolve tokens: tokenA=${tokenA?.symbol}, tokenB=${tokenB?.symbol}, quote_token=${quote_token}`);
+    }
+    const inputToken = isBuy ? quoteToken : baseToken;
+    const outputToken = isBuy ? baseToken : quoteToken;
+    return { isBuy, inputToken, outputToken, baseToken, quoteToken };
+}
+function calculateStandardPrice(inputAmount, outputAmount, isBuy) {
+    if (isBuy) {
+        return (inputAmount / outputAmount).toFixed(18);
+    }
+    else {
+        return (outputAmount / inputAmount).toFixed(18);
+    }
+}

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@clonegod/ttd-sol-common",
-  "version": "2.0.67",
+  "version": "2.0.69",
   "description": "",
   "main": "dist/index.js",
-  "types": "types/index.d.ts",
+  "types": "dist/index.d.ts",
   "keywords": [],
   "author": "",
   "license": "ISC",
@@ -13,13 +13,13 @@
     "push": "npm run build && npm publish"
   },
   "dependencies": {
-    "@clonegod/ttd-core": "2.1.33",
+    "@clonegod/ttd-core": "3.1.84",
     "@solana/web3.js": "1.91.6",
     "rpc-websockets": "7.10.0",
     "axios": "^1.2.3",
     "bn.js": "^4.12.1",
     "bs58": "^6.0.0",
-    "helius-laserstream": "^0.2.7"
+    "helius-laserstream": "^0.4.0"
   },
   "devDependencies": {
     "@types/node": "^22.7.9",

package/src/appconfig/SolanaQuoteAppConfig.ts

@@ -0,0 +1,55 @@
+/**
+ * Solana 链通用 Quote 配置基类（对标 BSC 的 BscQuoteAppConfig）。
+ *
+ * 统一所有 DEX Quote 进程的配置初始化逻辑：
+ *  - ensureCoreEnv（即便入口忘记 import './appconfig' 也兜底）
+ *  - 初始化 arb_cache（super.init）+ arb_event_subscriber
+ *  - 建立 Solana Connection（所有 DEX 共用，commitment 可由 env 覆盖）
+ *  - env_args 收窄为 SolanaDexEnvArgs
+ *
+ * 池子加载 / 过滤不在这里做 —— 与 BSC 一致，放到各 DEX 的 entry(quote/index.ts)，
+ * 直接 arb_cache.get_pair_dex_pool_list([pair],[dex_id]) + filterPools。
+ */
+
+import { AppConfig, getArbEventSubscriber, getCoreEnv, log_info } from '@clonegod/ttd-core'
+import { Commitment, Connection } from '@solana/web3.js'
+import { COMMITMENT_LEVEL } from '../common/constants'
+import { SolanaDexEnvArgs } from './sol_dex_env_args'
+import { ensureCoreEnv } from './ensure_core_env'
+
+export class SolanaQuoteAppConfig extends AppConfig {
+    public env_args: SolanaDexEnvArgs
+    public connection: Connection
+
+    constructor() {
+        // super 前 ensure coreEnv（AppConfig.constructor 内部读 getCoreEnv()）
+        ensureCoreEnv()
+        super()
+        // AppConfig.constructor 已 this.env_args = getCoreEnv()；这里只做类型收窄
+        this.env_args = getCoreEnv() as SolanaDexEnvArgs
+    }
+
+    async init() {
+        // super.init() 初始化 arb_cache
+        await super.init()
+
+        // 确保 arb_event_subscriber 已就绪（池事件订阅依赖）
+        if (!this.arb_event_subscriber) {
+            this.arb_event_subscriber = getArbEventSubscriber(this.arb_cache)
+        }
+
+        // Solana 连接（所有 DEX quote 共用；commitment 默认 PROCESSED，可由 env 覆盖）
+        const commitment =
+            (process.env.CONNECTION_COMMITMENT_LEVEL as Commitment) || COMMITMENT_LEVEL.PROCESSED
+        this.connection = new Connection(this.env_args.rpc_endpoint, { commitment })
+
+        log_info('SolanaQuoteAppConfig initialized', {
+            chain_id: this.env_args.chain_id,
+            dex_id: this.env_args.dex_id,
+            pair: this.env_args.pair,
+            rpc_endpoint: this.env_args.rpc_endpoint,
+        })
+    }
+
+    // subscribe_config_change 不覆盖 —— 继承 AppConfig 基类版本
+}

package/src/appconfig/SolanaTradeAppConfig.ts

@@ -0,0 +1,117 @@
+/**
+ * Solana 链通用 Trade 配置基类（对标 BSC 的 BscTradeAppConfig，与 SolanaQuoteAppConfig 对称）。
+ *
+ * 统一所有 DEX Trade 进程：
+ *  - ensureCoreEnv + env_args 收窄为 SolanaDexEnvArgs
+ *  - 建立 Solana Connection（commitment 可由 env 覆盖）
+ *  - init_trade_runtime：create_trade_runtime + 从 wallet.private_key 还原 keypair（原本每个 DEX 各抄一份，现上提）
+ *  - subscribe_wallet_raw_txn_event：订阅 stream-trade 推送的链上 tx 结果
+ *
+ * 各 DEX 的 *TradeAppConfig 直接 `extends SolanaTradeAppConfig` 即可，通常无需再覆盖任何方法。
+ */
+
+import {
+    AbstractTradeAppConfig,
+    getCoreEnv,
+    LOCAL_EVENT_NAME,
+    log_error,
+    log_info,
+    sleep,
+    WebSocketClient,
+} from '@clonegod/ttd-core/dist'
+import { Commitment, Connection, Keypair } from '@solana/web3.js'
+import bs58 from 'bs58'
+import { COMMITMENT_LEVEL } from '../common/constants'
+import { SolanaDexEnvArgs } from './sol_dex_env_args'
+import { ensureCoreEnv } from './ensure_core_env'
+
+export class SolanaTradeAppConfig extends AbstractTradeAppConfig {
+    public env_args: SolanaDexEnvArgs
+    public connection: Connection
+    public keypair: Keypair
+
+    // WebSocket 客户端实例，用于订阅交易结果
+    private ws_client: WebSocketClient | null = null
+
+    constructor() {
+        ensureCoreEnv()
+        super()
+        this.env_args = getCoreEnv() as SolanaDexEnvArgs
+    }
+
+    async init() {
+        await super.init()
+
+        // Solana 连接（所有 DEX trade 共用；commitment 默认 PROCESSED）
+        const commitment =
+            (process.env.CONNECTION_COMMITMENT_LEVEL as Commitment) || COMMITMENT_LEVEL.PROCESSED
+        this.connection = new Connection(this.env_args.rpc_endpoint, { commitment })
+
+        this.subscribe_wallet_raw_txn_event()
+        log_info('SolanaTradeAppConfig init ...')
+    }
+
+    /**
+     * 初始化交易上下文 + 从 wallet.private_key 还原 keypair。
+     * （原本 byreal / meteora / orca / pumpswap / raydium / jupiter 各抄一份，现统一上提）
+     */
+    async init_trade_runtime() {
+        try {
+            const { chain_id, dex_id, group_id, pair } = this.env_args
+
+            this.trade_runtime = await this.arb_cache.create_trade_runtime(
+                chain_id,
+                group_id,
+                dex_id,
+                pair,
+            )
+            this.trade_runtime.wallet_token_accounts = new Map()
+
+            // 从 trade_runtime.wallet.private_key 还原 Solana keypair
+            const secret_key = new Uint8Array(bs58.decode(this.trade_runtime.wallet.private_key))
+            this.keypair = Keypair.fromSecretKey(secret_key)
+        } catch (err) {
+            log_error(`SolanaTradeAppConfig create_trade_runtime error!`, err)
+            await sleep(1000)
+            process.exit(0)
+        }
+    }
+
+    // 订阅 Wallet 在链上发生的 tx data（stream-trade 经 WS 推送）
+    subscribe_wallet_raw_txn_event(): void {
+        // 检查是否已经订阅
+        if (this.is_already_subscribe_wallet_raw_txn) {
+            if (this.ws_client && this.ws_client.isConnected()) {
+                return
+            } else {
+                // 连接已断开，需要重新连接
+                log_info('subscribe_wallet_raw_txn_event was subscribed but connection lost, reconnecting...')
+                if (this.ws_client) {
+                    this.ws_client.disconnect()
+                    this.ws_client = null
+                }
+            }
+        }
+        this.is_already_subscribe_wallet_raw_txn = true
+
+        const transactionHandler = async (messageStr: any) => {
+            let messageObj = messageStr
+            if (typeof messageStr === 'string') {
+                messageObj = JSON.parse(messageStr)
+            }
+
+            const tx_id = messageObj.transaction.signature
+            log_info(`Received transaction result via WebSocket: ${tx_id}`)
+
+            this.emit(LOCAL_EVENT_NAME.EVENT_WALLET_TRANSACTION + '#' + tx_id, messageObj)
+        }
+
+        const ws_port = process.env.STREAM_WS_TRADE_PORT || 10002
+        const ws_url = `ws://127.0.0.1:${ws_port}`
+        this.ws_client = new WebSocketClient(ws_url)
+        this.ws_client.onMessage(transactionHandler)
+        this.ws_client.connect()
+
+        log_info(`subscribe_wallet_raw_txn_event, WebSocket connecting to ${ws_url}`)
+    }
+}

package/src/appconfig/ensure_core_env.ts

@@ -0,0 +1,28 @@
+/**
+ * 通用 ensureCoreEnv：Solana AppConfig 子类构造器在 super() 之前调用，
+ * 确保 ttd-core 的 coreEnv 已被 setCoreEnv —— 即便入口忘记 import './appconfig'。
+ *
+ * 设计理由（同 BSC ensure_core_env）：
+ *   - AppConfig.constructor() 内部读 getCoreEnv()，没设置就抛错
+ *   - 入口必须 import './appconfig' 触发 setCoreEnv 是隐式约定，容易漏
+ *   - 此 helper 在 super 前补一刀；即便已设置（入口正常 import）也无副作用（短路返回）
+ *
+ * 限制：super() 之前不能访问 this，本 helper 只做无 this 的纯函数调用。
+ */
+
+import { getCoreEnv, setCoreEnv } from '@clonegod/ttd-core'
+import { SolanaDexEnvArgs } from './sol_dex_env_args'
+
+let _ensured = false
+
+export function ensureCoreEnv(): void {
+    if (_ensured) return
+    try {
+        getCoreEnv()  // 已设置则直接通过
+        _ensured = true
+    } catch {
+        // 未设置：兜底创建一个 Solana DEX 子类的 EnvArgs
+        setCoreEnv(new SolanaDexEnvArgs())
+        _ensured = true
+    }
+}

package/src/appconfig/index.ts

@@ -0,0 +1,5 @@
+export * from './sol_env_args'
+export * from './sol_dex_env_args'
+export * from './SolanaQuoteAppConfig'
+export * from './SolanaTradeAppConfig'
+export * from './ensure_core_env'