@ocap/resolver 1.28.8 → 1.29.0

package/esm/migration-chain.d.mts

@@ -0,0 +1,52 @@
+//#region src/migration-chain.d.ts
+interface Migration {
+  time: string;
+  tx: {
+    from: string;
+    itxJson: {
+      address: string;
+    };
+  };
+}
+declare class MigrationNode {
+  address: string;
+  validFrom: Date;
+  validUntil: Date | null;
+  nextAddress: string | null;
+  constructor(address: string, validFrom: Date, validUntil?: Date | null, nextAddress?: string | null);
+}
+declare class MigrationChainManager {
+  chains: Map<string, MigrationNode[]>;
+  rootAddresses: Map<string, string>;
+  constructor();
+  validateMigration(migration: Migration): boolean;
+  /**
+   * Build migration chains from a list of migration transactions
+   * @param migrations - List of migration transactions
+   */
+  buildChains(migrations: Migration[]): void;
+  /**
+   * Process a single migration and update the chains
+   * @param fromAddr - Source address
+   * @param toAddr - Destination address
+   * @param timestamp - Migration timestamp
+   */
+  private _processMigration;
+  /**
+   * Find the valid address at a specific timestamp
+   * @param address - Address to look up
+   * @param timestamp - Timestamp to check
+   * @returns Valid address at the timestamp
+   */
+  findAddressAtTime(address: string, timestamp: Date): string;
+  formatAddress(address: string): string;
+  getRootAddress(address: string): string;
+  /**
+   * Get the complete migration history for an address
+   * @param address - Address to look up
+   * @returns List of migration nodes
+   */
+  getMigrationHistory(address: string): MigrationNode[];
+}
+//#endregion
+export { MigrationChainManager, MigrationNode };

package/esm/migration-chain.mjs

@@ -0,0 +1,97 @@
+import { isEthereumDid } from "@arcblock/did";
+
+//#region src/migration-chain.ts
+var MigrationNode = class {
+	constructor(address, validFrom, validUntil = null, nextAddress = null) {
+		this.address = address;
+		this.validFrom = validFrom;
+		this.validUntil = validUntil;
+		this.nextAddress = nextAddress;
+	}
+};
+var MigrationChainManager = class {
+	constructor() {
+		this.chains = /* @__PURE__ */ new Map();
+		this.rootAddresses = /* @__PURE__ */ new Map();
+	}
+	validateMigration(migration) {
+		if (!migration?.tx?.from || !migration?.tx?.itxJson?.address || !migration?.time) throw new Error("Invalid migration format");
+		if (new Date(migration.time).toString() === "Invalid Date") throw new Error("Invalid timestamp");
+		return true;
+	}
+	/**
+	* Build migration chains from a list of migration transactions
+	* @param migrations - List of migration transactions
+	*/
+	buildChains(migrations) {
+		if (!Array.isArray(migrations)) throw new Error("Migrations must be an array");
+		migrations.forEach((migration) => this.validateMigration(migration));
+		const sortedMigrations = [...migrations].sort((a, b) => new Date(a.time).getTime() - new Date(b.time).getTime());
+		for (const migration of sortedMigrations) {
+			const fromAddr = migration.tx.from;
+			const toAddr = migration.tx.itxJson.address;
+			const timestamp = new Date(migration.time);
+			this._processMigration(fromAddr, toAddr, timestamp);
+		}
+	}
+	/**
+	* Process a single migration and update the chains
+	* @param fromAddr - Source address
+	* @param toAddr - Destination address
+	* @param timestamp - Migration timestamp
+	*/
+	_processMigration(fromAddr, toAddr, timestamp) {
+		const rootAddr = this.getRootAddress(fromAddr);
+		if (!this.chains.has(rootAddr)) this.chains.set(rootAddr, []);
+		const chain = this.chains.get(rootAddr);
+		if (chain.length === 0) {
+			chain.push(new MigrationNode(fromAddr, /* @__PURE__ */ new Date(0), timestamp));
+			chain.push(new MigrationNode(toAddr, timestamp));
+		} else {
+			const lastNode = chain[chain.length - 1];
+			lastNode.validUntil = timestamp;
+			lastNode.nextAddress = toAddr;
+			chain.push(new MigrationNode(toAddr, timestamp));
+		}
+		this.rootAddresses.set(this.formatAddress(toAddr), rootAddr);
+	}
+	/**
+	* Find the valid address at a specific timestamp
+	* @param address - Address to look up
+	* @param timestamp - Timestamp to check
+	* @returns Valid address at the timestamp
+	*/
+	findAddressAtTime(address, timestamp) {
+		const chains = this.getMigrationHistory(address);
+		if (!chains?.length) return address;
+		let left = 0;
+		let right = chains.length - 1;
+		while (left <= right) {
+			const mid = Math.floor((left + right) / 2);
+			const node = chains[mid];
+			if (node.validFrom <= timestamp && (!node.validUntil || timestamp < node.validUntil)) return node.address;
+			if (timestamp < node.validFrom) right = mid - 1;
+			else left = mid + 1;
+		}
+		return chains[chains.length - 1].address;
+	}
+	formatAddress(address) {
+		return isEthereumDid(address) ? address.toLowerCase() : address;
+	}
+	getRootAddress(address) {
+		const formattedAddress = this.formatAddress(address);
+		return this.rootAddresses.get(formattedAddress) || formattedAddress;
+	}
+	/**
+	* Get the complete migration history for an address
+	* @param address - Address to look up
+	* @returns List of migration nodes
+	*/
+	getMigrationHistory(address) {
+		const rootAddr = this.getRootAddress(address);
+		return this.chains.get(rootAddr) || [];
+	}
+};
+
+//#endregion
+export { MigrationChainManager, MigrationNode };

