@indexing/jiti 0.0.77 → 0.1.1

package/CLAUDE.md

@@ -0,0 +1,69 @@
+# CLAUDE.md
+
+This file provides context for AI assistants working on this codebase.
+
+## Project Overview
+
+JITI (Just In Time Indexing) is a TypeScript library that extracts structured data from raw blockchain blocks. It provides a unified `NetworkTransfer` type across 15+ blockchain VMs.
+
+Published as `@indexing/jiti` on npm.
+
+## Build & Test
+
+```bash
+npm install        # install dependencies
+npm test           # run tests (ts-node tests.ts) - requires API_KEY in .env
+npm run build      # build with parcel (outputs to dist/)
+npm run lint       # prettier + eslint
+```
+
+Tests fetch real block data from `https://jiti.indexing.co/networks/{network}/{block}` and compare output against expected values using `assert.deepStrictEqual`. An `API_KEY` environment variable is required.
+
+## Project Structure
+
+- `src/index.ts` - Main entry point, exports templates and utilities
+- `src/types.ts` - Core types: `Template`, `SubTemplate`, `VMType`, `NetworkType`
+- `src/templates/token-transfers/` - Per-chain token transfer extraction (one file per VM type)
+- `src/templates/token-transfers/index.ts` - Orchestrator that routes blocks to the right chain handler
+- `src/templates/token-transfers/types.ts` - `NetworkTransfer` type definition
+- `src/templates/filter-values.ts` - Filter values template
+- `src/templates/raw.ts` - Pass-through raw block template (disabled)
+- `src/utils/` - Multi-chain utility functions (block parsing, EVM helpers)
+- `tests.ts` - Test runner that validates all template outputs
+
+## Key Patterns
+
+### Adding/Modifying Chain Support
+
+Each chain's token transfer logic is in `src/templates/token-transfers/{chain}.ts` and implements the `SubTemplate` interface with `match`, `transform`, and `tests`.
+
+- `match(block)` uses `blockToVM(block)` from `src/utils/block-to-vm.ts` to detect the chain
+- `transform(block)` returns `NetworkTransfer[]`
+- `tests` include real block URLs and expected outputs - tests are inline, not in separate files
+
+To register a new chain, add it to the `SUB_TEMPLATES` array in `src/templates/token-transfers/index.ts`. Universal templates (EVM, Cosmos) go in `UNIVERSAL_SUB_TEMPLATES`.
+
+### VM Detection
+
+`blockToVM()` in `src/utils/block-to-vm.ts` maps network names to VM types. EVM is the default fallback. Chain-specific VMs (CARDANO, UTXO, SVM, etc.) are explicitly mapped.
+
+### Filtering
+
+The main `tokenTransfers` template in `index.ts` applies post-processing filters:
+- `walletAddress` - matches against `from` or `to`
+- `contractAddress` - matches against `token`
+- `transactionHash` - exact match
+- Deduplication via composite key
+- Zero-amount transfers are excluded
+
+## CI/CD
+
+- `.github/workflows/publish.yml` - On push to main: test, bump patch version, build, commit version back (via deploy key), publish to npm
+- `.github/workflows/artifacts.yml` - On push: build and upload dist artifacts
+- Version bumps use `[skip ci]` to avoid infinite loops
+
+## Code Style
+
+- Prettier: single quotes, 120 char width, es5 trailing commas
+- ESLint with prettier plugin
+- TypeScript targeting ES2020

package/README.md

@@ -1,13 +1,135 @@
-# Just In Time Indexing Service (JITI)
+# JITI - Just In Time Indexing
 
-Open source template library for the JITI community.
+Open source template library for extracting and transforming blockchain data across 15+ networks. Built by [Indexing Co](https://indexing.co).
 
-NOTE: This is an active work in progress and not yet ready for community usage.
+## Installation
 
-# Contributing
+```bash
+npm install @indexing/jiti
+```
 
-This package will be ready for external contributors in early 2025.
+## Overview
+
+JITI provides a unified interface for extracting structured data from raw blockchain blocks. It ships with built-in templates for common use cases and utility functions for working with multi-chain data.
+
+### Supported Networks
+
+| VM Type | Networks |
+|---------|----------|
+| **EVM** | Ethereum, Polygon, Arbitrum, Base, Optimism, Avalanche, and [100+ more](src/utils/evm-chain-to-id.ts) |
+| **SVM** | Solana, Eclipse |
+| **UTXO** | Bitcoin, Litecoin, Dogecoin, Zcash |
+| **Substrate** | Polkadot, Kusama, Astar, Bittensor, Enjin |
+| **Cosmos** | Cosmos Hub and Tendermint-based chains |
+| **Aptos** | Aptos, Movement |
+| **Cardano** | Cardano |
+| **Sui** | Sui |
+| **Starknet** | Starknet |
+| **Stellar** | Stellar |
+| **Filecoin** | Filecoin |
+| **Ripple** | XRP Ledger |
+| **TON** | The Open Network |
+
+## Usage
+
+### Token Transfers
+
+Extract token transfers from any supported block with a single interface:
+
+```typescript
+import { templates } from '@indexing/jiti';
+
+const transfers = templates.tokenTransfers.transform(block, {
+  params: {
+    network: 'ETHEREUM',
+    walletAddress: '0x...', // optional - filter by wallet
+    contractAddress: '0x...', // optional - filter by token contract
+    tokenTypes: ['NATIVE', 'TOKEN', 'NFT'], // optional - filter by type
+  },
+});
+```
+
+Each transfer follows the `NetworkTransfer` type:
+
+```typescript
+type NetworkTransfer = {
+  amount: number | bigint;
+  blockNumber: number;
+  from: string;
+  to: string;
+  token?: string;
+  tokenId?: string;
+  tokenType: 'NATIVE' | 'TOKEN' | 'NFT';
+  transactionHash: string;
+  transactionGasFee: bigint;
+  timestamp: string;
+};
+```
+
+### Utilities
+
+```typescript
+import { utils } from '@indexing/jiti';
+
+// Detect the VM type from a raw block
+utils.blockToVM(block); // 'EVM' | 'SVM' | 'CARDANO' | ...
+
+// Extract block number, timestamp, or tx hashes from any block
+utils.blockToBeat(block);
+utils.blockToTimestamp(block);
+utils.blockToTransactionHashes(block);
+
+// EVM-specific helpers
+utils.evmChainToId('ETHEREUM'); // 1
+utils.evmIdToChain(137); // 'POLYGON'
+utils.evmAddressToChecksum('0xabc...');
+utils.evmDecodeLog(log, abi);
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Build
+npm run build
+
+# Lint & format
+npm run lint
+```
+
+### Adding a New Network
+
+Token transfer templates live in `src/templates/token-transfers/`. Each network implements the `SubTemplate` interface:
+
+```typescript
+import { SubTemplate } from '../../types';
+
+export const MyChainTokenTransfers: SubTemplate = {
+  match: (block) => /* return true if this block belongs to your chain */,
+  transform(block) {
+    // Parse the block and return NetworkTransfer[]
+  },
+  tests: [
+    {
+      params: { network: 'MY_CHAIN', walletAddress: '...' },
+      payload: 'https://jiti.indexing.co/networks/my_chain/12345',
+      output: [/* expected NetworkTransfer objects */],
+    },
+  ],
+};
+```
+
+Then register it in `src/templates/token-transfers/index.ts`.
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.
 
 ## License
 
-See the [LICENSE](LICENSE.md) file for license rights and limitations (GPL-3.0-or-later).
+[GPL-3.0-or-later](LICENSE.md) - Copyright 2024 The Indexing Company