@clayno-club/asset-flow 0.1.3 → 0.1.4

package/README.md

@@ -1,14 +1,19 @@
 # @clayno-club/asset-flow
 
-Deterministic Solana NFT asset-flow classification and normalization.
+Deterministic asset-flow classification and normalization for supported chains.
 
-This package turns transaction data into a canonical ownership history for a mint. It is designed for consumers that want consistent classification results across services, codebases, or audit pipelines.
+This package turns transaction data into a canonical ownership history for a tracked asset. It is designed for consumers that want consistent classification results across services, codebases, or audit pipelines.
+
+Current support:
+
+- Solana NFT asset-flow normalization via the root convenience exports such as `classify`, `buildFlows`, and `buildOwnershipPeriods`
+- Sui Popkins classification via explicit Sui exports such as `classifySuiTransactionForAsset`
 
 ## What it does
 
-- classify enhanced Solana transactions for a tracked mint
-- merge raw ownership evidence into enhanced transactions when needed
-- normalize a mint's transaction history into canonical flows
+- classify supported chain transactions for a tracked asset
+- merge raw ownership evidence into enhanced Solana transactions when needed
+- normalize an asset's transaction history into canonical flows
 - derive ownership periods from normalized flows
 - explain why a transaction matched a given classification path
 - analyze provided transaction sets for review candidates
@@ -21,6 +26,11 @@ This package turns transaction data into a canonical ownership history for a min
 
 You provide the transaction data. The package provides deterministic interpretation.
 
