@portal-hq/web 3.11.0 → 3.12.0

package/src/mpc/index.ts

@@ -1,4 +1,5 @@
 import { PortalMpcError } from './errors'
+import { sdkLogger } from '../logger'
 
 import Portal, {
   BackupMethods,
@@ -107,14 +108,16 @@ import {
   ScreenAddressApiResponse,
   ScreenAddressRequestOptions,
 } from '../../hypernative'
+import { generateTraceId } from '../shared/trace'
 
-const WEB_SDK_VERSION = '3.11.0'
+const WEB_SDK_VERSION = '3.12.0'
 
 class Mpc {
   public iframe?: HTMLIFrameElement
 
   private portal: Portal
   private _ready = false
+  private presignatureLogHandler: ((event: MessageEvent) => void) | null = null
 
   public get ready() {
     return this._ready
@@ -143,10 +146,16 @@ class Mpc {
     progress: ProgressCallback = () => {
       // Noop
     },
+    traceId?: string,
   ): Promise<BackupResponse> {
     // validates password config for password backup
     this.validateBackupConfig(data)
 
+    const resolvedTraceId = traceId ?? generateTraceId()
+    sdkLogger.info(
+      `[Portal MPC] backup started | backupMethod=${data.backupMethod} | traceId=${resolvedTraceId}`,
+    )
+
     return this.handleRequestToIframeAndPost({
       methodMessage: 'portal:wasm:backup',
       errorMessage: 'portal:wasm:backupError',
@@ -154,6 +163,7 @@ class Mpc {
       data,
       progressMessage: 'portal:wasm:backupProgress',
       progressCallback: progress,
+      traceId: resolvedTraceId,
       mapReturnValue: (result: Record<string, unknown>) => {
         const resultData = result as Record<string, unknown>
         const backupIds = Array.isArray(resultData.backupIds)
@@ -183,6 +193,9 @@ class Mpc {
       resultMessage: 'portal:destroyResult',
       data: {},
       mapReturnValue: () => true,
+    }).then((result) => {
+      this.teardownPresignatureLogForwarding()
+      return result
     })
   }
 
@@ -191,7 +204,11 @@ class Mpc {
     progress: ProgressCallback = () => {
       // Noop
     },
+    traceId?: string,
   ): Promise<string> {
+    const resolvedTraceId = traceId ?? generateTraceId()
+    sdkLogger.info(`[Portal MPC] generate started | traceId=${resolvedTraceId}`)
+
     return this.handleRequestToIframeAndPost({
       methodMessage: 'portal:wasm:generate',
       errorMessage: 'portal:wasm:generateError',
@@ -199,6 +216,7 @@ class Mpc {
       data,
       progressMessage: 'portal:wasm:generateProgress',
       progressCallback: progress,
+      traceId: resolvedTraceId,
     })
   }
 
@@ -216,7 +234,13 @@ class Mpc {
     progress: ProgressCallback = () => {
       // Noop
     },
+    traceId?: string,
   ): Promise<string> {
+    const resolvedTraceId = traceId ?? generateTraceId()
+    sdkLogger.info(
+      `[Portal MPC] recover started | backupMethod=${data.backupMethod} | traceId=${resolvedTraceId}`,
+    )
+
     return this.handleRequestToIframeAndPost({
       methodMessage: 'portal:wasm:recover',
       errorMessage: 'portal:wasm:recoverError',
@@ -224,26 +248,30 @@ class Mpc {
       data,
       progressMessage: 'portal:wasm:recoverProgress',
       progressCallback: progress,
+      traceId: resolvedTraceId,
     })
   }
 
-  public async eject(data: EjectArgs): Promise<EjectResult> {
+  public async eject(data: EjectArgs, traceId?: string): Promise<EjectResult> {
     return this.handleRequestToIframeAndPost({
       methodMessage: 'portal:wasm:eject',
       errorMessage: 'portal:wasm:ejectError',
       resultMessage: 'portal:wasm:ejectResult',
       data,
+      traceId,
     })
   }
 
   public async ejectPrivateKeys(
     data: EjectPrivateKeysArgs,
+    traceId?: string,
   ): Promise<EjectPrivateKeysResult> {
     return this.handleRequestToIframeAndPost({
       methodMessage: 'portal:wasm:ejectPrivateKeys',
       errorMessage: 'portal:wasm:ejectPrivateKeysError',
       resultMessage: 'portal:wasm:ejectPrivateKeysResult',
       data,
+      traceId,
     })
   }
 
@@ -272,13 +300,19 @@ class Mpc {
       // Noop
     },
   ): Promise<string> {
+    const resolvedTraceId = data.traceId ?? generateTraceId()
+    sdkLogger.info(
+      `[Portal MPC] sign started | method=${data.method} | traceId=${resolvedTraceId} | chainId=${data.chainId}`,
+    )
+
     return this.handleRequestToIframeAndPost({
       methodMessage: 'portal:wasm:sign',
       errorMessage: 'portal:wasm:signError',
       resultMessage: 'portal:wasm:signResult',
-      data,
+      data: { ...data, traceId: resolvedTraceId },
       progressMessage: 'portal:wasm:signProgress',
       progressCallback: progress,
+      traceId: resolvedTraceId,
     })
   }
 
@@ -360,12 +394,14 @@ class Mpc {
     to: string,
     token: string,
     amount: string,
+    traceId?: string,
   ): Promise<BuiltTransaction> {
     return this.handleRequestToIframeAndPost({
       methodMessage: 'portal:buildTransaction',
       errorMessage: 'portal:buildTransactionError',
       resultMessage: 'portal:buildTransactionResult',
       data: { chainId, to, token, amount },
+      traceId,
     })
   }
 
@@ -879,6 +915,7 @@ class Mpc {
     progressMessage,
     progressCallback,
     mapReturnValue,
+    traceId: providedTraceId,
   }: {
     methodMessage: string
     errorMessage: string
@@ -887,7 +924,16 @@ class Mpc {
     progressMessage?: string
     progressCallback?: (status: MpcStatus) => void
     mapReturnValue?: (result: any) => ResponseType
+    traceId?: string
   }): Promise<ResponseType> {
+    // Single traceId per operation: use provided or generate. Propagates to iframe and all internal REST/MPC calls.
+    const traceId = providedTraceId ?? generateTraceId()
+    sdkLogger.debug(
+      '[Portal] request traceId:',
+      traceId,
+      'method:',
+      methodMessage,
+    )
     return new Promise((resolve, reject) => {
       const handleRequest = (event: MessageEvent<WorkerResult>) => {
         const { type, data: result } = event.data
@@ -920,10 +966,11 @@ class Mpc {
       // Bind the function to the message event
       window.addEventListener('message', handleRequest)
 
-      // Send the request to the iframe
+      // Send the request to the iframe (traceId at top-level so data shape stays unchanged)
       this.postMessage({
         type: methodMessage,
         data,
+        traceId,
       })
     })
   }
@@ -960,6 +1007,7 @@ class Mpc {
       mpcHost: this.portal.mpcHost,
       mpcVersion: this.portal.mpcVersion,
       featureFlags: this.portal.featureFlags,
+      logLevel: this.portal.getLogLevel(),
     }
 
     const message = {
@@ -969,9 +1017,29 @@ class Mpc {
 
     this.postMessage(message)
 
+    this.setupPresignatureLogForwarding()
     this.waitForReadyMessage()
   }
 
+  private setupPresignatureLogForwarding() {
+    if (this.presignatureLogHandler) return
+    const handler = (event: MessageEvent) => {
+      if (event.origin !== this.getOrigin()) return
+      const { type, data } = event.data || {}
+      if (type === 'portal:presignature:log' && data?.message) {
+        sdkLogger.warn(data.message)
+      }
+    }
+    this.presignatureLogHandler = handler
+    window.addEventListener('message', handler)
+  }
+
+  private teardownPresignatureLogForwarding() {
+    if (!this.presignatureLogHandler) return
+    window.removeEventListener('message', this.presignatureLogHandler)
+    this.presignatureLogHandler = null
+  }
+
   private getOrigin(): string {
     const host = this.portal.host
     const origin = host.startsWith('localhost:')
@@ -1028,7 +1096,7 @@ class Mpc {
     })
   }
 
-  private postMessage(event: { type: string; data: any }) {
+  private postMessage(event: { type: string; data: any; traceId?: string }) {
     this.iframe?.contentWindow?.postMessage(event, this.getOrigin())
   }
 

package/src/namespaces/evmAccountType/index.test.ts

@@ -50,7 +50,8 @@ describe('EvmAccountType', () => {
                     const { type, data } = message
 
                     expect(type).toEqual('portal:evmAccountType:getStatus')
-                    expect(data).toEqual(args)
+                    expect(data).toMatchObject(args)
+                    expect(typeof message.traceId).toBe('string')
                     expect(origin).toEqual(mockHostOrigin)
 
                     window.dispatchEvent(
@@ -83,7 +84,8 @@ describe('EvmAccountType', () => {
                     const { type, data } = message
 
                     expect(type).toEqual('portal:evmAccountType:getStatus')
-                    expect(data).toEqual(args)
+                    expect(data).toMatchObject(args)
+                    expect(typeof message.traceId).toBe('string')
                     expect(origin).toEqual(mockHostOrigin)
 
                     window.dispatchEvent(
@@ -130,7 +132,8 @@ describe('EvmAccountType', () => {
                     const { type, data } = message
 
                     expect(type).toEqual('portal:evmAccountType:getAddresses')
-                    expect(data).toEqual(args)
+                    expect(data).toMatchObject(args)
+                    expect(typeof message.traceId).toBe('string')
                     expect(origin).toEqual(mockHostOrigin)
 
                     window.dispatchEvent(
@@ -163,7 +166,8 @@ describe('EvmAccountType', () => {
                     const { type, data } = message
 
                     expect(type).toEqual('portal:evmAccountType:getAddresses')
-                    expect(data).toEqual(args)
+                    expect(data).toMatchObject(args)
+                    expect(typeof message.traceId).toBe('string')
                     expect(origin).toEqual(mockHostOrigin)
 
                     window.dispatchEvent(
@@ -189,6 +193,7 @@ describe('EvmAccountType', () => {
                 .catch((error) => {
                     expect(error).toBeInstanceOf(PortalMpcError)
                     expect(error.message).toEqual('test')
+                    expect(error.code).toEqual(1)
                     done()
                 })
         })
@@ -209,7 +214,8 @@ describe('EvmAccountType', () => {
                     const { type, data } = message
 
                     expect(type).toEqual('portal:evmAccountType:buildAuthorizationList')
-                    expect(data).toEqual(args)
+                    expect(data).toMatchObject(args)
+                    expect(typeof message.traceId).toBe('string')
                     expect(origin).toEqual(mockHostOrigin)
 
                     window.dispatchEvent(
@@ -249,7 +255,8 @@ describe('EvmAccountType', () => {
                     expect(type).toEqual(
                         'portal:evmAccountType:buildAuthorizationList',
                     )
-                    expect(data).toEqual(argsWithoutSubsidize)
+                    expect(data).toMatchObject(argsWithoutSubsidize)
+                    expect(typeof message.traceId).toBe('string')
                     expect(origin).toEqual(mockHostOrigin)
 
                     window.dispatchEvent(
@@ -290,7 +297,8 @@ describe('EvmAccountType', () => {
                     expect(type).toEqual(
                         'portal:evmAccountType:buildAuthorizationList',
                     )
-                    expect(data).toEqual(args)
+                    expect(data).toMatchObject(args)
+                    expect(typeof message.traceId).toBe('string')
                     expect(origin).toEqual(mockHostOrigin)
 
                     window.dispatchEvent(
@@ -337,7 +345,8 @@ describe('EvmAccountType', () => {
                     const { type, data } = message
 
                     expect(type).toEqual('portal:evmAccountType:build7702UpgradeTx')
-                    expect(data).toEqual(args)
+                    expect(data).toMatchObject(args)
+                    expect(typeof message.traceId).toBe('string')
                     expect(origin).toEqual(mockHostOrigin)
 
                     window.dispatchEvent(
@@ -378,7 +387,8 @@ describe('EvmAccountType', () => {
                     expect(type).toEqual(
                         'portal:evmAccountType:build7702UpgradeTx',
                     )
-                    expect(data).toEqual(argsWithoutSubsidize)
+                    expect(data).toMatchObject(argsWithoutSubsidize)
+                    expect(typeof message.traceId).toBe('string')
                     expect(origin).toEqual(mockHostOrigin)
 
                     window.dispatchEvent(
@@ -419,7 +429,8 @@ describe('EvmAccountType', () => {
                     expect(type).toEqual(
                         'portal:evmAccountType:build7702UpgradeTx',
                     )
-                    expect(data).toEqual(args)
+                    expect(data).toMatchObject(args)
+                    expect(typeof message.traceId).toBe('string')
                     expect(origin).toEqual(mockHostOrigin)
 
                     window.dispatchEvent(
@@ -468,7 +479,8 @@ describe('EvmAccountType', () => {
                     const { type, data } = message
 
                     if (type === 'portal:evmAccountType:getStatus') {
-                        expect(data).toEqual({ chain: args.chain })
+                        expect(data).toMatchObject({ chain: args.chain })
+                        expect(typeof message.traceId).toBe('string')
                         window.dispatchEvent(
                             new MessageEvent('message', {
                                 origin: mockHostOrigin,
@@ -479,7 +491,8 @@ describe('EvmAccountType', () => {
                             }),
                         )
                     } else if (type === 'portal:evmAccountType:buildAuthorizationList') {
-                        expect(data).toEqual({ chain: args.chain, subsidize: true })
+                        expect(data).toMatchObject({ chain: args.chain, subsidize: true })
+                        expect(typeof message.traceId).toBe('string')
                         window.dispatchEvent(
                             new MessageEvent('message', {
                                 origin: mockHostOrigin,

package/src/provider/index.test.ts

@@ -9,6 +9,13 @@ import { ProviderRpcError, RpcErrorCodes } from './errors'
 import { RequestMethod } from '../'
 import mpcMock from '../__mocks/portal/mpc'
 import { sdkLogger } from '../logger'
+import { X_PORTAL_TRACE_ID_HEADER } from '../shared/trace'
+
+jest.mock('../shared/trace', () => ({
+  ...jest.requireActual('../shared/trace'),
+  generateTraceId: jest.fn(() => 'mock-trace-id-12345'),
+  X_PORTAL_TRACE_ID_HEADER: 'X-Portal-Trace-Id',
+}))
 
 describe('Provider', () => {
   beforeEach(() => {
@@ -221,6 +228,7 @@ describe('Provider', () => {
             method: RequestMethod.eth_sendTransaction,
             params: 'test',
             rpcUrl: mockRpcUrl,
+            traceId: 'mock-trace-id-12345',
           })
           expect(provider.emit).toHaveBeenCalledWith(
             'portal_signatureReceived',
@@ -276,6 +284,7 @@ describe('Provider', () => {
             method: RequestMethod.eth_signTransaction,
             params: 'test',
             rpcUrl: mockRpcUrl,
+            traceId: 'mock-trace-id-12345',
           })
           expect(provider.emit).toHaveBeenCalledWith(
             'portal_signatureReceived',
@@ -331,6 +340,7 @@ describe('Provider', () => {
             method: RequestMethod.eth_sign,
             params: ['test'],
             rpcUrl: mockRpcUrl,
+            traceId: 'mock-trace-id-12345',
           })
           expect(provider.emit).toHaveBeenCalledWith(
             'portal_signatureReceived',
@@ -386,6 +396,7 @@ describe('Provider', () => {
             method: RequestMethod.eth_signTypedData_v3,
             params: ['test'],
             rpcUrl: mockRpcUrl,
+            traceId: 'mock-trace-id-12345',
           })
           expect(provider.emit).toHaveBeenCalledWith(
             'portal_signatureReceived',
@@ -441,6 +452,7 @@ describe('Provider', () => {
             method: RequestMethod.eth_signTypedData_v4,
             params: ['test'],
             rpcUrl: mockRpcUrl,
+            traceId: 'mock-trace-id-12345',
           })
           expect(provider.emit).toHaveBeenCalledWith(
             'portal_signatureReceived',
@@ -496,6 +508,7 @@ describe('Provider', () => {
             method: RequestMethod.personal_sign,
             params: ['test'],
             rpcUrl: mockRpcUrl,
+            traceId: 'mock-trace-id-12345',
           })
           expect(provider.emit).toHaveBeenCalledWith(
             'portal_signatureReceived',
@@ -551,6 +564,7 @@ describe('Provider', () => {
             method: RequestMethod.sol_signAndConfirmTransaction,
             params: ['test'],
             rpcUrl: mockRpcUrl,
+            traceId: 'mock-trace-id-12345',
           })
           expect(provider.emit).toHaveBeenCalledWith(
             'portal_signatureReceived',
@@ -606,6 +620,7 @@ describe('Provider', () => {
             method: RequestMethod.sol_signAndSendTransaction,
             params: ['test'],
             rpcUrl: mockRpcUrl,
+            traceId: 'mock-trace-id-12345',
           })
           expect(provider.emit).toHaveBeenCalledWith(
             'portal_signatureReceived',
@@ -661,6 +676,7 @@ describe('Provider', () => {
             method: RequestMethod.sol_signMessage,
             params: ['test'],
             rpcUrl: mockRpcUrl,
+            traceId: 'mock-trace-id-12345',
           })
           expect(provider.emit).toHaveBeenCalledWith(
             'portal_signatureReceived',
@@ -716,6 +732,7 @@ describe('Provider', () => {
             method: RequestMethod.sol_signTransaction,
             params: ['test'],
             rpcUrl: mockRpcUrl,
+            traceId: 'mock-trace-id-12345',
           })
           expect(provider.emit).toHaveBeenCalledWith(
             'portal_signatureReceived',
@@ -830,6 +847,7 @@ describe('Provider', () => {
             method: RequestMethod.eth_sendTransaction,
             params: 'test',
             rpcUrl: mockRpcUrl,
+            traceId: 'mock-trace-id-12345',
           })
           expect(mockSignatureReceivedHandler).toHaveBeenCalledWith({
             chainId: 'eip155:1',
@@ -887,6 +905,7 @@ describe('Provider', () => {
             method: RequestMethod.eth_signTransaction,
             params: 'test',
             rpcUrl: mockRpcUrl,
+            traceId: 'mock-trace-id-12345',
           })
           expect(mockSignatureReceivedHandler).toHaveBeenCalledWith({
             chainId: 'eip155:1',
@@ -944,6 +963,7 @@ describe('Provider', () => {
             method: RequestMethod.eth_sign,
             params: ['test'],
             rpcUrl: mockRpcUrl,
+            traceId: 'mock-trace-id-12345',
           })
           expect(mockSignatureReceivedHandler).toHaveBeenCalledWith({
             chainId: 'eip155:1',
@@ -1001,6 +1021,7 @@ describe('Provider', () => {
             method: RequestMethod.eth_signTypedData_v3,
             params: ['test'],
             rpcUrl: mockRpcUrl,
+            traceId: 'mock-trace-id-12345',
           })
           expect(mockSignatureReceivedHandler).toHaveBeenCalledWith({
             chainId: 'eip155:1',
@@ -1058,6 +1079,7 @@ describe('Provider', () => {
             method: RequestMethod.eth_signTypedData_v4,
             params: ['test'],
             rpcUrl: mockRpcUrl,
+            traceId: 'mock-trace-id-12345',
           })
           expect(mockSignatureReceivedHandler).toHaveBeenCalledWith({
             chainId: 'eip155:1',
@@ -1115,6 +1137,7 @@ describe('Provider', () => {
             method: RequestMethod.personal_sign,
             params: ['test'],
             rpcUrl: mockRpcUrl,
+            traceId: 'mock-trace-id-12345',
           })
           expect(mockSignatureReceivedHandler).toHaveBeenCalledWith({
             chainId: 'eip155:1',
@@ -1172,6 +1195,7 @@ describe('Provider', () => {
             method: RequestMethod.sol_signAndConfirmTransaction,
             params: ['test'],
             rpcUrl: mockRpcUrl,
+            traceId: 'mock-trace-id-12345',
           })
           expect(mockSignatureReceivedHandler).toHaveBeenCalledWith({
             chainId: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
@@ -1229,6 +1253,7 @@ describe('Provider', () => {
             method: RequestMethod.sol_signAndSendTransaction,
             params: ['test'],
             rpcUrl: mockRpcUrl,
+            traceId: 'mock-trace-id-12345',
           })
           expect(mockSignatureReceivedHandler).toHaveBeenCalledWith({
             chainId: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
@@ -1286,6 +1311,7 @@ describe('Provider', () => {
             method: RequestMethod.sol_signMessage,
             params: ['test'],
             rpcUrl: mockRpcUrl,
+            traceId: 'mock-trace-id-12345',
           })
           expect(mockSignatureReceivedHandler).toHaveBeenCalledWith({
             chainId: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
@@ -1343,6 +1369,7 @@ describe('Provider', () => {
             method: RequestMethod.sol_signTransaction,
             params: ['test'],
             rpcUrl: mockRpcUrl,
+            traceId: 'mock-trace-id-12345',
           })
           expect(mockSignatureReceivedHandler).toHaveBeenCalledWith({
             chainId: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
@@ -1393,9 +1420,10 @@ describe('Provider', () => {
         expect(result).toEqual('test')
         expect(global.fetch).toHaveBeenCalledWith(mockRpcUrl, {
           method: 'POST',
-          headers: {
+          headers: expect.objectContaining({
             'Content-Type': 'application/json',
-          },
+            [X_PORTAL_TRACE_ID_HEADER]: 'mock-trace-id-12345',
+          }),
           body: JSON.stringify({
             jsonrpc: '2.0',
             id: '0',

package/src/provider/index.ts

@@ -2,6 +2,7 @@ import { ProviderRpcError, RpcErrorCodes } from './errors'
 
 import Portal from '../index'
 import { sdkLogger } from '../logger'
+import { generateTraceId, X_PORTAL_TRACE_ID_HEADER } from '../shared/trace'
 
 import type {
   EventHandler,
@@ -251,7 +252,13 @@ class Provider {
     params,
     sponsorGas,
     signatureApprovalMemo,
+    traceId: providedTraceId,
   }: RequestArguments): Promise<any> {
+    const traceId = providedTraceId ?? generateTraceId()
+    sdkLogger.info(
+      `[PortalProvider] request started | method=${method} | traceId=${traceId}`,
+    )
+
     const isSignerMethod = signerMethods.includes(method)
     const chainId = this.getCAIP2ChainId(requestChainId)
 
@@ -261,6 +268,7 @@ class Provider {
         chainId,
         method,
         params,
+        traceId,
       })
 
       this.emit('portal_signatureReceived', {
@@ -283,6 +291,7 @@ class Provider {
         params,
         sponsorGas,
         signatureApprovalMemo,
+        traceId,
       })
 
       if (transactionHash) {
@@ -408,8 +417,8 @@ class Provider {
     chainId,
     method,
     params,
+    traceId,
   }: RequestArguments): Promise<any> {
-    // Prepare the request body
     const requestBody = {
       body: JSON.stringify({
         jsonrpc: '2.0',
@@ -420,10 +429,10 @@ class Provider {
       method: 'POST',
       headers: {
         'Content-Type': 'application/json',
+        ...(traceId && { [X_PORTAL_TRACE_ID_HEADER]: traceId }),
       },
     }
 
-    // Pass request off to the gateway
     const result = await fetch(this.portal.getRpcUrl(chainId), requestBody)
 
     return result.json()
@@ -441,6 +450,7 @@ class Provider {
     params,
     sponsorGas,
     signatureApprovalMemo,
+    traceId,
   }: RequestArguments): Promise<any> {
     const isApproved = passiveSignerMethods.includes(method)
       ? true
@@ -480,6 +490,7 @@ class Provider {
           ...(signatureApprovalMemo !== undefined && {
             signatureApprovalMemo,
           }),
+          traceId,
         })
         return result
       }
@@ -494,7 +505,10 @@ class Provider {
           params: this.buildParams(method, params),
           rpcUrl: this.portal.getRpcUrl(chainId),
           sponsorGas,
-          signatureApprovalMemo,
+          traceId,
+          ...(signatureApprovalMemo !== undefined && {
+            signatureApprovalMemo,
+          }),
         })
         return result
       }

package/src/shared/logger.ts

@@ -0,0 +1,69 @@
+/**
+ * Configurable logger for the iframe SDK. Respects logLevel so that when the
+ * parent sets logLevel to 'none', no messages are written to the console.
+ */
+
+export type LogLevel = 'none' | 'error' | 'warn' | 'info' | 'debug'
+
+const LOG_LEVEL_PRIORITY: Record<LogLevel, number> = {
+  none: 0,
+  error: 1,
+  warn: 2,
+  info: 3,
+  debug: 4,
+}
+
+interface SdkLoggerInterface {
+  debug(message: string, ...args: unknown[]): void
+  warn(message: string, ...args: unknown[]): void
+  error(message: string, ...args: unknown[]): void
+  configure(logLevel: LogLevel): void
+  getLogLevel(): LogLevel
+}
+
+class SdkLoggerImpl implements SdkLoggerInterface {
+  private logLevel: LogLevel = 'none'
+
+  configure(logLevel: LogLevel): void {
+    this.logLevel = logLevel
+  }
+
+  getLogLevel(): LogLevel {
+    return this.logLevel
+  }
+
+  private shouldLog(level: Exclude<LogLevel, 'none'>): boolean {
+    return LOG_LEVEL_PRIORITY[level] <= LOG_LEVEL_PRIORITY[this.logLevel]
+  }
+
+  private log(level: 'debug' | 'warn' | 'error', message: string, ...args: unknown[]): void {
+    if (!this.shouldLog(level)) return
+    if (typeof console === 'undefined') return
+    const prefix = `[PortalMpc] ${message}`
+    try {
+      if (level === 'debug' && console.debug) {
+        console.debug(prefix, ...args)
+      } else if (level === 'warn' && console.warn) {
+        console.warn(prefix, ...args)
+      } else if (level === 'error' && console.error) {
+        console.error(prefix, ...args)
+      }
+    } catch {
+      // no-op if console is unavailable or throws
+    }
+  }
+
+  debug(message: string, ...args: unknown[]): void {
+    this.log('debug', message, ...args)
+  }
+
+  warn(message: string, ...args: unknown[]): void {
+    this.log('warn', message, ...args)
+  }
+
+  error(message: string, ...args: unknown[]): void {
+    this.log('error', message, ...args)
+  }
+}
+
+export const sdkLogger = new SdkLoggerImpl()