@crewhaus/tool-chainread 0.7.0

package/dist/lib/transfers.js

@@ -0,0 +1,231 @@
+import { ChainReadError, field, hexToBigint, lowerHex, optionalHexToBigint } from "./quantity";
+/** `Transfer(address,address,uint256)` — ERC-20 and ERC-721 share it. */
+export const TRANSFER_TOPIC = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef";
+/** `Approval(address,address,uint256)`. */
+export const APPROVAL_TOPIC = "0x8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b925";
+/** `ApprovalForAll(address,address,bool)` — the blanket ERC-721/1155 approval. */
+export const APPROVAL_FOR_ALL_TOPIC = "0x17307eab39ab6107e8899845ad3d59bd9653f200f220920489ca2b5937696c31";
+/** `TransferSingle(address,address,address,uint256,uint256)` — ERC-1155. */
+export const TRANSFER_SINGLE_TOPIC = "0xc3d58168c5ae7397731d063d5bbf3d657854427343f4c083240f7aacaa2d0f62";
+/** The signatures the constants above are the Keccak of, so the test can recompute them. */
+export const TOPIC_SIGNATURES = Object.freeze({
+    [TRANSFER_TOPIC]: "Transfer(address,address,uint256)",
+    [APPROVAL_TOPIC]: "Approval(address,address,uint256)",
+    [APPROVAL_FOR_ALL_TOPIC]: "ApprovalForAll(address,address,bool)",
+    [TRANSFER_SINGLE_TOPIC]: "TransferSingle(address,address,address,uint256,uint256)",
+});
+/** The low 20 bytes of a 32-byte topic word, which is how an indexed address is stored. */
+export function topicToAddress(topic) {
+    if (!/^0x[0-9a-fA-F]{64}$/.test(topic)) {
+        throw new ChainReadError(`expected a 32-byte topic, got "${topic}"`);
+    }
+    return `0x${topic.slice(26).toLowerCase()}`;
+}
+/**
+ * The inverse: an address as the 32-byte topic word a log filter matches on.
+ *
+ * Left-padded to 32 bytes and lowercased, because `eth_getLogs` compares topics
+ * as fixed-width words and an unpadded or mixed-case one matches nothing — a
+ * filter that silently returns an empty set, which reads exactly like an
+ * address that never moved anything.
+ */
+export function addressToTopic(address) {
+    if (!/^0x[0-9a-fA-F]{40}$/.test(address)) {
+        throw new ChainReadError(`expected a 20-byte address, got "${address}"`);
+    }
+    return `0x${"0".repeat(24)}${address.slice(2).toLowerCase()}`;
+}
+const MAX_UINT256 = (1n << 256n) - 1n;
+/**
+ * An ERC-20 transfer and an ERC-721 transfer are the same event with different
+ * indexing: the token id is indexed, the amount is not. So three topics means
+ * fungible and four means a specific NFT — the only signal there is, and
+ * reading a token id as an amount is how an NFT becomes "1e-18 of a token".
+ */
+export function decodeTransfer(log) {
+    const [topic0, from, to, third] = log.topics;
+    if (topic0 === TRANSFER_TOPIC && from !== undefined && to !== undefined) {
+        if (third !== undefined) {
+            return {
+                standard: "erc721",
+                token: log.address,
+                from: topicToAddress(from),
+                to: topicToAddress(to),
+                amount: "1",
+                tokenId: BigInt(third).toString(),
+                logIndex: log.logIndex,
+            };
+        }
+        return {
+            standard: "erc20",
+            token: log.address,
+            from: topicToAddress(from),
+            to: topicToAddress(to),
+            amount: dataWord(log.data, 0, "Transfer value").toString(),
+            logIndex: log.logIndex,
+        };
+    }
+    const [, operator, sender, recipient] = log.topics;
+    if (topic0 === TRANSFER_SINGLE_TOPIC &&
+        operator !== undefined &&
+        sender !== undefined &&
+        recipient !== undefined) {
+        return {
+            standard: "erc1155",
+            token: log.address,
+            from: topicToAddress(sender),
+            to: topicToAddress(recipient),
+            amount: dataWord(log.data, 1, "TransferSingle value").toString(),
+            tokenId: dataWord(log.data, 0, "TransferSingle id").toString(),
+            logIndex: log.logIndex,
+        };
+    }
+    return null;
+}
+export function decodeApproval(log) {
+    const [topic0, owner, spender, third] = log.topics;
+    if (owner === undefined || spender === undefined)
+        return null;
+    if (topic0 === APPROVAL_TOPIC && third === undefined) {
+        const amount = dataWord(log.data, 0, "Approval value");
+        return {
+            kind: "approval",
+            token: log.address,
+            owner: topicToAddress(owner),
+            spender: topicToAddress(spender),
+            amount: amount.toString(),
+            // The infinite-allowance pattern. Worth flagging on its own: it is the
+            // difference between "approved 100 USDC" and "approved the balance,
+            // forever".
+            unlimited: amount === MAX_UINT256,
+            logIndex: log.logIndex,
+        };
+    }
+    if (topic0 === APPROVAL_FOR_ALL_TOPIC) {
+        return {
+            kind: "approvalForAll",
+            token: log.address,
+            owner: topicToAddress(owner),
+            spender: topicToAddress(spender),
+            approved: dataWord(log.data, 0, "ApprovalForAll approved") !== 0n,
+            logIndex: log.logIndex,
+        };
+    }
+    return null;
+}
+function dataWord(data, index, what) {
+    const body = data.startsWith("0x") ? data.slice(2) : data;
+    const start = index * 64;
+    const word = body.slice(start, start + 64);
+    if (word.length < 64) {
+        throw new ChainReadError(`${what}: the log's data has ${body.length / 2} bytes, too few to hold word ${index} — this is not the event it claims to be`);
+    }
+    return BigInt(`0x${word}`);
+}
+export function projectTransaction(raw) {
+    const input = typeof raw["input"] === "string" ? lowerHex(raw["input"], "tx input") : "0x";
+    const to = typeof raw["to"] === "string" ? lowerHex(raw["to"], "tx to") : null;
+    const blockNumber = optionalHexToBigint(raw["blockNumber"], "tx blockNumber");
+    return {
+        hash: lowerHex(raw["hash"], "tx hash"),
+        from: lowerHex(raw["from"], "tx from"),
+        to,
+        value: hexToBigint(raw["value"], "tx value").toString(),
+        nonce: hexToBigint(raw["nonce"], "tx nonce").toString(),
+        input,
+        // Four bytes is a call; anything shorter is a plain transfer or a
+        // contract creation, and slicing it anyway would invent a selector.
+        selector: input.length >= 10 ? input.slice(0, 10) : null,
+        gas: optionalHexToBigint(raw["gas"], "tx gas")?.toString() ?? null,
+        gasPrice: optionalHexToBigint(raw["gasPrice"], "tx gasPrice")?.toString() ?? null,
+        maxFeePerGas: optionalHexToBigint(raw["maxFeePerGas"], "maxFeePerGas")?.toString() ?? null,
+        maxPriorityFeePerGas: optionalHexToBigint(raw["maxPriorityFeePerGas"], "maxPriorityFeePerGas")?.toString() ?? null,
+        type: typeof raw["type"] === "string" ? raw["type"] : null,
+        blockNumber: blockNumber === null ? null : blockNumber.toString(),
+        blockHash: typeof raw["blockHash"] === "string" ? lowerHex(raw["blockHash"], "blockHash") : null,
+        contractCreation: to === null,
+    };
+}
+export function projectReceipt(raw, projectLog) {
+    const status = raw["status"];
+    const logs = Array.isArray(raw["logs"]) ? raw["logs"].map(projectLog) : [];
+    const decided = status === "0x1" || status === "0x01"
+        ? "success"
+        : status === "0x0" || status === "0x00"
+            ? "reverted"
+            : "unknown";
+    return {
+        status: decided,
+        ...(decided === "unknown"
+            ? {
+                statusReason: raw["root"] === undefined
+                    ? `the receipt carries no status field (got ${JSON.stringify(status)})`
+                    : "this is a pre-Byzantium receipt: it carries a state root instead of a status, so whether the call reverted is not recorded",
+            }
+            : {}),
+        blockNumber: hexToBigint(raw["blockNumber"], "receipt blockNumber").toString(),
+        blockHash: lowerHex(raw["blockHash"], "receipt blockHash"),
+        transactionIndex: raw["transactionIndex"] === undefined
+            ? null
+            : Number(hexToBigint(raw["transactionIndex"], "receipt transactionIndex")),
+        gasUsed: hexToBigint(raw["gasUsed"], "receipt gasUsed").toString(),
+        effectiveGasPrice: optionalHexToBigint(raw["effectiveGasPrice"], "effectiveGasPrice")?.toString() ?? null,
+        contractAddress: typeof raw["contractAddress"] === "string"
+            ? lowerHex(raw["contractAddress"], "contractAddress")
+            : null,
+        logs,
+    };
+}
+/**
+ * `gasUsed * effectiveGasPrice` is the whole fee on L1 and is WRONG on a
+ * rollup, in two different directions.
+ *
+ * OP-stack chains charge a separate L1 data fee that appears as `l1Fee` on the
+ * receipt and is not included in `gasUsed`; leaving it out understates the cost
+ * of a Base or Optimism transaction by most of the cost. Arbitrum folds its L1
+ * component INTO `gasUsed` and reports the share as `gasUsedForL1`, so the
+ * simple product is right there and adding anything would double-count.
+ *
+ * Both are detected from fields the receipt either has or does not, rather than
+ * from a chain id table that goes stale every time a new rollup ships.
+ */
+export function feeBreakdown(receipt, view) {
+    const gasUsed = BigInt(view.gasUsed);
+    const price = view.effectiveGasPrice === null ? null : BigInt(view.effectiveGasPrice);
+    const execution = price === null ? null : gasUsed * price;
+    const l1Fee = optionalHexToBigint(field(receipt, "l1Fee"), "l1Fee");
+    const gasUsedForL1 = optionalHexToBigint(field(receipt, "gasUsedForL1"), "gasUsedForL1");
+    if (l1Fee !== null) {
+        return {
+            model: "op-stack",
+            gasUsed: view.gasUsed,
+            effectiveGasPrice: view.effectiveGasPrice,
+            executionFeeWei: execution?.toString() ?? null,
+            l1FeeWei: l1Fee.toString(),
+            totalFeeWei: execution === null ? null : (execution + l1Fee).toString(),
+            note: "OP-stack: the L1 data fee is charged separately from gas, so the total is execution + l1Fee",
+        };
+    }
+    if (gasUsedForL1 !== null) {
+        return {
+            model: "arbitrum",
+            gasUsed: view.gasUsed,
+            effectiveGasPrice: view.effectiveGasPrice,
+            executionFeeWei: execution?.toString() ?? null,
+            l1FeeWei: null,
+            totalFeeWei: execution?.toString() ?? null,
+            note: `Arbitrum: gasUsed already includes the ${gasUsedForL1} gas charged for L1 data, so the total is the single product`,
+        };
+    }
+    return {
+        model: price === null ? "unknown" : "eip1559",
+        gasUsed: view.gasUsed,
+        effectiveGasPrice: view.effectiveGasPrice,
+        executionFeeWei: execution?.toString() ?? null,
+        l1FeeWei: null,
+        totalFeeWei: execution?.toString() ?? null,
+        note: price === null
+            ? "this receipt carries no effectiveGasPrice, so the fee cannot be computed from it"
+            : "gasUsed * effectiveGasPrice; no rollup fee fields were present on this receipt",
+    };
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@crewhaus/tool-chainread",
+  "version": "0.7.0",
+  "type": "module",
+  "description": "Deterministic EVM chain reads over a public RPC: blocks, transactions, receipts, logs, nonces, and an address's history as reconciler rows",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@crewhaus/chain-adapter-base": "0.7.0",
+    "@crewhaus/errors": "0.7.0",
+    "@crewhaus/tool-builder": "0.7.0",
+    "@crewhaus/tool-catalog": "0.7.0",
+    "@crewhaus/tool-money": "0.7.0",
+    "@crewhaus/tool-onchain": "0.7.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@crewhaus/tool-executor": "workspace:*"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@crewhaus.ai",
+    "url": "https://crewhaus.ai"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/tool-chainread"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/tool-chainread#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": ["dist", "README.md", "LICENSE", "NOTICE"]
+}