@clonegod/ttd-sui-common 1.0.101 → 2.0.1

package/dist/trade/executor/central_executor.js

@@ -0,0 +1,240 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CentralExecutor = void 0;
+const dist_1 = require("@clonegod/ttd-core/dist");
+const ed25519_1 = require("@mysten/sui/keypairs/ed25519");
+const transactions_1 = require("@mysten/sui/transactions");
+const coin_cache_1 = require("./coin_cache");
+const effects_1 = require("./effects");
+const swap_1 = require("../swap");
+const constants_1 = require("../../constants");
+class CentralExecutor {
+    constructor(core, opts = {}) {
+        this.core = core;
+        this.cache = new coin_cache_1.InProcessCoinCache();
+        this.gasAddress = '';
+        this.tradeWallets = new Map();
+        this.sharedRefCache = new Map();
+        this.seq = 0;
+        this.gasBudget = opts.gasBudget ?? BigInt(process.env.SUI_GAS_BUDGET || '50000000');
+        this.gasMinCoin = opts.gasMinCoin ?? BigInt(process.env.SUI_GAS_MIN_COIN || this.gasBudget.toString());
+        this.reconcileAfterTx = opts.reconcileAfterTx ?? true;
+        this.onBroadcastResult = opts.onBroadcastResult;
+    }
+    async init() {
+        const tradeIds = (process.env.SUI_WALLET_GROUP_IDS || '').split(',').map(s => s.trim()).filter(Boolean);
+        const gasIds = (process.env.SUI_GAS_WALLET_GROUP_IDS || '').split(',').map(s => s.trim()).filter(Boolean);
+        if (!tradeIds.length)
+            throw new Error('SUI_WALLET_GROUP_IDS 未配置（集中执行器需交易钱包）');
+        if (!gasIds.length)
+            throw new Error('SUI_GAS_WALLET_GROUP_IDS 未配置（集中执行器需 gas 赞助钱包）');
+        for (const info of (0, dist_1.load_wallet_multi)(tradeIds, false)) {
+            const kp = ed25519_1.Ed25519Keypair.fromSecretKey(info.private_key);
+            this.tradeWallets.set(kp.getPublicKey().toSuiAddress(), kp);
+        }
+        const gasInfos = (0, dist_1.load_wallet_multi)(gasIds, false);
+        if (!gasInfos.length)
+            throw new Error('gas 钱包加载为空');
+        this.gasKeypair = ed25519_1.Ed25519Keypair.fromSecretKey(gasInfos[0].private_key);
+        this.gasAddress = this.gasKeypair.getPublicKey().toSuiAddress();
+        await this.reconcileCoins(this.gasAddress, constants_1.SUI_TOKEN_ADDRESS.LONG);
+        (0, dist_1.log_info)(`[executor] init: trade=${[...this.tradeWallets.keys()].join(',')}, gas=${this.gasAddress}, gasBudget=${this.gasBudget}`);
+    }
+    async reconcileCoins(wallet, coinType) {
+        try {
+            const refs = [];
+            let cursor = undefined;
+            do {
+                const page = await this.core.getCoins({ address: wallet, coinType, cursor });
+                for (const c of page.objects) {
+                    refs.push({ objectId: c.id, version: c.version, digest: c.digest, balance: c.balance });
+                }
+                cursor = page.hasNextPage ? page.cursor : null;
+            } while (cursor);
+            this.cache.reconcile(wallet, coinType, refs);
+        }
+        catch (e) {
+            (0, dist_1.log_error)(`[executor] reconcileCoins 失败 ${wallet} ${coinType}`, e);
+        }
+    }
+    async getSharedRefCached(objectId) {
+        let isv = this.sharedRefCache.get(objectId);
+        if (!isv) {
+            const res = await this.core.getObjects({ objectIds: [objectId] });
+            const obj = res.objects[0];
+            if (obj instanceof Error)
+                throw new Error(`[executor] getObjects(${objectId}) 失败: ${obj.message}`);
+            const owner = obj.owner;
+            if (owner.$kind !== 'Shared')
+                throw new Error(`[executor] ${objectId} 非共享对象（$kind=${owner.$kind}）`);
+            isv = owner.Shared.initialSharedVersion;
+            this.sharedRefCache.set(objectId, isv);
+        }
+        return isv;
+    }
+    async getGasPrice() {
+        return BigInt((await this.core.getReferenceGasPrice()).referenceGasPrice);
+    }
+    nextTag(prefix) { return `${prefix}:${Date.now()}:${++this.seq}`; }
+    inputCoinType(req) { return req.a2b ? req.coinTypeA : req.coinTypeB; }
+    outputCoinType(req) { return req.a2b ? req.coinTypeB : req.coinTypeA; }
+    chooseTradeWallet(req, coinType, amount) {
+        if (req.walletAddress) {
+            if (!this.tradeWallets.has(req.walletAddress))
+                throw new Error(`未知交易钱包: ${req.walletAddress}`);
+            return req.walletAddress;
+        }
+        let best = '';
+        let bestTotal = -1n;
+        for (const w of this.tradeWallets.keys()) {
+            const { total } = this.cache.snapshot(w, coinType);
+            if (total >= amount && total > bestTotal) {
+                best = w;
+                bestTotal = total;
+            }
+        }
+        if (!best)
+            throw new Error(`无交易钱包持有 ≥ ${amount} 的 ${coinType}`);
+        return best;
+    }
+    async registerShared(tx, objectId, mutable) {
+        const initialSharedVersion = await this.getSharedRefCached(objectId);
+        tx.object(transactions_1.Inputs.SharedObjectRef({ objectId, initialSharedVersion, mutable }));
+    }
+    async submitSwap(req) {
+        const inType = this.inputCoinType(req);
+        const wallet = this.chooseTradeWallet(req, inType, req.amountIn);
+        const inputTag = this.nextTag('in');
+        const gasTag = this.nextTag('gas');
+        const inputRes = this.cache.acquire(wallet, inType, req.amountIn, inputTag);
+        let gasRes;
+        try {
+            gasRes = this.cache.acquireGas(this.gasAddress, constants_1.SUI_TOKEN_ADDRESS.LONG, this.gasMinCoin, gasTag);
+        }
+        catch (e) {
+            this.cache.abort(inputTag, false);
+            throw e;
+        }
+        try {
+            const { txBytes, tx } = await this.buildSwapTx(req, wallet, inputRes.coins, gasRes.coin);
+            const { signature: senderSig } = await this.tradeWallets.get(wallet).signTransaction(txBytes);
+            const { signature: sponsorSig } = await this.gasKeypair.signTransaction(txBytes);
+            const digest = await tx.getDigest();
+            void this.broadcastAndCommit(txBytes, [senderSig, sponsorSig], digest, wallet, inType, this.outputCoinType(req), inputRes.coins, gasRes.coin.objectId, inputTag, gasTag);
+            (0, dist_1.log_info)(`[executor] swap 已签提交 digest=${digest} dex=${req.dexId} ${req.a2b ? 'a2b' : 'b2a'} in=${req.amountIn}`);
+            return { digest, submitted: true };
+        }
+        catch (e) {
+            this.cache.abort(inputTag, false);
+            this.cache.abort(gasTag, false);
+            (0, dist_1.log_error)(`[executor] submitSwap 失败 dex=${req.dexId}`, e);
+            return { digest: '', submitted: false, error: e.message };
+        }
+    }
+    async broadcastAndCommit(txBytes, signatures, digest, wallet, inType, outType, inputCoins, gasCoinId, inputTag, gasTag) {
+        try {
+            const resp = await this.core.executeTransaction({ transaction: txBytes, signatures });
+            const tr = resp.transaction;
+            if (!tr?.effects) {
+                this.cache.abort(inputTag, true);
+                this.cache.abort(gasTag, true);
+                this.reconcileAfterFailure(wallet, inType, outType);
+                (0, dist_1.log_error)(`[executor] 响应缺 effects，无法更新 cache digest=${digest}`, new Error('missing effects'));
+                this.onBroadcastResult?.({ digest, success: false, error: 'missing effects' });
+                return;
+            }
+            const { success, error } = (0, effects_1.coreTxStatus)(tr.effects);
+            if (!success) {
+                this.cache.abort(inputTag, true);
+                this.cache.abort(gasTag, true);
+                this.reconcileAfterFailure(wallet, inType, outType);
+                (0, dist_1.log_warn)(`[executor] swap 链上失败 digest=${digest} err=${error}`);
+                this.onBroadcastResult?.({ digest, success: false, error });
+                return;
+            }
+            await this.onSuccess(tr, wallet, inType, outType, inputCoins, gasCoinId, inputTag, gasTag);
+            (0, dist_1.log_info)(`[executor] swap quorum-executed 确认 digest=${digest}`);
+            this.onBroadcastResult?.({ digest, success: true });
+        }
+        catch (e) {
+            this.cache.abort(inputTag, true);
+            this.cache.abort(gasTag, true);
+            this.reconcileAfterFailure(wallet, inType, outType);
+            (0, dist_1.log_error)(`[executor] broadcast 失败 digest=${digest}`, e);
+        }
+    }
+    reconcileAfterFailure(wallet, inType, outType) {
+        for (const t of new Set([inType, outType, constants_1.SUI_TOKEN_ADDRESS.LONG]))
+            void this.reconcileCoins(wallet, t);
+        void this.reconcileCoins(this.gasAddress, constants_1.SUI_TOKEN_ADDRESS.LONG);
+    }
+    async simulateSwap(req) {
+        const inType = this.inputCoinType(req);
+        const wallet = req.walletAddress ?? this.chooseTradeWallet(req, inType, req.amountIn);
+        const { coins } = this.cache.snapshot(wallet, inType);
+        if (!coins.length)
+            throw new Error(`[executor] simulate 无 ${inType} 输入币（先 reconcileCoins）`);
+        const picked = [];
+        let sum = 0n;
+        for (const c of coins) {
+            picked.push(c);
+            sum += BigInt(c.balance);
+            if (sum >= req.amountIn)
+                break;
+        }
+        if (sum < req.amountIn)
+            throw new Error(`[executor] simulate 输入不足 ${sum} < ${req.amountIn}`);
+        const gasSnap = this.cache.snapshot(this.gasAddress, constants_1.SUI_TOKEN_ADDRESS.LONG);
+        const gasCoin = gasSnap.coins.find(c => BigInt(c.balance) >= this.gasMinCoin);
+        if (!gasCoin)
+            throw new Error(`[executor] simulate 无 ≥ ${this.gasMinCoin} 的 gas coin`);
+        const { txBytes } = await this.buildSwapTx(req, wallet, picked, gasCoin);
+        return (await this.core.dryRunTransaction({ transaction: txBytes })).transaction;
+    }
+    async buildSwapTx(req, wallet, inputCoins, gasCoin) {
+        const tx = new transactions_1.Transaction();
+        tx.setSender(wallet);
+        await this.registerShared(tx, req.poolId, true);
+        await this.registerShared(tx, (0, swap_1.configSharedObjectId)(req.dexId), true);
+        tx.object(transactions_1.Inputs.SharedObjectRef({ objectId: swap_1.SUI_CLOCK_ID, initialSharedVersion: '1', mutable: false }));
+        const primary = tx.object(transactions_1.Inputs.ObjectRef(inputCoins[0]));
+        if (inputCoins.length > 1) {
+            tx.mergeCoins(primary, inputCoins.slice(1).map(c => tx.object(transactions_1.Inputs.ObjectRef(c))));
+        }
+        const [inCoin] = tx.splitCoins(primary, [tx.pure.u64(req.amountIn)]);
+        const { outputCoin, leftoverCoins } = (0, swap_1.buildSwapMoveCall)(req.dexId, tx, {
+            coinTypeA: req.coinTypeA, coinTypeB: req.coinTypeB, poolId: req.poolId,
+            a2b: req.a2b, byAmountIn: true, amount: req.amountIn,
+            amountLimit: req.minOut, sqrtPriceLimit: req.sqrtPriceLimit,
+        }, inCoin);
+        tx.transferObjects([outputCoin, ...leftoverCoins], tx.pure.address(wallet));
+        tx.setGasOwner(this.gasAddress);
+        tx.setGasPayment([{ objectId: gasCoin.objectId, version: gasCoin.version, digest: gasCoin.digest }]);
+        tx.setGasBudget(this.gasBudget);
+        tx.setGasPrice(await this.getGasPrice());
+        const txBytes = await tx.build();
+        return { txBytes, tx };
+    }
+    async onSuccess(tr, wallet, inType, outType, inputCoins, gasCoinId, inputTag, gasTag) {
+        const objectTypes = await tr.objectTypes;
+        const coinTypeById = new Map();
+        for (const c of inputCoins)
+            coinTypeById.set(c.objectId, inType);
+        coinTypeById.set(gasCoinId, constants_1.SUI_TOKEN_ADDRESS.LONG);
+        const tradeChanges = (0, effects_1.extractCoinChangesFromCore)(tr.effects, objectTypes, { owners: new Set([wallet]), coinTypeById });
+        const gasChanges = (0, effects_1.extractCoinChangesFromCore)(tr.effects, objectTypes, { owners: new Set([this.gasAddress]), coinTypeById });
+        this.cache.commit(inputTag, tradeChanges);
+        this.cache.commit(gasTag, gasChanges);
+        if (this.reconcileAfterTx) {
+            for (const t of new Set([inType, outType, constants_1.SUI_TOKEN_ADDRESS.LONG]))
+                void this.reconcileCoins(wallet, t);
+            void this.reconcileCoins(this.gasAddress, constants_1.SUI_TOKEN_ADDRESS.LONG);
+        }
+    }
+    get coinCache() { return this.cache; }
+    get gasWalletAddress() { return this.gasAddress; }
+    get gasSigner() { return this.gasKeypair; }
+    get tradeWalletAddresses() { return [...this.tradeWallets.keys()]; }
+    get coreClient() { return this.core; }
+}
+exports.CentralExecutor = CentralExecutor;

