@clayno-club/asset-flow 0.1.2 → 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
@@ -29,20 +39,30 @@ pnpm add @clayno-club/asset-flow
 
 ## Core API
 
-- `classifyEnhancedTransactionForMint(tx, mint)`
-- `augmentEnhancedTransactionWithRaw(tx, rawTx)`
-- `normalizeMintHistory(transactions, mint)`
-- `explainEnhancedTransactionForMint(tx, mint)`
-- `collectCoverageReviewCandidates(transactions, mint)`
-- `clusterCoverageReviewCandidates(candidates)`
-- `scanTransactionsForCoverage(transactions, mint)`
+**Classification:**
+
+- `classify(tx, mint)` — classify a single transaction for a tracked mint
+- `explain(tx, mint)` — same as classify, but returns the full decision trace
+
+**Raw augmentation:**
+
+- `shouldFetchRaw(tx, mint)` — check if raw data would improve classification
+- `augmentWithRaw(tx, rawTx)` — merge raw ownership evidence into enhanced tx
+
+**History normalization:**
+
+- `buildMintHistory(transactions, mint)` — full pipeline: flows + value movements + ownership periods
+- `buildFlows(transactions, mint)` — just the canonical flows
+- `buildValueMovements(transactions, mint)` — just the value movements
+- `buildOwnershipPeriods(flows)` — ownership periods from flows
+- `extractMints(tx)` — extract candidate mint addresses from a transaction
 
 ## Example: classify one transaction
 
 ```ts
-import { classifyEnhancedTransactionForMint } from "@clayno-club/asset-flow";
+import { classify } from "@clayno-club/asset-flow";
 
-const classification = classifyEnhancedTransactionForMint(tx, mint);
+const classification = classify(tx, mint);
 
 console.log(classification.family);
 console.log(classification.derivedType);
@@ -52,17 +72,17 @@ console.log(classification.materialization);
 ## Example: augment enhanced data with raw ownership evidence
 
 ```ts
-import { augmentEnhancedTransactionWithRaw } from "@clayno-club/asset-flow";
+import { augmentWithRaw } from "@clayno-club/asset-flow";
 
-const augmented = augmentEnhancedTransactionWithRaw(enhancedTx, rawTx);
+const augmented = augmentWithRaw(enhancedTx, rawTx);
 ```
 
 ## Example: normalize mint history
 
 ```ts
-import { normalizeMintHistory } from "@clayno-club/asset-flow";
+import { buildMintHistory } from "@clayno-club/asset-flow";
 
-const normalized = normalizeMintHistory(transactions, mint);
+const normalized = buildMintHistory(transactions, mint);
 
 console.log(normalized.flows);
 console.log(normalized.valueMovements);
@@ -72,9 +92,9 @@ console.log(normalized.periods);
 ## Example: explain a classification decision
 
 ```ts
-import { explainEnhancedTransactionForMint } from "@clayno-club/asset-flow";
+import { explain } from "@clayno-club/asset-flow";
 
-const explanation = explainEnhancedTransactionForMint(tx, mint);
+const explanation = explain(tx, mint);
 
 console.log(explanation.facts);
 console.log(explanation.candidates);
@@ -111,8 +131,8 @@ The normalized history contains:
 
 Some Solana transactions do not expose enough ownership detail in enhanced/indexed form alone. When raw transaction data is available, use:
 
-- `shouldFetchRawForMintTx()`
-- `augmentEnhancedTransactionWithRaw()`
+- `shouldFetchRaw()`
+- `augmentWithRaw()`
 
 This lets you keep the classification path deterministic while improving owner resolution for custody-heavy or protocol-heavy transactions.
 

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, buildTransactionFacts, classifyEnhancedTransactionForMint, clusterCoverageReviewCandidates, collectCoverageReviewCandidates, explainEnhancedTransactionForMint, extractCandidateMintsFromEnhancedTx, extractCandidateMintsFromRawTransaction, extractMintFlows, extractValueMovements, getMintNftTransfers, hasMeaningfulNativeSettlement, isMintNftTransfer, isNonFungibleTokenStandard, mergeRawProgramEvidence, normalizeEnhancedType, normalizeMintHistory, observationFromFacts, observeEnhancedTransactionForMint, reconstructOwnershipPeriods, scanTransactionsForCoverage, shouldApplyRawOwnerOverrides, 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 };