{"_id":"@clayno-club/solana-asset-flow","_rev":"2-9e87ca699935929e69b6a850757f113e","name":"@clayno-club/solana-asset-flow","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@clayno-club/solana-asset-flow","version":"0.1.0","_id":"@clayno-club/solana-asset-flow@0.1.0","maintainers":[{"name":"ryan_c","email":"racollette@gmail.com"}],"dist":{"shasum":"43707b7ad8a3288b6040e7c406f3e44711a13d03","tarball":"https://registry.npmjs.org/@clayno-club/solana-asset-flow/-/solana-asset-flow-0.1.0.tgz","fileCount":9,"integrity":"sha512-9L98CHv+zFN0LDL6VZkWeHb+WMO1LwJhhVqH8v/k2fZDBVCv5jx2dG4vAAJQz7uwr8zcpUNXO8WpMkonrnpL1g==","signatures":[{"sig":"MEUCIQDmshfcVK1CtqoDNDJV95lBnAdICoqWIYfNs8yVUm/7CQIgeBmn/G6iFZlewtO6QIYwYorZtOoCyqG6Mvo9Ep5dlOI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":477459},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"},"./internal":{"types":"./dist/internal.d.ts","import":"./dist/internal.js","default":"./dist/internal.js"}},"gitHead":"b4909ebf4870e6a13f2adc6da7240202d3ccffec","scripts":{"dev":"tsup --watch","lint":"eslint .","test":"pnpm exec tsx --test src/**/*.test.ts","build":"tsup","clean":"rm -rf dist","lint:fix":"eslint . --fix","type-check":"tsc --noEmit"},"_npmUser":{"name":"ryan_c","email":"racollette@gmail.com"},"_npmVersion":"11.6.1","description":"Solana asset-flow classification and normalization for Helius enhanced transactions","directories":{},"_nodeVersion":"24.10.0","dependencies":{},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.1","typescript":"^5.3.3"},"_npmOperationalInternal":{"tmp":"tmp/solana-asset-flow_0.1.0_1774375105374_0.9147128174688137","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."}},"time":{"created":"2026-03-24T17:58:25.268Z","modified":"2026-03-30T03:32:46.155Z","0.1.0":"2026-03-24T17:58:25.553Z"},"description":"Solana asset-flow classification and normalization for Helius enhanced transactions","maintainers":[{"name":"ryan_c","email":"racollette@gmail.com"}],"readme":"# @clayno-club/solana-asset-flow\n\nDeterministic Solana NFT asset-flow classification and normalization.\n\nThis 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.\n\n## What it does\n\n- classify enhanced Solana transactions for a tracked mint\n- merge raw ownership evidence into enhanced transactions when needed\n- normalize a mint's transaction history into canonical flows\n- derive ownership periods from normalized flows\n- explain why a transaction matched a given classification path\n\n## What it does not do\n\n- fetch transaction history from RPC providers or indexers\n- persist results to a database\n- manage queues, jobs, or orchestration\n\nYou provide the transaction data. The package provides deterministic interpretation.\n\n## Install\n\n```bash\npnpm add @clayno-club/solana-asset-flow\n```\n\n## Core API\n\n**Classification:**\n- `classify(tx, mint)` — classify a single transaction for a tracked mint\n- `explain(tx, mint)` — same as classify, but returns the full decision trace\n\n**Raw augmentation:**\n- `shouldFetchRaw(tx, mint)` — check if raw data would improve classification\n- `augmentWithRaw(tx, rawTx)` — merge raw ownership evidence into enhanced tx\n\n**History normalization:**\n- `buildMintHistory(transactions, mint)` — full pipeline: flows + value movements + ownership periods\n- `buildMintFlows(transactions, mint)` — just the canonical flows\n- `buildValueMovements(transactions, mint)` — just the value movements\n- `buildOwnershipPeriods(flows)` — ownership periods from flows\n- `extractMints(tx)` — extract candidate mint addresses from a transaction\n\n## Example: classify one transaction\n\n```ts\nimport { classify } from \"@clayno-club/solana-asset-flow\";\n\nconst classification = classify(tx, mint);\n\nconsole.log(classification.family);\nconsole.log(classification.derivedType);\nconsole.log(classification.materialization);\n```\n\n## Example: augment enhanced data with raw ownership evidence\n\n```ts\nimport { augmentWithRaw } from \"@clayno-club/solana-asset-flow\";\n\nconst augmented = augmentWithRaw(enhancedTx, rawTx);\n```\n\n## Example: normalize mint history\n\n```ts\nimport { buildMintHistory } from \"@clayno-club/solana-asset-flow\";\n\nconst normalized = buildMintHistory(transactions, mint);\n\nconsole.log(normalized.flows);\nconsole.log(normalized.valueMovements);\nconsole.log(normalized.periods);\n```\n\n## Example: explain a classification decision\n\n```ts\nimport { explain } from \"@clayno-club/solana-asset-flow\";\n\nconst explanation = explain(tx, mint);\n\nconsole.log(explanation.facts);\nconsole.log(explanation.candidates);\nconsole.log(explanation.selected);\n```\n\n## Concepts\n\nThe package is structured around three steps:\n\n1. Facts\n   Convert transaction evidence into normalized facts about ownership change, settlement, program signals, and participants.\n\n2. Classification\n   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.\n\n3. Normalization\n   Turn classified transaction history into canonical mint flows, value movements, and ownership periods.\n\n## Output model\n\nThe normalized history contains:\n\n- `flows`\n  Canonical mint ownership events such as `MINT`, `SALE`, `TRANSFER`, `SWAP`, `LIST`, `DELIST`, `LOCK`, `UNLOCK`, and `FORECLOSURE`\n\n- `valueMovements`\n  Associated native or fungible settlement movements with roles such as `SALE_GROSS`, `SELLER_PROCEEDS`, `ROYALTY`, `MARKETPLACE_FEE`, `RENT`, and `SWAP_CONSIDERATION`\n\n- `periods`\n  Reconstructed ownership periods derived from normalized beneficial flows\n\n## When to use raw data\n\nSome Solana transactions do not expose enough ownership detail in enhanced/indexed form alone. When raw transaction data is available, use:\n\n- `shouldFetchRaw(tx, mint)`\n- `augmentWithRaw(tx, rawTx)`\n\nThis lets you keep the classification path deterministic while improving owner resolution for custody-heavy or protocol-heavy transactions.\n\n## Internal entry point\n\nWorkspace consumers that need access to lower-level building blocks (coverage analysis, raw transaction utilities, fact builders) can import from the `./internal` entry point:\n\n```ts\nimport { ... } from \"@clayno-club/solana-asset-flow/internal\";\n```\n\nThis surface is not part of the public API and may change between releases. External consumers should use the default entry point only.\n\n## Extending the matcher set\n\nWhen adding support for a new marketplace or protocol family:\n\n1. identify the reusable evidence\n2. add or reuse fact-building signals\n3. add a narrow matcher for the family\n4. register it with the appropriate priority\n5. add fixture coverage and regression tests\n\nPrefer adding a matcher for a real transaction family over expanding generic fallback behavior.\n\n## Testing\n\nTypical verification:\n\n```bash\npnpm --filter @clayno-club/solana-asset-flow test\npnpm --filter @clayno-club/solana-asset-flow build\npnpm --filter @clayno-club/solana-asset-flow type-check\n```\n","readmeFilename":"README.md"}