@volga-sh/evm-ghostcall 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 volga-sh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,320 @@
+# ghostcall
+
+`ghostcall` is a zero-deployment batching program for CREATE-style `eth_call`.
+
+Instead of calling a deployed Multicall contract, the client sends compiled initcode plus an
+appended payload. The EVM executes that initcode exactly as if it were deploying a contract, but
+because the transport is `eth_call`, nothing is persisted. Whatever the initcode `RETURN`s comes
+back as the RPC result.
+
+The implementation lives in [`src/Ghostcall.yul`](src/Ghostcall.yul).
+
+## Quick example
+
+```ts
+import { aggregateCalls } from "@volga-sh/evm-ghostcall";
+import {
+	createPublicClient,
+	decodeFunctionResult,
+	encodeFunctionData,
+	http,
+	parseAbi,
+} from "viem";
+import { mainnet } from "viem/chains";
+
+const erc20Abi = parseAbi([
+	"function balanceOf(address account) view returns (uint256)",
+	"function allowance(address owner, address spender) view returns (uint256)",
+]);
+
+const token = "0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eb48";
+const owner = "0x1111111111111111111111111111111111111111";
+const spender = "0x2222222222222222222222222222222222222222";
+
+const client = createPublicClient({
+	chain: mainnet,
+	transport: http(),
+});
+
+const [balance, allowance] = await aggregateCalls(
+	client,
+	[
+		{
+			to: token,
+			data: encodeFunctionData({
+				abi: erc20Abi,
+				functionName: "balanceOf",
+				args: [owner],
+			}),
+			decodeResult: (data) =>
+				decodeFunctionResult({
+					abi: erc20Abi,
+					functionName: "balanceOf",
+					data,
+				}),
+		},
+		{
+			to: token,
+			data: encodeFunctionData({
+				abi: erc20Abi,
+				functionName: "allowance",
+				args: [owner, spender],
+			}),
+			decodeResult: (data) =>
+				decodeFunctionResult({
+					abi: erc20Abi,
+					functionName: "allowance",
+					data,
+				}),
+		},
+	],
+	{ results: "decoded" },
+);
+
+console.log({
+	balance,
+	allowance,
+});
+```
+
+## Why this works
+
+- `eth_call` without a `to` field executes the supplied `data` as CREATE initcode.
+- Initcode can read caller-appended bytes from its own code using `CODECOPY`.
+- Initcode can perform ordinary external calls, pack the returned bytes into memory, and `RETURN` them.
+- Returned bytes are still subject to CREATE limits because the client treats them as would-be
+  runtime bytecode.
+
+## Development stack
+
+The repository now uses a minimal TypeScript-based test stack:
+
+- Foundry for contract compilation and `anvil`
+- Node's built-in [`node:test`](https://nodejs.org/api/test.html) runner
+- Node's built-in TypeScript stripping for test execution
+- [`ox`](https://www.npmjs.com/package/ox) for JSON-RPC, ABI, hex, and byte utilities
+- [`@safe-global/mock-contract`](https://www.npmjs.com/package/@safe-global/mock-contract) for configurable mock-call behavior
+
+That keeps the dependency footprint small while giving us a stable place to grow ABI-heavy tests.
+
+## TypeScript SDK
+
+Install the SDK from npm:
+
+```bash
+npm install @volga-sh/evm-ghostcall
+```
+
+The repository also includes a minimal internal-first TypeScript SDK in
+[`src/sdk/index.ts`](src/sdk/index.ts).
+
+It intentionally exposes only the small protocol surface:
+
+- `encodeCalls(calls)` bundles the canonical Ghostcall initcode and returns the full CREATE-style `eth_call` data blob.
+- `decodeResults(data)` parses the packed Ghostcall response format into `{ success, returnData }` entries.
+- `aggregateCalls(provider, calls, options?)` sends the CREATE-style `eth_call` through an EIP-1193 `request` provider, decodes the packed response, and optionally runs each call's `decodeResult` callback.
+
+`encodeCalls` fails fast if any subcall exceeds the `uint16` calldata limit or if the full
+encoded CREATE payload would exceed the EVM initcode size ceiling.
+
+`aggregateCalls` treats `allowFailure` as an SDK-side policy. Failed subcalls reject by default,
+matching Multicall3-style strict batches, while calls marked `allowFailure: true` are returned as
+ordinary `{ success: false, returnData }` entries.
+
+The SDK has no ABI helpers and no runtime artifact reads. To ABI-decode successful entries, pass
+`decodeResult` callbacks that call the ABI library already used by the application. By default,
+`aggregateCalls` returns result entries. Pass `{ results: "decoded" }` to return decoded values
+directly.
+
+## Current scope
+
+This implementation is intentionally focused on the smallest SDK-first variant:
+
+- zero-value `CALL` for subcalls
+- packed binary input instead of ABI encoding
+- packed binary output instead of ABI encoding
+- always-return result entries for every subcall
+- SDK-enforced strict failure policy instead of engine-enforced batch reverts
+
+That keeps the initcode small, auditable, and easy to extend.
+
+## Why not a naive Solidity constructor
+
+A straightforward deployless design is to write a Solidity constructor that:
+
+- accepts an ABI-encoded array of calls,
+- executes them in the constructor, and
+- rewrites constructor memory so the returned bytes look like a normal ABI-encoded multicall result.
+
+That approach works, but this project intentionally uses a lower-level Yul program instead.
+
+Advantages of the current design:
+
+- smaller base program, because it avoids Solidity's constructor scaffolding and generic ABI decoding,
+- a tighter wire format, because both requests and responses use a compact custom binary layout instead of full ABI encoding,
+- less compiler coupling, because the batching logic does not depend on Solidity memory-layout assumptions inside constructor-generated code.
+
+In practice, this means less initcode to ship on every request, fewer bytes on the wire, and a design that is easier to reason about at the EVM level.
+
+## Input format
+
+The caller sends:
+
+```text
+<compiled ghostcall initcode><payload>
+```
+
+Payload layout:
+
+```text
+N bytes  repeated call entries
+```
+
+Each call entry:
+
+```text
+ 2 bytes calldata length (big-endian uint16)
+20 bytes target
+ N bytes calldata
+```
+
+Notes:
+
+- Payload bytes are not normal calldata. They are appended after the compiled initcode and read via
+  `CODECOPY`.
+- The length comes first on purpose. Ghostcall copies the 22-byte fixed header into scratch memory
+  at offset `0x0a`, so one `mload(0x00)` exposes the length in the high 2 non-zero bytes and the
+  target address in the low 20 bytes used by `CALL`.
+- An empty payload is valid and returns an empty result blob.
+- Per-call calldata is limited to `65535` bytes because the format uses `uint16`.
+- The whole CREATE payload is still limited by the network/client initcode size ceiling.
+
+## Output format
+
+The program returns:
+
+```text
+N bytes  repeated result entries
+```
+
+Each result entry:
+
+```text
+ 2 bytes packed header
+         bit 15    = success flag
+         bits 0-14 = returndata length (big-endian uint15)
+ N bytes returndata
+```
+
+Subcall failures are returned inline as ordinary result entries with `success = 0`.
+
+The engine only reverts for malformed payloads or per-entry return-size violations, and those
+top-level reverts are intentionally empty. The SDK is expected to validate payloads up front and
+impose any higher-level "fail the whole batch" policy for callers that want it.
+
+The packed result header can represent up to `32767` bytes of returndata per entry. On
+Ethereum, EIP-170's returned-code limit is usually the stricter bound: CREATE-style execution
+limits the whole response to `24,576` bytes, including the 2-byte header on each entry.
+
+## Limits
+
+The aggregate response is returned through CREATE-style execution, so clients still treat it as
+would-be runtime code. Ghostcall does not impose its own aggregate response cap; the effective
+ceiling comes from the chain, client, RPC provider, gas setting, and request-size policy.
+
+Common reference points:
+
+- Ethereum's EIP-170 returned-code limit is `24,576` bytes.
+- Ethereum's EIP-3860 initcode limit is `49,152` bytes.
+- Other chains may set different values. For example, Monad documents larger contract-code and
+  initcode limits.
+
+Measure the endpoint you plan to use instead of assuming a consensus value. Provider-side request
+limits can be lower than the chain limit.
+
+## Benchmark limits
+
+The repository includes a TypeScript benchmark for rough endpoint-specific measurements:
+
+```bash
+npm run benchmark:limits -- --rpc-url "$RPC_URL" --mode raw
+```
+
+`raw` mode probes accepted CREATE initcode bytes and returned runtime-code bytes. `balances` mode
+uses a realistic ERC-20 balance workload:
+
+```bash
+npm run benchmark:limits -- \
+  --rpc-url "$RPC_URL" \
+  --mode balances \
+  --token "$TOKEN_ADDRESS" \
+  --owner "$OWNER_ADDRESS"
+```
+
+For balance benchmarking, pass token addresses that implement `balanceOf(address)` on the selected
+chain. The script repeats those token and owner inputs, builds ghostcall batches with the public
+SDK encoder, and searches for the largest successful call count. The balance search is capped by
+both `--max-calls` and `--max-initcode-bytes`.
+
+Useful options:
+
+- `--mode raw|balances|all`, default `all`
+- `--token` and `--owner`, repeatable or comma-separated
+- `--block`, `--from`, `--gas`, and `--timeout-ms`
+- `--max-calls`, `--max-initcode-bytes`, and `--max-runtime-bytes`
+- `--json` for machine-readable output
+
+## Install
+
+```bash
+npm install
+```
+
+## Build contracts
+
+```bash
+npm run build:contracts
+```
+
+The compiled artifacts are emitted into the standard Foundry artifact tree under `out/`.
+That build step also refreshes the generated SDK initcode file at
+[`src/sdk/generated/initcode.ts`](src/sdk/generated/initcode.ts).
+
+## Test
+
+```bash
+npm test
+```
+
+The test suite:
+
+- compiles the contracts with Foundry,
+- starts an ephemeral `anvil` instance automatically,
+- deploys and configures `MockContract` from Foundry artifacts,
+- encodes function calldata with `ox`,
+- executes a CREATE-style `eth_call` against Ghostcall,
+- dogfoods the provider-facing SDK aggregation helper,
+- decodes both function return data and revert data with `ox`,
+- verifies configurable success paths, calldata-vs-method precedence, inline failure entries, the empty-batch case, the CREATE request-size boundary, the CREATE return-size boundary, and top-level malformed-payload handling.
+
+For static TypeScript checking:
+
+```bash
+npm run typecheck
+```
+
+## Design notes
+
+The implementation chooses Yul over raw bytecode because it keeps the control flow legible while
+still mapping one-to-one onto the EVM concepts that matter here:
+
+- `dataoffset(...)` anchors the appended payload boundary
+- `codecopy` streams headers and calldata directly from the appended payload
+- the len-first header plus a `0x0a` scratch offset lets one `mload(0x00)` yield both calldata
+  length and the `CALL` address word without extra masking
+- `call` executes each subcall with zero value
+- `returndatacopy` packs the aggregate response into a compact binary format
+- `return` hands the batch result back to RPC
+
+That gives you a maintainable base version first, with a straightforward path to hand-optimizing
+hot spots later if initcode size becomes the bottleneck.

package/dist/sdk/generated/initcode.d.ts

@@ -0,0 +1,2 @@
+export declare const ghostcallInitcode: "0x6020606c5b38810360135750601f19016020f35b90601682600a395f51918260a01c9060168282010193388511606757825f92838093601696600289019788940184395af1913d91617fff83116067575f839182600296600f1b1760f01b84523e0101906004565b5f80fdfe";
+//# sourceMappingURL=initcode.d.ts.map

package/dist/sdk/generated/initcode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"initcode.d.ts","sourceRoot":"","sources":["../../../src/sdk/generated/initcode.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,iBAAiB,EAC7B,4NAAqO,CAAC"}

package/dist/sdk/generated/initcode.js

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

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

@@ -0,0 +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,4NAAqO,CAAC"}

package/dist/sdk/index.d.ts

@@ -0,0 +1,254 @@
+/**
+ * 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.
+ */
+type Hex = `0x${string}`;
+/**
+ * One Ghostcall subcall entry.
+ */
+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`.
+     */
+    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.
+     */
+    allowFailure?: boolean;
+    /**
+     * Optional decoder for 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<unknown>;
+};
+/**
+ * One Ghostcall aggregate subcall entry for decoded-results mode.
+ */
+type GhostcallDecodedAggregateCall<TResult = unknown> = GhostcallCall & {
+    /**
+     * Decodes this call's successful return data.
+     */
+    decodeResult: GhostcallResultDecoder<TResult>;
+    /**
+     * Decoded-results mode is strict and does not return failed entries.
+     */
+    allowFailure?: false;
+};
+/**
+ * One decoded Ghostcall result entry.
+ */
+type GhostcallResult = {
+    /**
+     * 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: boolean;
+    /**
+     * 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;
+};
+/**
+ * Function used by {@link aggregateCalls} to turn raw successful return data into
+ * a caller-chosen value.
+ */
+type GhostcallResultDecoder<TResult> = (returnData: Hex, entry: GhostcallResult, index: number) => TResult;
+/**
+ * One decoded aggregate result entry when a call provides `decodeResult`.
+ */
+type GhostcallDecodedResult<TResult> = {
+    success: true;
+    returnData: Hex;
+    decodedResult: TResult;
+};
+type GhostcallAggregateResult<TCall> = TCall extends {
+    decodeResult: GhostcallResultDecoder<infer TResult>;
+} ? TCall extends {
+    allowFailure: true;
+} ? GhostcallDecodedResult<TResult> | GhostcallResult : GhostcallDecodedResult<TResult> : GhostcallResult;
+type GhostcallAggregateResults<TCalls extends readonly GhostcallAggregateCall[]> = {
+    -readonly [Index in keyof TCalls]: GhostcallAggregateResult<TCalls[Index]>;
+};
+type GhostcallDecodedResults<TCalls extends readonly GhostcallDecodedAggregateCall[]> = {
+    -readonly [Index in keyof TCalls]: TCalls[Index] extends {
+        decodeResult: GhostcallResultDecoder<infer TResult>;
+    } ? TResult : never;
+};
+type GhostcallAggregateOptions = {
+    /**
+     * Result shape returned by {@link aggregateCalls}.
+     *
+     * Defaults to `entries`, returning Ghostcall result entries. Set to `decoded`
+     * to return each call's decoded value directly.
+     */
+    results?: "entries";
+};
+type GhostcallDecodedAggregateOptions = {
+    /**
+     * Return each call's decoded value directly.
+     */
+    results: "decoded";
+};
+/**
+ * Minimal EIP-1193 provider shape used by the SDK.
+ */
+type EIP1193ProviderWithRequestFn = {
+    request(args: {
+        method: string;
+        params?: unknown;
+    }): Promise<unknown>;
+};
+/**
+ * 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]`.
+ *
+ * @param calls - Ordered list of subcalls to execute. Each entry becomes one
+ *                Ghostcall payload segment in the same order it appears here.
+ *
+ * @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
+ *                      EVM initcode size limit.
+ *
+ * @example
+ * const data = encodeCalls([
+ *   {
+ *     to: "0x1111111111111111111111111111111111111111",
+ *     data: "0x70a08231000000000000000000000000aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+ *   },
+ *   {
+ *     to: "0x2222222222222222222222222222222222222222",
+ *     data: "0x18160ddd",
+ *   },
+ * ]);
+ *
+ * // Later:
+ * // provider.request({ method: "eth_call", params: [{ data }, "latest"] })
+ */
+declare function encodeCalls(calls: readonly GhostcallCall[]): 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 decoded result entries
+ * in the same order as the input calls.
+ *
+ * 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. Set `decodeResult` on a call to transform successful raw
+ * return data, for example with `decodeFunctionResult` from an ABI library.
+ * Pass `{ results: "decoded" }` as the third argument to receive only the
+ * decoded values.
+ *
+ * @param provider - EIP-1193-compatible provider with a `request` method.
+ * @param calls - Ordered list of subcalls to execute.
+ * @param options - Optional result-shape controls.
+ *
+ * @returns Ordered decoded 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 EVM
+ *                      size limits.
+ * @throws {Error} If a subcall fails without `allowFailure: true`, or if the
+ *                 response entry count does not match the request entry count.
+ *
+ * @example
+ * const results = await aggregateCalls(provider, [
+ *   {
+ *     to: "0x1111111111111111111111111111111111111111",
+ *     data: "0x70a08231000000000000000000000000aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+ *     decodeResult: (returnData) => decodeFunctionResult({
+ *       abi: erc20Abi,
+ *       functionName: "balanceOf",
+ *       data: returnData,
+ *     }),
+ *   },
+ *   {
+ *     to: "0x2222222222222222222222222222222222222222",
+ *     data: "0x18160ddd",
+ *     allowFailure: true,
+ *   },
+ * ]);
+ *
+ * const [balance] = await aggregateCalls(provider, [
+ *   {
+ *     to: "0x1111111111111111111111111111111111111111",
+ *     data: "0x70a08231000000000000000000000000aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+ *     decodeResult: (returnData) => decodeFunctionResult({
+ *       abi: erc20Abi,
+ *       functionName: "balanceOf",
+ *       data: returnData,
+ *     }),
+ *   },
+ * ], { results: "decoded" });
+ */
+declare function aggregateCalls<const TCalls extends readonly GhostcallAggregateCall[]>(provider: EIP1193ProviderWithRequestFn, calls: TCalls, options?: GhostcallAggregateOptions): Promise<GhostcallAggregateResults<TCalls>>;
+declare function aggregateCalls<const TCalls extends readonly GhostcallDecodedAggregateCall[]>(provider: EIP1193ProviderWithRequestFn, calls: TCalls, options: GhostcallDecodedAggregateOptions): Promise<GhostcallDecodedResults<TCalls>>;
+/**
+ * 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" }
+ * // ]
+ */
+declare function decodeResults(data: Hex): GhostcallResult[];
+export type { EIP1193ProviderWithRequestFn, GhostcallAggregateCall, GhostcallAggregateOptions, GhostcallAggregateResult, GhostcallCall, GhostcallDecodedAggregateCall, GhostcallDecodedAggregateOptions, GhostcallDecodedResult, GhostcallDecodedResults, GhostcallResult, GhostcallResultDecoder, Hex, };
+export { aggregateCalls, decodeResults, encodeCalls };
+//# sourceMappingURL=index.d.ts.map

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

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

