sol-parser-sdk-nodejs 0.3.0 → 0.4.0

package/dist/grpc/geyser_connect.js

@@ -0,0 +1,40 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultGeyserConnectConfig = defaultGeyserConnectConfig;
+exports.geyserGrpcChannelOptions = geyserGrpcChannelOptions;
+exports.connectYellowstoneGeyser = connectYellowstoneGeyser;
+const yellowstone_grpc_1 = __importDefault(require("@triton-one/yellowstone-grpc"));
+/** 与 Rust `GeyserConnectConfig::default` 一致 */
+function defaultGeyserConnectConfig() {
+    return {
+        connectTimeoutMs: 8000,
+        maxDecodingMessageSize: 1024 * 1024 * 1024,
+        xToken: undefined,
+        keepAliveIntervalMs: 30_000,
+        keepAliveTimeoutMs: 5000,
+    };
+}
+/** 与 `ClientConfig` / `grpc.keepalive_*` 对齐，用于长连接抗 NAT/负载均衡 idle 断开 */
+function geyserGrpcChannelOptions(config = defaultGeyserConnectConfig()) {
+    const max = config.maxDecodingMessageSize;
+    const interval = config.keepAliveIntervalMs ?? 30_000;
+    const timeout = config.keepAliveTimeoutMs ?? 5000;
+    return {
+        "grpc.max_receive_message_length": max,
+        "grpc.max_send_message_length": max,
+        "grpc.keepalive_time_ms": interval,
+        "grpc.keepalive_timeout_ms": timeout,
+        /** 无活跃 RPC 时仍发 keepalive，避免长时间仅订阅时被中间设备掐断 */
+        "grpc.keepalive_permit_without_calls": 1,
+    };
+}
+/**
+ * 建立 Yellowstone Geyser 客户端（与 Rust `connect_yellowstone_geyser` 一致）。
+ * Rust 为 async；此处构造同步完成，返回 `Promise` 以保持 `await connectYellowstoneGeyser(...)` 写法。
+ */
+async function connectYellowstoneGeyser(endpoint, config = defaultGeyserConnectConfig()) {
+    return new yellowstone_grpc_1.default(endpoint, config.xToken, geyserGrpcChannelOptions(config));
+}

package/dist/grpc/program_ids.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 与 Rust `sol-parser-sdk/src/grpc/program_ids.rs` 对齐的 DEX 程序 ID 与协议映射。
+ */
+import type { Protocol } from "./types.js";
+import type { AccountFilter, TransactionFilter } from "./types.js";
+export declare const PUMPFUN_PROGRAM_ID = "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P";
+export declare const PUMPSWAP_PROGRAM_ID = "pAMMBay6oceH9fJKBRHGP5D4bD4sWpmSwMn52FMfXEA";
+export declare const PUMPSWAP_FEES_PROGRAM_ID = "pfeeUxB6jkeY1Hxd7CsFCAjcbHA9rWtchMGdZ6VojVZ";
+/** 与 Rust `BONK_PROGRAM_ID`（`Protocol::Bonk`）一致 */
+export declare const BONK_PROGRAM_ID = "BSwp6bEBihVLdqJRKS58NaebUBSDNjN7MdpFwNaR6gn3";
+export declare const RAYDIUM_CPMM_PROGRAM_ID = "CPMMoo8L3F4NbTegBCKVNunggL7H1ZpdTHKxQB5qKP1C";
+export declare const RAYDIUM_CLMM_PROGRAM_ID = "CAMMCzo5YL8w4VFF8KVHrK22GGUQtcaMpgYqJPXBDvfE";
+export declare const RAYDIUM_AMM_V4_PROGRAM_ID = "675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8";
+export declare const ORCA_WHIRLPOOL_PROGRAM_ID = "whirLbMiicVdio4qvUfM5KAg6Ct8VwpYzGff3uctyCc";
+export declare const METEORA_POOLS_PROGRAM_ID = "Eo7WjKq67rjJQSZxS6z3YkapzY3eMj6Xy8X5EQVn5UaB";
+export declare const METEORA_DAMM_V2_PROGRAM_ID = "cpamdpZCGKUy5JxQXB4dcpGPiikHawvSWAd6mEn1sGG";
+export declare const METEORA_DLMM_PROGRAM_ID = "LBUZKhRxPF3XUpBCjp4YzTKgLccjZhTSDM9YuVaPwxo";
+/** 与 Rust `PROTOCOL_PROGRAM_IDS` 一致（仅含 Rust 中存在的协议） */
+export declare const PROTOCOL_PROGRAM_IDS: Record<Protocol, readonly string[]>;
+/** 与 Rust `get_program_ids_for_protocols` 一致 */
+export declare function getProgramIdsForProtocols(protocols: readonly Protocol[]): string[];
+/** 与 Rust `TransactionFilter::for_protocols` 一致 */
+export declare function transactionFilterForProtocols(protocols: readonly Protocol[]): TransactionFilter;
+/** 与 Rust `AccountFilter::for_protocols` 一致 */
+export declare function accountFilterForProtocols(protocols: readonly Protocol[]): AccountFilter;

