envio 3.6.1 → 3.7.0-subgraph

package/src/subgraph/calls.ts

@@ -0,0 +1,217 @@
+/**
+ * `Contract.bind(x).foo()` -> an envio effect over viem.
+ *
+ * graph-node evaluates a mapping's contract calls against the block the event
+ * came from, so the block number is part of the effect's input — and therefore
+ * of its cache key, which is what makes a cached call safe to reuse.
+ */
+
+import {
+  createPublicClient,
+  decodeFunctionResult,
+  encodeFunctionData,
+  fallback,
+  http,
+  parseAbiParameters,
+  type Abi,
+} from "viem";
+import * as Sury from "rescript-schema";
+import { createEffect } from "../Envio.res.mjs";
+import { missingRpcMessage } from "./errors.ts";
+
+export type ParsedSignature = {
+  name: string;
+  inputs: string;
+  outputs: string;
+};
+
+/**
+ * graph codegen emits `"balanceOf(address):(uint256)"`. Types only, no names —
+ * which is all `parseAbiParameters` needs.
+ */
+export function parseSignature(signature: string): ParsedSignature {
+  const open = signature.indexOf("(");
+  if (open === -1) {
+    throw new Error(`Unreadable contract call signature "${signature}"`);
+  }
+  const name = signature.slice(0, open);
+
+  let depth = 0;
+  let close = -1;
+  for (let index = open; index < signature.length; index++) {
+    const char = signature[index];
+    if (char === "(") depth++;
+    if (char === ")") {
+      depth--;
+      if (depth === 0) {
+        close = index;
+        break;
+      }
+    }
+  }
+  if (close === -1) {
+    throw new Error(`Unreadable contract call signature "${signature}"`);
+  }
+
+  const inputs = signature.slice(open + 1, close);
+  const rest = signature.slice(close + 1).replace(/^:/, "");
+  const outputs = rest.startsWith("(") ? rest.slice(1, -1) : rest;
+
+  return { name, inputs, outputs };
+}
+
+export function abiItemFor(signature: string): Abi {
+  const { name, inputs, outputs } = parseSignature(signature);
+  return [
+    {
+      type: "function",
+      name,
+      stateMutability: "view",
+      inputs: inputs.trim() === "" ? [] : [...parseAbiParameters(inputs)],
+      outputs: outputs.trim() === "" ? [] : [...parseAbiParameters(outputs)],
+    },
+  ] as Abi;
+}
+
+/**
+ * A revert is data: the mapping's `try_` sees `{reverted: true}`. A transport
+ * failure is not — it throws as the handler error so envio retries, and a flaky
+ * RPC never fabricates reverted data.
+ */
+export function isRevert(error: unknown): boolean {
+  const parts: string[] = [];
+  let current: any = error;
+  for (let depth = 0; current && depth < 10; depth++) {
+    parts.push(current.name, current.shortMessage, current.details, current.message);
+    current = current.cause;
+  }
+  const text = parts.filter(Boolean).join(" | ");
+
+  if (/revert|ContractFunctionZeroDataError|invalid opcode|out of gas/i.test(text)) {
+    return true;
+  }
+  return false;
+}
+
+export type CallInput = {
+  chainId: number;
+  address: string;
+  signature: string;
+  args: unknown[];
+  blockNumber: number;
+};
+
+export type CallOutput = {
+  reverted: boolean;
+  values: unknown[] | null;
+};
+
+let clients: Map<string, ReturnType<typeof createPublicClient>> = new Map();
+
+function clientFor(rpcUrls: string[]) {
+  const key = rpcUrls.join("|");
+  let client = clients.get(key);
+  if (!client) {
+    client = createPublicClient({
+      // Retrying is envio's job: a failed call becomes a handler error and
+      // the batch is retried with the effect's dedup still in place.
+      transport: fallback(rpcUrls.map((url) => http(url, { retryCount: 0 }))),
+    });
+    clients.set(key, client);
+  }
+  return client;
+}
+
+/** Reset between test indexers, which each bring their own endpoints. */
+export function resetClients() {
+  clients = new Map();
+}
+
+/**
+ * BigInt and Bytes cross the effect boundary through Sury, which needs a
+ * serialisable shape — so the call is described in plain JSON and the graph-ts
+ * values are converted on both sides by the shim.
+ */
+export function makeCallEffect(rpcUrls: string[]) {
+  return createEffect(
+    {
+      name: "envio_subgraph_eth_call",
+      // Both sides travel as JSON text: the cache key is then the exact call
+      // description, and the cached row is readable.
+      input: Sury.string,
+      output: Sury.string,
+      rateLimit: false,
+      cache: true,
+      crossChain: false,
+    },
+    async ({ input: encoded }: { input: string }) => {
+      const input = JSON.parse(encoded) as CallInput;
+      if (rpcUrls.length === 0) {
+        throw new Error(missingRpcMessage(input.signature));
+      }
+      const abi = abiItemFor(input.signature);
+      const { name } = parseSignature(input.signature);
+      const data = encodeFunctionData({
+        abi,
+        functionName: name,
+        args: input.args.map(decodeArg),
+      });
+
+      let result;
+      try {
+        result = await clientFor(rpcUrls).call({
+          to: input.address as `0x${string}`,
+          data,
+          blockNumber: BigInt(input.blockNumber),
+        });
+      } catch (error) {
+        if (isRevert(error)) {
+          return JSON.stringify({ reverted: true, values: null });
+        }
+        throw error;
+      }
+
+      try {
+        const decoded = decodeFunctionResult({
+          abi,
+          functionName: name,
+          data: (result.data ?? "0x") as `0x${string}`,
+        });
+        // graph-ts returns one `ethereum.Value` per ABI output. A single
+        // tuple/struct is therefore `[tuple]`, not the flattened fields —
+        // generated bindings call `result[0].toTuple()`.
+        const outputs = (abi[0] as { outputs?: unknown[] }).outputs ?? [];
+        const values = outputs.length === 1 ? [decoded] : Array.isArray(decoded) ? decoded : [decoded];
+        return JSON.stringify({ reverted: false, values: values.map(encodeArg) });
+      } catch {
+        // Output the declared signature can't decode counts as a failed call,
+        // which is what lets a mapping retry through a different ABI — the
+        // bytes32-vs-string ERC20 name is the case every token subgraph hits.
+        return JSON.stringify({ reverted: true, values: null });
+      }
+    },
+  );
+}
+
+/** Effect inputs/outputs travel as strings, tagged so the type survives. */
+export function encodeArg(value: unknown): string {
+  if (typeof value === "bigint") return `i:${value.toString()}`;
+  if (typeof value === "boolean") return `b:${value ? "1" : "0"}`;
+  if (Array.isArray(value)) return `a:${JSON.stringify(value.map(encodeArg))}`;
+  return `s:${String(value)}`;
+}
+
+export function decodeArg(value: string): unknown {
+  const tag = value.slice(0, 2);
+  const body = value.slice(2);
+  switch (tag) {
+    case "i:":
+      return BigInt(body);
+    case "b:":
+      return body === "1";
+    case "a:":
+      return (JSON.parse(body) as string[]).map(decodeArg);
+    default:
+      return body;
+  }
+}

