@ocap/resolver 1.28.8 → 1.29.0

package/lib/token-distribution.d.cts

@@ -0,0 +1,166 @@
+import { IChainConfig, IChunkIterator, IIndexDB, IIndexTable, IPipelineLogger, IResolverTransaction, IStateDB, IStateTable, ITokenInfo, TTokenDistribution } from "./types.cjs";
+import { BN } from "@ocap/util";
+
+//#region src/token-distribution.d.ts
+
+/**
+ * Token balance in array format (used in stake state for distribution)
+ */
+interface ITokenBalance {
+  address: string;
+  balance: string;
+  value?: string;
+}
+/**
+ * Stake state with array-format tokens (for distribution calculation)
+ */
+interface IDistributionStakeState {
+  address: string;
+  sender: string;
+  message: string;
+  tokens: ITokenBalance[];
+  revokedTokens: ITokenBalance[];
+  renaissanceTime?: string;
+}
+/**
+ * State snapshot for tracking token changes
+ */
+interface IStateSnapshot {
+  [address: string]: {
+    tokens: Record<string, string>;
+    revokedTokens: Record<string, string>;
+  };
+}
+/**
+ * Transaction context for distribution calculation
+ */
+interface IResolverTransactionContext {
+  txn?: unknown;
+  stateSnapshot?: IStateSnapshot;
+  stakeState?: {
+    tokens: Record<string, string>;
+    revokedTokens: Record<string, string>;
+  };
+  [key: string]: unknown;
+}
+/**
+ * Distribution with BN values (for calculation)
+ */
+interface IDistribution {
+  tokenAddress: string;
+  account: InstanceType<typeof BN>;
+  gas: InstanceType<typeof BN>;
+  fee: InstanceType<typeof BN>;
+  slashedVault: InstanceType<typeof BN>;
+  stake: InstanceType<typeof BN>;
+  revokedStake: InstanceType<typeof BN>;
+  gasStake: InstanceType<typeof BN>;
+  other: InstanceType<typeof BN>;
+  txTime: string;
+}
+/**
+ * Raw distribution input (string/number values)
+ */
+interface IRawDistribution {
+  tokenAddress: string;
+  account?: string | number;
+  gas?: string | number;
+  fee?: string | number;
+  slashedVault?: string | number;
+  stake?: string | number;
+  revokedStake?: string | number;
+  gasStake?: string | number;
+  other?: string | number;
+  txTime?: string;
+}
+/**
+ * Options for handleTx method
+ */
+interface IHandleTxOptions {
+  context?: IResolverTransactionContext;
+  isHandleStake?: boolean;
+}
+/**
+ * Resolver interface for TokenDistributionManager
+ */
+interface IDistributionResolver {
+  indexdb: IIndexDB;
+  statedb: IStateDB & {
+    stake: IStateTable<IDistributionStakeState>;
+  };
+  config: IChainConfig;
+  logger?: IPipelineLogger;
+  formatTx: (tx: IResolverTransaction) => Promise<IResolverTransaction & {
+    tokenSymbols: ITokenInfo[];
+  }>;
+  listTransactionsChunks: (params: {
+    timeFilter?: {
+      startDateTime: string;
+    };
+    tokenFilter?: {
+      tokenFilter?: {
+        tokens: string[];
+      };
+    };
+  }) => Promise<IChunkIterator<IResolverTransaction>>;
+  listStakeChunks: () => Promise<IChunkIterator<IDistributionStakeState>>;
+}
+/**
+ * TokenDistribution IndexDB table interface
+ */
+type ITokenDistributionTable = IIndexTable<TTokenDistribution> & {
+  insert: (data: TTokenDistribution) => Promise<void>;
+  update: (tokenAddress: string, data: TTokenDistribution) => Promise<void>;
+};
+declare class TokenDistributionManager {
+  resolver: IDistributionResolver;
+  indexdb: IIndexDB & {
+    tokenDistribution: ITokenDistributionTable;
+  };
+  isProcessing: boolean;
+  constructor(resolver: IDistributionResolver);
+  formatDistribution(distribution: IRawDistribution): IDistribution;
+  getDistribution(tokenAddress: string): Promise<TTokenDistribution | null>;
+  saveDistribution(distribution: IDistribution, isEnsureLatest?: boolean): Promise<TTokenDistribution>;
+  /**
+   * Calculate token distribution based on all transaction data.
+   * This method is usually used to update historical token distribution data
+   *
+   * @param tokenAddress Token address
+   * @param force If force is false, only calculate distributions for new transactions after txTime in indexdb. default is false
+   * @returns The updated token distribution or null if failed
+   */
+  updateByToken(tokenAddress: string, force?: boolean): Promise<TTokenDistribution | null | undefined>;
+  /**
+   * Split out revokedStake / gasStake from stake
+   *
+   * @param distribution The distribution object to update
+   * @returns The updated distribution
+   */
+  splitStake(distribution: IDistribution): Promise<IDistribution>;
+  /**
+   * Update token distribution by a single transaction.
+   * This method is usually used when a tx is completed.
+   *
+   * @param tx The transaction object
+   * @param context The transaction context
+   * @returns The updated token distributions
+   */
+  updateByTx(tx: IResolverTransaction, context: IResolverTransactionContext): Promise<TTokenDistribution[] | undefined>;
+  /**
+   * Parse token distribution for a single transaction
+   * @param tx The transaction
+   * @param distribution The distribution to update
+   * @param options Handle options
+   * @returns The updated token distribution
+   */
+  handleTx(tx: IResolverTransaction, distribution: IDistribution, {
+    context,
+    isHandleStake
+  }?: IHandleTxOptions): Promise<IDistribution>;
+  handleModerator(distribution: IDistribution): IDistribution;
+  getStakeState(address: string, ctx: IResolverTransactionContext): Promise<IDistributionStakeState>;
+  isGasStake(stakeState: IDistributionStakeState): boolean;
+}
+//#endregion
+export { TokenDistributionManager };

