@pushchain/core 5.1.5-alpha.0 → 5.1.5

package/src/lib/orchestrator/orchestrator.types.d.ts

@@ -1,10 +1,16 @@
 import type { CHAIN } from '../constants/enums';
 /**
  * Chain target for cross-chain routing (Routes 2, 3, 4)
- * When `to` is a ChainTarget, the transaction executes on the specified external chain
+ * When `to` is a ChainTarget, the transaction executes on the specified external chain.
+ *
+ * `address` is typed as `string` because the accepted shape varies by VM:
+ *   - EVM chains expect a 0x-prefixed 20-byte hex address.
+ *   - SVM chains (Solana) accept either a base58 32-byte pubkey OR a 0x-prefixed
+ *     32-byte hex address; the SDK normalizes base58 to hex internally.
+ * Runtime validation happens in the route detector.
  */
 export type ChainTarget = {
-    address: `0x${string}`;
+    address: string;
     chain: CHAIN;
 };
 /**
@@ -135,13 +141,37 @@ export interface UniversalTxResponse {
     maxFeePerGas?: bigint;
     maxPriorityFeePerGas?: bigint;
     accessList: any[];
-    wait: () => Promise<UniversalTxReceipt>;
+    /**
+     * Wait for this transaction to reach its final state.
+     *
+     * For outbound routes (R2 / R3) the resolved receipt also includes external
+     * chain details. Pass `options.outboundTimeoutMs` / `options.inboundTimeoutMs`
+     * to override the default polling timeouts on a per-call basis — useful for
+     * latency-sensitive UIs that want to surface a provisional timeout and retry
+     * with a longer budget.
+     *
+     * When the outbound or inbound leg times out / fails, `.wait()` still
+     * resolves with a receipt (no throw); inspect `externalStatus` to classify
+     * the outcome.
+     */
+    wait: (options?: WaitOptions) => Promise<UniversalTxReceipt>;
     /**
      * Register a progress callback for events during wait().
-     * Call this BEFORE calling wait() to receive tracking events.
+     * Call this BEFORE calling wait() to receive tracking events, including
+     * the route-specific external/inbound polling events: R2 emits the 209/299
+     * series, R3 emits 309/310/399. Registering after wait() resolves will
+     * replay the pre-execution event buffer but miss outbound polling events.
      * @param callback - Function called with each progress event
      */
     progressHook: (callback: (event: import('../progress-hook/progress-hook.types').ProgressEvent) => void) => void;
+    /**
+     * @internal Register a wait-phase progressHook without replaying buffered
+     * events. Used by `trackTransaction()` to auto-attach the caller's per-call
+     * progressHook so `tracked.wait()` can deliver wait-phase events (209-xx /
+     * 299-xx / 399-xx) to the same callback — without re-emitting the
+     * reconstructed execute-phase stream that trackTransaction already fired.
+     */
+    _setProgressHookNoReplay?: (callback: (event: import('../progress-hook/progress-hook.types').ProgressEvent) => void) => void;
     type: string;
     typeVerbose: string;
     signature: Signature;
@@ -164,10 +194,66 @@ export interface UniversalTxResponse {
     childTxHash?: string;
     /** Transaction route (UOA_TO_PUSH, UOA_TO_CEA, CEA_TO_PUSH, CEA_TO_CEA) */
     route?: TransactionRouteType;
+    /**
+     * @internal True when this response was produced by `trackTransaction` and
+     * its progress events have already been replayed via the registered hook.
+     * `wait()` checks this to skip a redundant inner trackTransaction call that
+     * would otherwise emit the same reconstructed events a second time when
+     * the user does `tracked = trackTransaction(...); tracked.wait()`.
+     */
+    _eventsReconstructed?: boolean;
+    /**
+     * @internal True when the R3 (CEA_TO_PUSH) execution produces a child UTX
+     * on Push Chain — i.e., the source-chain CEA payload actually calls
+     * `sendUniversalTxToUEA` (funds flowing back to UEA). When false, `.wait()`
+     * skips `waitForInboundPushTx` to avoid a 300s timeout on payload-only R3
+     * flows that have no inbound leg.
+     */
+    _expectsInboundRoundTrip?: boolean;
 }
 /**
  * New Universal Transaction Receipt interface for transaction receipts
  */