package/esm/package.mjs

@@ -0,0 +1,5 @@
+//#region package.json
+var name = "@ocap/resolver";
+
+//#endregion
+export { name };

package/esm/token-cache.d.mts

@@ -0,0 +1,20 @@
+import { TIndexedTokenState } from "./types.mjs";
+
+//#region src/token-cache.d.ts
+
+/**
+ * Token DB adapter interface for cache
+ */
+interface ITokenDBAdapter {
+  get(address: string): Promise<TIndexedTokenState | null>;
+}
+declare class Cache {
+  private dbAdapter;
+  private cache;
+  constructor(dbAdapter: ITokenDBAdapter);
+  get(address: string): Promise<TIndexedTokenState | null | undefined>;
+  set(address: string, token: TIndexedTokenState): TIndexedTokenState;
+}
+declare function getInstance(dbAdapter: ITokenDBAdapter): Cache;
+//#endregion
+export { getInstance };

package/esm/token-cache.mjs

@@ -0,0 +1,26 @@
+//#region src/token-cache.ts
+var Cache = class {
+	constructor(dbAdapter) {
+		this.dbAdapter = dbAdapter;
+		this.cache = /* @__PURE__ */ new Map();
+	}
+	async get(address) {
+		if (this.cache.has(address)) return this.cache.get(address);
+		const token = await this.dbAdapter.get(address);
+		if (token) this.cache.set(address, token);
+		return token;
+	}
+	set(address, token) {
+		this.cache.set(address, token);
+		return token;
+	}
+};
+let cache = null;
+function getInstance(dbAdapter) {
+	if (cache !== null) return cache;
+	cache = new Cache(dbAdapter);
+	return cache;
+}
+
+//#endregion
+export { getInstance };

package/esm/token-distribution.d.mts

@@ -0,0 +1,166 @@
+import { IChainConfig, IChunkIterator, IIndexDB, IIndexTable, IPipelineLogger, IResolverTransaction, IStateDB, IStateTable, ITokenInfo, TTokenDistribution } from "./types.mjs";
+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/esm/token-distribution.mjs

