@volga-sh/evm-ghostcall 0.0.4 → 0.0.6

package/README.md

@@ -1,11 +1,10 @@
 # ghostcall
 
-`ghostcall` batches EVM contract reads without deploying a Multicall contract.
+`ghostcall` batches EVM contract reads into one `eth_call` without deploying a
+Multicall contract.
 
-## Documentation
-
-Start at [ghostcall.volga.sh](https://ghostcall.volga.sh) for the setup guide,
-recipes, API reference, protocol, and size limits.
+**Documentation: [ghostcall.volga.sh](https://ghostcall.volga.sh)**: getting
+started, API reference, protocol, and size limits.
 
 ## Install
 
@@ -13,94 +12,24 @@ recipes, API reference, protocol, and size limits.
 npm install @volga-sh/evm-ghostcall
 ```
 
-## Quick start
-
-This example uses viem for its client and ABI definition. ghostcall uses ox
-internally to encode arguments and decode results:
-
-```sh
-npm install viem
-```
+## Example
 
 ```ts
 import { aggregateDecodedCalls } from "@volga-sh/evm-ghostcall";
-import {
-	createPublicClient,
-	http,
-	parseAbi,
-} from "viem";
+import { createPublicClient, http, parseAbi } from "viem";
 import { mainnet } from "viem/chains";
 
-const client = createPublicClient({
-	chain: mainnet,
-	transport: http(),
-});
-
+const client = createPublicClient({ chain: mainnet, transport: http() });
 const abi = parseAbi(["function totalSupply() view returns (uint256)"]);
-const token = "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2";
+const weth = "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2";
 
 const [totalSupply] = await aggregateDecodedCalls(client, [
-	{
-		to: token,
-		abi,
-		functionName: "totalSupply",
-	},
+	{ to: weth, abi, functionName: "totalSupply" },
 ]);
 // totalSupply is inferred as bigint.
 ```
 
-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`.
-
-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()` 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.
-
-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
 
-```sh
-npm install
-npm run build:sdk
-npm run test
-npm run check
-```
-
-To work on the documentation:
-
-```sh
-npm run docs:dev
-npm run docs:build
-```
-
-The source is hosted at
-[github.com/volga-sh/ghostcall](https://github.com/volga-sh/ghostcall).
+See [Development](https://ghostcall.volga.sh/development/) for setup, the Yul
+workflow, tests, and benchmarks.

package/dist/sdk/abi.d.ts

@@ -32,8 +32,11 @@ type CallArguments<TCall extends GhostcallAbiCall> = TCall extends {
 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;
+/**
+ * Turn ABI calls into raw decoded calls that encode and decode with the same
+ * resolved function. Raw decoded calls pass through unchanged.
+ */
+declare function prepareDecodedCalls(calls: readonly (GhostcallAbiCall | GhostcallDecodedCall)[]): GhostcallDecodedCall[];
 export type { GhostcallAbiCall, GhostcallAbiResult };
-export { prepareAbiCall };
+export { prepareDecodedCalls };
 //# sourceMappingURL=abi.d.ts.map

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

@@ -1 +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"}
+{"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;AAOH;;;GAGG;AACH,iBAAS,mBAAmB,CAC3B,KAAK,EAAE,SAAS,CAAC,gBAAgB,GAAG,oBAAoB,CAAC,EAAE,GACzD,oBAAoB,EAAE,CAoBxB;AA0BD,YAAY,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,CAAC"}

package/dist/sdk/abi.js

@@ -1,20 +1,43 @@
 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,
+/**
+ * Turn ABI calls into raw decoded calls that encode and decode with the same
+ * resolved function. Raw decoded calls pass through unchanged.
+ */
+function prepareDecodedCalls(calls) {
+    const sharedFunctions = new Map();
+    return calls.map((call) => {
+        if (call.abi === undefined)
+            return call;
+        const args = call.args ?? [];
+        const abiFunction = resolveAbiFunction(call, args, sharedFunctions);
+        // ox encodes only the selector when args are missing, so reject that
+        // before RPC; literal ABIs catch it in types, runtime-loaded ABIs cannot.
+        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),
+        };
     });
-    // 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}`);
+}
+// Each ox lookup hashes the function signature, so a batch resolves each name
+// once when it can. ox ignores args when exactly one ABI item has the name, of
+// any item type. Other names resolve per call, by argument types.
+function resolveAbiFunction(call, args, sharedFunctions) {
+    const functions = sharedFunctions.get(call.abi) ?? new Map();
+    sharedFunctions.set(call.abi, functions);
+    let shared = functions.get(call.functionName);
+    if (shared === undefined) {
+        const matches = call.abi.filter((item) => "name" in item && item.name === call.functionName);
+        shared =
+            matches.length === 1
+                ? AbiFunction.fromAbi(call.abi, call.functionName)
+                : null;
+        functions.set(call.functionName, shared);
     }
-    return {
-        to: call.to,
-        data: AbiFunction.encodeData(abiFunction, args),
-        decodeResult: (returnData) => AbiFunction.decodeResult(abiFunction, returnData),
-    };
+    return shared ?? AbiFunction.fromAbi(call.abi, call.functionName, { args });
 }
