@crewhaus/tool-onchain 0.7.0

package/README.md

@@ -0,0 +1,111 @@
+# @crewhaus/tool-onchain
+
+The onchain arithmetic, offline.
+
+| Tool | Answers |
+|---|---|
+| `AbiEncodeCall` | what are the exact bytes of this contract call |
+| `AbiDecode` | what does this returned hex actually say |
+| `FunctionSelector` | what is this function's selector, or this event's topic |
+| `AddressCheck` | is this address well-formed, and does its checksum hold |
+| `TypedDataHash` | what digest would a wallet sign for this message |
+| `TokenUnits` | what is this amount in base units, exactly |
+| `DefiMath` | minimum out, maximum in, price impact, share, health factor |
+
+No RPC, no network, no keys. These are the calculations that must be right
+*before* a transaction is composed — and a transaction is irreversible, so
+"plausible" is not good enough.
+
+## Nothing here signs
+
+No private key is accepted, read or handled anywhere in this package, and a
+test asserts that no schema has a field one could be passed to.
+
+`TypedDataHash` computes the digest a wallet *would* sign. That is the useful
+half, because it lets a signature request be checked **before** it is
+approved: hash the message a human was actually shown and compare it against
+what the dapp asked for. A malicious dapp's whole trick is the gap between
+those two.
+
+## Verified against published vectors, not against itself
+
+A codec tested only against its own output agrees with itself and with
+nothing on a chain. So:
+
+- ABI encoding is checked against real ERC-20 `transfer` calldata, byte for
+  byte, and selectors against the ones every block explorer shows.
+- EIP-712 is checked against the specification's own worked example — the
+  type hash, the domain separator, the struct hash and the final digest.
+- EIP-55 is checked against the addresses in that specification.
+- Keccak-256, in `@crewhaus/tool-encode`, is checked against the standard
+  vectors. It is **not** SHA3-256: same permutation, different padding, and
+  substituting one gives a plausible digest that is wrong for every Ethereum
+  purpose. WebCrypto offers neither, which is exactly the trap.
+
+## The mistakes it exists to prevent
+
+- **A misplaced offset.** Dynamic values move to a tail and leave an offset
+  behind, relative to the start of the enclosing tuple — not the call. A
+  wrong offset produces calldata a node accepts and a contract misreads.
+- **Alignment.** Fixed bytes are left-aligned, integers right-aligned.
+  `bytes4` and `uint32` holding "the same" value are different words.
+- **A canonical signature that differs from what was typed.** `uint` is
+  `uint256` in the string the selector is hashed over, so writing `uint` and
+  hashing it literally gives a selector no contract answers to.
+- **Precision.** A `uint256` does not fit in a double; a balance read as a
+  number loses its low digits, and two balances one wei apart become the same
+  value. Integers are `bigint` or decimal strings throughout, and a number
+  past the safe range is refused rather than accepted after it has already
+  lost precision.
+- **`0.1 * 1e18`.** `TokenUnits` is string arithmetic, and it refuses an
+  amount with more decimal places than the token has rather than dropping the
+  extra digits.
+- **The direction of a rounding error in a bound.** A minimum is rounded
+  down and a maximum up; the other way round rejects a swap that was inside
+  tolerance or accepts one that was not. Slippage is basis points, never a
+  percentage, because a percentage invites a decimal and a decimal invites a
+  float.
+
+An address with no checksum is reported as valid **and** as unverifiable,
+rather than letting `valid: true` be read as "no typo". A position with no
+debt has no health factor rather than an infinite one — `Infinity` would read
+as safe to a caller comparing against a threshold.
+
+## Multicall3, as library code
+
+`encodeAggregate3`, `decodeAggregate3` and `decodeRevertData` are exported
+from the package but register no tool: packing a batch is only useful to
+something that can dial a chain, and nothing here dials anything. They pack
+`aggregate3((address,bool,bytes)[])` and read `(bool,bytes)[]` back.
+
+Two properties are the reason they exist:
+
+- **A failed sub-call is data.** With `allowFailure` — which defaults to true
+  — the batch succeeds and the failed entry comes back with `success: false`
+  and its revert bytes. A batch whose own answer cannot be read throws
+  instead, because that is a different event: there are no partial results.
+- **Results are matched by position**, and nothing in the return blob names
+  the call it answers. A blob holding a different number of results than the
+  batch sent is refused rather than zipped against the calls, since a balance
+  read against the wrong token is worse than no balance.
+
+Revert bytes are decoded where they say something: `Error(string)` gives its
+reason, `Panic(uint256)` the documented meaning of its code. An unrecognised
+selector keeps its hex and gets no message — a guess at a custom error is
+worse than the bytes, which are at least searchable.
+
+The canonical Multicall3 address is a **default**, not a constant: the
+deterministic deploy is at the same address on most chains, which is not the
+same as all of them, so every entry point takes it as an argument.
+
+## What it does not do
+
+- **It does not reach a chain.** No RPC calls, no balances, no gas estimates,
+  no broadcasting. Those need a node and belong elsewhere.
+- **It does not sign or hold keys.**
+- **It does not know what a contract does.** `AbiDecode` decodes the types
+  you name; naming the wrong ones produces confident nonsense, which is why
+  data that ends early is an error rather than a short answer.
+- **It does not fetch an ABI.** Signatures come from the caller.
+- **It does not price anything.** `DefiMath` computes against a reference you
+  supply; where that reference came from is your problem.

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+import type { RegisteredTool } from "@crewhaus/tool-catalog";
+/**
+ * Multicall3 packing, as library code for other packages to build on. It
+ * registers no tool of its own: a batch read is only useful to something that
+ * can dial a chain, and nothing in this package dials anything.
+ */
+export { AGGREGATE3_RETURN_TYPE, AGGREGATE3_SELECTOR, AGGREGATE3_SIGNATURE, type Aggregate3Request, type Aggregate3Result, type Call3, ERROR_STRING_SELECTOR, MULTICALL3_ADDRESS, PANIC_REASONS, PANIC_SELECTOR, type RevertKind, type RevertReason, decodeAggregate3, decodeRevertData, encodeAggregate3, } from "./lib/multicall";
+export declare const abiEncodeCall: RegisteredTool;
+export declare const abiDecode: RegisteredTool;
+export declare const functionSelector: RegisteredTool;
+export declare const addressCheck: RegisteredTool;
+export declare const typedDataHash: RegisteredTool;
+export declare const tokenUnits: RegisteredTool;
+export declare const defiMath: RegisteredTool;
+/** Every tool this package registers, in the order a catalog should list them. */
+export declare const ONCHAIN_TOOLS: ReadonlyArray<RegisteredTool>;