@@ -0,0 +1,241 @@
+import { BN, fromTokenToUnit, isSameDid } from "@ocap/util";
+import { toTypeInfo } from "@arcblock/did";
+import { types } from "@ocap/mcrypto";
+import { isGasStakeAddress } from "@ocap/tx-protocols/lib/util";
+import omit from "lodash/omit.js";
+import { createIndexedTokenDistribution } from "@ocap/indexdb/lib/util";
+import { eachReceipts } from "@ocap/state/lib/states/tx";
+
+//#region src/token-distribution.ts
+const { RoleType } = types;
+const ZERO = new BN(0);
+var TokenDistributionManager = class {
+	constructor(resolver) {
+		this.resolver = resolver;
+		this.indexdb = resolver.indexdb;
+		this.isProcessing = false;
+	}
+	formatDistribution(distribution) {
+		const { tokenAddress, account, gas, fee, slashedVault, stake, revokedStake, gasStake, other, txTime } = distribution;
+		return {
+			tokenAddress,
+			account: new BN(account || 0),
+			gas: new BN(gas || 0),
+			fee: new BN(fee || 0),
+			slashedVault: new BN(slashedVault || 0),
+			stake: new BN(stake || 0),
+			revokedStake: new BN(revokedStake || 0),
+			gasStake: new BN(gasStake || 0),
+			other: new BN(other || 0),
+			txTime: txTime || (/* @__PURE__ */ new Date(0)).toISOString()
+		};
+	}
+	async getDistribution(tokenAddress) {
+		const data = await this.indexdb.tokenDistribution.get(tokenAddress);
+		return data && createIndexedTokenDistribution(data);
+	}
+	async saveDistribution(distribution, isEnsureLatest = true) {
+		const data = createIndexedTokenDistribution(distribution);
+		const indexdbDistribution = await this.getDistribution(data.tokenAddress);
+		if (!indexdbDistribution) await this.indexdb.tokenDistribution.insert(data);
+		else {
+			if (isEnsureLatest) {
+				const latestTime = Math.max(new Date(indexdbDistribution.txTime).getTime(), new Date(data.txTime).getTime());
+				data.txTime = new Date(latestTime).toISOString();
+			}
+			await this.indexdb.tokenDistribution.update(data.tokenAddress, data);
+		}
+		return data;
+	}
+	/**
+	* 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
+	*/
+	async updateByToken(tokenAddress, force) {
+		const { logger, config } = this.resolver;
+		if (this.isProcessing) {
+			logger?.debug?.("Token distribution is already in progress", {
+				tokenAddress,
+				force
+			});
+			return;
+		}
+		const distribution = force ? this.formatDistribution({ tokenAddress }) : this.formatDistribution(await this.getDistribution(tokenAddress) || { tokenAddress });
+		const isDefaultToken = tokenAddress === config.token.address;
+		logger?.info(`Update distribution by token (${tokenAddress})`, { distribution: createIndexedTokenDistribution(distribution) });
+		this.isProcessing = true;
+		try {
+			if (force && isDefaultToken) this.handleModerator(distribution);
+			const { next } = await this.resolver.listTransactionsChunks({
+				timeFilter: { startDateTime: distribution.txTime },
+				tokenFilter: isDefaultToken ? {} : { tokenFilter: { tokens: [tokenAddress] } }
+			});
+			let nextData = await next();
+			while (nextData.length) {
+				logger?.info("Updating token distribution in chunks", {
+					chunkSize: nextData.length,
+					startTime: nextData[0].time,
+					startHash: nextData[0].hash,
+					endTime: nextData[nextData.length - 1].time
+				});
+				const handlePromises = nextData.map((tx) => this.handleTx(tx, distribution));
+				await Promise.all(handlePromises);
+				await this.saveDistribution(distribution, false);
+				nextData = await next();
+			}
+			await this.splitStake(distribution);
+			await this.saveDistribution(distribution, false);
+			const result = createIndexedTokenDistribution(distribution);
+			logger?.info(`Token distribution update completed (${tokenAddress})`, { distribution: result });
+			return result;
+		} catch (e) {
+			logger?.error("Token distribution update failed", { error: e });
+			return null;
+		} finally {
+			this.isProcessing = false;
+		}
+	}
+	/**
+	* Split out revokedStake / gasStake from stake
+	*
+	* @param distribution The distribution object to update
+	* @returns The updated distribution
+	*/
+	async splitStake(distribution) {
+		const { logger } = this.resolver;
+		const { tokenAddress } = distribution;
+		const { next } = await this.resolver.listStakeChunks();
+		let nextData = await next();
+		while (nextData.length) {
+			logger?.info("Updating stake distribution in chunks", {
+				chunkSize: nextData.length,
+				startTime: nextData[0].renaissanceTime,
+				startAddress: nextData[0].address,
+				endTime: nextData[nextData.length - 1].renaissanceTime
+			});
+			nextData.forEach((stakeState) => {
+				const isGasStake = this.isGasStake(stakeState);
+				const token = stakeState.tokens.find((x) => x.address === tokenAddress);
+				const revokedBalance = new BN(stakeState.revokedTokens.find((x) => x.address === tokenAddress)?.balance || 0);
+				const balance = new BN(token?.balance || 0);
+				distribution.revokedStake = distribution.revokedStake.add(revokedBalance);
+				distribution.stake = distribution.stake.sub(revokedBalance);
+				if (isGasStake) {
+					distribution.gasStake = distribution.gasStake.add(balance);
+					distribution.stake = distribution.stake.sub(balance);
+				}
+			});
+			nextData = await next();
+		}
+		return distribution;
+	}
+	/**
+	* 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
+	*/
+	async updateByTx(tx, context) {
+		const { logger } = this.resolver;
+		const ctx = omit(context, "txn");
+		if (this.isProcessing) {
+			logger?.debug?.("Token distribution is already in progress", { tx });
+			return;
+		}
+		const tokens = (await this.resolver.formatTx(tx)).tokenSymbols.map(({ address }) => address);
+		return await Promise.all(tokens.map(async (tokenAddress) => {
+			const distribution = this.formatDistribution(await this.getDistribution(tokenAddress) || { tokenAddress });
+			await this.handleTx(tx, distribution, {
+				context: ctx,
+				isHandleStake: true
+			});
+			return await this.saveDistribution(distribution);
+		}));
+	}
+	/**
+	* 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
+	*/
+	async handleTx(tx, distribution, { context, isHandleStake = false } = {}) {
+		if (isHandleStake && !context) throw new Error("context is missing, handle revoke stake is not supported without context");
+		const type = tx.tx?.itxJson?._type;
+		const receipts = tx.receipts || [];
+		const { tokenAddress } = distribution;
+		const handlePromises = eachReceipts(receipts, async (address, change) => {
+			if (!isSameDid(change.target, tokenAddress)) return;
+			if (change.action === "migrate") return;
+			const roleType = toTypeInfo(address).role;
+			const value = new BN(change.value);
+			if (roleType === RoleType.ROLE_STAKE) {
+				if (isHandleStake) {
+					const stakeState = await this.getStakeState(address, context);
+					const isGasStakeResult = this.isGasStake(stakeState);
+					if (type === "ClaimStakeTx") {
+						distribution.revokedStake = distribution.revokedStake.add(value);
+						return;
+					}
+					if (type === "SlashStakeTx") {
+						const beforeState = context.stateSnapshot[address];
+						const afterState = context.stakeState;
+						if (!beforeState || !afterState) throw new Error("stake state is missing on slash stake tx");
+						const revokeTokenDiff = new BN(beforeState.revokedTokens[tokenAddress]).sub(new BN(afterState.revokedTokens[tokenAddress]));
+						const tokenDiff = new BN(beforeState.tokens[tokenAddress]).sub(new BN(afterState.tokens[tokenAddress]));
+						distribution.revokedStake = distribution.revokedStake.sub(revokeTokenDiff);
+						if (isGasStakeResult) distribution.gasStake = distribution.gasStake.sub(tokenDiff);
+						else distribution.stake = distribution.stake.sub(tokenDiff);
+						return;
+					}
+					if (isGasStakeResult) {
+						distribution.gasStake = distribution.gasStake.add(value);
+						return;
+					}
+				}
+				distribution.stake = distribution.stake.add(value);
+			} else if (change.action === "gas" && value.gt(ZERO)) distribution.gas = distribution.gas.add(value);
+			else if (change.action === "fee" && value.gt(ZERO)) distribution.fee = distribution.fee.add(value);
+			else if (type === "SlashStakeTx" && value.gt(ZERO) && isSameDid(address, this.resolver.config.vaults.slashedStake ?? "")) distribution.slashedVault = distribution.slashedVault.add(value);
+			else distribution.account = distribution.account.add(value);
+		});
+		await Promise.all(handlePromises);
+		if (isHandleStake && type === "RevokeStakeTx") {
+			const { address } = tx.tx.itxJson;
+			const stakeState = await this.getStakeState(address, context);
+			const isGasStakeResult = this.isGasStake(stakeState);
+			tx.tx.itxJson.outputs.forEach((x) => {
+				x.tokens.filter((change) => isSameDid(change.address, tokenAddress)).forEach((change) => {
+					const value = new BN(change.value || change.balance || 0);
+					distribution.revokedStake = distribution.revokedStake.add(value);
+					if (isGasStakeResult) distribution.gasStake = distribution.gasStake.sub(value);
+					else distribution.stake = distribution.stake.sub(value);
+				});
+			});
+		}
+		distribution.txTime = tx.time;
+		return distribution;
+	}
+	handleModerator(distribution) {
+		const { config } = this.resolver;
+		if (distribution.tokenAddress !== config.token.address) return distribution;
+		const value = config.accounts.filter((account) => Number(account.balance) > 0).map((account) => new BN(account.balance)).reduce((cur, balance) => cur.add(balance), ZERO);
+		distribution.account = distribution.account.add(fromTokenToUnit(value.toString()));
+		return distribution;
+	}
+	async getStakeState(address, ctx) {
+		return await this.resolver.statedb.stake.get(address, ctx);
+	}
+	isGasStake(stakeState) {
+		return isGasStakeAddress(stakeState.sender, stakeState.address) && stakeState.message === "stake-for-gas";
+	}
+};
+
+//#endregion
+export { TokenDistributionManager };