@clayno-club/asset-flow 0.1.1

package/README.md

@@ -0,0 +1,149 @@
+# @clayno-club/asset-flow
+
+Deterministic Solana NFT asset-flow classification and normalization.
+
+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.
+
+## 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
+- derive ownership periods from normalized flows
+- explain why a transaction matched a given classification path
+- analyze provided transaction sets for review candidates
+
+## What it does not do
+
+- fetch transaction history from RPC providers or indexers
+- persist results to a database
+- manage queues, jobs, or orchestration
+
+You provide the transaction data. The package provides deterministic interpretation.
+
+## Install
+
+```bash
+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)`
+
+## Example: classify one transaction
+
+```ts
+import { classifyEnhancedTransactionForMint } from "@clayno-club/asset-flow";
+
+const classification = classifyEnhancedTransactionForMint(tx, mint);
+
+console.log(classification.family);
+console.log(classification.derivedType);
+console.log(classification.materialization);
+```
+
+## Example: augment enhanced data with raw ownership evidence
+
+```ts
+import { augmentEnhancedTransactionWithRaw } from "@clayno-club/asset-flow";
+
+const augmented = augmentEnhancedTransactionWithRaw(enhancedTx, rawTx);
+```
+
+## Example: normalize mint history
+
+```ts
+import { normalizeMintHistory } from "@clayno-club/asset-flow";
+
+const normalized = normalizeMintHistory(transactions, mint);
+
+console.log(normalized.flows);
+console.log(normalized.valueMovements);
+console.log(normalized.periods);
+```
+
+## Example: explain a classification decision
+
+```ts
+import { explainEnhancedTransactionForMint } from "@clayno-club/asset-flow";
+
+const explanation = explainEnhancedTransactionForMint(tx, mint);
+
+console.log(explanation.facts);
+console.log(explanation.candidates);
+console.log(explanation.selection);
+```
+
+## Concepts
+
+The package is structured around three steps:
+
+1. Facts
+   Convert transaction evidence into normalized facts about ownership change, settlement, program signals, and participants.
+
+2. Classification
+   Match the transaction to a known family and determine whether it should materialize as a canonical flow, be skipped as non-settlement activity, or remain review-worthy.
+
+3. Normalization
+   Turn classified transaction history into canonical mint flows, value movements, and ownership periods.
+
+## Output model
+
+The normalized history contains:
+
+- `flows`
+  Canonical mint ownership events such as `MINT`, `SALE`, `TRANSFER`, `SWAP`, `LIST`, `DELIST`, `LOCK`, `UNLOCK`, and `FORECLOSURE`
+
+- `valueMovements`
+  Associated native or fungible settlement movements with roles such as `SALE_GROSS`, `SELLER_PROCEEDS`, `ROYALTY`, `MARKETPLACE_FEE`, `RENT`, and `SWAP_CONSIDERATION`
+
+- `periods`
+  Reconstructed ownership periods derived from normalized beneficial flows
+
+## When to use raw data
+
+Some Solana transactions do not expose enough ownership detail in enhanced/indexed form alone. When raw transaction data is available, use:
+
+- `shouldFetchRawForMintTx()`
+- `augmentEnhancedTransactionWithRaw()`
+
+This lets you keep the classification path deterministic while improving owner resolution for custody-heavy or protocol-heavy transactions.
+
+## Review analysis helpers
+
+If you already have a set of transactions and want to identify unresolved patterns:
+
+- `collectCoverageReviewCandidates()` returns review-worthy transactions
+- `clusterCoverageReviewCandidates()` groups them into stable fingerprints
+- `scanTransactionsForCoverage()` combines both into a mint-scoped summary
+
+These helpers are pure over provided transactions and do not fetch data.
+
+## Extending the matcher set
+
+When adding support for a new marketplace or protocol family:
+
+1. identify the reusable evidence
+2. add or reuse fact-building signals
+3. add a narrow matcher for the family
+4. register it with the appropriate priority
+5. add fixture coverage and regression tests
+
+Prefer adding a matcher for a real transaction family over expanding generic fallback behavior.
+
+## Testing
+
+Typical verification:
+
+```bash
+pnpm --filter @clayno-club/asset-flow test
+pnpm --filter @clayno-club/asset-flow build
+pnpm --filter @clayno-club/asset-flow type-check
+```

package/dist/index.d.ts

