How fragmetric-labs/fragmetric-snapshot works
Project type and purpose
• This is an open-source CLI tool (TypeScript/Node.js) for taking on-chain DeFi “snapshots” on Solana.
• It exposes a single command (snapshot) with multiple pluggable “source” modules, each implementing logic to fetch and aggregate on-chain data via an RPC endpoint.
File structure
• Top-level files:
– index.js / index.ts: Entry point that wires up the CLI
– package.json / pnpm-workspace.yaml: Package configuration and workspace layout
– tsconfig.json, vitest.config.ts: Build/test configuration
• src/commands/snapshot:
– index.ts: Registers the snapshot command and handles global options (e.g. --rpc)
– output.ts: Formats and prints the result to stdout
• src/commands/snapshot/source:
– Each <source>.ts + <source>.test.ts pair implements a SnapshotSource interface
– .idl.json/.idl.ts files define on-chain account/data layouts for each protocol
– testutil.ts contains shared test helpers
• src/rpc.ts: RPC client abstraction for interacting with Solana nodes
• src/logger.ts: Simple logging utility
README for additional insights
• Shows usage patterns: pnpx @fragmetric-labs/snapshot snapshot --rpc <URL> <source> <args…>
• Lists supported sources (orca-liquidity, kamino-lending, etc.)
• Describes test and publish workflows
Main components & interactions
a. Component breakdown:
1. CLI Entrypoint
2. Command Registrar / Parser
3. Snapshot Command Handler
4. Source Module Factory & Loader
5. RPC Client Layer
6. Data Model / IDL Parsers
7. Output Formatter
8. Logger Utility
9. Test Harness (Vitest)
10. Build/Publish Pipeline (pnpm, build script, npm publish)
b. Relationships & data flow:
• User invokes fragmetric-snapshot CLI
→ Commander.js (or similar) parses arguments
→ Snapshot command handler picks the correct source module
→ Source module uses IDL definitions and the RPC client to fetch on-chain accounts
→ Business logic in the source aggregates count & amount
→ Handler passes result to Output Formatter → console (stdout)
→ Logger captures info/debug as configured
c. Architectural patterns / design principles:
• Plugin pattern for snapshot sources (extensibility)
• Single Responsibility per module (parser, source, RPC, logger, output)
• Interface-driven design for sources (SnapshotSource abstraction)
• Test-first development (Vitest unit tests alongside each source)
d. Key technologies:
• Node.js + TypeScript
• pnpm workspaces
• Commander.js (or similar) for CLI parsing
• Vitest for testing
• JSON-based IDL schemas for on-chain data layouts
• Solana RPC (helius for certain sources)