@pushchain/core 6.0.24 → 6.0.26

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

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeReadQueryKey = computeReadQueryKey;
+exports.getReadRegistryAddress = getReadRegistryAddress;
+exports.resolveReadCallback = resolveReadCallback;
+exports.getRegistryReadResult = getRegistryReadResult;
+exports.getLatestRegistryReadResult = getLatestRegistryReadResult;
+const viem_1 = require("viem");
+const read_state_1 = require("../constants/read-state");
+const universalReadRegistry_evm_1 = require("../constants/abi/universalReadRegistry.evm");
+const envelopes_1 = require("./envelopes");
+const destination_1 = require("./destination");
+const errors_1 = require("./errors");
+/** Versioned logical identity. Height, fee, expiry, refund, callback and HTTP timeout are excluded. */
+function computeReadQueryKey(destination, query) {
+    const dest = (0, destination_1.resolveDestination)(destination);
+    // Use fixed references in the existing canonical encoders; never hash live heights.
+    const encoded = (0, envelopes_1.encodeReadQuery)(destination, query.type === 'http' ? { ...query, timeoutMs: read_state_1.WEB2_DEFAULT_TIMEOUT_MS } : query, { blockNumber: 1n, minSlot: 0n });
+    return (0, viem_1.keccak256)((0, viem_1.encodeAbiParameters)([{ type: 'string' }, { type: 'string' }, { type: 'string' }, { type: 'bytes' }, { type: 'bytes' }], ['pushchain:universal-read:query:v1', dest.chainNamespace, dest.chainId, encoded.ownerBytes ?? '0x', encoded.encoded]));
+}
+function getReadRegistryAddress(network) {
+    const address = read_state_1.UNIVERSAL_READ_REGISTRY_ADDRESS[network];
+    if (!address)
+        throw new errors_1.ReadRegistryUnavailableError('read registry');
+    return address;
+}
+function resolveReadCallback(callback, network, queryKey) {
+    if (callback && 'request' in callback)
+        throw new errors_1.InvalidReadQueryError('callback.request was removed; use callback.abi, functionName and args');
+    if (callback?.target !== undefined) {
+        // Same default as the registry: unused callback budget is refunded.
+        return { ...callback, gasLimit: callback.gasLimit ?? read_state_1.REGISTRY_CALLBACK_GAS };
+    }
+    if (callback?.abi !== undefined || callback?.functionName !== undefined || callback?.args !== undefined) {
+        throw new errors_1.InvalidReadQueryError('callback abi, functionName and args require callback.target');
+    }
+    return {
+        target: getReadRegistryAddress(network),
+        gasLimit: callback?.gasLimit ?? read_state_1.REGISTRY_CALLBACK_GAS,
+        abi: universalReadRegistry_evm_1.UNIVERSAL_READ_REGISTRY_EVM, functionName: 'read', args: (spec, gas) => [spec, queryKey, gas],
+    };
+}
+/** Raw registry storage only: presence does not prove successful consensus or freshness. */
+function getRegistryReadResult(client, network, requestId) {
+    return client.readContract({ address: getReadRegistryAddress(network), abi: universalReadRegistry_evm_1.UNIVERSAL_READ_REGISTRY_EVM,
+        functionName: 'resultByRequestId', args: [requestId] });
+}
+/** Keys are caller-supplied labels; verify the associated request before relying on its identity. */
+function getLatestRegistryReadResult(client, network, reader, queryKey) {
+    return client.readContract({ address: getReadRegistryAddress(network), abi: universalReadRegistry_evm_1.UNIVERSAL_READ_REGISTRY_EVM,
+        functionName: 'latestResult', args: [reader, queryKey] });
+}
+//# sourceMappingURL=registry.js.map

package/src/lib/read-state/result-decoder.d.ts