package/dist/grpc/program_ids.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROTOCOL_PROGRAM_IDS = exports.METEORA_DLMM_PROGRAM_ID = exports.METEORA_DAMM_V2_PROGRAM_ID = exports.METEORA_POOLS_PROGRAM_ID = exports.ORCA_WHIRLPOOL_PROGRAM_ID = exports.RAYDIUM_AMM_V4_PROGRAM_ID = exports.RAYDIUM_CLMM_PROGRAM_ID = exports.RAYDIUM_CPMM_PROGRAM_ID = exports.BONK_PROGRAM_ID = exports.PUMPSWAP_FEES_PROGRAM_ID = exports.PUMPSWAP_PROGRAM_ID = exports.PUMPFUN_PROGRAM_ID = void 0;
+exports.getProgramIdsForProtocols = getProgramIdsForProtocols;
+exports.transactionFilterForProtocols = transactionFilterForProtocols;
+exports.accountFilterForProtocols = accountFilterForProtocols;
+exports.PUMPFUN_PROGRAM_ID = "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P";
+exports.PUMPSWAP_PROGRAM_ID = "pAMMBay6oceH9fJKBRHGP5D4bD4sWpmSwMn52FMfXEA";
+exports.PUMPSWAP_FEES_PROGRAM_ID = "pfeeUxB6jkeY1Hxd7CsFCAjcbHA9rWtchMGdZ6VojVZ";
+/** 与 Rust `BONK_PROGRAM_ID`（`Protocol::Bonk`）一致 */
+exports.BONK_PROGRAM_ID = "BSwp6bEBihVLdqJRKS58NaebUBSDNjN7MdpFwNaR6gn3";
+exports.RAYDIUM_CPMM_PROGRAM_ID = "CPMMoo8L3F4NbTegBCKVNunggL7H1ZpdTHKxQB5qKP1C";
+exports.RAYDIUM_CLMM_PROGRAM_ID = "CAMMCzo5YL8w4VFF8KVHrK22GGUQtcaMpgYqJPXBDvfE";
+exports.RAYDIUM_AMM_V4_PROGRAM_ID = "675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8";
+exports.ORCA_WHIRLPOOL_PROGRAM_ID = "whirLbMiicVdio4qvUfM5KAg6Ct8VwpYzGff3uctyCc";
+exports.METEORA_POOLS_PROGRAM_ID = "Eo7WjKq67rjJQSZxS6z3YkapzY3eMj6Xy8X5EQVn5UaB";
+exports.METEORA_DAMM_V2_PROGRAM_ID = "cpamdpZCGKUy5JxQXB4dcpGPiikHawvSWAd6mEn1sGG";
+exports.METEORA_DLMM_PROGRAM_ID = "LBUZKhRxPF3XUpBCjp4YzTKgLccjZhTSDM9YuVaPwxo";
+/** 与 Rust `PROTOCOL_PROGRAM_IDS` 一致（仅含 Rust 中存在的协议） */
+exports.PROTOCOL_PROGRAM_IDS = {
+    PumpFun: [exports.PUMPFUN_PROGRAM_ID],
+    PumpSwap: [exports.PUMPSWAP_PROGRAM_ID],
+    Bonk: [exports.BONK_PROGRAM_ID],
+    RaydiumCpmm: [exports.RAYDIUM_CPMM_PROGRAM_ID],
+    RaydiumClmm: [exports.RAYDIUM_CLMM_PROGRAM_ID],
+    RaydiumAmmV4: [exports.RAYDIUM_AMM_V4_PROGRAM_ID],
+    MeteoraDammV2: [exports.METEORA_DAMM_V2_PROGRAM_ID],
+};
+/** 与 Rust `get_program_ids_for_protocols` 一致 */
+function getProgramIdsForProtocols(protocols) {
+    const out = [];
+    for (const p of protocols) {
+        const ids = exports.PROTOCOL_PROGRAM_IDS[p];
+        if (ids)
+            out.push(...ids);
+    }
+    return [...new Set(out)].sort();
+}
+/** 与 Rust `TransactionFilter::for_protocols` 一致 */
+function transactionFilterForProtocols(protocols) {
+    return {
+        account_include: getProgramIdsForProtocols(protocols),
+        account_exclude: [],
+        account_required: [],
+    };
+}
+/** 与 Rust `AccountFilter::for_protocols` 一致 */
+function accountFilterForProtocols(protocols) {
+    return {
+        account: [],
+        owner: getProgramIdsForProtocols(protocols),
+        filters: [],
+    };
+}

