@portal-hq/web 3.13.1 → 3.13.2-0

package/src/internal/pollLoop.test.ts

@@ -0,0 +1,109 @@
+import { pollLoop, PollLoopTimeoutError, type PollTickResult } from './pollLoop'
+
+describe('pollLoop', () => {
+  it('returns immediately when tick returns stop', async () => {
+    const tick = jest.fn().mockResolvedValue({
+      kind: 'stop',
+      value: 42,
+    } as PollTickResult<number>)
+
+    await expect(
+      pollLoop({
+        tick,
+        intervalMs: 1000,
+        timeoutMs: 5000,
+      }),
+    ).resolves.toBe(42)
+    expect(tick).toHaveBeenCalledTimes(1)
+  })
+
+  it('rejects when tick returns throw', async () => {
+    const err = new Error('tick failed')
+    const tick = jest.fn().mockResolvedValue({
+      kind: 'throw',
+      error: err,
+    } as PollTickResult<never>)
+
+    await expect(
+      pollLoop({
+        tick,
+        intervalMs: 100,
+        timeoutMs: 1000,
+      }),
+    ).rejects.toThrow('tick failed')
+  })
+
+  it('throws PollLoopTimeoutError when tick always continues', async () => {
+    jest.useFakeTimers()
+    const tick = jest.fn().mockResolvedValue({ kind: 'continue' } as const)
+
+    const p = pollLoop({
+      tick,
+      intervalMs: 10,
+      timeoutMs: 100,
+    })
+
+    const expectTimeout = expect(p).rejects.toBeInstanceOf(PollLoopTimeoutError)
+    await jest.runAllTimersAsync()
+    await expectTimeout
+    jest.useRealTimers()
+  })
+
+  it('waits initialDelayMs before first tick', async () => {
+    jest.useFakeTimers()
+    const tick = jest.fn().mockResolvedValue({
+      kind: 'stop',
+      value: true,
+    } as PollTickResult<boolean>)
+
+    const p = pollLoop({
+      tick,
+      intervalMs: 100,
+      initialDelayMs: 300,
+      timeoutMs: 2000,
+    })
+
+    expect(tick).not.toHaveBeenCalled()
+    await jest.advanceTimersByTimeAsync(299)
+    expect(tick).not.toHaveBeenCalled()
+    await jest.advanceTimersByTimeAsync(1)
+    await expect(p).resolves.toBe(true)
+    expect(tick).toHaveBeenCalledTimes(1)
+    jest.useRealTimers()
+  })
+
+  it('increases sleep interval with backoff until maxIntervalMs', async () => {
+    jest.useFakeTimers()
+    let n = 0
+    const tick = jest.fn().mockImplementation(async () => {
+      n += 1
+      if (n < 3) {
+        return { kind: 'continue' } as const
+      }
+      return { kind: 'stop', value: 'ok' } as PollTickResult<string>
+    })
+
+    const p = pollLoop({
+      tick,
+      intervalMs: 10,
+      timeoutMs: 10_000,
+      backoff: { factor: 100, maxIntervalMs: 500 },
+    })
+
+    const settled = p.then((v) => v)
+    await Promise.resolve()
+    expect(tick).toHaveBeenCalledTimes(1)
+
+    await jest.advanceTimersByTimeAsync(10)
+    await Promise.resolve()
+    expect(tick).toHaveBeenCalledTimes(2)
+
+    await jest.advanceTimersByTimeAsync(500)
+    await Promise.resolve()
+    expect(tick).toHaveBeenCalledTimes(3)
+
+    await settled
+    expect(await settled).toBe('ok')
+    jest.useRealTimers()
+  })
+})

package/src/internal/pollLoop.ts