@@ -0,0 +1,16 @@
+import { type Hex } from 'viem';
+import type { DecodedReadResult, ReadResultShape } from './read-state.types';
+/**
+ * Decode `resultData` using the shape recorded by the query that produced it.
+ *
+ * `resultData` is not self-describing. Shapes (from the validator executors):
+ *   EVM AccountBalance / SVM LamportBalance / SVM SPLTokenAccount → abi.encode(uint256)
+ *   EVM ContractCall → raw eth_call return bytes (decoded with the recorded ABI, else raw)
+ *   EVM StorageSlot  → raw 32 bytes
+ *   SVM RawAccountData → raw account bytes
+ *   Web2 → abi.encode(v1, v2, …) — a FLAT argument list, one per extract, in order
+ *
+ * Throws `ReadDecodeError` rather than mis-decoding. Do not call this for an ERROR
+ * result (empty bytes) — check `result.status` first.
+ */
+export declare function decodeReadResult(resultData: Hex, shape: ReadResultShape): DecodedReadResult;

package/src/lib/read-state/result-decoder.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decodeReadResult = decodeReadResult;
+const viem_1 = require("viem");
+const errors_1 = require("./errors");
+const buffer_1 = require("buffer");
+const svm_account_1 = require("./svm-account");
+const WEB2_ABI_TYPE = {
+    uint256: 'uint256',
+    int256: 'int256',
+    bool: 'bool',
+    string: 'string',
+    bytes: 'bytes',
+};
+/**
+ * Decode `resultData` using the shape recorded by the query that produced it.
+ *
+ * `resultData` is not self-describing. Shapes (from the validator executors):
+ *   EVM AccountBalance / SVM LamportBalance / SVM SPLTokenAccount → abi.encode(uint256)
+ *   EVM ContractCall → raw eth_call return bytes (decoded with the recorded ABI, else raw)
+ *   EVM StorageSlot  → raw 32 bytes
+ *   SVM RawAccountData → raw account bytes
+ *   Web2 → abi.encode(v1, v2, …) — a FLAT argument list, one per extract, in order
+ *
+ * Throws `ReadDecodeError` rather than mis-decoding. Do not call this for an ERROR
+ * result (empty bytes) — check `result.status` first.
+ */
+function decodeReadResult(resultData, shape) {
+    if (!(0, viem_1.isHex)(resultData))
+        throw new errors_1.ReadDecodeError('resultData is not hex');
+    const len = (0, viem_1.size)(resultData);
+    try {
+        switch (shape.kind) {
+            case 'svmAccount': {
+                const { accountName, value } = (0, svm_account_1.decodeIdlAccount)(shape.idl, buffer_1.Buffer.from(resultData.slice(2), 'hex'), shape.accountName);
+                return { kind: 'svmAccount', value, accountName };
+            }
+            case 'uint256': {
+                if (len !== 32)
+                    throw new errors_1.ReadDecodeError(`expected 32 bytes for uint256, got ${len}`);
+                const [value] = (0, viem_1.decodeAbiParameters)([{ type: 'uint256' }], resultData);
+                return { kind: 'uint256', value };
+            }
+            case 'bytes32': {
+                if (len !== 32)
+                    throw new errors_1.ReadDecodeError(`expected 32 bytes for bytes32, got ${len}`);
+                return { kind: 'bytes32', value: resultData };
+            }
+            case 'raw':
+                return { kind: 'raw', value: resultData };
+            case 'evmCall': {
+                if (len === 0)
+                    throw new errors_1.ReadDecodeError('empty resultData for a contract call');
+                const item = (0, viem_1.getAbiItem)({ abi: shape.abi, name: shape.functionName });
+                if (!item)
+                    throw new errors_1.ReadDecodeError(`function not found in abi: ${shape.functionName}`);
+                const decoded = (0, viem_1.decodeFunctionResult)({ abi: shape.abi, functionName: shape.functionName, data: resultData });
+                return { kind: 'evmCall', value: decoded };
+            }
+            case 'web2': {
+                if (shape.extract.length === 0)
+                    throw new errors_1.ReadDecodeError('web2 shape has no extracts');
+                if (len === 0)
+                    throw new errors_1.ReadDecodeError('empty resultData for a web2 read');
+                const params = shape.extract.map((e) => ({ type: WEB2_ABI_TYPE[e.valueType] }));
+                const values = (0, viem_1.decodeAbiParameters)(params, resultData);
+                return { kind: 'web2', values };
+            }
+            default:
+                throw new errors_1.ReadDecodeError(`unknown result shape: ${shape.kind}`);
+        }
+    }
+    catch (err) {
+        if (err instanceof errors_1.ReadDecodeError)
+            throw err;
+        throw new errors_1.ReadDecodeError(`resultData does not match shape ${shape.kind}: ${err.message}`);
+    }
+}
+//# sourceMappingURL=result-decoder.js.map

