@volga-sh/evm-ghostcall 0.0.3 → 0.0.5

package/README.md

@@ -1,12 +1,11 @@
 # ghostcall
 
-`ghostcall` batches EVM blockchain reads without deployment dependencies.
+`ghostcall` batches EVM contract reads without deploying a Multicall contract.
 
 ## Documentation
 
-The docs live at [ghostcall.volga.sh](https://ghostcall.volga.sh).
-
-Start there for installation, examples, the API reference, protocol details, and endpoint limit notes.
+Start at [ghostcall.volga.sh](https://ghostcall.volga.sh) for the setup guide,
+recipes, API reference, protocol, and size limits.
 
 ## Install
 
@@ -14,16 +13,19 @@ Start there for installation, examples, the API reference, protocol details, and
 npm install @volga-sh/evm-ghostcall
 ```
 
-## Quick Start
+## Quick start
+
+This example uses viem for its client and ABI definition. ghostcall uses ox
+internally to encode arguments and decode results:
 
-This example uses viem for the EIP-1193-compatible client and ABI helpers. Install it with `npm install viem` if your app does not already use it.
+```sh
+npm install viem
+```
 
 ```ts
 import { aggregateDecodedCalls } from "@volga-sh/evm-ghostcall";
 import {
 	createPublicClient,
-	decodeFunctionResult,
-	encodeFunctionData,
 	http,
 	parseAbi,
 } from "viem";
@@ -34,50 +36,81 @@ const client = createPublicClient({
 	transport: http(),
 });
 
-const erc20Abi = parseAbi(["function totalSupply() view returns (uint256)"]);
+const abi = parseAbi(["function totalSupply() view returns (uint256)"]);
+const token = "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2";
 
 const [totalSupply] = await aggregateDecodedCalls(client, [
 	{
-		to: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
-		data: encodeFunctionData({
-			abi: erc20Abi,
-			functionName: "totalSupply",
-		}),
-		decodeResult: (returnData) =>
-			decodeFunctionResult({
-				abi: erc20Abi,
-				functionName: "totalSupply",
-				data: returnData,
-			}),
+		to: token,
+		abi,
+		functionName: "totalSupply",
 	},
 ]);
+// totalSupply is inferred as bigint.
 ```
 
-See the [Getting Started guide](https://ghostcall.volga.sh/getting-started/) for a complete viem example with ABI encoding and decoding.
+Function names, arguments, and results are inferred from the ABI. Functions
+with inputs require `args`, for example `args: [owner]` for `balanceOf`.
+Keep ABIs literal with `as const`, viem's `parseAbi`, or ox's `Abi.from`.
+
+Since 0.0.5, ABI-decoded addresses are checksummed, including addresses nested in
+tuples and arrays. Earlier versions returned lowercase addresses.
+
+For already-encoded calldata, use the raw API:
+
+```ts
+import { aggregateCalls } from "@volga-sh/evm-ghostcall";
+
+const results = await aggregateCalls(client, [
+	{ to: token, data: "0x18160ddd" },
+]);
+// [{ success: true, returnData: "0x..." }]
+```
+
+`aggregateDecodedCalls()` also accepts raw `data` with a custom `decodeResult`
+callback, including in the same batch as ABI calls. Each entry uses either ABI
+fields or raw calldata; TypeScript rejects entries that mix the two forms.
+
+See [Getting Started](https://ghostcall.volga.sh/getting-started/) for a complete
+two-call walkthrough.
 
 ## API
 
-- `aggregateDecodedCalls()` sends a strict batch and returns decoded values.
-- `aggregateCalls()` sends a batch and returns raw `{ success, returnData }` entries.
-- `encodeCalls()` builds the CREATE-style `eth_call` data payload.
-- `decodeResults()` parses the packed ghostcall response.
+- `aggregateDecodedCalls()` accepts ABI calls or custom decoders and returns a typed result tuple.
+- `aggregateCalls()` sends calls and returns raw success or failure results.
+- `encodeCalls()` builds request data for an `eth_call` without `to`.
+- `decodeResults()` parses a raw ghostcall response.
+
+Read the [API reference](https://ghostcall.volga.sh/api/) for signatures,
+options, return types, and errors.
 
-Full reference: [API docs](https://ghostcall.volga.sh/api/).
+The public type surface contains seven types, including ghostcall's own `Hex`.
+`GhostcallAggregateCall` is merged into `GhostcallCall`. See
+[type import migration](https://ghostcall.volga.sh/api/types/#migrating-type-imports)
+for the removed helper aliases. Runtime exports are unchanged.
 
 ## Development
 
+Use Node.js from `.nvmrc`, npm 12.1.0, and Foundry v1.8.3. CI also tests the
+latest Node.js 24 LTS release. Foundry installs the compiler pinned in
+`foundry.toml` (Solidity 0.8.37); the EVM target stays Prague for compatibility.
+
 ```sh
-npm install
+nvm install
+npm install --global npm@12.1.0
+npm ci
 npm run build:sdk
 npm run test
 npm run check
 ```
 
-Docs are built with Astro Starlight:
+To work on the documentation:
 
 ```sh
+npm ci --prefix docs
 npm run docs:dev
 npm run docs:build
 ```
 
-The repository is hosted at [github.com/volga-sh/ghostcall](https://github.com/volga-sh/ghostcall).
+The source is hosted at
+[github.com/volga-sh/ghostcall](https://github.com/volga-sh/ghostcall).

package/dist/sdk/abi.d.ts

@@ -0,0 +1,39 @@
+import type { Abi } from "ox/Abi";
+import * as AbiFunction from "ox/AbiFunction";
+import type * as AbiItem from "ox/AbiItem";
+import type { GhostcallDecodedCall, Hex } from "./index.ts";
+type FunctionCall<TFunction extends AbiFunction.AbiFunction> = TFunction extends AbiFunction.AbiFunction ? {
+    functionName: TFunction["name"];
+} & (TFunction["inputs"] extends readonly [] ? {
+    args?: readonly [];
+} : {
+    args: NonNullable<AbiFunction.encodeData.Args<TFunction>[0]>;
+}) : never;
+/**
+ * An ABI-described call. A literal ABI determines valid function names and args.
+ * Use `as const` or an ABI parser to retain those literal types.
+ */
+type GhostcallAbiCall<TAbi extends Abi = Abi> = {
+    to: Hex;
+    abi: TAbi;
+    data?: never;
+    decodeResult?: never;
+    allowFailure?: never;
+} & (Abi extends TAbi ? {
+    functionName: string;
+    args?: readonly unknown[];
+} : FunctionCall<Extract<TAbi[number], {
+    type: "function";
+}>>);
+type CallFunctionName<TCall extends GhostcallAbiCall> = TCall["functionName"] & AbiFunction.Name<TCall["abi"]>;
+type CallArguments<TCall extends GhostcallAbiCall> = TCall extends {
+    args: infer TArgs extends readonly unknown[];
+} ? TArgs : readonly [];
+type ResolvedFunction<TCall extends GhostcallAbiCall> = AbiItem.fromAbi.Options<TCall["abi"], CallFunctionName<TCall>> extends AbiItem.fromAbi.Options<TCall["abi"], CallFunctionName<TCall>, infer TArgs> ? AbiItem.fromAbi.ReturnType<TCall["abi"], CallFunctionName<TCall>, Extract<CallArguments<TCall>, TArgs>, AbiFunction.AbiFunction> : never;
+/** The decoded result of an ABI call, including argument-selected overloads. */
+type GhostcallAbiResult<TCall extends GhostcallAbiCall> = AbiFunction.decodeResult.ReturnType<Extract<ResolvedFunction<TCall>, AbiFunction.AbiFunction>>;
+/** Bind encoding and decoding to the same resolved ABI function. */
+declare function prepareAbiCall(call: GhostcallAbiCall): GhostcallDecodedCall;
+export type { GhostcallAbiCall, GhostcallAbiResult };
+export { prepareAbiCall };
+//# sourceMappingURL=abi.d.ts.map

package/dist/sdk/abi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abi.d.ts","sourceRoot":"","sources":["../../src/sdk/abi.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,QAAQ,CAAC;AAClC,OAAO,KAAK,WAAW,MAAM,gBAAgB,CAAC;AAC9C,OAAO,KAAK,KAAK,OAAO,MAAM,YAAY,CAAC;AAE3C,OAAO,KAAK,EAAE,oBAAoB,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AAG5D,KAAK,YAAY,CAAC,SAAS,SAAS,WAAW,CAAC,WAAW,IAC1D,SAAS,SAAS,WAAW,CAAC,WAAW,GACtC;IACA,YAAY,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;CAChC,GAAG,CAAC,SAAS,CAAC,QAAQ,CAAC,SAAS,SAAS,EAAE,GACzC;IAAE,IAAI,CAAC,EAAE,SAAS,EAAE,CAAA;CAAE,GACtB;IAAE,IAAI,EAAE,WAAW,CAAC,WAAW,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;CAAE,CAAC,GACnE,KAAK,CAAC;AAEV;;;GAGG;AACH,KAAK,gBAAgB,CAAC,IAAI,SAAS,GAAG,GAAG,GAAG,IAAI;IAC/C,EAAE,EAAE,GAAG,CAAC;IACR,GAAG,EAAE,IAAI,CAAC;IACV,IAAI,CAAC,EAAE,KAAK,CAAC;IACb,YAAY,CAAC,EAAE,KAAK,CAAC;IACrB,YAAY,CAAC,EAAE,KAAK,CAAC;CACrB,GAAG,CAAC,GAAG,SAAS,IAAI,GAClB;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,SAAS,OAAO,EAAE,CAAA;CAAE,GACnD,YAAY,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,CAAC,CAAC,CAAC,CAAC;AAE9D,KAAK,gBAAgB,CAAC,KAAK,SAAS,gBAAgB,IAAI,KAAK,CAAC,cAAc,CAAC,GAC5E,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;AAEhC,KAAK,aAAa,CAAC,KAAK,SAAS,gBAAgB,IAAI,KAAK,SAAS;IAClE,IAAI,EAAE,MAAM,KAAK,SAAS,SAAS,OAAO,EAAE,CAAC;CAC7C,GACE,KAAK,GACL,SAAS,EAAE,CAAC;AAIf,KAAK,gBAAgB,CAAC,KAAK,SAAS,gBAAgB,IACnD,OAAO,CAAC,OAAO,CAAC,OAAO,CACtB,KAAK,CAAC,KAAK,CAAC,EACZ,gBAAgB,CAAC,KAAK,CAAC,CACvB,SAAS,OAAO,CAAC,OAAO,CAAC,OAAO,CAChC,KAAK,CAAC,KAAK,CAAC,EACZ,gBAAgB,CAAC,KAAK,CAAC,EACvB,MAAM,KAAK,CACX,GACE,OAAO,CAAC,OAAO,CAAC,UAAU,CAC1B,KAAK,CAAC,KAAK,CAAC,EACZ,gBAAgB,CAAC,KAAK,CAAC,EACvB,OAAO,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,EACpC,WAAW,CAAC,WAAW,CACvB,GACA,KAAK,CAAC;AAEV,gFAAgF;AAChF,KAAK,kBAAkB,CAAC,KAAK,SAAS,gBAAgB,IACrD,WAAW,CAAC,YAAY,CAAC,UAAU,CAClC,OAAO,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC,WAAW,CAAC,CACzD,CAAC;AAEH,oEAAoE;AACpE,iBAAS,cAAc,CAAC,IAAI,EAAE,gBAAgB,GAAG,oBAAoB,CAoBpE;AAED,YAAY,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,CAAC"}

package/dist/sdk/abi.js

@@ -0,0 +1,20 @@
+import * as AbiFunction from "ox/AbiFunction";
+/** Bind encoding and decoding to the same resolved ABI function. */
+function prepareAbiCall(call) {
+    const args = call.args ?? [];
+    const abiFunction = AbiFunction.fromAbi(call.abi, call.functionName, {
+        args,
+    });
+    // ox permits selector-only encoding with no args. At this wire boundary,
+    // missing arguments must fail before RPC, including for dynamically loaded ABIs.
+    if (args.length !== abiFunction.inputs.length) {
+        throw new TypeError(`${call.functionName} expects ${abiFunction.inputs.length} arguments, received ${args.length}`);
+    }
+    return {
+        to: call.to,
+        data: AbiFunction.encodeData(abiFunction, args),
+        decodeResult: (returnData) => AbiFunction.decodeResult(abiFunction, returnData),
+    };
+}
+export { prepareAbiCall };
+//# sourceMappingURL=abi.js.map

package/dist/sdk/abi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abi.js","sourceRoot":"","sources":["../../src/sdk/abi.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,WAAW,MAAM,gBAAgB,CAAC;AA+D9C,oEAAoE;AACpE,SAAS,cAAc,CAAC,IAAsB;IAC7C,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC;IAC7B,MAAM,WAAW,GAAG,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,EAAE;QACpE,IAAI;KACJ,CAAC,CAAC;IAEH,yEAAyE;IACzE,iFAAiF;IACjF,IAAI,IAAI,CAAC,MAAM,KAAK,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;QAC/C,MAAM,IAAI,SAAS,CAClB,GAAG,IAAI,CAAC,YAAY,YAAY,WAAW,CAAC,MAAM,CAAC,MAAM,wBAAwB,IAAI,CAAC,MAAM,EAAE,CAC9F,CAAC;IACH,CAAC;IAED,OAAO;QACN,EAAE,EAAE,IAAI,CAAC,EAAE;QACX,IAAI,EAAE,WAAW,CAAC,UAAU,CAAC,WAAW,EAAE,IAAI,CAAC;QAC/C,YAAY,EAAE,CAAC,UAAU,EAAE,EAAE,CAC5B,WAAW,CAAC,YAAY,CAAC,WAAW,EAAE,UAAU,CAAC;KAClD,CAAC;AACH,CAAC;AAGD,OAAO,EAAE,cAAc,EAAE,CAAC"}

package/dist/sdk/index.d.ts

@@ -1,322 +1,89 @@
-/**
- * Hex-encoded binary data prefixed with `0x`.
- *
- * Ghostcall request and response data is represented as raw hex strings. The
- * SDK does not accept byte arrays or ABI fragments.
- */
+import { type GhostcallAbiCall, type GhostcallAbiResult } from "./abi.ts";
+/** A 0x-prefixed string, validated at SDK wire boundaries. */
 type Hex = `0x${string}`;
-/**
- * Hex-encoded RPC quantity prefixed with `0x`.
- */
-type HexQuantity = `0x${string}`;
-/**
- * Block reference accepted by the outer `eth_call`.
- */
-type GhostcallBlockReference = string | number | bigint;
-/**
- * One Ghostcall subcall entry.
- */
+/** Raw calldata for one target. Encoding ignores the SDK-only failure policy. */
 type GhostcallCall = {
-    /**
-     * Target contract address to invoke.
-     */
     to: Hex;
-    /**
-     * Hex-encoded call data to forward to {@link GhostcallCall.to}.
-     *
-     * The encoded payload is limited to `65535` bytes because Ghostcall stores each
-     * calldata length as a big-endian `uint16`.
-     */
+    /** At most 65,535 bytes (the wire format stores a uint16 length). */
     data: Hex;
-};
-/**
- * One Ghostcall aggregate subcall entry.
- *
- * The wire format does not include failure-policy bits. `allowFailure` is an SDK
- * policy applied after Ghostcall returns the packed result entries.
- */
-type GhostcallAggregateCall = GhostcallCall & {
-    /**
-     * Allows this subcall to return a failed result entry.
-     *
-     * Defaults to `false`, matching Multicall3's strict `aggregate3` behavior when
-     * a call does not explicitly opt into failure.
-     */
+    /** Return failed entries from aggregateCalls instead of throwing. Default: false. */
     allowFailure?: boolean;
 };
-/**
- * One Ghostcall subcall entry for decoded aggregate results.
- */
+/** Raw calldata with a decoder that only receives successful results. */
 type GhostcallDecodedCall<TResult = unknown> = GhostcallCall & {
-    /**
-     * Decodes this call's successful return data.
-     *
-     * This is intentionally a caller-provided function so the SDK stays independent
-     * from ABI libraries while still letting callers plug in helpers such as
-     * `decodeFunctionResult` from viem or ox.
-     */
-    decodeResult: GhostcallResultDecoder<TResult>;
+    abi?: never;
+    functionName?: never;
+    args?: never;
+    allowFailure?: never;
+    decodeResult: (returnData: Hex, entry: Extract<GhostcallResult, {
+        success: true;
+    }>, index: number) => TResult;
 };
-/**
- * One successful Ghostcall result entry.
- */
-type GhostcallSuccessResult = {
-    /**
-     * Indicates whether the underlying EVM `CALL` returned successfully.
-     *
-     * A `true` value means the target call returned successfully.
-     */
+/** Raw results retain input order and include revert data for failed calls. */
+type GhostcallResult = {
     success: true;
-    /**
-     * Raw return data produced by the target call.
-     */
     returnData: Hex;
-};
-/**
- * One failed Ghostcall result entry.
- */
-type GhostcallFailedResult = {
-    /**
-     * Indicates whether the underlying EVM `CALL` returned successfully.
-     *
-     * A `false` value means the target call reverted or otherwise failed, but the
-     * Ghostcall batch itself still completed successfully.
-     */
+} | {
     success: false;
-    /**
-     * Raw return data produced by the target call.
-     *
-     * For failed calls this contains revert data, if any. The SDK leaves higher-level
-     * ABI decoding and failure policy to the caller.
-     */
     returnData: Hex;
 };
-/**
- * One decoded Ghostcall result entry.
- */
-type GhostcallResult = GhostcallSuccessResult | GhostcallFailedResult;
-/**
- * Function used by {@link aggregateCalls} to turn raw successful return data into
- * a caller-chosen value.
- */
-type GhostcallResultDecoder<TResult> = (returnData: Hex, entry: GhostcallSuccessResult, index: number) => TResult;
-/**
- * Error thrown when a strict Ghostcall batch encounters a failed subcall.
- */
-declare class GhostcallSubcallError extends Error {
-    readonly index: number;
-    readonly call: GhostcallAggregateCall;
-    readonly result: GhostcallFailedResult;
-    constructor(index: number, call: GhostcallAggregateCall, result: GhostcallFailedResult);
-}
-type GhostcallDecodedResults<TCalls extends readonly GhostcallDecodedCall[]> = {
-    -readonly [Index in keyof TCalls]: TCalls[Index] extends {
-        decodeResult: GhostcallResultDecoder<infer TResult>;
-    } ? TResult : never;
+type GhostcallFailedResult = Extract<GhostcallResult, {
+    success: false;
+}>;
+type GhostcallDecodedInput = GhostcallAbiCall | GhostcallDecodedCall;
+type ValidatedDecodedCall<TCall extends GhostcallDecodedInput> = TCall extends GhostcallAbiCall ? GhostcallAbiCall<TCall["abi"]> : TCall;
+type ValidatedDecodedCalls<TCalls extends readonly GhostcallDecodedInput[]> = {
+    [Index in keyof TCalls]: ValidatedDecodedCall<TCalls[Index]>;
+};
+type DecodedResult<TCall extends GhostcallDecodedInput> = TCall extends GhostcallAbiCall ? GhostcallAbiResult<TCall> : TCall extends GhostcallDecodedCall ? ReturnType<TCall["decodeResult"]> : never;
+type GhostcallDecodedResults<TCalls extends readonly GhostcallDecodedInput[]> = {
+    -readonly [Index in keyof TCalls]: DecodedResult<TCalls[Index]>;
 };
 type GhostcallEncodeOptions = {
-    /**
-     * Maximum allowed CREATE initcode size in bytes.
-     *
-     * This applies to the full request `data`, including bundled Ghostcall
-     * initcode and every encoded subcall entry.
-     *
-     * Defaults to Ethereum's EIP-3860 limit of `49,152` bytes.
-     */
+    /** Full CREATE request ceiling, including bundled initcode. Default: 49,152 bytes. */
     maxInitcodeBytes?: number;
 };
-type GhostcallEthCallOptions = {
-    /**
-     * Optional `from` address for the outer `eth_call`.
-     */
-    from?: Hex;
-    /**
-     * Optional gas limit for the outer `eth_call`.
-     */
-    gas?: HexQuantity;
-    /**
-     * Optional block tag, hex quantity, or block number for the outer `eth_call`.
-     *
-     * Decimal strings, numbers, and bigints are normalized to hex quantities.
-     * Defaults to `latest`.
-     */
-    blockTag?: GhostcallBlockReference;
-};
 type GhostcallAggregateOptions = GhostcallEncodeOptions & {
-    /**
-     * Optional outer `eth_call` controls shared by {@link aggregateCalls} and
-     * {@link aggregateDecodedCalls}.
-     */
-    ethCall?: GhostcallEthCallOptions;
+    /** Controls the outer eth_call, shared by the entire batch. */
+    ethCall?: {
+        from?: Hex;
+        /** Canonical RPC hex quantity. */
+        gas?: Hex;
+        /** Decimal block numbers are normalized to hex. Default: "latest". */
+        blockTag?: string | number | bigint;
+    };
 };
-/**
- * Minimal EIP-1193 provider shape used by the SDK.
- */
-type EIP1193ProviderWithRequestFn = {
+type Provider = {
     request(args: {
         method: string;
         params?: unknown;
     }): Promise<unknown>;
 };
+/** A disallowed failure, with its zero-based index, executed call, and revert data. */
+declare class GhostcallSubcallError extends Error {
+    readonly index: number;
+    readonly call: GhostcallCall;
+    readonly result: GhostcallFailedResult;
+    constructor(index: number, call: GhostcallCall, result: GhostcallFailedResult);
+}
 /**
- * Encodes a list of contract calls into the full CREATE-style `eth_call` payload
- * expected by Ghostcall.
- *
- * The returned hex string already includes the bundled Ghostcall initcode followed
- * by the compact binary payload for each subcall, so callers can pass it directly
- * as the `data` field of an `eth_call` request without supplying a `to` address.
- * Each encoded subcall entry uses the compact layout `[len(2)][target(20)][data]`.
- * The bundled initcode assumes appended bytes follow this exact shape; this
- * function is the supported boundary for producing well-formed Ghostcall payloads.
- *
- * @param calls - Ordered list of subcalls to execute. Each entry becomes one
- *                Ghostcall payload segment in the same order it appears here.
- * @param options - Optional encoding controls.
- *
- * @returns Full CREATE payload consisting of the bundled Ghostcall initcode plus
- *          the encoded call list.
- *
- * @throws {TypeError} If any call address or calldata value is not valid hex.
- * @throws {RangeError} If any call data exceeds the protocol `uint16` length limit
- *                      or if the full encoded CREATE payload would exceed the
- *                      configured initcode size limit.
- *
- * @example
- * const data = encodeCalls([
- *   {
- *     // USDC on Ethereum mainnet: balanceOf(Binance 14)
- *     to: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
- *     data: "0x70a0823100000000000000000000000028c6c06298d514db089934071355e5743bf21d60",
- *   },
- *   {
- *     // WETH9 on Ethereum mainnet: totalSupply()
- *     to: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
- *     data: "0x18160ddd",
- *   },
- * ]);
- *
- * // Later:
- * // provider.request({ method: "eth_call", params: [{ data }, "latest"] })
- */
-declare function encodeCalls(calls: readonly GhostcallCall[], options?: GhostcallEncodeOptions): Hex;
-/**
- * Sends a Ghostcall batch with a CREATE-style `eth_call` and decodes the result.
- *
- * This is the provider-facing counterpart to {@link encodeCalls} and
- * {@link decodeResults}. It sends the bundled Ghostcall initcode as the `data`
- * field of `eth_call` without a `to` address, then returns raw result entries
- * in the same order as the input calls. Request bytes are built through
- * {@link encodeCalls}, so SDK callers get the supported payload validation before
- * the RPC request is sent.
- *
- * By default, any failed subcall makes this method reject. Set
- * `allowFailure: true` on a call to receive that failed entry in the returned
- * results instead. Use {@link aggregateDecodedCalls} when you want a strict batch
- * that returns decoded values directly. Use `options.ethCall` to forward `from`,
- * `gas`, or `blockTag` to the outer `eth_call`.
- *
- * @param provider - EIP-1193-compatible provider with a `request` method.
- * @param calls - Ordered list of subcalls to execute.
- * @param options - Optional outer call and initcode controls.
- *
- * @returns Ordered Ghostcall result entries.
- *
- * @throws {TypeError} If inputs are not valid Ghostcall call entries or if the
- *                     provider returns a non-hex `eth_call` result.
- * @throws {RangeError} If the encoded CREATE payload exceeds protocol or the
- *                      configured CREATE initcode ceiling.
- * @throws {GhostcallSubcallError} If a subcall fails without `allowFailure: true`.
- * @throws {Error} If the response entry count does not match the request entry count.
- *
- * @example
- * const results = await aggregateCalls(provider, [
- *   {
- *     // USDC on Ethereum mainnet: balanceOf(Binance 14)
- *     to: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
- *     data: "0x70a0823100000000000000000000000028c6c06298d514db089934071355e5743bf21d60",
- *   },
- *   {
- *     // WETH9 on Ethereum mainnet: totalSupply()
- *     to: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
- *     data: "0x18160ddd",
- *   },
- * ]);
+ * Build CREATE-style eth_call data: initcode followed by [length (2)][target (20)][data].
+ * Send without a `to` address. Invalid inputs throw TypeError; size limits throw RangeError.
  */
-declare function aggregateCalls(provider: EIP1193ProviderWithRequestFn, calls: readonly GhostcallAggregateCall[], options?: GhostcallAggregateOptions): Promise<GhostcallResult[]>;
+declare function encodeCalls(calls: readonly GhostcallCall[], { maxInitcodeBytes, }?: GhostcallEncodeOptions): Hex;
 /**
- * Sends a strict Ghostcall batch and decodes each successful result entry.
- *
- * This is the decoded counterpart to {@link aggregateCalls}. It sends the bundled
- * Ghostcall initcode as the `data` field of `eth_call` without a `to` address,
- * then runs each call's `decodeResult` callback over the successful return data in
- * the same order as the input calls.
- *
- * `aggregateDecodedCalls` is always strict. Its TypeScript input shape requires a
- * `decodeResult` callback on every call and does not accept `allowFailure`.
- * Any failed subcall rejects with {@link GhostcallSubcallError}. Use
- * {@link aggregateCalls} if you need raw failed entries. Use `options.ethCall`
- * to forward `from`, `gas`, or `blockTag` to the outer `eth_call`.
- *
- * @param provider - EIP-1193-compatible provider with a `request` method.
- * @param calls - Ordered list of strict decoded subcalls to execute.
- * @param options - Optional outer call and initcode controls.
- *
- * @returns Ordered list of decoded values.
- *
- * @throws {TypeError} If inputs are not valid Ghostcall call entries or if the
- *                     provider returns a non-hex `eth_call` result.
- * @throws {RangeError} If the encoded CREATE payload exceeds protocol or the
- *                      configured CREATE initcode ceiling.
- * @throws {GhostcallSubcallError} If any subcall fails.
- * @throws {Error} If the response entry count does not match the request entry count.
- *
- * @example
- * const erc20Abi = parseAbi([
- *   "function balanceOf(address account) view returns (uint256)",
- * ]);
- * const usdc = "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48";
- * const owner = "0x28C6c06298d514Db089934071355E5743bf21d60";
- *
- * const [balance] = await aggregateDecodedCalls(provider, [
- *   {
- *     to: usdc,
- *     data: "0x70a0823100000000000000000000000028c6c06298d514db089934071355e5743bf21d60",
- *     decodeResult: (returnData) => decodeFunctionResult({
- *       abi: erc20Abi,
- *       functionName: "balanceOf",
- *       data: returnData,
- *     }),
- *   },
- * ]);
+ * Execute a raw batch in order. Failed calls throw GhostcallSubcallError unless
+ * their entry sets allowFailure. Provider errors pass through unchanged.
  */
-declare function aggregateDecodedCalls<const TCalls extends readonly GhostcallDecodedCall<unknown>[]>(provider: EIP1193ProviderWithRequestFn, calls: TCalls, options?: GhostcallAggregateOptions): Promise<GhostcallDecodedResults<TCalls>>;
+declare function aggregateCalls(provider: Provider, calls: readonly GhostcallCall[], options?: GhostcallAggregateOptions): Promise<GhostcallResult[]>;
 /**
- * Decodes the packed result blob returned by Ghostcall.
- *
- * Each decoded entry corresponds to exactly one subcall in the original batch and
- * preserves the original ordering. The SDK intentionally returns raw result bytes
- * rather than ABI-decoding them so higher-level callers can apply their own
- * decoding and failure policy.
- *
- * @param data - Raw bytes returned by Ghostcall, typically the direct result of a
- *               CREATE-style `eth_call`.
- *
- * @returns Ordered list of decoded Ghostcall result entries. Returns an empty
- *          array for `0x`.
- *
- * @throws {TypeError} If the provided data is not valid hex, if a result header is
- *                     truncated, or if an entry body is shorter than advertised.
- *
- * @example
- * const results = decodeResults("0x8002cafe0004deadbeef");
- *
- * console.log(results);
- * // [
- * //   { success: true, returnData: "0xcafe" },
- * //   { success: false, returnData: "0xdeadbeef" }
- * // ]
+ * Execute ABI-described calls or raw calls with custom decoders. Each tuple position
+ * retains its result type. Any failed call throws; encoding/decoding errors pass through.
+ * ABI-decoded addresses are checksummed, including addresses nested in tuples or arrays.
  */
+declare function aggregateDecodedCalls<const TCalls extends readonly GhostcallDecodedInput[]>(provider: Provider, calls: TCalls & NoInfer<ValidatedDecodedCalls<TCalls>>, options?: GhostcallAggregateOptions): Promise<GhostcallDecodedResults<TCalls>>;
+/** Decode ordered [success bit | uint15 length][returndata] entries. Reject malformed data. */
 declare function decodeResults(data: Hex): GhostcallResult[];
-export type { EIP1193ProviderWithRequestFn, GhostcallAggregateCall, GhostcallAggregateOptions, GhostcallBlockReference, GhostcallCall, GhostcallDecodedCall, GhostcallDecodedResults, GhostcallEncodeOptions, GhostcallEthCallOptions, GhostcallFailedResult, GhostcallResult, GhostcallResultDecoder, GhostcallSuccessResult, Hex, HexQuantity, };
+export type { GhostcallAbiCall, GhostcallAggregateOptions, GhostcallCall, GhostcallDecodedCall, GhostcallEncodeOptions, GhostcallResult, Hex, };
 export { aggregateCalls, aggregateDecodedCalls, decodeResults, encodeCalls, GhostcallSubcallError, };
 //# sourceMappingURL=index.d.ts.map

package/dist/sdk/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sdk/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sdk/index.ts"],"names":[],"mappings":"AAGA,OAAO,EACN,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EAEvB,MAAM,UAAU,CAAC;AAGlB,8DAA8D;AAC9D,KAAK,GAAG,GAAG,KAAK,MAAM,EAAE,CAAC;AAEzB,iFAAiF;AACjF,KAAK,aAAa,GAAG;IACpB,EAAE,EAAE,GAAG,CAAC;IACR,qEAAqE;IACrE,IAAI,EAAE,GAAG,CAAC;IACV,qFAAqF;IACrF,YAAY,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF,yEAAyE;AACzE,KAAK,oBAAoB,CAAC,OAAO,GAAG,OAAO,IAAI,aAAa,GAAG;IAC9D,GAAG,CAAC,EAAE,KAAK,CAAC;IACZ,YAAY,CAAC,EAAE,KAAK,CAAC;IACrB,IAAI,CAAC,EAAE,KAAK,CAAC;IACb,YAAY,CAAC,EAAE,KAAK,CAAC;IACrB,YAAY,EAAE,CACb,UAAU,EAAE,GAAG,EACf,KAAK,EAAE,OAAO,CAAC,eAAe,EAAE;QAAE,OAAO,EAAE,IAAI,CAAA;KAAE,CAAC,EAClD,KAAK,EAAE,MAAM,KACT,OAAO,CAAC;CACb,CAAC;AAEF,+EAA+E;AAC/E,KAAK,eAAe,GACjB;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,UAAU,EAAE,GAAG,CAAA;CAAE,GAClC;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,UAAU,EAAE,GAAG,CAAA;CAAE,CAAC;AAEvC,KAAK,qBAAqB,GAAG,OAAO,CAAC,eAAe,EAAE;IAAE,OAAO,EAAE,KAAK,CAAA;CAAE,CAAC,CAAC;AAC1E,KAAK,qBAAqB,GAAG,gBAAgB,GAAG,oBAAoB,CAAC;AAGrE,KAAK,oBAAoB,CAAC,KAAK,SAAS,qBAAqB,IAC5D,KAAK,SAAS,gBAAgB,GAAG,gBAAgB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,GAAG,KAAK,CAAC;AAEzE,KAAK,qBAAqB,CAAC,MAAM,SAAS,SAAS,qBAAqB,EAAE,IAAI;KAC5E,KAAK,IAAI,MAAM,MAAM,GAAG,oBAAoB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;CAC5D,CAAC;AAEF,KAAK,aAAa,CAAC,KAAK,SAAS,qBAAqB,IACrD,KAAK,SAAS,gBAAgB,GAC3B,kBAAkB,CAAC,KAAK,CAAC,GACzB,KAAK,SAAS,oBAAoB,GACjC,UAAU,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,GACjC,KAAK,CAAC;AAEX,KAAK,uBAAuB,CAAC,MAAM,SAAS,SAAS,qBAAqB,EAAE,IAC3E;IACC,CAAC,UAAU,KAAK,IAAI,MAAM,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;CAC/D,CAAC;AAEH,KAAK,sBAAsB,GAAG;IAC7B,sFAAsF;IACtF,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,KAAK,yBAAyB,GAAG,sBAAsB,GAAG;IACzD,+DAA+D;IAC/D,OAAO,CAAC,EAAE;QACT,IAAI,CAAC,EAAE,GAAG,CAAC;QACX,kCAAkC;QAClC,GAAG,CAAC,EAAE,GAAG,CAAC;QACV,sEAAsE;QACtE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;KACpC,CAAC;CACF,CAAC;AAEF,KAAK,QAAQ,GAAG;IACf,OAAO,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACtE,CAAC;AAEF,uFAAuF;AACvF,cAAM,qBAAsB,SAAQ,KAAK;IACxC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;gBAGtC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,aAAa,EACnB,MAAM,EAAE,qBAAqB;CAQ9B;AAUD;;;GAGG;AACH,iBAAS,WAAW,CACnB,KAAK,EAAE,SAAS,aAAa,EAAE,EAC/B,EACC,gBAA+C,GAC/C,GAAE,sBAA2B,GAC5B,GAAG,CA6BL;AAED;;;GAGG;AACH,iBAAe,cAAc,CAC5B,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,SAAS,aAAa,EAAE,EAC/B,OAAO,CAAC,EAAE,yBAAyB,GACjC,OAAO,CAAC,eAAe,EAAE,CAAC,CA6B5B;AAED;;;;GAIG;AACH,iBAAe,qBAAqB,CACnC,KAAK,CAAC,MAAM,SAAS,SAAS,qBAAqB,EAAE,EAErD,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC,MAAM,CAAC,CAAC,EACtD,OAAO,CAAC,EAAE,yBAAyB,GACjC,OAAO,CAAC,uBAAuB,CAAC,MAAM,CAAC,CAAC,CAY1C;AAED,+FAA+F;AAC/F,iBAAS,aAAa,CAAC,IAAI,EAAE,GAAG,GAAG,eAAe,EAAE,CAwBnD;AAiDD,YAAY,EACX,gBAAgB,EAChB,yBAAyB,EACzB,aAAa,EACb,oBAAoB,EACpB,sBAAsB,EACtB,eAAe,EACf,GAAG,GACH,CAAC;AACF,OAAO,EACN,cAAc,EACd,qBAAqB,EACrB,aAAa,EACb,WAAW,EACX,qBAAqB,GACrB,CAAC"}