@crewhaus/tool-onchain 0.7.0

package/dist/lib/abi.js

@@ -0,0 +1,429 @@
+/**
+ * ABI encoding and decoding.
+ *
+ * Producing calldata by hand is exactly the kind of work that looks easy and
+ * is not: every value is padded into a 32-byte word, dynamic values move to
+ * a tail and leave an offset behind, and a wrong offset produces calldata
+ * that a node accepts and a contract misreads. A model asked to do this will
+ * sometimes produce something plausible, and the transaction is irreversible.
+ *
+ * Integers are handled as `bigint` throughout. A `uint256` does not fit in a
+ * double, and reading one as a number silently loses the low bits of any
+ * balance above about nine quadrillion wei — which is nine thousandths of an
+ * ether.
+ */
+import { keccak256, toHex } from "@crewhaus/tool-encode";
+const WORD = 32;
+const INT_RE = /^(u?int)(\d*)$/;
+const BYTES_RE = /^bytes(\d*)$/;
+/** Split a top-level comma list, respecting nested parentheses and brackets. */
+function splitTop(text) {
+    const parts = [];
+    let depth = 0;
+    let current = "";
+    for (const ch of text) {
+        if (ch === "(" || ch === "[")
+            depth++;
+        else if (ch === ")" || ch === "]")
+            depth--;
+        if (ch === "," && depth === 0) {
+            parts.push(current.trim());
+            current = "";
+            continue;
+        }
+        current += ch;
+    }
+    if (current.trim() !== "")
+        parts.push(current.trim());
+    return parts;
+}
+export function parseType(raw) {
+    const text = raw.trim();
+    if (text === "")
+        throw new Error("an empty string is not an ABI type");
+    // Array suffix, innermost last: `uint256[2][]` is a dynamic array of
+    // fixed-length-2 arrays, so the LAST suffix is the outer type.
+    const arrayMatch = /^(.*)\[(\d*)\]$/.exec(text);
+    if (arrayMatch) {
+        const child = parseType(arrayMatch[1]);
+        const length = arrayMatch[2] === "" ? -1 : Number.parseInt(arrayMatch[2], 10);
+        if (length === 0)
+            throw new Error(`"${text}" has a zero-length array, which cannot hold a value`);
+        return {
+            base: "array",
+            bits: 0,
+            arrayLength: length,
+            child,
+            components: [],
+            dynamic: length === -1 || child.dynamic,
+            canonical: `${child.canonical}[${length === -1 ? "" : length}]`,
+        };
+    }
+    if (text.startsWith("(") && text.endsWith(")")) {
+        const components = splitTop(text.slice(1, -1)).map(parseType);
+        return {
+            base: "tuple",
+            bits: 0,
+            arrayLength: null,
+            child: null,
+            components,
+            dynamic: components.some((c) => c.dynamic),
+            canonical: `(${components.map((c) => c.canonical).join(",")})`,
+        };
+    }
+    if (text === "address") {
+        return {
+            base: "address",
+            bits: 160,
+            arrayLength: null,
+            child: null,
+            components: [],
+            dynamic: false,
+            canonical: "address",
+        };
+    }
+    if (text === "bool") {
+        return {
+            base: "bool",
+            bits: 8,
+            arrayLength: null,
+            child: null,
+            components: [],
+            dynamic: false,
+            canonical: "bool",
+        };
+    }
+    if (text === "string") {
+        return {
+            base: "string",
+            bits: 0,
+            arrayLength: null,
+            child: null,
+            components: [],
+            dynamic: true,
+            canonical: "string",
+        };
+    }
+    const intMatch = INT_RE.exec(text);
+    if (intMatch) {
+        // Bare `uint` and `int` mean 256 bits, and the canonical form — the one
+        // the selector is hashed over — always spells it out.
+        const bits = intMatch[2] === "" ? 256 : Number.parseInt(intMatch[2], 10);
+        if (bits % 8 !== 0 || bits < 8 || bits > 256) {
+            throw new Error(`"${text}" is not a valid integer width; it must be a multiple of 8 from 8 to 256`);
+        }
+        return {
+            base: intMatch[1],
+            bits,
+            arrayLength: null,
+            child: null,
+            components: [],
+            dynamic: false,
+            canonical: `${intMatch[1]}${bits}`,
+        };
+    }
+    const bytesMatch = BYTES_RE.exec(text);
+    if (bytesMatch) {
+        if (bytesMatch[1] === "") {
+            return {
+                base: "bytes",
+                bits: 0,
+                arrayLength: null,
+                child: null,
+                components: [],
+                dynamic: true,
+                canonical: "bytes",
+            };
+        }
+        const size = Number.parseInt(bytesMatch[1], 10);
+        if (size < 1 || size > 32)
+            throw new Error(`"${text}" is not a valid fixed bytes size; it must be 1 to 32`);
+        return {
+            base: "bytesN",
+            bits: size * 8,
+            arrayLength: null,
+            child: null,
+            components: [],
+            dynamic: false,
+            canonical: `bytes${size}`,
+        };
+    }
+    throw new Error(`"${text}" is not an ABI type this understands`);
+}
+function hexToBytes(raw, what) {
+    const text = raw.startsWith("0x") || raw.startsWith("0X") ? raw.slice(2) : raw;
+    if (text.length % 2 !== 0)
+        throw new Error(`${what} has an odd number of hex digits`);
+    if (!/^[0-9a-fA-F]*$/.test(text))
+        throw new Error(`${what} is not hex`);
+    const out = new Uint8Array(text.length / 2);
+    for (let i = 0; i < out.length; i++)
+        out[i] = Number.parseInt(text.slice(i * 2, i * 2 + 2), 16);
+    return out;
+}
+/** Two's complement into a 32-byte word, big-endian. */
+function wordFromBigInt(value, signed, bits, what) {
+    const limit = 1n << BigInt(bits);
+    let v = value;
+    if (signed) {
+        const half = limit >> 1n;
+        if (v >= half || v < -half) {
+            throw new Error(`${what}: ${value} does not fit in an int${bits}`);
+        }
+        if (v < 0n)
+            v += limit;
+    }
+    else {
+        if (v < 0n)
+            throw new Error(`${what}: ${value} is negative, and the type is unsigned`);
+        if (v >= limit)
+            throw new Error(`${what}: ${value} does not fit in a uint${bits}`);
+    }
+    const out = new Uint8Array(WORD);
+    for (let i = WORD - 1; i >= 0 && v > 0n; i--) {
+        out[i] = Number(v & 0xffn);
+        v >>= 8n;
+    }
+    // A negative value sign-extends to the full word.
+    if (signed && value < 0n) {
+        const bytes = bits / 8;
+        for (let i = 0; i < WORD - bytes; i++)
+            out[i] = 0xff;
+    }
+    return out;
+}
+function toBigInt(value, what) {
+    if (typeof value === "bigint")
+        return value;
+    if (typeof value === "number") {
+        if (!Number.isInteger(value))
+            throw new Error(`${what}: ${value} is not an integer`);
+        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 or a bigint`);
+        }
+        return BigInt(value);
+    }
+    if (typeof value === "string") {
+        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);
+    }
+    throw new Error(`${what}: expected an integer`);
+}
+const concat = (parts) => {
+    const total = parts.reduce((s, p) => s + p.length, 0);
+    const out = new Uint8Array(total);
+    let at = 0;
+    for (const part of parts) {
+        out.set(part, at);
+        at += part.length;
+    }
+    return out;
+};
+const padRight = (bytes) => {
+    const padded = new Uint8Array(Math.ceil(bytes.length / WORD) * WORD);
+    padded.set(bytes);
+    return padded;
+};
+/** Encode one value. Returns head and tail; dynamic values put bytes in the tail. */
+function encodeValue(type, value, what) {
+    const none = new Uint8Array(0);
+    if (type.base === "array") {
+        const child = type.child;
+        if (!Array.isArray(value))
+            throw new Error(`${what}: expected an array`);
+        if (type.arrayLength !== -1 && value.length !== type.arrayLength) {
+            throw new Error(`${what}: expected ${type.arrayLength} items, got ${value.length}`);
+        }
+        const body = encodeTuple(value.map(() => child), value, what);
+        if (type.arrayLength === -1) {
+            return {
+                head: none,
+                tail: concat([wordFromBigInt(BigInt(value.length), false, 256, what), body]),
+            };
+        }
+        return type.dynamic ? { head: none, tail: body } : { head: body, tail: none };
+    }
+    if (type.base === "tuple") {
+        if (!Array.isArray(value))
+            throw new Error(`${what}: expected an array of components`);
+        if (value.length !== type.components.length) {
+            throw new Error(`${what}: expected ${type.components.length} components, got ${value.length}`);
+        }
+        const body = encodeTuple(type.components, value, what);
+        return type.dynamic ? { head: none, tail: body } : { head: body, tail: none };
+    }
+    if (type.base === "string" || type.base === "bytes") {
+        const bytes = type.base === "string"
+            ? new TextEncoder().encode(String(value))
+            : hexToBytes(String(value), what);
+        return {
+            head: none,
+            tail: concat([wordFromBigInt(BigInt(bytes.length), false, 256, what), padRight(bytes)]),
+        };
+    }
+    if (type.base === "address") {
+        const bytes = hexToBytes(String(value), what);
+        if (bytes.length !== 20)
+            throw new Error(`${what}: an address is 20 bytes, got ${bytes.length}`);
+        const word = new Uint8Array(WORD);
+        word.set(bytes, 12);
+        return { head: word, tail: none };
+    }
+    if (type.base === "bool") {
+        if (typeof value !== "boolean")
+            throw new Error(`${what}: expected true or false`);
+        return { head: wordFromBigInt(value ? 1n : 0n, false, 8, what), tail: none };
+    }
+    if (type.base === "bytesN") {
+        const bytes = hexToBytes(String(value), what);
+        const size = type.bits / 8;
+        if (bytes.length !== size)
+            throw new Error(`${what}: bytes${size} needs ${size} bytes, got ${bytes.length}`);
+        // Fixed bytes are LEFT-aligned; integers are right-aligned. Getting this
+        // backwards produces a word a contract reads as a completely different
+        // value.
+        const word = new Uint8Array(WORD);
+        word.set(bytes, 0);
+        return { head: word, tail: none };
+    }
+    return {
+        head: wordFromBigInt(toBigInt(value, what), type.base === "int", type.bits, what),
+        tail: none,
+    };
+}
+/** Head/tail encoding for a list of types, which is what a tuple is. */
+export function encodeTuple(types, values, what = "argument") {
+    const parts = types.map((type, i) => encodeValue(type, values[i], `${what}[${i}]`));
+    // Each dynamic value occupies one word in the head, holding the offset of
+    // its bytes from the start of THIS tuple — not from the start of the call.
+    const headSize = types.reduce((sum, type, i) => sum + (type.dynamic ? WORD : parts[i].head.length), 0);
+    const heads = [];
+    const tails = [];
+    let tailOffset = headSize;
+    for (const [i, type] of types.entries()) {
+        const part = parts[i];
+        if (type.dynamic) {
+            heads.push(wordFromBigInt(BigInt(tailOffset), false, 256, what));
+            tails.push(part.tail);
+            tailOffset += part.tail.length;
+        }
+        else {
+            heads.push(part.head);
+        }
+    }
+    return concat([...heads, ...tails]);
+}
+/** The canonical signature a selector is hashed over. */
+export function canonicalSignature(name, types) {
+    return `${name}(${types.map((t) => t.canonical).join(",")})`;
+}
+export function selectorOf(signature) {
+    return toHex(keccak256(new TextEncoder().encode(signature))).slice(0, 8);
+}
+/** Split `transfer(address,uint256)` into its name and parsed argument types. */
+export function parseSignature(signature) {
+    const open = signature.indexOf("(");
+    if (open === -1 || !signature.trim().endsWith(")")) {
+        throw new Error(`"${signature}" is not a function signature — expected name(type,type)`);
+    }
+    const name = signature.slice(0, open).trim();
+    if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name)) {
+        throw new Error(`"${name}" is not a valid function name`);
+    }
+    const inner = signature.slice(open + 1, signature.lastIndexOf(")"));
+    return { name, types: inner.trim() === "" ? [] : splitTop(inner).map(parseType) };
+}
+export function encodeCall(signature, args) {
+    const { name, types } = parseSignature(signature);
+    if (args.length !== types.length) {
+        throw new Error(`${name} takes ${types.length} argument(s), ${args.length} given`);
+    }
+    const canonical = canonicalSignature(name, types);
+    return `0x${selectorOf(canonical)}${toHex(encodeTuple(types, args))}`;
+}
+function wordAt(data, offset, what) {
+    if (offset + WORD > data.length) {
+        throw new Error(`${what}: the data ends before offset ${offset}, so it is truncated or mistyped`);
+    }
+    return data.subarray(offset, offset + WORD);
+}
+function bigIntFromWord(word, signed, bits) {
+    let value = 0n;
+    for (const byte of word)
+        value = (value << 8n) | BigInt(byte);
+    if (!signed)
+        return value;
+    const limit = 1n << BigInt(bits);
+    const half = limit >> 1n;
+    const truncated = value & (limit - 1n);
+    return truncated >= half ? truncated - limit : truncated;
+}
+function decodeValue(type, data, offset, what) {
+    if (type.base === "array") {
+        const child = type.child;
+        if (type.arrayLength === -1) {
+            const length = Number(bigIntFromWord(wordAt(data, offset, what), false, 256));
+            if (length * WORD > data.length) {
+                throw new Error(`${what}: claims ${length} items, more than the data could hold`);
+            }
+            return decodeTuple(new Array(length).fill(child), data, offset + WORD, what);
+        }
+        return decodeTuple(new Array(type.arrayLength).fill(child), data, offset, what);
+    }
+    if (type.base === "tuple")
+        return decodeTuple(type.components, data, offset, what);
+    if (type.base === "string" || type.base === "bytes") {
+        const length = Number(bigIntFromWord(wordAt(data, offset, what), false, 256));
+        const start = offset + WORD;
+        if (start + length > data.length) {
+            throw new Error(`${what}: declares ${length} bytes, past the end of the data`);
+        }
+        const bytes = data.subarray(start, start + length);
+        return type.base === "string" ? new TextDecoder().decode(bytes) : `0x${toHex(bytes)}`;
+    }
+    const word = wordAt(data, offset, what);
+    if (type.base === "address")
+        return `0x${toHex(word.subarray(12))}`;
+    if (type.base === "bool") {
+        const value = bigIntFromWord(word, false, 256);
+        if (value > 1n)
+            throw new Error(`${what}: a bool word holds ${value}, which is neither true nor false`);
+        return value === 1n;
+    }
+    if (type.base === "bytesN")
+        return `0x${toHex(word.subarray(0, type.bits / 8))}`;
+    return bigIntFromWord(word, type.base === "int", type.bits).toString();
+}
+export function decodeTuple(types, data, base = 0, what = "value") {
+    const out = [];
+    let head = base;
+    for (const [i, type] of types.entries()) {
+        const label = `${what}[${i}]`;
+        if (type.dynamic) {
+            const offset = Number(bigIntFromWord(wordAt(data, head, label), false, 256));
+            // An offset is relative to the start of the enclosing tuple. Treating
+            // it as absolute reads the wrong bytes and usually still "works".
+            out.push(decodeValue(type, data, base + offset, label));
+            head += WORD;
+        }
+        else {
+            out.push(decodeValue(type, data, head, label));
+            head += staticSize(type);
+        }
+    }
+    return out;
+}
+/** How many bytes a static type occupies in a head. */
+function staticSize(type) {
+    if (type.base === "tuple")
+        return type.components.reduce((s, c) => s + staticSize(c), 0);
+    if (type.base === "array")
+        return type.arrayLength * staticSize(type.child);
+    return WORD;
+}
+export function decodeData(typeList, hex) {
+    const types = typeList.map(parseType);
+    return decodeTuple(types, hexToBytes(hex, "data"));
+}

package/dist/lib/address.d.ts

@@ -0,0 +1,22 @@
+export type AddressResult = {
+    readonly valid: boolean;
+    /** The EIP-55 mixed-case form, when the input was a well-formed address. */
+    readonly checksummed: string;
+    readonly lowercase: string;
+    /** True when the input carried a checksum that this verified. */
+    readonly hadChecksum: boolean;
+    readonly reason: string;
+    readonly isZero: boolean;
+};
+/** Apply the EIP-55 case checksum to a lowercase address. */
+export declare function toChecksumAddress(lowercase: string): string;
+export declare function validateAddress(raw: string): AddressResult;
+/**
+ * Parse a decimal amount into base units, exactly.
+ *
+ * `parseFloat("0.1") * 1e18` is not 10^17, and the difference is real money.
+ * This is string arithmetic: no value ever becomes a double.
+ */
+export declare function parseUnits(amount: string, decimals: number): bigint;
+/** Render base units as a decimal string, exactly, with no trailing zeros. */
+export declare function formatUnits(value: bigint, decimals: number): string;

package/dist/lib/address.js

@@ -0,0 +1,90 @@
+/**
+ * EIP-55 address checksums and unit conversion.
+ *
+ * An Ethereum address has no check digits of its own — it is 20 raw bytes,
+ * and any 20 bytes are a valid address. EIP-55 adds a checksum by varying
+ * the CASE of the hex, which is why a mixed-case address can be validated
+ * and an all-lowercase one cannot. Sending to a mistyped address is
+ * irreversible, so this is the one check available and it is worth making.
+ */
+import { keccak256Hex } from "@crewhaus/tool-encode";
+/** Apply the EIP-55 case checksum to a lowercase address. */
+export function toChecksumAddress(lowercase) {
+    const body = lowercase.replace(/^0x/i, "").toLowerCase();
+    const hash = keccak256Hex(body);
+    let out = "0x";
+    for (let i = 0; i < body.length; i++) {
+        const char = body[i];
+        // A nibble of 8 or more uppercases the corresponding hex digit; digits
+        // have no case, so they are unaffected.
+        out += Number.parseInt(hash[i], 16) >= 8 ? char.toUpperCase() : char;
+    }
+    return out;
+}
+export function validateAddress(raw) {
+    const text = raw.trim();
+    const body = text.replace(/^0x/i, "");
+    const base = { lowercase: `0x${body.toLowerCase()}`, isZero: /^0*$/.test(body) };
+    if (!/^0x[0-9a-fA-F]{40}$/.test(text)) {
+        return {
+            ...base,
+            valid: false,
+            checksummed: "",
+            hadChecksum: false,
+            reason: /^0x/i.test(text)
+                ? `an address is 0x followed by 40 hex characters; this has ${body.length}`
+                : "an address starts with 0x",
+        };
+    }
+    const checksummed = toChecksumAddress(body);
+    const mixed = body !== body.toLowerCase() && body !== body.toUpperCase();
+    if (mixed && `0x${body}` !== checksummed) {
+        return {
+            ...base,
+            valid: false,
+            checksummed,
+            hadChecksum: true,
+            // This is the case worth catching: the address is well-formed and the
+            // checksum says at least one character is wrong.
+            reason: "the EIP-55 checksum does not match — at least one character is wrong",
+        };
+    }
+    return {
+        ...base,
+        valid: true,
+        checksummed,
+        hadChecksum: mixed,
+        reason: mixed
+            ? ""
+            : "this address carries no EIP-55 checksum, so only its shape was checked; a typo in an all-lowercase address cannot be detected",
+    };
+}
+/**
+ * Parse a decimal amount into base units, exactly.
+ *
+ * `parseFloat("0.1") * 1e18` is not 10^17, and the difference is real money.
+ * This is string arithmetic: no value ever becomes a double.
+ */
+export function parseUnits(amount, decimals) {
+    const text = amount.trim();
+    if (!/^-?\d*\.?\d*$/.test(text) || text === "" || text === "." || text === "-") {
+        throw new Error(`"${amount}" is not a decimal amount`);
+    }
+    const negative = text.startsWith("-");
+    const unsigned = negative ? text.slice(1) : text;
+    const [whole = "", fraction = ""] = unsigned.split(".");
+    if (fraction.length > decimals) {
+        throw new Error(`"${amount}" has ${fraction.length} decimal places but the unit has ${decimals}; the extra digits would be silently dropped`);
+    }
+    const scaled = `${whole === "" ? "0" : whole}${fraction.padEnd(decimals, "0")}`;
+    const value = BigInt(scaled === "" ? "0" : scaled);
+    return negative ? -value : value;
+}
+/** Render base units as a decimal string, exactly, with no trailing zeros. */
+export function formatUnits(value, decimals) {
+    const negative = value < 0n;
+    const digits = (negative ? -value : value).toString().padStart(decimals + 1, "0");
+    const whole = digits.slice(0, digits.length - decimals);
+    const fraction = decimals === 0 ? "" : digits.slice(digits.length - decimals).replace(/0+$/, "");
+    return `${negative ? "-" : ""}${whole}${fraction === "" ? "" : `.${fraction}`}`;
+}

package/dist/lib/defi.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The fixed-point arithmetic that goes wrong in a model's head.
+ *
+ * Every value here is an integer in base units. Slippage is basis points,
+ * not a percentage, because a percentage invites a decimal and a decimal
+ * invites a double. A `minOut` that is off by a rounding error either fails
+ * a swap that should have succeeded or accepts one that should have failed.
+ */
+export type SlippageResult = {
+    readonly quotedOut: string;
+    readonly slippageBps: number;
+    readonly minOut: string;
+    /** What the caller gives up in the worst allowed case. */
+    readonly worstCaseLossBase: string;
+};
+/**
+ * The floor a swap may return before it should revert.
+ *
+ * Rounded DOWN, always. Rounding a minimum up would reject swaps that were
+ * inside the caller's tolerance, and the direction of a rounding error in a
+ * bound is not a detail.
+ */
+export declare function minimumOut(quotedOut: bigint, slippageBps: number): SlippageResult;
+/** The ceiling an input may reach, for an exact-output swap. Rounded UP. */
+export declare function maximumIn(quotedIn: bigint, slippageBps: number): string;
+/**
+ * Convert an amount between two token decimalisations.
+ *
+ * Six-decimal USDC and eighteen-decimal DAI hold "the same" amount as very
+ * different integers, and mixing them up is a factor of a trillion.
+ */
+export declare function rescaleDecimals(amount: bigint, from: number, to: number): string;
+/**
+ * Price impact in basis points, against a reference mid price.
+ *
+ * Both prices are integers with the same scale. Positive means the execution
+ * is worse than the reference.
+ */
+export declare function priceImpactBps(executionPrice: bigint, referencePrice: bigint): number;
+/** Proportional share of a pool, in basis points, for an LP position. */
+export declare function shareBps(part: bigint, total: bigint): number;
+/**
+ * Health factor for a collateralised position, in basis points.
+ *
+ * `collateral * liquidationThresholdBps / debt`. Below 10000 the position is
+ * liquidatable. Debt of zero has no health factor rather than an infinite
+ * one, because a caller comparing against a threshold would read Infinity as
+ * safe and a NaN as unsafe by accident.
+ */
+export declare function healthFactorBps(collateralBase: bigint, debtBase: bigint, liquidationThresholdBps: number): number | null;

package/dist/lib/defi.js

@@ -0,0 +1,94 @@
+/**
+ * The fixed-point arithmetic that goes wrong in a model's head.
+ *
+ * Every value here is an integer in base units. Slippage is basis points,
+ * not a percentage, because a percentage invites a decimal and a decimal
+ * invites a double. A `minOut` that is off by a rounding error either fails
+ * a swap that should have succeeded or accepts one that should have failed.
+ */
+const BPS = 10000n;
+/**
+ * The floor a swap may return before it should revert.
+ *
+ * Rounded DOWN, always. Rounding a minimum up would reject swaps that were
+ * inside the caller's tolerance, and the direction of a rounding error in a
+ * bound is not a detail.
+ */
+export function minimumOut(quotedOut, slippageBps) {
+    if (!Number.isInteger(slippageBps) || slippageBps < 0 || slippageBps > 10_000) {
+        throw new Error(`slippageBps must be an integer from 0 to 10000, got ${slippageBps}`);
+    }
+    if (quotedOut < 0n)
+        throw new Error("quotedOut must not be negative");
+    const minOut = (quotedOut * (BPS - BigInt(slippageBps))) / BPS;
+    return {
+        quotedOut: quotedOut.toString(),
+        slippageBps,
+        minOut: minOut.toString(),
+        worstCaseLossBase: (quotedOut - minOut).toString(),
+    };
+}
+/** The ceiling an input may reach, for an exact-output swap. Rounded UP. */
+export function maximumIn(quotedIn, slippageBps) {
+    if (!Number.isInteger(slippageBps) || slippageBps < 0 || slippageBps > 10_000) {
+        throw new Error(`slippageBps must be an integer from 0 to 10000, got ${slippageBps}`);
+    }
+    const numerator = quotedIn * (BPS + BigInt(slippageBps));
+    // Ceiling division: a maximum rounded down would reject an acceptable swap.
+    return ((numerator + BPS - 1n) / BPS).toString();
+}
+/**
+ * Convert an amount between two token decimalisations.
+ *
+ * Six-decimal USDC and eighteen-decimal DAI hold "the same" amount as very
+ * different integers, and mixing them up is a factor of a trillion.
+ */
+export function rescaleDecimals(amount, from, to) {
+    if (from < 0 || to < 0 || from > 77 || to > 77)
+        throw new Error("decimals must be 0 to 77");
+    if (to >= from)
+        return (amount * 10n ** BigInt(to - from)).toString();
+    const divisor = 10n ** BigInt(from - to);
+    const scaled = amount / divisor;
+    if (amount % divisor !== 0n) {
+        // Say so rather than silently truncating: going from 18 decimals to 6
+        // throws away real value, and the caller has to decide.
+        throw new Error(`${amount} at ${from} decimals does not fit in ${to} decimals without discarding ${amount % divisor}; rescale a rounded amount deliberately`);
+    }
+    return scaled.toString();
+}
+/**
+ * Price impact in basis points, against a reference mid price.
+ *
+ * Both prices are integers with the same scale. Positive means the execution
+ * is worse than the reference.
+ */
+export function priceImpactBps(executionPrice, referencePrice) {
+    if (referencePrice <= 0n)
+        throw new Error("referencePrice must be positive");
+    const delta = referencePrice - executionPrice;
+    return Number((delta * BPS) / referencePrice);
+}
+/** Proportional share of a pool, in basis points, for an LP position. */
+export function shareBps(part, total) {
+    if (total <= 0n)
+        throw new Error("total must be positive");
+    if (part < 0n)
+        throw new Error("part must not be negative");
+    return Number((part * BPS) / total);
+}
+/**
+ * Health factor for a collateralised position, in basis points.
+ *
+ * `collateral * liquidationThresholdBps / debt`. Below 10000 the position is
+ * liquidatable. Debt of zero has no health factor rather than an infinite
+ * one, because a caller comparing against a threshold would read Infinity as
+ * safe and a NaN as unsafe by accident.
+ */
+export function healthFactorBps(collateralBase, debtBase, liquidationThresholdBps) {
+    if (debtBase <= 0n)
+        return null;
+    if (collateralBase < 0n)
+        throw new Error("collateral must not be negative");
+    return Number((collateralBase * BigInt(liquidationThresholdBps)) / debtBase);
+}