@logrix/sdk 0.3.1 → 0.3.2

package/README.md

@@ -24,11 +24,11 @@ npm test
 
 ### `logrix init [name]`
 
-Scaffolds a new indexer project. Run interactively or pass flags for CI/CD automation.
+Scaffolds a new indexer project with built-in presets for 26+ popular mainnets and testnets. Run interactively or pass flags for CI/CD automation.
 
 Options:
 - `-y, --yes` -- non-interactive mode using sensible defaults
-- `--network <name>` -- network preset (`arbitrum-one`, `ethereum`, `base`, `polygon`, `sepolia`)
+- `--network <name>` -- network preset (`arbitrum-one`, `ethereum`, `base`, `optimism`, `polygon`, `bsc`, `avalanche`, `sepolia`, etc.)
 - `--rpc <url>` -- custom RPC endpoint
 - `--contract-name <name>` -- contract name
 - `--address <address>` -- target contract 0x address
@@ -51,6 +51,23 @@ my-indexer/
 
 ---
 
+### `logrix status`
+
+Checks live JSON-RPC connectivity, measures round-trip latency, verifies chain ID match, checks latest block height, and verifies that target smart contracts are deployed with on-chain bytecode.
+
+```bash
+npx logrix status
+```
+
+Output includes:
+- Network Name & Chain ID verification
+- RPC reachability and response latency (ms)
+- Latest chain block number
+- Contract deployment verification (`eth_getCode` bytecode inspection)
+- Sync scope and remaining block delta
+
+---
+
 ### `logrix add contract <name>`
 
 Adds an additional smart contract to an existing `logrix.yaml` project for multi-contract indexing.
@@ -62,7 +79,7 @@ npx logrix add contract SecondaryToken \
   --abi ./my-abis/SecondaryToken.json \
   --start-block 1000000
 
-# Add with automatic ABI fetch from Etherscan / Sourcify
+# Add with automatic ABI fetch from block explorers / Sourcify
 npx logrix add contract DaiToken \
   --address 0x6b175474e89094c44da98b954eedeac495271d0f \
   --fetch-abi
@@ -71,8 +88,8 @@ npx logrix add contract DaiToken \
 Options:
 - `--address <address>` -- contract address
 - `--abi <path>` -- path to local ABI JSON
-- `--fetch-abi` -- auto-fetch verified contract ABI from Etherscan / Sourcify
-- `--etherscan-key <key>` -- optional Etherscan API key for rate limits
+- `--fetch-abi` -- auto-fetch verified contract ABI from block explorers (Etherscan, Arbiscan, Basescan, Polygonscan, etc.) and Sourcify
+- `--etherscan-key <key>` -- optional block explorer API key for rate limits
 - `--start-block <block>` -- initial indexing block
 
 ---
