@indexing/jiti 0.0.75 → 0.0.78

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

package/dist/main.js

@@ -284,6 +284,7 @@ function $596a656635c74d50$export$db81f9ea057ab646(address) {
 var $e5566e47593dc3e2$exports = {};
 
 $parcel$export($e5566e47593dc3e2$exports, "evmChainToId", () => $e5566e47593dc3e2$export$f93b8abed77a4120);
+$parcel$export($e5566e47593dc3e2$exports, "evmIdToChain", () => $e5566e47593dc3e2$export$88f733cc92705522);
 const $e5566e47593dc3e2$var$CHAIN_ID = {
     "0G": 16661,
     ABSTRACT: 2741,
@@ -409,6 +410,11 @@ const $e5566e47593dc3e2$var$CHAIN_ID = {
 function $e5566e47593dc3e2$export$f93b8abed77a4120(chain) {
     return $e5566e47593dc3e2$var$CHAIN_ID[chain?.toUpperCase()];
 }
+const $e5566e47593dc3e2$var$ID_TO_CHAIN = {};
+for (const [chain, id] of Object.entries($e5566e47593dc3e2$var$CHAIN_ID))if (!(id in $e5566e47593dc3e2$var$ID_TO_CHAIN)) $e5566e47593dc3e2$var$ID_TO_CHAIN[id] = chain;
+function $e5566e47593dc3e2$export$88f733cc92705522(id) {
+    return $e5566e47593dc3e2$var$ID_TO_CHAIN[typeof id === "string" ? Number(id) : id];
+}
 
 
 var $da55be3e40667945$exports = {};
@@ -899,20 +905,41 @@ const $60d24c82dc5feb2e$export$893111d8d332e195 = {
                 return acc + val;
             }, BigInt(0));
             const transactionFee = sumInputs + BigInt(sumOutputs);
+            const absFee = transactionFee < 0 ? -transactionFee : transactionFee;
+            const blockNumber = block.block_identifier.index;
             for (const out of outputs){
+                const toAddress = out.account?.address || "";
+                // ADA (native) transfer
                 const rawValue = out.amount?.value || "0";
                 const absoluteValue = BigInt(rawValue);
                 transfers.push({
                     amount: absoluteValue < 0 ? -absoluteValue : absoluteValue,
-                    blockNumber: block.block_identifier.index,
+                    blockNumber: blockNumber,
                     from: fromAddress,
                     timestamp: blockTimestamp,
-                    to: out.account?.address || "",
+                    to: toAddress,
                     token: out.amount?.currency?.symbol?.toUpperCase() === "ADA" ? null : out.amount?.currency?.symbol,
                     tokenType: out.amount?.currency?.symbol?.toUpperCase() === "ADA" ? "NATIVE" : "TOKEN",
-                    transactionGasFee: transactionFee < 0 ? -transactionFee : transactionFee,
+                    transactionGasFee: absFee,
                     transactionHash: transactionHash
                 });
+                // Native tokens from tokenBundle metadata
+                if (out.metadata?.tokenBundle) {
+                    for (const bundle of out.metadata.tokenBundle)for (const tkn of bundle.tokens){
+                        const tokenValue = BigInt(tkn.value);
+                        transfers.push({
+                            amount: tokenValue < 0 ? -tokenValue : tokenValue,
+                            blockNumber: blockNumber,
+                            from: fromAddress,
+                            timestamp: blockTimestamp,
+                            to: toAddress,
+                            token: `${bundle.policyId}.${tkn.currency.symbol}`,
+                            tokenType: "TOKEN",
+                            transactionGasFee: absFee,
+                            transactionHash: transactionHash
+                        });
+                    }
+                }
             }
         }
         return transfers;
@@ -938,6 +965,59 @@ const $60d24c82dc5feb2e$export$893111d8d332e195 = {
                     transactionHash: "261c42ba9124f55d8e169ebb692cd3759d796a54369acb316ee449b546e79309"
                 }
             ]
