@portal-hq/web 3.13.2 → 3.14.0-alpha.0

package/src/internal/waitForSolanaTxConfirmation.ts

@@ -0,0 +1,135 @@
+import { sdkLogger } from '../logger'
+
+const LOG_PREFIX = '[Portal.waitForConfirmation]'
+
+export type SolanaConfirmationCommitment =
+  | 'processed'
+  | 'confirmed'
+  | 'finalized'
+
+export type SolanaRequestFn = (
+  method: string,
+  params: unknown[],
+  network: string,
+) => Promise<unknown>
+
+export interface WaitForSolanaTxConfirmationOptions {
+  pollIntervalMs: number
+  timeoutMs: number
+  commitment: SolanaConfirmationCommitment
+}
+
+const COMMITMENT_ORDER: Record<SolanaConfirmationCommitment, number> = {
+  processed: 0,
+  confirmed: 1,
+  finalized: 2,
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+function statusMeetsCommitment(
+  confirmationStatus: string | undefined,
+  required: SolanaConfirmationCommitment,
+): boolean {
+  if (!confirmationStatus) return false
+  const level = COMMITMENT_ORDER[confirmationStatus as SolanaConfirmationCommitment]
+  const need = COMMITMENT_ORDER[required]
+  if (level === undefined || need === undefined) return false
+  return level >= need
+}
+
+interface SignatureStatusRow {
+  err?: unknown
+  confirmationStatus?: string
+}
+
+function parseSignatureStatusesResult(raw: unknown): SignatureStatusRow | null {
+  if (raw == null || typeof raw !== 'object') return null
+  const outer = raw as { value?: unknown; result?: unknown }
+  const arr = outer.value ?? outer.result
+  if (!Array.isArray(arr) || arr.length === 0) return null
+  const first = arr[0]
+  if (first == null || typeof first !== 'object') return null
+  return first as SignatureStatusRow
+}
+
+/**
+ * Polls Solana `getSignatureStatuses` via {@link request} (routed through the
+ * iframe RPC proxy) until the signature reaches the requested commitment,
+ * fails on-chain, or times out.
+ */
+export async function waitForSolanaTxConfirmation(
+  signature: string,
+  network: string,
+  request: SolanaRequestFn,
+  options: WaitForSolanaTxConfirmationOptions,
+): Promise<boolean> {
+  const { pollIntervalMs, timeoutMs, commitment } = options
+
+  sdkLogger.debug(`${LOG_PREFIX} waiting for Solana confirmation`, {
+    signature,
+    network,
+    pollIntervalMs,
+    timeoutMs,
+    commitment,
+  })
+
+  const deadline = Date.now() + timeoutMs
+
+  while (Date.now() < deadline) {
+    try {
+      const raw = await request(
+        'getSignatureStatuses',
+        [[signature], { searchTransactionHistory: true }],
+        network,
+      )
+
+      const rpcResponse = raw as { result?: unknown; error?: unknown }
+      if (rpcResponse.error) {
+        throw new Error(
+          `${LOG_PREFIX} RPC error for getSignatureStatuses: ${JSON.stringify(rpcResponse.error)}`,
+        )
+      }
+
+      const statusRow = parseSignatureStatusesResult(
+        rpcResponse.result ?? raw,
+      )
+      if (statusRow != null) {
+        if (statusRow.err != null) {
+          sdkLogger.debug(`${LOG_PREFIX} Solana tx error on-chain`, {
+            signature,
+            network,
+            err: statusRow.err,
+          })
+          return false
+        }
+        if (statusMeetsCommitment(statusRow.confirmationStatus, commitment)) {
+          sdkLogger.debug(`${LOG_PREFIX} Solana commitment met`, {
+            signature,
+            network,
+            confirmationStatus: statusRow.confirmationStatus,
+            commitment,
+          })
+          return true
+        }
+      }
+    } catch (error) {
+      sdkLogger.warn(`${LOG_PREFIX} Solana poll transient error`, {
+        signature,
+        network,
+        error: error instanceof Error ? error.message : String(error),
+      })
+    }
+
+    const remaining = deadline - Date.now()
+    if (remaining <= 0) break
+    await sleep(Math.min(pollIntervalMs, Math.max(0, remaining)))
+  }
+
+  sdkLogger.warn(
+    `${LOG_PREFIX} timeout after ${timeoutMs}ms waiting for Solana confirmation on ${signature} (${network}). Returning false.`,
+  )
+  return false
+}

package/src/internal/yieldEvmNetwork.ts

@@ -0,0 +1,57 @@
+/**
+ * Yield / Portal-style EVM network slugs → EIP-155 CAIP-2.
+ */
+
+const YIELD_EVM_SLUG_TO_CAIP2: Record<string, string> = {
+  // Common friendly names (subset of typical integrations)
+  ethereum: 'eip155:1',
+  eth: 'eip155:1',
+  mainnet: 'eip155:1',
+  polygon: 'eip155:137',
+  matic: 'eip155:137',
+  arbitrum: 'eip155:42161',
+  optimism: 'eip155:10',
+  base: 'eip155:8453',
+  blast: 'eip155:81457',
+  scroll: 'eip155:534352',
+  mantle: 'eip155:5000',
+  mode: 'eip155:34443',
+  opbnb: 'eip155:204',
+  // Testnets and alternate slugs (e.g. *-sepolia) mapped to EIP-155 CAIP-2
+  'ethereum-sepolia': 'eip155:11155111',
+  'ethereum-goerli': 'eip155:5',
+  'ethereum-holesky': 'eip155:17000',
+  'ethereum-hoodi': 'eip155:560048',
+  binance: 'eip155:56',
+  bsc: 'eip155:56',
+  'avalanche-c': 'eip155:43114',
+  'avalanche-c-atomic': 'eip155:43114',
+  gnosis: 'eip155:100',
+  zksync: 'eip155:324',
+  linea: 'eip155:59144',
+  celo: 'eip155:42220',
+  fantom: 'eip155:250',
+  harmony: 'eip155:1666600000',
+  moonriver: 'eip155:1285',
+  okc: 'eip155:66',
+  viction: 'eip155:88',
+  core: 'eip155:1116',
+  cronos: 'eip155:25',
+  evmos: 'eip155:9001',
+  unichain: 'eip155:130',
+  sonic: 'eip155:146',
+}
+
+/** Resolve a Yield transaction `network` string to EIP-155 CAIP-2 when known. */
+export function resolveYieldNetworkToCaip2(
+  network: string,
+): string | undefined {
+  if (typeof network !== 'string' || network === '') return undefined
+  if (network.startsWith('eip155:')) return network
+  if (network.toLowerCase().startsWith('solana')) return undefined
+  return YIELD_EVM_SLUG_TO_CAIP2[network.toLowerCase()]
+}
+
+export function isYieldEvmNetwork(network: string): boolean {
+  return resolveYieldNetworkToCaip2(network) !== undefined
+}

package/src/mpc/index.ts

@@ -41,6 +41,10 @@ import type {
   FundParams,
   FundResponse,
 } from '../../types'
+import type {
+  GetTransactionHistoryParams,
+  GetTransactionHistoryResponse,
+} from '../shared/types'
 import {
   YieldXyzEnterRequest,
   YieldXyzEnterYieldResponse,
@@ -57,6 +61,9 @@ import {
   YieldXyzManageYieldResponse,
   YieldXyzTrackTransactionRequest,
   YieldXyzTrackTransactionResponse,
+  YieldXyzGetYieldDefaultsRequest,
+  YieldXyzGetYieldDefaultsResponse,
+  YieldXyzGetYieldValidatorsResponse,
   LifiQuoteRequest,
   LifiQuoteResponse,
   LifiRoutesRequest,
@@ -118,6 +125,8 @@ import {
   TransferFromRequest,
   TransferFromResponse,
   RawSignOptions,
+  RpcProxyRequest,
+  RpcProxyResponse,
 } from '../shared/types'
 import {
   ScreenAddressApiResponse,
@@ -125,7 +134,7 @@ import {
 } from '../../hypernative'
 import { generateTraceId } from '../shared/trace'
 
-const WEB_SDK_VERSION = '3.13.2'
+const WEB_SDK_VERSION = '3.14.0-alpha.0'
 
 class Mpc {
   public iframe?: HTMLIFrameElement
@@ -452,12 +461,25 @@ class Mpc {
     })
   }
 
+  /**
+   * @deprecated This method is deprecated and will be removed in a future version.
+   * Please use `getTransactionHistory()` instead, which uses the new Portal v3 API
+   * endpoint and returns the unified transaction format across all chains.
+   */
   public async getTransactions(
     chainId: string,
     limit?: number,
     offset?: number,
     order?: GetTransactionsOrder,
   ): Promise<Transaction[]> {
+    // Log deprecation warning
+    sdkLogger.warn(
+      '[DEPRECATED] getTransactions() is deprecated and will be removed in a future version. ' +
+      'Please use getTransactionHistory() instead, which provides improved type safety with ' +
+      'discriminated unions for regular transactions and UserOperations, and proper polymorphic ' +
+      'response types for Solana vs unified formats.'
+    )
+
     return this.handleRequestToIframeAndPost({
       methodMessage: 'portal:getTransactions',
       errorMessage: 'portal:getTransactionsError',
@@ -471,6 +493,32 @@ class Mpc {
     })
   }
 
+  /**
+   * Retrieves transaction history for the client's wallet on the specified chain.
+   * 
+   * This method uses the new Portal v3 API endpoint and returns the unified
+   * transaction format. Supports EVM (EIP-155), Solana, Bitcoin, Tron, and Stellar chains.
+   * 
+   * @param params - Request parameters
+   * @param params.chainId - Chain ID in CAIP-2 format (e.g., 'eip155:1', 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp')
+   * @param params.limit - Maximum number of transactions to return (default: 50)
+   * @param params.offset - Number of transactions to skip (default: 0)
+   * @param params.order - Sort order ('asc' or 'desc')
+   * @param params.address - Override wallet address (EVM only)
+   * @param params.userOperations - Filter for ERC-4337 UserOperations (EVM only)
+   * @returns Promise resolving to transaction history response
+   */
+  public async getTransactionHistory(
+    params: GetTransactionHistoryParams,
+  ): Promise<GetTransactionHistoryResponse> {
+    return this.handleRequestToIframeAndPost({
+      methodMessage: 'portal:getTransactionHistory',
+      errorMessage: 'portal:getTransactionHistoryError',
+      resultMessage: 'portal:getTransactionHistoryResult',
+      data: params,
+    })
+  }
+
   public async setBackupStatus(
     status: string,
     backupIds: string[],
@@ -640,6 +688,28 @@ class Mpc {
     })
   }
 
+  public async getYieldXyzDefaults(
+    data?: YieldXyzGetYieldDefaultsRequest,
+  ): Promise<YieldXyzGetYieldDefaultsResponse> {
+    return this.handleRequestToIframeAndPost({
+      methodMessage: 'portal:yieldxyz:getDefaults',
+      errorMessage: 'portal:yieldxyz:getDefaultsError',
+      resultMessage: 'portal:yieldxyz:getDefaultsResult',
+      data: data ?? {},
+    })
+  }
+
+  public async getYieldXyzValidators(
+    yieldId: string,
+  ): Promise<YieldXyzGetYieldValidatorsResponse> {
+    return this.handleRequestToIframeAndPost({
+      methodMessage: 'portal:yieldxyz:getValidators',
+      errorMessage: 'portal:yieldxyz:getValidatorsError',
+      resultMessage: 'portal:yieldxyz:getValidatorsResult',
+      data: yieldId,
+    })
+  }
+
   public async getLifiRoutes(
     data: LifiRoutesRequest,
   ): Promise<LifiRoutesResponse> {
@@ -1122,6 +1192,8 @@ class Mpc {
       mpcVersion: this.portal.mpcVersion,
       featureFlags: this.portal.featureFlags,
       logLevel: this.portal.getLogLevel(),
+      rpcConfig: this.portal.rpcConfig,
+      iframeRpcConfig: this.portal.iframeRpcConfig,
     }
 
     const message = {
@@ -1210,6 +1282,75 @@ class Mpc {
     })
   }
 
+  public async rpcRequest(
+    data: Omit<RpcProxyRequest, 'requestId'>,
+    options?: { timeoutMs?: number; traceId?: string },
+  ): Promise<RpcProxyResponse> {
+    const { timeoutMs = 30_000, traceId } = options ?? {}
+    const requestId =
+      crypto.randomUUID?.() ?? `${Date.now()}-${Math.random()}`
+    const resolvedTraceId = traceId ?? generateTraceId()
+
+    sdkLogger.debug('[Portal] rpcRequest', {
+      requestId,
+      method: data.method,
+      chainId: data.chainId,
+      traceId: resolvedTraceId,
+      timeoutMs,
+    })
+
+    return new Promise((resolve, reject) => {
+      let timeoutId: ReturnType<typeof setTimeout> | undefined
+
+      const cleanup = () => {
+        window.removeEventListener('message', handleResponse)
+        if (timeoutId !== undefined) {
+          clearTimeout(timeoutId)
+        }
+      }
+
+      const handleResponse = (event: MessageEvent) => {
+        const { origin } = event
+        if (origin !== this.getOrigin()) return
+
+        const { type, data: result } = event.data
+        if (
+          type === 'portal:rpc:requestResult' &&
+          result?.requestId === requestId
+        ) {
+          cleanup()
+          resolve(result as RpcProxyResponse)
+        } else if (
+          type === 'portal:rpc:requestError' &&
+          result?.requestId === requestId
+        ) {
+          cleanup()
+          reject(new Error(result.message ?? 'RPC proxy error'))
+        }
+      }
+
+      timeoutId = setTimeout(() => {
+        cleanup()
+        const msg = `RPC request ${requestId} (${data.method}) timed out after ${timeoutMs}ms`
+        sdkLogger.error('[Portal] rpcRequest timeout', {
+          requestId,
+          method: data.method,
+          chainId: data.chainId,
+          timeoutMs,
+        })
+        reject(new Error(msg))
+      }, timeoutMs)
+
+      window.addEventListener('message', handleResponse)
+
+      this.postMessage({
+        type: 'portal:rpc:request',
+        data: { ...data, requestId },
+        traceId: resolvedTraceId,
+      })
+    })
+  }
+
   private postMessage(event: { type: string; data: any; traceId?: string }) {
     this.iframe?.contentWindow?.postMessage(event, this.getOrigin())
   }

package/src/provider/index.ts

@@ -157,6 +157,12 @@ const signerMethods = [
   RequestMethod.sol_signTransaction,
 ]
 
+const iframeProxiedMethodStrings: string[] = [
+  'eth_getTransactionReceipt',
+  'eth_getUserOperationReceipt',
+  'getSignatureStatuses',
+]
+
 class Provider {
   public events: Record<string, RegisteredEventHandler[]>
 
@@ -419,6 +425,25 @@ class Provider {
     params,
     traceId,
   }: RequestArguments): Promise<any> {
+    if (iframeProxiedMethodStrings.includes(method)) {
+      sdkLogger.info(
+        `[PortalProvider] routing ${method} through iframe (chainId=${String(chainId)})`,
+        { traceId },
+      )
+      return this.portal.mpc.rpcRequest(
+        {
+          method,
+          params: Array.isArray(params)
+            ? params
+            : params != null
+              ? [params]
+              : [],
+          chainId: chainId as string,
+        },
+        { traceId },
+      )
+    }
+
     const requestBody = {
       body: JSON.stringify({
         jsonrpc: '2.0',

package/src/shared/trace/index.ts

@@ -1,6 +1,5 @@
 /**
  * Request tracing for Portal API calls.
- * Aligns with portal-react-native X-Portal-Trace-Id / traceId behavior.
  *
  * Propagation in the Web SDK:
  * - Browser: High-level methods (backup, recover, sendAsset, provider.request) accept optional

package/src/shared/types/README.md

@@ -0,0 +1,6 @@
+# Shared types (canonical source)
+
+Type definitions in this folder are the single source of truth for Web and related packages.
+
+- **Browser (`packages/browser`)** — run `yarn shared:symlink` (dev) or `yarn shared:copy` (CI/publish) from the browser package so `src/shared` mirrors `packages/shared/src`.
+- **Do not** maintain divergent copies of these files under `packages/browser/src/shared/types`; edit here and re-sync the browser package.

package/src/shared/types/api.ts

@@ -2,7 +2,7 @@
  * API response types shared between browser and iframe packages
  */
 
-import type { FeatureFlags, GDriveConfig, PasskeyConfig } from './common'
+import type { FeatureFlags, GDriveConfig, PasskeyConfig, RpcConfig } from './common'
 
 // Asset response types
 export interface GetAssetsResponse {
@@ -147,6 +147,17 @@ export interface IframeConfigurationOptions {
   /** When set to 'none', the iframe SDK will not log to the console. Passed from parent via portal:configure. */
   logLevel?: IframeLogLevel
 
+  /** RPC endpoint map (CAIP-2 chainId → URL). Passed from parent so the iframe can proxy RPC calls. */
+  rpcConfig?: RpcConfig
+
+  /**
+   * Optional RPC map used only for iframe-proxied JSON-RPC (receipt polling, Solana status, etc.).
+   * When set, the iframe `fetch`es these URLs instead of {@link rpcConfig}. The parent still uses
+   * `rpcConfig` for signing (`mpc.sign` / `getRpcUrl`). Use in local dev when the gateway URL must
+   * match presignature but the iframe origin is blocked by CORS (e.g. same-origin or local proxy).
+   */
+  iframeRpcConfig?: RpcConfig
+
   // One of these three is required for authentication
   apiKey?: string
   authToken?: string