@pushchain/core 6.0.23 → 6.0.25

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

@@ -0,0 +1,29 @@
+import { type Hex } from 'viem';
+import type { EncodedReadQuery, Web2ReadQuery, Web2ValueType } from '../read-state.types';
+/** `universalClient/externalchains/web2/read_envelope.go`. */
+export declare const WEB2_METHOD: {
+    readonly GET: 0;
+    readonly POST: 1;
+};
+export declare const WEB2_VALUE_TYPE: Record<Web2ValueType, number>;
+/**
+ * Deterministic JSON object bytes: keys sorted, no whitespace. The validator
+ * `json.Unmarshal`s into map[string]string, so ordering does not affect the read —
+ * canonicalising just keeps the on-chain envelope stable across SDK versions.
+ */
+export declare function canonicalizeHeaders(headers: Record<string, string> | undefined): Hex;
+/** Encode a `web2` read query. Pure. `blockRef` is always 0 (heightless namespace). */
+export declare function encodeWeb2QueryEnvelope(query: Web2ReadQuery): EncodedReadQuery;
+export declare function decodeWeb2QueryEnvelope(encoded: Hex): {
+    method: number;
+    url: string;
+    headers: Record<string, string>;
+    body: Hex;
+    timeoutMs: bigint;
+    extract: {
+        path: string;
+        valueType: number;
+        mode: number;
+        decimals: number;
+    }[];
+};

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

