@chainfoundry/chaincodec 0.1.1 → 0.1.2

package/README.md

@@ -26,7 +26,7 @@ No build step required — pre-built native binaries are bundled for all major p
 ## Platform support
 
 | Platform | Architecture | Supported |
-|----------|-------------|-----------|
+| --- | --- | --- |
 | Linux (glibc) | x64 | ✅ |
 | Linux (glibc) | arm64 | ✅ |
 | Linux (musl / Alpine) | x64 | ✅ |
@@ -36,14 +36,34 @@ No build step required — pre-built native binaries are bundled for all major p
 
 ---
 
-## Quick start
+## Quick start — decode an EVM event log
 
 ```typescript
 import { EvmDecoder, MemoryRegistry } from '@chainfoundry/chaincodec';
 
-// 1. Load schemas
+// 1. Load your schemas (CSDL YAML format)
 const registry = new MemoryRegistry();
-registry.loadDirectory('./node_modules/@chainfoundry/chaincodec/schemas');
+
+// Load from inline CSDL string
+registry.loadCsdl(`
+schema ERC20Transfer:
+  version: 1
+  description: "ERC-20 standard Transfer event"
+  chains: [ethereum, arbitrum, base, polygon, optimism]
+  event: Transfer
+  fingerprint: "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
+  fields:
+    from:  { type: address, indexed: true }
+    to:    { type: address, indexed: true }
+    value: { type: uint256, indexed: false }
+  meta:
+    protocol: erc20
+    category: token
+`);
+
+// Or load from files on disk
+// registry.loadFile('./schemas/erc20.csdl');
+// registry.loadDirectory('./schemas');
 
 // 2. Decode a raw log from eth_getLogs
 const decoder = new EvmDecoder();
@@ -51,8 +71,8 @@ const decoder = new EvmDecoder();
 const rawLog = {
   chain: 'ethereum',
   txHash: '0xabc123...',
-  blockNumber: 19500000n,
-  blockTimestamp: 1710000000n,
+  blockNumber: 19500000,
+  blockTimestamp: 1710000000,
   logIndex: 0,
   address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48', // USDC
   topics: [
@@ -63,16 +83,13 @@ const rawLog = {
   data: '0x00000000000000000000000000000000000000000000000000000000000f4240',
 };
 
-const fp = decoder.fingerprint(rawLog);
-const schema = registry.getByFingerprint(fp);
+const event = decoder.decodeEvent(rawLog, registry);
 
-if (schema) {
-  const event = decoder.decodeEvent(rawLog, schema);
-  console.log(event.schemaName);       // "ERC20Transfer"
-  console.log(event.fields.from);      // "0xd8da6bf2..."
-  console.log(event.fields.to);        // "0xab5801a7..."
-  console.log(event.fields.value);     // "1000000"  (1 USDC)
-}
+console.log(event.schema);          // "ERC20Transfer"
+console.log(event.fields.from);     // { type: 'address', value: '0xd8da6bf2...' }
+console.log(event.fields.to);       // { type: 'address', value: '0xab5801a7...' }
+console.log(event.fields.value);    // { type: 'biguint', value: '1000000' }
+console.log(event.fingerprint);     // "0xddf252ad..."
 ```
 
 ---
@@ -84,159 +101,276 @@ import { EvmCallDecoder } from '@chainfoundry/chaincodec';
 import { readFileSync } from 'fs';
 
 // Load ABI JSON (from Etherscan, Hardhat artifacts, Foundry out/, etc.)
-const abiJson = readFileSync('./abi/uniswap_v3_router.json', 'utf-8');
+const abiJson = readFileSync('./abi/erc20.json', 'utf-8');
 const decoder = EvmCallDecoder.fromAbiJson(abiJson);
 
 // Decode raw calldata from a transaction's `input` field
-const calldata = '0x414bf389...';
+const calldata = '0xa9059cbb000000000000000000000000d8da6bf26964af9d7eed9e03e53415d37aa96045000000000000000000000000000000000000000000000000000000000000000a';
 const call = decoder.decodeCall(calldata);
 