package/dist/grpc/rpc_to_grpc.d.ts

@@ -0,0 +1,18 @@
+import type { Transaction as YTransaction, TransactionStatusMeta } from "@triton-one/yellowstone-grpc/dist/grpc/solana-storage.js";
+import { type VersionedTransactionResponse } from "@solana/web3.js";
+import type { ParseError } from "../core/error.js";
+export type ConvertRpcToGrpcOk = {
+    ok: true;
+    meta: TransactionStatusMeta;
+    transaction: YTransaction;
+};
+export type ConvertRpcToGrpcErr = {
+    ok: false;
+    error: ParseError;
+};
+/**
+ * 与 Rust `convert_rpc_to_grpc` 对齐：输入为 RPC `getTransaction` 的 **非 jsonParsed**、已编译 message 的响应。
+ */
+export declare function convertRpcToGrpc(tx: VersionedTransactionResponse): ConvertRpcToGrpcOk | ConvertRpcToGrpcErr;
+/** Rust 蛇形命名 */
+export declare const convert_rpc_to_grpc: typeof convertRpcToGrpc;

package/dist/grpc/rpc_to_grpc.js

@@ -0,0 +1,127 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.convert_rpc_to_grpc = void 0;
+exports.convertRpcToGrpc = convertRpcToGrpc;
+/**
+ * 将 `@solana/web3.js` 的 `VersionedTransactionResponse` 转为 Yellowstone `Transaction` + `TransactionStatusMeta`，
+ * 与 Rust `rpc_parser::convert_rpc_to_grpc` 字段取舍一致（token balances / rewards 置空，err 置空等）。
+ */
+const bs58_1 = __importDefault(require("bs58"));
+const rpc_invoke_map_js_1 = require("../core/rpc_invoke_map.js");
+function toYCompiled(ix) {
+    const accounts = "accountKeyIndexes" in ix ? ix.accountKeyIndexes : ix.accounts;
+    return {
+        programIdIndex: ix.programIdIndex,
+        accounts: Uint8Array.from(accounts),
+        data: (0, rpc_invoke_map_js_1.decodeIxData)(ix.data),
+    };
+}
+function toYInnerInstruction(ix) {
+    const stackHeight = ix.stackHeight;
+    return {
+        programIdIndex: ix.programIdIndex,
+        accounts: Uint8Array.from(ix.accounts),
+        data: (0, rpc_invoke_map_js_1.decodeIxData)(ix.data),
+        ...(stackHeight !== undefined ? { stackHeight } : {}),
+    };
+}
+function legacyMessageToYellowstone(msg) {
+    return {
+        header: {
+            numRequiredSignatures: msg.header.numRequiredSignatures,
+            numReadonlySignedAccounts: msg.header.numReadonlySignedAccounts,
+            numReadonlyUnsignedAccounts: msg.header.numReadonlyUnsignedAccounts,
+        },
+        accountKeys: msg.accountKeys.map((k) => new Uint8Array(k.toBytes())),
+        recentBlockhash: new Uint8Array(bs58_1.default.decode(msg.recentBlockhash)),
+        instructions: msg.compiledInstructions.map(toYCompiled),
+        versioned: false,
+        addressTableLookups: [],
+    };
+}
+function v0MessageToYellowstone(msg) {
+    const lookups = msg.addressTableLookups.map((l) => ({
+        accountKey: new Uint8Array(l.accountKey.toBytes()),
+        writableIndexes: l.writableIndexes instanceof Uint8Array ? l.writableIndexes : Uint8Array.from(l.writableIndexes),
+        readonlyIndexes: l.readonlyIndexes instanceof Uint8Array ? l.readonlyIndexes : Uint8Array.from(l.readonlyIndexes),
+    }));
+    return {
+        header: {
+            numRequiredSignatures: msg.header.numRequiredSignatures,
+            numReadonlySignedAccounts: msg.header.numReadonlySignedAccounts,
+            numReadonlyUnsignedAccounts: msg.header.numReadonlyUnsignedAccounts,
+        },
+        accountKeys: msg.staticAccountKeys.map((k) => new Uint8Array(k.toBytes())),
+        recentBlockhash: new Uint8Array(bs58_1.default.decode(msg.recentBlockhash)),
+        instructions: msg.compiledInstructions.map(toYCompiled),
+        versioned: true,
+        addressTableLookups: lookups,
+    };
+}
+function metaToYellowstone(meta) {
+    const innerGroups = meta.innerInstructions;
+    const innerInstructions = [];
+    if (innerGroups) {
+        for (const g of innerGroups) {
+            innerInstructions.push({
+                index: g.index,
+                instructions: g.instructions.map(toYInnerInstruction),
+            });
+        }
+    }
+    const loaded = meta.loadedAddresses;
+    const loadedWritable = loaded?.writable.map((k) => new Uint8Array(k.toBytes())) ?? [];
+    const loadedReadonly = loaded?.readonly.map((k) => new Uint8Array(k.toBytes())) ?? [];
+    const logs = meta.logMessages ?? [];
+    return {
+        err: undefined,
+        fee: String(meta.fee),
+        preBalances: meta.preBalances.map(String),
+        postBalances: meta.postBalances.map(String),
+        innerInstructions,
+        innerInstructionsNone: innerGroups == null,
+        logMessages: [...logs],
+        logMessagesNone: logs.length === 0,
+        preTokenBalances: [],
+        postTokenBalances: [],
+        rewards: [],
+        loadedWritableAddresses: loadedWritable,
+        loadedReadonlyAddresses: loadedReadonly,
+        returnData: undefined,
+        returnDataNone: true,
+        computeUnitsConsumed: meta.computeUnitsConsumed !== undefined ? String(meta.computeUnitsConsumed) : undefined,
+    };
+}
+/**
+ * 与 Rust `convert_rpc_to_grpc` 对齐：输入为 RPC `getTransaction` 的 **非 jsonParsed**、已编译 message 的响应。
+ */
+function convertRpcToGrpc(tx) {
+    const msg = tx.transaction?.message;
+    if (!msg || !(0, rpc_invoke_map_js_1.isCompiledVersionedMessage)(msg)) {
+        return {
+            ok: false,
+            error: {
+                kind: "ConversionError",
+                message: "交易 message 非编译形态（例如 jsonParsed）。请使用默认编码的 getTransaction 响应后再转换。",
+            },
+        };
+    }
+    const meta = tx.meta;
+    if (meta == null) {
+        return {
+            ok: false,
+            error: { kind: "MissingField", field: "meta" },
+        };
+    }
+    const yMsg = msg.version === "legacy" ? legacyMessageToYellowstone(msg) : v0MessageToYellowstone(msg);
+    const transaction = {
+        signatures: tx.transaction.signatures.map((s) => new Uint8Array(bs58_1.default.decode(s))),
+        message: yMsg,
+    };
+    return { ok: true, meta: metaToYellowstone(meta), transaction };
+}
+/** Rust 蛇形命名 */
+exports.convert_rpc_to_grpc = convertRpcToGrpc;