@@ -0,0 +1,149 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WEB2_VALUE_TYPE = exports.WEB2_METHOD = void 0;
+exports.canonicalizeHeaders = canonicalizeHeaders;
+exports.encodeWeb2QueryEnvelope = encodeWeb2QueryEnvelope;
+exports.decodeWeb2QueryEnvelope = decodeWeb2QueryEnvelope;
+const viem_1 = require("viem");
+const read_state_1 = require("../../constants/read-state");
+const errors_1 = require("../errors");
+/** `universalClient/externalchains/web2/read_envelope.go`. */
+exports.WEB2_METHOD = { GET: 0, POST: 1 };
+exports.WEB2_VALUE_TYPE = {
+    uint256: 0,
+    int256: 1,
+    bool: 2,
+    string: 3,
+    bytes: 4,
+};
+/** Only IDENTICAL (quorum on identical bytes) exists in v1. */
+const WEB2_MODE_IDENTICAL = 0;
+const WEB2_ENVELOPE_ABI = [
+    {
+        type: 'tuple',
+        components: [
+            { name: 'method', type: 'uint8' },
+            { name: 'url', type: 'string' },
+            { name: 'headers', type: 'bytes' },
+            { name: 'body', type: 'bytes' },
+            { name: 'timeoutMs', type: 'uint64' },
+            {
+                name: 'extract',
+                type: 'tuple[]',
+                components: [
+                    { name: 'path', type: 'string' },
+                    { name: 'valueType', type: 'uint8' },
+                    { name: 'mode', type: 'uint8' },
+                    { name: 'decimals', type: 'uint8' },
+                ],
+            },
+        ],
+    },
+];
+const SENSITIVE_HEADER = /auth|key|token|secret|bearer|cookie|session/i;
+const NUMERIC = new Set(['uint256', 'int256']);
+/**
+ * Deterministic JSON object bytes: keys sorted, no whitespace. The validator
+ * `json.Unmarshal`s into map[string]string, so ordering does not affect the read —
+ * canonicalising just keeps the on-chain envelope stable across SDK versions.
+ */
+function canonicalizeHeaders(headers) {
+    const entries = Object.entries(headers ?? {});
+    if (entries.length === 0)
+        return (0, viem_1.stringToHex)('{}');
+    for (const [k, v] of entries) {
+        if (typeof v !== 'string')
+            throw new errors_1.InvalidReadQueryError(`header ${k} must be a string`);
+    }
+    const sorted = Object.fromEntries(entries.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+    return (0, viem_1.stringToHex)(JSON.stringify(sorted));
+}
+function toBodyHex(body) {
+    if (body === undefined)
+        return '0x';
+    return typeof body === 'string' ? (0, viem_1.stringToHex)(body) : (0, viem_1.bytesToHex)(body);
+}
+function validateExtract(extract) {
+    if (!Array.isArray(extract) || extract.length === 0) {
+        throw new errors_1.InvalidReadQueryError('web2 query needs at least one extract entry');
+    }
+    if (extract.length > read_state_1.WEB2_MAX_EXTRACT_ENTRIES) {
+        throw new errors_1.InvalidReadQueryError(`web2 query has ${extract.length} extracts; max is ${read_state_1.WEB2_MAX_EXTRACT_ENTRIES}`);
+    }
+    extract.forEach((e, i) => {
+        if (!e.path || !e.path.startsWith('$')) {
+            throw new errors_1.InvalidReadQueryError(`extract[${i}].path must be a JSONPath starting with "$": ${e.path}`);
+        }
+        if (!(e.valueType in exports.WEB2_VALUE_TYPE)) {
+            throw new errors_1.InvalidReadQueryError(`extract[${i}].valueType unknown: ${String(e.valueType)}`);
+        }
+        if (e.decimals !== undefined) {
+            if (!NUMERIC.has(e.valueType)) {
+                throw new errors_1.InvalidReadQueryError(`extract[${i}].decimals only applies to uint256/int256`);
+            }
+            if (!Number.isInteger(e.decimals) || e.decimals < 0 || e.decimals > 255) {
+                throw new errors_1.InvalidReadQueryError(`extract[${i}].decimals must be an integer 0..255`);
+            }
+        }
+    });
+}
+/** Encode a `web2` read query. Pure. `blockRef` is always 0 (heightless namespace). */
+function encodeWeb2QueryEnvelope(query) {
+    const method = query.method ?? 'GET';
+    if (method !== 'GET' && method !== 'POST')
+        throw new errors_1.InvalidReadQueryError(`unsupported method: ${String(method)}`);
+    if (!/^https:\/\/\S+$/i.test(query.url)) {
+        throw new errors_1.InvalidReadQueryError('web2 url must be https:// — validators refuse other schemes');
+    }
+    if (method === 'GET' && query.body !== undefined) {
+        throw new errors_1.InvalidReadQueryError('body is only allowed with POST');
+    }
+    const timeoutMs = query.timeoutMs ?? read_state_1.WEB2_DEFAULT_TIMEOUT_MS;
+    if (!Number.isInteger(timeoutMs) || timeoutMs <= 0)
+        throw new errors_1.InvalidReadQueryError('timeoutMs must be a positive integer');
+    validateExtract(query.extract);
+    const warnings = [];
+    for (const name of Object.keys(query.headers ?? {})) {
+        if (SENSITIVE_HEADER.test(name)) {
+            warnings.push(`header "${name}" looks sensitive and will be written to a PUBLIC event log forever`);
+        }
+    }
+    if (timeoutMs > read_state_1.WEB2_MAX_TIMEOUT_MS) {
+        warnings.push(`timeoutMs ${timeoutMs} exceeds the validator clamp of ${read_state_1.WEB2_MAX_TIMEOUT_MS}`);
+    }
+    const encoded = (0, viem_1.encodeAbiParameters)(WEB2_ENVELOPE_ABI, [
+        {
+            method: exports.WEB2_METHOD[method],
+            url: query.url,
+            headers: canonicalizeHeaders(query.headers),
+            body: toBodyHex(query.body),
+            timeoutMs: BigInt(timeoutMs),
+            extract: query.extract.map((e) => ({
+                path: e.path,
+                valueType: exports.WEB2_VALUE_TYPE[e.valueType],
+                mode: WEB2_MODE_IDENTICAL,
+                decimals: e.decimals ?? 0,
+            })),
+        },
+    ]);
+    return {
+        namespace: read_state_1.READ_NAMESPACE.WEB2,
+        queryType: exports.WEB2_METHOD[method],
+        encoded,
+        blockRef: 0n,
+        resultShape: { kind: 'web2', extract: query.extract },
+        warnings,
+    };
+}
+function decodeWeb2QueryEnvelope(encoded) {
+    const [env] = (0, viem_1.decodeAbiParameters)(WEB2_ENVELOPE_ABI, encoded);
+    return {
+        method: env.method,
+        url: env.url,
+        headers: env.headers === '0x' ? {} : JSON.parse((0, viem_1.hexToString)(env.headers)),
+        body: env.body,
+        timeoutMs: env.timeoutMs,
+        extract: env.extract.map((e) => ({ ...e })),
+    };
+}
+//# sourceMappingURL=web2.js.map

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

@@ -0,0 +1,70 @@
+/**
+ * Typed read-state errors.
+ *
+ * Every error carries a stable `code` so callers classify by `instanceof` or
+ * `err.code`, plus curated context and a remediation hint. Mirrors the PC20 error
+ * family (`orchestrator/internals/pc20/errors.ts`).
+ */
+export type ReadStateErrorContext = {
+    /** Destination in CAIP-2 form, when relevant. */
+    destination?: string;
+    /** requestId (0x-prefixed hex), when relevant. */
+    requestId?: string;
+    /** Push tx hash, when relevant. */
+    txHash?: string;
+    /** Successfully mined requests from a partial non-atomic batch. */
+    transactionHashes?: `0x${string}`[];
+    /** Broadcast transaction whose receipt could not be confirmed. Check before retrying. */
+    pendingTransactionHash?: `0x${string}`;
+    /** Short, actionable remediation. */
+    hint?: string;
+};
+/** Base class for all read-state failures. `instanceof ReadStateError` catches the family. */
+export declare class ReadStateError extends Error {
+    readonly code: string;
+    readonly destination?: string;
+    readonly requestId?: string;
+    readonly txHash?: string;
+    readonly transactionHashes?: `0x${string}`[];
+    readonly pendingTransactionHash?: `0x${string}`;
+    readonly hint?: string;
+    constructor(code: string, message: string, ctx?: ReadStateErrorContext);
+}
+/** The query itself is malformed (bad target, non-view ABI function, too many extracts, …). */
+export declare class InvalidReadQueryError extends ReadStateError {
+    constructor(message: string, ctx?: ReadStateErrorContext);
+}
+/** Every contract precondition the SDK mirrors client-side. Names match `UniversalCallbackErrors`. */
+export type ReadSpecViolation = 'INVALID_ACCOUNT_ID' | 'EMPTY_QUERY' | 'INVALID_MIN_CONFIRMATIONS' | 'DOMAIN_BLOCKED' | 'INVALID_BLOCK_NUMBER' | 'INVALID_EXPIRY_HEIGHT' | 'ZERO_REVERT_RECIPIENT' | 'ZERO_CALLBACK_GAS_LIMIT' | 'CALLBACK_GAS_LIMIT_EXCEEDED' | 'INSUFFICIENT_FEE' | 'EXCESSIVE_FEE' | 'ZERO_CALLBACK_BUDGET'
+/** Node affordability gate: remaining escrow must cover declared gas at current base fee. */
+ | 'INSUFFICIENT_CALLBACK_BUDGET' | 'SVM_OWNER_NOT_32_BYTES';
+/** A `ReadSpec` that `requestExternalReadSelf` would revert on. */
+export declare class InvalidReadSpecError extends ReadStateError {
+    readonly violations: readonly ReadSpecViolation[];
+    constructor(violations: readonly ReadSpecViolation[], ctx?: ReadStateErrorContext);
+}
+/** The destination's oracle height is zero — it is not a configured chain. */
+export declare class ReadHeightUnavailableError extends ReadStateError {
+    constructor(destination: string, ctx?: ReadStateErrorContext);
+}
+/** Destination is not one the read path can route (unknown namespace, or on-chain blacklist). */
+export declare class UnsupportedReadDestinationError extends ReadStateError {
+    constructor(message: string, ctx?: ReadStateErrorContext);
+}
+/** `resultData` does not match the shape the query declared. Fails loud, never mis-decodes. */
+export declare class ReadDecodeError extends ReadStateError {
+    constructor(message: string, ctx?: ReadStateErrorContext);
+}
+/** Client-side polling deadline hit before a terminal status. Carries the last status seen. */
+export declare class ReadTimeoutError extends ReadStateError {
+    readonly lastStatus: number;
+    constructor(lastStatus: number, elapsedMs: number, ctx?: ReadStateErrorContext);
+}
+/** No `UniversalRead` record for the reference — not ingested yet, or the tx made no read. */
+export declare class ReadNotFoundError extends ReadStateError {
+    constructor(ref: string, ctx?: ReadStateErrorContext);
+}
+/** No custom receiver was supplied and this network has no configured registry. */
+export declare class ReadRegistryUnavailableError extends ReadStateError {
+    constructor(method: string, ctx?: ReadStateErrorContext);
+}

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

@@ -0,0 +1,116 @@
+"use strict";
+/**
+ * Typed read-state errors.
+ *
+ * Every error carries a stable `code` so callers classify by `instanceof` or
+ * `err.code`, plus curated context and a remediation hint. Mirrors the PC20 error
+ * family (`orchestrator/internals/pc20/errors.ts`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReadRegistryUnavailableError = exports.ReadNotFoundError = exports.ReadTimeoutError = exports.ReadDecodeError = exports.UnsupportedReadDestinationError = exports.ReadHeightUnavailableError = exports.InvalidReadSpecError = exports.InvalidReadQueryError = exports.ReadStateError = void 0;
+/** Base class for all read-state failures. `instanceof ReadStateError` catches the family. */
+class ReadStateError extends Error {
+    code;
+    destination;
+    requestId;
+    txHash;
+    transactionHashes;
+    pendingTransactionHash;
+    hint;
+    constructor(code, message, ctx = {}) {
+        const parts = [message];
+        if (ctx.destination)
+            parts.push(`destination=${ctx.destination}`);
+        if (ctx.requestId)
+            parts.push(`requestId=${ctx.requestId}`);
+        if (ctx.txHash)
+            parts.push(`txHash=${ctx.txHash}`);
+        if (ctx.hint)
+            parts.push(`hint: ${ctx.hint}`);
+        super(parts.join(' | '));
+        this.name = new.target.name;
+        this.code = code;
+        this.destination = ctx.destination;
+        this.requestId = ctx.requestId;
+        this.txHash = ctx.txHash;
+        this.transactionHashes = ctx.transactionHashes ? [...ctx.transactionHashes] : undefined;
+        this.pendingTransactionHash = ctx.pendingTransactionHash;
+        this.hint = ctx.hint;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.ReadStateError = ReadStateError;
+/** The query itself is malformed (bad target, non-view ABI function, too many extracts, …). */
+class InvalidReadQueryError extends ReadStateError {
+    constructor(message, ctx = {}) {
+        super('INVALID_READ_QUERY', message, ctx);
+    }
+}
+exports.InvalidReadQueryError = InvalidReadQueryError;
+/** A `ReadSpec` that `requestExternalReadSelf` would revert on. */
+class InvalidReadSpecError extends ReadStateError {
+    violations;
+    constructor(violations, ctx = {}) {
+        super('INVALID_READ_SPEC', `ReadSpec violates contract preconditions: ${violations.join(', ')}`, ctx);
+        this.violations = violations;
+    }
+}
+exports.InvalidReadSpecError = InvalidReadSpecError;
+/** The destination's oracle height is zero — it is not a configured chain. */
+class ReadHeightUnavailableError extends ReadStateError {
+    constructor(destination, ctx = {}) {
+        super('READ_HEIGHT_UNAVAILABLE', 'destination has no observed chain height on UniversalCore', {
+            destination,
+            hint: 'Only chains with a running chain-meta oracle can be read. Check the CAIP-2 id.',
+            ...ctx,
+        });
+    }
+}
+exports.ReadHeightUnavailableError = ReadHeightUnavailableError;
+/** Destination is not one the read path can route (unknown namespace, or on-chain blacklist). */
+class UnsupportedReadDestinationError extends ReadStateError {
+    constructor(message, ctx = {}) {
+        super('UNSUPPORTED_READ_DESTINATION', message, ctx);
+    }
+}
+exports.UnsupportedReadDestinationError = UnsupportedReadDestinationError;
+/** `resultData` does not match the shape the query declared. Fails loud, never mis-decodes. */
+class ReadDecodeError extends ReadStateError {
+    constructor(message, ctx = {}) {
+        super('READ_DECODE_FAILED', message, ctx);
+    }
+}
+exports.ReadDecodeError = ReadDecodeError;
+/** Client-side polling deadline hit before a terminal status. Carries the last status seen. */
+class ReadTimeoutError extends ReadStateError {
+    lastStatus;
+    constructor(lastStatus, elapsedMs, ctx = {}) {
+        super('READ_TIMEOUT', `read did not reach a terminal status within ${elapsedMs} ms (last status ${lastStatus})`, {
+            hint: 'The request may still complete on-chain — resume with trackRead.',
+            ...ctx,
+        });
+        this.lastStatus = lastStatus;
+    }
+}
+exports.ReadTimeoutError = ReadTimeoutError;
+/** No `UniversalRead` record for the reference — not ingested yet, or the tx made no read. */
+class ReadNotFoundError extends ReadStateError {
+    constructor(ref, ctx = {}) {
+        super('READ_NOT_FOUND', `no read record for ${ref}`, {
+            hint: 'A request is indexed once its block is processed; a tx with no ReadRequested log never gets one.',
+            ...ctx,
+        });
+    }
+}
+exports.ReadNotFoundError = ReadNotFoundError;
+/** No custom receiver was supplied and this network has no configured registry. */
+class ReadRegistryUnavailableError extends ReadStateError {
+    constructor(method, ctx = {}) {
+        super('READ_REGISTRY_UNAVAILABLE', `${method} needs the UniversalReadRegistry, which is not deployed on this network`, {
+            hint: 'Pass callback.target, gasLimit, abi and functionName (plus optional args) for your app contract.',
+            ...ctx,
+        });
+    }
+}
+exports.ReadRegistryUnavailableError = ReadRegistryUnavailableError;
+//# sourceMappingURL=errors.js.map

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

@@ -0,0 +1,13 @@
+export * from './read-state.types';
+export * from './errors';
+export { resolveDestination } from './destination';
+export * from './envelopes';
+export { decodeReadResult } from './result-decoder';
+export * from './read-events';
+export { preflightRead } from './preflight';
+export { sizeCallbackBudget, MIN_CALLBACK_BUDGET_GAS_PRICE } from './budget';
+export { validateReadSpec, assertValidReadSpec } from './validate';
+export { buildReadSpecFromPreflight, prepareRead, simulateRead, toCallData, type PrepareReadDeps } from './spec-builder';
+export { trackRead, waitForRead, inferResultShape, toRequestIdHex, statusName, defaultWaitTimeoutMs, type TrackReadDeps, type ReadHookEmitter } from './read-tracker';
+export { toBuildReadSpecParams, toReadQuery, toReadDestination, toLifecycleOptions, type ReadOptions, type ReadPrepareOptions, type ReadQueryOptions, type ReadCallbackOptions, type ReadValue, type ValidateReadCall, type ReadWeb2Options, type ReadTrackOptions } from './read-params';
+export type { ReadExecuteOptions } from './read-params';

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

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toLifecycleOptions = exports.toReadDestination = exports.toReadQuery = exports.toBuildReadSpecParams = exports.defaultWaitTimeoutMs = exports.statusName = exports.toRequestIdHex = exports.inferResultShape = exports.waitForRead = exports.trackRead = exports.toCallData = exports.simulateRead = exports.prepareRead = exports.buildReadSpecFromPreflight = exports.assertValidReadSpec = exports.validateReadSpec = exports.MIN_CALLBACK_BUDGET_GAS_PRICE = exports.sizeCallbackBudget = exports.preflightRead = exports.decodeReadResult = exports.resolveDestination = void 0;
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./read-state.types"), exports);
+tslib_1.__exportStar(require("./errors"), exports);
+var destination_1 = require("./destination");
+Object.defineProperty(exports, "resolveDestination", { enumerable: true, get: function () { return destination_1.resolveDestination; } });
+tslib_1.__exportStar(require("./envelopes"), exports);
+var result_decoder_1 = require("./result-decoder");
+Object.defineProperty(exports, "decodeReadResult", { enumerable: true, get: function () { return result_decoder_1.decodeReadResult; } });
+tslib_1.__exportStar(require("./read-events"), exports);
+var preflight_1 = require("./preflight");
+Object.defineProperty(exports, "preflightRead", { enumerable: true, get: function () { return preflight_1.preflightRead; } });
+var budget_1 = require("./budget");
+Object.defineProperty(exports, "sizeCallbackBudget", { enumerable: true, get: function () { return budget_1.sizeCallbackBudget; } });
+Object.defineProperty(exports, "MIN_CALLBACK_BUDGET_GAS_PRICE", { enumerable: true, get: function () { return budget_1.MIN_CALLBACK_BUDGET_GAS_PRICE; } });
+var validate_1 = require("./validate");
+Object.defineProperty(exports, "validateReadSpec", { enumerable: true, get: function () { return validate_1.validateReadSpec; } });
+Object.defineProperty(exports, "assertValidReadSpec", { enumerable: true, get: function () { return validate_1.assertValidReadSpec; } });
+var spec_builder_1 = require("./spec-builder");
+Object.defineProperty(exports, "buildReadSpecFromPreflight", { enumerable: true, get: function () { return spec_builder_1.buildReadSpecFromPreflight; } });
+Object.defineProperty(exports, "prepareRead", { enumerable: true, get: function () { return spec_builder_1.prepareRead; } });
+Object.defineProperty(exports, "simulateRead", { enumerable: true, get: function () { return spec_builder_1.simulateRead; } });
+Object.defineProperty(exports, "toCallData", { enumerable: true, get: function () { return spec_builder_1.toCallData; } });
+var read_tracker_1 = require("./read-tracker");
+Object.defineProperty(exports, "trackRead", { enumerable: true, get: function () { return read_tracker_1.trackRead; } });
+Object.defineProperty(exports, "waitForRead", { enumerable: true, get: function () { return read_tracker_1.waitForRead; } });
+Object.defineProperty(exports, "inferResultShape", { enumerable: true, get: function () { return read_tracker_1.inferResultShape; } });
+Object.defineProperty(exports, "toRequestIdHex", { enumerable: true, get: function () { return read_tracker_1.toRequestIdHex; } });
+Object.defineProperty(exports, "statusName", { enumerable: true, get: function () { return read_tracker_1.statusName; } });
+Object.defineProperty(exports, "defaultWaitTimeoutMs", { enumerable: true, get: function () { return read_tracker_1.defaultWaitTimeoutMs; } });
+var read_params_1 = require("./read-params");
+Object.defineProperty(exports, "toBuildReadSpecParams", { enumerable: true, get: function () { return read_params_1.toBuildReadSpecParams; } });
+Object.defineProperty(exports, "toReadQuery", { enumerable: true, get: function () { return read_params_1.toReadQuery; } });
+Object.defineProperty(exports, "toReadDestination", { enumerable: true, get: function () { return read_params_1.toReadDestination; } });
+Object.defineProperty(exports, "toLifecycleOptions", { enumerable: true, get: function () { return read_params_1.toLifecycleOptions; } });
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,21 @@
+import type { PUSH_NETWORK } from '../constants/enums';
+import type { PushClient } from '../push-client/push-client';
+import type { ReadDestination, ReadPreflight } from './read-state.types';
+/** The slice of OrchestratorContext preflight needs — keeps it testable with a bare mock. */
+export interface PreflightDeps {
+    pushClient: Pick<PushClient, 'readContract' | 'getGasPrice' | 'publicClient'>;
+    pushNetwork: PUSH_NETWORK;
+}
+/**
+ * Fetch the on-chain values a valid ReadSpec depends on. Four reads against Push Chain,
+ * none against the destination:
+ *
+ *   UniversalCore.chainHeightByChainNamespace(caip2)   → blockNumber ceiling
+ *   UniversalCallback.estimateFee(ns, chainId)          → protocol fee (msg.value floor)
+ *   UniversalCallback.blockedDomains(ns, chainId)       → fail fast on a blocklisted domain
+ *   eth_blockNumber + eth_gasPrice                      → expiry + budget sizing
+ *
+ * The height is keyed by the FULL CAIP-2 id — the oracle writes it that way. Passing the
+ * bare namespace reads 0 and was the C1 blocker.
+ */
+export declare function preflightRead(deps: PreflightDeps, destination: ReadDestination): Promise<ReadPreflight>;

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

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.preflightRead = preflightRead;
+const universalCallback_evm_1 = require("../constants/abi/universalCallback.evm");
+const prc20_evm_1 = require("../constants/abi/prc20.evm");
+const chain_1 = require("../constants/chain");
+const read_state_1 = require("../constants/read-state");
+const destination_1 = require("./destination");
+const errors_1 = require("./errors");
+/**
+ * Fetch the on-chain values a valid ReadSpec depends on. Four reads against Push Chain,
+ * none against the destination:
+ *
+ *   UniversalCore.chainHeightByChainNamespace(caip2)   → blockNumber ceiling
+ *   UniversalCallback.estimateFee(ns, chainId)          → protocol fee (msg.value floor)
+ *   UniversalCallback.blockedDomains(ns, chainId)       → fail fast on a blocklisted domain
+ *   eth_blockNumber + eth_gasPrice                      → expiry + budget sizing
+ *
+ * The height is keyed by the FULL CAIP-2 id — the oracle writes it that way. Passing the
+ * bare namespace reads 0 and was the C1 blocker.
+ */
+async function preflightRead(deps, destination) {
+    const dest = (0, destination_1.resolveDestination)(destination);
+    const universalCore = chain_1.UNIVERSAL_CORE_ADDRESSES[deps.pushNetwork];
+    const universalCallback = chain_1.UNIVERSAL_CALLBACK_ADDRESSES[deps.pushNetwork];
+    const { pushClient } = deps;
+    const [observedChainHeight, protocolFee, blocked, pushBlockNumber, pushGasPrice] = await Promise.all([
+        pushClient.readContract({
+            address: universalCore,
+            abi: prc20_evm_1.UNIVERSAL_CORE_EVM,
+            functionName: 'chainHeightByChainNamespace',
+            args: [dest.caip2],
+        }),
+        pushClient.readContract({
+            address: universalCallback,
+            abi: universalCallback_evm_1.UNIVERSAL_CALLBACK_EVM,
+            functionName: 'estimateFee',
+            args: [dest.chainNamespace, dest.chainId],
+        }),
+        pushClient.readContract({
+            address: universalCallback,
+            abi: universalCallback_evm_1.UNIVERSAL_CALLBACK_EVM,
+            functionName: 'blockedDomains',
+            args: [dest.chainNamespace, dest.chainId],
+        }),
+        pushClient.publicClient.getBlockNumber(),
+        pushClient.getGasPrice(),
+    ]);
+    if (blocked) {
+        throw new errors_1.UnsupportedReadDestinationError('destination is on the UniversalCallback blocklist', {
+            destination: dest.caip2,
+        });
+    }
+    // Heightless namespaces (web2) legitimately read 0 and must pin blockNumber = 0.
+    // For a blockchain, 0 means no chain-meta oracle is voting → the guard can never pass.
+    if (dest.namespace !== read_state_1.READ_NAMESPACE.WEB2 && observedChainHeight === 0n) {
+        throw new errors_1.ReadHeightUnavailableError(dest.caip2);
+    }
+    return {
+        destination: dest,
+        protocolFee,
+        observedChainHeight,
+        pushBlockNumber,
+        pushGasPrice,
+        universalCallback,
+        universalCore,
+        fetchedAt: Date.now(),
+    };
+}
+//# sourceMappingURL=preflight.js.map

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

@@ -0,0 +1,27 @@
+import { type AbiEvent, type Address, type Hex } from 'viem';
+import type { FulfilOutcome, ParsedReadRequest, ReceiptLike } from './read-state.types';
+export declare const READ_REQUESTED_EVENT: AbiEvent;
+export declare const READ_REQUESTED_TOPIC0: Hex;
+export declare const READ_FULFILLED_TOPIC0: Hex;
+export declare const CALLBACK_FAILED_TOPIC0: Hex;
+export declare const CALLBACK_GAS_REPORTED_TOPIC0: Hex;
+export declare const REFUND_SENT_TOPIC0: Hex;
+export declare const REFUND_FAILED_TOPIC0: Hex;
+export declare const REQUEST_EXPIRED_TOPIC0: Hex;
+/**
+ * Every read a transaction requested, in log order.
+ *
+ * Filters on BOTH the contract address and topic0. The address filter is a security
+ * control (the node applies the same one in `ingest.go`): without it any contract
+ * can forge a matching log.
+ */
+export declare function parseReadRequestsFromReceipt(receipt: ReceiptLike, universalCallback: Address): ParsedReadRequest[];
+/**
+ * Read the fulfil / settle / expiry logs for ONE request out of a receipt.
+ *
+ * `FULFILLED` on the node does not mean the app callback ran: the contract swallows
+ * a reverting callback into `CallbackFailed`. This is where `callbackDelivered`
+ * comes from. Note: EndBlocker-driven expiry transactions are NOT EVM-indexed —
+ * `RequestExpired` will never be seen through a receipt; use the node record.
+ */
+export declare function parseFulfilOutcome(receipt: ReceiptLike, universalCallback: Address, requestId: Hex): FulfilOutcome;