package/dist/sdk/index.js

@@ -0,0 +1,226 @@
+import { ghostcallInitcode } from "./generated/initcode.js";
+const addressHexLength = 40;
+const encodedHeaderHexLength = 4;
+const maxCalldataSize = 0xffff;
+const encodedCallHeaderSize = 0x16;
+const maxCreateInitcodeSize = 0xc000;
+const successFlagMask = 0x8000;
+const returnDataLengthMask = 0x7fff;
+const bundledInitcodeSize = byteLength(ghostcallInitcode);
+/**
+ * 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]`.
+ *
+ * @param calls - Ordered list of subcalls to execute. Each entry becomes one
+ *                Ghostcall payload segment in the same order it appears here.
+ *
+ * @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
+ *                      EVM initcode size limit.
+ *
+ * @example
+ * const data = encodeCalls([
+ *   {
+ *     to: "0x1111111111111111111111111111111111111111",
+ *     data: "0x70a08231000000000000000000000000aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+ *   },
+ *   {
+ *     to: "0x2222222222222222222222222222222222222222",
+ *     data: "0x18160ddd",
+ *   },
+ * ]);
+ *
+ * // Later:
+ * // provider.request({ method: "eth_call", params: [{ data }, "latest"] })
+ */
+function encodeCalls(calls) {
+    const encodedParts = [ghostcallInitcode.slice(2)];
+    let totalEncodedSize = bundledInitcodeSize;
+    for (const [index, call] of calls.entries()) {
+        assertAddress(call.to, `calls[${index}].to`);
+        const calldata = assertHex(call.data, `calls[${index}].data`);
+        const calldataSize = byteLength(calldata);
+        if (calldataSize > maxCalldataSize) {
+            throw new RangeError(`calls[${index}].data exceeds the ${maxCalldataSize}-byte calldata limit`);
+        }
+        totalEncodedSize += encodedCallHeaderSize + calldataSize;
+        if (totalEncodedSize > maxCreateInitcodeSize) {
+            throw new RangeError(`encoded Ghostcall initcode exceeds the ${maxCreateInitcodeSize}-byte CREATE initcode limit`);
+        }
+        encodedParts.push(calldataSize.toString(16).padStart(4, "0"));
+        encodedParts.push(call.to.slice(2));
+        encodedParts.push(calldata.slice(2));
+    }
+    return `0x${encodedParts.join("")}`;
+}
+async function aggregateCalls(provider, calls, options = {}) {
+    let decodedCalls;
+    if (options.results === "decoded") {
+        for (const [index, call] of calls.entries()) {
+            if (call.allowFailure === true) {
+                throw new TypeError(`calls[${index}].allowFailure cannot be true when results is decoded`);
+            }
+            if (call.decodeResult === undefined) {
+                throw new TypeError(`calls[${index}].decodeResult is required when results is decoded`);
+            }
+        }
+        decodedCalls = calls;
+    }
+    const data = encodeCalls(calls);
+    const result = await provider.request({
+        method: "eth_call",
+        params: [{ data }, "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()) {
+        if (!entry.success && calls[index]?.allowFailure !== true) {
+            throw new Error(`Ghostcall subcall ${index} failed`);
+        }
+    }
+    if (decodedCalls !== undefined) {
+        return entries.map((entry, index) => {
+            const call = decodedCalls[index];
+            if (call === undefined) {
+                throw new Error("Ghostcall decoded call invariant failed");
+            }
+            return call.decodeResult(entry.returnData, entry, index);
+        });
+    }
+    const decodedEntries = entries.map((entry, index) => {
+        const decodeResult = calls[index]?.decodeResult;
+        if (!entry.success || decodeResult === undefined) {
+            return entry;
+        }
+        return {
+            ...entry,
+            success: true,
+            decodedResult: decodeResult(entry.returnData, entry, index),
+        };
+    });
+    return decodedEntries;
+}
+/**
+ * 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" }
+ * // ]
+ */
+function decodeResults(data) {
+    const normalizedData = assertHex(data, "data");
+    if (normalizedData === "0x") {
+        return [];
+    }
+    const results = [];
+    const encodedData = normalizedData.slice(2);
+    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);
+        const success = (header & successFlagMask) !== 0;
+        const returnDataSize = header & returnDataLengthMask;
+        const nextCursor = cursor + encodedHeaderHexLength;
+        const returnDataEnd = nextCursor + returnDataSize * 2;
+        if (returnDataEnd > encodedData.length) {
+            throw new TypeError("Truncated Ghostcall response body");
+        }
+        results.push({
+            success,
+            returnData: `0x${encodedData.slice(nextCursor, returnDataEnd)}`,
+        });
+        cursor = returnDataEnd;
+    }
+    return results;
+}
+/**
+ * Validates that a value is a canonical 20-byte hex address.
+ *
+ * @param value - Unknown input to validate.
+ * @param label - Field name used in thrown error messages.
+ *
+ * @throws {TypeError} If the value is not valid `0x`-prefixed hex or is not
+ *                     exactly 20 bytes long.
+ *
+ * @internal
+ */
+function assertAddress(value, label) {
+    const normalizedValue = assertHex(value, label);
+    if (normalizedValue.length !== addressHexLength + 2) {
+        throw new TypeError(`${label} must be a 20-byte hex string`);
+    }
+}
+/**
+ * Validates that a value is an even-length `0x`-prefixed hex string.
+ *
+ * @param value - Unknown input to validate.
+ * @param label - Field name used in thrown error messages.
+ *
+ * @returns The validated value narrowed to {@link Hex}.
+ *
+ * @throws {TypeError} If the value is not a string, lacks the `0x` prefix, has an
+ *                     odd number of hex characters, or contains non-hex digits.
+ *
+ * @internal
+ */
+function assertHex(value, label) {
+    if (typeof value !== "string") {
+        throw new TypeError(`${label} must be a hex string`);
+    }
+    if (!value.startsWith("0x")) {
+        throw new TypeError(`${label} must start with 0x`);
+    }
+    const rawValue = value.slice(2);
+    if (rawValue.length % 2 !== 0) {
+        throw new TypeError(`${label} must have an even number of hex characters`);
+    }
+    if (!/^[0-9a-fA-F]*$/.test(rawValue)) {
+        throw new TypeError(`${label} must contain only hexadecimal characters`);
+    }
+    return value;
+}
+/**
+ * Returns the byte length of a validated hex string.
+ *
+ * @param value - Validated hex string.
+ * @returns Number of bytes represented by {@link value}.
+ *
+ * @internal
+ */
+function byteLength(value) {
+    return (value.length - 2) / 2;
+}
+export { aggregateCalls, decodeResults, encodeCalls };
+//# sourceMappingURL=index.js.map