package/src/lib/read-state/spec-builder.d.ts

@@ -0,0 +1,47 @@
+import { type Abi, type Address, type Hex } from 'viem';
+import { type PreflightDeps } from './preflight';
+import type { BuildReadSpecParams, PreparedRead, ReadPreflight, ReadSpec, ReadSpecTuple, SimulateReadResult } from './read-state.types';
+import type { ReadHookEmitter } from './read-tracker';
+export interface PrepareReadDeps extends PreflightDeps {
+    emit?: ReadHookEmitter;
+    /** The signer's Push-side account (UEA or EOA). Used when `refundTo` is not given. */
+    defaultRefundTo?: Address;
+}
+export declare function encodeSpec(spec: ReadSpec): Hex;
+/**
+ * Assemble a `PreparedRead` from an already-fetched preflight. Pure — no network.
+ * Use directly when preparing several reads from one preflight.
+ */
+export declare function buildReadSpecFromPreflight(preflight: ReadPreflight, params: BuildReadSpecParams, defaults?: {
+    refundTo?: Address;
+}): PreparedRead;
+/**
+ * Preflight + build. Adds the `refundTo` advisory: a contract recipient that is not a
+ * UEA must have a payable receive() or the refund is forfeited to the admin rescue
+ * pool (verified live). UEAs (UEA_EVM / UEA_SVM) always have one.
+ */
+export declare function prepareRead(deps: PrepareReadDeps, params: BuildReadSpecParams): Promise<PreparedRead>;
+/**
+ * Splice the prepared spec into the app's own entrypoint.
+ * Default argument order is `(spec, callbackGasLimit)`; pass `args` to remap.
+ */
+export declare function toCallData(prepared: PreparedRead, target: {
+    abi: Abi;
+    functionName: string;
+    args?: (spec: ReadSpecTuple, callbackGasLimit: bigint) => readonly unknown[];
+}): {
+    data: Hex;
+    value: bigint;
+};
+/**
+ * eth_call `requestExternalReadSelf` with `from` = the app contract, so validation
+ * reverts surface before broadcast, decoded into the contract's custom errors.
+ * Only meaningful for the app-contract persona: `callbackTarget` becomes `msg.sender`.
+ */
+export declare function simulateRead(deps: PreflightDeps, prepared: PreparedRead, opts: {
+    appContract: Address;
+    callbackSelector: Hex;
+    staleAfterMs?: number;
+}): Promise<SimulateReadResult>;
+/** Fresh validation only: never rebuild or mutate the prepared request. */
+export declare function revalidateRead(deps: PreflightDeps, prepared: PreparedRead): Promise<void>;

package/src/lib/read-state/spec-builder.js

