@pushchain/core 4.0.14-alpha.0 → 5.1.0

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

@@ -1,3 +1,30 @@
+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
+ */
+export type ChainTarget = {
+    address: `0x${string}`;
+    chain: CHAIN;
+};
+/**
+ * Source chain for CEA-originated transactions (Routes 3, 4)
+ * Specifies which CEA domain submits the transaction
+ * NOTE: This does NOT represent where the user signed from
+ */
+export type ChainSource = {
+    chain: CHAIN;
+};
+/**
+ * Union type for 'to' parameter - backwards compatible
+ * - string: Route 1 (UOA → Push)
+ * - ChainTarget: Routes 2, 3, 4 (cross-chain)
+ */
+export type UniversalTo = `0x${string}` | ChainTarget;
+/**
+ * Transaction route identifiers
+ */
+export type TransactionRouteType = 'UOA_TO_PUSH' | 'UOA_TO_CEA' | 'CEA_TO_PUSH' | 'CEA_TO_CEA';
 export type ExecuteParams = {
     /**
      * The target contract or account on Push Chain.
@@ -62,6 +89,23 @@ export type ExecuteParams = {
         amount: bigint;
         token?: import('../constants').MoveableToken;
     };
+    /**
+     * Internal: Pre-fetched UEA status to avoid redundant RPC calls.
+     * Used by executeUoaToCea() to pass UEA state to execute().
+     * @internal
+     */
+    _ueaStatus?: {
+        isDeployed: boolean;
+        nonce: bigint;
+        balance: bigint;
+    };
+    /**
+     * Internal: Skip fee locking for outbound flows (UEA→CEA).
+     * Outbound txs execute entirely on Push Chain and don't need
+     * external-chain fee locking.
+     * @internal
+     */
+    _skipFeeLocking?: boolean;
 };
 /**
  * New Universal Transaction Receipt interface with prioritized field ordering
@@ -100,6 +144,18 @@ export interface UniversalTxResponse {
         data: string;
         value: bigint;
     };
+    /** Target chain where transaction was executed */
+    chain?: CHAIN;
+    /** CAIP-2 chain namespace, e.g., "eip155:11155111" */
+    chainNamespace?: string;
+    /** Position in chain sequence (0-indexed) */
+    hopIndex?: number;
+    /** Previous transaction hash in chain */
+    parentTxHash?: string;
+    /** Next transaction hash in chain */
+    childTxHash?: string;
+    /** Transaction route (UOA_TO_PUSH, UOA_TO_CEA, CEA_TO_PUSH, CEA_TO_CEA) */
+    route?: TransactionRouteType;
 }
 /**
  * New Universal Transaction Receipt interface for transaction receipts
@@ -122,6 +178,22 @@ export interface UniversalTxReceipt {
         from: string;
         to: string;
     };
+    /** Target chain where transaction was executed */
+    chain?: CHAIN;
+    /** CAIP-2 chain namespace, e.g., "eip155:11155111" */
+    chainNamespace?: string;
+    /** Transaction hash on external chain (outbound only) */
+    externalTxHash?: string;
+    /** External chain where tx executed */
+    externalChain?: CHAIN;
+    /** Explorer URL for external tx */
+    externalExplorerUrl?: string;
+    /** Recipient on external chain */
+    externalRecipient?: string;
+    /** Amount transferred to external chain */
+    externalAmount?: string;
+    /** Asset address on external chain */
+    externalAssetAddr?: string;
 }
 /**
  * Signature interface modeled after ethers.js v6 Signature interface
@@ -151,6 +223,15 @@ export interface UniversalTxRequest {
     };
     signatureData: `0x${string}`;
 }
+/** V1 gateway request — uses a plain `revertRecipient` address instead of a struct. */
+export interface UniversalTxRequestV1 {
+    recipient: `0x${string}`;
+    token: `0x${string}`;
+    amount: bigint;
+    payload: `0x${string}`;
+    revertRecipient: `0x${string}`;
+    signatureData: `0x${string}`;
+}
 export interface UniversalTokenTxRequest {
     recipient: `0x${string}`;
     token: `0x${string}`;
@@ -166,9 +247,324 @@ export interface UniversalTokenTxRequest {
     amountOutMinETH: bigint;
     deadline: bigint;
 }
+/** V1 gateway token request — uses a plain `revertRecipient` address instead of a struct. */
+export interface UniversalTokenTxRequestV1 {
+    recipient: `0x${string}`;
+    token: `0x${string}`;
+    amount: bigint;
+    gasToken: `0x${string}`;
+    gasAmount: bigint;
+    payload: `0x${string}`;
+    revertRecipient: `0x${string}`;
+    signatureData: `0x${string}`;
+    amountOutMinETH: bigint;
+    deadline: bigint;
+}
 /**
  * Options for tracking a transaction by hash
  */
+/**
+ * Extended ExecuteParams for multi-chain transactions
+ * Supports all 4 routes:
+ * - Route 1: UOA → Push (to is string)
+ * - Route 2: UOA → CEA (to is ChainTarget, no from)
+ * - Route 3: CEA → Push (from.chain present, to.chain is Push)
+ * - Route 4: CEA → CEA (from.chain present, to.chain is external)
+ */
+export type UniversalExecuteParams = Omit<ExecuteParams, 'to'> & {
+    /**
+     * Source chain for CEA-originated transactions (Routes 3, 4)
+     * When present, transaction originates from CEA on this chain
+     */
+    from?: ChainSource;
+    /**
+     * Destination - where execution happens
+     * - string: Push Chain target (Route 1)
+     * - ChainTarget: External chain target (Routes 2, 3, 4)
+     */
+    to: UniversalTo;
+    /**
+     * SVM-specific: CPI execution parameters for Solana targets (Route 2).
+     * When present, the outbound transaction will execute a Cross-Program Invocation
+     * on the specified Solana program with the given accounts and instruction data.
+     * Only applicable when `to.chain` is a Solana chain.
+     */
+    svmExecute?: SvmExecuteParams;
+    /**
+     * When true, sends MIGRATION_SELECTOR as raw CEA payload (no multicall wrapping).
+     * Used for CEA contract upgrades. Incompatible with value/funds/data/svmExecute.
+     * Only applicable for Route 2 (UOA_TO_CEA) on EVM chains.
+     */
+    migration?: boolean;
+};
+/**
+ * Account metadata for SVM CPI execution (Solana Gateway pattern).
+ * Pubkey is 0x-prefixed hex encoding of a 32-byte Solana public key.
+ */
+export interface SvmGatewayAccountMeta {
+    /** Solana public key as 0x-prefixed hex (32 bytes = 0x + 64 hex chars) */
+    pubkey: `0x${string}`;
+    /** Whether this account is writable in the CPI */
+    isWritable: boolean;
+}
+/**
+ * Fields for encoding the SVM execute payload (binary format).
+ * Used internally by encodeSvmExecutePayload.
+ */
+export interface SvmExecutePayloadFields {
+    /** Target Solana program to CPI into (32 bytes, 0x-prefixed hex) */
+    targetProgram: `0x${string}`;
+    /** Accounts required for the CPI call */
+    accounts: SvmGatewayAccountMeta[];
+    /** Raw instruction data for the target program */
+    ixData: Uint8Array;
+    /** Instruction ID: 2 = execute (default) */
+    instructionId?: number;
+}
+/**
+ * User-facing parameters for CPI execution on a Solana program via Route 2.
+ * Passed as `svmExecute` in UniversalExecuteParams when targeting SVM chains.
+ */
+export interface SvmExecuteParams {
+    /** Target Solana program to CPI into (32 bytes, 0x-prefixed hex) */
+    targetProgram: `0x${string}`;
+    /** Accounts required for the CPI call */
+    accounts: SvmGatewayAccountMeta[];
+    /** Raw instruction data for the target program */
+    ixData: Uint8Array;
+}
+/**
+ * Request structure for sendUniversalTxOutbound on Push Chain
+ * Used for Routes 2, 3, 4 (outbound from Push)
+ *
+ * NOTE: The `target` field is a LEGACY parameter for contract compatibility.
+ * The deployed UniversalGatewayPC contract still expects this field, but it will
+ * be removed in future contract upgrades. Pass any non-zero address (e.g., CEA address).
+ * The actual destination is determined by the relay from the token's SOURCE_CHAIN_NAMESPACE.
+ */
+export interface UniversalOutboundTxRequest {
+    /**
+     * LEGACY/DUMMY: Raw destination address bytes for contract compatibility.
+     * Pass any non-zero address - this value is NOT used by the relay to determine
+     * the actual transaction destination. Will be removed in future contract upgrades.
+     */
+    target: `0x${string}`;
+    /** PRC20 token address on Push Chain to burn */
+    token: `0x${string}`;
+    /** Amount to burn (0 for no-burn, use existing CEA balance) */
+    amount: bigint;
+    /** Gas limit for fee quote (0 = default BASE_GAS_LIMIT) */
+    gasLimit: bigint;
+    /** Raw ABI-encoded Multicall[] (no selector prefix) */
+    payload: `0x${string}`;
+    /** Address to receive funds on revert */
+    revertRecipient: `0x${string}`;
+}
+/**
+ * Internal metadata attached to each prepared transaction.
+ * Carries all information needed to nest this hop into a cascade.
+ * @internal
+ */
+export interface HopDescriptor {
+    /** Original user params */
+    params: UniversalExecuteParams;
+    /** Detected route */
+    route: TransactionRouteType;
+    /** Target chain for outbound (Route 2) */
+    targetChain?: CHAIN;
+    /** Source chain for inbound (Route 3) */
+    sourceChain?: CHAIN;
+    /** CEA address on the relevant external chain */
+    ceaAddress?: `0x${string}`;
+    /** Operations to execute on external chain CEA */
+    ceaMulticalls?: MultiCall[];
+    /** Operations to execute on Push Chain */
+    pushMulticalls?: MultiCall[];
+    /** PRC-20 token address to burn for outbound */
+    prc20Token?: `0x${string}`;
+    /** Amount of PRC-20 to burn */
+    burnAmount?: bigint;
+    /** Gas token address on Push Chain */
+    gasToken?: `0x${string}`;
+    /** Gas fee amount in gas token */
+    gasFee?: bigint;
+    /** Gas limit for outbound relay */
+    gasLimit: bigint;
+    /** UEA address */
+    ueaAddress: `0x${string}`;
+    /** Address to receive funds on revert */
+    revertRecipient: `0x${string}`;
+    /** Whether this hop targets an SVM chain (Solana) */
+    isSvmTarget?: boolean;
+    /** SVM execute payload (binary-encoded, for Solana targets) */
+    svmPayload?: `0x${string}`;
+    /** Whether this hop is a CEA migration (raw MIGRATION_SELECTOR payload) */
+    isMigration?: boolean;
+}
+/**
+ * Segment types for cascade composition
+ * @internal
+ */
+export type CascadeSegmentType = 'PUSH_EXECUTION' | 'OUTBOUND_TO_CEA' | 'INBOUND_FROM_CEA';
+/**
+ * A segment groups one or more hops of the same type/direction.
+ * Consecutive same-chain hops are merged within a segment.
+ * @internal
+ */
+export interface CascadeSegment {
+    /** Segment type determines composition behavior */
+    type: CascadeSegmentType;
+    /** Hops in this segment */
+    hops: HopDescriptor[];
+    /** Target chain (for OUTBOUND_TO_CEA) */
+    targetChain?: CHAIN;
+    /** Source chain (for INBOUND_FROM_CEA) */
+    sourceChain?: CHAIN;
+    /** Merged CEA multicalls from all hops in segment */
+    mergedCeaMulticalls?: MultiCall[];
+    /** Merged Push Chain multicalls from all hops in segment */
+    mergedPushMulticalls?: MultiCall[];
+    /** Sum of burn amounts from merged hops */
+    totalBurnAmount?: bigint;
+    /** PRC-20 token for this segment */
+    prc20Token?: `0x${string}`;
+    /** Gas token for this segment */
+    gasToken?: `0x${string}`;
+    /** Total gas fee for this segment */
+    gasFee?: bigint;
+    /** Gas limit for this segment */
+    gasLimit?: bigint;
+}
+/**
+ * Prepared transaction for inspection before sending
+ * Returned by prepareTransaction()
+ */
+export interface PreparedUniversalTx {
+    /** Detected route for this transaction */
+    route: TransactionRouteType;
+    /** Encoded payload ready for submission */
+    payload: `0x${string}`;
+    /** Gateway request object (inbound or outbound) */
+    gatewayRequest: UniversalTxRequest | UniversalOutboundTxRequest;
+    /** Estimated gas for the transaction */
+    estimatedGas: bigint;
+    /** Nonce to use */
+    nonce: bigint;
+    /** Signature deadline */
+    deadline: bigint;
+    /** Internal hop descriptor for cascade nesting @internal */
+    _hop: HopDescriptor;
+    /** Chain additional transactions after this one (cascade) */
+    thenOn: (nextTx: PreparedUniversalTx) => CascadedTransactionBuilder;
+    /** Execute this prepared transaction */
+    send: () => Promise<UniversalTxResponse>;
+}
+/**
+ * @deprecated Use CascadedTransactionBuilder instead.
+ * Kept for backward compatibility.
+ */
+export interface ChainedTransactionBuilder {
+    /** Add another transaction to the chain */
+    thenOn: (nextTx: UniversalExecuteParams) => ChainedTransactionBuilder;
+    /** Execute all chained transactions */
+    send: () => Promise<MultiChainTxResponse>;
+}
+/**
+ * @deprecated Use CascadedTxResponse instead.
+ * Kept for backward compatibility.
+ */
+export interface MultiChainTxResponse {
+    /** All transaction responses in execution order */
+    transactions: UniversalTxResponse[];
+    /** Summary of each chain's execution */
+    chains: {
+        chain: CHAIN;
+        hash: string;
+        blockNumber: bigint;
+        status: 'pending' | 'confirmed' | 'failed';
+    }[];
+}
+/**
+ * Builder for composing cascaded (nested) multi-chain transactions.
+ * Each call to thenOn() adds another hop to the cascade.
+ * send() composes all hops bottom-to-top and executes a single Push Chain tx.
+ */
+export interface CascadedTransactionBuilder {
+    /** Add another hop to the cascade */
+    thenOn: (nextTx: PreparedUniversalTx) => CascadedTransactionBuilder;
+    /** Compose all hops bottom-to-top and execute the single initial tx */
+    send: () => Promise<CascadedTxResponse>;
+}
+/**
+ * Response for cascaded multi-chain transactions.
+ * Contains the initial tx and tracking info for all hops.
+ */
+export interface CascadedTxResponse {
+    /** The initial Push Chain transaction hash (user-signed) */
+    initialTxHash: string;
+    /** The initial transaction response */
+    initialTxResponse: UniversalTxResponse;
+    /** Ordered list of hops with their expected routing */
+    hops: CascadeHopInfo[];
+    /** Total number of hops in the cascade */
+    hopCount: number;
+    /** Wait for ALL hops to complete across all chains */
+    waitForAll: (opts?: CascadeTrackOptions) => Promise<CascadeCompletionResult>;
+    /** Convenience alias for waitForAll() */
+    wait: (opts?: CascadeTrackOptions) => Promise<CascadeCompletionResult>;
+}
+/**
+ * Information about a single hop in a cascade
+ */
+export interface CascadeHopInfo {
+    /** Index in the cascade (0 = first hop) */
+    hopIndex: number;
+    /** Route for this hop */
+    route: TransactionRouteType;
+    /** Chain where execution occurs */
+    executionChain: CHAIN;
+    /** Expected universalSubTxId (computed from parent) */
+    expectedSubTxId?: string;
+    /** Status tracking */
+    status: 'pending' | 'submitted' | 'confirmed' | 'failed';
+    /** Resolved tx hash once available */
+    txHash?: string;
+    /** External chain tx details (for outbound hops) */
+    outboundDetails?: OutboundTxDetails;
+}
+/**
+ * Options for cascade tracking
+ */
+export interface CascadeTrackOptions {
+    /** Polling interval (default: 5000ms) */
+    pollingIntervalMs?: number;
+    /** Total timeout (default: 600000ms = 10 min) */
+    timeout?: number;
+    /** Progress callback */
+    progressHook?: (event: CascadeProgressEvent) => void;
+}
+/**
+ * Progress event emitted during cascade tracking
+ */
+export interface CascadeProgressEvent {
+    hopIndex: number;
+    route: TransactionRouteType;
+    chain: CHAIN;
+    status: 'waiting' | 'polling' | 'found' | 'confirmed' | 'failed' | 'timeout';
+    txHash?: string;
+    elapsed: number;
+}
+/**
+ * Final result of cascade completion tracking
+ */
+export interface CascadeCompletionResult {
+    /** Whether all hops completed successfully */
+    success: boolean;
+    /** Final state of all hops */
+    hops: CascadeHopInfo[];
+    /** Index of first failed hop (if any) */
+    failedAt?: number;
+}
 export interface TrackTransactionOptions {
     /**
      * Target chain to track transaction on. Defaults to Push Chain based on client network.
@@ -202,3 +598,94 @@ export interface TrackTransactionOptions {
         rpcUrls?: Partial<Record<import('../constants/enums').CHAIN, string[]>>;
     };
 }
+/**
+ * External chain transaction details after relay completion
+ */
+export interface OutboundTxDetails {
+    /** Transaction hash on the external chain */
+    externalTxHash: string;
+    /** Target chain enum */
+    destinationChain: import('../constants/enums').CHAIN;
+    /** Full explorer URL for the transaction */
+    explorerUrl: string;
+    /** Recipient address on the external chain */
+    recipient: string;
+    /** Amount transferred */
+    amount: string;
+    /** Asset address on external chain (address(0) for native) */
+    assetAddr: string;
+}
+/**
+ * Progress event for outbound sync operations
+ */
+export interface OutboundSyncProgress {
+    status: 'waiting' | 'polling' | 'success' | 'failed' | 'timeout';
+    elapsed: number;
+}
+/**
+ * Options for waitForOutboundTx polling
+ */
+export interface WaitForOutboundOptions {
+    /**
+     * Initial wait before first poll (default: 30000ms)
+     * Gives relay time to process before we start polling
+     */
+    initialWaitMs?: number;
+    /**
+     * Interval between polls (default: 5000ms)
+     */
+    pollingIntervalMs?: number;
+    /**
+     * Total timeout in milliseconds (default: 120000ms)
+     * Measured from start, includes initial wait
+     */
+    timeout?: number;
+    /**
+     * Progress callback for tracking events
+     */
+    progressHook?: (event: {
+        status: 'waiting' | 'polling' | 'found' | 'failed' | 'timeout';
+        elapsed: number;
+    }) => void;
+    /**
+     * @internal Pre-resolved universalSubTxId for cascade per-hop tracking.
+     * When provided, skips extraction from the Push Chain tx events.
+     */
+    _resolvedSubTxId?: string;
+    /**
+     * @internal Expected destination chain CAIP-2 namespace (e.g., 'eip155:97').
+     * When provided, only considers an outbound as found if its destinationChain
+     * matches this value. Used for multi-outbound cascades where a single utx_id
+     * has multiple outbound operations to different chains.
+     */
+    _expectedDestinationChain?: string;
+}
+/**
+ * UEA deployment and version status.
+ * Versions are stored as strings (e.g. "1.0.2") matching the on-chain format.
+ * Comparison uses parseUEAVersion() to convert to numeric for ordering.
+ */
+export interface UEAStatus {
+    /** Whether status has been fetched from chain */
+    loaded: boolean;
+    /** Whether the UEA proxy is deployed on Push Chain */
+    deployed: boolean;
+    /** Current UEA implementation version string (e.g. "1.0.0", empty if not deployed) */
+    version: string;
+    /** Latest required version from UEAFactory (e.g. "1.0.2", empty if unknown) */
+    minRequiredVersion: string;
+    /** True when deployed && parseUEAVersion(version) < parseUEAVersion(minRequiredVersion) */
+    requiresUpgrade: boolean;
+}
+/**
+ * Account status returned by pushChainClient.getAccountStatus()
+ */
+export interface AccountStatus {
+    mode: 'read-only' | 'signer';
+    uea: UEAStatus;
+}
+/**
+ * Parse a semver string into the numeric UEA version format.
+ * e.g. "1.0.2" → 1000002
+ */
+export declare function parseUEAVersion(version: string): number;

package/src/lib/orchestrator/orchestrator.types.js

@@ -1,3 +1,20 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseUEAVersion = parseUEAVersion;
+// ============================================================================
+// UEA Version Utilities
+// ============================================================================
+/**
+ * Parse a semver string into the numeric UEA version format.
+ * e.g. "1.0.2" → 1000002
+ */
+function parseUEAVersion(version) {
+    const parts = version.split('.');
+    if (parts.length !== 3)
+        return 0;
+    const major = parseInt(parts[0], 10) || 0;
+    const minor = parseInt(parts[1], 10) || 0;
+    const patch = parseInt(parts[2], 10) || 0;
+    return major * 1000000 + minor * 1000 + patch;
+}
 //# sourceMappingURL=orchestrator.types.js.map

package/src/lib/orchestrator/orchestrator.types.js.map

@@ -1 +1 @@
-{"version":3,"file":"orchestrator.types.js","sourceRoot":"","sources":["../../../../../../packages/core/src/lib/orchestrator/orchestrator.types.ts"],"names":[],"mappings":""}
+{"version":3,"file":"orchestrator.types.js","sourceRoot":"","sources":["../../../../../../packages/core/src/lib/orchestrator/orchestrator.types.ts"],"names":[],"mappings":";;AAy1BA,0CAOC;AAfD,+EAA+E;AAC/E,wBAAwB;AACxB,+EAA+E;AAE/E;;;GAGG;AACH,SAAgB,eAAe,CAAC,OAAe;IAC7C,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACjC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IACjC,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;IAC1C,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;IAC1C,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;IAC1C,OAAO,KAAK,GAAG,OAAO,GAAG,KAAK,GAAG,IAAI,GAAG,KAAK,CAAC;AAChD,CAAC"}