@@ -96,7 +113,7 @@ npx logrix codegen
 ```
 
 Outputs:
-- `src/generated/events.ts` -- typed event and parameter classes (namespaced per contract), multi-contract address constants, and router helpers
+- `src/generated/events.ts` -- typed event and parameter classes (namespaced per contract), multi-contract address constants, router helpers, and dynamic ABI decoding (`string`, `bytes`)
 - `src/generated/schema.ts` -- entity classes with static `.load(id)`, `.remove(id)`, and `.save()`, handling `@derivedFrom` relationships
 
 ---
@@ -165,6 +182,9 @@ Imported via `import { ... } from "@logrix/sdk"` in AssemblyScript handlers:
 | `Bytes` | Hex byte wrapper: `.fromHexString()`, `.fromUTF8()`, `.toHexString()`, `.toByteArray()`, `.length` |
 | `crypto.keccak256(data)` | Computes standard EVM Keccak-256 hash |
 | `formatUnits(val, decimals)` | Formats raw BigInt value into human-readable decimal string (default: 18) |
+| `decodeDynamicString(data, idx)` | Decodes dynamic string parameter from raw ABI event data |
+| `decodeDynamicBytes(data, idx)` | Decodes dynamic bytes parameter from raw ABI event data |
+| `createMockEventLog(config)` | Creates mock EventLog instance for testing mapping logic |
 | `log` | Structured logging: `log.info()`, `log.warning()`, `log.error()`, `log.debug()` |
 | `allocate(size)` | Guest memory allocator (must be re-exported by `mapping.ts`) |
 

package/dist/commands/build.js

@@ -55,6 +55,13 @@ function buildCommand() {
             console.error(`Error: entry file not found: ${opts.entry}`);
             process.exit(1);
         }
+        // Check if generated bindings exist
+        const generatedSchema = path.join(projectDir, "src", "generated", "schema.ts");
+        const generatedEvents = path.join(projectDir, "src", "generated", "events.ts");
+        if (!fs.existsSync(generatedSchema) || !fs.existsSync(generatedEvents)) {
+            console.warn("Notice: Generated bindings (src/generated/) not found or incomplete.");
+            console.warn("Tip: Run `logrix codegen` before `logrix build` to generate typed classes.\n");
+        }
         // Ensure output directory exists
         fs.mkdirSync(path.dirname(outFile), { recursive: true });
         // Prefer logrix.yaml mapping.file if present
@@ -81,7 +88,7 @@ function buildCommand() {
             ascBin = "asc"; // global
         }
         const optimizeFlag = opts.debug ? "" : "--optimize";
-        const cmd = [
+        const ascCmd = [
             ascBin,
             resolvedEntry,
             "--config", "tsconfig.json",
@@ -91,14 +98,18 @@ function buildCommand() {
         ]
             .filter(Boolean)
             .join(" ");
-        console.log(`Running: ${cmd}\n`);
+        console.log(`Running: ${ascCmd}\n`);
         try {
-            (0, child_process_1.execSync)(cmd, { cwd: projectDir, stdio: "inherit" });
+            (0, child_process_1.execSync)(ascCmd, { cwd: projectDir, stdio: "inherit" });
             const stat = fs.statSync(outFile);
             console.log(`\nBuild complete: ${path.relative(projectDir, outFile)} (${stat.size} bytes)`);
         }
         catch {
             console.error("\nBuild failed.");
+            console.error("Troubleshooting tips:");
+            console.error("  1. Verify AssemblyScript types in src/mapping.ts (e.g. use BigInt / Address / Bytes from @logrix/sdk)");
+            console.error("  2. Run `logrix codegen` to refresh generated bindings");
+            console.error("  3. Run `logrix validate` to check configuration syntax\n");
             process.exit(1);
         }
     });

package/dist/commands/codegen.js

@@ -57,7 +57,7 @@ function solTypeToAs(solType) {
 function generateEventsTs(dataSources, projectDir) {
     const lines = [
         "// Auto-generated by `logrix codegen`. Do not edit.",
-        'import { EventLog, BigInt, Address, Bytes } from "@logrix/sdk";',
+        'import { EventLog, BigInt, Address, Bytes, decodeDynamicString, decodeDynamicBytes } from "@logrix/sdk";',
         "",
     ];
     // Contract address constants for multi-contract indexers
@@ -138,23 +138,31 @@ function generateEventsTs(dataSources, projectDir) {
                         topicIdx++;
                     }
                     else {
-                        lines.push(`    {`);
-                        lines.push(`      const dataHex = raw.data.startsWith("0x") ? raw.data.slice(2) : raw.data;`);
-                        lines.push(`      const offset = ${nonIndexedIdx * 64};`);
-                        lines.push(`      const rawWord = dataHex.length >= offset + 64 ? "0x" + dataHex.slice(offset, offset + 64) : (offset == 0 ? raw.data : "");`);
-                        if (asType === "BigInt") {
-                            lines.push(`      this.${inp.name} = BigInt.fromString(rawWord);`);
-                        }
-                        else if (asType === "Address") {
-                            lines.push(`      this.${inp.name} = Address.fromString(rawWord);`);
+                        if (inp.type === "string") {
+                            lines.push(`    this.${inp.name} = decodeDynamicString(raw.data, ${nonIndexedIdx});`);
                         }
-                        else if (asType === "Bytes") {
-                            lines.push(`      this.${inp.name} = Bytes.fromHexString(rawWord);`);
+                        else if (inp.type === "bytes") {
+                            lines.push(`    this.${inp.name} = decodeDynamicBytes(raw.data, ${nonIndexedIdx});`);
                         }
                         else {
-                            lines.push(`      this.${inp.name} = rawWord;`);
+                            lines.push(`    {`);
+                            lines.push(`      const dataHex = raw.data.startsWith("0x") ? raw.data.slice(2) : raw.data;`);
+                            lines.push(`      const offset = ${nonIndexedIdx * 64};`);
+                            lines.push(`      const rawWord = dataHex.length >= offset + 64 ? "0x" + dataHex.slice(offset, offset + 64) : (offset == 0 ? raw.data : "");`);
+                            if (asType === "BigInt") {
+                                lines.push(`      this.${inp.name} = BigInt.fromString(rawWord);`);
+                            }
+                            else if (asType === "Address") {
+                                lines.push(`      this.${inp.name} = Address.fromString(rawWord);`);
+                            }
+                            else if (asType === "Bytes") {
+                                lines.push(`      this.${inp.name} = Bytes.fromHexString(rawWord);`);
+                            }
+                            else {
+                                lines.push(`      this.${inp.name} = rawWord;`);
+                            }
+                            lines.push(`    }`);
                         }
-                        lines.push(`    }`);
                         nonIndexedIdx++;
                     }
                 }

package/dist/commands/status.js

@@ -0,0 +1,140 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.statusCommand = statusCommand;
+const commander_1 = require("commander");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const yaml_1 = require("yaml");
+async function jsonRpcCall(url, method, params = []) {
+    const start = Date.now();
+    try {
+        const res = await fetch(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
+        });
+        const latencyMs = Date.now() - start;
+        if (!res.ok) {
+            return { error: `HTTP ${res.status}: ${res.statusText}`, latencyMs };
+        }
+        const json = await res.json();
+        return { result: json.result, error: json.error, latencyMs };
+    }
+    catch (e) {
+        return { error: e.message, latencyMs: Date.now() - start };
+    }
+}
+function statusCommand() {
+    const cmd = new commander_1.Command("status");
+    cmd
+        .description("Check RPC connectivity, network block height, and contract deployment status")
+        .action(async () => {
+        const projectDir = process.cwd();
+        const configPath = path.join(projectDir, "logrix.yaml");
+        if (!fs.existsSync(configPath)) {
+            console.error("Error: logrix.yaml not found. Run this command from your project root.");
+            process.exit(1);
+        }
+        let config;
+        try {
+            config = (0, yaml_1.parse)(fs.readFileSync(configPath, "utf-8"));
+        }
+        catch (e) {
+            console.error(`Error parsing logrix.yaml: ${e.message}`);
+            process.exit(1);
+        }
+        const networkName = config.network?.name || "unspecified";
+        const configuredChainId = config.network?.chainId;
+        const rpcUrl = config.network?.rpcUrl;
+        console.log("\nLogrix Indexer Status");
+        console.log("============================================================");
+        console.log(`Network Name:     ${networkName}`);
+        console.log(`Configured Chain: ${configuredChainId ?? "Not set"}`);
+        console.log(`RPC Endpoint:     ${rpcUrl || "None"}`);
+        if (!rpcUrl) {
+            console.error("\nError: No RPC URL configured in logrix.yaml.");
+            console.log("============================================================\n");
+            process.exit(1);
+        }
+        // 1. Query block height
+        process.stdout.write("Connecting to RPC endpoint ... ");
+        const blockRes = await jsonRpcCall(rpcUrl, "eth_blockNumber");
+        if (blockRes.error || !blockRes.result) {
+            console.log("FAILED");
+            console.error(`RPC Error: ${JSON.stringify(blockRes.error)} (${blockRes.latencyMs} ms)`);
+            console.log("============================================================\n");
+            process.exit(1);
+        }
+        const latestBlock = parseInt(blockRes.result, 16);
+        console.log(`ONLINE (${blockRes.latencyMs} ms)`);
+        console.log(`Latest Block:     #${latestBlock.toLocaleString()}`);
+        // 2. Query chain ID
+        const chainRes = await jsonRpcCall(rpcUrl, "eth_chainId");
+        if (chainRes.result) {
+            const reportedChainId = parseInt(chainRes.result, 16);
+            const match = configuredChainId === reportedChainId;
+            console.log(`Chain ID Check:   Reported ${reportedChainId} (${match ? "VERIFIED MATCH" : "MISMATCH WARNING"})`);
+        }
+        // 3. Inspect contracts
+        const dataSources = config.dataSources || [];
+        console.log(`\nContracts Monitored (${dataSources.length}):`);
+        console.log("------------------------------------------------------------");
+        for (const ds of dataSources) {
+            const addr = ds.source?.address || "";
+            const name = ds.name || "Unnamed";
+            const startBlock = ds.source?.startBlock ?? 0;
+            if (!addr) {
+                console.log(`  - ${name}: [NO ADDRESS SPECIFIED]`);
+                continue;
+            }
+            const codeRes = await jsonRpcCall(rpcUrl, "eth_getCode", [addr, "latest"]);
+            const code = codeRes.result || "";
+            const isDeployed = code.length > 2 && code !== "0x" && code !== "0x0";
+            const byteSize = isDeployed ? (code.length - 2) / 2 : 0;
+            console.log(`  - Name:        ${name}`);
+            console.log(`    Address:     ${addr}`);
+            console.log(`    Deployed:    ${isDeployed ? `YES (${byteSize.toLocaleString()} bytes bytecode)` : "NO (Empty bytecode / Not found)"}`);
+            console.log(`    Start Block: #${startBlock.toLocaleString()}`);
+            if (latestBlock > startBlock) {
+                const lag = latestBlock - startBlock;
+                console.log(`    Sync Scope:  #${startBlock} -> #${latestBlock} (${lag.toLocaleString()} blocks to process)`);
+            }
+            console.log("");
+        }
+        console.log("============================================================\n");
+    });
+    return cmd;
+}