@@ -0,0 +1,274 @@
+interface HeliusTokenTransfer {
+    mint?: string;
+    fromUserAccount?: string;
+    toUserAccount?: string;
+    tokenAmount?: number | string;
+    tokenStandard?: string;
+}
+interface HeliusNativeTransfer {
+    fromUserAccount?: string;
+    toUserAccount?: string;
+    amount?: number | string;
+}
+interface HeliusEnhancedAction {
+    actionType?: string;
+    from?: string;
+    to?: string;
+    amount?: number | string;
+    mint?: string;
+    decimals?: number;
+}
+interface HeliusEnhancedInstruction {
+    programId?: string;
+    name?: string;
+    innerInstructions?: HeliusEnhancedInstruction[];
+}
+interface HeliusEnhancedTx {
+    signature: string;
+    slot?: number;
+    timestamp?: number;
+    type?: string;
+    source?: string;
+    description?: string;
+    fee?: number;
+    transactionError?: unknown | null;
+    programIds?: string[];
+    instructionLabels?: string[];
+    instructions?: HeliusEnhancedInstruction[];
+    actions?: HeliusEnhancedAction[];
+    tokenTransfers?: HeliusTokenTransfer[];
+    nativeTransfers?: HeliusNativeTransfer[];
+}
+type RawAssetFlowAccountKey = string | {
+    pubkey: string;
+    writable?: boolean;
+    signer?: boolean;
+    source?: string;
+};
+interface RawAssetFlowInstruction {
+    programId?: string;
+    programIdIndex?: number;
+    accounts?: (string | number)[];
+    data?: string;
+}
+interface RawAssetFlowTokenBalance {
+    accountIndex: number;
+    mint: string;
+    owner?: string;
+    uiTokenAmount: {
+        amount: string;
+        decimals?: number;
+        uiAmount?: number | null;
+    };
+}
+interface RawAssetFlowTransaction {
+    signature?: string;
+    blockTime?: number;
+    slot?: number;
+    transaction?: {
+        message?: {
+            accountKeys?: RawAssetFlowAccountKey[];
+            instructions?: RawAssetFlowInstruction[];
+        };
+        signatures?: string[];
+    };
+    meta?: {
+        preBalances?: number[];
+        postBalances?: number[];
+        preTokenBalances?: RawAssetFlowTokenBalance[];
+        postTokenBalances?: RawAssetFlowTokenBalance[];
+        logMessages?: string[];
+    };
+}
+type AssetFlowFamily = "NFT_MINT" | "EXPLICIT_NFT_SALE" | "TENSOR_UNKNOWN_SALE" | "MAGIC_EDEN_LUCKY_BUY" | "LOAN_PROGRAM_ACTIVITY" | "MARKETPLACE_LISTING" | "MARKETPLACE_BID" | "MAGIC_EDEN_BUY_INTENT" | "BUBBLEGUM_COMPRESSED_MINT" | "BET_PROGRAM_ACTIVITY" | "METAPLEX_METADATA_UPDATE" | "TLOCK_LEGACY_CLAIM" | "GENERIC_SWAP" | "GENERIC_UNKNOWN_SALE" | "GENERIC_TRANSFER" | "GENERIC_NON_SETTLEMENT" | "UNKNOWN";
+type AssetFlowInterpreterConfidence = "high" | "medium" | "low";
+type AssetFlowEffect = "OWNERSHIP_CHANGE_AND_SETTLEMENT" | "OWNERSHIP_CHANGE_ONLY" | "NON_SETTLEMENT_MARKETPLACE_ACTION" | "NO_MINT_EFFECT" | "UNKNOWN";
+type AssetFlowMaterialization = "PERSIST_FLOW" | "SKIP_FLOW" | "REVIEW";
+type AssetFlowDerivedType = "SALE" | "SWAP" | "TRANSFER" | "MINT" | "LIST" | "DELIST" | "LOCK" | "UNLOCK" | "FORECLOSURE" | "NON_SETTLEMENT" | "UNKNOWN";
+interface AssetFlowObservation {
+    mint: string;
+    tx: HeliusEnhancedTx;
+    normalizedType: string;
+    normalizedSource: string;
+    nftTransfers: HeliusTokenTransfer[];
+    hasOwnershipChange: boolean;
+    hasMeaningfulSettlement: boolean;
+    primaryBuyer: string | null;
+    primarySeller: string | null;
+    programIds: string[];
+    instructionLabels: string[];
+}
+interface AssetFlowTxClassification {
+    family: AssetFlowFamily;
+    effect: AssetFlowEffect;
+    materialization: AssetFlowMaterialization;
+    normalizedType: string;
+    matcherId: string;
+    confidence: AssetFlowInterpreterConfidence;
+    derivedType: AssetFlowDerivedType;
+    hasOwnershipChange: boolean;
+    shouldExtractValueMovements: boolean;
+    reason: string;
+}
+interface ExtractedMintFlow {
+    signature: string;
+    slot: number | null;
+    timestamp: number;
+    heliusType: string;
+    source: string;
+    fromAddress: string | null;
+    toAddress: string | null;
+    transferIndex: number;
+    tokenStandard: string | null;
+    derivedType: "SALE" | "SWAP" | "TRANSFER" | "MINT" | "LIST" | "DELIST" | "LOCK" | "UNLOCK" | "FORECLOSURE" | "UNKNOWN";
+}
+interface ExtractedValueMovement {
+    signature: string;
+    slot: number | null;
+    timestamp: number;
+    heliusType: string;
+    source: string;
+    movementKind: "NATIVE" | "TOKEN";
+    currency: string;
+    amount: number;
+    rawAmount: string | null;
+    decimals: number | null;
+    fromAddress: string | null;
+    toAddress: string | null;
+    movementIndex: number;
+    tokenStandard: string | null;
+    role: "SALE_GROSS" | "SELLER_PROCEEDS" | "ROYALTY" | "MARKETPLACE_FEE" | "OTHER_FEE" | "RENT" | "REFUND" | "SWAP_CONSIDERATION" | "UNKNOWN";
+    confidence: "HIGH" | "MEDIUM" | "LOW";
+    isSynthetic: boolean;
+}
+interface ReconstructedOwnershipPeriod {
+    ownerAddress: string;
+    startTimestamp: number;
+    endTimestamp: number | null;
+}
+interface NormalizedMintHistory {
+    flows: ExtractedMintFlow[];
+    valueMovements: ExtractedValueMovement[];
+    periods: ReconstructedOwnershipPeriod[];
+}
+
+type AssetOwnershipKind = "NONE" | "DIRECT" | "CUSTODY" | "SAME_OWNER" | "AMBIGUOUS";
+type AssetSettlementKind = "NONE" | "NATIVE_SALE" | "POTENTIAL_SALE" | "AMBIGUOUS";
+type AssetNftTouchKind = "NONE" | "SAME_OWNER" | "OWNERSHIP_CHANGE";
+interface AssetFlowTransactionFacts {
+    mint: string;
+    tx: HeliusEnhancedTx;
+    normalizedType: string;
+    normalizedSource: string;
+    nftTransfers: HeliusTokenTransfer[];
+    nftTouchKind: AssetNftTouchKind;
+    ownershipKind: AssetOwnershipKind;
+    settlementKind: AssetSettlementKind;
+    hasOwnershipChange: boolean;
+    hasMeaningfulSettlement: boolean;
+    primaryBuyer: string | null;
+    primarySeller: string | null;
+    custodyEndpoint: string | null;
+    hasProgramEvidence: boolean;
+    isNoisyOwnershipChange: boolean;
+    programIds: string[];
+    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;
+    classify(observation: AssetFlowObservation): AssetFlowTxClassification;
+}
+interface RegisteredAssetFlowClassificationMatcher extends AssetFlowClassificationMatcher {
+    priority: number;
+}
+
+interface AssetFlowMatcherExplanation {
+    matcher: RegisteredAssetFlowClassificationMatcher;
+    classification: AssetFlowTxClassification;
+}
+interface AssetFlowClassificationExplanation {
+    facts: AssetFlowTransactionFacts;
+    observation: AssetFlowObservation;
+    candidates: AssetFlowMatcherExplanation[];
+    selected: AssetFlowMatcherExplanation;
+    classification: AssetFlowTxClassification;
+}
+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;
+    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;
+
+declare function reconstructOwnershipPeriods(flows: ExtractedMintFlow[]): ReconstructedOwnershipPeriod[];
+
+declare function extractCandidateMintsFromEnhancedTx(tx: HeliusEnhancedTx): string[];
+declare function extractMintFlows(transactions: HeliusEnhancedTx[], mint: string, classificationCache?: Map<string, AssetFlowTxClassification>): ExtractedMintFlow[];
+declare function extractValueMovements(transactions: HeliusEnhancedTx[], mint: string, classificationCache?: Map<string, AssetFlowTxClassification>): ExtractedValueMovement[];
+declare function normalizeMintHistory(transactions: HeliusEnhancedTx[], mint: string): NormalizedMintHistory;
+
+declare function extractCandidateMintsFromRawTransaction(tx: RawAssetFlowTransaction): string[];
+declare function synthesizeEnhancedTransactionsFromRaw(tx: RawAssetFlowTransaction): HeliusEnhancedTx[];
+declare function mergeRawProgramEvidence(tx: HeliusEnhancedTx, rawTx: RawAssetFlowTransaction): HeliusEnhancedTx;
+declare function shouldApplyRawOwnerOverrides(tx: HeliusEnhancedTx, rawTx: RawAssetFlowTransaction): boolean;
+declare function augmentEnhancedTransactionWithRaw(tx: HeliusEnhancedTx, rawTx: RawAssetFlowTransaction): HeliusEnhancedTx;
+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 };