@portal-hq/web 3.11.0 → 3.12.0

package/src/shared/trace/index.ts

@@ -0,0 +1,59 @@
+/**
+ * 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
+ *   traceId or generate one. They pass it to handleRequestToIframeAndPost (postMessage) or
+ *   to fetch headers (X-Portal-Trace-Id).
+ * - Iframe: On each portal:* message, the iframe reads traceId from the message (top-level or
+ *   data.traceId), calls setRequestTraceId(traceId), which sets it on Api, Mpc, ZeroX, etc.
+ *   All REST and MPC calls made during that request then use the same trace ID (header or reqId).
+ * - After the request completes, clearRequestTraceId() is called so the next message gets a
+ *   fresh or caller-provided trace ID.
+ */
+
+/**
+ * HTTP header name for request tracing.
+ * Used by connect-api (client + custodian APIs) in the Web SDK.
+ * Note: Other internal services may use different header names.
+ */
+export const X_PORTAL_TRACE_ID_HEADER = 'X-Portal-Trace-Id'
+
+/**
+ * Generates a UUID v4 trace ID for request correlation.
+ * Uses crypto.randomUUID() when available; otherwise crypto.getRandomValues() for better
+ * quality than Math.random(); falls back to Math.random() only when no crypto API exists.
+ */
+export function generateTraceId(): string {
+  if (
+    typeof crypto !== 'undefined' &&
+    typeof (crypto as Crypto).randomUUID === 'function'
+  ) {
+    return (crypto as Crypto).randomUUID()
+  }
+  if (
+    typeof crypto !== 'undefined' &&
+    typeof (crypto as Crypto).getRandomValues === 'function'
+  ) {
+    return fallbackUuidV4WithCrypto(crypto as Crypto)
+  }
+  return fallbackUuidV4WithMathRandom()
+}
+
+function fallbackUuidV4WithCrypto(crypto: Crypto): string {
+  const bytes = new Uint8Array(16)
+  crypto.getRandomValues(bytes)
+  bytes[6] = (bytes[6]! & 0x0f) | 0x40
+  bytes[8] = (bytes[8]! & 0x3f) | 0x80
+  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('')
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`
+}
+
+function fallbackUuidV4WithMathRandom(): string {
+  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+    const r = (Math.random() * 16) | 0
+    const v = c === 'x' ? r : (r & 0x3) | 0x8
+    return v.toString(16)
+  })
+}

package/src/shared/types/api.ts

@@ -133,6 +133,8 @@ interface MediaInfo {
 }
 
 // Iframe configuration types
+export type IframeLogLevel = 'none' | 'error' | 'warn' | 'info' | 'debug'
+
 export interface IframeConfigurationOptions {
   autoApprove: boolean
   featureFlags?: FeatureFlags
@@ -142,6 +144,9 @@ export interface IframeConfigurationOptions {
   mpcHost: string
   mpcVersion: string
 
+  /** When set to 'none', the iframe SDK will not log to the console. Passed from parent via portal:configure. */
+  logLevel?: IframeLogLevel
+
   // One of these three is required for authentication
   apiKey?: string
   authToken?: string

package/src/shared/types/common.ts

@@ -5,6 +5,10 @@
 // Basic types
 export interface FeatureFlags {
   isMultiBackupEnabled?: boolean
+  /** Enable presignature buffer for faster signing (SECP256K1 only). */
+  usePresignatures?: boolean
+  /** Per-curve max presignatures (e.g. { SECP256K1: 3 }). */
+  maxPresignaturesPerCurve?: Partial<Record<string, number>>
 }
 
 export interface Network {
@@ -36,6 +40,13 @@ export interface DkgData {
   signingSharePairId?: string
 }
 
+/** Presignature item stored per curve (SECP256K1 only in current implementation). */
+export interface Presignature {
+  id: string
+  expiresAt: string
+  data: string
+}
+
 // Transaction types
 export interface EIP1559Transaction {
   from: string
@@ -433,6 +444,8 @@ export interface SendAssetParams {
   token: string
   sponsorGas?: boolean
   signatureApprovalMemo?: string
+  /** Optional trace ID for correlating this operation with backend logs (X-Portal-Trace-Id). */
+  traceId?: string
 }
 
 export interface SendAssetResponse {
@@ -539,6 +552,7 @@ export interface SignArgs {
   sponsorGas?: boolean
   /** Optional memo displayed to the user during the signature approval flow. */
   signatureApprovalMemo?: string
+  traceId?: string
 }
 
 export interface SignResult {

package/src/shared/types/index.ts

@@ -1,7 +1,8 @@
 /**
  * Shared types barrel export
  *
- * This module exports all shared types used by both browser and iframe packages
+ * This module exports all shared types used by both browser and iframe packages.
+ * For trace ID helpers (X_PORTAL_TRACE_ID_HEADER, generateTraceId), use shared/trace.
  */
 
 // Common types

package/types.d.ts

@@ -303,6 +303,7 @@ export interface RequestArguments {
   params?: unknown[] | SigningRequestParams
   sponsorGas?: boolean
   signatureApprovalMemo?: string
+  traceId?: string
 }
 
 export interface RecoverArgs extends MpcOperationArgs {