package/dist/trade/executor/coin_cache.d.ts

@@ -0,0 +1,21 @@
+import { CoinRef, CoinReservation, GasReservation, CoinObjectChange } from '../coin/types';
+export declare class InProcessCoinCache {
+    private available;
+    private inflight;
+    private walletMap;
+    private list;
+    private sortDesc;
+    seed(wallet: string, coinType: string, coins: CoinRef[]): void;
+    reconcile(wallet: string, coinType: string, freshCoins: CoinRef[]): void;
+    acquire(wallet: string, coinType: string, amount: bigint, txTag: string, maxCoins?: number): CoinReservation;
+    acquireGas(wallet: string, coinType: string, minGas: bigint, txTag: string): GasReservation;
+    commit(txTag: string, changes: CoinObjectChange[]): void;
+    abort(txTag: string, consumed: boolean): void;
+    private removeEverywhere;
+    snapshot(wallet: string, coinType: string): {
+        count: number;
+        total: bigint;
+        coins: CoinRef[];
+    };
+    inflightCount(): number;
+}

package/dist/trade/executor/coin_cache.js

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InProcessCoinCache = void 0;
+const dist_1 = require("@clonegod/ttd-core/dist");
+class InProcessCoinCache {
+    constructor() {
+        this.available = new Map();
+        this.inflight = new Map();
+    }
+    walletMap(wallet) {
+        let m = this.available.get(wallet);
+        if (!m) {
+            m = new Map();
+            this.available.set(wallet, m);
+        }
+        return m;
+    }
+    list(wallet, coinType) {
+        const m = this.walletMap(wallet);
+        let l = m.get(coinType);
+        if (!l) {
+            l = [];
+            m.set(coinType, l);
+        }
+        return l;
+    }
+    sortDesc(l) {
+        l.sort((a, b) => (BigInt(b.balance) > BigInt(a.balance) ? 1 : BigInt(b.balance) < BigInt(a.balance) ? -1 : 0));
+    }
+    seed(wallet, coinType, coins) {
+        const l = coins.slice();
+        this.sortDesc(l);
+        this.walletMap(wallet).set(coinType, l);
+        (0, dist_1.log_info)(`[coin-cache] seed ${wallet} ${coinType}: ${l.length} coins`);
+    }
+    reconcile(wallet, coinType, freshCoins) {
+        const inflightIds = new Set();
+        for (const r of this.inflight.values()) {
+            if (r.wallet === wallet && r.coinType === coinType)
+                r.coins.forEach(c => inflightIds.add(c.objectId));
+        }
+        const kept = freshCoins.filter(c => !inflightIds.has(c.objectId));
+        this.sortDesc(kept);
+        this.walletMap(wallet).set(coinType, kept);
+        (0, dist_1.log_info)(`[coin-cache] reconcile ${wallet} ${coinType}: ${kept.length} avail (${inflightIds.size} inflight kept)`);
+    }
+    acquire(wallet, coinType, amount, txTag, maxCoins = 8) {
+        if (this.inflight.has(txTag))
+            throw new Error(`[coin-cache] txTag 重复: ${txTag}`);
+        const l = this.list(wallet, coinType);
+        const picked = [];
+        let sum = 0n;
+        for (const c of l) {
+            if (sum >= amount)
+                break;
+            picked.push(c);
+            sum += BigInt(c.balance);
+            if (picked.length >= maxCoins && sum < amount) {
+                throw new Error(`[coin-cache] ${wallet} ${coinType} 碎片化：${maxCoins} 个 coin 仅凑 ${sum} < ${amount}（需先 merge）`);
+            }
+        }
+        if (sum < amount) {
+            throw new Error(`[coin-cache] ${wallet} ${coinType} 余额不足：可用 ${sum} < 需 ${amount}`);
+        }
+        const pickedIds = new Set(picked.map(c => c.objectId));
+        this.walletMap(wallet).set(coinType, l.filter(c => !pickedIds.has(c.objectId)));
+        this.inflight.set(txTag, { wallet, coinType, coins: picked, gas: false });
+        return { txTag, coinType, coins: picked };
+    }
+    acquireGas(wallet, coinType, minGas, txTag) {
+        if (this.inflight.has(txTag))
+            throw new Error(`[coin-cache] gas txTag 重复: ${txTag}`);
+        const l = this.list(wallet, coinType);
+        let chosen;
+        for (let i = l.length - 1; i >= 0; i--) {
+            if (BigInt(l[i].balance) >= minGas) {
+                chosen = l[i];
+                break;
+            }
+        }
+        if (!chosen)
+            throw new Error(`[coin-cache] gas 钱包 ${wallet} 无 ≥ ${minGas} 的 gas coin（需 split 补给）`);
+        this.walletMap(wallet).set(coinType, l.filter(c => c.objectId !== chosen.objectId));
+        this.inflight.set(txTag, { wallet, coinType, coins: [chosen], gas: true });
+        return { txTag, coin: chosen };
+    }
+    commit(txTag, changes) {
+        const res = this.inflight.get(txTag);
+        if (!res) {
+            (0, dist_1.log_warn)(`[coin-cache] commit 未知 txTag: ${txTag}`);
+            return;
+        }
+        this.inflight.delete(txTag);
+        for (const ch of changes) {
+            const wallet = res.wallet;
+            if (ch.kind === 'deleted') {
+                this.removeEverywhere(wallet, ch.coinType, ch.objectId);
+                continue;
+            }
+            if (ch.version == null || ch.digest == null) {
+                (0, dist_1.log_warn)(`[coin-cache] commit 跳过缺 version/digest 的 ${ch.kind} ${ch.objectId}`);
+                continue;
+            }
+            const old = this.list(wallet, ch.coinType).find(c => c.objectId === ch.objectId);
+            const balance = ch.balance ?? old?.balance ?? '0';
+            const ref = { objectId: ch.objectId, version: ch.version, digest: ch.digest, balance };
+            this.removeEverywhere(wallet, ch.coinType, ch.objectId);
+            const l = this.list(wallet, ch.coinType);
+            l.push(ref);
+            this.sortDesc(l);
+        }
+    }
+    abort(txTag, consumed) {
+        const res = this.inflight.get(txTag);
+        if (!res) {
+            (0, dist_1.log_warn)(`[coin-cache] abort 未知 txTag: ${txTag}`);
+            return;
+        }
+        this.inflight.delete(txTag);
+        if (consumed) {
+            (0, dist_1.log_warn)(`[coin-cache] abort consumed txTag=${txTag}（${res.coins.length} coin 交 reconcile 兜底）`);
+            return;
+        }
+        const l = this.list(res.wallet, res.coinType);
+        for (const c of res.coins)
+            if (!l.find(x => x.objectId === c.objectId))
+                l.push(c);
+        this.sortDesc(l);
+    }
+    removeEverywhere(wallet, coinType, objectId) {
+        const l = this.list(wallet, coinType);
+        const idx = l.findIndex(c => c.objectId === objectId);
+        if (idx >= 0)
+            l.splice(idx, 1);
+    }
+    snapshot(wallet, coinType) {
+        const l = this.list(wallet, coinType);
+        const total = l.reduce((s, c) => s + BigInt(c.balance), 0n);
+        return { count: l.length, total, coins: l.slice() };
+    }
+    inflightCount() { return this.inflight.size; }
+}
+exports.InProcessCoinCache = InProcessCoinCache;