package/dist/index.js

@@ -9,11 +9,12 @@ const add_1 = require("./commands/add");
 const validate_1 = require("./commands/validate");
 const export_values_1 = require("./commands/export_values");
 const test_1 = require("./commands/test");
+const status_1 = require("./commands/status");
 const program = new commander_1.Command();
 program
     .name("logrix")
     .description("Developer CLI for Logrix blockchain indexers")
-    .version("0.3.1");
+    .version("0.3.2");
 program.addCommand((0, init_1.initCommand)());
 program.addCommand((0, add_1.addCommand)());
 program.addCommand((0, codegen_1.codegenCommand)());
@@ -21,4 +22,5 @@ program.addCommand((0, validate_1.validateCommand)());
 program.addCommand((0, build_1.buildCommand)());
 program.addCommand((0, export_values_1.exportValuesCommand)());
 program.addCommand((0, test_1.testCommand)());
+program.addCommand((0, status_1.statusCommand)());
 program.parse(process.argv);

package/index.ts

@@ -1,3 +1,4 @@
-// Root AssemblyScript entry point — re-exports the full runtime.
+// Root entry point -- re-exports runtime and testing utilities.
 // asc resolves @logrix/sdk to this file when building user handler projects.
 export * from "./src/runtime/index";
+export * from "./src/testing/index";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logrix/sdk",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Official CLI and AssemblyScript runtime library for Logrix blockchain indexers",
   "main": "index.ts",
   "bin": {
@@ -13,6 +13,7 @@
   "files": [
     "dist",
     "src/runtime",
+    "src/testing",
     "index.ts",
     "tsconfig.as.json",
     "README.md"

package/src/runtime/index.ts

@@ -258,6 +258,58 @@ export class Bytes {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Dynamic ABI Offset Decoding Helpers (Solidity Head/Tail)
+// ---------------------------------------------------------------------------
+
+function parseHexI32(hex: string): i32 {
+  let val: i32 = 0;
+  for (let i = 0; i < hex.length; i++) {
+    val = (val << 4) | parseHexChar(hex.charCodeAt(i));
+  }
+  return val;
+}
+
+export function decodeDynamicString(dataHex: string, paramIndex: i32): string {
+  let clean = dataHex.startsWith("0x") ? dataHex.slice(2) : dataHex;
+  const headOffset = paramIndex * 64;
+  if (clean.length < headOffset + 64) return "";
+  const ptrWord = clean.slice(headOffset, headOffset + 64);
+  const offsetBytes = parseHexI32(ptrWord);
+  const offsetHex = offsetBytes * 2;
+  if (clean.length < offsetHex + 64) return "";
+  const lenWord = clean.slice(offsetHex, offsetHex + 64);
+  const byteLen = parseHexI32(lenWord);
+  const contentHexStart = offsetHex + 64;
+  const contentHexEnd = contentHexStart + byteLen * 2;
+  if (clean.length < contentHexEnd) return "";
+  const contentHex = clean.slice(contentHexStart, contentHexEnd);
+  const bytes = new Uint8Array(byteLen);
+  for (let i = 0; i < byteLen; i++) {
+    const high = parseHexChar(contentHex.charCodeAt(i * 2));
+    const low = parseHexChar(contentHex.charCodeAt(i * 2 + 1));
+    bytes[i] = ((high << 4) | low) as u8;
+  }
+  return String.UTF8.decode(bytes.buffer);
+}
+
+export function decodeDynamicBytes(dataHex: string, paramIndex: i32): Bytes {
+  let clean = dataHex.startsWith("0x") ? dataHex.slice(2) : dataHex;
+  const headOffset = paramIndex * 64;
+  if (clean.length < headOffset + 64) return Bytes.fromHexString("0x");
+  const ptrWord = clean.slice(headOffset, headOffset + 64);
+  const offsetBytes = parseHexI32(ptrWord);
+  const offsetHex = offsetBytes * 2;
+  if (clean.length < offsetHex + 64) return Bytes.fromHexString("0x");
+  const lenWord = clean.slice(offsetHex, offsetHex + 64);
+  const byteLen = parseHexI32(lenWord);
+  const contentHexStart = offsetHex + 64;
+  const contentHexEnd = contentHexStart + byteLen * 2;
+  if (clean.length < contentHexEnd) return Bytes.fromHexString("0x");
+  const contentHex = clean.slice(contentHexStart, contentHexEnd);
+  return Bytes.fromHexString("0x" + contentHex);
+}
+
 // ---------------------------------------------------------------------------
 // Keccak-256 Implementation & Crypto namespace
 // ---------------------------------------------------------------------------

package/src/testing/index.ts

@@ -0,0 +1,29 @@
+import { EventLog } from "../runtime";
+
+export interface MockEventLogConfig {
+  address?: string;
+  blockNumber?: number;
+  blockHash?: string;
+  transactionHash?: string;
+  logIndex?: number;
+  blockTimestamp?: number;
+  topics?: string[];
+  data?: string;
+}
+
+/**
+ * Construct an EventLog instance pre-populated with test values.
+ * Useful for writing local unit tests for AssemblyScript/TypeScript mapping handlers.
+ */
+export function createMockEventLog(config: MockEventLogConfig = {}): EventLog {
+  const log = new EventLog();
+  log.address = config.address || "0x0000000000000000000000000000000000000000";
+  log.block_number = BigInt(config.blockNumber ?? 1) as any;
+  log.block_hash = config.blockHash || "0x0000000000000000000000000000000000000000000000000000000000000000";
+  log.transaction_hash = config.transactionHash || "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef";
+  log.log_index = (config.logIndex ?? 0) as any;
+  log.block_timestamp = BigInt(config.blockTimestamp ?? 1700000000) as any;
+  log.topics = config.topics || [];
+  log.data = config.data || "0x";
+  return log;
+}