@logrix/sdk 0.3.0

package/README.md

@@ -0,0 +1,231 @@
+# @logrix/sdk
+
+Official CLI and AssemblyScript runtime library for [Logrix](https://github.com/Vishal-770/Logrix) blockchain indexers.
+
+[![npm](https://img.shields.io/npm/v/@logrix/sdk)](https://www.npmjs.com/package/@logrix/sdk)
+
+---
+
+## Quick Start
+
+```bash
+npx @logrix/sdk init my-indexer
+cd my-indexer
+npm install
+npm run codegen
+npm run validate
+npm run build
+npm test
+```
+
+---
+
+## CLI Commands
+
+### `logrix init [name]`
+
+Scaffolds a new indexer project. 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`)
+- `--rpc <url>` -- custom RPC endpoint
+- `--contract-name <name>` -- contract name
+- `--address <address>` -- target contract 0x address
+- `--start-block <block>` -- initial indexing block
+
+Creates:
+```
+my-indexer/
+  logrix.yaml          # indexer manifest: network, contracts, ABIs, WASM path
+  schema.graphql       # entity definitions
+  abis/
+    TokenContract.json # contract ABI
+  src/
+    mapping.ts         # handler logic
+  package.json
+  tsconfig.json
+  .gitignore
+  README.md
+```
+
+---
+
+### `logrix add contract <name>`
+
+Adds an additional smart contract to an existing `logrix.yaml` project for multi-contract indexing.
+
+```bash
+# Add with manual ABI path
+npx logrix add contract SecondaryToken \
+  --address 0x1111111111111111111111111111111111111111 \
+  --abi ./my-abis/SecondaryToken.json \
+  --start-block 1000000
+
+# Add with automatic ABI fetch from Etherscan / Sourcify
+npx logrix add contract DaiToken \
+  --address 0x6b175474e89094c44da98b954eedeac495271d0f \
+  --fetch-abi
+```
+
+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
+- `--start-block <block>` -- initial indexing block
+
+---
+
+### `logrix validate`
+
+Validates your `logrix.yaml`, contract addresses, ABI files, `schema.graphql` entities, and handler mappings before compilation.
+
+```bash
+npx logrix validate
+```
+
+---
+
+### `logrix codegen`
+
+Parses `logrix.yaml` dataSources, ABI files, and `schema.graphql` to generate typed AssemblyScript bindings.
+
+```bash
+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/schema.ts` -- entity classes with static `.load(id)`, `.remove(id)`, and `.save()`, handling `@derivedFrom` relationships
+
+---
+
+### `logrix build`
+
+Compiles your AssemblyScript handler into an optimized WebAssembly module (`build/mapping.wasm`).
+
+```bash
+npx logrix build
+```
+
+Options:
+- `--entry <file>` -- handler entry point (default: `src/mapping.ts`)
+- `--out <file>` -- output WASM binary path (default: `build/mapping.wasm`)
+- `--debug` -- compile without optimizations for debugging
+
+---
+
+### `logrix export-values`
+
+Reads `logrix.yaml`, `schema.graphql`, and `build/mapping.wasm` to produce a ready-to-deploy `indexer-values.yaml` for Helm.
+
+```bash
+npx logrix export-values
+```
+
+Options:
+- `--out <file>` -- output values file (default: `indexer-values.yaml`)
+- `--chain-id <id>` -- override chain ID
+- `--rpc <url>` -- override RPC URL
+
+Deploy directly to Kubernetes:
+```bash
+helm install logrix oci://ghcr.io/vishal-770/charts/logrix \
+  -f cluster-infra.yaml \
+  -f indexer-values.yaml
+```
+
+---
+
+### `logrix test`
+
+Runs local test validation across configuration, code generation, and WASM compilation, and executes any unit tests in `tests/`.
+
+```bash
+npx logrix test
+```
+
+---
+
+## Runtime API
+
+Imported via `import { ... } from "@logrix/sdk"` in AssemblyScript handlers:
+
+| Export | Description |
+|--------|-------------|
+| `store.get(entity, id)` | Load raw entity JSON string from persistent store |
+| `store.set(entity, id, data)` | Write entity to persistent store and stage for DB |
+| `store.remove(entity, id)` | Mark entity as deleted and stage soft-delete |
+| `Entity.load(id)` | Auto-generated on each `@entity` class; loads existing entity or returns `null` |
+| `Entity.remove(id)` | Auto-generated on each `@entity` class; removes entity by ID |
+| `entity.save()` | Saves and persists entity state |
+| `BigInt` | EVM 256-bit safe arithmetic: `.plus()`, `.minus()`, `.times()`, `.div()`, `.equals()`, `.gt()`, `.lt()` |
+| `Address` | Address wrapper: `.fromString()`, `.toHexString()`, `.equals()` |
+| `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) |
+| `log` | Structured logging: `log.info()`, `log.warning()`, `log.error()`, `log.debug()` |
+| `allocate(size)` | Guest memory allocator (must be re-exported by `mapping.ts`) |
+
+---
+
+## Writing Handlers (`src/mapping.ts`)
+
+```typescript
+import { EventLog, log, BigInt, Address, crypto, formatUnits, allocate } from "@logrix/sdk";
+import { TransferEvent } from "./generated/events";
+import { Transfer } from "./generated/schema";
+
+export { allocate } from "@logrix/sdk";
+
+export function handle_event(ptr: i32, len: i32): i32 {
+  const bytes = new Uint8Array(len);
+  for (let i = 0; i < len; i++) {
+    bytes[i] = load<u8>(ptr + i);
+  }
+  const raw = String.UTF8.decode(bytes.buffer);
+
+  if (raw.includes("Transfer")) {
+    return handleTransfer(raw);
+  }
+  return 0;
+}
+
+function handleTransfer(raw: string): i32 {
+  const event = new TransferEvent(new EventLog());
+
+  const entityId = event.transactionHash + "-" + event.logIndex.toString();
+
+  // Load existing entity or instantiate a new one
+  let entity = Transfer.load(entityId);
+  if (!entity) {
+    entity = new Transfer(entityId);
+  }
+
+  entity.fromAddress = event.params.from.toHexString();
+  entity.toAddress = event.params.to.toHexString();
+  entity.amount = event.params.value; // Typed BigInt
+  entity.save();
+
+  log.info("Indexed transfer: " + entityId);
+  return 0;
+}
+```
+
+---
+
+## Deployment
+
+1. Use `@logrix/sdk` to build and export your indexer:
+   ```bash
+   logrix codegen && logrix build && logrix export-values
+   ```
+2. Deploy via Helm to your Kubernetes cluster:
+   ```bash
+   helm install logrix oci://ghcr.io/vishal-770/charts/logrix \
+     -f cluster-infra.yaml \
+     -f indexer-values.yaml
+   ```
+
+Refer to the [Logrix Helm Chart](https://github.com/Vishal-770/Logrix) for full Helm deployment options.

package/dist/commands/add.js

@@ -0,0 +1,235 @@
+"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.addCommand = addCommand;
+const commander_1 = require("commander");
+const prompts_1 = require("@inquirer/prompts");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const yaml_1 = require("yaml");
+const templates_1 = require("../templates");
+/**
+ * Fetch ABI from Etherscan (mainnet) or Sourcify as fallback.
+ * Returns the parsed ABI array, or null if both fail.
+ */
+async function fetchAbi(address, etherscanKey) {
+    const addr = address.toLowerCase();
+    // Try Etherscan first if API key provided
+    if (etherscanKey) {
+        try {
+            const url = `https://api.etherscan.io/api?module=contract&action=getabi&address=${addr}&apikey=${etherscanKey}`;
+            const resp = await fetch(url);
+            const json = await resp.json();
+            if (json.status === "1" && json.result) {
+                const parsed = JSON.parse(json.result);
+                if (Array.isArray(parsed) && parsed.length > 0) {
+                    console.log(`  Fetched ABI from Etherscan for ${address}`);
+                    return parsed;
+                }
+            }
+        }
+        catch {
+            // fall through
+        }
+    }
+    // Try Sourcify (no key required)
+    try {
+        // Sourcify returns verified contracts at chainId 1 (mainnet)
+        const url = `https://repo.sourcify.dev/contracts/full_match/1/${addr}/metadata.json`;
+        const resp = await fetch(url);
+        if (resp.ok) {
+            const json = await resp.json();
+            const abi = json?.output?.abi;
+            if (Array.isArray(abi) && abi.length > 0) {
+                console.log(`  Fetched ABI from Sourcify for ${address}`);
+                return abi;
+            }
+        }
+    }
+    catch {
+        // fall through
+    }
+    return null;
+}
+function addCommand() {
+    const cmd = new commander_1.Command("add");
+    cmd
+        .description("Add components to an existing Logrix indexer project")
+        .argument("<type>", "Type of component to add (e.g. contract)")
+        .argument("[name]", "Name of the component")
+        .option("--address <address>", "Contract address")
+        .option("--abi <path>", "Path to ABI JSON file")
+        .option("--fetch-abi", "Auto-fetch ABI from Etherscan / Sourcify")
+        .option("--etherscan-key <key>", "Etherscan API key for ABI fetch (optional)")
+        .option("--start-block <block>", "Starting block number", "0")
+        .action(async (type, nameArg, opts) => {
+        const projectDir = process.cwd();
+        const configPath = path.join(projectDir, "logrix.yaml");
+        if (!fs.existsSync(configPath)) {
+            console.error("Error: logrix.yaml not found. Please run this command from the project root.");
+            process.exit(1);
+        }
+        if (type !== "contract") {
+            console.error(`Error: Unknown component type '${type}'. Supported types: contract`);
+            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);
+        }
+        if (!config.dataSources) {
+            config.dataSources = [];
+        }
+        // 1. Resolve contract name
+        let contractName = nameArg;
+        if (!contractName) {
+            if (process.stdin.isTTY) {
+                contractName = await (0, prompts_1.input)({
+                    message: "Smart Contract Name:",
+                    default: "SecondaryContract",
+                    validate: (v) => /^[A-Za-z][A-Za-z0-9]*$/.test(v.trim()) ||
+                        "Must be alphanumeric, starting with a letter",
+                });
+            }
+            else {
+                contractName = "SecondaryContract";
+            }
+        }
+        contractName = contractName.trim();
+        // Check for collision
+        const exists = config.dataSources.some((ds) => ds.name === contractName);
+        if (exists) {
+            console.error(`Error: A contract named '${contractName}' is already defined in logrix.yaml.`);
+            process.exit(1);
+        }
+        // 2. Resolve contract address
+        let contractAddress = opts.address;
+        if (!contractAddress) {
+            if (process.stdin.isTTY) {
+                contractAddress = await (0, prompts_1.input)({
+                    message: "Target Contract Address:",
+                    default: "0x0000000000000000000000000000000000000000",
+                    validate: (v) => /^0x[0-9a-fA-F]{40}$/.test(v.trim()) || "Must be a valid 0x hex address",
+                });
+            }
+            else {
+                contractAddress = "0x0000000000000000000000000000000000000000";
+            }
+        }
+        contractAddress = contractAddress.trim();
+        // 3. Resolve start block
+        let startBlockStr = opts.startBlock;
+        if (!opts.address && process.stdin.isTTY) {
+            startBlockStr = await (0, prompts_1.input)({
+                message: "Start Block:",
+                default: "0",
+                validate: (v) => /^\d+$/.test(v.trim()) || "Must be a non-negative integer",
+            });
+        }
+        const startBlock = parseInt(startBlockStr.trim(), 10);
+        // 4. Resolve ABI
+        const abisDir = path.join(projectDir, "abis");
+        fs.mkdirSync(abisDir, { recursive: true });
+        const targetAbiFile = path.join(abisDir, `${contractName}.json`);
+        if (opts.abi) {
+            // Explicit local file
+            const sourceAbi = path.resolve(projectDir, opts.abi);
+            if (!fs.existsSync(sourceAbi)) {
+                console.error(`Error: Specified ABI file not found: ${opts.abi}`);
+                process.exit(1);
+            }
+            fs.copyFileSync(sourceAbi, targetAbiFile);
+            console.log(`  Copied ABI from ${opts.abi} to abis/${contractName}.json`);
+        }
+        else if (opts.fetchAbi) {
+            // Auto-fetch from Etherscan / Sourcify
+            console.log(`  Fetching ABI for ${contractAddress} ...`);
+            const abi = await fetchAbi(contractAddress, opts.etherscanKey);
+            if (abi) {
+                fs.writeFileSync(targetAbiFile, JSON.stringify(abi, null, 2));
+                console.log(`  Saved fetched ABI to abis/${contractName}.json`);
+            }
+            else {
+                console.warn(`  Warning: Could not fetch ABI for ${contractAddress}. Using ERC-20 placeholder.`);
+                fs.writeFileSync(targetAbiFile, JSON.stringify(templates_1.ERC20_ABI, null, 2));
+            }
+        }
+        else if (!fs.existsSync(targetAbiFile)) {
+            // Default placeholder
+            fs.writeFileSync(targetAbiFile, JSON.stringify(templates_1.ERC20_ABI, null, 2));
+            console.log(`  Created default ERC-20 placeholder ABI at abis/${contractName}.json`);
+        }
+        // 5. Append new dataSource to logrix.yaml
+        const networkName = config.network?.name || "mainnet";
+        const newDataSource = {
+            kind: "ethereum/contract",
+            name: contractName,
+            network: networkName,
+            source: {
+                address: contractAddress,
+                abi: contractName,
+                startBlock: startBlock,
+            },
+            mapping: {
+                kind: "wasm/assemblyscript",
+                file: "./build/mapping.wasm",
+                abis: [
+                    {
+                        name: contractName,
+                        file: `./abis/${contractName}.json`,
+                    },
+                ],
+                eventHandlers: [
+                    {
+                        event: "Transfer(address indexed,address indexed,uint256)",
+                        handler: `handle${contractName}Transfer`,
+                    },
+                ],
+            },
+        };
+        config.dataSources.push(newDataSource);
+        fs.writeFileSync(configPath, (0, yaml_1.stringify)(config, { indent: 2 }));
+        console.log(`\nSuccessfully added contract '${contractName}' to logrix.yaml!`);
+        console.log("Next steps:");
+        console.log(`  1. Review / replace ABI at: abis/${contractName}.json`);
+        console.log("  2. Run: logrix codegen");
+        console.log("  3. Run: logrix build\n");
+    });
+    return cmd;
+}

package/dist/commands/build.js

@@ -0,0 +1,106 @@
+"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.buildCommand = buildCommand;
+const commander_1 = require("commander");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+const yaml_1 = require("yaml");
+function buildCommand() {
+    const cmd = new commander_1.Command("build");
+    cmd
+        .description("Compile AssemblyScript handler to WASM using asc")
+        .option("--entry <file>", "Handler entry point", "src/mapping.ts")
+        .option("--out <file>", "Output WASM path", "build/mapping.wasm")
+        .option("--debug", "Build without optimization (for debugging)")
+        .action((opts) => {
+        const projectDir = process.cwd();
+        // Resolve entry and output paths
+        const entryFile = path.resolve(projectDir, opts.entry);
+        const outFile = path.resolve(projectDir, opts.out);
+        if (!fs.existsSync(entryFile)) {
+            console.error(`Error: entry file not found: ${opts.entry}`);
+            process.exit(1);
+        }
+        // Ensure output directory exists
+        fs.mkdirSync(path.dirname(outFile), { recursive: true });
+        // Prefer logrix.yaml mapping.file if present
+        const configPath = path.join(projectDir, "logrix.yaml");
+        let resolvedEntry = entryFile;
+        if (fs.existsSync(configPath)) {
+            try {
+                const config = (0, yaml_1.parse)(fs.readFileSync(configPath, "utf-8"));
+                const mappingFile = config?.dataSources?.[0]?.mapping?.file;
+                if (mappingFile) {
+                    const fromConfig = path.resolve(projectDir, mappingFile);
+                    if (fs.existsSync(fromConfig)) {
+                        resolvedEntry = fromConfig;
+                    }
+                }
+            }
+            catch {
+                // fallback to opts.entry
+            }
+        }
+        // Locate asc: prefer local node_modules, fall back to global
+        let ascBin = path.join(projectDir, "node_modules", ".bin", "asc");
+        if (!fs.existsSync(ascBin)) {
+            ascBin = "asc"; // global
+        }
+        const optimizeFlag = opts.debug ? "" : "--optimize";
+        const cmd = [
+            ascBin,
+            resolvedEntry,
+            "--config", "tsconfig.json",
+            "-o", outFile,
+            optimizeFlag,
+            "--exportRuntime",
+        ]
+            .filter(Boolean)
+            .join(" ");
+        console.log(`Running: ${cmd}\n`);
+        try {
+            (0, child_process_1.execSync)(cmd, { 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.");
+            process.exit(1);
+        }
+    });
+    return cmd;
+}