package/dist/grpc/subscribe_builder.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Yellowstone `SubscribeRequest` 构造（与 Rust `grpc/subscribe_builder` 对齐）。
+ */
+import type { SubscribeRequest } from "@triton-one/yellowstone-grpc";
+import { CommitmentLevel } from "@triton-one/yellowstone-grpc";
+import type { AccountFilter, TransactionFilter } from "./types.js";
+export declare function buildSubscribeRequest(txFilters: TransactionFilter[], accFilters: AccountFilter[]): SubscribeRequest;
+export declare function buildSubscribeRequestWithCommitment(txFilters: TransactionFilter[], accFilters: AccountFilter[], commitment: CommitmentLevel): SubscribeRequest;
+export declare function buildSubscribeTransactionFiltersNamed(namedTxFilters: readonly {
+    name: string;
+    filter: TransactionFilter;
+}[], accFilters: AccountFilter[], commitment: CommitmentLevel): SubscribeRequest;
+export { CommitmentLevel };

package/dist/grpc/subscribe_builder.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommitmentLevel = void 0;
+exports.buildSubscribeRequest = buildSubscribeRequest;
+exports.buildSubscribeRequestWithCommitment = buildSubscribeRequestWithCommitment;
+exports.buildSubscribeTransactionFiltersNamed = buildSubscribeTransactionFiltersNamed;
+const yellowstone_grpc_1 = require("@triton-one/yellowstone-grpc");
+Object.defineProperty(exports, "CommitmentLevel", { enumerable: true, get: function () { return yellowstone_grpc_1.CommitmentLevel; } });
+function txFilterToProto(f) {
+    return {
+        vote: false,
+        failed: false,
+        signature: undefined,
+        accountInclude: f.account_include,
+        accountExclude: f.account_exclude,
+        accountRequired: f.account_required,
+    };
+}
+function accFilterToProto(f) {
+    return {
+        account: f.account,
+        owner: f.owner,
+        filters: f.filters,
+        nonemptyTxnSignature: undefined,
+    };
+}
+function finalize(transactions, accounts, commitment) {
+    return {
+        slots: {},
+        accounts,
+        transactions,
+        transactionsStatus: {},
+        blocks: {},
+        blocksMeta: {},
+        entry: {},
+        commitment,
+        accountsDataSlice: [],
+        ping: undefined,
+        fromSlot: undefined,
+    };
+}
+function buildSubscribeRequest(txFilters, accFilters) {
+    return buildSubscribeRequestWithCommitment(txFilters, accFilters, yellowstone_grpc_1.CommitmentLevel.PROCESSED);
+}
+function buildSubscribeRequestWithCommitment(txFilters, accFilters, commitment) {
+    const transactions = {};
+    txFilters.forEach((f, i) => {
+        transactions[`tx_${i}`] = txFilterToProto(f);
+    });
+    const accounts = {};
+    accFilters.forEach((f, i) => {
+        accounts[`acc_${i}`] = accFilterToProto(f);
+    });
+    return finalize(transactions, accounts, commitment);
+}
+function buildSubscribeTransactionFiltersNamed(namedTxFilters, accFilters, commitment) {
+    const transactions = {};
+    for (const { name, filter } of namedTxFilters) {
+        transactions[name] = txFilterToProto(filter);
+    }
+    const accounts = {};
+    accFilters.forEach((f, i) => {
+        accounts[`acc_${i}`] = accFilterToProto(f);
+    });
+    return finalize(transactions, accounts, commitment);
+}