+## Supported entrypoints
+
+- Root exports: Solana-oriented convenience API such as `classify`, `buildMintHistory`, `buildFlows`, `buildValueMovements`, and `augmentWithRaw`
+- Sui exports: explicit helpers such as `classifySuiTransactionForAsset` and the Sui transaction/type definitions
+
 ## Install
 
 ```bash

package/dist/index.d.ts

@@ -152,6 +152,53 @@ interface NormalizedMintHistory {
     periods: ReconstructedOwnershipPeriod[];
 }
 
+declare function classifyEnhancedTransactionForMint(tx: HeliusEnhancedTx, mint: string): AssetFlowTxClassification;
+
+interface AssetFlowCoverageReviewCandidate {
+    mint: string;
+    signature: string;
+    timestamp: number | null;
+    source: string;
+    normalizedType: string;
+    matcherId: string;
+    family: AssetFlowTxClassification["family"];
+    effect: AssetFlowTxClassification["effect"];
+    materialization: AssetFlowTxClassification["materialization"];
+    confidence: AssetFlowTxClassification["confidence"];
+    reason: AssetFlowTxClassification["reason"];
+    hasOwnershipChange: boolean;
+    hasMeaningfulSettlement: boolean;
+    programIds: string[];
+    instructionLabels: string[];
+}
+interface AssetFlowCoverageCluster {
+    fingerprint: string;
+    matcherId: string;
+    family: AssetFlowTxClassification["family"];
+    effect: AssetFlowTxClassification["effect"];
+    materialization: AssetFlowTxClassification["materialization"];
+    confidence: AssetFlowTxClassification["confidence"];
+    normalizedType: string;
+    source: string;
+    reason: AssetFlowTxClassification["reason"];
+    hasOwnershipChange: boolean;
+    hasMeaningfulSettlement: boolean;
+    programIds: string[];
+    instructionLabels: string[];
+    count: number;
+    sampleSignatures: string[];
+    sampleMints: string[];
+}
+interface AssetFlowCoverageScanResult {
+    mint: string;
+    transactionsScanned: number;
+    reviewCandidates: AssetFlowCoverageReviewCandidate[];
+    clusters: AssetFlowCoverageCluster[];
+}
+declare function collectCoverageReviewCandidates(transactions: HeliusEnhancedTx[], mint: string): AssetFlowCoverageReviewCandidate[];
+declare function clusterCoverageReviewCandidates(candidates: AssetFlowCoverageReviewCandidate[], sampleLimit?: number): AssetFlowCoverageCluster[];
+declare function scanTransactionsForCoverage(transactions: HeliusEnhancedTx[], mint: string): AssetFlowCoverageScanResult;
+
 type AssetOwnershipKind = "NONE" | "DIRECT" | "CUSTODY" | "SAME_OWNER" | "AMBIGUOUS";
 type AssetSettlementKind = "NONE" | "NATIVE_SALE" | "POTENTIAL_SALE" | "AMBIGUOUS";
 type AssetNftTouchKind = "NONE" | "SAME_OWNER" | "OWNERSHIP_CHANGE";
@@ -175,20 +222,6 @@ interface AssetFlowTransactionFacts {
     instructionLabels: string[];
 }
 
-declare function buildTransactionFacts(tx: HeliusEnhancedTx, mint: string): AssetFlowTransactionFacts;
-
-declare function normalizeEnhancedType(value: string | undefined): string;
-declare function toNullableNumber(value: unknown): number | null;
-declare function isNonFungibleTokenStandard(tokenStandard: string | null | undefined): boolean;
-declare function isMintNftTransfer(transfer: HeliusTokenTransfer, mint: string): boolean;
-declare function getMintNftTransfers(tx: HeliusEnhancedTx, mint: string): HeliusTokenTransfer[];
-declare function hasMeaningfulNativeSettlement(tx: HeliusEnhancedTx, mint: string): boolean;
-
-declare function observationFromFacts(facts: AssetFlowTransactionFacts): AssetFlowObservation;
-declare function observeEnhancedTransactionForMint(tx: HeliusEnhancedTx, mint: string): AssetFlowObservation;
-
-declare function classifyEnhancedTransactionForMint(tx: HeliusEnhancedTx, mint: string): AssetFlowTxClassification;
-
 interface AssetFlowClassificationMatcher {
     id: string;
     matches(observation: AssetFlowObservation): boolean;
@@ -211,50 +244,28 @@ interface AssetFlowClassificationExplanation {
 }
 declare function explainEnhancedTransactionForMint(tx: HeliusEnhancedTx, mint: string): AssetFlowClassificationExplanation;
 
-interface AssetFlowCoverageReviewCandidate {
-    mint: string;
-    signature: string;
-    timestamp: number | null;
-    source: string;
-    normalizedType: string;
-    matcherId: string;
-    family: AssetFlowTxClassification["family"];
-    effect: AssetFlowTxClassification["effect"];
-    materialization: AssetFlowTxClassification["materialization"];
-    confidence: AssetFlowTxClassification["confidence"];
-    reason: AssetFlowTxClassification["reason"];
-    hasOwnershipChange: boolean;
-    hasMeaningfulSettlement: boolean;
-    programIds: string[];
-    instructionLabels: string[];
-}
-interface AssetFlowCoverageCluster {
-    fingerprint: string;
+declare function buildTransactionFacts(tx: HeliusEnhancedTx, mint: string): AssetFlowTransactionFacts;
+
+interface ClassificationInput {
+    family: AssetFlowFamily;
+    derivedType: AssetFlowDerivedType;
     matcherId: string;
-    family: AssetFlowTxClassification["family"];
-    effect: AssetFlowTxClassification["effect"];
-    materialization: AssetFlowTxClassification["materialization"];
-    confidence: AssetFlowTxClassification["confidence"];
-    normalizedType: string;
-    source: string;
-    reason: AssetFlowTxClassification["reason"];
-    hasOwnershipChange: boolean;
-    hasMeaningfulSettlement: boolean;
-    programIds: string[];
-    instructionLabels: string[];
-    count: number;
-    sampleSignatures: string[];
-    sampleMints: string[];
-}
-interface AssetFlowCoverageScanResult {
-    mint: string;
-    transactionsScanned: number;
-    reviewCandidates: AssetFlowCoverageReviewCandidate[];
-    clusters: AssetFlowCoverageCluster[];
+    reason: string;
+    observation: {
+        normalizedType: string;
+        hasOwnershipChange: boolean;
+    };
+    overrides?: Partial<Pick<AssetFlowTxClassification, "normalizedType" | "effect" | "materialization" | "confidence" | "shouldExtractValueMovements">>;
 }
-declare function collectCoverageReviewCandidates(transactions: HeliusEnhancedTx[], mint: string): AssetFlowCoverageReviewCandidate[];
-declare function clusterCoverageReviewCandidates(candidates: AssetFlowCoverageReviewCandidate[], sampleLimit?: number): AssetFlowCoverageCluster[];
-declare function scanTransactionsForCoverage(transactions: HeliusEnhancedTx[], mint: string): AssetFlowCoverageScanResult;
+declare const PERSIST_DERIVED_TYPES: Set<AssetFlowDerivedType>;
+declare function classification(input: ClassificationInput): AssetFlowTxClassification;
+
+declare const protocolMatchers: RegisteredAssetFlowClassificationMatcher[];
+declare const coreAndMarketplaceMatchers: RegisteredAssetFlowClassificationMatcher[];
+declare const assetFlowMatchers: RegisteredAssetFlowClassificationMatcher[];
+
+declare function getMatchingAssetFlowMatchers(matchers: RegisteredAssetFlowClassificationMatcher[], observation: AssetFlowObservation): RegisteredAssetFlowClassificationMatcher[];
+declare function selectAssetFlowMatcher(matchers: RegisteredAssetFlowClassificationMatcher[], observation: AssetFlowObservation): RegisteredAssetFlowClassificationMatcher;
 
 declare function reconstructOwnershipPeriods(flows: ExtractedMintFlow[]): ReconstructedOwnershipPeriod[];
 
@@ -263,6 +274,30 @@ declare function extractMintFlows(transactions: HeliusEnhancedTx[], mint: string
 declare function extractValueMovements(transactions: HeliusEnhancedTx[], mint: string, classificationCache?: Map<string, AssetFlowTxClassification>): ExtractedValueMovement[];
 declare function normalizeMintHistory(transactions: HeliusEnhancedTx[], mint: string): NormalizedMintHistory;
 
+declare function observationFromFacts(facts: AssetFlowTransactionFacts): AssetFlowObservation;
+declare function observeEnhancedTransactionForMint(tx: HeliusEnhancedTx, mint: string): AssetFlowObservation;
+
+type MintFlowProtocolEventKind = "DIRECT_FLOW" | "POOL_SALE" | "ESCROW_SALE" | "SWAP_REASSIGN";
+interface MintFlowProtocolEventFlow {
+    fromAddress: string | null;
+    toAddress: string | null;
+    transferIndex: number;
+    tokenStandard: string | null;
+    derivedType: ExtractedMintFlow["derivedType"];
+}
+interface MintFlowProtocolEvent {
+    kind: MintFlowProtocolEventKind;
+    tx: HeliusEnhancedTx;
+    timestamp: number;
+    classification: AssetFlowTxClassification | null;
+    flows: MintFlowProtocolEventFlow[];
+}
+declare function interpretMintFlowProtocolEvent(params: {
+    tx: HeliusEnhancedTx;
+    mint: string;
+    getClassification: (tx: HeliusEnhancedTx) => AssetFlowTxClassification;
+}): MintFlowProtocolEvent | null;
+
 declare function extractCandidateMintsFromRawTransaction(tx: RawAssetFlowTransaction): string[];
 declare function synthesizeEnhancedTransactionsFromRaw(tx: RawAssetFlowTransaction): HeliusEnhancedTx[];
 declare function mergeRawProgramEvidence(tx: HeliusEnhancedTx, rawTx: RawAssetFlowTransaction): HeliusEnhancedTx;
@@ -271,4 +306,78 @@ declare function augmentEnhancedTransactionWithRaw(tx: HeliusEnhancedTx, rawTx:
 declare function applyRawOwnerOverridesToEnhanced(tx: HeliusEnhancedTx, rawTx: RawAssetFlowTransaction): HeliusEnhancedTx;
 declare function shouldFetchRawForMintTx(tx: HeliusEnhancedTx, mint: string): boolean;
 
-export { type AssetFlowClassificationExplanation, type AssetFlowCoverageCluster, type AssetFlowCoverageReviewCandidate, type AssetFlowCoverageScanResult, type AssetFlowDerivedType, type AssetFlowEffect, type AssetFlowFamily, type AssetFlowInterpreterConfidence, type AssetFlowMatcherExplanation, type AssetFlowMaterialization, type AssetFlowObservation, type AssetFlowTransactionFacts, type AssetFlowTxClassification, type AssetNftTouchKind, type AssetOwnershipKind, type AssetSettlementKind, type ExtractedMintFlow, type ExtractedValueMovement, type HeliusEnhancedAction, type HeliusEnhancedInstruction, type HeliusEnhancedTx, type HeliusNativeTransfer, type HeliusTokenTransfer, type NormalizedMintHistory, type RawAssetFlowAccountKey, type RawAssetFlowInstruction, type RawAssetFlowTokenBalance, type RawAssetFlowTransaction, type ReconstructedOwnershipPeriod, applyRawOwnerOverridesToEnhanced, augmentEnhancedTransactionWithRaw, augmentEnhancedTransactionWithRaw as augmentWithRaw, extractMintFlows as buildFlows, normalizeMintHistory as buildMintHistory, reconstructOwnershipPeriods as buildOwnershipPeriods, buildTransactionFacts, extractValueMovements as buildValueMovements, classifyEnhancedTransactionForMint as classify, classifyEnhancedTransactionForMint, clusterCoverageReviewCandidates, collectCoverageReviewCandidates, explainEnhancedTransactionForMint as explain, explainEnhancedTransactionForMint, extractCandidateMintsFromEnhancedTx, extractCandidateMintsFromRawTransaction, extractMintFlows, extractCandidateMintsFromEnhancedTx as extractMints, extractValueMovements, getMintNftTransfers, hasMeaningfulNativeSettlement, isMintNftTransfer, isNonFungibleTokenStandard, mergeRawProgramEvidence, normalizeEnhancedType, normalizeMintHistory, observationFromFacts, observeEnhancedTransactionForMint, reconstructOwnershipPeriods, scanTransactionsForCoverage, shouldApplyRawOwnerOverrides, shouldFetchRawForMintTx as shouldFetchRaw, shouldFetchRawForMintTx, synthesizeEnhancedTransactionsFromRaw, toNullableNumber };
+declare function normalizeEnhancedType(value: string | undefined): string;
+declare function toNullableNumber(value: unknown): number | null;
+declare function isNonFungibleTokenStandard(tokenStandard: string | null | undefined): boolean;
+declare function isMintNftTransfer(transfer: HeliusTokenTransfer, mint: string): boolean;
+declare function getMintNftTransfers(tx: HeliusEnhancedTx, mint: string): HeliusTokenTransfer[];
+declare function hasMeaningfulNativeSettlement(tx: HeliusEnhancedTx, mint: string): boolean;
+
+interface SuiEventLike {
+    type: string;
+    parsedJson?: unknown | null;
+}
+type SuiObjectOwnerLike = {
+    AddressOwner: string;
+} | {
+    ObjectOwner: string;
+} | {
+    Shared: {
+        initial_shared_version: string;
+    };
+} | {
+    ConsensusV2: unknown;
+} | "Immutable" | null | undefined;
+interface SuiObjectChangeLike {
+    type: string;
+    objectId?: string;
+    objectType?: string;
+    sender?: string;
+    owner?: SuiObjectOwnerLike;
+    recipient?: SuiObjectOwnerLike;
+}
+interface SuiBalanceChangeLike {
+    owner?: SuiObjectOwnerLike;
+    coinType?: string;
+    amount?: string;
+}
+interface SuiTransactionBlockLike {
+    digest: string;
+    checkpoint?: string | null;
+    timestampMs?: string | null;
+    events?: SuiEventLike[] | null;
+    objectChanges?: SuiObjectChangeLike[] | null;
+    balanceChanges?: SuiBalanceChangeLike[] | null;
+    transaction?: {
+        data?: {
+            sender?: string | null;
+        } | null;
+    } | null;
+}
+type SuiAssetFlowFamily = "NFT_MINT" | "TRADEPORT_SALE" | "TRADEPORT_LISTING" | "TRADEPORT_BID_INTENT" | "POPKINS_STAKING" | "POPSWAP" | "GENERIC_OBJECT_TRANSFER" | "UNKNOWN";
+interface SuiAssetOwnerChange {
+    sender: string | null;
+    nextOwner: string | null;
+    objectType: string | null;
+}
+interface SuiAssetFlowClassification {
+    assetId: string;
+    family: SuiAssetFlowFamily;
+    effect: AssetFlowEffect;
+    materialization: AssetFlowMaterialization;
+    confidence: AssetFlowInterpreterConfidence;
+    derivedType: AssetFlowDerivedType;
+    matcherId: string;
+    reason: string;
+    hasOwnershipChange: boolean;
+    shouldExtractValueMovements: boolean;
+    eventTypes: string[];
+    market: string | null;
+    priceRaw: string | null;
+    currency: string | null;
+    ownerChange: SuiAssetOwnerChange | null;
+}
+
+declare function classifySuiTransactionForAsset(tx: SuiTransactionBlockLike, assetId: string): SuiAssetFlowClassification;
+
+export { type AssetFlowClassificationExplanation, type AssetFlowClassificationMatcher, type AssetFlowCoverageCluster, type AssetFlowCoverageReviewCandidate, type AssetFlowCoverageScanResult, type AssetFlowDerivedType, type AssetFlowEffect, type AssetFlowFamily, type AssetFlowInterpreterConfidence, type AssetFlowMatcherExplanation, type AssetFlowMaterialization, type AssetFlowObservation, type AssetFlowTransactionFacts, type AssetFlowTxClassification, type AssetNftTouchKind, type AssetOwnershipKind, type AssetSettlementKind, type ExtractedMintFlow, type ExtractedValueMovement, type HeliusEnhancedAction, type HeliusEnhancedInstruction, type HeliusEnhancedTx, type HeliusNativeTransfer, type HeliusTokenTransfer, type MintFlowProtocolEvent, type MintFlowProtocolEventFlow, type MintFlowProtocolEventKind, type NormalizedMintHistory, PERSIST_DERIVED_TYPES, type RawAssetFlowAccountKey, type RawAssetFlowInstruction, type RawAssetFlowTokenBalance, type RawAssetFlowTransaction, type ReconstructedOwnershipPeriod, type RegisteredAssetFlowClassificationMatcher, type SuiAssetFlowClassification, type SuiAssetFlowFamily, type SuiAssetOwnerChange, type SuiBalanceChangeLike, type SuiEventLike, type SuiObjectChangeLike, type SuiObjectOwnerLike, type SuiTransactionBlockLike, applyRawOwnerOverridesToEnhanced, assetFlowMatchers, augmentEnhancedTransactionWithRaw, augmentEnhancedTransactionWithRaw as augmentWithRaw, extractMintFlows as buildFlows, normalizeMintHistory as buildMintHistory, reconstructOwnershipPeriods as buildOwnershipPeriods, buildTransactionFacts, extractValueMovements as buildValueMovements, classification, classifyEnhancedTransactionForMint as classify, classifyEnhancedTransactionForMint, classifySuiTransactionForAsset, clusterCoverageReviewCandidates, collectCoverageReviewCandidates, coreAndMarketplaceMatchers, explainEnhancedTransactionForMint as explain, explainEnhancedTransactionForMint, extractCandidateMintsFromEnhancedTx, extractCandidateMintsFromRawTransaction, extractMintFlows, extractCandidateMintsFromEnhancedTx as extractMints, extractValueMovements, getMatchingAssetFlowMatchers, getMintNftTransfers, hasMeaningfulNativeSettlement, interpretMintFlowProtocolEvent, isMintNftTransfer, isNonFungibleTokenStandard, mergeRawProgramEvidence, normalizeEnhancedType, normalizeMintHistory, observationFromFacts, observeEnhancedTransactionForMint, protocolMatchers, reconstructOwnershipPeriods, scanTransactionsForCoverage, selectAssetFlowMatcher, shouldApplyRawOwnerOverrides, shouldFetchRawForMintTx as shouldFetchRaw, shouldFetchRawForMintTx, synthesizeEnhancedTransactionsFromRaw, toNullableNumber };