@@ -0,0 +1,251 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeSpec = encodeSpec;
+exports.buildReadSpecFromPreflight = buildReadSpecFromPreflight;
+exports.prepareRead = prepareRead;
+exports.toCallData = toCallData;
+exports.simulateRead = simulateRead;
+exports.revalidateRead = revalidateRead;
+const viem_1 = require("viem");
+const universalCallback_evm_1 = require("../constants/abi/universalCallback.evm");
+const uea_factory_1 = require("../constants/abi/uea-factory");
+const chain_1 = require("../constants/chain");
+const read_state_1 = require("../constants/read-state");
+const budget_1 = require("./budget");
+const registry_1 = require("./registry");
+const destination_1 = require("./destination");
+const envelopes_1 = require("./envelopes");
+const errors_1 = require("./errors");
+const preflight_1 = require("./preflight");
+const validate_1 = require("./validate");
+const progress_hook_types_1 = require("../progress-hook/progress-hook.types");
+/** The ReadSpec tuple as the contract declares it — for abi.encode(spec). */
+const READ_SPEC_ABI_PARAM = (0, viem_1.getAbiItem)({ abi: universalCallback_evm_1.UNIVERSAL_CALLBACK_EVM, name: 'requestExternalReadSelf' }).inputs[0];
+function toTuple(spec) {
+    return [
+        [spec.account.chainNamespace, spec.account.chainId, spec.account.owner],
+        spec.query,
+        spec.minConfirmations,
+        spec.blockNumber,
+        spec.expiryPushChainHeight,
+        spec.maxFee,
+        spec.revertRecipient,
+    ];
+}
+function encodeSpec(spec) {
+    return (0, viem_1.encodeAbiParameters)([READ_SPEC_ABI_PARAM], [spec]);
+}
+/**
+ * Assemble a `PreparedRead` from an already-fetched preflight. Pure — no network.
+ * Use directly when preparing several reads from one preflight.
+ */
+function buildReadSpecFromPreflight(preflight, params, defaults = {}) {
+    const dest = preflight.destination;
+    if ((0, destination_1.resolveDestination)(params.destination).caip2 !== dest.caip2) {
+        throw new errors_1.InvalidReadQueryError('preflight destination does not match the requested destination');
+    }
+    const isWeb2 = dest.namespace === read_state_1.READ_NAMESPACE.WEB2;
+    const minConfirmations = params.minConfirmations ?? read_state_1.MIN_CONFIRMATIONS_FLOOR;
+    // --- pin ---
+    let blockNumber;
+    if (isWeb2) {
+        if (params.blockNumber !== undefined && params.blockNumber !== 0n) {
+            throw new errors_1.InvalidReadQueryError('web2 is heightless: blockNumber must be 0 (or omitted)');
+        }
+        blockNumber = 0n;
+    }
+    else if (params.blockNumber !== undefined) {
+        blockNumber = params.blockNumber;
+    }
+    else {
+        // Back off by minConfirmations: validators hold until latest ≥ blockNumber + minConfirmations,
+        // and the oracle height IS roughly latest — pinning at the head would always wait.
+        const backed = preflight.observedChainHeight - BigInt(minConfirmations);
+        blockNumber = backed >= 1n ? backed : 1n;
+    }
+    // --- envelope ---
+    const encodedQuery = (0, envelopes_1.encodeReadQuery)(params.destination, params.query, {
+        blockNumber,
+        minSlot: dest.namespace === read_state_1.READ_NAMESPACE.SVM ? blockNumber : undefined,
+    });
+    // --- money ---
+    const callbackBudget = params.callbackBudget ?? (0, budget_1.sizeCallbackBudget)(params.callbackGasLimit, preflight.pushGasPrice, params.budgetBuffer);
+    const value = preflight.protocolFee + callbackBudget;
+    const bps = BigInt(params.maxFeeBufferBps ?? 0);
+    const maxFee = params.maxFee ?? value + (value * bps) / 10000n;
+    // --- identities ---
+    const refundTo = params.refundTo ?? defaults.refundTo;
+    if (!refundTo || !(0, viem_1.isAddress)(refundTo)) {
+        throw new errors_1.InvalidReadSpecError(['ZERO_REVERT_RECIPIENT'], {
+            destination: dest.caip2,
+            hint: 'Pass refundTo (where unspent budget is pushed). In the SDK it defaults to your Push-side account.',
+        });
+    }
+    let owner;
+    if (dest.namespace === read_state_1.READ_NAMESPACE.SVM) {
+        if (!encodedQuery.ownerBytes)
+            throw new errors_1.InvalidReadQueryError('SVM query did not yield the 32-byte owner');
+        if (params.owner !== undefined)
+            throw new errors_1.InvalidReadQueryError('SVM reads take the account from the query, not `owner`');
+        owner = encodedQuery.ownerBytes;
+    }
+    else {
+        owner = params.owner ?? refundTo.toLowerCase(); // validators ignore it for EVM; any non-empty bytes
+    }
+    const expiryPushChainHeight = params.expiryPushChainHeight ?? preflight.pushBlockNumber + (params.expiryBlocks ?? read_state_1.DEFAULT_EXPIRY_BLOCKS);
+    const spec = {
+        account: { chainNamespace: dest.chainNamespace, chainId: dest.chainId, owner },
+        query: encodedQuery.encoded,
+        minConfirmations,
+        blockNumber,
+        expiryPushChainHeight,
+        maxFee,
+        revertRecipient: refundTo,
+    };
+    (0, validate_1.assertValidReadSpec)({ spec, value, callbackGasLimit: params.callbackGasLimit, preflight });
+    return {
+        callback: params.callback,
+        queryKey: (0, registry_1.computeReadQueryKey)(params.destination, params.query),
+        chain: dest.caip2,
+        spec,
+        specTuple: toTuple(spec),
+        encodedSpec: encodeSpec(spec),
+        value,
+        protocolFee: preflight.protocolFee,
+        callbackBudget,
+        fees: { protocolFee: preflight.protocolFee, callbackBudget, total: value },
+        callbackGasLimit: params.callbackGasLimit,
+        encodedQuery,
+        resultShape: encodedQuery.resultShape,
+        preflight,
+        warnings: [...encodedQuery.warnings],
+    };
+}
+/**
+ * Preflight + build. Adds the `refundTo` advisory: a contract recipient that is not a
+ * UEA must have a payable receive() or the refund is forfeited to the admin rescue
+ * pool (verified live). UEAs (UEA_EVM / UEA_SVM) always have one.
+ */
+async function prepareRead(deps, params) {
+    const emit = deps.emit ?? (() => undefined);
+    const dest = (0, destination_1.resolveDestination)(params.destination);
+    emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_101, dest.caip2, dest.namespace, params.query.type);
+    emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_102_01, dest.caip2);
+    let preflight;
+    try {
+        preflight = await (0, preflight_1.preflightRead)(deps, params.destination);
+    }
+    catch (error) {
+        if (error instanceof errors_1.ReadHeightUnavailableError)
+            emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_102_03, dest.caip2);
+        throw error;
+    }
+    const prepared = buildReadSpecFromPreflight(preflight, params, { refundTo: deps.defaultRefundTo });
+    emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_102_02, prepared.protocolFee, prepared.callbackBudget, prepared.value, prepared.spec.blockNumber, prepared.spec.expiryPushChainHeight);
+    if (params.query.type === 'http') {
+        const matched = Object.keys(params.query.headers ?? {}).filter((name) => /auth|key|token|secret|bearer/i.test(name));
+        if (matched.length)
+            emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_103_03, matched);
+    }
+    const refundTo = prepared.spec.revertRecipient;
+    const code = await deps.pushClient.publicClient.getCode({ address: refundTo });
+    // EIP-7702 delegation designator (0xef0100 + delegate): an EOA that batches via the SDK's
+    // executor. It receives value like an EOA — refunds to such accounts have landed live.
+    const isDelegatedEoa = !!code && code.toLowerCase().startsWith('0xef0100');
+    if (code && code !== '0x' && !isDelegatedEoa) {
+        const [, isUEA] = await deps.pushClient.readContract({
+            address: chain_1.UEA_FACTORY[deps.pushNetwork],
+            abi: uea_factory_1.UEA_FACTORY_ABI,
+            functionName: 'getOriginForUEA',
+            args: [refundTo],
+        });
+        if (!isUEA) {
+            emit(progress_hook_types_1.PROGRESS_HOOK.READ_TX_102_05, refundTo);
+            prepared.warnings.push(`refundTo ${refundTo} is a contract that is not a UEA — it must have a payable receive() or the unspent callback budget is forfeited`);
+        }
+    }
+    return prepared;
+}
+/**
+ * Splice the prepared spec into the app's own entrypoint.
+ * Default argument order is `(spec, callbackGasLimit)`; pass `args` to remap.
+ */
+function toCallData(prepared, target) {
+    // Positional tuple: viem accepts it whether the app ABI names the struct components or not.
+    const args = target.args ? target.args(prepared.specTuple, prepared.callbackGasLimit) : [prepared.specTuple, prepared.callbackGasLimit];
+    return {
+        data: (0, viem_1.encodeFunctionData)({ abi: target.abi, functionName: target.functionName, args: args }),
+        value: prepared.value,
+    };
+}
+/**
+ * eth_call `requestExternalReadSelf` with `from` = the app contract, so validation
+ * reverts surface before broadcast, decoded into the contract's custom errors.
+ * Only meaningful for the app-contract persona: `callbackTarget` becomes `msg.sender`.
+ */
+async function simulateRead(deps, prepared, opts) {
+    const age = Date.now() - prepared.preflight.fetchedAt;
+    if (age > (opts.staleAfterMs ?? read_state_1.READ_PREFLIGHT_STALE_MS)) {
+        prepared.warnings.push(`preflight is ${Math.round(age / 1000)} s old — pushBlockNumber moves every block; rebuild before sending`);
+    }
+    try {
+        await deps.pushClient.publicClient.simulateContract({
+            address: prepared.preflight.universalCallback,
+            abi: universalCallback_evm_1.UNIVERSAL_CALLBACK_EVM,
+            functionName: 'requestExternalReadSelf',
+            args: [prepared.spec, opts.callbackSelector, prepared.callbackGasLimit],
+            account: opts.appContract,
+            value: prepared.value,
+            // In the real flow the app contract forwards the msg.value it just received from the
+            // user, so for the simulation it must "hold" it. Without this the node answers
+            // "insufficient balance for transfer" — and maps it to JSON-RPC -32602, which viem
+            // renders as the misleading "Missing or invalid parameters". Verified on Donut.
+            stateOverride: [{ address: opts.appContract, balance: prepared.value * 2n + 10n ** 18n }],
+        });
+        return { ok: true };
+    }
+    catch (err) {
+        if (err instanceof viem_1.BaseError) {
+            const reverted = err.walk((e) => e instanceof viem_1.ContractFunctionRevertedError);
+            if (reverted instanceof viem_1.ContractFunctionRevertedError && reverted.data) {
+                return { ok: false, error: reverted.shortMessage, errorName: reverted.data.errorName, args: reverted.data.args };
+            }
+            // Surface the node's own reason when viem's summary is generic.
+            const details = err.details || err.cause?.details;
+            return { ok: false, error: details ? `${err.shortMessage} (${details})` : err.shortMessage };
+        }
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+/** Fresh validation only: never rebuild or mutate the prepared request. */
+async function revalidateRead(deps, prepared) {
+    const [preflight, block] = await Promise.all([
+        (0, preflight_1.preflightRead)(deps, {
+            chainNamespace: prepared.spec.account.chainNamespace,
+            chainId: prepared.spec.account.chainId,
+        }),
+        deps.pushClient.publicClient.getBlock({ blockTag: 'latest' }),
+    ]);
+    // Mirrors node keeper.CallbackCost / CanAffordCallback (x/ucallback/keeper/evm.go).
+    // The module prices declared gas at base fee, without tips or the SDK sizing buffer.
+    const baseFee = block.baseFeePerGas;
+    if (baseFee === null || baseFee === undefined) {
+        throw new errors_1.ReadStateError('READ_CALLBACK_BASE_FEE_UNAVAILABLE', 'cannot validate callback affordability without the current Push base fee');
+    }
+    try {
+        (0, validate_1.assertValidReadSpec)({ spec: prepared.spec, value: prepared.value, callbackGasLimit: prepared.callbackGasLimit, preflight });
+        if (prepared.value - preflight.protocolFee < prepared.callbackGasLimit * baseFee) {
+            throw new errors_1.InvalidReadSpecError(['INSUFFICIENT_CALLBACK_BUDGET']);
+        }
+    }
+    catch (error) {
+        if (error instanceof errors_1.InvalidReadSpecError) {
+            throw new errors_1.InvalidReadSpecError([...error.violations], {
+                destination: preflight.destination.caip2,
+                hint: 'Prepared read is no longer valid. Call prepareRead again and review its pin, expiry and payment before executing.',
+            });
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=spec-builder.js.map

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

@@ -0,0 +1,20 @@
+import { type Idl } from '@coral-xyz/anchor';
+import { PublicKey } from '@solana/web3.js';
+import type { CHAIN } from '../constants/enums';
+/** snake_case, camelCase and PascalCase spellings of one name share a key. */
+export declare function idlNameKey(name: string): string;
+/** Structural checks the coder does not make, so a bad IDL fails at prepare time. */
+export declare function validateIdl(idl: Idl): void;
+/** The IDL's own spelling of an account layout name given in any case style. */
+export declare function resolveAccountName(idl: Idl, name: string): string;
+/**
+ * Decode account bytes with the IDL. With `accountName`, the data's discriminator
+ * must match that layout; without it, the layout is the one whose discriminator
+ * prefixes the data.
+ */
+export declare function decodeIdlAccount(idl: Idl, data: Uint8Array, accountName?: string): {
+    accountName: string;
+    value: unknown;
+};
+/** Inspect the mint owner; the chain alone cannot distinguish SPL Token and Token-2022. */
+export declare function detectTokenProgram(mint: string, chain: CHAIN, rpcUrls?: string[]): Promise<PublicKey>;

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

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.idlNameKey = idlNameKey;
+exports.validateIdl = validateIdl;
+exports.resolveAccountName = resolveAccountName;
+exports.decodeIdlAccount = decodeIdlAccount;
+exports.detectTokenProgram = detectTokenProgram;
+const anchor_1 = require("@coral-xyz/anchor");
+const web3_js_1 = require("@solana/web3.js");
+const chain_1 = require("../constants/chain");
+const buffer_1 = require("buffer");
+const errors_1 = require("./errors");
+const svm_1 = require("./envelopes/svm");
+/** snake_case, camelCase and PascalCase spellings of one name share a key. */
+function idlNameKey(name) {
+    return name.replace(/_/g, '').toLowerCase();
+}
+/** Structural checks the coder does not make, so a bad IDL fails at prepare time. */
+function validateIdl(idl) {
+    try {
+        if (!idl || typeof idl !== 'object')
+            throw new Error('idl must be an Anchor IDL object');
+        new web3_js_1.PublicKey(idl.address);
+        if (!idl.accounts?.length)
+            throw new Error('the IDL declares no accounts');
+        for (const a of idl.accounts) {
+            const d = a.discriminator;
+            if (!Array.isArray(d) || d.length === 0 || d.some(b => !Number.isInteger(b) || b < 0 || b > 255)) {
+                throw new Error(`account ${a.name}: discriminator must be a non-empty byte array`);
+            }
+        }
+        new anchor_1.BorshAccountsCoder(idl);
+    }
+    catch (error) {
+        throw new errors_1.InvalidReadQueryError(`invalid Solana account IDL: ${error.message}`);
+    }
+}
+/** The IDL's own spelling of an account layout name given in any case style. */
+function resolveAccountName(idl, name) {
+    const accounts = idl.accounts ?? [];
+    const exact = accounts.find(a => a.name === name);
+    if (exact)
+        return exact.name;
+    const key = idlNameKey(name);
+    const matches = accounts.filter(a => idlNameKey(a.name) === key);
+    if (matches.length === 1)
+        return matches[0].name;
+    const known = accounts.map(a => a.name).join(', ') || 'none';
+    throw new errors_1.InvalidReadQueryError(matches.length > 1 ? `functionName ${name} is ambiguous in the IDL (${matches.map(a => a.name).join(', ')})` : `functionName ${name} is not an account in the IDL (accounts: ${known})`);
+}
+function hasDiscriminator(a, data) {
+    return data.length >= a.discriminator.length && a.discriminator.every((b, i) => data[i] === b);
+}
+/**
+ * Decode account bytes with the IDL. With `accountName`, the data's discriminator
+ * must match that layout; without it, the layout is the one whose discriminator
+ * prefixes the data.
+ */
+function decodeIdlAccount(idl, data, accountName) {
+    const accounts = idl.accounts ?? [];
+    let def;
+    if (accountName !== undefined) {
+        def = accounts.find(a => a.name === resolveAccountName(idl, accountName));
+        if (def && !hasDiscriminator(def, data)) {
+            throw new errors_1.ReadDecodeError(`account data discriminator does not match ${def.name}`);
+        }
+    }
+    else {
+        const found = accounts.filter(a => hasDiscriminator(a, data));
+        // Longest match wins if one discriminator prefixes another.
+        def = found.sort((x, y) => y.discriminator.length - x.discriminator.length)[0];
+        if (!def) {
+            const head = buffer_1.Buffer.from(data.subarray(0, 8)).toString('hex');
+            throw new errors_1.ReadDecodeError(`no IDL account discriminator matches the account data (0x${head})`);
+        }
+    }
+    if (!def)
+        throw new errors_1.ReadDecodeError('account not found in the IDL');
+    return { accountName: def.name, value: new anchor_1.BorshAccountsCoder(idl).decode(def.name, buffer_1.Buffer.from(data)) };
+}
+/** Inspect the mint owner; the chain alone cannot distinguish SPL Token and Token-2022. */
+async function detectTokenProgram(mint, chain, rpcUrls) {
+    const address = new web3_js_1.PublicKey(mint);
+    const urls = rpcUrls ?? chain_1.CHAIN_INFO[chain]?.defaultRPC;
+    if (!urls?.length)
+        throw new errors_1.InvalidReadQueryError(`no Solana RPC configured for ${chain}`);
+    let lastError;
+    for (const url of urls) {
+        let info;
+        try {
+            info = await new web3_js_1.Connection(url, 'finalized').getAccountInfo(address, 'finalized');
+        }
+        catch (error) {
+            lastError = error;
+            continue;
+        }
+        if (!info)
+            throw new errors_1.InvalidReadQueryError(`token mint does not exist: ${mint}`);
+        if (!info.owner.equals(svm_1.TOKEN_PROGRAM_ID) && !info.owner.equals(svm_1.TOKEN_2022_PROGRAM_ID)) {
+            throw new errors_1.InvalidReadQueryError('mint is not owned by SPL Token or Token-2022');
+        }
+        // Mint base layout: 82 bytes, initialized flag at byte 45. Token-2022
+        // extensions pad to 165 bytes and carry AccountType.Mint (1) at byte 165.
+        if (info.executable || info.data.length < 82 || info.data[45] !== 1 ||
+            (info.owner.equals(svm_1.TOKEN_PROGRAM_ID) && info.data.length !== 82) ||
+            (info.owner.equals(svm_1.TOKEN_2022_PROGRAM_ID) && info.data.length !== 82 &&
+                (info.data.length < 166 || info.data[165] !== 1))) {
+            throw new errors_1.InvalidReadQueryError('token address is not an initialized mint');
+        }
+        return info.owner;
+    }
+    throw lastError;
+}
+//# sourceMappingURL=svm-account.js.map

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

@@ -0,0 +1,13 @@
+/**
+ * PDA derivation for `read(programId, { idl, functionName, args })`.
+ *
+ * The seed layout comes from the IDL, never from a guessed encoding: Anchor
+ * records each PDA's seeds on the instruction accounts that use it. `args` fill
+ * the non-constant seeds in order, encoded as the IDL declares them.
+ */
+import type { Idl } from '@coral-xyz/anchor';
+import { PublicKey } from '@solana/web3.js';
+/** Derive the PDA of account layout `functionName` from its IDL seed template and positional `args`. */
+export declare function deriveIdlPda(idl: Idl, functionName: string, args?: readonly unknown[]): PublicKey;
+/** Whether `subject` is the IDL's program id (base58 or 0x-hex). */
+export declare function isProgramSubject(idl: Idl, subject: string): boolean;