package/lib/token-flow.cjs

@@ -0,0 +1,336 @@
+const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+let _ocap_util = require("@ocap/util");
+let _arcblock_validator = require("@arcblock/validator");
+let _ocap_util_lib_error = require("@ocap/util/lib/error");
+let lodash_uniq = require("lodash/uniq");
+lodash_uniq = require_rolldown_runtime.__toESM(lodash_uniq);
+let _ocap_state_lib_states_tx = require("@ocap/state/lib/states/tx");
+
+//#region src/token-flow.ts
+const ZERO = new _ocap_util.BN(0);
+const paramsSchema = _arcblock_validator.Joi.object({
+	accountAddress: _arcblock_validator.schemas.tokenHolder.required(),
+	tokenAddress: _arcblock_validator.Joi.DID().prefix().role("ROLE_TOKEN").required(),
+	resolver: _arcblock_validator.Joi.object().required()
+});
+/**
+* Parse transfer in/out list from transaction
+* @param tx Transaction object
+* @param tokenAddress Token address to filter by
+* @returns Object containing transferInList and transferOutList
+*/
+const getTransferList = (tx, tokenAddress) => {
+	const transferInList = [];
+	const transferOutList = [];
+	for (const receipt of tx.receipts || []) {
+		const changes = receipt.changes.filter((item) => item.target === tokenAddress && item.value !== "0");
+		for (const change of changes) {
+			const value = new _ocap_util.BN(change.value);
+			const item = {
+				address: receipt.address,
+				value: value.abs(),
+				action: change.action
+			};
+			if (value.lt(ZERO)) transferOutList.push(item);
+			else transferInList.push(item);
+		}
+	}
+	return {
+		transferInList,
+		transferOutList
+	};
+};
+/**
+* Parse transfer flow from transaction
+* @param tx Transaction object
+* @param tokenAddress Token address to filter by
+* @returns Array of transfer flows
+*/
+const getTransferFlow = (tx, tokenAddress) => {
+	const { transferInList, transferOutList } = getTransferList(tx, tokenAddress);
+	const txTransfers = [];
+	for (const outItem of transferOutList) {
+		if (outItem.archived) continue;
+		const matchedInItem = transferInList.find((x) => x.value.eq(outItem.value));
+		if (matchedInItem) {
+			txTransfers.push({
+				from: outItem.address,
+				to: matchedInItem.address,
+				value: outItem.value,
+				hash: tx.hash
+			});
+			matchedInItem.archived = true;
+			outItem.archived = true;
+			continue;
+		}
+		for (const inItem of transferInList) {
+			if (inItem.archived) continue;
+			if (outItem.archived) continue;
+			if (outItem.value.gt(inItem.value)) {
+				txTransfers.push({
+					from: outItem.address,
+					to: inItem.address,
+					value: inItem.value,
+					hash: tx.hash
+				});
+				inItem.archived = true;
+				outItem.value = outItem.value.sub(inItem.value);
+				continue;
+			}
+			if (outItem.value.lt(inItem.value)) {
+				txTransfers.push({
+					from: outItem.address,
+					to: inItem.address,
+					value: outItem.value,
+					hash: tx.hash
+				});
+				outItem.archived = true;
+				inItem.value = inItem.value.sub(outItem.value);
+				continue;
+			}
+			if (outItem.value.eq(inItem.value)) {
+				txTransfers.push({
+					from: outItem.address,
+					to: inItem.address,
+					value: inItem.value,
+					hash: tx.hash
+				});
+				inItem.archived = true;
+				outItem.archived = true;
+			}
+		}
+	}
+	return txTransfers;
+};
+const getVaultAccounts = (config) => {
+	return Object.values(config.vaults).flat().concat(_ocap_state_lib_states_tx.FORGE_TOKEN_HOLDER);
+};
+const getInitialBalance = (address, config) => {
+	const account = config?.accounts?.find((x) => (0, _ocap_util.isSameDid)(x.address, address));
+	return account ? (0, _ocap_util.fromTokenToUnit)(account.balance ?? 0) : ZERO;
+};
+const getBalance = async (address, tokenAddress, { resolver, txn }) => {
+	const state = await resolver.statedb.account.get(address, {
+		txn,
+		traceMigration: false
+	});
+	if (!state) throw new _ocap_util_lib_error.CustomError("INVALID_REQUEST", `Invalid address ${address}`);
+	return state.tokens[tokenAddress] || 0;
+};
+const fixMigrateReceipts = async (tx, resolver) => {
+	const migrationChain = await resolver.getMigrationChain();
+	const txTime = new Date(tx.time);
+	tx.receipts?.forEach((receipt) => {
+		receipt.address = migrationChain.findAddressAtTime(receipt.address, txTime);
+	});
+};
+const verifyAccountRisk = async ({ accountAddress, tokenAddress, accountLimit = 400, txLimit = 1e4, tolerance = "0.0000000001" }, resolver, ctx = {}) => {
+	const validation = paramsSchema.validate({
+		accountAddress,
+		tokenAddress,
+		resolver
+	});
+	if (validation.error) throw new _ocap_util_lib_error.CustomError("INVALID_PARAMS", validation.error.message);
+	const { logger } = resolver;
+	const checkedAccounts = /* @__PURE__ */ new Map();
+	const checkedTx = /* @__PURE__ */ new Map();
+	const toleranceUnit = (0, _ocap_util.fromTokenToUnit)(tolerance, (await resolver.tokenCache.get(tokenAddress))?.decimal);
+	const vaultAccounts = getVaultAccounts(resolver.config);
+	const accountQueue = [[{
+		address: accountAddress,
+		chain: []
+	}]];
+	const execute = async (depth, txn) => {
+		const queue = accountQueue[depth];
+		for (let i = 0; i < queue.length; i++) {
+			if (checkedAccounts.size >= accountLimit) {
+				logger.warn("Account risk check reached max account size limit", {
+					address: accountAddress,
+					tokenAddress,
+					accountCount: checkedAccounts.size,
+					txCount: checkedTx.size,
+					depth,
+					accountLimit,
+					txLimit,
+					tolerance
+				});
+				return {
+					isRisky: false,
+					reason: "MAX_ACCOUNT_SIZE_LIMIT",
+					data: {
+						accountCount: checkedAccounts.size,
+						txCount: checkedTx.size
+					}
+				};
+			}
+			const { address, chain } = queue[i];
+			chain.push(address);
+			if (checkedAccounts.has(address)) continue;
+			const trustedConfig = await resolver.filter?.getTrustedAccountConfig?.(address);
+			if (trustedConfig && !trustedConfig.tolerance) {
+				checkedAccounts.set(address, true);
+				continue;
+			}
+			let balance = 0;
+			let transactions = [];
+			try {
+				[balance, transactions] = await Promise.all([getBalance(address, tokenAddress, {
+					resolver,
+					txn
+				}), resolver._getAllResults("transactions", (paging) => resolver.listTransactions({
+					paging,
+					accountFilter: { accounts: [address] }
+				}, ctx), txLimit)]);
+			} catch (e) {
+				if (e?.code === "EXCEED_LIMIT") {
+					logger.warn("Skip checking account cause tx count exceeding limit", {
+						address,
+						txLimit
+					});
+					checkedAccounts.set(address, true);
+					continue;
+				}
+				throw e;
+			}
+			let transferIn = getInitialBalance(address, resolver.config);
+			let transferOut = ZERO;
+			for (const tx of transactions) {
+				if (!checkedTx.has(tx.hash)) {
+					await fixMigrateReceipts(tx, resolver);
+					checkedTx.set(tx.hash, getTransferList(tx, tokenAddress));
+				}
+				const { transferInList, transferOutList } = checkedTx.get(tx.hash);
+				const transferInAmount = transferInList.filter((item) => (0, _ocap_util.isSameDid)(item.address, address)).map((item) => item.value).reduce((prev, cur) => prev.add(cur), ZERO);
+				const transferOutAmount = transferOutList.filter((item) => (0, _ocap_util.isSameDid)(item.address, address)).map((item) => item.value).reduce((prev, cur) => prev.add(cur), ZERO);
+				transferIn = transferIn.add(transferInAmount);
+				transferOut = transferOut.add(transferOutAmount);
+				if (transferInAmount.gt(ZERO)) {
+					if (!accountQueue[depth + 1]) accountQueue[depth + 1] = [];
+					const accountsToQueue = transferOutList.filter((item) => {
+						if (checkedAccounts.has(item.address)) return false;
+						if (_arcblock_validator.schemas.tokenHolder.validate(item.address).error) return false;
+						if (vaultAccounts.includes(item.address)) return false;
+						if (["gas", "fee"].includes(item.action || "")) return false;
+						return true;
+					}).map((item) => item.address);
+					accountQueue[depth + 1].push(...(0, lodash_uniq.default)(accountsToQueue).map((x) => ({
+						address: x,
+						chain: chain.concat()
+					})));
+				}
+			}
+			checkedAccounts.set(address, true);
+			const diff = transferIn.sub(transferOut).sub(new _ocap_util.BN(balance)).add((0, _ocap_util.fromTokenToUnit)(trustedConfig?.tolerance || 0));
+			if (diff.abs().gt(toleranceUnit)) {
+				const data = {
+					address: chain.join("->"),
+					balance,
+					transferIn: transferIn.toString(),
+					transferOut: transferOut.toString(),
+					accountCount: checkedAccounts.size,
+					txCount: checkedTx.size
+				};
+				logger.warn("Account balance does not match transfer records", {
+					...data,
+					sourceAccount: accountAddress,
+					tokenAddress,
+					diff: diff.toString(),
+					depth,
+					accountLimit,
+					txLimit,
+					tolerance
+				});
+				return {
+					isRisky: true,
+					reason: "INVALID_BALANCE",
+					data
+				};
+			}
+		}
+	};
+	for (let depth = 0; depth < accountQueue.length; depth++) {
+		let isExecuted = false;
+		const result = await resolver.runAsLambda((txn) => {
+			if (isExecuted) throw new _ocap_util_lib_error.CustomError("INVALID_REQUEST", "verifyAccountRisk should not retry");
+			isExecuted = true;
+			return execute(depth, txn);
+		}, { retryLimit: 0 });
+		if (result) return result;
+	}
+	logger.info("Account risk check completed", {
+		address: accountAddress,
+		tokenAddress,
+		accountCount: checkedAccounts.size,
+		txCount: checkedTx.size,
+		depth: accountQueue.length,
+		accountLimit,
+		txLimit,
+		tolerance
+	});
+	return {
+		isRisky: false,
+		data: {
+			accountCount: checkedAccounts.size,
+			txCount: checkedTx.size
+		}
+	};
+};
+const listTokenFlows = async ({ accountAddress, tokenAddress, paging = {}, depth = 2, direction = "OUT" }, resolver, ctx = {}) => {
+	const { error } = paramsSchema.validate({
+		accountAddress,
+		tokenAddress,
+		resolver
+	});
+	if (error) throw new _ocap_util_lib_error.CustomError("INVALID_PARAMS", error.message);
+	const minAmount = (0, _ocap_util.fromTokenToUnit)(1, (await resolver.tokenCache.get(tokenAddress))?.decimal || 18);
+	const maxAccountSize = Math.min(200, paging.size || 200);
+	const maxDepth = Math.min(5, depth);
+	const vaultAccounts = getVaultAccounts(resolver.config);
+	const tokenFlows = [];
+	const checkedAccounts = /* @__PURE__ */ new Map();
+	const checkedTx = /* @__PURE__ */ new Map();
+	let curDepth = 1;
+	const depthQueue = { [curDepth]: [accountAddress] };
+	while (depthQueue[curDepth]?.length && curDepth <= maxDepth && checkedAccounts.size < maxAccountSize) {
+		for (const address of depthQueue[curDepth]) {
+			if (checkedAccounts.has(address)) continue;
+			if (_arcblock_validator.schemas.tokenHolder.validate(address).error) continue;
+			const transactions = await resolver._getAllResults("transactions", (page) => resolver.listTransactions({
+				paging: page,
+				accountFilter: { accounts: [address] },
+				tokenFilter: { tokens: [tokenAddress] }
+			}, ctx));
+			let accountsToQueue = [];
+			for (const tx of transactions) {
+				if (!checkedTx.has(tx.hash)) {
+					await fixMigrateReceipts(tx, resolver);
+					checkedTx.set(tx.hash, getTransferFlow(tx, tokenAddress));
+				}
+				const txTransfers = checkedTx.get(tx.hash).filter((item) => {
+					if (direction === "OUT" && item.from !== address) return false;
+					if (direction === "IN" && item.to !== address) return false;
+					if (item.value.lt(minAmount)) return false;
+					return true;
+				});
+				tokenFlows.push(...txTransfers.map((item) => ({
+					...item,
+					value: item.value.toString()
+				})));
+				accountsToQueue = accountsToQueue.concat(txTransfers.map((item) => direction === "IN" ? item.from : item.to).filter((item) => !vaultAccounts.includes(item)));
+			}
+			checkedAccounts.set(address, true);
+			if (checkedAccounts.size >= maxAccountSize) break;
+			if (!depthQueue[curDepth + 1]) depthQueue[curDepth + 1] = [];
+			depthQueue[curDepth + 1].push(...(0, lodash_uniq.default)(accountsToQueue));
+		}
+		curDepth++;
+	}
+	return tokenFlows;
+};
+
+//#endregion
+exports.fixMigrateReceipts = fixMigrateReceipts;
+exports.getTransferFlow = getTransferFlow;
+exports.getTransferList = getTransferList;
+exports.listTokenFlows = listTokenFlows;
+exports.verifyAccountRisk = verifyAccountRisk;