package/dist/trade/executor/coin_maintainer.d.ts

@@ -0,0 +1,32 @@
+import { Ed25519Keypair } from '@mysten/sui/keypairs/ed25519';
+import { CentralExecutor } from './central_executor';
+import { ExecutorCore } from './core_channel';
+export interface CoinMaintainerOptions {
+    gasTarget?: number;
+    gasMin?: number;
+    gasMax?: number;
+    gasCoinSize?: bigint;
+    intervalMs?: number;
+    maintainGasBudget?: bigint;
+}
+export declare class CoinMaintainer {
+    private readonly core;
+    private readonly gasKeypair;
+    private readonly executor;
+    private readonly gasTarget;
+    private readonly gasMin;
+    private readonly gasMax;
+    private readonly gasCoinSize;
+    private readonly intervalMs;
+    private readonly maintainGasBudget;
+    private timer;
+    private running;
+    constructor(core: ExecutorCore, gasKeypair: Ed25519Keypair, executor: CentralExecutor, opts?: CoinMaintainerOptions);
+    start(): void;
+    stop(): void;
+    maintainGasPool(): Promise<void>;
+    private splitGasCoins;
+    private mergeGasCoins;
+    private sortedDesc;
+    private buildAndSend;
+}

package/dist/trade/executor/coin_maintainer.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CoinMaintainer = void 0;
+const dist_1 = require("@clonegod/ttd-core/dist");
+const transactions_1 = require("@mysten/sui/transactions");
+const effects_1 = require("./effects");
+const constants_1 = require("../../constants");
+class CoinMaintainer {
+    constructor(core, gasKeypair, executor, opts = {}) {
+        this.core = core;
+        this.gasKeypair = gasKeypair;
+        this.executor = executor;
+        this.timer = null;
+        this.running = false;
+        this.gasTarget = opts.gasTarget ?? Number(process.env.SUI_GAS_POOL_TARGET || 8);
+        this.gasMin = opts.gasMin ?? Number(process.env.SUI_GAS_POOL_MIN || 5);
+        this.gasMax = opts.gasMax ?? Number(process.env.SUI_GAS_POOL_MAX || 10);
+        this.gasCoinSize = opts.gasCoinSize ?? BigInt(process.env.SUI_GAS_COIN_SIZE || '150000000');
+        this.intervalMs = opts.intervalMs ?? Number(process.env.SUI_COIN_MAINTAIN_INTERVAL_MS || 30000);
+        this.maintainGasBudget = opts.maintainGasBudget ?? BigInt(process.env.SUI_MAINTAIN_GAS_BUDGET || '20000000');
+    }
+    start() {
+        if (this.timer)
+            return;
+        (0, dist_1.log_info)(`[maintainer] start: gas target=${this.gasTarget}[${this.gasMin}-${this.gasMax}], size=${this.gasCoinSize}, interval=${this.intervalMs}ms`);
+        const tick = async () => {
+            if (this.running)
+                return;
+            this.running = true;
+            try {
+                await this.maintainGasPool();
+            }
+            catch (e) {
+                (0, dist_1.log_error)('[maintainer] tick 失败', e);
+            }
+            finally {
+                this.running = false;
+            }
+        };
+        void tick();
+        this.timer = setInterval(tick, this.intervalMs);
+    }
+    stop() { if (this.timer) {
+        clearInterval(this.timer);
+        this.timer = null;
+    } }
+    async maintainGasPool() {
+        const gasAddr = this.executor.gasWalletAddress;
+        const snap = this.executor.coinCache.snapshot(gasAddr, constants_1.SUI_TOKEN_ADDRESS.LONG);
+        const count = snap.count;
+        if (count >= this.gasMin && count <= this.gasMax)
+            return;
+        if (count < this.gasMin)
+            await this.splitGasCoins(gasAddr, snap.coins, this.gasTarget - count);
+        else
+            await this.mergeGasCoins(gasAddr, snap.coins, count - this.gasTarget);
+        await this.executor.reconcileCoins(gasAddr, constants_1.SUI_TOKEN_ADDRESS.LONG);
+    }
+    async splitGasCoins(gasAddr, coins, n) {
+        if (n <= 0)
+            return;
+        const sorted = this.sortedDesc(coins);
+        const src = sorted[0];
+        const gasPay = sorted[1];
+        if (!src || !gasPay) {
+            (0, dist_1.log_warn)('[maintainer] gas coin 不足 2 个，无法独立挑 gas payment 做 split');
+            return;
+        }
+        const need = this.gasCoinSize * BigInt(n);
+        if (BigInt(src.balance) < need) {
+            (0, dist_1.log_warn)(`[maintainer] gas 源 coin ${src.balance} 不足 split ${n} × ${this.gasCoinSize}=${need}`);
+            return;
+        }
+        const tx = new transactions_1.Transaction();
+        tx.setSender(gasAddr);
+        const srcCoin = tx.object(transactions_1.Inputs.ObjectRef(src));
+        const amounts = Array.from({ length: n }, () => tx.pure.u64(this.gasCoinSize));
+        const newCoins = tx.splitCoins(srcCoin, amounts);
+        tx.transferObjects(Array.from({ length: n }, (_, i) => newCoins[i]), tx.pure.address(gasAddr));
+        await this.buildAndSend(tx, gasAddr, gasPay, `split ${n} gas coins`);
+    }
+    async mergeGasCoins(gasAddr, coins, n) {
+        if (n <= 0)
+            return;
+        const sorted = this.sortedDesc(coins);
+        const primary = sorted[0];
+        const toMerge = sorted.slice(-n).filter(c => c.objectId !== primary.objectId);
+        if (!toMerge.length)
+            return;
+        const mergeIds = new Set(toMerge.map(c => c.objectId));
+        const gasPay = sorted.find(c => c.objectId !== primary.objectId && !mergeIds.has(c.objectId));
+        if (!gasPay) {
+            (0, dist_1.log_warn)('[maintainer] 无空闲 gas coin 付 merge 交易 gas');
+            return;
+        }
+        const tx = new transactions_1.Transaction();
+        tx.setSender(gasAddr);
+        const primaryArg = tx.object(transactions_1.Inputs.ObjectRef(primary));
+        tx.mergeCoins(primaryArg, toMerge.map(c => tx.object(transactions_1.Inputs.ObjectRef(c))));
+        await this.buildAndSend(tx, gasAddr, gasPay, `merge ${toMerge.length} gas coins`);
+    }
+    sortedDesc(coins) {
+        return coins.slice().sort((a, b) => (BigInt(b.balance) > BigInt(a.balance) ? 1 : BigInt(b.balance) < BigInt(a.balance) ? -1 : 0));
+    }
+    async buildAndSend(tx, gasAddr, gasPay, label) {
+        try {
+            tx.setGasOwner(gasAddr);
+            tx.setGasPayment([{ objectId: gasPay.objectId, version: gasPay.version, digest: gasPay.digest }]);
+            tx.setGasBudget(this.maintainGasBudget);
+            tx.setGasPrice(BigInt((await this.core.getReferenceGasPrice()).referenceGasPrice));
+            const bytes = await tx.build();
+            const { signature } = await this.gasKeypair.signTransaction(bytes);
+            const resp = await this.core.executeTransaction({ transaction: bytes, signatures: [signature] });
+            const tr = resp.transaction;
+            const { success, error } = (0, effects_1.coreTxStatus)(tr.effects);
+            (0, dist_1.log_info)(`[maintainer] ${label} ${success ? 'OK' : 'FAILED'} digest=${tr.digest}${error ? ' err=' + error : ''}`);
+        }
+        catch (e) {
+            (0, dist_1.log_error)(`[maintainer] ${label} 失败`, e);
+        }
+    }
+}
+exports.CoinMaintainer = CoinMaintainer;