package/dist/grpc/transaction_meta.d.ts

@@ -0,0 +1,29 @@
+import type { TokenBalance, Transaction, TransactionStatusMeta } from "@triton-one/yellowstone-grpc/dist/grpc/solana-storage.js";
+/** 32 字节公钥 → Base58（无效长度返回 `null`） */
+export declare function pubkeyBytesToBs58(bytes: Uint8Array): string | null;
+/**
+ * 消息静态 `accountKeys` + meta 中 `loadedWritableAddresses` / `loadedReadonlyAddresses`，
+ * 顺序与 `preBalances` / `postBalances` 对齐。
+ */
+export declare function collectAccountKeysBs58(tx: Transaction, meta: TransactionStatusMeta): string[] | null;
+/** 每个账户索引的 lamports 变化（post − pre） */
+export declare function lamportBalanceDeltas(meta: TransactionStatusMeta): bigint[];
+/**
+ * 启发式原生 SOL：对 `watchedBs58` 中出现的账户，若 lamports 净减少 ≥ `minOutflowLamports`，
+ * 再与其它索引配对，要求对方 delta ≥ `minOutflowLamports/2`。
+ */
+export declare function heuristicSolCounterpartiesForWatchedKeys(accountKeysBs58: string[], lamportDeltas: bigint[], watchedBs58: Set<string>, minOutflowLamports: bigint): [string, string][];
+/** `TokenBalance.uiTokenAmount.amount` → 原始整数；解析失败为 `0n` */
+export declare function tokenBalanceRawAmount(t: TokenBalance): bigint;
+/**
+ * SPL：当 `watchOwnerBs58` 在某 mint 上余额净减少 ≥ `minWatchDecreaseRaw` 时，
+ * 找同 mint 下余额增加的其它 owner，返回 `(watch_owner, counterparty_owner)`。
+ */
+export declare function splTokenCounterpartyByOwner(meta: TransactionStatusMeta, watchOwnerBs58: string, minWatchDecreaseRaw: bigint): [string, string][];
+/**
+ * 汇总监控地址在一笔交易中的转出对手方（原生 SOL 启发式 + SPL token balance 启发式）。
+ * 若账户 key 与 balance 数组长度不一致则返回 `null`。
+ */
+export declare function collectWatchTransferCounterpartyPairs(tx: Transaction, meta: TransactionStatusMeta, watchedBs58: string[], minNativeOutflowLamports: bigint, splMinWatchDecreaseRaw: bigint): [string, string][] | null;
+/** Yellowstone 交易签名原始字节（64）→ Base58 签名字符串；长度非 64 返回 `null` */
+export declare function tryYellowstoneSignature(sig: Uint8Array): string | null;