+/**
+ * Per-call options accepted by `UniversalTxResponse.wait()`.
+ *
+ * All fields are optional; omitted values fall back to the orchestrator's
+ * defaults (`OUTBOUND_MAX_TIMEOUT_MS`, `INBOUND_MAX_TIMEOUT_MS`).
+ */
+export interface WaitOptions {
+    /**
+     * Override the outbound polling budget (ms) — applies to R2 / R3 while
+     * waiting for the external-chain tx to land via UGPC relay. When exceeded,
+     * `wait()` resolves with `externalStatus: 'timeout'` and the progress-hook
+     * stream emits `SEND-TX-299-03` (R2) or `SEND-TX-399-03` (R3 inbound).
+     *
+     * The outbound-sync initial settle-wait is automatically clamped to this
+     * timeout, so a 200ms budget will throw in ~200ms rather than blocking for
+     * the default 20s.
+     */
+    outboundTimeoutMs?: number;
+    /**
+     * Override the inbound polling budget (ms) — applies to R3 only, for the
+     * round-trip Push tx produced by the external CEA. When exceeded,
+     * `wait()` resolves with `externalStatus: 'timeout'` and emits
+     * `SEND-TX-399-03`.
+     */
+    inboundTimeoutMs?: number;
+    /**
+     * Override the poll interval (ms) between outbound status checks. Default
+     * is 5000ms. Lower values give faster feedback on fast relays; higher
+     * values reduce RPC pressure. Only applies to R2 / R3 outbound polling.
+     */
+    outboundPollingIntervalMs?: number;
+    /**
+     * Override the initial settle-wait (ms) before the outbound polling loop
+     * starts. Default is 20000ms — a buffer for UGPC relay submission latency.
+     * Reducing this doesn't affect the timeout budget but may cause earlier
+     * polls that miss the relay submission and burn RPC. Rarely needed; prefer
+     * `outboundTimeoutMs` which auto-clamps the initial wait.
+     */
+    outboundInitialWaitMs?: number;
+}
 export interface UniversalTxReceipt {
     hash: string;
     blockNumber: bigint;
@@ -202,6 +288,20 @@ export interface UniversalTxReceipt {
     externalAmount?: string;
     /** Asset address on external chain */
     externalAssetAddr?: string;
+    /**
+     * Outcome of the external-chain leg for outbound routes (R2 / R3).
+     * - `success`: external tx landed and was confirmed (299-01 fired).
+     * - `failed`: external tx reverted or UGPC reported terminal failure (299-02 fired).
+     * - `timeout`: UGPC relay timed out before an external tx was observed (299-03 fired).
+     * Undefined on non-outbound receipts.
+     */
+    externalStatus?: 'success' | 'failed' | 'timeout';
+    /** Error message from the external-chain leg when `externalStatus !== 'success'`. */
+    externalError?: string;
+    /** Push Chain tx hash that closed the R3 round-trip (inbound from CEA). */
+    pushInboundTxHash?: string;
+    /** Child UTX id that owns the inbound execution. */
+    pushInboundUtxId?: string;
 }
 /**
  * Signature interface modeled after ethers.js v6 Signature interface
@@ -400,6 +500,8 @@ export interface HopDescriptor {
     svmPayload?: `0x${string}`;
     /** Whether this hop is a CEA migration (raw MIGRATION_SELECTOR payload) */
     isMigration?: boolean;
+    /** SDK 5.2 gas-abstraction sizing decision for this hop. @internal */
+    sizing?: import('./internals/gas-usd-sizer').GasSizingDecision;
 }
 /**
  * Segment types for cascade composition
@@ -434,6 +536,13 @@ export interface CascadeSegment {
     gasFee?: bigint;
     /** Gas limit for this segment */
     gasLimit?: bigint;
+    /**
+     * SDK 5.2 gas-abstraction sizing decision for this segment. When the
+     * segment merges multiple hops, the strictest (highest category) sizing
+     * among them is taken (C > B > A).
+     * @internal
+     */
+    sizing?: import('./internals/gas-usd-sizer').GasSizingDecision;
 }
 /**
  * Prepared transaction for inspection before sending
@@ -515,8 +624,14 @@ export interface CascadeTrackOptions {
     pollingIntervalMs?: number;
     /** Total timeout (default: 600000ms = 10 min) */
     timeout?: number;