package/dist/trade/executor/core_channel.d.ts

@@ -0,0 +1,38 @@
+import { Experimental_CoreClient, Experimental_SuiClientTypes } from '@mysten/sui/experimental';
+export interface GrpcCoreOptions {
+    endpoint?: string;
+    token?: string;
+    network?: 'mainnet' | 'testnet' | 'devnet' | 'localnet';
+}
+export declare function buildGrpcCore(opts?: GrpcCoreOptions): Experimental_CoreClient;
+export interface GraphqlCoreOptions {
+    url?: string;
+}
+export declare function buildGraphqlCore(opts?: GraphqlCoreOptions): Experimental_CoreClient;
+export declare function buildDefaultCore(): Experimental_CoreClient;
+export type ExecutorCore = Pick<Experimental_CoreClient, 'getCoins' | 'getObjects' | 'executeTransaction' | 'dryRunTransaction'> & {
+    getReferenceGasPrice(): Promise<Experimental_SuiClientTypes.GetReferenceGasPriceResponse>;
+};
+export interface ResilientCoreOptions {
+    retries?: number;
+    readDeadlineMs?: number;
+    execDeadlineMs?: number;
+    gasPriceTtlMs?: number;
+}
+export declare class ResilientCore implements ExecutorCore {
+    private readonly primary;
+    private readonly fallback?;
+    private readonly retries;
+    private readonly readDeadlineMs;
+    private readonly execDeadlineMs;
+    private readonly gasPriceTtlMs;
+    private gasPriceCache?;
+    constructor(primary: Experimental_CoreClient, fallback?: Experimental_CoreClient, opts?: ResilientCoreOptions);
+    private read;
+    getCoins(o: Experimental_SuiClientTypes.GetCoinsOptions): Promise<Experimental_SuiClientTypes.GetCoinsResponse>;
+    getObjects(o: Experimental_SuiClientTypes.GetObjectsOptions): Promise<Experimental_SuiClientTypes.GetObjectsResponse>;
+    dryRunTransaction(o: Experimental_SuiClientTypes.DryRunTransactionOptions): Promise<Experimental_SuiClientTypes.DryRunTransactionResponse>;
+    getReferenceGasPrice(): Promise<Experimental_SuiClientTypes.GetReferenceGasPriceResponse>;
+    executeTransaction(o: Experimental_SuiClientTypes.ExecuteTransactionOptions): Promise<Experimental_SuiClientTypes.ExecuteTransactionResponse>;
+}
+export declare function buildResilientCore(opts?: ResilientCoreOptions): ResilientCore;