@@ -0,0 +1,87 @@
+/**
+ * Domain-agnostic poll loop (sleep + deadline + optional backoff).
+ * LiFi / other modules supply classification via `tick`.
+ */
+
+export type PollTickResult<T> =
+  | { kind: 'stop'; value: T }
+  | { kind: 'throw'; error: Error }
+  | { kind: 'continue' }
+
+export interface PollLoopBackoff {
+  factor: number
+  maxIntervalMs: number
+}
+
+export interface PollLoopOptions<T> {
+  tick: () => Promise<PollTickResult<T>>
+  /** Base delay between polls (ms), after optional {@link initialDelayMs}. */
+  intervalMs: number
+  /** Wait this long before the first {@link tick}. @default 0 */
+  initialDelayMs?: number
+  backoff?: PollLoopBackoff
+  timeoutMs: number
+}
+
+export class PollLoopTimeoutError extends Error {
+  override readonly name = 'PollLoopTimeoutError'
+
+  constructor(message: string) {
+    super(message)
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+/**
+ * Repeatedly awaits `tick` until it returns `stop` (returns value), `throw` (propagates),
+ * or the deadline passes (throws {@link PollLoopTimeoutError}).
+ */
+export async function pollLoop<T>(options: PollLoopOptions<T>): Promise<T> {
+  const {
+    tick,
+    intervalMs: baseIntervalMs,
+    initialDelayMs = 0,
+    backoff,
+    timeoutMs,
+  } = options
+
+  const deadline = Date.now() + timeoutMs
+  let interval = baseIntervalMs
+
+  if (initialDelayMs > 0) {
+    await sleep(initialDelayMs)
+  }
+
+  while (Date.now() < deadline) {
+    const result = await tick()
+    
+    // Check deadline again after tick completes (tick may have taken a long time)
+    if (Date.now() >= deadline && result.kind === 'continue') {
+      break
+    }
+    
+    if (result.kind === 'stop') {
+      return result.value
+    }
+    if (result.kind === 'throw') {
+      throw result.error
+    }
+
+    const remaining = deadline - Date.now()
+    if (remaining <= 0) {
+      break
+    }
+
+    const sleepMs = Math.min(interval, Math.max(0, remaining))
+    await sleep(sleepMs)
+
+    if (backoff) {
+      interval = Math.min(interval * backoff.factor, backoff.maxIntervalMs)
+    }
+  }
+
+  throw new PollLoopTimeoutError(`pollLoop timed out after ${timeoutMs}ms`)
+}

package/src/internal/stripStalePlanningNonce.test.ts

@@ -0,0 +1,38 @@
+/**
+ * @jest-environment node
+ */
+
+import { stripStalePlanningNonceIfJsonObject } from './stripStalePlanningNonce'
+
+describe('stripStalePlanningNonceIfJsonObject', () => {
+  it('removes nonce from a flat tx object', () => {
+    const tx = { from: '0xa', to: '0xb', nonce: '0x5', data: '0x' }
+    expect(stripStalePlanningNonceIfJsonObject(tx)).toEqual({
+      from: '0xa',
+      to: '0xb',
+      data: '0x',
+    })
+  })
+
+  it('unwraps single-key wrapper then strips nonce', () => {
+    const wrapped = {
+      transaction: { from: '0xa', nonce: 1, value: '0x0' },
+    }
+    expect(stripStalePlanningNonceIfJsonObject(wrapped)).toEqual({
+      from: '0xa',
+      value: '0x0',
+    })
+  })
+
+  it('parses JSON string and strips nonce', () => {
+    const s = JSON.stringify({ to: '0xt', nonce: '2', gas: '21000' })
+    expect(stripStalePlanningNonceIfJsonObject(s)).toEqual({
+      to: '0xt',
+      gas: '21000',
+    })
+  })
+
+  it('returns opaque string on parse error', () => {
+    expect(stripStalePlanningNonceIfJsonObject('not-json')).toBe('not-json')
+  })
+})

package/src/internal/stripStalePlanningNonce.ts

@@ -0,0 +1,66 @@
+/**
+ * Removes a stale `nonce` from EVM tx payloads planned ahead of signing so the
+ * signer can fetch a fresh nonce at broadcast time (multi-step Yield / LiFi).
+ */
+
+function unwrapSingleKeyTransactionObject(
+  obj: Record<string, unknown>,
+): Record<string, unknown> {
+  const keys = Object.keys(obj)
+  if (keys.length !== 1) {
+    return obj
+  }
+  
+  const firstKey = keys[0]
+  const inner = obj[firstKey]
+  
+  // Type guard: only unwrap if inner value is a plain object
+  if (
+    typeof inner === 'object' &&
+    inner !== null &&
+    !Array.isArray(inner)
+  ) {
+    return inner as Record<string, unknown>
+  }
+  
+  return obj
+}
+
+/**
+ * If the payload is JSON (object or JSON string), drop `nonce` from the inner tx object.
+ * Otherwise returns the input unchanged.
+ */
+export function stripStalePlanningNonceIfJsonObject(
+  unsigned: string | Record<string, unknown>,
+): unknown {
+  if (
+    typeof unsigned === 'object' &&
+    unsigned !== null &&
+    !Array.isArray(unsigned)
+  ) {
+    const spread = { ...unsigned } as Record<string, unknown>
+    const inner = unwrapSingleKeyTransactionObject(spread)
+    const { nonce: _staleNonce, ...rest } = inner
+    return rest
+  }
+  if (typeof unsigned === 'string') {
+    try {
+      const parsed = JSON.parse(unsigned) as unknown
+      // Validate parsed result is a plain object
+      if (
+        typeof parsed === 'object' &&
+        parsed !== null &&
+        !Array.isArray(parsed)
+      ) {
+        const inner = unwrapSingleKeyTransactionObject(
+          parsed as Record<string, unknown>,
+        )
+        const { nonce: _staleNonce, ...rest } = inner
+        return rest
+      }
+    } catch {
+      return unsigned
+    }
+  }
+  return unsigned
+}

package/src/internal/waitForEvmOrUserOpConfirmation.test.ts

@@ -0,0 +1,31 @@
+/**
+ * @jest-environment node
+ */
+
+import { waitForEvmOrUserOpConfirmation } from './waitForEvmOrUserOpConfirmation'
+
+describe('waitForEvmOrUserOpConfirmation', () => {
+  beforeEach(() => {
+    jest.useFakeTimers()
+  })
+
+  afterEach(() => {
+    jest.useRealTimers()
+  })
+
+  it('returns false on timeout when receipt never appears', async () => {
+    const request = jest.fn().mockImplementation(async () => null)
+
+    const done = waitForEvmOrUserOpConfirmation('0x1', 'eip155:1', request, {
+      pollIntervalMs: 1_000,
+      timeoutMs: 2_500,
+    })
+
+    await jest.advanceTimersByTimeAsync(3_100)
+
+    await expect(done).resolves.toBe(false)
+    expect(request.mock.calls.some((c) => c[0] === 'eth_getTransactionReceipt')).toBe(
+      true,
+    )
+  })
+})

package/src/internal/waitForEvmOrUserOpConfirmation.ts

@@ -0,0 +1,194 @@
+import { sdkLogger } from '../logger'
+
+import {
+  pollLoop,
+  PollLoopTimeoutError,
+  type PollTickResult,
+} from './pollLoop'
+import type { EvmRequestFn } from './waitForEvmTxConfirmation'
+
+const LOG_PREFIX = '[Portal.waitForConfirmation]'
+
+type ConfirmationMode = 'auto' | 'tx' | 'userOp'
+type ReceiptState = 'not_found' | 'pending' | 'success' | 'failed'
+
+interface EvmTxReceiptLike {
+  blockNumber?: string | null
+  status?: string | number | null
+}
+
+interface UserOpReceiptLike {
+  success?: boolean | null
+  receipt?: {
+    blockNumber?: string | null
+    status?: string | number | null
+  } | null
+}
+
+function parseStatusToOutcome(status: unknown): 'success' | 'failed' | 'unknown' {
+  if (typeof status === 'boolean') return status ? 'success' : 'failed'
+  if (typeof status === 'number') return status === 1 ? 'success' : 'failed'
+  if (typeof status === 'string') {
+    const normalized = status.trim().toLowerCase()
+    if (normalized === '0x1' || normalized === '1') return 'success'
+    if (normalized === '0x0' || normalized === '0') return 'failed'
+  }
+  return 'unknown'
+}
+
+function parseTxReceiptState(raw: unknown): ReceiptState {
+  if (raw == null || typeof raw !== 'object') return 'not_found'
+  const receipt = raw as EvmTxReceiptLike
+
+  if (receipt.blockNumber == null) return 'pending'
+
+  const outcome = parseStatusToOutcome(receipt.status)
+  if (outcome === 'success') return 'success'
+  if (outcome === 'failed') return 'failed'
+
+  return 'pending'
+}
+
+function parseUserOpReceiptState(raw: unknown): ReceiptState {
+  if (raw == null || typeof raw !== 'object') return 'not_found'
+  const receipt = raw as UserOpReceiptLike
+
+  if (typeof receipt.success === 'boolean') {
+    return receipt.success ? 'success' : 'failed'
+  }
+
+  const nested = receipt.receipt
+  if (nested == null) return 'pending'
+  if (nested.blockNumber == null) return 'pending'
+
+  const outcome = parseStatusToOutcome(nested.status)
+  if (outcome === 'success') return 'success'
+  if (outcome === 'failed') return 'failed'
+
+  return 'pending'
+}
+
+function isMethodNotSupportedError(error: unknown): boolean {
+  const message =
+    error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase()
+
+  return (
+    message.includes('method not found') ||
+    message.includes('does not exist/is not available') ||
+    message.includes('-32601') ||
+    message.includes('eth_getuseroperationreceipt')
+  )
+}
+
+export interface WaitForEvmOrUserOpConfirmationOptions {
+  pollIntervalMs?: number
+  timeoutMs?: number
+  onTimeout?: 'resolve_false' | 'throw'
+  lockModeAfterDetection?: boolean
+}
+
+export async function waitForEvmOrUserOpConfirmation(
+  hash: string,
+  network: string,
+  request: EvmRequestFn,
+  options: WaitForEvmOrUserOpConfirmationOptions = {},
+): Promise<boolean> {
+  const {
+    pollIntervalMs = 4_000,
+    timeoutMs = 300_000,
+    onTimeout = 'resolve_false',
+    lockModeAfterDetection = true,
+  } = options
+
+  let mode: ConfirmationMode = 'auto'
+  let userOpMethodSupported = true
+
+  sdkLogger.debug(`${LOG_PREFIX} waiting for tx/userOp confirmation`, {
+    hash,
+    network,
+    pollIntervalMs,
+    timeoutMs,
+    mode,
+  })
+
+  const tick = async (): Promise<PollTickResult<boolean>> => {
+    if (mode !== 'userOp') {
+      try {
+        const txRaw = await request('eth_getTransactionReceipt', [hash], network)
+        const txState = parseTxReceiptState(txRaw)
+
+        if (txState === 'success') return { kind: 'stop', value: true }
+        if (txState === 'failed') return { kind: 'stop', value: false }
+
+        if (lockModeAfterDetection && mode === 'auto' && txState === 'pending') {
+          mode = 'tx'
+          sdkLogger.debug(`${LOG_PREFIX} mode locked`, { hash, network, mode })
+        }
+      } catch (error) {
+        sdkLogger.warn(`${LOG_PREFIX} tx receipt poll transient error`, {
+          hash,
+          network,
+          error: error instanceof Error ? error.message : String(error),
+        })
+      }
+    }
+
+    if (mode !== 'tx' && userOpMethodSupported) {
+      try {
+        const userOpRaw = await request(
+          'eth_getUserOperationReceipt',
+          [hash],
+          network,
+        )
+        const userOpState = parseUserOpReceiptState(userOpRaw)
+
+        if (userOpState === 'success') return { kind: 'stop', value: true }
+        if (userOpState === 'failed') return { kind: 'stop', value: false }
+
+        if (
+          lockModeAfterDetection &&
+          mode === 'auto' &&
+          userOpState === 'pending'
+        ) {
+          mode = 'userOp'
+          sdkLogger.debug(`${LOG_PREFIX} mode locked`, { hash, network, mode })
+        }
+      } catch (error) {
+        if (isMethodNotSupportedError(error)) {
+          userOpMethodSupported = false
+          sdkLogger.debug(
+            `${LOG_PREFIX} eth_getUserOperationReceipt unsupported; disabling userOp polling`,
+            { hash, network },
+          )
+        } else {
+          sdkLogger.warn(`${LOG_PREFIX} userOp receipt poll transient error`, {
+            hash,
+            network,
+            error: error instanceof Error ? error.message : String(error),
+          })
+        }
+      }
+    }
+
+    return { kind: 'continue' }
+  }
+
+  try {
+    return await pollLoop<boolean>({
+      tick,
+      intervalMs: pollIntervalMs,
+      initialDelayMs: 0,
+      timeoutMs,
+    })
+  } catch (error) {
+    if (error instanceof PollLoopTimeoutError) {
+      const msg = `${LOG_PREFIX} timeout after ${timeoutMs}ms waiting for confirmation on ${hash} (${network}).`
+      if (onTimeout === 'throw') {
+        throw new Error(`${msg} Confirmation not reached.`)
+      }
+      sdkLogger.warn(`${msg} Returning false (resolve_false).`)
+      return false
+    }
+    throw error
+  }
+}

package/src/internal/waitForEvmTxConfirmation.ts

@@ -0,0 +1,155 @@
+/**
+ * Shared EVM transaction confirmation via `eth_getTransactionReceipt` + {@link pollLoop}.
+ *
+ * **Use in each domain:**
+ * - **Yield** (multi-step): Prefer {@link Portal.waitForConfirmation} (returns `false` on soft timeout)
+ *   or standalone `pollForEvmReceipt` (same engine).
+ * - **LiFi** (`tradeAsset`): Use `onTimeout: 'throw'` with the same RPC `request` as Portal's
+ *   gateway so a stuck tx fails before bridge status polling.
+ * - **Legacy swaps** (`@portal-hq/swaps`): Call `portal.waitForConfirmation(txHash, caip2)` after
+ *   `eth_sendTransaction` so "submitted" reflects chain inclusion when the network is known.
+ *
+ * Domain-specific orchestration (LiFi status, Yield multi-tx, route steps) stays outside this module.
+ */
+
+import { sdkLogger } from '../logger'
+
+import {
+  pollLoop,
+  PollLoopTimeoutError,
+  type PollTickResult,
+} from './pollLoop'
+
+const LOG_PREFIX = '[Portal.evmReceipt]'
+
+/** Shape of the relevant fields in an eth_getTransactionReceipt response. */
+interface EvmReceipt {
+  blockNumber: string | null
+  /** '0x1' = success, '0x0' = reverted, absent on pending txs */
+  status?: string
+}
+
+/** Minimal RPC: any implementation of JSON-RPC `eth_getTransactionReceipt`. */
+export type EvmRequestFn = (
+  method: string,
+  params: unknown[],
+  network: string,
+) => Promise<unknown>
+
+export type WaitForEvmTxConfirmationOnTimeout = 'resolve_false' | 'throw'
+
+export interface WaitForEvmTxConfirmationOptions {
+  pollIntervalMs?: number
+  timeoutMs?: number
+  /**
+   * Yield / `Portal.waitForConfirmation`: `resolve_false` (optimistic continuation).
+   * LiFi default waiter: `throw` so `tradeAsset` does not poll bridge status after a timed-out tx.
+   * @default 'resolve_false'
+   */
+  onTimeout?: WaitForEvmTxConfirmationOnTimeout
+}
+
+interface EvmReceiptPollTickContext {
+  txHash: string
+  network: string
+  request: EvmRequestFn
+  pollIntervalMs: number
+}
+
+async function evmReceiptPollTick(
+  ctx: EvmReceiptPollTickContext,
+): Promise<PollTickResult<boolean>> {
+  const { txHash, network, request, pollIntervalMs } = ctx
+
+  try {
+    const raw = await request('eth_getTransactionReceipt', [txHash], network)
+    const receipt = raw as EvmReceipt | null
+
+    if (receipt?.blockNumber != null) {
+      if (receipt.status === '0x0') {
+        return {
+          kind: 'throw',
+          error: new Error(
+            `${LOG_PREFIX} Transaction ${txHash} was reverted on-chain (status 0x0). ` +
+              'The transaction did not succeed.',
+          ),
+        }
+      }
+      sdkLogger.debug(`${LOG_PREFIX} receipt confirmed`, {
+        txHash,
+        network,
+        blockNumber: receipt.blockNumber,
+        status: receipt.status,
+      })
+      return { kind: 'stop', value: true }
+    }
+
+    sdkLogger.debug(`${LOG_PREFIX} not yet mined, retrying`, { txHash, network })
+    return { kind: 'continue' }
+  } catch (error) {
+    if (error instanceof Error && error.message.includes('reverted')) {
+      return { kind: 'throw', error }
+    }
+    sdkLogger.warn(
+      `${LOG_PREFIX} transient error polling receipt for ${txHash} (${network}), will retry in ${pollIntervalMs}ms:`,
+      error,
+    )
+    return { kind: 'continue' }
+  }
+}
+
+/**
+ * Poll until the tx is mined with success (`0x1`), reverted (`0x0` → throw), or timeout.
+ * Pending receipts and transient RPC errors retry with warn logs; logs always include `txHash` / `network` where relevant.
+ */
+export async function waitForEvmTxConfirmation(
+  txHash: string,
+  network: string,
+  request: EvmRequestFn,
+  options: WaitForEvmTxConfirmationOptions = {},
+): Promise<boolean> {
+  const {
+    pollIntervalMs = 4_000,
+    timeoutMs = 900_000,
+    onTimeout = 'resolve_false',
+  } = options
+
+  sdkLogger.debug(`${LOG_PREFIX} waiting for receipt`, {
+    txHash,
+    network,
+    pollIntervalMs,
+    timeoutMs,
+    onTimeout,
+  })
+
+  const tickCtx: EvmReceiptPollTickContext = {
+    txHash,
+    network,
+    request,
+    pollIntervalMs,
+  }
+
+  try {
+    return await pollLoop<boolean>({
+      tick: () => evmReceiptPollTick(tickCtx),
+      intervalMs: pollIntervalMs,
+      initialDelayMs: 0,
+      timeoutMs,
+    })
+  } catch (error) {
+    if (error instanceof PollLoopTimeoutError) {
+      const msg =
+        `${LOG_PREFIX} timeout after ${timeoutMs}ms waiting for receipt on ${txHash} (${network}).`
+      if (onTimeout === 'throw') {
+        throw new Error(
+          `${msg} Transaction may still confirm; aborting this wait.`,
+        )
+      }
+      sdkLogger.warn(
+        `${msg} Transaction may still confirm. Proceeding optimistically.`,
+      )
+      return false
+    }
+    throw error
+  }
+}