-    /** Progress callback */
+    /** Per-hop progress callback */
     progressHook?: (event: CascadeProgressEvent) => void;
+    /**
+     * Unified ProgressEvent stream for SEND-TX-08/99_03-05 telemetry.
+     * Fires per outbound hop during external chain polling. Use alongside
+     * `progressHook` — they emit complementary views of the same events.
+     */
+    eventHook?: (event: import('../progress-hook/progress-hook.types').ProgressEvent) => void;
 }
 /**
  * Progress event emitted during cascade tracking

package/src/lib/orchestrator/payload-builders.d.ts

@@ -5,6 +5,22 @@ export declare function buildExecuteMulticall({ execute, ueaAddress, logger, }:
     ueaAddress: `0x${string}`;
     logger?: (msg: string) => void;
 }): MultiCall[];
+/**
+ * Multicall tuple type definition for ABI encoding
+ */
+export declare const MULTICALL_TUPLE_TYPE: {
+    readonly type: "tuple[]";
+    readonly components: readonly [{
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "value";
+        readonly type: "uint256";
+    }, {
+        readonly name: "data";
+        readonly type: "bytes";
+    }];
+};
 /**
  * Build CEA multicall payload for outbound transactions
  * Format: UEA_MULTICALL_SELECTOR + abi.encode(Multicall[])

package/src/lib/orchestrator/payload-builders.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.MULTICALL_TUPLE_TYPE = void 0;
 exports.buildExecuteMulticall = buildExecuteMulticall;
 exports.buildCeaMulticallPayload = buildCeaMulticallPayload;
 exports.buildInboundUniversalPayload = buildInboundUniversalPayload;
@@ -124,7 +125,7 @@ function buildExecuteMulticall({ execute, ueaAddress, logger, }) {
 /**
  * Multicall tuple type definition for ABI encoding
  */
