@pushchain/core 6.0.24 → 6.0.26

package/src/lib/push-client/push-client.d.ts

@@ -5,12 +5,15 @@ import { TxBody, TxRaw } from 'cosmjs-types/cosmos/tx/v1beta1/tx';
 import { DeliverTxResponse } from '@cosmjs/stargate';
 import { QueryGetUniversalTxResponse } from '../generated/uexecutor/v1/query';
 import { QueryGetUniversalTxResponseV2 } from '../generated/uexecutor/v2/query';
+import { QueryReadsByTxResponse, QueryUniversalReadResponse } from '../generated/ucallback/v1';
 import { EvmClient } from '../vm-client/evm-client';
 import { PushClientOptions } from './push-client.types';
 import { TxResponse } from '../vm-client/vm-client.types';
 export declare class PushClient extends EvmClient {
-    /** Gas limit for Cosmos transactions on Push Chain */
-    private static readonly COSMOS_GAS_LIMIT;
+    /** Conservative SDK ceiling and fallback for gasless Cosmos transactions. */
+    private static readonly DEFAULT_COSMOS_GAS_LIMIT;
+    private static readonly GASLESS_GAS_LIMIT_CACHE_TTL_MS;
+    private static readonly MSG_EXECUTE_PAYLOAD_TYPE_URL;
     pushChainInfo: {
         chainId: string;
         vm: import("../constants/enums").VM;
@@ -42,6 +45,7 @@ export declare class PushClient extends EvmClient {
     private readonly ephemeralKey;
     private readonly ephemeralAccount;
     private currentRpcIndex;
+    private gaslessGasLimitCache?;
     /**
      * Archive (full-history) endpoints. History-sensitive reads fall back from
      * the prune RPC to these on a pruned-history miss. Resolved from the chain's
@@ -50,6 +54,13 @@ export declare class PushClient extends EvmClient {
      */
     private readonly archiveTendermintRpc;
     private readonly archivePublicClient?;
+    /**
+     * Prune endpoints with transport retries off, raced against the archive. A
+     * receipt miss on the prune node answers -32002 "Requested resource not
+     * available" after ~8 s (measured on Donut 2026-09-23), and the shared
+     * client's `http({ retryCount: 5 })` would retry that on top.
+     */
+    private readonly pruneProbeClient?;
     constructor(clientOptions: PushClientOptions);
     /**
      * Executes an operation with automatic fallback to next RPC endpoint on failure.
@@ -93,11 +104,40 @@ export declare class PushClient extends EvmClient {
      * In prod, signer should be passed in instead.
      */
     signCosmosTx(txBody: TxBody): Promise<TxRaw>;
+    private resolveCosmosGasLimit;
     broadcastCosmosTx(txRaw: TxRaw): Promise<DeliverTxResponse>;
     /**
      * Queries Push Chain's uexecutor gRPC service for a UniversalTx by its ID.
      */
     getUniversalTxById(id: string): Promise<QueryGetUniversalTxResponse>;
+    /**
+     * Queries x/ucallback for one cross-chain read by its requestId (0x-prefixed uint256 hex).
+     *
+     * Current-state query — an absent `read` is a real "does not exist", so there is
+     * deliberately no archive fallback (see getUniversalTxByIdV2 for the rationale).
+     */
+    getUniversalRead(requestId: string): Promise<QueryUniversalReadResponse>;
+    /**
+     * Cosmos `block_results` for one height, raw over the Tendermint HTTP RPC. Push Chain
+     * runs CometBFT 0.38 and emits `finalize_block_events`, which the cosmjs 0.33 decoders
+     * still drop (they only read `end_block_events`) — hence the direct call. This is the
+     * only place the EndBlocker's work is visible: read-state expiry runs there and leaves
+     * no EVM-indexed tx or receipt. Attribute values are plain strings.
+     */
+    getBlockResultEvents(height: number): Promise<readonly {
+        type: string;
+        attributes: readonly {
+            key: string;
+            value: string;
+        }[];
+    }[]>;
+    /**
+     * Queries x/ucallback for every read a Push transaction requested. One tx can emit
+     * several ReadRequested logs; this reassembles that batch. The node keys on the exact
+     * lowercase 0x hash, which is what the SDK's own tx responses carry — verified for
+     * both EOA and UEA-originated requests.
+     */
+    getReadsByTx(txHash: string): Promise<QueryReadsByTxResponse>;
     /**
      * Queries Push Chain's uexecutor v2 gRPC service for a UniversalTx by its ID.
      * V2 returns expanded OutboundTx fields and repeated outbound_tx array.

package/src/lib/push-client/push-client.js

@@ -8,6 +8,7 @@ const proto_signing_1 = require("@cosmjs/proto-signing");
 const stargate_1 = require("@cosmjs/stargate");
 const query_1 = require("../generated/uexecutor/v1/query");
 const query_2 = require("../generated/uexecutor/v2/query");
+const v1_1 = require("../generated/ucallback/v1");
 const crypto_1 = require("@cosmjs/crypto");
 const tendermint_rpc_1 = require("@cosmjs/tendermint-rpc");
 const auth_1 = require("cosmjs-types/cosmos/auth/v1beta1/auth");
@@ -24,13 +25,21 @@ function pushNetworkToChain(network) {
         return enums_1.CHAIN.PUSH_TESTNET_DONUT;
     return enums_1.CHAIN.PUSH_LOCALNET;
 }
+/** ABCI code 22 / gRPC NotFound from x/ucallback — "no read request with id …: key not found". */
+function isUcallbackNotFound(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return /\(22\)|code = NotFound|key not found/i.test(msg);
+}
 class PushClient extends evm_client_1.EvmClient {
-    /** Gas limit for Cosmos transactions on Push Chain */
-    static COSMOS_GAS_LIMIT = 100000000000;
+    /** Conservative SDK ceiling and fallback for gasless Cosmos transactions. */
+    static DEFAULT_COSMOS_GAS_LIMIT = 100_000_000;
+    static GASLESS_GAS_LIMIT_CACHE_TTL_MS = 60_000;
+    static MSG_EXECUTE_PAYLOAD_TYPE_URL = '/uexecutor.v1.MsgExecutePayload';
     pushChainInfo;
     ephemeralKey;
     ephemeralAccount;
     currentRpcIndex = 0;
+    gaslessGasLimitCache;
     /**
      * Archive (full-history) endpoints. History-sensitive reads fall back from
      * the prune RPC to these on a pruned-history miss. Resolved from the chain's
@@ -39,6 +48,13 @@ class PushClient extends evm_client_1.EvmClient {
      */
     archiveTendermintRpc;
     archivePublicClient;
+    /**
+     * Prune endpoints with transport retries off, raced against the archive. A
+     * receipt miss on the prune node answers -32002 "Requested resource not
+     * available" after ~8 s (measured on Donut 2026-09-23), and the shared
+     * client's `http({ retryCount: 5 })` would retry that on top.
+     */
+    pruneProbeClient;
     constructor(clientOptions) {
         const pushChainKey = pushNetworkToChain(clientOptions.network);
         const chain = clientOptions.chain ?? (0, chain_1.getPushViemChain)(pushChainKey);
@@ -57,6 +73,10 @@ class PushClient extends evm_client_1.EvmClient {
                 chain,
                 transport: (0, viem_1.fallback)(archiveEvmUrls.map((url) => (0, viem_1.http)(url, { retryCount: 5, retryDelay: 500 }))),
             });
+            this.pruneProbeClient = (0, viem_1.createPublicClient)({
+                chain,
+                transport: (0, viem_1.fallback)(clientOptions.rpcUrls.map((url) => (0, viem_1.http)(url, { retryCount: 0 }))),
+            });
         }
         this.ephemeralKey = (0, accounts_1.generatePrivateKey)();
         this.ephemeralAccount = (0, accounts_1.privateKeyToAccount)(this.ephemeralKey);
@@ -215,6 +235,7 @@ class PushClient extends evm_client_1.EvmClient {
             const status = await tmClient.status();
             const chainId = status.nodeInfo.network;
             const queryClient = stargate_1.QueryClient.withExtensions(tmClient, stargate_1.setupAuthExtension);
+            const cosmosGasLimit = await this.resolveCosmosGasLimit(txBody, queryClient, chainId);
             let baseAccount = null;
             try {
                 const accountResp = await queryClient.auth.account(sender);
@@ -245,7 +266,7 @@ class PushClient extends evm_client_1.EvmClient {
                     pubkey: pubkeyEncoded,
                     sequence: baseAccount ? Number(baseAccount.sequence) : 0,
                 },
-            ], [], PushClient.COSMOS_GAS_LIMIT, undefined, undefined);
+            ], [], cosmosGasLimit, undefined, undefined);
             const txBodyBytes = tx_2.TxBody.encode(txBody).finish();
             const signDoc = (0, proto_signing_1.makeSignDoc)(txBodyBytes, authInfoBytes, chainId, baseAccount ? Number(baseAccount.accountNumber) : 0);
             const digest = (0, viem_1.keccak256)(tx_2.SignDoc.encode(signDoc).finish());
@@ -257,6 +278,42 @@ class PushClient extends evm_client_1.EvmClient {
             });
         }, 'signCosmosTx');
     }