package/dist/grpc/transaction_meta.js

@@ -0,0 +1,208 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pubkeyBytesToBs58 = pubkeyBytesToBs58;
+exports.collectAccountKeysBs58 = collectAccountKeysBs58;
+exports.lamportBalanceDeltas = lamportBalanceDeltas;
+exports.heuristicSolCounterpartiesForWatchedKeys = heuristicSolCounterpartiesForWatchedKeys;
+exports.tokenBalanceRawAmount = tokenBalanceRawAmount;
+exports.splTokenCounterpartyByOwner = splTokenCounterpartyByOwner;
+exports.collectWatchTransferCounterpartyPairs = collectWatchTransferCounterpartyPairs;
+exports.tryYellowstoneSignature = tryYellowstoneSignature;
+/**
+ * Yellowstone `Transaction` / `TransactionStatusMeta` 通用工具（与 Rust `grpc/transaction_meta` 对齐）。
+ * 不依赖 DEX 日志解析，用于 mentions 订阅后的 SOL/SPL 转账启发式分析等。
+ */
+const bs58_1 = __importDefault(require("bs58"));
+const web3_js_1 = require("@solana/web3.js");
+/** 32 字节公钥 → Base58（无效长度返回 `null`） */
+function pubkeyBytesToBs58(bytes) {
+    if (bytes.length !== 32)
+        return null;
+    try {
+        return new web3_js_1.PublicKey(bytes).toBase58();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 消息静态 `accountKeys` + meta 中 `loadedWritableAddresses` / `loadedReadonlyAddresses`，
+ * 顺序与 `preBalances` / `postBalances` 对齐。
+ */
+function collectAccountKeysBs58(tx, meta) {
+    const msg = tx.message;
+    if (!msg)
+        return null;
+    const keys = [];
+    for (const b of msg.accountKeys) {
+        const s = pubkeyBytesToBs58(b);
+        if (!s)
+            continue;
+        keys.push(s);
+    }
+    for (const b of meta.loadedWritableAddresses) {
+        const s = pubkeyBytesToBs58(b);
+        if (!s)
+            continue;
+        keys.push(s);
+    }
+    for (const b of meta.loadedReadonlyAddresses) {
+        const s = pubkeyBytesToBs58(b);
+        if (!s)
+            continue;
+        keys.push(s);
+    }
+    return keys;
+}
+/** 每个账户索引的 lamports 变化（post − pre） */
+function lamportBalanceDeltas(meta) {
+    const n = Math.min(meta.preBalances.length, meta.postBalances.length);
+    const out = [];
+    for (let i = 0; i < n; i++) {
+        out.push(BigInt(meta.postBalances[i] ?? "0") - BigInt(meta.preBalances[i] ?? "0"));
+    }
+    return out;
+}
+/**
+ * 启发式原生 SOL：对 `watchedBs58` 中出现的账户，若 lamports 净减少 ≥ `minOutflowLamports`，
+ * 再与其它索引配对，要求对方 delta ≥ `minOutflowLamports/2`。
+ */
+function heuristicSolCounterpartiesForWatchedKeys(accountKeysBs58, lamportDeltas, watchedBs58, minOutflowLamports) {
+    const minL = minOutflowLamports;
+    const half = minL / 2n;
+    const pairs = [];
+    for (let i = 0; i < accountKeysBs58.length; i++) {
+        const key = accountKeysBs58[i];
+        if (!watchedBs58.has(key))
+            continue;
+        const d = lamportDeltas[i] ?? 0n;
+        if (d >= -minL)
+            continue;
+        for (let j = 0; j < lamportDeltas.length; j++) {
+            if (i === j)
+                continue;
+            const dj = lamportDeltas[j] ?? 0n;
+            if (dj <= half)
+                continue;
+            pairs.push([key, accountKeysBs58[j]]);
+        }
+    }
+    return pairs;
+}
+/** `TokenBalance.uiTokenAmount.amount` → 原始整数；解析失败为 `0n` */
+function tokenBalanceRawAmount(t) {
+    const a = t.uiTokenAmount?.amount;
+    if (a === undefined || a === "")
+        return 0n;
+    try {
+        return BigInt(a);
+    }
+    catch {
+        return 0n;
+    }
+}
+function mapKey(mint, owner) {
+    return `${mint}\0${owner}`;
+}
+function parseMapKey(k) {
+    const i = k.indexOf("\0");
+    if (i <= 0)
+        return null;
+    return { mint: k.slice(0, i), owner: k.slice(i + 1) };
+}
+/**
+ * SPL：当 `watchOwnerBs58` 在某 mint 上余额净减少 ≥ `minWatchDecreaseRaw` 时，
+ * 找同 mint 下余额增加的其它 owner，返回 `(watch_owner, counterparty_owner)`。
+ */
+function splTokenCounterpartyByOwner(meta, watchOwnerBs58, minWatchDecreaseRaw) {
+    const pre = meta.preTokenBalances ?? [];
+    const post = meta.postTokenBalances ?? [];
+    const preM = new Map();
+    for (const b of pre) {
+        if (!b.owner)
+            continue;
+        const k = mapKey(b.mint, b.owner);
+        preM.set(k, (preM.get(k) ?? 0n) + tokenBalanceRawAmount(b));
+    }
+    const postM = new Map();
+    for (const b of post) {
+        if (!b.owner)
+            continue;
+        const k = mapKey(b.mint, b.owner);
+        postM.set(k, (postM.get(k) ?? 0n) + tokenBalanceRawAmount(b));
+    }
+    const mints = new Set();
+    for (const k of preM.keys()) {
+        const p = parseMapKey(k);
+        if (p && p.owner === watchOwnerBs58)
+            mints.add(p.mint);
+    }
+    for (const k of postM.keys()) {
+        const p = parseMapKey(k);
+        if (p && p.owner === watchOwnerBs58)
+            mints.add(p.mint);
+    }
+    const out = [];
+    const minL = minWatchDecreaseRaw > 0n ? minWatchDecreaseRaw : 1n;
+    for (const mint of mints) {
+        const wPre = preM.get(mapKey(mint, watchOwnerBs58)) ?? 0n;
+        const wPost = postM.get(mapKey(mint, watchOwnerBs58)) ?? 0n;
+        const lost = wPre > wPost ? wPre - wPost : 0n;
+        if (lost < minL)
+            continue;
+        for (const [k, po] of postM) {
+            const parsed = parseMapKey(k);
+            if (!parsed || parsed.mint !== mint || parsed.owner === watchOwnerBs58)
+                continue;
+            const pr = preM.get(k) ?? 0n;
+            if (po > pr) {
+                out.push([watchOwnerBs58, parsed.owner]);
+            }
+        }
+    }
+    out.sort((a, b) => a[1].localeCompare(b[1]));
+    const dedup = [];
+    for (const p of out) {
+        const prev = dedup[dedup.length - 1];
+        if (prev && prev[0] === p[0] && prev[1] === p[1])
+            continue;
+        dedup.push(p);
+    }
+    return dedup;
+}
+/**
+ * 汇总监控地址在一笔交易中的转出对手方（原生 SOL 启发式 + SPL token balance 启发式）。
+ * 若账户 key 与 balance 数组长度不一致则返回 `null`。
+ */
+function collectWatchTransferCounterpartyPairs(tx, meta, watchedBs58, minNativeOutflowLamports, splMinWatchDecreaseRaw) {
+    const keys = collectAccountKeysBs58(tx, meta);
+    if (!keys)
+        return null;
+    const n = keys.length;
+    if (meta.preBalances.length !== n || meta.postBalances.length !== n)
+        return null;
+    const deltas = lamportBalanceDeltas(meta);
+    const watchedH = new Set(watchedBs58);
+    const pairs = heuristicSolCounterpartiesForWatchedKeys(keys, deltas, watchedH, minNativeOutflowLamports);
+    for (const w of watchedBs58) {
+        pairs.push(...splTokenCounterpartyByOwner(meta, w, splMinWatchDecreaseRaw));
+    }
+    pairs.sort((a, b) => a[1].localeCompare(b[1]));
+    const dedup = [];
+    for (const p of pairs) {
+        const prev = dedup[dedup.length - 1];
+        if (prev && prev[0] === p[0] && prev[1] === p[1])
+            continue;
+        dedup.push(p);
+    }
+    return dedup;
+}
+/** Yellowstone 交易签名原始字节（64）→ Base58 签名字符串；长度非 64 返回 `null` */
+function tryYellowstoneSignature(sig) {
+    if (sig.length !== 64)
+        return null;
+    return bs58_1.default.encode(sig);
+}