@pushchain/core 6.0.24 → 6.0.26

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

@@ -0,0 +1,164 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ERC20_BALANCE_OF_ABI = void 0;
+exports.toReadDestination = toReadDestination;
+exports.toReadQuery = toReadQuery;
+exports.toBuildReadSpecParams = toBuildReadSpecParams;
+exports.resolveReadSpecParams = resolveReadSpecParams;
+exports.getReadQueryKey = getReadQueryKey;
+exports.toLifecycleOptions = toLifecycleOptions;
+const viem_1 = require("viem");
+const web3_js_1 = require("@solana/web3.js");
+const svm_account_1 = require("./svm-account");
+const svm_pda_1 = require("./svm-pda");
+const enums_1 = require("../constants/enums");
+const registry_1 = require("./registry");
+const read_state_1 = require("../constants/read-state");
+const destination_1 = require("./destination");
+const svm_1 = require("./envelopes/svm");
+const errors_1 = require("./errors");
+/** Just `balanceOf` — it also types the decoded result as uint256. */
+exports.ERC20_BALANCE_OF_ABI = [
+    {
+        type: 'function',
+        name: 'balanceOf',
+        stateMutability: 'view',
+        inputs: [{ name: 'account', type: 'address' }],
+        outputs: [{ name: '', type: 'uint256' }],
+    },
+];
+const QUERY_KEYS = ['token', 'abi', 'idl', 'storageSlot', 'web2'];
+function queryKind(o) {
+    if ('tokenProgram' in o)
+        throw new errors_1.InvalidReadQueryError('tokenProgram is detected from the mint; remove options.tokenProgram');
+    if ('accountName' in o)
+        throw new errors_1.InvalidReadQueryError('accountName was removed; pass the account layout as functionName (optional — inferred from the discriminator)');
+    const present = QUERY_KEYS.filter((k) => o[k] !== undefined);
+    if (present.length > 1) {
+        throw new errors_1.InvalidReadQueryError(`query keys are mutually exclusive, got ${present.join(' + ')}`);
+    }
+    if ((o.functionName !== undefined || o.args !== undefined) && o.abi === undefined && o.idl === undefined) {
+        throw new errors_1.InvalidReadQueryError('functionName and args need abi or idl');
+    }
+    return present[0] ?? 'native';
+}
+function toReadDestination(chain) {
+    return chain === enums_1.CHAIN.WEB2 ? read_state_1.WEB2_DESTINATION : { chain };
+}
+/** Build the internal query from the public grammar. Pure. */
+function toReadQuery(subject, o, resolvedTokenProgram) {
+    const dest = (0, destination_1.resolveDestination)(toReadDestination(o.chain));
+    const kind = queryKind(o);
+    if (dest.namespace === read_state_1.READ_NAMESPACE.WEB2) {
+        if (kind !== 'web2' || !o.web2)
+            throw new errors_1.InvalidReadQueryError('a web2 read needs the `web2` option and no other query key');
+        if (!/^https:\/\//i.test(subject))
+            throw new errors_1.InvalidReadQueryError('web2 subject must be an https:// URL');
+        return { type: 'http', url: subject, ...o.web2 };
+    }
+    if (kind === 'web2')
+        throw new errors_1.InvalidReadQueryError('`web2` is only valid with chain CHAIN.WEB2');
+    if (dest.namespace === read_state_1.READ_NAMESPACE.EVM) {
+        if (!(0, viem_1.isAddress)(subject))
+            throw new errors_1.InvalidReadQueryError(`EVM subject must be an address, got ${subject}`);
+        switch (kind) {
+            case 'native':
+                return { type: 'accountBalance', target: subject };
+            case 'token': {
+                const token = o.token;
+                if (!(0, viem_1.isAddress)(token))
+                    throw new errors_1.InvalidReadQueryError(`token must be an address, got ${token}`);
+                return { type: 'contractCall', target: token, abi: exports.ERC20_BALANCE_OF_ABI, functionName: 'balanceOf', args: [subject] };
+            }
+            case 'abi':
+                if (!o.functionName)
+                    throw new errors_1.InvalidReadQueryError('abi needs functionName');
+                return { type: 'contractCall', target: subject, abi: o.abi, functionName: o.functionName, args: o.args };
+            case 'storageSlot':
+                return { type: 'storageSlot', target: subject, slot: o.storageSlot };
+            default:
+                throw new errors_1.InvalidReadQueryError(`unsupported query for eip155: ${kind}`);
+        }
+    }
+    // SVM: token-program ownership has already been resolved by the async public path.
+    switch (kind) {
+        case 'native':
+            return { type: 'lamportBalance', account: subject };
+        case 'token':
+            if (!resolvedTokenProgram)
+                throw new errors_1.InvalidReadQueryError('Solana token reads need mint-owner resolution; use universal.prepareRead or universal.read');
+            return { type: 'splTokenAccount', account: (0, svm_1.deriveAssociatedTokenAddress)(subject, o.token, resolvedTokenProgram).toBase58() };
+        case 'idl':
+            return toIdlAccountQuery(subject, o);
+        default:
+            throw new errors_1.InvalidReadQueryError(`unsupported query for solana: ${kind}; use idl for account-state decoding`);
+    }
+}
+/**
+ * `idl` → a raw account read that decodes with the IDL. The subject is the account,
+ * or the program id when `args` are the seeds of the `functionName` PDA.
+ */
+function toIdlAccountQuery(subject, o) {
+    const idl = o.idl;
+    (0, svm_account_1.validateIdl)(idl);
+    const accountName = o.functionName === undefined ? undefined : (0, svm_account_1.resolveAccountName)(idl, o.functionName);
+    if ((0, svm_pda_1.isProgramSubject)(idl, subject)) {
+        if (!o.functionName)
+            throw new errors_1.InvalidReadQueryError('the subject is the program id: pass functionName (the account layout) and args (its PDA seeds) to derive the account');
+        const pda = (0, svm_pda_1.deriveIdlPda)(idl, o.functionName, o.args ?? []);
+        return { type: 'rawAccountData', account: pda.toBase58(), idl, accountName };
+    }
+    if (o.args !== undefined)
+        throw new errors_1.InvalidReadQueryError('with idl, args are PDA seeds and need the program id as the subject');
+    try {
+        new web3_js_1.PublicKey(subject);
+    }
+    catch {
+        throw new errors_1.InvalidReadQueryError(`Solana subject must be a base58 pubkey, got ${subject}`);
+    }
+    return { type: 'rawAccountData', account: subject, idl, accountName };
+}
+/** Public options → the spec builder's params. Pure; throws `InvalidReadQueryError` on a malformed request. */
+function toBuildReadSpecParams(subject, o, network = enums_1.PUSH_NETWORK.TESTNET_DONUT, resolvedTokenProgram) {
+    const destination = toReadDestination(o.chain);
+    const namespace = (0, destination_1.resolveDestination)(destination).namespace;
+    if (namespace !== read_state_1.READ_NAMESPACE.EVM && (o.blockNumber !== undefined || o.minConfirmations !== undefined)) {
+        throw new errors_1.InvalidReadQueryError(`${namespace} reads do not expose blockNumber or minConfirmations; the SDK selects the read reference internally`);
+    }
+    const query = toReadQuery(subject, o, resolvedTokenProgram);
+    const callback = (0, registry_1.resolveReadCallback)(o.callback, network, (0, registry_1.computeReadQueryKey)(destination, query));
+    return {
+        callback,
+        destination,
+        query,
+        callbackGasLimit: callback.gasLimit,
+        refundTo: o.refundTo,
+        minConfirmations: o.minConfirmations,
+        blockNumber: o.blockNumber,
+        expiryBlocks: o.expiryBlocks,
+        maxFee: o.maxFee,
+    };
+}
+/** Resolve Solana mint ownership before the otherwise-pure options conversion. */
+async function resolveReadSpecParams(subject, o, network, rpcUrls) {
+    const kind = queryKind(o);
+    const namespace = (0, destination_1.resolveDestination)(toReadDestination(o.chain)).namespace;
+    if (namespace === read_state_1.READ_NAMESPACE.SVM && kind === 'token') {
+        new web3_js_1.PublicKey(subject);
+        const program = await (0, svm_account_1.detectTokenProgram)(o.token, o.chain, rpcUrls[o.chain]);
+        return toBuildReadSpecParams(subject, o, network, program);
+    }
+    return toBuildReadSpecParams(subject, o, network);
+}
+/** Internal offline key helper. Solana token callers must use PreparedRead.queryKey after mint resolution. */
+function getReadQueryKey(subject, options) {
+    return (0, registry_1.computeReadQueryKey)(toReadDestination(options.chain), toReadQuery(subject, options));
+}
+function toLifecycleOptions(o) {
+    return {
+        pollingIntervalMs: o?.advanced?.pollingIntervalMs,
+        timeoutMs: o?.advanced?.timeout,
+        resultShape: o?.resultShape,
+    };
+}
+//# sourceMappingURL=read-params.js.map

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

@@ -0,0 +1,458 @@
+import type { Abi, Address, Hex } from 'viem';
+import type { Idl } from '@coral-xyz/anchor';
+import type { CHAIN } from '../constants/enums';
+import type { ReadNamespace } from '../constants/read-state';
+/**
+ * Where a read goes. `CHAIN` enum values are CAIP-2 and split cleanly; the
+ * explicit form is the low-level escape hatch; the public API uses `CHAIN.WEB2`.
+ */
+export type ReadChain = CHAIN | typeof CHAIN.WEB2;
+export type ReadDestination = {
+    chain: ReadChain;
+} | {
+    chainNamespace: string;
+    chainId: string;
+};
+export type ResolvedDestination = {
+    chainNamespace: string;
+    chainId: string;
+    /** `${chainNamespace}:${chainId}` — the key the oracle and the node route on. */
+    caip2: string;
+    namespace: ReadNamespace;
+};
+export type EvmReadQuery = {
+    type: 'accountBalance';
+    target: Address;
+} | {
+    type: 'contractCall';
+    target: Address;
+    callData: Hex;
+} | {
+    type: 'contractCall';
+    target: Address;
+    /** encodes the call AND decodes the result */
+    abi: Abi;
+    functionName: string;
+    args?: readonly unknown[];
+} | {
+    type: 'storageSlot';
+    target: Address;
+    slot: Hex | bigint;
+};
+/** The account being read rides in `ReadSpec.account.owner` as a raw 32-byte pubkey, not in the envelope. */
+export type SvmReadQuery = {
+    type: 'lamportBalance';
+    account: string | Uint8Array;
+} | {
+    type: 'splTokenAccount';
+    account: string | Uint8Array;
+} | {
+    type: 'rawAccountData';
+    account: string | Uint8Array;
+    idl?: Idl; /** Omitted → layout inferred from the discriminator. */
+    accountName?: string;
+};
+export type Web2ValueType = 'uint256' | 'int256' | 'bool' | 'string' | 'bytes';
+export interface Web2Extract {
+    /** JSONPath, e.g. "$.data.price" */
+    path: string;
+    valueType: Web2ValueType;
+    /** Numeric only. Value × 10^decimals, TRUNCATED before encoding. */
+    decimals?: number;
+}
+export interface Web2ReadQuery {
+    type: 'http';
+    method?: 'GET' | 'POST';
+    url: string;
+    /** ⚠ Written to a public event log, forever. */
+    headers?: Record<string, string>;
+    /** POST only */
+    body?: string | Uint8Array;
+    timeoutMs?: number;
+    /** 1–16 entries; result values come back in this order. */
+    extract: readonly Web2Extract[];
+}
+export type ReadQuery = EvmReadQuery | SvmReadQuery | Web2ReadQuery;
+export type ReadResultShape = {
+    kind: 'svmAccount';
+    idl: Idl; /** Omitted → layout inferred from the discriminator. */
+    accountName?: string;
+} | {
+    kind: 'uint256';
+} | {
+    kind: 'bytes32';
+} | {
+    kind: 'raw';
+} | {
+    kind: 'evmCall';
+    abi: Abi;
+    functionName: string;
+} | {
+    kind: 'web2';
+    extract: readonly Web2Extract[];
+};
+export interface EncodedReadQuery {
+    namespace: ReadNamespace;
+    queryType: number;
+    /** abi.encode(envelope tuple) — goes into ReadSpec.query */
+    encoded: Hex;
+    /** EVM: pinned block. SVM: minSlot floor. Web2: 0. Mirrored into ReadSpec.blockNumber by the spec builder. */
+    blockRef: bigint;
+    resultShape: ReadResultShape;
+    /** SVM only: the raw 32-byte pubkey that MUST go in ReadSpec.account.owner. */
+    ownerBytes?: Hex;
+    /** Non-fatal advisories (e.g. a sensitive-looking web2 header). */
+    warnings: string[];
+}
+export type DecodedReadResult = {
+    kind: 'svmAccount';
+    value: unknown; /** The IDL layout the data decoded as. */
+    accountName: string;
+} | {
+    kind: 'uint256';
+    value: bigint;
+} | {
+    kind: 'bytes32';
+    value: Hex;
+} | {
+    kind: 'raw';
+    value: Hex;
+} | {
+    kind: 'evmCall';
+    value: unknown;
+} | {
+    kind: 'web2';
+    values: readonly unknown[];
+};
+export interface ReadPreflight {
+    destination: ResolvedDestination;
+    /** `UniversalCallback.estimateFee(ns, chainId)` — the protocol fee ONLY. 0 on Donut today. */
+    protocolFee: bigint;
+    /**
+     * `UniversalCore.chainHeightByChainNamespace(caip2)` — the oracle-observed height of the
+     * destination and the ceiling for `blockNumber`. Lags the real head. 0 for heightless
+     * namespaces (web2), where `blockNumber` must then be 0.
+     */
+    observedChainHeight: bigint;
+    /** Current Push Chain height, for expiry. */
+    pushBlockNumber: bigint;
+    /** Push gas price used to size the callback budget. */
+    pushGasPrice: bigint;
+    universalCallback: Address;
+    universalCore: Address;
+    /** Date.now() at fetch — pushBlockNumber moves every block; a stale preflight can miss expiry. */
+    fetchedAt: number;
+}
+export interface ReadSpec {
+    account: {
+        chainNamespace: string;
+        chainId: string;
+        owner: Hex;
+    };
+    query: Hex;
+    /** uint16, ≥ 1 */
+    minConfirmations: number;
+    /** uint64. Heightless namespaces (web2) MUST be 0; else 1..oracleHeight */
+    blockNumber: bigint;
+    /** uint64, > current Push height */
+    expiryPushChainHeight: bigint;
+    /** ≥ msg.value */
+    maxFee: bigint;
+    /** ≠ 0. Refunds are PUSHED here. */
+    revertRecipient: Address;
+}
+/** Positional form for `encodeFunctionData` / `encodeAbiParameters`. */
+export type ReadSpecTuple = readonly [
+    readonly [string, string, Hex],
+    Hex,
+    number,
+    bigint,
+    bigint,
+    bigint,
+    Address
+];
+export interface ReadCallback {
+    target?: Address;
+    /** Gas for the result callback, not the request entrypoint. */
+    gasLimit?: bigint;
+    /** Public payable request entrypoint on the application contract. */
+    abi?: Abi;
+    functionName?: string;
+    /** Defaults to (spec, callbackGasLimit). Must request exactly one read with this spec. */
+    args?: (spec: ReadSpecTuple, callbackGasLimit: bigint) => readonly unknown[];
+}
+export interface BuildReadSpecParams {
+    callback?: ReadCallback;
+    destination: ReadDestination;
+    query: ReadQuery;
+    /** 1n..1_000_000n. Execution bound on YOUR callback; also sizes the budget. */
+    callbackGasLimit: bigint;
+    /**
+     * Where unspent budget is PUSHED (ReadSpec.revertRecipient). Required by the contract.
+     * Default: the sending account (a UEA has a payable receive()). A non-UEA contract
+     * without one forfeits the refund — prepareRead warns.
+     */
+    refundTo?: Address;
+    /** EVM/web2 only: ReadSpec.account.owner. Ignored by validators for EVM; defaults to refundTo. SVM derives it from the query. */
+    owner?: Hex;
+    /** ≥ 1. Default 1. */
+    minConfirmations?: number;
+    /** Pinned destination height. Default observedChainHeight − minConfirmations (≥ 1). Web2: forced to 0. */
+    blockNumber?: bigint;
+    /** Default 300n. */
+    expiryBlocks?: bigint;
+    /** Absolute override for expiryBlocks. */
+    expiryPushChainHeight?: bigint;
+    /** Escrowed on top of the protocol fee. Default sizeCallbackBudget(gasLimit, gasPrice). Must be > 0. */
+    callbackBudget?: bigint;
+    /** Multiplier used by the default budget. */
+    budgetBuffer?: number;
+    /** Cap on msg.value. Default value × (1 + maxFeeBufferBps/10_000). */
+    maxFee?: bigint;
+    maxFeeBufferBps?: number;
+}
+declare const preparedReadValue: unique symbol;
+export interface PreparedRead<T = unknown> {
+    /** SDK logical query identity, independent of pinning and payment. */
+    queryKey: Hex;
+    /** Type-only result metadata retained through preparation and execution. */
+    readonly [preparedReadValue]?: T;
+    /** App request entrypoint retained for read()/executeReads(). */
+    callback?: ReadCallback;
+    /** Public destination identifier used to prepare this read. */
+    chain: ReadChain;
+    spec: ReadSpec;
+    /** Positional form for viem calls. */
+    specTuple: ReadSpecTuple;
+    /** abi.encode(spec) for hand-assembled calldata. */
+    encodedSpec: Hex;
+    /** msg.value to send: protocolFee + callbackBudget. */
+    value: bigint;
+    protocolFee: bigint;
+    callbackBudget: bigint;
+    /** The same three numbers, grouped: `total` === `value`. */
+    fees: {
+        protocolFee: bigint;
+        callbackBudget: bigint;
+        total: bigint;
+    };
+    callbackGasLimit: bigint;
+    /** Carries the result shape for decoding, and any encoder warnings. */
+    encodedQuery: EncodedReadQuery;
+    /** Public decoder description retained through execution. */
+    resultShape: ReadResultShape;
+    preflight: ReadPreflight;
+    /** Advisories: sensitive headers, refundTo is a non-UEA contract, … */
+    warnings: string[];
+}
+export type SimulateReadResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+    errorName?: string;
+    args?: readonly unknown[];
+};
+export interface ParsedReadRequest {
+    /** 32-byte topic hex, lowercase — the node's primary key */
+    requestId: Hex;
+    requestIdUint: bigint;
+    callbackTarget: Address;
+    originalFunder: Address;
+    spec: ReadSpec;
+    callbackGasLimit: bigint;
+    totalPaid: bigint;
+    protocolFee: bigint;
+    callbackBudget: bigint;
+    logIndex: number;
+}
+/** What the fulfil / settle / expiry transactions said, parsed from UniversalCallback logs. */
+export interface FulfilOutcome {
+    /** true = ReadFulfilled, false = CallbackFailed, undefined = neither seen in this receipt */
+    delivered?: boolean;
+    /** revert data from CallbackFailed */
+    failReason?: Hex;
+    gasReported?: bigint;
+    burned?: bigint;
+    refunded?: bigint;
+    refundTo?: Address;
+    /** RefundFailed seen — budget forfeited to the admin rescue pool */
+    refundFailed?: boolean;
+    /** RequestExpired seen */
+    expired?: boolean;
+}
+/** Minimal structural receipt — works with viem receipts and `cast receipt --json`. */
+export interface ReceiptLike {
+    logs: readonly {
+        address: string;
+        topics: readonly string[];
+        data: string;
+        logIndex?: number | string;
+    }[];
+}
+export type ReadRef = {
+    txHash: Hex;
+} | {
+    requestId: Hex | bigint;
+};
+export interface ReadLifecycleOptions {
+    /** Default `expiryBlocks × PUSH_BLOCK_TIME_MS`, capped at READ_TRACK_MAX_TIMEOUT_MS. */
+    timeoutMs?: number;
+    /** Default READ_TRACK_POLL_INTERVAL_MS; floor READ_TRACK_MIN_POLL_INTERVAL_MS. */
+    pollingIntervalMs?: number;
+    /**
+     * How to decode `resultData`. When omitted the tracker infers it from the on-chain
+     * envelope (balances → uint256, storage → bytes32, web2 → its extract list); a
+     * contract call has no ABI on chain and decodes to raw bytes unless given here.
+     */
+    resultShape?: ReadResultShape;
+}
+/** Accounting for one read, assembled from the request record and the settlement logs. */
+export interface ReadFees {
+    /** msg.value at request time (`feesDeposited`) */
+    paid: bigint;
+    /** gone at request time, never refunded */
+    protocolFee: bigint;
+    /** escrowed for the callback */
+    callbackBudget: bigint;
+    /** consumed by the callback — `CallbackGasReported` */
+    burned?: bigint;
+    /** pushed back to `refundTo` — `RefundSent` / `RequestExpired` */
+    /** Unknown for EndBlock expiry: EXPIRED does not prove the recipient accepted payment. */
+    refunded?: bigint;
+    /** the push was rejected — budget sits in the admin rescue pool */
+    refundFailed?: boolean;
+}
+export interface UniversalReadResponse<T = unknown> {
+    requestId: Hex;
+    /** `requestId` as the `uint256` contracts key results by (e.g. registry `resultByRequestId`). */
+    requestIdUint: bigint;
+    /** Push tx that carried the request */
+    txHash: Hex;
+    destination: ResolvedDestination;
+    /** Required read destination, including `CHAIN.WEB2`. */
+    chain: ReadChain;
+    /**
+     * The one field that answers "did it work": `SUCCESS` means the source read
+     * succeeded, your callback ran, and `value` is set (when a shape is known).
+     * Derived by the SDK from `status`, `raw.status`, `callbackDelivered` and
+     * `decodeError`, which stay available for debugging.
+     */
+    outcome: READ_OUTCOME;
+    status: UNIVERSAL_READ_STATUS;
+    isTerminal: boolean;
+    /**
+     * FULFILLED only. true = `ReadFulfilled`; false = `CallbackFailed` (your callback
+     * reverted / ran out of gas). FULFILLED does NOT imply delivered — check both.
+     */
+    callbackDelivered?: boolean;
+    /** Revert data from `CallbackFailed`. */
+    callbackFailReason?: Hex;
+    /** Decoded result. Present iff FULFILLED && callbackDelivered && result SUCCESS && decodable. */
+    value?: T;
+    decoded?: DecodedReadResult;
+    /** Why `value` is absent although the read succeeded (shape mismatch). */
+    decodeError?: string;
+    /** Consensus bytes — what ⅔ of validators voted on. `null` before a result exists. */
+    raw: {
+        status: READ_STATUS;
+        resultData: Hex;
+        errorCode: READ_ERROR_CODE;
+    } | null;
+    errorMsg: string;
+    fees: ReadFees;
+    request: {
+        spec: ReadSpec;
+        callbackTarget: Address;
+        /** who paid (msg.sender at request) — NOT where refunds go */
+        originalFunder: Address;
+        /** where refunds go */
+        refundTo: Address;
+        callbackGasLimit: bigint;
+        logIndex: number;
+        createdAtHeight: bigint;
+    };
+    /** Push txs the node sent for this read (fulfil, settle, expiry sweep). */
+    pcTx: readonly {
+        txHash: Hex;
+        blockHeight: number;
+        status: string;
+        errorMsg: string;
+    }[];
+    explorerUrl: string;
+    /** Poll until terminal (or already terminal → resolves at once). Only a timeout throws. */
+    wait(opts?: ReadLifecycleOptions): Promise<UniversalReadResponse<T>>;
+    /** One fresh snapshot, no polling. */
+    refresh(): Promise<UniversalReadResponse<T>>;
+}
+export type ReadResponseTuple<R extends readonly PreparedRead[]> = {
+    -readonly [K in keyof R]: UniversalReadResponse<R[K] extends PreparedRead<infer T> ? T : unknown>;
+};
+/** One execution containing one or more independently settled read requests. */
+export interface BatchReadResponse<R extends readonly PreparedRead[] = readonly PreparedRead[]> {
+    /** Primary Push transaction hash. For sequential fallback, see `transactionHashes`. */
+    txHash: Hex;
+    /** All request transactions in submission order when execution was non-atomic. */
+    transactionHashes?: readonly Hex[];
+    reads: ReadResponseTuple<R>;
+    count: number;
+    atomic: boolean;
+    /** Wait until every read is terminal. Terminal failures resolve; only timeout throws. */
+    wait(opts?: Omit<ReadLifecycleOptions, 'resultShape'>): Promise<ReadResponseTuple<R>>;
+}
+export declare enum UNIVERSAL_READ_STATUS {
+    UNSPECIFIED = 0,
+    PENDING = 1,
+    VOTING = 2,
+    /** fulfil tx succeeded — check `callbackDelivered` before trusting the result */
+    FULFILLED = 3,
+    EXPIRED = 4,
+    /** contract had already settled the request another way */
+    FAILED = 5,
+    ABORTED = 6
+}
+export declare enum READ_STATUS {
+    UNSPECIFIED = 0,
+    SUCCESS = 1,
+    ERROR = 2
+}
+export declare enum READ_ERROR_CODE {
+    UNSPECIFIED = 0,
+    INVALID_QUERY = 1,
+    UNSUPPORTED = 2,
+    REVERTED = 3,
+    NOT_FOUND = 4,
+    INVALID_RESULT = 5,
+    REJECTED = 6
+}
+/**
+ * SDK-derived single outcome. FULFILLED on the node only means the fulfil tx
+ * landed; this separates the ways a FULFILLED read can still not have worked.
+ */
+export declare enum READ_OUTCOME {
+    /** Not terminal yet. */
+    PENDING = "PENDING",
+    /** Source SUCCESS, callback delivered, result decoded (or no shape to decode with). */
+    SUCCESS = "SUCCESS",
+    /** FULFILLED, but the destination returned an error (`raw.errorCode`). */
+    SOURCE_ERROR = "SOURCE_ERROR",
+    /** FULFILLED, but the receiver callback reverted or ran out of gas (`callbackFailReason`). */
+    CALLBACK_FAILED = "CALLBACK_FAILED",
+    /** Delivered, but `resultData` did not match the expected shape (`decodeError`). */
+    DECODE_FAILED = "DECODE_FAILED",
+    EXPIRED = "EXPIRED",
+    FAILED = "FAILED",
+    ABORTED = "ABORTED",
+    /** FULFILLED, but the fulfil receipt was unavailable, so delivery cannot be confirmed. */
+    UNKNOWN = "UNKNOWN"
+}
+/** On-chain lifecycle (`RequestStatus` in ReadTypes.sol). */
+export declare enum CONTRACT_REQUEST_STATUS {
+    NONE = 0,
+    PENDING = 1,
+    EXECUTED = 2,
+    SETTLED = 3,
+    EXPIRED = 4
+}
+export declare const TERMINAL_READ_STATUSES: ReadonlySet<UNIVERSAL_READ_STATUS>;
+export {};