+    async resolveCosmosGasLimit(txBody, queryClient, chainId) {
+        const isGaslessExecutePayload = txBody.messages.length > 0 &&
+            txBody.messages.every(({ typeUrl }) => typeUrl === PushClient.MSG_EXECUTE_PAYLOAD_TYPE_URL);
+        if (!isGaslessExecutePayload) {
+            return PushClient.DEFAULT_COSMOS_GAS_LIMIT;
+        }
+        const cached = this.gaslessGasLimitCache;
+        if (cached?.chainId === chainId && cached.expiresAt > Date.now()) {
+            return cached.gasLimit;
+        }
+        try {
+            const rpc = (0, stargate_1.createProtobufRpcClient)(queryClient);
+            const request = query_1.QueryParamsRequest.fromPartial({});
+            const responseBytes = await rpc.request('uexecutor.v1.Query', 'Params', query_1.QueryParamsRequest.encode(request).finish());
+            const response = query_1.QueryParamsResponse.decode(responseBytes);
+            const onChainMaximum = response.params?.maxGaslessTxGas ?? BigInt(0);
+            if (onChainMaximum > BigInt(0)) {
+                const selected = onChainMaximum < BigInt(PushClient.DEFAULT_COSMOS_GAS_LIMIT)
+                    ? onChainMaximum
+                    : BigInt(PushClient.DEFAULT_COSMOS_GAS_LIMIT);
+                const gasLimit = Number(selected);
+                if (Number.isSafeInteger(gasLimit) && gasLimit > 0) {
+                    this.gaslessGasLimitCache = {
+                        chainId,
+                        gasLimit,
+                        expiresAt: Date.now() + PushClient.GASLESS_GAS_LIMIT_CACHE_TTL_MS,
+                    };
+                    return gasLimit;
+                }
+            }
+        }
+        catch {
+            // Older/unavailable query endpoints fall back to the current safe cap.
+        }
+        return PushClient.DEFAULT_COSMOS_GAS_LIMIT;
+    }
     async broadcastCosmosTx(txRaw) {
         return this.executeWithRpcFallback(async (rpcUrl) => {
             const client = await stargate_1.StargateClient.connect(rpcUrl);
@@ -276,6 +333,73 @@ class PushClient extends evm_client_1.EvmClient {
             return query_1.QueryGetUniversalTxResponse.decode(responseBytes);
         }, 'getUniversalTxById');
     }
+    /**
+     * Queries x/ucallback for one cross-chain read by its requestId (0x-prefixed uint256 hex).
+     *
+     * Current-state query — an absent `read` is a real "does not exist", so there is
+     * deliberately no archive fallback (see getUniversalTxByIdV2 for the rationale).
+     */
+    async getUniversalRead(requestId) {
+        const id = requestId.toLowerCase();
+        return this.executeWithRpcFallback(async (rpcUrl) => {
+            const tmClient = await tendermint_rpc_1.Tendermint34Client.connect(rpcUrl);
+            const queryClient = new stargate_1.QueryClient(tmClient);
+            const rpc = (0, stargate_1.createProtobufRpcClient)(queryClient);
+            const request = v1_1.QueryUniversalReadRequest.fromPartial({ requestId: id });
+            try {
+                const responseBytes = await rpc.request(v1_1.UCALLBACK_QUERY_SERVICE, 'UniversalRead', v1_1.QueryUniversalReadRequest.encode(request).finish());
+                return v1_1.QueryUniversalReadResponse.decode(responseBytes);
+            }
+            catch (err) {
+                // The node answers an unknown id with ABCI code 22 (sdk NotFound), which cosmjs
+                // throws. That is a deterministic miss, not a transport failure — classify it
+                // here so the RPC fallback does not retry it on every endpoint.
+                if (isUcallbackNotFound(err))
+                    return v1_1.QueryUniversalReadResponse.fromPartial({});
+                throw err;
+            }
+        }, 'getUniversalRead');
+    }
+    /**
+     * Cosmos `block_results` for one height, raw over the Tendermint HTTP RPC. Push Chain
+     * runs CometBFT 0.38 and emits `finalize_block_events`, which the cosmjs 0.33 decoders
+     * still drop (they only read `end_block_events`) — hence the direct call. This is the
+     * only place the EndBlocker's work is visible: read-state expiry runs there and leaves
+     * no EVM-indexed tx or receipt. Attribute values are plain strings.
+     */
+    async getBlockResultEvents(height) {
+        // Prune nodes drop old heights ("height N is not available"); the archive keeps them.
+        return this.executeWithArchiveFallback(async (rpcUrl) => {
+            const url = `${rpcUrl.replace(/\/+$/, '')}/block_results?height=${height}`;
+            const res = await fetch(url);
+            // CometBFT answers a pruned height with HTTP 500 plus a JSON-RPC error. Surface that
+            // error so it reads as a definite miss (→ archive), not a transient HTTP failure to retry.
+            const body = (await res.json().catch(() => undefined));
+            if (body?.error)
+                throw new Error(`block_results ${height}: ${body.error.data ?? body.error.message ?? 'error'}`);
+            if (!res.ok || !body)
+                throw new Error(`HTTP request failed: ${res.status} ${url}`);
+            const events = body.result?.finalize_block_events ?? body.result?.end_block_events ?? [];
+            return events;
+        }, 'getBlockResultEvents', () => false);
+    }
+    /**
+     * Queries x/ucallback for every read a Push transaction requested. One tx can emit
+     * several ReadRequested logs; this reassembles that batch. The node keys on the exact
+     * lowercase 0x hash, which is what the SDK's own tx responses carry — verified for
+     * both EOA and UEA-originated requests.
+     */
+    async getReadsByTx(txHash) {
+        const hash = txHash.toLowerCase();
+        return this.executeWithRpcFallback(async (rpcUrl) => {
+            const tmClient = await tendermint_rpc_1.Tendermint34Client.connect(rpcUrl);
+            const queryClient = new stargate_1.QueryClient(tmClient);
+            const rpc = (0, stargate_1.createProtobufRpcClient)(queryClient);
+            const request = v1_1.QueryReadsByTxRequest.fromPartial({ txHash: hash });
+            const responseBytes = await rpc.request(v1_1.UCALLBACK_QUERY_SERVICE, 'ReadsByTx', v1_1.QueryReadsByTxRequest.encode(request).finish());
+            return v1_1.QueryReadsByTxResponse.decode(responseBytes);
+        }, 'getReadsByTx');
+    }
     /**
      * Queries Push Chain's uexecutor v2 gRPC service for a UniversalTx by its ID.
      * V2 returns expanded OutboundTx fields and repeated outbound_tx array.
@@ -356,7 +480,10 @@ class PushClient extends evm_client_1.EvmClient {
                 throw error;
             const archiveClient = this.archivePublicClient;
             const tx = await archiveClient.getTransaction({ hash: txHash });
-            const wait = async (confirmations = 1) => archiveClient.waitForTransactionReceipt({ hash: txHash, confirmations });
+            const wait = async (confirmations = 1) => archiveClient.waitForTransactionReceipt({
+                hash: txHash,
+                confirmations,
+            });
             return { ...tx, wait };
         }
     }
@@ -366,17 +493,29 @@ class PushClient extends evm_client_1.EvmClient {
      * Prune first; on not-found, retry the archive EVM client if configured.
      */
     async getTransactionReceiptWithArchiveFallback(txHash) {
-        try {
-            return await this.publicClient.getTransactionReceipt({ hash: txHash });
-        }
-        catch (error) {
-            if (!this.hasArchiveEvm)
-                throw error;
-            return this.archivePublicClient.getTransactionReceipt({
-                hash: txHash,
-            });
+        if (!this.hasArchiveEvm || !this.pruneProbeClient) {
+            return this.publicClient.getTransactionReceipt({ hash: txHash });
         }
+        // Race prune and archive; the first receipt wins. A pruned receipt costs one
+        // archive round trip, a fresh one the prune round trip (if the archive lags).
+        const prune = this.pruneProbeClient.getTransactionReceipt({ hash: txHash });
+        const archive = this.archivePublicClient.getTransactionReceipt({
+            hash: txHash,
+        });
+        return firstFulfilled([archive, prune]);
     }
 }
 exports.PushClient = PushClient;
+/** First promise to resolve; if all reject, the last rejection. */
+function firstFulfilled(promises) {
+    return new Promise((resolve, reject) => {
+        let pending = promises.length;
+        for (const p of promises) {
+            p.then(resolve, (error) => {
+                if (--pending === 0)
+                    reject(error);
+            });
+        }
+    });
+}
 //# sourceMappingURL=push-client.js.map

package/src/lib/read-state/budget.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Gas price assumed when the chain reports 0 (dev chains). Donut charges 1 gwei per
+ * gas on module fulfil txs (verified: 118,289 gas → 118,289 × 10⁹ wei burned).
+ */
+export declare const MIN_CALLBACK_BUDGET_GAS_PRICE = 1000000000n;
+/**
+ * Size the callback budget escrowed on top of the protocol fee.
+ *
+ *   msg.value = protocolFee + callbackBudget
+ *
+ * The node refuses to fulfil a read whose budget cannot cover its callback
+ * ("callback budget too small") and lets it expire with the fee already spent, so a
+ * zero or thin budget is a guaranteed loss. This errs high by `buffer`; whatever the
+ * callback does not burn is pushed back to `refundTo` at settlement.
+ */
+export declare function sizeCallbackBudget(callbackGasLimit: bigint, pushGasPrice: bigint, buffer?: number): bigint;

package/src/lib/read-state/budget.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MIN_CALLBACK_BUDGET_GAS_PRICE = void 0;
+exports.sizeCallbackBudget = sizeCallbackBudget;
+const read_state_1 = require("../constants/read-state");
+const errors_1 = require("./errors");
+/**
+ * Gas price assumed when the chain reports 0 (dev chains). Donut charges 1 gwei per
+ * gas on module fulfil txs (verified: 118,289 gas → 118,289 × 10⁹ wei burned).
+ */
+exports.MIN_CALLBACK_BUDGET_GAS_PRICE = 1000000000n;
+/**
+ * Size the callback budget escrowed on top of the protocol fee.
+ *
+ *   msg.value = protocolFee + callbackBudget
+ *
+ * The node refuses to fulfil a read whose budget cannot cover its callback
+ * ("callback budget too small") and lets it expire with the fee already spent, so a
+ * zero or thin budget is a guaranteed loss. This errs high by `buffer`; whatever the
+ * callback does not burn is pushed back to `refundTo` at settlement.
+ */
+function sizeCallbackBudget(callbackGasLimit, pushGasPrice, buffer = read_state_1.CALLBACK_BUDGET_BUFFER) {
+    if (callbackGasLimit <= 0n)
+        throw new errors_1.InvalidReadQueryError('callbackGasLimit must be > 0');
+    if (!Number.isInteger(buffer) || buffer < 1)
+        throw new errors_1.InvalidReadQueryError('budget buffer must be an integer ≥ 1');
+    const price = pushGasPrice > 0n ? pushGasPrice : exports.MIN_CALLBACK_BUDGET_GAS_PRICE;
+    const budget = callbackGasLimit * price * BigInt(buffer);
+    // cannot be zero by construction, but the invariant is worth stating
+    return budget > 0n ? budget : 1n;
+}
+//# sourceMappingURL=budget.js.map

package/src/lib/read-state/destination.d.ts

@@ -0,0 +1,12 @@
+import type { ReadDestination, ResolvedDestination } from './read-state.types';
+/**
+ * Split a destination into the pieces the contract, the oracle and the node use.
+ *
+ * - `ReadSpec.account.chainNamespace` / `chainId` are the two halves.
+ * - `UniversalCore.chainHeightByChainNamespace` is keyed by the JOINED `caip2`.
+ * - The node routes on `chainNamespace + ":" + chainId`.
+ *
+ * Passing the joined form as the namespace would produce `eip155:1:1` on the node,
+ * so it is rejected here.
+ */
+export declare function resolveDestination(dest: ReadDestination): ResolvedDestination;

package/src/lib/read-state/destination.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveDestination = resolveDestination;
+const read_state_1 = require("../constants/read-state");
+const errors_1 = require("./errors");
+const KNOWN = new Set(Object.values(read_state_1.READ_NAMESPACE));
+/**
+ * Split a destination into the pieces the contract, the oracle and the node use.
+ *
+ * - `ReadSpec.account.chainNamespace` / `chainId` are the two halves.
+ * - `UniversalCore.chainHeightByChainNamespace` is keyed by the JOINED `caip2`.
+ * - The node routes on `chainNamespace + ":" + chainId`.
+ *
+ * Passing the joined form as the namespace would produce `eip155:1:1` on the node,
+ * so it is rejected here.
+ */
+function resolveDestination(dest) {
+    let chainNamespace;
+    let chainId;
+    if ('chain' in dest) {
+        const idx = dest.chain.indexOf(':');
+        if (idx <= 0) {
+            throw new errors_1.UnsupportedReadDestinationError(`chain is not CAIP-2: ${dest.chain}`);
+        }
+        chainNamespace = dest.chain.slice(0, idx);
+        chainId = dest.chain.slice(idx + 1);
+    }
+    else {
+        chainNamespace = dest.chainNamespace;
+        chainId = dest.chainId;
+    }
+    if (!chainNamespace || !chainId) {
+        throw new errors_1.UnsupportedReadDestinationError('destination needs both chainNamespace and chainId');
+    }
+    if (chainNamespace.includes(':')) {
+        throw new errors_1.UnsupportedReadDestinationError(`chainNamespace must be the bare namespace, not CAIP-2: ${chainNamespace}`, { hint: 'Pass { chainNamespace: "eip155", chainId: "1" } or { chain: CHAIN.X }.' });
+    }
+    if (!KNOWN.has(chainNamespace)) {
+        throw new errors_1.UnsupportedReadDestinationError(`unsupported read namespace: ${chainNamespace}`, {
+            destination: `${chainNamespace}:${chainId}`,
+            hint: `Supported: ${[...KNOWN].join(', ')}`,
+        });
+    }
+    return {
+        chainNamespace,
+        chainId,
+        caip2: `${chainNamespace}:${chainId}`,
+        namespace: chainNamespace,
+    };
+}
+//# sourceMappingURL=destination.js.map

package/src/lib/read-state/envelopes/evm.d.ts

@@ -0,0 +1,24 @@
+import { type Hex } from 'viem';
+import type { EncodedReadQuery, EvmReadQuery } from '../read-state.types';
+/** `universalClient/externalchains/evm/read_envelope.go` — evmQueryType. */
+export declare const EVM_QUERY_TYPE: {
+    readonly ACCOUNT_BALANCE: 0;
+    readonly CONTRACT_CALL: 1;
+    readonly STORAGE_SLOT: 2;
+};
+/** Normalise a storage slot (hex or bigint) to bytes32. */
+export declare function toStorageSlot(slot: Hex | bigint): Hex;
+/**
+ * Encode an `eip155` read query. Pure — `blockNumber` is the pinned destination
+ * height and is also mirrored into `ReadSpec.blockNumber` by the spec builder.
+ */
+export declare function encodeEvmQueryEnvelope(query: EvmReadQuery, options: {
+    blockNumber: bigint;
+}): EncodedReadQuery;
+/** Decode an envelope with the exact tuple shape the validator uses. */
+export declare function decodeEvmQueryEnvelope(encoded: Hex): {
+    queryType: number;
+    refType: number;
+    blockNumber: bigint;
+    payload: Hex;
+};

package/src/lib/read-state/envelopes/evm.js

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EVM_QUERY_TYPE = void 0;
+exports.toStorageSlot = toStorageSlot;
+exports.encodeEvmQueryEnvelope = encodeEvmQueryEnvelope;
+exports.decodeEvmQueryEnvelope = decodeEvmQueryEnvelope;
+const viem_1 = require("viem");
+const read_state_1 = require("../../constants/read-state");
+const errors_1 = require("../errors");
+/** `universalClient/externalchains/evm/read_envelope.go` — evmQueryType. */
+exports.EVM_QUERY_TYPE = {
+    ACCOUNT_BALANCE: 0,
+    CONTRACT_CALL: 1,
+    STORAGE_SLOT: 2,
+};
+/** Only AT_NUMBER exists in v1. */
+const EVM_BLOCK_REF_AT_NUMBER = 0;
+/**
+ * The validator unpacks `abi.Arguments{ ONE tuple }`. The envelope MUST therefore be
+ * `abi.encode(struct)` — a single dynamic tuple with a 0x20 head offset — never the
+ * fields as separate parameters. The three-parameter layout parses only by coincidence
+ * when queryType == 0 and cost the first live read (2026-09-09).
+ */
+const EVM_ENVELOPE_ABI = [
+    {
+        type: 'tuple',
+        components: [
+            { name: 'queryType', type: 'uint8' },
+            {
+                name: 'blockRef',
+                type: 'tuple',
+                components: [
+                    { name: 'refType', type: 'uint8' },
+                    { name: 'blockNumber', type: 'uint64' },
+                ],
+            },
+            { name: 'payload', type: 'bytes' },
+        ],
+    },
+];
+const UINT64_MAX = (1n << 64n) - 1n;
+function assertAddress(value, what) {
+    if (!(0, viem_1.isAddress)(value))
+        throw new errors_1.InvalidReadQueryError(`${what} is not an EVM address: ${value}`);
+}
+function assertBlockNumber(blockNumber) {
+    if (blockNumber < 0n || blockNumber > UINT64_MAX) {
+        throw new errors_1.InvalidReadQueryError(`blockNumber out of uint64 range: ${blockNumber}`);
+    }
+}
+/** Normalise a storage slot (hex or bigint) to bytes32. */
+function toStorageSlot(slot) {
+    if (typeof slot === 'bigint') {
+        if (slot < 0n || slot >= 1n << 256n)
+            throw new errors_1.InvalidReadQueryError(`storage slot out of range: ${slot}`);
+        return (0, viem_1.toHex)(slot, { size: 32 });
+    }
+    if (!(0, viem_1.isHex)(slot))
+        throw new errors_1.InvalidReadQueryError(`storage slot is not hex: ${slot}`);
+    if ((0, viem_1.size)(slot) > 32)
+        throw new errors_1.InvalidReadQueryError(`storage slot longer than 32 bytes: ${slot}`);
+    return (0, viem_1.pad)(slot, { size: 32 });
+}
+function encodeEnvelope(queryType, blockNumber, payload) {
+    return (0, viem_1.encodeAbiParameters)(EVM_ENVELOPE_ABI, [
+        { queryType, blockRef: { refType: EVM_BLOCK_REF_AT_NUMBER, blockNumber }, payload },
+    ]);
+}
+/**
+ * Encode an `eip155` read query. Pure — `blockNumber` is the pinned destination
+ * height and is also mirrored into `ReadSpec.blockNumber` by the spec builder.
+ */
+function encodeEvmQueryEnvelope(query, options) {
+    const { blockNumber } = options;
+    assertBlockNumber(blockNumber);
+    assertAddress(query.target, 'target');
+    let queryType;
+    let payload;
+    let resultShape;
+    switch (query.type) {
+        case 'accountBalance': {
+            queryType = exports.EVM_QUERY_TYPE.ACCOUNT_BALANCE;
+            // abi.encode(address) — 32 bytes. The raw 20-byte address is rejected by validators.
+            payload = (0, viem_1.encodeAbiParameters)([{ type: 'address' }], [query.target]);
+            resultShape = { kind: 'uint256' };
+            break;
+        }
+        case 'contractCall': {
+            queryType = exports.EVM_QUERY_TYPE.CONTRACT_CALL;
+            let callData;
+            if ('callData' in query) {
+                if (!(0, viem_1.isHex)(query.callData) || (0, viem_1.size)(query.callData) < 4) {
+                    throw new errors_1.InvalidReadQueryError('callData must be hex with at least a 4-byte selector');
+                }
+                callData = query.callData;
+                resultShape = { kind: 'raw' };
+            }
+            else {
+                const item = (0, viem_1.getAbiItem)({
+                    abi: query.abi,
+                    name: query.functionName,
+                    args: query.args,
+                });
+                if (!item || item.type !== 'function') {
+                    throw new errors_1.InvalidReadQueryError(`function not found in abi: ${query.functionName}`);
+                }
+                // Any mutability: validators run the call as an eth_call simulation at the
+                // pinned block, so nonpayable/payable functions return data and never execute.
+                callData = (0, viem_1.encodeFunctionData)({
+                    abi: query.abi,
+                    functionName: query.functionName,
+                    args: query.args,
+                });
+                resultShape = { kind: 'evmCall', abi: [item], functionName: query.functionName };
+            }
+            payload = (0, viem_1.encodeAbiParameters)([{ type: 'address' }, { type: 'bytes' }], [query.target, callData]);
+            break;
+        }
+        case 'storageSlot': {
+            queryType = exports.EVM_QUERY_TYPE.STORAGE_SLOT;
+            payload = (0, viem_1.encodeAbiParameters)([{ type: 'address' }, { type: 'bytes32' }], [query.target, toStorageSlot(query.slot)]);
+            resultShape = { kind: 'bytes32' };
+            break;
+        }
+        default:
+            throw new errors_1.InvalidReadQueryError(`unknown EVM query type: ${query.type}`);
+    }
+    return {
+        namespace: read_state_1.READ_NAMESPACE.EVM,
+        queryType,
+        encoded: encodeEnvelope(queryType, blockNumber, payload),
+        blockRef: blockNumber,
+        resultShape,
+        warnings: [],
+    };
+}
+/** Decode an envelope with the exact tuple shape the validator uses. */
+function decodeEvmQueryEnvelope(encoded) {
+    const [env] = (0, viem_1.decodeAbiParameters)(EVM_ENVELOPE_ABI, encoded);
+    return {
+        queryType: env.queryType,
+        refType: env.blockRef.refType,
+        blockNumber: env.blockRef.blockNumber,
+        payload: env.payload,
+    };
+}
+//# sourceMappingURL=evm.js.map

package/src/lib/read-state/envelopes/index.d.ts

@@ -0,0 +1,12 @@
+import type { EncodedReadQuery, ReadDestination, ReadQuery } from '../read-state.types';
+export * from './evm';
+export * from './svm';
+export * from './web2';
+/**
+ * Encode any read query for its destination. Rejects a query kind that does not
+ * belong to the destination's namespace (e.g. a `storageSlot` read against Solana).
+ */
+export declare function encodeReadQuery(destination: ReadDestination, query: ReadQuery, options?: {
+    blockNumber?: bigint;
+    minSlot?: bigint;
+}): EncodedReadQuery;

package/src/lib/read-state/envelopes/index.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeReadQuery = encodeReadQuery;
+const tslib_1 = require("tslib");
+const read_state_1 = require("../../constants/read-state");
+const destination_1 = require("../destination");
+const errors_1 = require("../errors");
+const evm_1 = require("./evm");
+const svm_1 = require("./svm");
+const web2_1 = require("./web2");
+tslib_1.__exportStar(require("./evm"), exports);
+tslib_1.__exportStar(require("./svm"), exports);
+tslib_1.__exportStar(require("./web2"), exports);
+const EVM_TYPES = new Set(['accountBalance', 'contractCall', 'storageSlot']);
+const SVM_TYPES = new Set(['lamportBalance', 'splTokenAccount', 'rawAccountData']);
+/**
+ * Encode any read query for its destination. Rejects a query kind that does not
+ * belong to the destination's namespace (e.g. a `storageSlot` read against Solana).
+ */
+function encodeReadQuery(destination, query, options = {}) {
+    const dest = (0, destination_1.resolveDestination)(destination);
+    switch (dest.namespace) {
+        case read_state_1.READ_NAMESPACE.EVM: {
+            if (!EVM_TYPES.has(query.type))
+                throw new errors_1.InvalidReadQueryError(`query type ${query.type} is not valid for ${dest.caip2}`);
+            if (options.blockNumber === undefined) {
+                throw new errors_1.InvalidReadQueryError('EVM reads need options.blockNumber (the pinned destination height)');
+            }
+            return (0, evm_1.encodeEvmQueryEnvelope)(query, { blockNumber: options.blockNumber });
+        }
+        case read_state_1.READ_NAMESPACE.SVM: {
+            if (!SVM_TYPES.has(query.type))
+                throw new errors_1.InvalidReadQueryError(`query type ${query.type} is not valid for ${dest.caip2}`);
+            return (0, svm_1.encodeSvmQueryEnvelope)(query, { minSlot: options.minSlot });
+        }
+        case read_state_1.READ_NAMESPACE.WEB2: {
+            if (query.type !== 'http')
+                throw new errors_1.InvalidReadQueryError(`query type ${query.type} is not valid for web2`);
+            return (0, web2_1.encodeWeb2QueryEnvelope)(query);
+        }
+        default:
+            throw new errors_1.UnsupportedReadDestinationError(`unsupported namespace: ${dest.namespace}`);
+    }
+}
+//# sourceMappingURL=index.js.map