-const MULTICALL_TUPLE_TYPE = {
+exports.MULTICALL_TUPLE_TYPE = {
     type: 'tuple[]',
     components: [
         { name: 'to', type: 'address' },
@@ -148,7 +149,7 @@ function buildCeaMulticallPayload(multicalls) {
         return '0x';
     }
     // Encode the multicall array
-    const encoded = (0, viem_1.encodeAbiParameters)([MULTICALL_TUPLE_TYPE], [multicalls.map((m) => ({
+    const encoded = (0, viem_1.encodeAbiParameters)([exports.MULTICALL_TUPLE_TYPE], [multicalls.map((m) => ({
             to: m.to,
             value: m.value,
             data: m.data,
@@ -418,11 +419,11 @@ function isZeroAddress(address) {
  */
 function buildOutboundApprovalAndCall(opts) {
     var _a;
-    const { prc20Token, burnAmount, gasFee, gatewayPcAddress, outboundRequest } = opts;
+    const { prc20Token, gasFee, gatewayPcAddress, outboundRequest } = opts;
     const multicalls = [];
     // ERC20 approve for burn amount (contract calls transferFrom for PRC20 burn)
     // Reset to 0 first for USDT-style tokens that revert on non-zero to non-zero approve.
-    if (burnAmount > BigInt(0) &&
+    if (opts.burnAmount > BigInt(0) &&
         prc20Token.toLowerCase() !== selectors_1.ZERO_ADDRESS.toLowerCase()) {
         const approveZeroData = (0, viem_1.encodeFunctionData)({
             abi: erc20_evm_1.ERC20_EVM,
@@ -432,7 +433,7 @@ function buildOutboundApprovalAndCall(opts) {
         const approveData = (0, viem_1.encodeFunctionData)({
             abi: erc20_evm_1.ERC20_EVM,
             functionName: 'approve',
-            args: [gatewayPcAddress, burnAmount],
+            args: [gatewayPcAddress, opts.burnAmount],
         });
         multicalls.push({
             to: prc20Token,

package/src/lib/orchestrator/route-detector.js

@@ -21,6 +21,7 @@ exports.getRouteInfo = getRouteInfo;
 const enums_1 = require("../constants/enums");
 const tokens_1 = require("../constants/tokens");
 const payload_builders_1 = require("./payload-builders");
+const normalize_address_1 = require("./svm-idl/normalize-address");
 // ============================================================================
 // Transaction Route Enum
 // ============================================================================
@@ -253,13 +254,18 @@ function validateRouteParams(params, context) {
             throw new RouteValidationError('migration is not supported on SVM chains');
         }
     }
-    // Validate funds token symbol is available on target chain (Route 2 outbound)
+    // Validate funds token symbol is available on target chain (Route 2 outbound).
+    // A PushChainMoveableToken (e.g. pSOL, pETH_BNB) carries a `sourceChain` pointing at
+    // the external chain it mirrors — bridging it to that chain is always valid since
+    // the target receives the underlying asset (SOL, ETH, etc.).
     if (((_b = params.funds) === null || _b === void 0 ? void 0 : _b.token) && isChainTarget(params.to)) {
         const targetChain = params.to.chain;
         if (!isPushChain(targetChain)) {
+            const tokenSourceChain = params.funds.token.sourceChain;
+            const isBridgeBack = tokenSourceChain === targetChain;
             const targetTokens = tokens_1.MOVEABLE_TOKENS[targetChain] || [];
             const hasSymbolOnTarget = targetTokens.some(t => t.symbol === params.funds.token.symbol);
-            if (!hasSymbolOnTarget) {
+            if (!hasSymbolOnTarget && !isBridgeBack) {
                 const tokenChain = findTokenChain(params.funds.token);
                 const tokenLabel = tokenChain
                     ? `${chainEnumToName(tokenChain)}.${params.funds.token.symbol}`
@@ -297,16 +303,22 @@ function validateRouteParams(params, context) {
     }
     // Validate address format
     if (isChainTarget(params.to)) {
-        if (!params.to.address.startsWith('0x')) {
-            throw new RouteValidationError(`Invalid address format: ${params.to.address}`);
-        }
-        // SVM targets require 32-byte addresses (0x + 64 hex chars)
         if ((0, payload_builders_1.isSvmChain)(params.to.chain)) {
-            if (!(0, payload_builders_1.isValidSolanaHexAddress)(params.to.address)) {
+            // SVM targets accept either base58 (native Solana form) or 0x-prefixed
+            // 32-byte hex. Normalize to hex up front so downstream handlers only see
+            // the canonical form.
+            try {
+                params.to.address = (0, normalize_address_1.toSvmHexAddress)(params.to.address);
+            }
+            catch (err) {
                 throw new RouteValidationError(`Invalid Solana address format: ${params.to.address}. ` +
-                    `Expected 32 bytes (0x + 64 hex chars).`);
+                    `Expected base58 (32-byte pubkey) or 0x-prefixed 32-byte hex. ` +
+                    `(${err.message})`);
             }
         }
+        else if (!params.to.address.startsWith('0x')) {
+            throw new RouteValidationError(`Invalid address format: ${params.to.address}`);
+        }
     }
     else if (typeof params.to === 'string') {
         if (!params.to.startsWith('0x')) {

package/src/lib/orchestrator/svm-idl/normalize-address.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Canonical internal form of a Solana program / account address.
+ * All validation and payload paths key off this `0x`-prefixed 32-byte hex string.
+ */
+export type SvmHexAddress = `0x${string}`;
+/**
+ * Normalize an SVM address supplied by an end user to the internal `0x`-prefixed
+ * 32-byte hex form. Accepts either:
+ *   - `0x`-prefixed 64-hex-char string (the internal form), or
+ *   - base58 string that decodes to exactly 32 bytes (the native Solana form).
+ *
+ * Throws with a message naming both accepted forms if the input matches neither.
+ */
+export declare function toSvmHexAddress(input: unknown): SvmHexAddress;
+/**
+ * Predicate form of {@link toSvmHexAddress} — returns true if the input is a
+ * valid SVM address in either accepted form.
+ */
+export declare function isValidSvmAddress(input: unknown): boolean;

package/src/lib/orchestrator/svm-idl/normalize-address.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toSvmHexAddress = toSvmHexAddress;
+exports.isValidSvmAddress = isValidSvmAddress;
+const bs58_1 = require("../../internal/bs58");
+const HEX_FORM = /^0x[0-9a-fA-F]{64}$/;
+/**
+ * Normalize an SVM address supplied by an end user to the internal `0x`-prefixed
+ * 32-byte hex form. Accepts either:
+ *   - `0x`-prefixed 64-hex-char string (the internal form), or
+ *   - base58 string that decodes to exactly 32 bytes (the native Solana form).
+ *
+ * Throws with a message naming both accepted forms if the input matches neither.
+ */
+function toSvmHexAddress(input) {
+    if (typeof input !== 'string' || input.length === 0) {
+        throw new Error(`SVM address must be a non-empty string (base58 or 0x-prefixed 32-byte hex), got ${typeof input}`);
+    }
+    if (input.startsWith('0x')) {
+        if (!HEX_FORM.test(input)) {
+            throw new Error(`SVM address in hex form must be 0x + 64 hex chars (32 bytes), got '${input}' (length ${input.length})`);
+        }
+        return input.toLowerCase();
+    }
+    let decoded;
+    try {
+        decoded = bs58_1.bs58.decode(input);
+    }
+    catch (_a) {
+        throw new Error(`SVM address '${input}' is not valid base58 and does not start with 0x. ` +
+            `Expected base58 (e.g. 'So11111111111111111111111111111111111111112') ` +
+            `or 0x-prefixed 32-byte hex.`);
+    }
+    if (decoded.length !== 32) {
+        throw new Error(`SVM address '${input}' decodes to ${decoded.length} bytes; expected 32.`);
+    }
+    let hex = '0x';
+    for (let i = 0; i < decoded.length; i++) {
+        hex += decoded[i].toString(16).padStart(2, '0');
+    }
+    return hex;
+}
+/**
+ * Predicate form of {@link toSvmHexAddress} — returns true if the input is a
+ * valid SVM address in either accepted form.
+ */
+function isValidSvmAddress(input) {
+    try {
+        toSvmHexAddress(input);
+        return true;
+    }
+    catch (_a) {
+        return false;
+    }
+}
+//# sourceMappingURL=normalize-address.js.map

package/src/lib/orchestrator/svm-idl/registry.d.ts

@@ -1,10 +1,19 @@
 import type { Idl } from '@coral-xyz/anchor';
-type AddressKey = `0x${string}`;
-export declare function registerIdl(programAddress: string, idl: unknown): void;
+import { type SvmHexAddress } from './normalize-address';
+/**
+ * Register an Anchor IDL so the SDK can resolve accounts, PDAs, and CEA
+ * authorities when building SVM gateway payloads.
+ *
+ * Normal usage never needs this — `PushChain.utils.helpers.encodeTxData`
+ * auto-registers the IDL whenever you pass it as `abi`. Use this only when
+ * building `data` manually (raw discriminator + Borsh bytes).
+ *
+ * The program address is pulled from `idl.address` (Anchor ≥ 0.30 spec).
+ */
+export declare function registerIdl(idl: unknown): void;
 export declare function getIdl(programAddress: string): Idl | undefined;
 export declare function getRegisteredIdls(): Array<{
-    address: AddressKey;
+    address: SvmHexAddress;
     idl: Idl;
 }>;
 export declare function clearRegistry(): void;
-export {};

package/src/lib/orchestrator/svm-idl/registry.js

@@ -5,26 +5,27 @@ exports.getIdl = getIdl;
 exports.getRegisteredIdls = getRegisteredIdls;
 exports.clearRegistry = clearRegistry;
 const ix_encoder_1 = require("./ix-encoder");
+const normalize_address_1 = require("./normalize-address");
 const store = new Map();
-function normalizeKey(address) {
-    if (typeof address !== 'string' || !address.startsWith('0x')) {
-        throw new Error(`registerIdl: programAddress must be 0x-prefixed 32-byte hex, got '${address}'`);
-    }
-    const body = address.slice(2);
-    if (body.length !== 64 || !/^[0-9a-fA-F]+$/.test(body)) {
-        throw new Error(`registerIdl: programAddress must be 32 bytes (66 chars incl. 0x), got length ${address.length}`);
-    }
-    return ('0x' + body.toLowerCase());
-}
-function registerIdl(programAddress, idl) {
-    const key = normalizeKey(programAddress);
+/**
+ * Register an Anchor IDL so the SDK can resolve accounts, PDAs, and CEA
+ * authorities when building SVM gateway payloads.
+ *
+ * Normal usage never needs this — `PushChain.utils.helpers.encodeTxData`
+ * auto-registers the IDL whenever you pass it as `abi`. Use this only when
+ * building `data` manually (raw discriminator + Borsh bytes).
+ *
+ * The program address is pulled from `idl.address` (Anchor ≥ 0.30 spec).
+ */
+function registerIdl(idl) {
     if (!(0, ix_encoder_1.isAnchorIdl)(idl)) {
-        throw new Error(`registerIdl: idl for ${programAddress} is not a recognized Anchor IDL (missing 'instructions' or 'address')`);
+        throw new Error(`registerIdl: input is not a recognized Anchor IDL (missing 'instructions' or 'address')`);
     }
+    const key = (0, normalize_address_1.toSvmHexAddress)(idl.address);
     store.set(key, idl);
 }
 function getIdl(programAddress) {
-    const key = normalizeKey(programAddress);
+    const key = (0, normalize_address_1.toSvmHexAddress)(programAddress);
     return store.get(key);
 }
 function getRegisteredIdls() {

package/src/lib/orchestrator/svm-idl/resolve.js

@@ -16,8 +16,11 @@ function resolveSvmCall(input) {
     var _a, _b;
     const idl = (0, registry_1.getIdl)(input.programAddress);
     if (!idl) {
-        throw new Error(`resolveSvmCall: no IDL registered for ${input.programAddress}. ` +
-            `Call PushChain.utils.svm.registerIdl(${input.programAddress}, idl) first.`);
+        throw new Error(`resolveSvmCall: no IDL found for ${input.programAddress}. ` +
+            `The SDK auto-registers Anchor IDLs when you call ` +
+            `PushChain.utils.helpers.encodeTxData({abi: idl, ...}). ` +
+            `If you built 'data' manually, call PushChain.utils.svm.registerIdl(idl) ` +
+            `once before prepareTransaction.`);
     }
     if (input.data.length < 8) {
         throw new Error('resolveSvmCall: data must be at least 8 bytes (Anchor discriminator)');

package/src/lib/progress-hook/progress-hook.d.ts

@@ -1,3 +1,31 @@
 import { ProgressEventFunction } from './progress-hook.types';
+/**
+ * Shape of the `response` field emitted by `SEND_TX_104_04` (R1),
+ * `SEND_TX_204_04` (R2), and `SEND_TX_304_04` (R3). Exported so consumers
+ * can read `isUserDecline` without casting through `object`.
+ */
+export interface DeclineHookResponse {
+    /** The underlying sign-time error message (decline copy when absent). */
+    error: string;
+    /** True if the error looks like a real wallet rejection. */
+    isUserDecline: boolean;
+}
+/**
+ * Classify a sign-time error as either a true wallet user-decline
+ * (viem `UserRejectedRequestError`, ethers `ACTION_REJECTED`, EIP-1193 4001,
+ * or textual "user rejected"/"user denied"/"declined by user") or a generic
+ * signature failure (insufficient funds, RPC failure, contract revert
+ * during sign, etc.). Shared by SEND_TX_104_04 (R1), SEND_TX_204_04 (R2),
+ * and SEND_TX_304_04 (R3) so the heuristic lives in one place.
+ *
+ * When `errorMessage` is omitted, treat it as a decline — the spec copy is
+ * already the decline copy ("Verification declined by user"), so flipping
+ * to "Signature Failed" would make the event self-contradict.
+ */
+export declare function classifyDeclineError(errorMessage?: string): {
+    isUserDecline: boolean;
+    title: string;
+    message: string;
+};
 declare const PROGRESS_HOOKS: Record<string, ProgressEventFunction>;
 export default PROGRESS_HOOKS;