package/dist/index.js

@@ -0,0 +1,305 @@
+/**
+ * @crewhaus/tool-onchain — the onchain arithmetic, offline.
+ *
+ * Everything here is pure: no RPC, no network, no keys. These are the
+ * calculations that must be right before a transaction is composed, and that
+ * a model will sometimes get plausibly wrong — calldata with a misplaced
+ * offset, an address with a typo no checksum caught, a `minOut` computed in
+ * floating point, an EIP-712 digest over the wrong type string.
+ *
+ * **Nothing here signs anything.** No private key is accepted, read or
+ * handled. `TypedDataHash` computes the digest a wallet would sign, which is
+ * what lets a signature request be CHECKED before it is approved: hash the
+ * message a human was actually shown and compare it against what the dapp
+ * asked for.
+ *
+ * Integers are `bigint` or decimal strings. A uint256 does not fit in a
+ * double, and reading a balance as a number silently loses its low bits.
+ */
+import { buildTool } from "@crewhaus/tool-builder";
+import { keccak256Hex } from "@crewhaus/tool-encode";
+import { z } from "zod";
+import { decodeData, encodeCall, parseSignature, selectorOf } from "./lib/abi";
+import { formatUnits, parseUnits, validateAddress } from "./lib/address";
+import { healthFactorBps, maximumIn, minimumOut, priceImpactBps, rescaleDecimals, shareBps, } from "./lib/defi";
+import { personalSignHash, typedDataDigest } from "./lib/typed";
+/**
+ * Multicall3 packing, as library code for other packages to build on. It
+ * registers no tool of its own: a batch read is only useful to something that
+ * can dial a chain, and nothing in this package dials anything.
+ */
+export { AGGREGATE3_RETURN_TYPE, AGGREGATE3_SELECTOR, AGGREGATE3_SIGNATURE, ERROR_STRING_SELECTOR, MULTICALL3_ADDRESS, PANIC_REASONS, PANIC_SELECTOR, decodeAggregate3, decodeRevertData, encodeAggregate3, } from "./lib/multicall";
+const json = (value) => JSON.stringify(value);
+const LIMITS = { args: 256, types: 64, hexChars: 2_000_000 };
+/** Accepts a bigint-safe integer: a decimal or hex string, or a safe number. */
+const integerish = z.union([z.string(), z.number().int(), z.bigint()]);
+const bigintFrom = (value, what) => {
+    if (typeof value === "bigint")
+        return value;
+    if (typeof value === "number") {
+        if (!Number.isSafeInteger(value)) {
+            throw new Error(`${what}: ${value} is past the safe integer range, so it has already lost precision — pass it as a string`);
+        }
+        return BigInt(value);
+    }
+    const text = value.trim();
+    if (!/^-?(0x[0-9a-fA-F]+|\d+)$/.test(text))
+        throw new Error(`${what}: "${value}" is not an integer`);
+    return BigInt(text);
+};
+// ---------------------------------------------------------------------------
+export const abiEncodeCall = buildTool({
+    name: "AbiEncodeCall",
+    description: "Build the calldata for a contract call from a function signature and its arguments, returning the 0x hex and the four-byte selector. Use it instead of having a model assemble words by hand: every value is padded into a 32-byte slot, dynamic values move to a tail and leave an offset behind, and a wrong offset produces calldata a node accepts and a contract misreads. Handles uint/int of any width, address, bool, fixed and dynamic bytes, string, arrays and tuples. It composes calldata and never sends it.",
+    inputSchema: z.object({
+        signature: z.string().min(3).describe("e.g. transfer(address,uint256)"),
+        args: z
+            .array(z.unknown())
+            .max(LIMITS.args)
+            .describe("one per parameter; integers as strings or numbers, bytes as 0x hex"),
+    }),
+    readOnly: true,
+    concurrencySafe: true,
+    execute: async (input) => {
+        const { name, types } = parseSignature(input.signature);
+        const canonical = `${name}(${types.map((t) => t.canonical).join(",")})`;
+        const data = encodeCall(input.signature, input.args);
+        return json({
+            data,
+            selector: `0x${selectorOf(canonical)}`,
+            // The canonical form is what the selector is hashed over, and it can
+            // differ from what was written: `uint` is `uint256` here.
+            canonicalSignature: canonical,
+            argumentTypes: types.map((t) => t.canonical),
+            bytes: (data.length - 2) / 2,
+        });
+    },
+});
+export const abiDecode = buildTool({
+    name: "AbiDecode",
+    description: "Decode ABI-encoded hex — an eth_call result, a log's data, a transaction's arguments, revert data — into named, typed values. Use it to read a contract's answer without a model squinting at 32-byte words. Integers come back as decimal STRINGS so a uint256 survives JSON intact; addresses come back lowercase and hex-prefixed. Data that ends early is an error rather than a plausible short answer.",
+    inputSchema: z.object({
+        data: z.string().max(LIMITS.hexChars).describe("0x hex, without a function selector"),
+        types: z.array(z.string()).min(1).max(LIMITS.types).describe('e.g. ["uint256", "address"]'),
+        names: z.array(z.string()).max(LIMITS.types).optional().describe("labels for the values"),
+    }),
+    readOnly: true,
+    concurrencySafe: true,
+    execute: async (input) => {
+        const values = decodeData(input.types, input.data);
+        const names = input.names ?? [];
+        return json({
+            values,
+            named: names.length === 0
+                ? undefined
+                : Object.fromEntries(values.map((v, i) => [names[i] ?? `arg${i}`, v])),
+            types: input.types,
+        });
+    },
+});
+export const functionSelector = buildTool({
+    name: "FunctionSelector",
+    description: "Compute the four-byte selector of a function signature, or the 32-byte topic of an event signature, with Keccak-256. Use it to identify what a transaction calls, to build a log filter, or to check that a selector in a block explorer is what you think. It canonicalises the signature first — `uint` becomes `uint256`, which changes the answer — so it agrees with what a compiler produces rather than with what was typed.",
+    inputSchema: z.object({
+        signature: z
+            .string()
+            .min(3)
+            .describe("e.g. transfer(address,uint256) or Transfer(address,address,uint256)"),
+        kind: z
+            .enum(["function", "event"])
+            .optional()
+            .describe("function (4 bytes, default) or event (32)"),
+    }),
+    readOnly: true,
+    concurrencySafe: true,
+    execute: async (input) => {
+        const { name, types } = parseSignature(input.signature);
+        const canonical = `${name}(${types.map((t) => t.canonical).join(",")})`;
+        const full = keccak256Hex(canonical);
+        return json({
+            canonicalSignature: canonical,
+            selector: `0x${full.slice(0, 8)}`,
+            topic: `0x${full}`,
+            value: input.kind === "event" ? `0x${full}` : `0x${full.slice(0, 8)}`,
+            canonicalised: canonical !== input.signature.trim(),
+        });
+    },
+});
+export const addressCheck = buildTool({
+    name: "AddressCheck",
+    description: "Validate an Ethereum address and return its EIP-55 checksummed form. Use it before composing any transfer: an address is 20 raw bytes with no check digits of its own, and EIP-55 adds a checksum by varying the case of the hex — so a mixed-case address can be verified and a typo caught, while an all-lowercase one cannot be. The result says which of those happened rather than letting a bare 'valid' be read as 'verified', and flags the zero address.",
+    inputSchema: z.object({
+        address: z.string().min(1),
+    }),
+    readOnly: true,
+    concurrencySafe: true,
+    execute: async (input) => json(validateAddress(input.address)),
+});
+export const typedDataHash = buildTool({
+    name: "TypedDataHash",
+    description: "Compute the EIP-712 digest a wallet would sign, together with the domain separator, the struct hash and the encoded type string. Use it to CHECK a signature request before approving it: hash the message a human was actually shown and compare it against what the dapp asked for. It also computes the EIP-191 personal_sign hash. It computes digests and never signs — no private key is accepted anywhere in this package.",
+    inputSchema: z
+        .object({
+        domain: z
+            .object({
+            name: z.string().optional(),
+            version: z.string().optional(),
+            chainId: integerish.optional(),
+            verifyingContract: z.string().optional(),
+            salt: z.string().optional(),
+        })
+            .optional(),
+        types: z
+            .record(z.array(z.object({ name: z.string(), type: z.string() })))
+            .optional()
+            .describe("the EIP-712 type definitions; EIP712Domain is ignored if present"),
+        primaryType: z.string().optional(),
+        message: z.record(z.unknown()).optional(),
+        /** The EIP-191 path, which needs none of the above. */
+        personalSignMessage: z
+            .string()
+            .optional()
+            .describe("hash this as a personal_sign message instead"),
+    })
+        .refine((v) => v.personalSignMessage !== undefined ||
+        (v.domain !== undefined &&
+            v.types !== undefined &&
+            v.primaryType !== undefined &&
+            v.message !== undefined), {
+        message: "give either personalSignMessage, or all of domain, types, primaryType and message",
+    }),
+    readOnly: true,
+    concurrencySafe: true,
+    execute: async (input) => {
+        if (input.personalSignMessage !== undefined) {
+            return json({
+                scheme: "eip191",
+                digest: personalSignHash(input.personalSignMessage),
+                messageBytes: new TextEncoder().encode(input.personalSignMessage).length,
+            });
+        }
+        return json({
+            scheme: "eip712",
+            ...typedDataDigest(input.domain, input.types, input.primaryType, input.message),
+            note: "this is the digest a wallet would sign; nothing here signs it",
+        });
+    },
+});
+export const tokenUnits = buildTool({
+    name: "TokenUnits",
+    description: "Convert between a decimal amount and a token's base units, exactly, in either direction. This is token decimals, not physical units — `UnitConvert` in @crewhaus/tool-math converts metres and kilograms. Use it for every amount that goes into a transaction: `0.1 * 1e18` in floating point is not 10^17, and the difference is real money. It refuses an amount with more decimal places than the token has rather than dropping the extra digits, and it converts between two different decimalisations — six-decimal USDC and eighteen-decimal DAI hold the same amount as integers a trillion apart.",
+    inputSchema: z
+        .object({
+        amount: z.string().min(1).describe("a decimal amount, or base units when toDecimal is set"),
+        decimals: z
+            .number()
+            .int()
+            .min(0)
+            .max(77)
+            .describe("the token's decimals; 18 for ether, 6 for USDC"),
+        toDecimal: z
+            .boolean()
+            .optional()
+            .describe("treat `amount` as base units and render it as a decimal"),
+        toDecimals: z
+            .number()
+            .int()
+            .min(0)
+            .max(77)
+            .optional()
+            .describe("rescale base units to another token's decimals"),
+    })
+        .strict(),
+    readOnly: true,
+    concurrencySafe: true,
+    execute: async (input) => {
+        if (input.toDecimals !== undefined) {
+            const base = bigintFrom(input.amount, "amount");
+            return json({
+                baseUnits: rescaleDecimals(base, input.decimals, input.toDecimals),
+                fromDecimals: input.decimals,
+                toDecimals: input.toDecimals,
+            });
+        }
+        if (input.toDecimal) {
+            const base = bigintFrom(input.amount, "amount");
+            return json({
+                decimal: formatUnits(base, input.decimals),
+                baseUnits: base.toString(),
+                decimals: input.decimals,
+            });
+        }
+        const base = parseUnits(input.amount, input.decimals);
+        return json({ baseUnits: base.toString(), decimal: input.amount, decimals: input.decimals });
+    },
+});
+export const defiMath = buildTool({
+    name: "DefiMath",
+    description: "Do the fixed-point arithmetic a swap or a lending position needs: the minimum output for a slippage tolerance, the maximum input for an exact-output swap, price impact against a reference mid, a pool share, and a health factor. Use it because these are integer calculations in base units where the DIRECTION of a rounding error matters — a minimum is rounded down and a maximum up, since rounding a bound the wrong way rejects a swap that was inside tolerance or accepts one that was not. Slippage is basis points, never a percentage, because a percentage invites a decimal and a decimal invites a float.",
+    inputSchema: z.discriminatedUnion("operation", [
+        z.object({
+            operation: z.literal("minimumOut"),
+            quotedOut: integerish.describe("base units the quote promises"),
+            slippageBps: z.number().int().min(0).max(10_000),
+        }),
+        z.object({
+            operation: z.literal("maximumIn"),
+            quotedIn: integerish,
+            slippageBps: z.number().int().min(0).max(10_000),
+        }),
+        z.object({
+            operation: z.literal("priceImpact"),
+            executionPrice: integerish,
+            referencePrice: integerish,
+        }),
+        z.object({ operation: z.literal("share"), part: integerish, total: integerish }),
+        z.object({
+            operation: z.literal("healthFactor"),
+            collateralBase: integerish,
+            debtBase: integerish,
+            liquidationThresholdBps: z.number().int().min(0).max(10_000),
+        }),
+    ]),
+    readOnly: true,
+    concurrencySafe: true,
+    execute: async (input) => {
+        switch (input.operation) {
+            case "minimumOut":
+                return json(minimumOut(bigintFrom(input.quotedOut, "quotedOut"), input.slippageBps));
+            case "maximumIn":
+                return json({
+                    quotedIn: bigintFrom(input.quotedIn, "quotedIn").toString(),
+                    slippageBps: input.slippageBps,
+                    maxIn: maximumIn(bigintFrom(input.quotedIn, "quotedIn"), input.slippageBps),
+                });
+            case "priceImpact":
+                return json({
+                    impactBps: priceImpactBps(bigintFrom(input.executionPrice, "executionPrice"), bigintFrom(input.referencePrice, "referencePrice")),
+                });
+            case "share":
+                return json({
+                    shareBps: shareBps(bigintFrom(input.part, "part"), bigintFrom(input.total, "total")),
+                });
+            default: {
+                const health = healthFactorBps(bigintFrom(input.collateralBase, "collateralBase"), bigintFrom(input.debtBase, "debtBase"), input.liquidationThresholdBps);
+                return json({
+                    healthFactorBps: health,
+                    liquidatable: health === null ? false : health < 10_000,
+                    // No debt has no health factor. Reporting Infinity would be read as
+                    // safe by a caller comparing against a threshold, and NaN as unsafe.
+                    note: health === null ? "no debt, so there is no health factor" : "",
+                });
+            }
+        }
+    },
+});
+/** Every tool this package registers, in the order a catalog should list them. */
+export const ONCHAIN_TOOLS = Object.freeze([
+    abiDecode,
+    abiEncodeCall,
+    addressCheck,
+    defiMath,
+    functionSelector,
+    typedDataHash,
+    tokenUnits,
+]);