package/lib/token-flow.d.cts

@@ -0,0 +1,139 @@
+import { IChainConfig, IFilter, IMigrationChain, IPipelineLogger, IResolverPaging, IStateDB, ITokenCache, TTransactionReceipt } from "./types.cjs";
+import { BN } from "@ocap/util";
+
+//#region src/token-flow.d.ts
+
+/**
+ * Transfer item with BN value for calculation
+ */
+interface ITransferItem {
+  address: string;
+  value: InstanceType<typeof BN>;
+  action?: string;
+  archived?: boolean;
+}
+/**
+ * Transfer flow with BN value
+ */
+interface ITransferFlow {
+  from: string;
+  to: string;
+  value: InstanceType<typeof BN>;
+  hash: string;
+}
+/**
+ * Transfer flow result with string value
+ */
+interface ITransferFlowResult {
+  from: string;
+  to: string;
+  value: string;
+  hash: string;
+}
+/**
+ * Risk check result
+ */
+interface IRiskCheckResult {
+  isRisky: boolean;
+  reason?: string;
+  data: {
+    address?: string;
+    balance?: string | number;
+    transferIn?: string;
+    transferOut?: string;
+    accountCount: number;
+    txCount: number;
+  };
+}
+/**
+ * Parameters for verifyAccountRisk
+ */
+interface IVerifyAccountRiskParams {
+  accountAddress: string;
+  tokenAddress: string;
+  accountLimit?: number;
+  txLimit?: number;
+  tolerance?: string;
+}
+/**
+ * Parameters for listTokenFlows
+ */
+interface IListTokenFlowsParams {
+  accountAddress: string;
+  tokenAddress: string;
+  paging?: IResolverPaging;
+  depth?: number;
+  direction?: 'IN' | 'OUT';
+}
+/**
+ * Simplified transaction for token flow
+ */
+interface ITokenFlowTx {
+  hash: string;
+  time: string;
+  receipts?: TTransactionReceipt[];
+  [key: string]: unknown;
+}
+/**
+ * Resolver interface for token flow operations
+ */
+interface ITokenFlowResolver {
+  config: IChainConfig;
+  tokenCache: ITokenCache;
+  filter?: IFilter;
+  logger: IPipelineLogger;
+  statedb: IStateDB;
+  getMigrationChain: () => Promise<IMigrationChain>;
+  _getAllResults: <T>(type: string, fetcher: (paging: IResolverPaging) => Promise<{
+    transactions?: T[];
+    data?: T[];
+  }>, limit?: number) => Promise<T[]>;
+  listTransactions: (params: {
+    paging?: IResolverPaging;
+    accountFilter?: {
+      accounts: string[];
+    };
+    tokenFilter?: {
+      tokens: string[];
+    };
+  }, ctx?: Record<string, unknown>) => Promise<{
+    transactions: ITokenFlowTx[];
+  }>;
+  runAsLambda: <T>(fn: (txn: unknown) => Promise<T>, options?: {
+    retryLimit?: number;
+  }) => Promise<T>;
+}
+/**
+ * Parse transfer in/out list from transaction
+ * @param tx Transaction object
+ * @param tokenAddress Token address to filter by
+ * @returns Object containing transferInList and transferOutList
+ */
+declare const getTransferList: (tx: ITokenFlowTx, tokenAddress: string) => {
+  transferInList: ITransferItem[];
+  transferOutList: ITransferItem[];
+};
+/**
+ * Parse transfer flow from transaction
+ * @param tx Transaction object
+ * @param tokenAddress Token address to filter by
+ * @returns Array of transfer flows
+ */
+declare const getTransferFlow: (tx: ITokenFlowTx, tokenAddress: string) => ITransferFlow[];
+declare const fixMigrateReceipts: (tx: ITokenFlowTx, resolver: ITokenFlowResolver) => Promise<void>;
+declare const verifyAccountRisk: ({
+  accountAddress,
+  tokenAddress,
+  accountLimit,
+  txLimit,
+  tolerance
+}: IVerifyAccountRiskParams, resolver: ITokenFlowResolver, ctx?: Record<string, unknown>) => Promise<IRiskCheckResult>;
+declare const listTokenFlows: ({
+  accountAddress,
+  tokenAddress,
+  paging,
+  depth,
+  direction
+}: IListTokenFlowsParams, resolver: ITokenFlowResolver, ctx?: Record<string, unknown>) => Promise<ITransferFlowResult[]>;
+//#endregion
+export { fixMigrateReceipts, getTransferFlow, getTransferList, listTokenFlows, verifyAccountRisk };