package/dist/sdk/index.js.map

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

package/package.json

@@ -0,0 +1,56 @@
+{
+	"name": "@volga-sh/evm-ghostcall",
+	"version": "0.0.1",
+	"description": "Zero-deployment batching program and TypeScript SDK for CREATE-style eth_call requests.",
+	"license": "MIT",
+	"type": "module",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/volga-sh/ghostcall.git"
+	},
+	"bugs": {
+		"url": "https://github.com/volga-sh/ghostcall/issues"
+	},
+	"homepage": "https://github.com/volga-sh/ghostcall#readme",
+	"main": "./dist/sdk/index.js",
+	"types": "./dist/sdk/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/sdk/index.d.ts",
+			"import": "./dist/sdk/index.js"
+		}
+	},
+	"files": [
+		"dist/",
+		"src/Ghostcall.yul"
+	],
+	"sideEffects": false,
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"benchmark:limits": "node --disable-warning=ExperimentalWarning --experimental-strip-types scripts/benchmark-limits.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 .",
+		"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",
+		"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",
+		"typecheck": "tsc --project tsconfig.json"
+	},
+	"dependencies": {},
+	"devDependencies": {
+		"@biomejs/biome": "2.4.12",
+		"@safe-global/mock-contract": "4.1.0",
+		"ox": "0.9.6",
+		"@types/node": "24.3.1",
+		"typescript": "5.9.2"
+	}
+}