+        },
+        {
+            params: {
+                network: "CARDANO",
+                transactionHash: "c807ee792e47b47178aea89c9e760020ea24ed80897f9de82a2cd23e05da4d18"
+            },
+            payload: "https://jiti.indexing.co/networks/cardano/13119492",
+            output: [
+                {
+                    amount: 1159390n,
+                    blockNumber: 13119492,
+                    from: "addr1q9k660rwqcdsr8e4ema5jd9qahmfquf44n8uszvacvvfswlrzr27g03klu862usxqsru794d03gzkk8n86ta34n85z0s6j9ylh",
+                    timestamp: "2026-03-05T09:34:59.000Z",
+                    to: "addr1qxvhvz9860r2qzcmx0qz55gzdt58etren35hhn9etpe3j5yewcy2057x5q93kv7q9fgsy6hg0jk8n8rf00xtjkrnr9gq7mz2sz",
+                    token: null,
+                    tokenType: "NATIVE",
+                    transactionGasFee: 178481n,
+                    transactionHash: "c807ee792e47b47178aea89c9e760020ea24ed80897f9de82a2cd23e05da4d18"
+                },
+                {
+                    amount: 100000000n,
+                    blockNumber: 13119492,
+                    from: "addr1q9k660rwqcdsr8e4ema5jd9qahmfquf44n8uszvacvvfswlrzr27g03klu862usxqsru794d03gzkk8n86ta34n85z0s6j9ylh",
+                    timestamp: "2026-03-05T09:34:59.000Z",
+                    to: "addr1qxvhvz9860r2qzcmx0qz55gzdt58etren35hhn9etpe3j5yewcy2057x5q93kv7q9fgsy6hg0jk8n8rf00xtjkrnr9gq7mz2sz",
+                    token: "0691b2fecca1ac4f53cb6dfb00b7013e561d1f34403b957cbb5af1fa.4e49474854",
+                    tokenType: "TOKEN",
+                    transactionGasFee: 178481n,
+                    transactionHash: "c807ee792e47b47178aea89c9e760020ea24ed80897f9de82a2cd23e05da4d18"
+                },
+                {
+                    amount: 172823143n,
+                    blockNumber: 13119492,
+                    from: "addr1q9k660rwqcdsr8e4ema5jd9qahmfquf44n8uszvacvvfswlrzr27g03klu862usxqsru794d03gzkk8n86ta34n85z0s6j9ylh",
+                    timestamp: "2026-03-05T09:34:59.000Z",
+                    to: "addr1q8dusprx8fr89xkl88g3gq5kya46s9r4fcnwyx5yhdp3rx8rzr27g03klu862usxqsru794d03gzkk8n86ta34n85z0s8728d0",
+                    token: null,
+                    tokenType: "NATIVE",
+                    transactionGasFee: 178481n,
+                    transactionHash: "c807ee792e47b47178aea89c9e760020ea24ed80897f9de82a2cd23e05da4d18"
+                },
+                {
+                    amount: 204930000n,
+                    blockNumber: 13119492,
+                    from: "addr1q9k660rwqcdsr8e4ema5jd9qahmfquf44n8uszvacvvfswlrzr27g03klu862usxqsru794d03gzkk8n86ta34n85z0s6j9ylh",
+                    timestamp: "2026-03-05T09:34:59.000Z",
+                    to: "addr1q8dusprx8fr89xkl88g3gq5kya46s9r4fcnwyx5yhdp3rx8rzr27g03klu862usxqsru794d03gzkk8n86ta34n85z0s8728d0",
+                    token: "0691b2fecca1ac4f53cb6dfb00b7013e561d1f34403b957cbb5af1fa.4e49474854",
+                    tokenType: "TOKEN",
+                    transactionGasFee: 178481n,
+                    transactionHash: "c807ee792e47b47178aea89c9e760020ea24ed80897f9de82a2cd23e05da4d18"
+                }
+            ]
         }
     ]
 };