package/src/subgraph/conformance.ts

@@ -0,0 +1,99 @@
+/**
+ * The shim, checked against the types a subgraph developer codes against.
+ *
+ * A subgraph's mappings are type-checked by `asc` against
+ * `@graphprotocol/graph-ts`, and then run by this shim. Nothing else makes
+ * those two agree, so a gap shows up as green types and a runtime error — the
+ * worst feedback loop there is. This file closes it: every export the shim
+ * claims to provide has to be assignable to the real one.
+ *
+ * The declarations come from the real package (see
+ * `scripts/generate-graph-ts-types.mjs`). This file is type-checked, never run.
+ *
+ * A `@ts-expect-error` below is a known gap, and it cleans itself up: closing
+ * the gap makes the directive unused, which is itself an error, so the comment
+ * has to go with the fix. Adding a new one is a deliberate act.
+ */
+
+import type * as GraphTs from "./graph-ts-types/index.js";
+import * as Shim from "./graph-ts.ts";
+
+// @ts-expect-error graph-ts' BigInt extends Uint8Array and is constructed
+// from a byte length; this one is constructed from the value it holds. No
+// mapping calls `new BigInt(...)` — they go through `BigInt.from*` — and
+// every other member matches. The five below are the same difference,
+// reached through a BigInt in their own signatures.
+const _BigInt: typeof GraphTs.BigInt = Shim.BigInt;
+
+// @ts-expect-error constructor takes a BigInt (see above).
+const _BigDecimal: typeof GraphTs.BigDecimal = Shim.BigDecimal;
+
+const _Bytes: typeof GraphTs.Bytes = Shim.Bytes;
+
+const _ByteArray: typeof GraphTs.ByteArray = Shim.ByteArray;
+
+const _Address: typeof GraphTs.Address = Shim.Address;
+
+const _TypedMap: typeof GraphTs.TypedMap = Shim.TypedMap;
+
+const _TypedMapEntry: typeof GraphTs.TypedMapEntry = Shim.TypedMapEntry;
+
+const _Entity: typeof GraphTs.Entity = Shim.Entity;
+
+const _Value: typeof GraphTs.Value = Shim.Value;
+
+const _ValueKind: typeof GraphTs.ValueKind = Shim.ValueKind;
+
+const _store: typeof GraphTs.store = Shim.store;
+
+// @ts-expect-error `ethereum.Value` carries a BigInt (see above).
+const _ethereum: typeof GraphTs.ethereum = Shim.ethereum;
+
+const _dataSource: typeof GraphTs.dataSource = Shim.dataSource;
+
+const _DataSourceTemplate: typeof GraphTs.DataSourceTemplate = Shim.DataSourceTemplate;
+
+const _DataSourceContext: typeof GraphTs.DataSourceContext = Shim.DataSourceContext;
+
+// @ts-expect-error `log` formats a BigInt (see above).
+const _log: typeof GraphTs.log = Shim.log;
+
+const _crypto: typeof GraphTs.crypto = Shim.crypto;
+
+// @ts-expect-error `json.toBigInt` returns a BigInt (see above).
+const _json: typeof GraphTs.json = Shim.json;
+
+// @ts-expect-error `JSONValue.toBigInt` returns a BigInt (see above).
+const _JSONValue: typeof GraphTs.JSONValue = Shim.JSONValue;
+
+const _JSONValueKind: typeof GraphTs.JSONValueKind = Shim.JSONValueKind;
+
+const _ipfs: typeof GraphTs.ipfs = Shim.ipfs;
+
+const _ens: typeof GraphTs.ens = Shim.ens;
+
+export type {};
+void [
+  _BigInt,
+  _BigDecimal,
+  _Bytes,
+  _ByteArray,
+  _Address,
+  _TypedMap,
+  _TypedMapEntry,
+  _Entity,
+  _Value,
+  _ValueKind,
+  _store,
+  _ethereum,
+  _dataSource,
+  _DataSourceTemplate,
+  _DataSourceContext,
+  _log,
+  _crypto,
+  _json,
+  _JSONValue,
+  _JSONValueKind,
+  _ipfs,
+  _ens,
+];

