@volga-sh/evm-ghostcall 0.0.1 → 0.0.3

package/README.md

@@ -1,18 +1,25 @@
 # ghostcall
 
-`ghostcall` is a zero-deployment batching program for CREATE-style `eth_call`.
+`ghostcall` batches EVM blockchain reads without deployment dependencies.
 
-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.
+## Documentation
 
-The implementation lives in [`src/Ghostcall.yul`](src/Ghostcall.yul).
+The docs live at [ghostcall.volga.sh](https://ghostcall.volga.sh).
 
-## Quick example
+Start there for installation, examples, the API reference, protocol details, and endpoint limit notes.
+
+## Install
+
+```sh
+npm install @volga-sh/evm-ghostcall
+```
+
+## Quick Start
+
+This example uses viem for the EIP-1193-compatible client and ABI helpers. Install it with `npm install viem` if your app does not already use it.
 
 ```ts
-import { aggregateCalls } from "@volga-sh/evm-ghostcall";
+import { aggregateDecodedCalls } from "@volga-sh/evm-ghostcall";
 import {
 	createPublicClient,
 	decodeFunctionResult,
@@ -22,299 +29,55 @@ import {
 } 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({
+const erc20Abi = parseAbi(["function totalSupply() view returns (uint256)"]);
+
+const [totalSupply] = await aggregateDecodedCalls(client, [
+	{
+		to: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
+		data: encodeFunctionData({
+			abi: erc20Abi,
+			functionName: "totalSupply",
+		}),
+		decodeResult: (returnData) =>
+			decodeFunctionResult({
 				abi: erc20Abi,
-				functionName: "allowance",
-				args: [owner, spender],
+				functionName: "totalSupply",
+				data: returnData,
 			}),
-			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:
+See the [Getting Started guide](https://ghostcall.volga.sh/getting-started/) for a complete viem example with ABI encoding and decoding.
 
-```bash
-npm run benchmark:limits -- \
-  --rpc-url "$RPC_URL" \
-  --mode balances \
-  --token "$TOKEN_ADDRESS" \
-  --owner "$OWNER_ADDRESS"
-```
+## API
 
-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`.
+- `aggregateDecodedCalls()` sends a strict batch and returns decoded values.
+- `aggregateCalls()` sends a batch and returns raw `{ success, returnData }` entries.
+- `encodeCalls()` builds the CREATE-style `eth_call` data payload.
+- `decodeResults()` parses the packed ghostcall response.
 
-Useful options:
+Full reference: [API docs](https://ghostcall.volga.sh/api/).
 
-- `--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
+## Development
 
-## Install
-
-```bash
+```sh
 npm install
+npm run build:sdk
+npm run test
+npm run check
 ```
 
-## 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
+Docs are built with Astro Starlight:
 
-```bash
-npm test
+```sh
+npm run docs:dev
+npm run docs:build
 ```
 
-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.
+The repository is hosted at [github.com/volga-sh/ghostcall](https://github.com/volga-sh/ghostcall).

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

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

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

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

package/dist/sdk/generated/initcode.js

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

package/dist/sdk/index.d.ts

@@ -5,6 +5,14 @@
  * SDK does not accept byte arrays or ABI fragments.
  */
 type Hex = `0x${string}`;
+/**
+ * Hex-encoded RPC quantity prefixed with `0x`.
+ */
+type HexQuantity = `0x${string}`;
+/**
+ * Block reference accepted by the outer `eth_call`.
+ */
+type GhostcallBlockReference = string | number | bigint;
 /**
  * One Ghostcall subcall entry.
  */
@@ -35,39 +43,46 @@ type GhostcallAggregateCall = GhostcallCall & {
      * a call does not explicitly opt into failure.
      */
     allowFailure?: boolean;
+};
+/**
+ * One Ghostcall subcall entry for decoded aggregate results.
+ */
+type GhostcallDecodedCall<TResult = unknown> = GhostcallCall & {
     /**
-     * Optional decoder for this call's successful return data.
+     * Decodes this call's successful return data.
      *
      * This is intentionally a caller-provided function so the SDK stays independent
      * from ABI libraries while still letting callers plug in helpers such as
      * `decodeFunctionResult` from viem or ox.
      */
-    decodeResult?: GhostcallResultDecoder<unknown>;
+    decodeResult: GhostcallResultDecoder<TResult>;
 };
 /**
- * One Ghostcall aggregate subcall entry for decoded-results mode.
+ * One successful Ghostcall result entry.
  */
-type GhostcallDecodedAggregateCall<TResult = unknown> = GhostcallCall & {
+type GhostcallSuccessResult = {
     /**
-     * Decodes this call's successful return data.
+     * Indicates whether the underlying EVM `CALL` returned successfully.
+     *
+     * A `true` value means the target call returned successfully.
      */
-    decodeResult: GhostcallResultDecoder<TResult>;
+    success: true;
     /**
-     * Decoded-results mode is strict and does not return failed entries.
+     * Raw return data produced by the target call.
      */
-    allowFailure?: false;
+    returnData: Hex;
 };
 /**
- * One decoded Ghostcall result entry.
+ * One failed Ghostcall result entry.
  */
-type GhostcallResult = {
+type GhostcallFailedResult = {
     /**
      * Indicates whether the underlying EVM `CALL` returned successfully.
      *
      * A `false` value means the target call reverted or otherwise failed, but the
      * Ghostcall batch itself still completed successfully.
      */
-    success: boolean;
+    success: false;
     /**
      * Raw return data produced by the target call.
      *
@@ -76,46 +91,63 @@ type GhostcallResult = {
      */
     returnData: Hex;
 };
+/**
+ * One decoded Ghostcall result entry.
+ */
+type GhostcallResult = GhostcallSuccessResult | GhostcallFailedResult;
 /**
  * Function used by {@link aggregateCalls} to turn raw successful return data into
  * a caller-chosen value.
  */
-type GhostcallResultDecoder<TResult> = (returnData: Hex, entry: GhostcallResult, index: number) => TResult;
+type GhostcallResultDecoder<TResult> = (returnData: Hex, entry: GhostcallSuccessResult, index: number) => TResult;
 /**
- * One decoded aggregate result entry when a call provides `decodeResult`.
+ * Error thrown when a strict Ghostcall batch encounters a failed subcall.
  */
-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[]> = {
+declare class GhostcallSubcallError extends Error {
+    readonly index: number;
+    readonly call: GhostcallAggregateCall;
+    readonly result: GhostcallFailedResult;
+    constructor(index: number, call: GhostcallAggregateCall, result: GhostcallFailedResult);
+}
+type GhostcallDecodedResults<TCalls extends readonly GhostcallDecodedCall[]> = {
     -readonly [Index in keyof TCalls]: TCalls[Index] extends {
         decodeResult: GhostcallResultDecoder<infer TResult>;
     } ? TResult : never;
 };
-type GhostcallAggregateOptions = {
+type GhostcallEncodeOptions = {
+    /**
+     * Maximum allowed CREATE initcode size in bytes.
+     *
+     * This applies to the full request `data`, including bundled Ghostcall
+     * initcode and every encoded subcall entry.
+     *
+     * Defaults to Ethereum's EIP-3860 limit of `49,152` bytes.
+     */
+    maxInitcodeBytes?: number;
+};
+type GhostcallEthCallOptions = {
+    /**
+     * Optional `from` address for the outer `eth_call`.
+     */
+    from?: Hex;
+    /**
+     * Optional gas limit for the outer `eth_call`.
+     */
+    gas?: HexQuantity;
     /**
-     * Result shape returned by {@link aggregateCalls}.
+     * Optional block tag, hex quantity, or block number for the outer `eth_call`.
      *
-     * Defaults to `entries`, returning Ghostcall result entries. Set to `decoded`
-     * to return each call's decoded value directly.
+     * Decimal strings, numbers, and bigints are normalized to hex quantities.
+     * Defaults to `latest`.
      */
-    results?: "entries";
+    blockTag?: GhostcallBlockReference;
 };
-type GhostcallDecodedAggregateOptions = {
+type GhostcallAggregateOptions = GhostcallEncodeOptions & {
     /**
-     * Return each call's decoded value directly.
+     * Optional outer `eth_call` controls shared by {@link aggregateCalls} and
+     * {@link aggregateDecodedCalls}.
      */
-    results: "decoded";
+    ethCall?: GhostcallEthCallOptions;
 };
 /**
  * Minimal EIP-1193 provider shape used by the SDK.
@@ -134,9 +166,12 @@ type EIP1193ProviderWithRequestFn = {
  * by the compact binary payload for each subcall, so callers can pass it directly
  * as the `data` field of an `eth_call` request without supplying a `to` address.
  * Each encoded subcall entry uses the compact layout `[len(2)][target(20)][data]`.
+ * The bundled initcode assumes appended bytes follow this exact shape; this
+ * function is the supported boundary for producing well-formed Ghostcall payloads.
  *
  * @param calls - Ordered list of subcalls to execute. Each entry becomes one
  *                Ghostcall payload segment in the same order it appears here.
+ * @param options - Optional encoding controls.
  *
  * @returns Full CREATE payload consisting of the bundled Ghostcall initcode plus
  *          the encoded call list.
@@ -144,16 +179,18 @@ type EIP1193ProviderWithRequestFn = {
  * @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.
+ *                      configured initcode size limit.
  *
  * @example
  * const data = encodeCalls([
  *   {
- *     to: "0x1111111111111111111111111111111111111111",
- *     data: "0x70a08231000000000000000000000000aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+ *     // USDC on Ethereum mainnet: balanceOf(Binance 14)
+ *     to: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+ *     data: "0x70a0823100000000000000000000000028c6c06298d514db089934071355e5743bf21d60",
  *   },
  *   {
- *     to: "0x2222222222222222222222222222222222222222",
+ *     // WETH9 on Ethereum mainnet: totalSupply()
+ *     to: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
  *     data: "0x18160ddd",
  *   },
  * ]);
@@ -161,67 +198,98 @@ type EIP1193ProviderWithRequestFn = {
  * // Later:
  * // provider.request({ method: "eth_call", params: [{ data }, "latest"] })
  */
-declare function encodeCalls(calls: readonly GhostcallCall[]): Hex;
+declare function encodeCalls(calls: readonly GhostcallCall[], options?: GhostcallEncodeOptions): Hex;
 /**
  * Sends a Ghostcall batch with a CREATE-style `eth_call` and decodes the result.
  *
  * This is the provider-facing counterpart to {@link encodeCalls} and
  * {@link decodeResults}. It sends the bundled Ghostcall initcode as the `data`
- * field of `eth_call` without a `to` address, then returns decoded result entries
- * in the same order as the input calls.
+ * field of `eth_call` without a `to` address, then returns raw result entries
+ * in the same order as the input calls. Request bytes are built through
+ * {@link encodeCalls}, so SDK callers get the supported payload validation before
+ * the RPC request is sent.
  *
  * By default, any failed subcall makes this method reject. Set
  * `allowFailure: true` on a call to receive that failed entry in the returned
- * results instead. 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.
+ * results instead. Use {@link aggregateDecodedCalls} when you want a strict batch
+ * that returns decoded values directly. Use `options.ethCall` to forward `from`,
+ * `gas`, or `blockTag` to the outer `eth_call`.
  *
  * @param provider - EIP-1193-compatible provider with a `request` method.
  * @param calls - Ordered list of subcalls to execute.
- * @param options - Optional result-shape controls.
+ * @param options - Optional outer call and initcode controls.
  *
- * @returns Ordered decoded Ghostcall result entries.
+ * @returns Ordered Ghostcall result entries.
  *
  * @throws {TypeError} If inputs are not valid Ghostcall call entries or if the
  *                     provider returns a non-hex `eth_call` result.
- * @throws {RangeError} If the encoded CREATE payload exceeds protocol or 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.
+ * @throws {RangeError} If the encoded CREATE payload exceeds protocol or the
+ *                      configured CREATE initcode ceiling.
+ * @throws {GhostcallSubcallError} If a subcall fails without `allowFailure: true`.
+ * @throws {Error} If the response entry count does not match the request entry count.
  *
  * @example
  * const results = await aggregateCalls(provider, [
  *   {
- *     to: "0x1111111111111111111111111111111111111111",
- *     data: "0x70a08231000000000000000000000000aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
- *     decodeResult: (returnData) => decodeFunctionResult({
- *       abi: erc20Abi,
- *       functionName: "balanceOf",
- *       data: returnData,
- *     }),
+ *     // USDC on Ethereum mainnet: balanceOf(Binance 14)
+ *     to: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+ *     data: "0x70a0823100000000000000000000000028c6c06298d514db089934071355e5743bf21d60",
  *   },
  *   {
- *     to: "0x2222222222222222222222222222222222222222",
+ *     // WETH9 on Ethereum mainnet: totalSupply()
+ *     to: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
  *     data: "0x18160ddd",
- *     allowFailure: true,
  *   },
  * ]);
+ */
+declare function aggregateCalls(provider: EIP1193ProviderWithRequestFn, calls: readonly GhostcallAggregateCall[], options?: GhostcallAggregateOptions): Promise<GhostcallResult[]>;
+/**
+ * Sends a strict Ghostcall batch and decodes each successful result entry.
+ *
+ * This is the decoded counterpart to {@link aggregateCalls}. It sends the bundled
+ * Ghostcall initcode as the `data` field of `eth_call` without a `to` address,
+ * then runs each call's `decodeResult` callback over the successful return data in
+ * the same order as the input calls.
+ *
+ * `aggregateDecodedCalls` is always strict. Its TypeScript input shape requires a
+ * `decodeResult` callback on every call and does not accept `allowFailure`.
+ * Any failed subcall rejects with {@link GhostcallSubcallError}. Use
+ * {@link aggregateCalls} if you need raw failed entries. Use `options.ethCall`
+ * to forward `from`, `gas`, or `blockTag` to the outer `eth_call`.
+ *
+ * @param provider - EIP-1193-compatible provider with a `request` method.
+ * @param calls - Ordered list of strict decoded subcalls to execute.
+ * @param options - Optional outer call and initcode controls.
+ *
+ * @returns Ordered list of decoded values.
+ *
+ * @throws {TypeError} If inputs are not valid Ghostcall call entries or if the
+ *                     provider returns a non-hex `eth_call` result.
+ * @throws {RangeError} If the encoded CREATE payload exceeds protocol or the
+ *                      configured CREATE initcode ceiling.
+ * @throws {GhostcallSubcallError} If any subcall fails.
+ * @throws {Error} If the response entry count does not match the request entry count.
+ *
+ * @example
+ * const erc20Abi = parseAbi([
+ *   "function balanceOf(address account) view returns (uint256)",
+ * ]);
+ * const usdc = "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48";
+ * const owner = "0x28C6c06298d514Db089934071355E5743bf21d60";
  *
- * const [balance] = await aggregateCalls(provider, [
+ * const [balance] = await aggregateDecodedCalls(provider, [
  *   {
- *     to: "0x1111111111111111111111111111111111111111",
- *     data: "0x70a08231000000000000000000000000aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+ *     to: usdc,
+ *     data: "0x70a0823100000000000000000000000028c6c06298d514db089934071355e5743bf21d60",
  *     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>>;
+declare function aggregateDecodedCalls<const TCalls extends readonly GhostcallDecodedCall<unknown>[]>(provider: EIP1193ProviderWithRequestFn, calls: TCalls, options?: GhostcallAggregateOptions): Promise<GhostcallDecodedResults<TCalls>>;
 /**
  * Decodes the packed result blob returned by Ghostcall.
  *
@@ -249,6 +317,6 @@ declare function aggregateCalls<const TCalls extends readonly GhostcallDecodedAg
  * // ]
  */
 declare function decodeResults(data: Hex): GhostcallResult[];
-export type { EIP1193ProviderWithRequestFn, GhostcallAggregateCall, GhostcallAggregateOptions, GhostcallAggregateResult, GhostcallCall, GhostcallDecodedAggregateCall, GhostcallDecodedAggregateOptions, GhostcallDecodedResult, GhostcallDecodedResults, GhostcallResult, GhostcallResultDecoder, Hex, };
-export { aggregateCalls, decodeResults, encodeCalls };
+export type { EIP1193ProviderWithRequestFn, GhostcallAggregateCall, GhostcallAggregateOptions, GhostcallBlockReference, GhostcallCall, GhostcallDecodedCall, GhostcallDecodedResults, GhostcallEncodeOptions, GhostcallEthCallOptions, GhostcallFailedResult, GhostcallResult, GhostcallResultDecoder, GhostcallSuccessResult, Hex, HexQuantity, };
+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":"AAEA;;;;;GAKG;AACH,KAAK,GAAG,GAAG,KAAK,MAAM,EAAE,CAAC;AAEzB;;GAEG;AACH,KAAK,WAAW,GAAG,KAAK,MAAM,EAAE,CAAC;AAEjC;;GAEG;AACH,KAAK,uBAAuB,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAExD;;GAEG;AACH,KAAK,aAAa,GAAG;IACpB;;OAEG;IACH,EAAE,EAAE,GAAG,CAAC;IAER;;;;;OAKG;IACH,IAAI,EAAE,GAAG,CAAC;CACV,CAAC;AAEF;;;;;GAKG;AACH,KAAK,sBAAsB,GAAG,aAAa,GAAG;IAC7C;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF;;GAEG;AACH,KAAK,oBAAoB,CAAC,OAAO,GAAG,OAAO,IAAI,aAAa,GAAG;IAC9D;;;;;;OAMG;IACH,YAAY,EAAE,sBAAsB,CAAC,OAAO,CAAC,CAAC;CAC9C,CAAC;AAEF;;GAEG;AACH,KAAK,sBAAsB,GAAG;IAC7B;;;;OAIG;IACH,OAAO,EAAE,IAAI,CAAC;IAEd;;OAEG;IACH,UAAU,EAAE,GAAG,CAAC;CAChB,CAAC;AAEF;;GAEG;AACH,KAAK,qBAAqB,GAAG;IAC5B;;;;;OAKG;IACH,OAAO,EAAE,KAAK,CAAC;IAEf;;;;;OAKG;IACH,UAAU,EAAE,GAAG,CAAC;CAChB,CAAC;AAEF;;GAEG;AACH,KAAK,eAAe,GAAG,sBAAsB,GAAG,qBAAqB,CAAC;AAEtE;;;GAGG;AACH,KAAK,sBAAsB,CAAC,OAAO,IAAI,CACtC,UAAU,EAAE,GAAG,EACf,KAAK,EAAE,sBAAsB,EAC7B,KAAK,EAAE,MAAM,KACT,OAAO,CAAC;AAEb;;GAEG;AACH,cAAM,qBAAsB,SAAQ,KAAK;IACxC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;gBAGtC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,sBAAsB,EAC5B,MAAM,EAAE,qBAAqB;CAS9B;AAED,KAAK,uBAAuB,CAAC,MAAM,SAAS,SAAS,oBAAoB,EAAE,IAAI;IAC9E,CAAC,UAAU,KAAK,IAAI,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,SAAS;QACxD,YAAY,EAAE,sBAAsB,CAAC,MAAM,OAAO,CAAC,CAAC;KACpD,GACE,OAAO,GACP,KAAK;CACR,CAAC;AAEF,KAAK,sBAAsB,GAAG;IAC7B;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,KAAK,uBAAuB,GAAG;IAC9B;;OAEG;IACH,IAAI,CAAC,EAAE,GAAG,CAAC;IAEX;;OAEG;IACH,GAAG,CAAC,EAAE,WAAW,CAAC;IAElB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,uBAAuB,CAAC;CACnC,CAAC;AAEF,KAAK,yBAAyB,GAAG,sBAAsB,GAAG;IACzD;;;OAGG;IACH,OAAO,CAAC,EAAE,uBAAuB,CAAC;CAClC,CAAC;AAEF;;GAEG;AACH,KAAK,4BAA4B,GAAG;IACnC,OAAO,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACtE,CAAC;AAWF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,iBAAS,WAAW,CACnB,KAAK,EAAE,SAAS,aAAa,EAAE,EAC/B,OAAO,GAAE,sBAA2B,GAClC,GAAG,CAmCL;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,iBAAe,cAAc,CAC5B,QAAQ,EAAE,4BAA4B,EACtC,KAAK,EAAE,SAAS,sBAAsB,EAAE,EACxC,OAAO,CAAC,EAAE,yBAAyB,GACjC,OAAO,CAAC,eAAe,EAAE,CAAC,CAyC5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,iBAAe,qBAAqB,CACnC,KAAK,CAAC,MAAM,SAAS,SAAS,oBAAoB,CAAC,OAAO,CAAC,EAAE,EAE7D,QAAQ,EAAE,4BAA4B,EACtC,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,yBAAyB,GACjC,OAAO,CAAC,uBAAuB,CAAC,MAAM,CAAC,CAAC,CAQ1C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,iBAAS,aAAa,CAAC,IAAI,EAAE,GAAG,GAAG,eAAe,EAAE,CAsCnD;AAqKD,YAAY,EACX,4BAA4B,EAC5B,sBAAsB,EACtB,yBAAyB,EACzB,uBAAuB,EACvB,aAAa,EACb,oBAAoB,EACpB,uBAAuB,EACvB,sBAAsB,EACtB,uBAAuB,EACvB,qBAAqB,EACrB,eAAe,EACf,sBAAsB,EACtB,sBAAsB,EACtB,GAAG,EACH,WAAW,GACX,CAAC;AACF,OAAO,EACN,cAAc,EACd,qBAAqB,EACrB,aAAa,EACb,WAAW,EACX,qBAAqB,GACrB,CAAC"}

package/dist/sdk/index.js

@@ -1,9 +1,25 @@
 import { ghostcallInitcode } from "./generated/initcode.js";
+/**
+ * Error thrown when a strict Ghostcall batch encounters a failed subcall.
+ */
+class GhostcallSubcallError extends Error {
+    index;
+    call;
+    result;
+    constructor(index, call, result) {
+        super(`Ghostcall subcall ${index} failed`);
+        this.name = "GhostcallSubcallError";
+        this.index = index;
+        this.call = call;
+        this.result = result;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
 const addressHexLength = 40;
 const encodedHeaderHexLength = 4;
 const maxCalldataSize = 0xffff;
 const encodedCallHeaderSize = 0x16;
-const maxCreateInitcodeSize = 0xc000;
+const defaultMaxCreateInitcodeSize = 0xc000;
 const successFlagMask = 0x8000;
 const returnDataLengthMask = 0x7fff;
 const bundledInitcodeSize = byteLength(ghostcallInitcode);
@@ -15,9 +31,12 @@ const bundledInitcodeSize = byteLength(ghostcallInitcode);
  * by the compact binary payload for each subcall, so callers can pass it directly
  * as the `data` field of an `eth_call` request without supplying a `to` address.
  * Each encoded subcall entry uses the compact layout `[len(2)][target(20)][data]`.
+ * The bundled initcode assumes appended bytes follow this exact shape; this
+ * function is the supported boundary for producing well-formed Ghostcall payloads.
  *
  * @param calls - Ordered list of subcalls to execute. Each entry becomes one
  *                Ghostcall payload segment in the same order it appears here.
+ * @param options - Optional encoding controls.
  *
  * @returns Full CREATE payload consisting of the bundled Ghostcall initcode plus
  *          the encoded call list.
@@ -25,16 +44,18 @@ const bundledInitcodeSize = byteLength(ghostcallInitcode);
  * @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.
+ *                      configured initcode size limit.
  *
  * @example
  * const data = encodeCalls([
  *   {
- *     to: "0x1111111111111111111111111111111111111111",
- *     data: "0x70a08231000000000000000000000000aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+ *     // USDC on Ethereum mainnet: balanceOf(Binance 14)
+ *     to: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+ *     data: "0x70a0823100000000000000000000000028c6c06298d514db089934071355e5743bf21d60",
  *   },
  *   {
- *     to: "0x2222222222222222222222222222222222222222",
+ *     // WETH9 on Ethereum mainnet: totalSupply()
+ *     to: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
  *     data: "0x18160ddd",
  *   },
  * ]);
@@ -42,9 +63,13 @@ const bundledInitcodeSize = byteLength(ghostcallInitcode);
  * // Later:
  * // provider.request({ method: "eth_call", params: [{ data }, "latest"] })
  */
-function encodeCalls(calls) {
+function encodeCalls(calls, options = {}) {
     const encodedParts = [ghostcallInitcode.slice(2)];
+    const maxInitcodeBytes = resolveMaxInitcodeBytes(options.maxInitcodeBytes);
     let totalEncodedSize = bundledInitcodeSize;
+    if (totalEncodedSize > maxInitcodeBytes) {
+        throw new RangeError(`encoded Ghostcall initcode exceeds the ${maxInitcodeBytes}-byte CREATE initcode limit`);
+    }
     for (const [index, call] of calls.entries()) {
         assertAddress(call.to, `calls[${index}].to`);
         const calldata = assertHex(call.data, `calls[${index}].data`);
@@ -53,8 +78,8 @@ function encodeCalls(calls) {
             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`);
+        if (totalEncodedSize > maxInitcodeBytes) {
+            throw new RangeError(`encoded Ghostcall initcode exceeds the ${maxInitcodeBytes}-byte CREATE initcode limit`);
         }
         encodedParts.push(calldataSize.toString(16).padStart(4, "0"));
         encodedParts.push(call.to.slice(2));
@@ -62,54 +87,130 @@ function encodeCalls(calls) {
     }
     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;
+/**
+ * Sends a Ghostcall batch with a CREATE-style `eth_call` and decodes the result.
+ *
+ * This is the provider-facing counterpart to {@link encodeCalls} and
+ * {@link decodeResults}. It sends the bundled Ghostcall initcode as the `data`
+ * field of `eth_call` without a `to` address, then returns raw result entries
+ * in the same order as the input calls. Request bytes are built through
+ * {@link encodeCalls}, so SDK callers get the supported payload validation before
+ * the RPC request is sent.
+ *
+ * By default, any failed subcall makes this method reject. Set
+ * `allowFailure: true` on a call to receive that failed entry in the returned
+ * results instead. Use {@link aggregateDecodedCalls} when you want a strict batch
+ * that returns decoded values directly. Use `options.ethCall` to forward `from`,
+ * `gas`, or `blockTag` to the outer `eth_call`.
+ *
+ * @param provider - EIP-1193-compatible provider with a `request` method.
+ * @param calls - Ordered list of subcalls to execute.
+ * @param options - Optional outer call and initcode controls.
+ *
+ * @returns Ordered Ghostcall result entries.
+ *
+ * @throws {TypeError} If inputs are not valid Ghostcall call entries or if the
+ *                     provider returns a non-hex `eth_call` result.
+ * @throws {RangeError} If the encoded CREATE payload exceeds protocol or the
+ *                      configured CREATE initcode ceiling.
+ * @throws {GhostcallSubcallError} If a subcall fails without `allowFailure: true`.
+ * @throws {Error} If the response entry count does not match the request entry count.
+ *
+ * @example
+ * const results = await aggregateCalls(provider, [
+ *   {
+ *     // USDC on Ethereum mainnet: balanceOf(Binance 14)
+ *     to: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+ *     data: "0x70a0823100000000000000000000000028c6c06298d514db089934071355e5743bf21d60",
+ *   },
+ *   {
+ *     // WETH9 on Ethereum mainnet: totalSupply()
+ *     to: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
+ *     data: "0x18160ddd",
+ *   },
+ * ]);
+ */
+async function aggregateCalls(provider, calls, options) {
+    const resolvedOptions = options ?? {};
+    const data = encodeCalls(calls, resolvedOptions);
+    const ethCall = { data };
+    const blockTag = normalizeBlockTag(resolvedOptions.ethCall?.blockTag ?? "latest", "options.ethCall.blockTag");
+    if (resolvedOptions.ethCall?.from !== undefined) {
+        assertAddress(resolvedOptions.ethCall.from, "options.ethCall.from");
+        ethCall.from = resolvedOptions.ethCall.from;
+    }
+    if (resolvedOptions.ethCall?.gas !== undefined) {
+        ethCall.gas = assertHexQuantity(resolvedOptions.ethCall.gas, "options.ethCall.gas");
     }
-    const data = encodeCalls(calls);
     const result = await provider.request({
         method: "eth_call",
-        params: [{ data }, "latest"],
+        params: [ethCall, blockTag],
     });
     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`);
+        const call = calls[index];
+        if (!entry.success && call.allowFailure !== true) {
+            throw new GhostcallSubcallError(index, call, entry);
         }
     }
-    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 entries;
+}
+/**
+ * Sends a strict Ghostcall batch and decodes each successful result entry.
+ *
+ * This is the decoded counterpart to {@link aggregateCalls}. It sends the bundled
+ * Ghostcall initcode as the `data` field of `eth_call` without a `to` address,
+ * then runs each call's `decodeResult` callback over the successful return data in
+ * the same order as the input calls.
+ *
+ * `aggregateDecodedCalls` is always strict. Its TypeScript input shape requires a
+ * `decodeResult` callback on every call and does not accept `allowFailure`.
+ * Any failed subcall rejects with {@link GhostcallSubcallError}. Use
+ * {@link aggregateCalls} if you need raw failed entries. Use `options.ethCall`
+ * to forward `from`, `gas`, or `blockTag` to the outer `eth_call`.
+ *
+ * @param provider - EIP-1193-compatible provider with a `request` method.
+ * @param calls - Ordered list of strict decoded subcalls to execute.
+ * @param options - Optional outer call and initcode controls.
+ *
+ * @returns Ordered list of decoded values.
+ *
+ * @throws {TypeError} If inputs are not valid Ghostcall call entries or if the
+ *                     provider returns a non-hex `eth_call` result.
+ * @throws {RangeError} If the encoded CREATE payload exceeds protocol or the
+ *                      configured CREATE initcode ceiling.
+ * @throws {GhostcallSubcallError} If any subcall fails.
+ * @throws {Error} If the response entry count does not match the request entry count.
+ *
+ * @example
+ * const erc20Abi = parseAbi([
+ *   "function balanceOf(address account) view returns (uint256)",
+ * ]);
+ * const usdc = "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48";
+ * const owner = "0x28C6c06298d514Db089934071355E5743bf21d60";
+ *
+ * const [balance] = await aggregateDecodedCalls(provider, [
+ *   {
+ *     to: usdc,
+ *     data: "0x70a0823100000000000000000000000028c6c06298d514db089934071355e5743bf21d60",
+ *     decodeResult: (returnData) => decodeFunctionResult({
+ *       abi: erc20Abi,
+ *       functionName: "balanceOf",
+ *       data: returnData,
+ *     }),
+ *   },
+ * ]);
+ */
+async function aggregateDecodedCalls(provider, calls, options) {
+    const entries = await aggregateCalls(provider, calls, options);
+    return entries.map((entry, index) => {
+        const call = calls[index];
+        const successEntry = entry;
+        return call.decodeResult(successEntry.returnData, successEntry, index);
     });
-    return decodedEntries;
 }
 /**
  * Decodes the packed result blob returned by Ghostcall.
@@ -211,6 +312,80 @@ function assertHex(value, label) {
     }
     return value;
 }
+/**
+ * Validates that a value is an RPC hex quantity.
+ *
+ * @param value - Unknown input to validate.
+ * @param label - Field name used in thrown error messages.
+ * @returns The validated value narrowed to {@link HexQuantity}.
+ * @throws {TypeError} If the value is not a valid `0x`-prefixed quantity.
+ *
+ * @internal
+ */
+function assertHexQuantity(value, label) {
+    if (typeof value !== "string") {
+        throw new TypeError(`${label} must be a hex quantity string`);
+    }
+    if (!/^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;
+}
+/**
+ * Normalizes a block reference into the RPC shape expected by `eth_call`.
+ *
+ * @param value - Block reference to normalize.
+ * @param label - Field name used in thrown error messages.
+ * @returns Normalized block reference.
+ * @throws {TypeError} If the value is not a supported block reference.
+ *
+ * @internal
+ */
+function normalizeBlockTag(value, label) {
+    if (typeof value === "number") {
+        if (!Number.isSafeInteger(value) || value < 0) {
+            throw new TypeError(`${label} must be a non-negative safe integer, bigint, or non-empty string`);
+        }
+        return `0x${value.toString(16)}`;
+    }
+    if (typeof value === "bigint") {
+        if (value < 0n) {
+            throw new TypeError(`${label} must be a non-negative safe integer, bigint, or non-empty string`);
+        }
+        return `0x${value.toString(16)}`;
+    }
+    if (typeof value !== "string" || value.length === 0) {
+        throw new TypeError(`${label} must be a non-negative safe integer, bigint, or non-empty string`);
+    }
+    if (/^-?[0-9]+$/.test(value)) {
+        if (value.startsWith("-")) {
+            throw new TypeError(`${label} must be a non-negative safe integer, bigint, or non-empty string`);
+        }
+        return `0x${BigInt(value).toString(16)}`;
+    }
+    if (value.startsWith("0x") || value.startsWith("0X")) {
+        return assertHexQuantity(`0x${value.slice(2)}`, label);
+    }
+    return value;
+}
+/**
+ * Resolves the active CREATE initcode ceiling.
+ *
+ * @param value - Optional caller override.
+ * @returns Active initcode ceiling in bytes.
+ * @throws {TypeError} If the override is not a non-negative safe integer.
+ *
+ * @internal
+ */
+function resolveMaxInitcodeBytes(value) {
+    if (value === undefined) {
+        return defaultMaxCreateInitcodeSize;
+    }
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new TypeError("options.maxInitcodeBytes must be a non-negative safe integer");
+    }
+    return value;
+}
 /**
  * Returns the byte length of a validated hex string.
  *
@@ -222,5 +397,5 @@ function assertHex(value, label) {
 function byteLength(value) {
     return (value.length - 2) / 2;
 }
-export { aggregateCalls, decodeResults, encodeCalls };
+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,7 +1,7 @@
 {
 	"name": "@volga-sh/evm-ghostcall",
-	"version": "0.0.1",
-	"description": "Zero-deployment batching program and TypeScript SDK for CREATE-style eth_call requests.",
+	"version": "0.0.3",
+	"description": "Batch EVM blockchain reads without deployment dependencies.",
 	"license": "MIT",
 	"type": "module",
 	"repository": {
@@ -11,7 +11,7 @@
 	"bugs": {
 		"url": "https://github.com/volga-sh/ghostcall/issues"
 	},
-	"homepage": "https://github.com/volga-sh/ghostcall#readme",
+	"homepage": "https://ghostcall.volga.sh",
 	"main": "./dist/sdk/index.js",
 	"types": "./dist/sdk/index.d.ts",
 	"exports": {
@@ -34,6 +34,9 @@
 		"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",
 		"check:sdk:initcode": "git diff --exit-code -- src/sdk/generated/initcode.ts",
 		"format": "biome format --write .",
 		"format:check": "biome format .",

package/src/Ghostcall.yul

@@ -42,8 +42,9 @@ object "Ghostcall" {
         // - 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.
+        // The SDK is expected to validate caller-facing input invariants ahead of time. The only
+        // top-level check left here protects response packing, because returndata size is learned
+        // from the EVM after each CALL.
 
         // 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
@@ -52,51 +53,34 @@ object "Ghostcall" {
         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
+        // - 0x00..writePtr: finalized output buffer that will become the eth_call return value
+        // - writePtr..writePtr+0x1f: scratch space for reading the current entry header
         //
-        // 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
+        // writePtr always points to where the next result entry starts. The entry's memory is
+        // scratch until CALL completes, then the packed result overwrites that same region.
+        let writePtr := 0x00
+
+        // Process entries until the cursor reaches the end of the CREATE payload. SDK-generated
+        // payloads always land exactly on codesize(); raw malformed trailing bytes are outside the
+        // supported boundary and are not checked here.
+        for {} lt(payloadCursor, codesize()) {} {
+            // Read the 22-byte fixed-size entry header into scratch memory at writePtr.
             //
-            // 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)
+            // The header layout is [len(2)][target(20)]. One mload gives us:
+            //   [2-byte len][20-byte target][10 trailing bytes]
+            codecopy(writePtr, payloadCursor, 0x16)
 
-            let headerWord := mload(0x00)
+            let headerWord := mload(writePtr)
 
-            // 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)
+            // The high 2 bytes hold the big-endian uint16 calldata length. The target occupies the
+            // next 20 bytes, so shr(80, headerWord) yields the address for CALL.
+            let calldataSize := shr(240, headerWord)
 
-            // 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)
+            // Put calldata after the 22-byte input header scratch. The returned entry later uses
+            // only writePtr..writePtr+0x01 for its packed header and writePtr+0x02 onward for
+            // returndata, so this staging area can be safely overwritten after CALL.
+            let calldataPtr := add(writePtr, 0x16)
+            let returndataPtr := add(writePtr, 0x02)
 
             // Copy just this call's calldata into memory so CALL can read it.
             codecopy(calldataPtr, add(payloadCursor, 0x16), calldataSize)
@@ -107,21 +91,15 @@ object "Ghostcall" {
             // - 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 success := call(gas(), shr(80, 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) {
+            if shr(15, returndataSize) {
                 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
@@ -135,17 +113,17 @@ object "Ghostcall" {
             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)
+            returndatacopy(returndataPtr, 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
+            writePtr := add(returndataPtr, returndataSize)
+            payloadCursor := add(payloadCursor, add(0x16, calldataSize))
         }
 
         // Return exactly the bytes that were written to the response buffer.
-        return(0x20, sub(writePtr, 0x20))
+        return(0x00, writePtr)
 
     }