package/src/Ghostcall.yul

@@ -0,0 +1,153 @@
+object "Ghostcall" {
+    code {
+        // Ghostcall is an "initcode program" rather than a normal deployed contract.
+        //
+        // Mental model:
+        // 1. A normal CREATE transaction executes initcode.
+        // 2. That initcode usually builds runtime bytecode and RETURNs it.
+        // 3. Ghostcall uses the same mechanism, but inside eth_call.
+        // 4. Because this is only a simulation, nothing is deployed.
+        // 5. Whatever bytes this program RETURNs become the eth_call result.
+        //
+        // In other words: Ghostcall treats CREATE initcode like a tiny one-shot program that can
+        // batch external CALLs and return their raw results.
+        //
+        // The caller sends one byte blob:
+        //   <compiled ghostcall initcode><payload>
+        //
+        // The payload is appended directly after the compiled initcode. It is not normal calldata.
+        // This program reads that appended payload back out of its own code using CODECOPY.
+        //
+        // Payload layout:
+        //   repeated call entries
+        //
+        // Each call entry:
+        //    2 bytes  calldata length (big-endian uint16)
+        //   20 bytes  target address
+        //    N bytes  calldata
+        //
+        // Output layout:
+        //   repeated result entries
+        //
+        // Each result entry:
+        //    2 bytes  packed header
+        //             bit 15    = success flag from CALL
+        //             bits 0-14 = returndata length (big-endian uint15)
+        //    N bytes  returndata
+        //
+        // The program does the same high-level loop for every entry:
+        // - read the next calldata length + target
+        // - copy that call's calldata into memory
+        // - execute CALL(target, calldata)
+        // - append (success, returndata) to the response buffer
+        // - continue until the payload is fully consumed
+        //
+        // The SDK is expected to validate most caller-facing invariants ahead of time. The checks
+        // left in this file exist only to protect parser correctness and response packing.
+
+        // dataoffset("user_payload_anchor") is the byte offset of the empty data section declared at
+        // the bottom of this file. Because that data section is placed after the code, its offset is
+        // exactly "the first byte after the compiled initcode". That makes it the start of the
+        // caller-appended payload.
+        let payloadCursor := dataoffset("user_payload_anchor")
+
+        // Memory layout used by this program:
+        // - 0x00..0x1f: scratch space for reading the current entry header
+        // - 0x20..... : output buffer that will become the eth_call return value
+        //
+        // writePtr always points to "where the next result entry should be written".
+        let writePtr := 0x20
+
+        // Infinite loop with an explicit break once all payload bytes are consumed.
+        for {} 1 {} {
+            if eq(payloadCursor, codesize()) {
+                break
+            }
+
+            // Read the 22-byte fixed-size entry header into scratch memory starting at 0x0a rather
+            // than 0x00.
+            //
+            // Why 0x0a?
+            // - the header layout is [len(2)][target(20)]
+            // - placing the first header byte at memory offset 10 makes the 20-byte target end
+            //   exactly at byte 31 of the 32-byte word loaded from mload(0x00)
+            // - that means one mload gives us:
+            //     [10 zero bytes][2-byte len][20-byte target]
+            // - so shr(160, headerWord) yields calldata length
+            // - and headerWord itself already has the target in the low 20 bytes for CALL
+            //
+            // CODECOPY pads with zeros if it reads past the end of code. That is why we still need
+            // an explicit bounds check later: without it, a truncated entry would silently decode as
+            // zeros instead of failing.
+            codecopy(0x0a, payloadCursor, 0x16)
+
+            let headerWord := mload(0x00)
+
+            // The high 2 non-zero bytes hold the big-endian uint16 calldata length.
+            let calldataSize := shr(160, headerWord)
+            let nextCursor := add(add(payloadCursor, 0x16), calldataSize)
+
+            // Reject truncated entries. This single check covers both:
+            // - not enough bytes for the 22-byte header
+            // - not enough bytes for the calldata that the header claims exists
+            if gt(nextCursor, codesize()) {
+                revert(0x00, 0x00)
+            }
+
+            // The next result entry will be written at writePtr. Its first 2 bytes are the packed
+            // header, so the calldata scratch area can safely start immediately after that header.
+            let calldataPtr := add(writePtr, 0x02)
+
+            // Copy just this call's calldata into memory so CALL can read it.
+            codecopy(calldataPtr, add(payloadCursor, 0x16), calldataSize)
+
+            // Execute the external call with:
+            // - all remaining gas
+            // - zero ETH value
+            // - calldata in memory at calldataPtr
+            // - no output buffer yet, because we do not know returndata size in advance
+            //
+            // CALL only cares about the low 20 bytes of its address argument, so headerWord can be
+            // passed directly: the target is already sitting there after the 0x0a codecopy trick.
+            let success := call(gas(), headerWord, 0, calldataPtr, calldataSize, 0, 0)
+            let returndataSize := returndatasize()
+
+            // The packed result header has 15 returndata length bits; bit 15 is the success flag.
+            // Revert rather than letting oversized returndata collide with the success bit.
+            if gt(returndataSize, 0x7fff) {
+                revert(0x00, 0x00)
+            }
+
+            // Compute where the next result entry would begin after writing:
+            //   2-byte packed header + returndata bytes
+            let nextWritePtr := add(add(writePtr, 0x02), returndataSize)
+
+            // Intentionally do not enforce an aggregate response-size cap here. CREATE-style
+            // execution already treats returned bytes as would-be runtime code, so the active
+            // chain/client/RPC environment will reject oversized responses according to its own
+            // code-size policy. Keeping this uncapped lets the same Ghostcall initcode benefit from
+            // networks with larger limits, such as Monad's MIP-2:
+            // https://mips.monad.xyz/MIPS/MIP-2
+
+            // Write the packed 2-byte result header into the high 2 bytes of the 32-byte word at
+            // writePtr. The rest of that word does not matter because the return length is computed
+            // explicitly at the end.
+            mstore(writePtr, shl(240, or(shl(15, success), returndataSize)))
+
+            // Append the raw returndata bytes immediately after the 2-byte header.
+            returndatacopy(add(writePtr, 0x02), 0, returndataSize)
+
+            // Advance both cursors:
+            // - writePtr moves to the start of the next result entry
+            // - payloadCursor moves to the next input entry
+            writePtr := nextWritePtr
+            payloadCursor := nextCursor
+        }
+
+        // Return exactly the bytes that were written to the response buffer.
+        return(0x20, sub(writePtr, 0x20))
+
+    }
+
+    data "user_payload_anchor" hex""
+}