-console.log(call.functionName);        // "exactInputSingle"
-for (const [name, value] of Object.entries(call.inputs)) {
-  console.log(`  ${name}: ${value}`);
+console.log(call.functionName);   // "transfer"
+console.log(call.selector);       // "0xa9059cbb"
+
+for (const [name, value] of call.inputs) {
+  console.log(`  ${name}:`, value);
 }
-// tokenIn:      0xC02aaA39b... (WETH)
-// tokenOut:     0xA0b8699...  (USDC)
-// amountIn:     1000000000000000000
-// amountOutMin: 1800000000
+// to:     { type: 'address', value: '0xd8da6bf2...' }
+// amount: { type: 'biguint', value: '10' }
+
+// List all functions in the ABI
+console.log(decoder.functionNames());            // ['transfer', 'approve', ...]
+console.log(decoder.selectorFor('transfer'));    // "0xa9059cbb"
 ```
 
 ---
 
+## ABI encode a function call
+
+`encodeCall` takes `argsJson` — a JSON string of `NormalizedValue[]`.
+Each `NormalizedValue` has `{ type, value }` matching the Solidity type.
+
+```typescript
+import { EvmEncoder } from '@chainfoundry/chaincodec';
+
+const abiJson = JSON.stringify([{
+  name: 'transfer',
+  type: 'function',
+  inputs: [
+    { name: 'to',     type: 'address' },
+    { name: 'amount', type: 'uint256' },
+  ],
+  outputs: [{ name: '', type: 'bool' }],
+  stateMutability: 'nonpayable',
+}]);
+
+const encoder = EvmEncoder.fromAbiJson(abiJson);
+
+const calldata = encoder.encodeCall(
+  'transfer',
+  JSON.stringify([
+    { type: 'address', value: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045' },
+    { type: 'uint',    value: 1000000 },
+  ])
+);
+
+console.log(calldata);
+// "0xa9059cbb000000000000000000000000d8da6bf2...000f4240"
+// First 4 bytes (0xa9059cbb) = transfer(address,uint256) selector
+```
+
+### NormalizedValue input types for encoding
+
+| Solidity type | `NormalizedValue` JSON |
+| --- | --- |
+| `address` | `{ "type": "address", "value": "0x..." }` |
+| `uint256` | `{ "type": "uint", "value": 1000000 }` |
+| `uint256` (large) | `{ "type": "biguint", "value": "99999999999999999999" }` |
+| `int256` | `{ "type": "int", "value": -100 }` |
+| `bool` | `{ "type": "bool", "value": true }` |
+| `bytes` | `{ "type": "bytes", "value": [0xde, 0xad, 0xbe, 0xef] }` |
+| `string` | `{ "type": "str", "value": "hello" }` |
+| `address[]` | `{ "type": "array", "value": [{ "type": "address", "value": "0x..." }] }` |
+
+---
+
 ## Batch decode
 
+Decode thousands of logs in parallel using Rayon (Rust's parallel iterator):
+
 ```typescript
-import { BatchEngine, BatchRequest, ErrorMode } from '@chainfoundry/chaincodec';
+import { EvmDecoder, MemoryRegistry } from '@chainfoundry/chaincodec';
+
+const registry = new MemoryRegistry();
+registry.loadCsdl(/* your CSDL schemas */);
+
+const decoder = new EvmDecoder();
+
+// Decode a batch of raw logs — returns { events, errors }
+const { events, errors } = decoder.decodeBatch(rawLogs, registry);
+
+console.log(`decoded: ${events.length} events`);
+console.log(`errors:  ${errors.length}`);
 
-const engine = new BatchEngine(registry);
-engine.addDecoder('ethereum', new EvmDecoder());
+for (const event of events) {
+  console.log(event.schema, event.fields);
+}
 
-const logs = await fetchLogsFromRpc(fromBlock, toBlock);  // RawLog[]
+for (const { index, error } of errors) {
+  console.warn(`log[${index}] failed: ${error}`);
+}
+```
+
+---
 
-const result = engine.decode({
+## Compute topic0 fingerprint
+
+```typescript
+const decoder = new EvmDecoder();
+
+const fp = decoder.fingerprint({
   chain: 'ethereum',
-  logs,
-  chunkSize: 10_000,
-  errorMode: ErrorMode.Collect,
-  onProgress: (decoded, total) => {
-    process.stdout.write(`\r${decoded}/${total}`);
+  txHash: '0x0',
+  blockNumber: 0,
+  blockTimestamp: 0,
+  logIndex: 0,
+  address: '0x0000000000000000000000000000000000000000',
+  topics: ['0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef'],
+  data: '0x',
+});
+console.log(fp); // "0xddf252ad..."
+```
+
+---
+
+## EIP-712 typed data
+
+```typescript
+import { Eip712Parser } from '@chainfoundry/chaincodec';
+
+const parser = new Eip712Parser();
+
+const typedDataJson = JSON.stringify({
+  types: {
+    EIP712Domain: [
+      { name: 'name', type: 'string' },
+      { name: 'version', type: 'string' },
+      { name: 'chainId', type: 'uint256' },
+    ],
+    Transfer: [
+      { name: 'to',     type: 'address' },
+      { name: 'amount', type: 'uint256' },
+    ],
   },
+  primaryType: 'Transfer',
+  domain: { name: 'MyToken', version: '1', chainId: 1 },
+  message: { to: '0xd8dA...', amount: '1000000' },
 });
 
-console.log(`decoded: ${result.events.length}`);
-console.log(`errors:  ${result.errors.length}`);
+const parsed = parser.parse(typedDataJson);
+console.log(parsed.primary_type);  // "Transfer"  (snake_case from Rust serde)
+
+const domainHash = parser.domainSeparator(typedDataJson);
+console.log(domainHash);           // "0x..."
 ```
 
 ---
 
-## Compute topic0 fingerprint
+## Using CommonJS
 
-```typescript
-import { computeFingerprint } from '@chainfoundry/chaincodec';
+```javascript
+const { EvmDecoder, MemoryRegistry, EvmCallDecoder, EvmEncoder, Eip712Parser } = require('@chainfoundry/chaincodec');
 
-const fp = computeFingerprint('Transfer(address,address,uint256)');
-// "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
+const registry = new MemoryRegistry();
+registry.loadCsdl(csdlString);
 
-const fp2 = computeFingerprint('Swap(address,uint256,uint256,uint256,uint256,address)');
-// Uniswap V2 Swap topic0
+const decoder = new EvmDecoder();
+const event = decoder.decodeEvent(rawLog, registry);
 ```
 
 ---
 
 ## API reference
 
+### `MemoryRegistry`
+
+| Method / Property | Signature | Description |
+| --- | --- | --- |
+| `constructor` | `new MemoryRegistry()` | Create empty registry |
+| `loadCsdl` | `(csdl: string) => number` | Load schemas from CSDL YAML string; returns count loaded |
+| `loadFile` | `(path: string) => number` | Load a single `.csdl` file |
+| `loadDirectory` | `(path: string) => number` | Load all `.csdl` files in a directory |
+| `schemaCount` | `readonly number` | Number of schemas registered |
+| `schemaNames` | `() => string[]` | List all schema names |
+
 ### `EvmDecoder`
 
-| Method | Description |
-|--------|-------------|
-| `fingerprint(log)` | Compute topic0 fingerprint from a raw log |
-| `decodeEvent(log, schema)` | Decode an EVM log into named fields |
+| Method | Signature | Description |
+| --- | --- | --- |
+| `constructor` | `new EvmDecoder()` | Create decoder |
+| `decodeEvent` | `(raw: RawEvent, registry: MemoryRegistry) => DecodedEvent` | Decode a single EVM log |
+| `decodeBatch` | `(raws: RawEvent[], registry: MemoryRegistry) => BatchDecodeResult` | Parallel-decode many logs |
+| `fingerprint` | `(raw: RawEvent) => string` | Get topic0 fingerprint hex string |
 
 ### `EvmCallDecoder`
 
-| Method | Description |
-|--------|-------------|
-| `EvmCallDecoder.fromAbiJson(json)` | Create decoder from ABI JSON string |
-| `decodeCall(calldata, blockNumber?)` | Decode function calldata |
-| `encodeCall(functionName, args)` | ABI-encode a function call |
+| Method | Signature | Description |
+| --- | --- | --- |
+| `fromAbiJson` | `(abiJson: string) => EvmCallDecoder` | Create from ABI JSON (static factory) |
+| `decodeCall` | `(calldata: string, functionName?: string or null) => DecodedCall` | Decode calldata |
+| `functionNames` | `() => string[]` | List all function names in ABI |
+| `selectorFor` | `(functionName: string) => string or null` | Get 4-byte selector hex |
 
-### `MemoryRegistry`
+### `EvmEncoder`
 
-| Method | Description |
-|--------|-------------|
-| `loadFile(path)` | Load a CSDL schema file |
-| `loadDirectory(path)` | Load all `.csdl` files in a directory |
-| `getByFingerprint(fp)` | Look up schema by topic0 hash |
-| `getByName(name)` | Look up schema by name |
-| `allSchemas()` | Return all registered schemas |
+| Method | Signature | Description |
+| --- | --- | --- |
+| `fromAbiJson` | `(abiJson: string) => EvmEncoder` | Create from ABI JSON (static factory) |
+| `encodeCall` | `(functionName: string, argsJson: string) => string` | Encode; `argsJson` = `JSON.stringify(NormalizedValue[])`, returns `0x`-hex |
 
-### `BatchEngine`
+### `Eip712Parser`
 
-| Method | Description |
-|--------|-------------|
-| `addDecoder(chainSlug, decoder)` | Register a decoder for a chain |
-| `decode(request)` | Batch decode a list of raw logs |
+| Method | Signature | Description |
+| --- | --- | --- |
+| `constructor` | `new Eip712Parser()` | Create parser |
+| `parse` | `(json: string) => TypedData` | Parse EIP-712 typed data JSON |
+| `domainSeparator` | `(json: string) => string` | Compute domain separator hash |
 
 ---
 
 ## TypeScript types
 
 ```typescript
-interface RawLog {
-  chain: string;
+interface RawEvent {
+  chain: string;          // "ethereum" | "arbitrum" | "base" | "polygon" | "optimism" | numeric id
   txHash: string;
-  blockNumber: bigint;
-  blockTimestamp: bigint;
+  blockNumber: number;
+  blockTimestamp: number; // Unix seconds
   logIndex: number;
-  address: string;
-  topics: string[];
-  data: string;
+  address: string;        // contract address (hex, lowercase ok)
+  topics: string[];       // topics[0] = event signature hash
+  data: string;           // hex with 0x prefix
 }
 
 interface DecodedEvent {
-  schemaName: string;
+  schema: string;                          // schema name, e.g. "ERC20Transfer"
+  schemaVersion: number;
   chain: string;
-  blockNumber: bigint;
   txHash: string;
+  blockNumber: number;
+  blockTimestamp: number;
   logIndex: number;
-  fields: Record<string, string>;  // NormalizedValue as string
+  address: string;
+  fields: Record<string, NormalizedValue>; // decoded fields by name
+  fingerprint: string;                     // keccak256 of topics[0]
+  decodeErrors: Record<string, string>;    // fields that failed to decode
 }
 
 interface DecodedCall {
   functionName: string;
-  inputs: Record<string, string>;
+  selector: string | null;                 // "0xaabbccdd"
+  inputs: Array<[string, NormalizedValue]>; // [name, value] pairs
+  decodeErrors: Record<string, string>;
 }
-```
 
----
-
-## Using CommonJS
-
-```javascript
-const { EvmDecoder, MemoryRegistry } = require('@chainfoundry/chaincodec');
-
-const registry = new MemoryRegistry();
-registry.loadDirectory('./schemas');
-
-const decoder = new EvmDecoder();
-```
-
----
-
-## Bundled schemas
-
-The package ships with 50+ CSDL schemas covering ERC-20/721/1155, Uniswap, Aave, Compound, ChainLink, and more. Schemas are in the `schemas/` subdirectory of the installed package.
-
-```typescript
-import { join } from 'path';
-import { createRequire } from 'module';
-
-const require = createRequire(import.meta.url);
-const schemasDir = join(
-  require.resolve('@chainfoundry/chaincodec/package.json'),
-  '../schemas'
-);
-registry.loadDirectory(schemasDir);
+type NormalizedValue =
+  | { type: 'uint';      value: number }
+  | { type: 'biguint';   value: string }   // large uint256 as decimal string
+  | { type: 'int';       value: number }
+  | { type: 'bigint';    value: string }
+  | { type: 'bool';      value: boolean }
+  | { type: 'bytes';     value: number[] }
+  | { type: 'str';       value: string }
+  | { type: 'address';   value: string }   // "0x..." lowercase
+  | { type: 'hash256';   value: string }
+  | { type: 'timestamp'; value: number }
+  | { type: 'array';     value: NormalizedValue[] }
+  | { type: 'tuple';     value: Array<[string, NormalizedValue]> }
+  | { type: 'null' }
+
+interface BatchDecodeResult {
+  events: DecodedEvent[];
+  errors: Array<{ index: number; error: string }>;
+}
 ```
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chainfoundry/chaincodec",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Universal blockchain ABI decoder — production-grade event & call decoding for Ethereum and EVM chains",
   "keywords": [
     "ethereum",