@pushchain/core 6.0.23 → 6.0.25

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
@@ -215,6 +224,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 +255,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 +267,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 +322,70 @@ 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) {
+        return this.executeWithRpcFallback(async (rpcUrl) => {
+            const url = `${rpcUrl.replace(/\/+$/, '')}/block_results?height=${height}`;
+            const res = await fetch(url);
+            if (!res.ok)
+                throw new Error(`HTTP request failed: ${res.status} ${url}`);
+            const body = (await res.json());
+            if (body.error)
+                throw new Error(`block_results ${height}: ${body.error.data ?? body.error.message ?? 'error'}`);
+            const events = body.result?.finalize_block_events ?? body.result?.end_block_events ?? [];
+            return events;
+        }, 'getBlockResultEvents');
+    }
+    /**
+     * 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 +466,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 };
         }
     }

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,148 @@
+"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}`);
+                }
+                if (item.stateMutability !== 'view' && item.stateMutability !== 'pure') {
+                    throw new errors_1.InvalidReadQueryError(`${query.functionName} is ${item.stateMutability}; reads must target view/pure functions`);
+                }
+                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

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

@@ -0,0 +1,32 @@
+import { PublicKey } from '@solana/web3.js';
+import { type Hex } from 'viem';
+import type { EncodedReadQuery, SvmReadQuery } from '../read-state.types';
+/** `universalClient/externalchains/svm/read_envelope.go` — solanaQueryType. */
+export declare const SVM_QUERY_TYPE: {
+    readonly LAMPORT_BALANCE: 0;
+    readonly SPL_TOKEN_ACCOUNT: 1;
+    readonly RAW_ACCOUNT_DATA: 2;
+};
+export declare const TOKEN_PROGRAM_ID: PublicKey;
+export declare const TOKEN_2022_PROGRAM_ID: PublicKey;
+export declare const ASSOCIATED_TOKEN_PROGRAM_ID: PublicKey;
+/**
+ * The raw 32-byte pubkey the validator requires in `ReadSpec.account.owner`
+ * (`svm/read_executor.go:29-32` hard-rejects any other length).
+ */
+export declare function svmOwnerBytes(account: string | Uint8Array): Hex;
+/** Deterministic, offline. Same derivation as @solana/spl-token getAssociatedTokenAddressSync. */
+export declare function deriveAssociatedTokenAddress(owner: string | PublicKey, mint: string | PublicKey, tokenProgramId?: PublicKey): PublicKey;
+/**
+ * Encode a `solana` read query. `minSlot` is a staleness FLOOR at finalized
+ * commitment, not a pin — Solana cannot read at an exact past slot. The validator
+ * uses `max(envelope.minSlot, ReadSpec.blockNumber)`.
+ */
+export declare function encodeSvmQueryEnvelope(query: SvmReadQuery, options?: {
+    minSlot?: bigint;
+}): EncodedReadQuery;
+export declare function decodeSvmQueryEnvelope(encoded: Hex): {
+    queryType: number;
+    minSlot: bigint;
+    payload: Hex;
+};

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

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ASSOCIATED_TOKEN_PROGRAM_ID = exports.TOKEN_2022_PROGRAM_ID = exports.TOKEN_PROGRAM_ID = exports.SVM_QUERY_TYPE = void 0;
+exports.svmOwnerBytes = svmOwnerBytes;
+exports.deriveAssociatedTokenAddress = deriveAssociatedTokenAddress;
+exports.encodeSvmQueryEnvelope = encodeSvmQueryEnvelope;
+exports.decodeSvmQueryEnvelope = decodeSvmQueryEnvelope;
+const tslib_1 = require("tslib");
+const web3_js_1 = require("@solana/web3.js");
+const bs58_1 = tslib_1.__importDefault(require("bs58"));
+const viem_1 = require("viem");
+const read_state_1 = require("../../constants/read-state");
+const errors_1 = require("../errors");
+/** `universalClient/externalchains/svm/read_envelope.go` — solanaQueryType. */
+exports.SVM_QUERY_TYPE = {
+    LAMPORT_BALANCE: 0,
+    SPL_TOKEN_ACCOUNT: 1,
+    RAW_ACCOUNT_DATA: 2,
+};
+/** Single tuple, like EVM. Payload is empty for every v1 type. */
+const SVM_ENVELOPE_ABI = [
+    {
+        type: 'tuple',
+        components: [
+            { name: 'queryType', type: 'uint8' },
+            { name: 'slotRef', type: 'tuple', components: [{ name: 'minSlot', type: 'uint64' }] },
+            { name: 'payload', type: 'bytes' },
+        ],
+    },
+];
+exports.TOKEN_PROGRAM_ID = new web3_js_1.PublicKey('TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA');
+exports.TOKEN_2022_PROGRAM_ID = new web3_js_1.PublicKey('TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb');
+exports.ASSOCIATED_TOKEN_PROGRAM_ID = new web3_js_1.PublicKey('ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL');
+const UINT64_MAX = (1n << 64n) - 1n;
+/**
+ * The raw 32-byte pubkey the validator requires in `ReadSpec.account.owner`
+ * (`svm/read_executor.go:29-32` hard-rejects any other length).
+ */
+function svmOwnerBytes(account) {
+    let bytes;
+    if (typeof account === 'string') {
+        try {
+            bytes = bs58_1.default.decode(account);
+        }
+        catch {
+            throw new errors_1.InvalidReadQueryError(`account is not a base58 Solana pubkey: ${account}`);
+        }
+    }
+    else {
+        bytes = account;
+    }
+    if (bytes.length !== 32) {
+        throw new errors_1.InvalidReadQueryError(`Solana account must be 32 bytes, got ${bytes.length}`);
+    }
+    return (0, viem_1.bytesToHex)(bytes);
+}
+/** Deterministic, offline. Same derivation as @solana/spl-token getAssociatedTokenAddressSync. */
+function deriveAssociatedTokenAddress(owner, mint, tokenProgramId = exports.TOKEN_PROGRAM_ID) {
+    const o = typeof owner === 'string' ? new web3_js_1.PublicKey(owner) : owner;
+    const m = typeof mint === 'string' ? new web3_js_1.PublicKey(mint) : mint;
+    const [ata] = web3_js_1.PublicKey.findProgramAddressSync([o.toBuffer(), tokenProgramId.toBuffer(), m.toBuffer()], exports.ASSOCIATED_TOKEN_PROGRAM_ID);
+    return ata;
+}
+/**
+ * Encode a `solana` read query. `minSlot` is a staleness FLOOR at finalized
+ * commitment, not a pin — Solana cannot read at an exact past slot. The validator
+ * uses `max(envelope.minSlot, ReadSpec.blockNumber)`.
+ */
+function encodeSvmQueryEnvelope(query, options = {}) {
+    const minSlot = options.minSlot ?? 0n;
+    if (minSlot < 0n || minSlot > UINT64_MAX)
+        throw new errors_1.InvalidReadQueryError(`minSlot out of uint64 range: ${minSlot}`);
+    let queryType;
+    let resultShape;
+    switch (query.type) {
+        case 'lamportBalance':
+            queryType = exports.SVM_QUERY_TYPE.LAMPORT_BALANCE;
+            resultShape = { kind: 'uint256' };
+            break;
+        case 'splTokenAccount':
+            queryType = exports.SVM_QUERY_TYPE.SPL_TOKEN_ACCOUNT;
+            resultShape = { kind: 'uint256' };
+            break;
+        case 'rawAccountData':
+            queryType = exports.SVM_QUERY_TYPE.RAW_ACCOUNT_DATA;
+            resultShape = { kind: 'raw' };
+            break;
+        default:
+            throw new errors_1.InvalidReadQueryError(`unknown SVM query type: ${query.type}`);
+    }
+    const ownerBytes = svmOwnerBytes(query.account);
+    const encoded = (0, viem_1.encodeAbiParameters)(SVM_ENVELOPE_ABI, [{ queryType, slotRef: { minSlot }, payload: '0x' }]);
+    return {
+        namespace: read_state_1.READ_NAMESPACE.SVM,
+        queryType,
+        encoded,
+        blockRef: minSlot,
+        resultShape,
+        ownerBytes,
+        warnings: [],
+    };
+}
+function decodeSvmQueryEnvelope(encoded) {
+    const [env] = (0, viem_1.decodeAbiParameters)(SVM_ENVELOPE_ABI, encoded);
+    return { queryType: env.queryType, minSlot: env.slotRef.minSlot, payload: env.payload };
+}
+//# sourceMappingURL=svm.js.map