@pushchain/core 6.0.24 → 6.0.25

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 ?? 60_000)) {
+        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/validate.d.ts

@@ -0,0 +1,22 @@
+import { type ReadSpecViolation } from './errors';
+import type { ReadPreflight, ReadSpec } from './read-state.types';
+export interface ValidateReadSpecInput {
+    spec: ReadSpec;
+    /** msg.value the request will carry. */
+    value: bigint;
+    callbackGasLimit: bigint;
+    /** When present, the height / expiry / fee rules that need chain state are checked too. */
+    preflight?: ReadPreflight;
+}
+/**
+ * Client-side mirror of every revert in `UniversalCallback.requestExternalReadSelf`
+ * (feat-read-state f8d1a0c), plus two SDK invariants, so a developer gets a typed
+ * violation list instead of an opaque revert. Line numbers refer to the contract.
+ */
+export declare function validateReadSpec(input: ValidateReadSpecInput): {
+    ok: true;
+} | {
+    ok: false;
+    violations: ReadSpecViolation[];
+};
+export declare function assertValidReadSpec(input: ValidateReadSpecInput): void;

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

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateReadSpec = validateReadSpec;
+exports.assertValidReadSpec = assertValidReadSpec;
+const viem_1 = require("viem");
+const read_state_1 = require("../constants/read-state");
+const errors_1 = require("./errors");
+const ZERO_ADDRESS = '0x0000000000000000000000000000000000000000';
+const UINT16_MAX = 65_535;
+const UINT64_MAX = (1n << 64n) - 1n;
+/**
+ * Client-side mirror of every revert in `UniversalCallback.requestExternalReadSelf`
+ * (feat-read-state f8d1a0c), plus two SDK invariants, so a developer gets a typed
+ * violation list instead of an opaque revert. Line numbers refer to the contract.
+ */
+function validateReadSpec(input) {
+    const { spec, value, callbackGasLimit, preflight } = input;
+    const v = [];
+    // :98-103 InvalidAccountId — every account field non-empty
+    const ownerLen = isHexLike(spec.account.owner) ? (0, viem_1.size)(spec.account.owner) : 0;
+    if (!spec.account.chainNamespace || !spec.account.chainId || ownerLen === 0)
+        v.push('INVALID_ACCOUNT_ID');
+    // :104-106 EmptyQuery
+    if (!isHexLike(spec.query) || (0, viem_1.size)(spec.query) === 0)
+        v.push('EMPTY_QUERY');
+    // :107-109 InvalidMinConfirmations (uint16)
+    if (!Number.isInteger(spec.minConfirmations) || spec.minConfirmations < read_state_1.MIN_CONFIRMATIONS_FLOOR || spec.minConfirmations > UINT16_MAX) {
+        v.push('INVALID_MIN_CONFIRMATIONS');
+    }
+    // :113-134 InvalidBlockNumber — heightless: must be 0; else 1..oracleHeight
+    if (spec.blockNumber < 0n || spec.blockNumber > UINT64_MAX) {
+        v.push('INVALID_BLOCK_NUMBER');
+    }
+    else if (preflight) {
+        const h = preflight.observedChainHeight;
+        const bad = h === 0n ? spec.blockNumber !== 0n : spec.blockNumber === 0n || spec.blockNumber > h;
+        if (bad)
+            v.push('INVALID_BLOCK_NUMBER');
+    }
+    // :119-121 InvalidExpiryHeight — strictly in the future
+    if (spec.expiryPushChainHeight < 0n || spec.expiryPushChainHeight > UINT64_MAX) {
+        v.push('INVALID_EXPIRY_HEIGHT');
+    }
+    else if (preflight && spec.expiryPushChainHeight <= preflight.pushBlockNumber) {
+        v.push('INVALID_EXPIRY_HEIGHT');
+    }
+    // :122-124 ZeroRevertRecipient
+    if (!(0, viem_1.isAddress)(spec.revertRecipient) || spec.revertRecipient.toLowerCase() === ZERO_ADDRESS)
+        v.push('ZERO_REVERT_RECIPIENT');
+    // :125-130 ZeroCallbackGasLimit / CallbackGasLimitExceeded
+    if (callbackGasLimit <= 0n)
+        v.push('ZERO_CALLBACK_GAS_LIMIT');
+    else if (callbackGasLimit > read_state_1.MAX_CALLBACK_GAS_LIMIT)
+        v.push('CALLBACK_GAS_LIMIT_EXCEEDED');
+    // :132-139 InsufficientFee / ExcessiveFee
+    if (preflight && value < preflight.protocolFee)
+        v.push('INSUFFICIENT_FEE');
+    if (value > spec.maxFee)
+        v.push('EXCESSIVE_FEE');
+    // SDK invariant (not a contract revert): a zero budget is never fulfilled by the node.
+    if (preflight && value - preflight.protocolFee <= 0n)
+        v.push('ZERO_CALLBACK_BUDGET');
+    // SDM invariant from svm/read_executor.go:29-32 — validators hard-reject any other length.
+    if (spec.account.chainNamespace === read_state_1.READ_NAMESPACE.SVM && ownerLen !== 32)
+        v.push('SVM_OWNER_NOT_32_BYTES');
+    return v.length === 0 ? { ok: true } : { ok: false, violations: v };
+}
+function assertValidReadSpec(input) {
+    const r = validateReadSpec(input);
+    if (!r.ok) {
+        throw new errors_1.InvalidReadSpecError(r.violations, {
+            destination: `${input.spec.account.chainNamespace}:${input.spec.account.chainId}`,
+            hint: 'See ReadSpecViolation names — each mirrors a UniversalCallback revert.',
+        });
+    }
+}
+function isHexLike(x) {
+    return typeof x === 'string' && /^0x[0-9a-fA-F]*$/.test(x);
+}
+//# sourceMappingURL=validate.js.map

package/src/lib/universal-tx-detector/child-inbounds.d.ts

@@ -7,7 +7,9 @@
  * See push-chain/x/uexecutor/types/keys.go:49-53 (GetInboundUniversalTxKey).
  *
  * For SVM sources, `<txHash>` is the 0x-prefixed hex encoding of the 64-byte
- * Solana signature and `<logIndex>` is the event's index in `meta.logMessages`.
+ * Solana signature and `<logIndex>` is the gateway-event ordinal. Current
+ * gateways derive it from authenticated `emit_cpi` inner instructions;
+ * legacy log-emitting gateways used the `meta.logMessages` index.
  *
  * For Push-initiated outbounds (pcTx entries) the formula drops the log index:
  *   utxId = sha256(`<pcChainCaip>:<pcTxHash>`)

package/src/lib/universal-tx-detector/child-inbounds.js

@@ -14,7 +14,9 @@ exports.resolveChildInboundsFromLogs = resolveChildInboundsFromLogs;
  * See push-chain/x/uexecutor/types/keys.go:49-53 (GetInboundUniversalTxKey).
  *
  * For SVM sources, `<txHash>` is the 0x-prefixed hex encoding of the 64-byte
- * Solana signature and `<logIndex>` is the event's index in `meta.logMessages`.
+ * Solana signature and `<logIndex>` is the gateway-event ordinal. Current
+ * gateways derive it from authenticated `emit_cpi` inner instructions;
+ * legacy log-emitting gateways used the `meta.logMessages` index.
  *
  * For Push-initiated outbounds (pcTx entries) the formula drops the log index:
  *   utxId = sha256(`<pcChainCaip>:<pcTxHash>`)
@@ -44,10 +46,7 @@ const OUTBOUND_STATUS_NAMES = {
     2: 'OBSERVED',
     3: 'REVERTED',
 };
-const INBOUND_EVENT_NAMES = new Set([
-    'UniversalTx',
-    'RevertUniversalTx',
-]);
+const INBOUND_EVENT_NAMES = new Set(['UniversalTx', 'RevertUniversalTx']);
 const HEX_64_BYTE_RE = /^(?:0x)?[0-9a-fA-F]{128}$/;
 function normalizeInboundTxHashForKey(sourceChainCaip, externalTxHash) {
     if (!sourceChainCaip.startsWith('solana:')) {

package/src/lib/universal-tx-detector/detector-svm.js

@@ -6,18 +6,17 @@ const tslib_1 = require("tslib");
 /**
  * detectUniversalTxSvm — SVM counterpart to the EVM detector.
  *
- * Fetches the tx via Solana RPC, walks `meta.logMessages`, decodes each
- * `Program data:` entry with Anchor's BorshEventCoder against the gateway
- * IDL, normalizes field names to match classify.ts's EVM-derived shape,
- * and hands the result to the same classifier used by the EVM branch.
+ * Fetches the tx via Solana RPC and decodes gateway events with Anchor's
+ * BorshEventCoder. Current gateways use authenticated `emit_cpi!` inner
+ * instructions; legacy `Program data:` log events remain as a fallback.
  *
  * Behavior deliberately mirrors detector.ts: same UniversalTxDetection
  * return, same universalTxId derivation strategy (primary-log fallback
  * via deriveChildUniversalTxId on source-chain inbounds).
  *
  * The Push keeper stores SVM inbound ids using the 0x-prefixed hex encoding
- * of the 64-byte Solana signature and the index of the Anchor event inside
- * `meta.logMessages`: `${caip}:${hexSig}:${logMessageIndex}`.
+ * of the 64-byte Solana signature and the gateway-event ordinal:
+ * `${caip}:${hexSig}:${eventIndex}`.
  */
 const anchor_1 = require("@coral-xyz/anchor");
 const web3_js_1 = require("@solana/web3.js");
@@ -86,17 +85,22 @@ async function detectUniversalTxSvm(signature, chain, opts = {}) {
     }
     const eventCoder = new anchor_1.BorshEventCoder(universalGatewayV0_json_1.default);
     const matchingLogs = [];
-    // Walk logMessages for `Program data:` entries. Each matched event keeps
-    // the actual Solana log-message index because that is the value validators
-    // submit as the inbound log_index and the keeper uses for the UTX key.
-    for (let logIndex = 0; logIndex < logMessages.length; logIndex++) {
-        const rawLog = logMessages[logIndex];
-        if (typeof rawLog !== 'string')
-            continue;
-        const prefix = 'Program data: ';
-        if (!rawLog.startsWith(prefix))
-            continue;
-        const base64Data = rawLog.slice(prefix.length).trim();
+    const cpiPayloads = (0, svm_events_1.getSvmEventCpiPayloads)(tx, emitterBase58);
+    const eventPayloads = cpiPayloads.length > 0
+        ? cpiPayloads.map(({ base64Data, eventIndex }) => ({
+            base64Data,
+            logIndex: eventIndex,
+        }))
+        : logMessages.flatMap((rawLog, logIndex) => {
+            const prefix = 'Program data: ';
+            return typeof rawLog === 'string' && rawLog.startsWith(prefix)
+                ? [{ base64Data: rawLog.slice(prefix.length).trim(), logIndex }]
+                : [];
+        });
+    if (cpiPayloads.length > 0) {
+        notes.push('svm: decoded gateway events from emit_cpi inner instructions');
+    }
+    for (const { base64Data, logIndex } of eventPayloads) {
         // Fast discriminator check — skip non-universal events without running
         // the full Borsh decode.
         let bytes;
@@ -141,7 +145,7 @@ async function detectUniversalTxSvm(signature, chain, opts = {}) {
     notes.push(...classified.notes);
     const decoded = { ...classified.decoded };
     // Inbound fallback for universalTxId: same formula the EVM branch uses,
-    // with the canonical 0x-hex Solana signature and log-message index.
+    // with the canonical 0x-hex Solana signature and gateway-event index.
     if (!decoded.universalTxId) {
         const caip = chain;
         if (INBOUND_KINDS.has(classified.kind) &&
@@ -245,7 +249,9 @@ function coerceArgValue(srcKey, renamedKey, value) {
         return (0, viem_1.bytesToHex)(new Uint8Array(value));
     }
     // BN from anchor — has toString().
-    if (value && typeof value === 'object' && typeof value.toString === 'function') {
+    if (value &&
+        typeof value === 'object' &&
+        typeof value.toString === 'function') {
         const proto = Object.getPrototypeOf(value);
         const ctorName = proto?.constructor?.name;
         if (ctorName === 'BN') {
@@ -259,7 +265,10 @@ function coerceArgValue(srcKey, renamedKey, value) {
     }
     // Anchor enum → { [variantName]: {} }. tx_type must be surfaced as a
     // numeric index to match classify.ts's setTxType expectations.
-    if (renamedKey === 'txType' && value && typeof value === 'object' && !Array.isArray(value)) {
+    if (renamedKey === 'txType' &&
+        value &&
+        typeof value === 'object' &&
+        !Array.isArray(value)) {
         return extractTxTypeIndex(value);
     }
     return value;

package/src/lib/universal-tx-detector/svm-events.d.ts

@@ -1,12 +1,24 @@
 /**
  * SVM-side universal-tx event metadata.
  *
- * Anchor programs emit events as base64-encoded `Program data:` log lines
- * prefixed with an 8-byte discriminator. The map below covers the four SVM
- * gateway events that have EVM parity (source: universalGatewayV0.json
- * events section). The discriminator bytes come from the IDL and are
- * converted to lowercase hex for matching.
+ * Current Anchor programs emit events through `emit_cpi!`: an inner
+ * instruction whose data is EVENT_IX_TAG || event discriminator || Borsh
+ * body. Older deployments emitted the discriminator + body as a base64
+ * `Program data:` log line. Helpers in this module support both transports.
  */
+export declare const SVM_EVENT_IX_TAG: Uint8Array;
+export interface SvmGatewayEventPayload {
+    /** Base64 discriminator + Borsh body accepted by BorshEventCoder. */
+    base64Data: string;
+    /** Gateway-event ordinal used by the Push keeper as log_index. */
+    eventIndex: number;
+}
+/**
+ * Extract authenticated gateway events from Anchor `emit_cpi!` inner
+ * instructions. Only self-CPIs whose program id equals `gatewayAddress` are
+ * accepted; matching a discriminator alone is not proof of the emitter.
+ */
+export declare function getSvmEventCpiPayloads(txResp: any, gatewayAddress: string): SvmGatewayEventPayload[];
 /**
  * Mapping: 8-byte discriminator (lowercase hex, no 0x) → Anchor event name.
  * Only events with EVM classifier parity are listed; the keeper-agnostic

package/src/lib/universal-tx-detector/svm-events.js

@@ -2,15 +2,90 @@
 /**
  * SVM-side universal-tx event metadata.
  *
- * Anchor programs emit events as base64-encoded `Program data:` log lines
- * prefixed with an 8-byte discriminator. The map below covers the four SVM
- * gateway events that have EVM parity (source: universalGatewayV0.json
- * events section). The discriminator bytes come from the IDL and are
- * converted to lowercase hex for matching.
+ * Current Anchor programs emit events through `emit_cpi!`: an inner
+ * instruction whose data is EVENT_IX_TAG || event discriminator || Borsh
+ * body. Older deployments emitted the discriminator + body as a base64
+ * `Program data:` log line. Helpers in this module support both transports.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SVM_EVENT_FIELD_ALIASES = exports.SVM_FIELD_RENAMES = exports.SVM_EVENT_DISCRIMINATORS = void 0;
+exports.SVM_EVENT_FIELD_ALIASES = exports.SVM_FIELD_RENAMES = exports.SVM_EVENT_DISCRIMINATORS = exports.SVM_EVENT_IX_TAG = void 0;
+exports.getSvmEventCpiPayloads = getSvmEventCpiPayloads;
 exports.discriminatorHex = discriminatorHex;
+const web3_js_1 = require("@solana/web3.js");
+const bs58_1 = require("../internal/bs58");
+exports.SVM_EVENT_IX_TAG = Uint8Array.from([
+    0xe4, 0x45, 0xa5, 0x2e, 0x51, 0xcb, 0x9a, 0x1d,
+]);
+/**
+ * Extract authenticated gateway events from Anchor `emit_cpi!` inner
+ * instructions. Only self-CPIs whose program id equals `gatewayAddress` are
+ * accepted; matching a discriminator alone is not proof of the emitter.
+ */
+function getSvmEventCpiPayloads(txResp, gatewayAddress) {
+    const groups = txResp?.meta?.innerInstructions;
+    if (!Array.isArray(groups) || groups.length === 0)
+        return [];
+    let gateway;
+    try {
+        gateway = new web3_js_1.PublicKey(gatewayAddress);
+    }
+    catch {
+        return [];
+    }
+    const message = txResp?.transaction?.message;
+    const loadedAddresses = txResp?.meta?.loadedAddresses;
+    const accountKeyAt = (index) => {
+        try {
+            if (typeof message?.getAccountKeys === 'function') {
+                return message
+                    .getAccountKeys({
+                    accountKeysFromLookups: loadedAddresses,
+                })
+                    .get(index);
+            }
+            const keys = [
+                ...(message?.accountKeys ?? message?.staticAccountKeys ?? []),
+                ...(loadedAddresses?.writable ?? []),
+                ...(loadedAddresses?.readonly ?? loadedAddresses?.readOnly ?? []),
+            ];
+            const key = keys[index];
+            return key instanceof web3_js_1.PublicKey
+                ? key
+                : key
+                    ? new web3_js_1.PublicKey(key)
+                    : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const payloads = [];
+    for (const group of groups) {
+        for (const instruction of group?.instructions ?? []) {
+            const programId = accountKeyAt(Number(instruction?.programIdIndex));
+            if (!programId?.equals(gateway) ||
+                typeof instruction?.data !== 'string') {
+                continue;
+            }
+            let raw;
+            try {
+                raw = bs58_1.bs58.decode(instruction.data);
+            }
+            catch {
+                continue;
+            }
+            if (raw.length < exports.SVM_EVENT_IX_TAG.length + 8 ||
+                !exports.SVM_EVENT_IX_TAG.every((byte, i) => raw[i] === byte)) {
+                continue;
+            }
+            payloads.push({
+                base64Data: Buffer.from(raw.subarray(exports.SVM_EVENT_IX_TAG.length)).toString('base64'),
+                eventIndex: payloads.length,
+            });
+        }
+    }
+    return payloads;
+}
 const toHex = (bytes) => bytes.map((b) => b.toString(16).padStart(2, '0')).join('');
 /**
  * Mapping: 8-byte discriminator (lowercase hex, no 0x) → Anchor event name.

package/src/lib/vm-client/evm-client.js

@@ -202,18 +202,35 @@ class EvmClient {
      * console.log(`ETH transfer sent: ${txHash}`);
      */
     async sendTransaction({ to, data, value = BigInt(0), signer, nonce: explicitNonce, gas: explicitGas, }) {
+        const resolveGas = async () => {
+            if (explicitGas)
+                return explicitGas;
+            const estimate = () => this.publicClient.estimateGas({
+                account: signer.account.address,
+                to,
+                data,
+                value,
+            });
+            if (data !== '0x')
+                return estimate();
+            // A plain native transfer to a code-free EOA always costs 21k. Empty
+            // calldata is not sufficient to identify that case, though: contracts
+            // and EIP-7702 delegated accounts still execute code and need estimation.
+            // If the code lookup is unavailable, prefer estimation over submitting
+            // a transaction that can deterministically run out of gas.
+            try {
+                const targetCode = await this.publicClient.getCode({ address: to });
+                if (!targetCode || targetCode === '0x')
+                    return BigInt(21000);
+            }
+            catch {
+                // Fall through to estimateGas.
+            }
+            return estimate();
+        };
         // Estimate gas and fees first (can run in parallel)
         const [gas, feePerGas, chainId] = await Promise.all([
-            explicitGas
-                ? Promise.resolve(explicitGas)
-                : data === '0x'
-                    ? Promise.resolve(BigInt(21000))
-                    : this.publicClient.estimateGas({
-                        account: signer.account.address,
-                        to,
-                        data,
-                        value,
-                    }),
+            resolveGas(),
             this.publicClient.estimateFeesPerGas(),
             this.publicClient.getChainId(),
         ]);