package/dist/lib/abi.d.ts

@@ -0,0 +1,29 @@
+export type AbiValue = string | bigint | boolean | number | AbiValue[];
+/** A parsed ABI type. Tuples carry their components. */
+export type AbiType = {
+    readonly base: string;
+    readonly bits: number;
+    /** -1 for a dynamic array, a length for a fixed one, null when not an array. */
+    readonly arrayLength: number | null;
+    readonly child: AbiType | null;
+    readonly components: ReadonlyArray<AbiType>;
+    readonly dynamic: boolean;
+    /** Canonical form, which is what the selector is computed over. */
+    readonly canonical: string;
+};
+export declare function parseType(raw: string): AbiType;
+/** Head/tail encoding for a list of types, which is what a tuple is. */
+export declare function encodeTuple(types: ReadonlyArray<AbiType>, values: ReadonlyArray<AbiValue>, what?: string): Uint8Array;
+/** The canonical signature a selector is hashed over. */
+export declare function canonicalSignature(name: string, types: ReadonlyArray<AbiType>): string;
+export declare function selectorOf(signature: string): string;
+/** Split `transfer(address,uint256)` into its name and parsed argument types. */
+export declare function parseSignature(signature: string): {
+    name: string;
+    types: AbiType[];
+};
+export declare function encodeCall(signature: string, args: ReadonlyArray<AbiValue>): string;
+/** Decoded values use strings for integers, so a uint256 survives JSON. */
+export type Decoded = string | boolean | Decoded[];
+export declare function decodeTuple(types: ReadonlyArray<AbiType>, data: Uint8Array, base?: number, what?: string): Decoded[];
+export declare function decodeData(typeList: ReadonlyArray<string>, hex: string): Decoded[];