-export { prepareAbiCall };
+export { prepareDecodedCalls };
 //# sourceMappingURL=abi.js.map

package/dist/sdk/abi.js.map

@@ -1 +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"}
+{"version":3,"file":"abi.js","sourceRoot":"","sources":["../../src/sdk/abi.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,WAAW,MAAM,gBAAgB,CAAC;AAoE9C;;;GAGG;AACH,SAAS,mBAAmB,CAC3B,KAA2D;IAE3D,MAAM,eAAe,GAAoB,IAAI,GAAG,EAAE,CAAC;IACnD,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAwB,EAAE;QAC/C,IAAI,IAAI,CAAC,GAAG,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC;QACxC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC;QAC7B,MAAM,WAAW,GAAG,kBAAkB,CAAC,IAAI,EAAE,IAAI,EAAE,eAAe,CAAC,CAAC;QACpE,qEAAqE;QACrE,0EAA0E;QAC1E,IAAI,IAAI,CAAC,MAAM,KAAK,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;YAC/C,MAAM,IAAI,SAAS,CAClB,GAAG,IAAI,CAAC,YAAY,YAAY,WAAW,CAAC,MAAM,CAAC,MAAM,wBAAwB,IAAI,CAAC,MAAM,EAAE,CAC9F,CAAC;QACH,CAAC;QACD,OAAO;YACN,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,IAAI,EAAE,WAAW,CAAC,UAAU,CAAC,WAAW,EAAE,IAAI,CAAC;YAC/C,YAAY,EAAE,CAAC,UAAU,EAAE,EAAE,CAC5B,WAAW,CAAC,YAAY,CAAC,WAAW,EAAE,UAAU,CAAC;SAClD,CAAC;IACH,CAAC,CAAC,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,+EAA+E;AAC/E,kEAAkE;AAClE,SAAS,kBAAkB,CAC1B,IAAsB,EACtB,IAAwB,EACxB,eAAgC;IAEhC,MAAM,SAAS,GAAoB,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,IAAI,GAAG,EAAE,CAAC;IAC9E,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;IACzC,IAAI,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAC9C,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QAC1B,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAC9B,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,IAAI,IAAI,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,YAAY,CAC3D,CAAC;QACF,MAAM;YACL,OAAO,CAAC,MAAM,KAAK,CAAC;gBACnB,CAAC,CAAC,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC;gBAClD,CAAC,CAAC,IAAI,CAAC;QACT,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,MAAM,IAAI,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;AAC7E,CAAC;AAGD,OAAO,EAAE,mBAAmB,EAAE,CAAC"}

package/dist/sdk/generated/initcode.js

@@ -1,4 +1,4 @@
-// This file is generated by scripts/generate-sdk-initcode.mjs.
+// This file is generated by scripts/generate-sdk-initcode.ts.
 // Run npm run build:contracts after changing src/Ghostcall.yul.
 export const ghostcallInitcode = "0x5f605b5b388110600d57505ff35b90601682823980515f808260f01c80938260168701918360168a01843960501c5af13d80600f1c60565760169381600293600f1b1760f01b8152815f8483013e01019201016003565b5f80fdfe";
 //# sourceMappingURL=initcode.js.map

package/dist/sdk/generated/initcode.js.map

@@ -1 +1 @@
-{"version":3,"file":"initcode.js","sourceRoot":"","sources":["../../../src/sdk/generated/initcode.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,gEAAgE;AAEhE,MAAM,CAAC,MAAM,iBAAiB,GAC7B,0LAAmM,CAAC"}
+{"version":3,"file":"initcode.js","sourceRoot":"","sources":["../../../src/sdk/generated/initcode.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,gEAAgE;AAEhE,MAAM,CAAC,MAAM,iBAAiB,GAC7B,0LAAmM,CAAC"}

package/dist/sdk/index.d.ts

@@ -9,27 +9,22 @@ type GhostcallCall = {
     /** Return failed entries from aggregateCalls instead of throwing. Default: false. */
     allowFailure?: boolean;
 };
-/** Raw calldata with a decoder that only receives successful results. */
-type GhostcallDecodedCall<TResult = unknown> = GhostcallCall & {
+/** Raw calldata with a decoder that only receives successful return data. */
+type GhostcallDecodedCall<TResult = unknown> = {
+    to: Hex;
+    /** At most 65,535 bytes (the wire format stores a uint16 length). */
+    data: Hex;
+    decodeResult: (returnData: Hex, index: number) => TResult;
     abi?: never;
     functionName?: never;
     args?: never;
     allowFailure?: never;
-    decodeResult: (returnData: Hex, entry: Extract<GhostcallResult, {
-        success: true;
-    }>, index: number) => TResult;
 };
-/** Raw results retain input order and include revert data for failed calls. */
+/** One subcall result. Failed calls carry their revert data in returnData. */
 type GhostcallResult = {
-    success: true;
-    returnData: Hex;
-} | {
-    success: false;
+    success: boolean;
     returnData: Hex;
 };
-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[]> = {
@@ -47,13 +42,13 @@ type GhostcallAggregateOptions = GhostcallEncodeOptions & {
     /** 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;
+        gas?: bigint;
+        /** A block number or named tag. Default: "latest". */
+        blockTag?: bigint | "latest" | "earliest" | "pending" | "safe" | "finalized";
     };
 };
-type Provider = {
+/** A provider with an EIP-1193-style request method, such as a viem client or ox transport. */
+type GhostcallProvider = {
     request(args: {
         method: string;
         params?: unknown;
@@ -63,26 +58,27 @@ type Provider = {
 declare class GhostcallSubcallError extends Error {
     readonly index: number;
     readonly call: GhostcallCall;
-    readonly result: GhostcallFailedResult;
-    constructor(index: number, call: GhostcallCall, result: GhostcallFailedResult);
+    readonly returnData: Hex;
+    constructor(index: number, call: GhostcallCall, returnData: Hex);
 }
 /**
  * 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 encodeCalls(calls: readonly GhostcallCall[], { maxInitcodeBytes, }?: GhostcallEncodeOptions): Hex;
+declare function encodeCalls(calls: readonly GhostcallCall[], { maxInitcodeBytes }?: GhostcallEncodeOptions): Hex;
 /**
  * Execute a raw batch in order. Failed calls throw GhostcallSubcallError unless
  * their entry sets allowFailure. Provider errors pass through unchanged.
  */
-declare function aggregateCalls(provider: Provider, calls: readonly GhostcallCall[], options?: GhostcallAggregateOptions): Promise<GhostcallResult[]>;
+declare function aggregateCalls(provider: GhostcallProvider, calls: readonly GhostcallCall[], options?: GhostcallAggregateOptions): Promise<GhostcallResult[]>;
 /**
  * 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>>;
+declare function aggregateDecodedCalls<const TCalls extends readonly GhostcallDecodedInput[]>(provider: GhostcallProvider, 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 { GhostcallAbiCall, GhostcallAggregateOptions, GhostcallCall, GhostcallDecodedCall, GhostcallEncodeOptions, GhostcallResult, Hex, };
+export type { GhostcallAbiCall, GhostcallAggregateOptions, GhostcallCall, GhostcallDecodedCall, GhostcallEncodeOptions, GhostcallProvider, 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":"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"}

package/dist/sdk/index.js

@@ -1,128 +1,142 @@
 import { validate as isAddress } from "ox/Address";
 import { size as hexSize, validate as isHex } from "ox/Hex";
-import { prepareAbiCall, } from "./abi.js";
+import { prepareDecodedCalls, } from "./abi.js";
 import { ghostcallInitcode } from "./generated/initcode.js";
 /** A disallowed failure, with its zero-based index, executed call, and revert data. */
 class GhostcallSubcallError extends Error {
     index;
     call;
-    result;
-    constructor(index, call, result) {
-        super(`Ghostcall subcall ${index} failed`);
+    returnData;
+    constructor(index, call, returnData) {
+        super(`ghostcall subcall ${index} failed`);
         this.name = "GhostcallSubcallError";
         this.index = index;
         this.call = call;
-        this.result = result;
+        this.returnData = returnData;
     }
 }
-const encodedCallHeaderSize = 22;
-const encodedHeaderHexLength = 4;
+// Request entries: [uint16 calldata length][20-byte target][calldata].
+const callHeaderSize = 22;
+const calldataLengthHexChars = 4;
 const maxCalldataSize = 0xffff;
-const defaultMaxCreateInitcodeSize = 0xc000;
-const successFlagMask = 0x8000;
+// Result entries: [success bit | uint15 returndata length][returndata].
+const resultHeaderHexChars = 4;
+const successFlag = 0x8000;
 const returnDataLengthMask = 0x7fff;
+// EIP-3860 initcode limit.
+const defaultMaxInitcodeBytes = 0xc000;
 const bundledInitcodeSize = hexSize(ghostcallInitcode);
 /**
  * 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.
  */
-function encodeCalls(calls, { maxInitcodeBytes = defaultMaxCreateInitcodeSize, } = {}) {
-    if (!Number.isSafeInteger(maxInitcodeBytes) || maxInitcodeBytes < 0) {
-        throw new TypeError("options.maxInitcodeBytes must be a non-negative safe integer");
-    }
-    const encodedParts = [ghostcallInitcode.slice(2)];
+function encodeCalls(calls, { maxInitcodeBytes = defaultMaxInitcodeBytes } = {}) {
+    let encodedData = ghostcallInitcode;
     let totalEncodedSize = bundledInitcodeSize;
-    const sizeError = `encoded Ghostcall initcode exceeds the ${maxInitcodeBytes}-byte CREATE initcode limit`;
+    const sizeError = `encoded ghostcall initcode exceeds the ${maxInitcodeBytes}-byte CREATE initcode limit`;
     if (totalEncodedSize > maxInitcodeBytes)
         throw new RangeError(sizeError);
-    for (const [index, call] of calls.entries()) {
-        assertAddress(call.to, `calls[${index}].to`);
+    // A plain loop keeps the string concatenation fast; see benchmark:sdk.
+    let index = 0;
+    for (const call of calls) {
+        const to = assertAddress(call.to, `calls[${index}].to`);
         const calldata = assertHex(call.data, `calls[${index}].data`);
         const calldataSize = hexSize(calldata);
         if (calldataSize > maxCalldataSize) {
             throw new RangeError(`calls[${index}].data exceeds the ${maxCalldataSize}-byte calldata limit`);
         }
-        totalEncodedSize += encodedCallHeaderSize + calldataSize;
+        totalEncodedSize += callHeaderSize + calldataSize;
         if (totalEncodedSize > maxInitcodeBytes)
             throw new RangeError(sizeError);
-        encodedParts.push(calldataSize.toString(16).padStart(4, "0"), call.to.slice(2), calldata.slice(2));
+        const header = calldataSize
+            .toString(16)
+            .padStart(calldataLengthHexChars, "0");
+        encodedData = `${encodedData}${header}${to.slice(2)}${calldata.slice(2)}`;
+        index += 1;
     }
-    return `0x${encodedParts.join("")}`;
+    return encodedData;
 }
 /**
  * Execute a raw batch in order. Failed calls throw GhostcallSubcallError unless
  * their entry sets allowFailure. Provider errors pass through unchanged.
  */
 async function aggregateCalls(provider, calls, options) {
-    const { from, gas, blockTag } = options?.ethCall ?? {};
-    const ethCall = {
-        data: encodeCalls(calls, options ?? {}),
-    };
-    if (from !== undefined) {
-        assertAddress(from, "options.ethCall.from");
-        ethCall.from = from;
-    }
-    if (gas !== undefined)
-        ethCall.gas = assertHexQuantity(gas, "options.ethCall.gas");
-    const result = await provider.request({
-        method: "eth_call",
-        params: [ethCall, normalizeBlockTag(blockTag ?? "latest")],
-    });
-    const entries = decodeResults(assertHex(result, "eth_call result"));
-    if (entries.length !== calls.length) {
-        throw new Error(`Ghostcall returned ${entries.length} result entries for ${calls.length} calls`);
-    }
-    for (const [index, entry] of entries.entries()) {
+    const results = await executeCalls(provider, calls, options);
+    let index = 0;
+    for (const { success, returnData } of results) {
         const call = calls[index];
-        if (!entry.success && call.allowFailure !== true) {
-            throw new GhostcallSubcallError(index, call, entry);
+        if (!success && !call.allowFailure) {
+            throw new GhostcallSubcallError(index, call, returnData);
         }
+        index += 1;
     }
-    return entries;
+    return results;
 }
 /**
  * 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.
  */
 async function aggregateDecodedCalls(provider, calls, options) {
-    const preparedCalls = calls.map((call) => call.abi === undefined ? call : prepareAbiCall(call));
-    const entries = await aggregateCalls(provider, preparedCalls, options);
-    return entries.map((entry, index) => {
-        // aggregateCalls has checked the count. Hidden allowFailure fields still cannot
-        // bypass this guard and send failed returndata to a success-only decoder.
+    const preparedCalls = prepareDecodedCalls(calls);
+    const results = await executeCalls(provider, preparedCalls, options);
+    return results.map(({ success, returnData }, index) => {
         const call = preparedCalls[index];
-        if (!entry.success)
-            throw new GhostcallSubcallError(index, call, entry);
-        return call.decodeResult(entry.returnData, entry, index);
+        if (!success)
+            throw new GhostcallSubcallError(index, call, returnData);
+        return call.decodeResult(returnData, index);
     });
 }
 /** Decode ordered [success bit | uint15 length][returndata] entries. Reject malformed data. */
 function decodeResults(data) {
-    const encodedData = assertHex(data, "data").slice(2);
+    return decodeValidatedResults(assertHex(data, "data"));
+}
+/** Send one eth_call and return one result per call, without applying a failure policy. */
+async function executeCalls(provider, calls, options = {}) {
+    const { from, gas, blockTag = "latest" } = options.ethCall ?? {};
+    const ethCall = {
+        data: encodeCalls(calls, options),
+        ...(from !== undefined && {
+            from: assertAddress(from, "options.ethCall.from"),
+        }),
+        ...(gas !== undefined && { gas: toQuantity(gas) }),
+    };
+    const response = await provider.request({
+        method: "eth_call",
+        params: [
+            ethCall,
+            typeof blockTag === "bigint" ? toQuantity(blockTag) : blockTag,
+        ],
+    });
+    const results = decodeValidatedResults(assertHex(response, "eth_call result"));
+    if (results.length !== calls.length) {
+        throw new Error(`ghostcall returned ${results.length} result entries for ${calls.length} calls`);
+    }
+    return results;
+}
+/** Parse only after the public API or RPC boundary has validated the entire hex string. */
+function decodeValidatedResults(data) {
     const results = [];
-    let cursor = 0;
-    while (cursor < encodedData.length) {
-        if (cursor + encodedHeaderHexLength > encodedData.length) {
-            throw new TypeError("Truncated Ghostcall response header");
-        }
-        const header = Number.parseInt(encodedData.slice(cursor, cursor + encodedHeaderHexLength), 16);
-        cursor += encodedHeaderHexLength;
-        const returnDataEnd = cursor + (header & returnDataLengthMask) * 2;
-        if (returnDataEnd > encodedData.length) {
-            throw new TypeError("Truncated Ghostcall response body");
+    let cursor = 2;
+    while (cursor < data.length) {
+        const start = cursor + resultHeaderHexChars;
+        const header = Number.parseInt(data.slice(cursor, start), 16);
+        cursor = start + (header & returnDataLengthMask) * 2;
+        // A partial header also ends past the data, so one check covers both cases.
+        if (cursor > data.length) {
+            throw new TypeError("Truncated ghostcall response");
         }
-        results.push({
-            success: (header & successFlagMask) !== 0,
-            returnData: `0x${encodedData.slice(cursor, returnDataEnd)}`,
-        });
-        cursor = returnDataEnd;
+        const success = (header & successFlag) !== 0;
+        results.push({ success, returnData: `0x${data.slice(start, cursor)}` });
     }
     return results;
 }
+// Types cannot express a 20-byte length; call targets reach the Yul program unchecked.
 function assertAddress(value, label) {
-    if (typeof value !== "string" || !isAddress(value, { strict: false })) {
+    if (!isAddress(value, { strict: false })) {
         throw new TypeError(`${label} must be a 20-byte hex string`);
     }
+    return value;
 }
 function assertHex(value, label) {
     // ox checks prefix/digits; the wire format additionally requires whole bytes.
@@ -131,29 +145,8 @@ function assertHex(value, label) {
     }
     return value;
 }
-function assertHexQuantity(value, label) {
-    if (typeof value !== "string" ||
-        !/^0x(?:0|[1-9a-fA-F][0-9a-fA-F]*)$/.test(value)) {
-        throw new TypeError(`${label} must be a 0x-prefixed hex quantity`);
-    }
-    return value;
-}
-function normalizeBlockTag(value) {
-    if (typeof value === "bigint" ||
-        (typeof value === "number" && Number.isSafeInteger(value))) {
-        if (value >= 0)
-            return `0x${value.toString(16)}`;
-    }
-    else if (typeof value === "string" &&
-        value.length > 0 &&
-        !/^-\d+$/.test(value)) {
-        if (/^\d+$/.test(value))
-            return `0x${BigInt(value).toString(16)}`;
-        return /^0x/i.test(value)
-            ? assertHexQuantity(`0x${value.slice(2)}`, "options.ethCall.blockTag")
-            : value;
-    }
-    throw new TypeError("options.ethCall.blockTag must be a non-negative safe integer, bigint, or non-empty string");
+function toQuantity(value) {
+    return `0x${value.toString(16)}`;
 }
 export { aggregateCalls, aggregateDecodedCalls, decodeResults, encodeCalls, GhostcallSubcallError, };
 //# sourceMappingURL=index.js.map

package/dist/sdk/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/sdk/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/sdk/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,9 +1,10 @@
 {
 	"name": "@volga-sh/evm-ghostcall",
-	"version": "0.0.4",
+	"version": "0.0.6",
 	"description": "Batch EVM contract reads without deploying a Multicall contract.",
 	"license": "MIT",
 	"type": "module",
+	"packageManager": "npm@12.1.0",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/volga-sh/ghostcall.git"
@@ -22,39 +23,38 @@
 	},
 	"files": [
 		"dist/",
-		"src/Ghostcall.yul"
+		"src/Ghostcall.yul",
+		"src/sdk/"
 	],
 	"sideEffects": false,
 	"publishConfig": {
 		"access": "public"
 	},
 	"scripts": {
-		"benchmark:limits": "node --disable-warning=ExperimentalWarning --experimental-strip-types scripts/benchmark-limits.ts",
+		"benchmark:limits": "node scripts/benchmark-limits.ts",
+		"benchmark:sdk": "node --expose-gc scripts/benchmark-sdk.ts",
 		"build:contracts": "forge build && npm run generate:sdk:initcode",
 		"build:sdk": "npm run build:contracts && tsc --project tsconfig.build.json",
 		"check": "biome check .",
 		"check:fix": "biome check --write .",
-		"docs:build": "npm run build --prefix docs",
-		"docs:dev": "npm run dev --prefix docs",
-		"docs:preview": "npm run preview --prefix docs",
+		"docs:build": "npm run build --prefix docs --",
+		"docs:dev": "npm run dev --prefix docs --",
+		"docs:preview": "npm run preview --prefix docs --",
 		"check:sdk:initcode": "git diff --exit-code -- src/sdk/generated/initcode.ts",
 		"format": "biome format --write .",
-		"format:check": "biome format .",
-		"generate:sdk:initcode": "node scripts/generate-sdk-initcode.mjs",
-		"lint": "biome lint .",
-		"lint:fix": "npm run check:fix",
+		"generate:sdk:initcode": "node scripts/generate-sdk-initcode.ts",
 		"prepack": "npm run build:sdk",
-		"test": "npm run build:contracts && node --disable-warning=ExperimentalWarning --experimental-strip-types --test test/*.test.ts",
-		"test:watch": "node --disable-warning=ExperimentalWarning --experimental-strip-types --test --watch test/*.test.ts",
+		"test": "npm run build:contracts && node --test test/*.test.ts",
+		"test:watch": "node --test --watch test/*.test.ts",
 		"typecheck": "tsc --project tsconfig.json"
 	},
 	"dependencies": {
-		"ox": "0.9.6"
+		"ox": "^1.8.3"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "2.4.12",
+		"@biomejs/biome": "2.5.14",
 		"@safe-global/mock-contract": "4.1.0",
-		"@types/node": "24.3.1",
-		"typescript": "5.9.2"
+		"@types/node": "24.19.1",
+		"typescript": "7.0.2"
 	}
 }

package/src/sdk/abi.ts

@@ -0,0 +1,123 @@
+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";
+
+// Distribute over functions so each name stays paired with its own arguments.
+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 [];
+
+// Infer ox's argument constraint through its public options, then let ox choose
+// the overload. This keeps our result types aligned with runtime resolution.
+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>
+	>;
+
+// Functions resolved within one batch, keyed by ABI object and function name.
+// `null` marks a name that must be resolved per call from its arguments.
+type FunctionsByName = Map<string, AbiFunction.AbiFunction | null>;
+type SharedFunctions = Map<Abi, FunctionsByName>;
+
+/**
+ * Turn ABI calls into raw decoded calls that encode and decode with the same
+ * resolved function. Raw decoded calls pass through unchanged.
+ */
+function prepareDecodedCalls(
+	calls: readonly (GhostcallAbiCall | GhostcallDecodedCall)[],
+): GhostcallDecodedCall[] {
+	const sharedFunctions: SharedFunctions = new Map();
+	return calls.map((call): GhostcallDecodedCall => {
+		if (call.abi === undefined) return call;
+		const args = call.args ?? [];
+		const abiFunction = resolveAbiFunction(call, args, sharedFunctions);
+		// ox encodes only the selector when args are missing, so reject that
+		// before RPC; literal ABIs catch it in types, runtime-loaded ABIs cannot.
+		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),
+		};
+	});
+}
+
+// Each ox lookup hashes the function signature, so a batch resolves each name
+// once when it can. ox ignores args when exactly one ABI item has the name, of
+// any item type. Other names resolve per call, by argument types.
+function resolveAbiFunction(
+	call: GhostcallAbiCall,
+	args: readonly unknown[],
+	sharedFunctions: SharedFunctions,
+): AbiFunction.AbiFunction {
+	const functions: FunctionsByName = sharedFunctions.get(call.abi) ?? new Map();
+	sharedFunctions.set(call.abi, functions);
+	let shared = functions.get(call.functionName);
+	if (shared === undefined) {
+		const matches = call.abi.filter(
+			(item) => "name" in item && item.name === call.functionName,
+		);
+		shared =
+			matches.length === 1
+				? AbiFunction.fromAbi(call.abi, call.functionName)
+				: null;
+		functions.set(call.functionName, shared);
+	}
+	return shared ?? AbiFunction.fromAbi(call.abi, call.functionName, { args });
+}
+
+export type { GhostcallAbiCall, GhostcallAbiResult };
+export { prepareDecodedCalls };

package/src/sdk/generated/initcode.ts

@@ -0,0 +1,5 @@
+// This file is generated by scripts/generate-sdk-initcode.ts.
+// Run npm run build:contracts after changing src/Ghostcall.yul.
+
+export const ghostcallInitcode =
+	"0x5f605b5b388110600d57505ff35b90601682823980515f808260f01c80938260168701918360168a01843960501c5af13d80600f1c60565760169381600293600f1b1760f01b8152815f8483013e01019201016003565b5f80fdfe" as const;

package/src/sdk/index.ts

@@ -0,0 +1,283 @@
+import { validate as isAddress } from "ox/Address";
+import { size as hexSize, validate as isHex } from "ox/Hex";
+
+import {
+	type GhostcallAbiCall,
+	type GhostcallAbiResult,
+	prepareDecodedCalls,
+} from "./abi.ts";
+import { ghostcallInitcode } from "./generated/initcode.ts";
+
+/** A 0x-prefixed string, validated at SDK wire boundaries. */
+type Hex = `0x${string}`;
+
+/** Raw calldata for one target. Encoding ignores the SDK-only failure policy. */
+type GhostcallCall = {
+	to: Hex;
+	/** At most 65,535 bytes (the wire format stores a uint16 length). */
+	data: Hex;
+	/** Return failed entries from aggregateCalls instead of throwing. Default: false. */
+	allowFailure?: boolean;
+};
+
+/** Raw calldata with a decoder that only receives successful return data. */
+type GhostcallDecodedCall<TResult = unknown> = {
+	to: Hex;
+	/** At most 65,535 bytes (the wire format stores a uint16 length). */
+	data: Hex;
+	decodeResult: (returnData: Hex, index: number) => TResult;
+	abi?: never;
+	functionName?: never;
+	args?: never;
+	allowFailure?: never;
+};
+
+/** One subcall result. Failed calls carry their revert data in returnData. */
+type GhostcallResult = { success: boolean; returnData: Hex };
+
+type GhostcallDecodedInput = GhostcallAbiCall | GhostcallDecodedCall;
+
+// Distribute over mixed call unions while retaining each tuple position.
+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 = {
+	/** Full CREATE request ceiling, including bundled initcode. Default: 49,152 bytes. */
+	maxInitcodeBytes?: number;
+};
+
+type GhostcallAggregateOptions = GhostcallEncodeOptions & {
+	/** Controls the outer eth_call, shared by the entire batch. */
+	ethCall?: {
+		from?: Hex;
+		gas?: bigint;
+		/** A block number or named tag. Default: "latest". */
+		blockTag?:
+			| bigint
+			| "latest"
+			| "earliest"
+			| "pending"
+			| "safe"
+			| "finalized";
+	};
+};
+
+/** A provider with an EIP-1193-style request method, such as a viem client or ox transport. */
+type GhostcallProvider = {
+	request(args: { method: string; params?: unknown }): Promise<unknown>;
+};
+
+/** A disallowed failure, with its zero-based index, executed call, and revert data. */
+class GhostcallSubcallError extends Error {
+	readonly index: number;
+	readonly call: GhostcallCall;
+	readonly returnData: Hex;
+
+	constructor(index: number, call: GhostcallCall, returnData: Hex) {
+		super(`ghostcall subcall ${index} failed`);
+		this.name = "GhostcallSubcallError";
+		this.index = index;
+		this.call = call;
+		this.returnData = returnData;
+	}
+}
+
+// Request entries: [uint16 calldata length][20-byte target][calldata].
+const callHeaderSize = 22;
+const calldataLengthHexChars = 4;
+const maxCalldataSize = 0xffff;
+// Result entries: [success bit | uint15 returndata length][returndata].
+const resultHeaderHexChars = 4;
+const successFlag = 0x8000;
+const returnDataLengthMask = 0x7fff;
+// EIP-3860 initcode limit.
+const defaultMaxInitcodeBytes = 0xc000;
+const bundledInitcodeSize = hexSize(ghostcallInitcode);
+
+/**
+ * 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.
+ */
+function encodeCalls(
+	calls: readonly GhostcallCall[],
+	{ maxInitcodeBytes = defaultMaxInitcodeBytes }: GhostcallEncodeOptions = {},
+): Hex {
+	let encodedData: Hex = ghostcallInitcode;
+	let totalEncodedSize = bundledInitcodeSize;
+	const sizeError = `encoded ghostcall initcode exceeds the ${maxInitcodeBytes}-byte CREATE initcode limit`;
+	if (totalEncodedSize > maxInitcodeBytes) throw new RangeError(sizeError);
+
+	// A plain loop keeps the string concatenation fast; see benchmark:sdk.
+	let index = 0;
+	for (const call of calls) {
+		const to = assertAddress(call.to, `calls[${index}].to`);
+		const calldata = assertHex(call.data, `calls[${index}].data`);
+		const calldataSize = hexSize(calldata);
+		if (calldataSize > maxCalldataSize) {
+			throw new RangeError(
+				`calls[${index}].data exceeds the ${maxCalldataSize}-byte calldata limit`,
+			);
+		}
+		totalEncodedSize += callHeaderSize + calldataSize;
+		if (totalEncodedSize > maxInitcodeBytes) throw new RangeError(sizeError);
+		const header = calldataSize
+			.toString(16)
+			.padStart(calldataLengthHexChars, "0");
+		encodedData = `${encodedData}${header}${to.slice(2)}${calldata.slice(2)}`;
+		index += 1;
+	}
+	return encodedData;
+}
+
+/**
+ * Execute a raw batch in order. Failed calls throw GhostcallSubcallError unless
+ * their entry sets allowFailure. Provider errors pass through unchanged.
+ */
+async function aggregateCalls(
+	provider: GhostcallProvider,
+	calls: readonly GhostcallCall[],
+	options?: GhostcallAggregateOptions,
+): Promise<GhostcallResult[]> {
+	const results = await executeCalls(provider, calls, options);
+	let index = 0;
+	for (const { success, returnData } of results) {
+		const call = calls[index] as GhostcallCall;
+		if (!success && !call.allowFailure) {
+			throw new GhostcallSubcallError(index, call, returnData);
+		}
+		index += 1;
+	}
+	return results;
+}
+
+/**
+ * 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.
+ */
+async function aggregateDecodedCalls<
+	const TCalls extends readonly GhostcallDecodedInput[],
+>(
+	provider: GhostcallProvider,
+	calls: TCalls & NoInfer<ValidatedDecodedCalls<TCalls>>,
+	options?: GhostcallAggregateOptions,
+): Promise<GhostcallDecodedResults<TCalls>> {
+	const preparedCalls = prepareDecodedCalls(calls);
+	const results = await executeCalls(provider, preparedCalls, options);
+	return results.map(({ success, returnData }, index) => {
+		const call = preparedCalls[index] as GhostcallDecodedCall;
+		if (!success) throw new GhostcallSubcallError(index, call, returnData);
+		return call.decodeResult(returnData, index);
+	}) as GhostcallDecodedResults<TCalls>;
+}
+
+/** Decode ordered [success bit | uint15 length][returndata] entries. Reject malformed data. */
+function decodeResults(data: Hex): GhostcallResult[] {
+	return decodeValidatedResults(assertHex(data, "data"));
+}
+
+/** Send one eth_call and return one result per call, without applying a failure policy. */
+async function executeCalls(
+	provider: GhostcallProvider,
+	calls: readonly GhostcallCall[],
+	options: GhostcallAggregateOptions = {},
+): Promise<GhostcallResult[]> {
+	const { from, gas, blockTag = "latest" } = options.ethCall ?? {};
+	const ethCall = {
+		data: encodeCalls(calls, options),
+		...(from !== undefined && {
+			from: assertAddress(from, "options.ethCall.from"),
+		}),
+		...(gas !== undefined && { gas: toQuantity(gas) }),
+	};
+	const response = await provider.request({
+		method: "eth_call",
+		params: [
+			ethCall,
+			typeof blockTag === "bigint" ? toQuantity(blockTag) : blockTag,
+		],
+	});
+	const results = decodeValidatedResults(
+		assertHex(response, "eth_call result"),
+	);
+	if (results.length !== calls.length) {
+		throw new Error(
+			`ghostcall returned ${results.length} result entries for ${calls.length} calls`,
+		);
+	}
+	return results;
+}
+
+/** Parse only after the public API or RPC boundary has validated the entire hex string. */
+function decodeValidatedResults(data: Hex): GhostcallResult[] {
+	const results: GhostcallResult[] = [];
+	let cursor = 2;
+	while (cursor < data.length) {
+		const start = cursor + resultHeaderHexChars;
+		const header = Number.parseInt(data.slice(cursor, start), 16);
+		cursor = start + (header & returnDataLengthMask) * 2;
+		// A partial header also ends past the data, so one check covers both cases.
+		if (cursor > data.length) {
+			throw new TypeError("Truncated ghostcall response");
+		}
+		const success = (header & successFlag) !== 0;
+		results.push({ success, returnData: `0x${data.slice(start, cursor)}` });
+	}
+	return results;
+}
+
+// Types cannot express a 20-byte length; call targets reach the Yul program unchecked.
+function assertAddress(value: string, label: string): Hex {
+	if (!isAddress(value, { strict: false })) {
+		throw new TypeError(`${label} must be a 20-byte hex string`);
+	}
+	return value;
+}
+
+function assertHex(value: unknown, label: string): Hex {
+	// ox checks prefix/digits; the wire format additionally requires whole bytes.
+	if (!isHex(value, { strict: true }) || value.length % 2 !== 0) {
+		throw new TypeError(
+			`${label} must be an even-length 0x-prefixed hex string`,
+		);
+	}
+	return value;
+}
+
+function toQuantity(value: bigint): Hex {
+	return `0x${value.toString(16)}`;
+}
+
+export type {
+	GhostcallAbiCall,
+	GhostcallAggregateOptions,
+	GhostcallCall,
+	GhostcallDecodedCall,
+	GhostcallEncodeOptions,
+	GhostcallProvider,
+	GhostcallResult,
+	Hex,
+};
+export {
+	aggregateCalls,
+	aggregateDecodedCalls,
+	decodeResults,
+	encodeCalls,
+	GhostcallSubcallError,
+};