package/src/subgraph/division.ts

@@ -0,0 +1,110 @@
+/**
+ * AssemblyScript divides two integers as integers. JavaScript doesn't.
+ *
+ * `let dayID = timestamp / 86400` is an i32 division in a mapping and a float
+ * division here, and the difference travels: Uniswap multiplies the bucket back
+ * out and writes it to an `Int` column, where `1588712972.0000002` is a type
+ * error rather than a wrong number — but an entity id built the same way would
+ * simply be wrong. Nothing in the shim can intercept `/` between two plain
+ * numbers, so the operator is rewritten as the mapping is loaded.
+ *
+ * The rewrite is textual, driven by the TypeScript parser every subgraph project
+ * already has: each `a / b` becomes `__envio_idiv(a, b)`, which truncates only
+ * when both operands really are integers and otherwise divides as before — an
+ * `f64` in AssemblyScript divides as a float too.
+ */
+
+import { createRequire } from "node:module";
+import path from "node:path";
+
+type Edit = { at: number; length: number; text: string };
+
+let typescript: any | null | undefined;
+
+/**
+ * The project's own TypeScript, which `graph-cli` puts there. Resolving from the
+ * project rather than from here keeps the shim free of a parser dependency.
+ */
+export function loadTypeScript(root: string): any | null {
+  if (typescript !== undefined) return typescript;
+  try {
+    const require = createRequire(path.join(path.resolve(root), "package.json"));
+    typescript = require("typescript");
+  } catch {
+    typescript = null;
+  }
+  return typescript;
+}
+
+export function integerDivision(a: unknown, b: unknown): unknown {
+  const left = typeof a === "object" && a !== null ? (a as any).valueOf() : a;
+  const right = typeof b === "object" && b !== null ? (b as any).valueOf() : b;
+
+  const integral = (v: unknown) => typeof v === "bigint" || (typeof v === "number" && Number.isInteger(v));
+  if (integral(left) && integral(right)) {
+    // Only i64 / i64 stays 64-bit; anything narrower is an i32 in AssemblyScript
+    // and must come back as a number, or the bigint spreads through every
+    // arithmetic that follows.
+    if (typeof left === "bigint" && typeof right === "bigint") {
+      return left / right;
+    }
+    return Math.trunc(Number(left) / Number(right));
+  }
+  return (left as number) / (right as number);
+}
+
+export const DIVIDE_HELPER = "__envio_idiv";
+export const RETAG_HELPER = "__envio_retag";
+
+/** `changetype<Foo>(x)` → `__envio_retag(Foo, x)` when Foo is a class name. */
+export function rewriteChangetype(source: string): string {
+  if (!source.includes("changetype<")) return source;
+  return source.replace(
+    /changetype\s*<\s*([A-Za-z_][A-Za-z0-9_]*)\s*>\s*\(/g,
+    `${RETAG_HELPER}($1, `,
+  );
+}
+
+/** Returns the source unchanged when it divides nothing, or can't be parsed. */
+export function rewriteDivision(source: string): string {
+  if (!source.includes("/")) return source;
+  const ts = typescript;
+  if (!ts) return source;
+
+  let file: any;
+  try {
+    file = ts.createSourceFile("mapping.ts", source, ts.ScriptTarget.Latest, false, ts.ScriptKind.TS);
+  } catch {
+    return source;
+  }
+
+  const edits: Edit[] = [];
+  const visit = (node: any) => {
+    if (
+      node.kind === ts.SyntaxKind.BinaryExpression &&
+      node.operatorToken?.kind === ts.SyntaxKind.SlashToken
+    ) {
+      const left = ts.skipTrivia(source, node.left.pos);
+      const operator = ts.skipTrivia(source, node.operatorToken.pos);
+      edits.push({ at: left, length: 0, text: `${DIVIDE_HELPER}(` });
+      edits.push({ at: operator, length: node.operatorToken.end - operator, text: "," });
+      edits.push({ at: node.right.end, length: 0, text: ")" });
+    }
+    ts.forEachChild(node, visit);
+  };
+  try {
+    ts.forEachChild(file, visit);
+  } catch {
+    return source;
+  }
+  if (edits.length === 0) return source;
+
+  // Applied back to front so an outer division's insertion points stay valid
+  // while an inner one is rewritten.
+  edits.sort((a, b) => b.at - a.at || b.length - a.length);
+  let out = source;
+  for (const edit of edits) {
+    out = out.slice(0, edit.at) + edit.text + out.slice(edit.at + edit.length);
+  }
+  return out;
+}

package/src/subgraph/errors.ts

@@ -0,0 +1,90 @@
+const ISSUES_URL = "https://github.com/enviodev/hyperindex/issues";
+
+/** A feature we recognise and deliberately don't implement. */
+export function unsupported(feature: string, location: string): Error {
+  return new Error(
+    `Envio Subgraph doesn't support ${feature} yet.\n` +
+      `  Found in ${location}.\n` +
+      `First, make sure you're on the latest envio version — support may have landed:\n` +
+      `  pnpm add -D envio@latest\n` +
+      `If you're up to date and need this feature, please open an issue (existing\n` +
+      `issues welcome a 👍 — demand drives prioritization):\n  ${ISSUES_URL}`,
+  );
+}
+
+/** Something we don't recognise at all: newer than us, or a typo. */
+export function unknown(thing: string, location: string): Error {
+  return new Error(
+    `Envio Subgraph doesn't know ${thing}.\n` +
+      `  Found in ${location}.\n` +
+      `This may be a feature newer than this envio version understands, or a typo.\n` +
+      `First, make sure you're on the latest envio version:\n` +
+      `  pnpm add -D envio@latest\n` +
+      `If you're up to date and this is a real subgraph feature, please open an\n` +
+      `issue so we can add it: ${ISSUES_URL}`,
+  );
+}
+
+const RPC_ENV_VAR = "ENVIO_SUBGRAPH_RPC";
+
+/** §6b: contract calls need an endpoint HyperSync and HyperRPC don't serve. */
+export function missingRpcMessage(callSite: string): string {
+  return (
+    `This subgraph performs contract calls (${callSite}), which need an\n` +
+    `RPC endpoint — HyperSync and HyperRPC serve logs and blocks, not eth_call.\n` +
+    `Set one in .env or the environment:\n` +
+    `  ${RPC_ENV_VAR}=https://...\n` +
+    `Advanced (matches envio's rpc config; single entry or array):\n` +
+    `  ${RPC_ENV_VAR}={"url":"https://...","for":"fallback","headers":{...}}`
+  );
+}
+
+/**
+ * Names a trap must answer for rather than refuse. AS-compiled mappings never
+ * feature-detect, so nothing legitimate reaches these — but `console.log`,
+ * `await` and `JSON.stringify` do, and they must not explode.
+ */
+const PASSTHROUGH = new Set([
+  "then",
+  "toJSON",
+  "constructor",
+  "valueOf",
+  "toString",
+  "inspect",
+  "nodeType",
+  "$$typeof",
+  "@@__IMMUTABLE_ITERABLE__@@",
+]);
+
+function isPassthrough(prop: PropertyKey): boolean {
+  return typeof prop === "symbol" || PASSTHROUGH.has(prop as string);
+}
+
+export const PROTOTYPE_PASSTHROUGH = PASSTHROUGH;
+
+/**
+ * Full Proxy for a graph-ts namespace object. Future graph-ts APIs are
+ * unenumerable, so only a `get` trap can catch them; these are cold paths, so
+ * the trap cost doesn't matter.
+ */
+export function strictNamespace<T extends object>(name: string, target: T): T {
+  return new Proxy(target, {
+    get(target, prop, receiver) {
+      if (prop in target || isPassthrough(prop)) {
+        return Reflect.get(target, prop, receiver);
+      }
+      throw unknown(`the graph-ts API ${name}.${String(prop)}`, `a mapping handler`);
+    },
+  });
+}
+
+/** A known-but-refused field: enumerable, so a plain throwing getter is enough. */
+export function refusedGetter(object: object, prop: string, feature: string, location: string) {
+  Object.defineProperty(object, prop, {
+    enumerable: true,
+    configurable: true,
+    get() {
+      throw unsupported(feature, location);
+    },
+  });
+}

package/src/subgraph/graph-ts-types/VERSION

@@ -0,0 +1,2 @@
+@graphprotocol/graph-ts 0.38.1
+Generated by scripts/generate-graph-ts-types.mjs

package/src/subgraph/graph-ts-types/chain/arweave.d.ts

@@ -0,0 +1,70 @@
+import '../common/eager-offset';
+import { Bytes } from '../common/collections';
+export declare namespace arweave {
+    /**
+     * A key-value pair for arbitrary metadata
+     */
+    class Tag {
+        name: Bytes;
+        value: Bytes;
+        constructor(name: Bytes, value: Bytes);
+    }
+    class ProofOfAccess {
+        option: string;
+        txPath: Bytes;
+        dataPath: Bytes;
+        chunk: Bytes;
+        constructor(option: string, txPath: Bytes, dataPath: Bytes, chunk: Bytes);
+    }
+    /**
+     * An Arweave block.
+     */
+    class Block {
+        timestamp: bigint;
+        lastRetarget: bigint;
+        height: bigint;
+        indepHash: Bytes;
+        nonce: Bytes;
+        previousBlock: Bytes;
+        diff: Bytes;
+        hash: Bytes;
+        txRoot: Bytes;
+        txs: Bytes[];
+        walletList: Bytes;
+        rewardAddr: Bytes;
+        tags: Tag[];
+        rewardPool: Bytes;
+        weaveSize: Bytes;
+        blockSize: Bytes;
+        cumulativeDiff: Bytes;
+        hashListMerkle: Bytes;
+        poa: ProofOfAccess;
+        constructor(timestamp: bigint, lastRetarget: bigint, height: bigint, indepHash: Bytes, nonce: Bytes, previousBlock: Bytes, diff: Bytes, hash: Bytes, txRoot: Bytes, txs: Bytes[], walletList: Bytes, rewardAddr: Bytes, tags: Tag[], rewardPool: Bytes, weaveSize: Bytes, blockSize: Bytes, cumulativeDiff: Bytes, hashListMerkle: Bytes, poa: ProofOfAccess);
+    }
+    /**
+     * An Arweave transaction
+     */
+    class Transaction {
+        format: number;
+        id: Bytes;
+        lastTx: Bytes;
+        owner: Bytes;
+        tags: Tag[];
+        target: Bytes;
+        quantity: Bytes;
+        data: Bytes;
+        dataSize: Bytes;
+        dataRoot: Bytes;
+        signature: Bytes;
+        reward: Bytes;
+        constructor(format: number, id: Bytes, lastTx: Bytes, owner: Bytes, tags: Tag[], target: Bytes, quantity: Bytes, data: Bytes, dataSize: Bytes, dataRoot: Bytes, signature: Bytes, reward: Bytes);
+    }
+    /**
+     * An Arweave transaction with block ptr
+     */
+    class TransactionWithBlockPtr {
+        tx: Transaction;
+        block: Block;
+        constructor(tx: Transaction, block: Block);
+    }
+}