@portal-hq/web 3.11.0 → 3.12.0

package/lib/esm/namespaces/evmAccountType/index.test.js

@@ -31,7 +31,8 @@ describe('EvmAccountType', () => {
                 .mockImplementation((message, origin) => {
                 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(new MessageEvent('message', {
                     origin: mockHostOrigin,
@@ -59,7 +60,8 @@ describe('EvmAccountType', () => {
                 .mockImplementationOnce((message, origin) => {
                 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(new MessageEvent('message', {
                     origin: mockHostOrigin,
@@ -99,7 +101,8 @@ describe('EvmAccountType', () => {
                 .mockImplementation((message, origin) => {
                 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(new MessageEvent('message', {
                     origin: mockHostOrigin,
@@ -127,7 +130,8 @@ describe('EvmAccountType', () => {
                 .mockImplementationOnce((message, origin) => {
                 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(new MessageEvent('message', {
                     origin: mockHostOrigin,
@@ -149,6 +153,7 @@ describe('EvmAccountType', () => {
                 .catch((error) => {
                 expect(error).toBeInstanceOf(PortalMpcError);
                 expect(error.message).toEqual('test');
+                expect(error.code).toEqual(1);
                 done();
             });
         });
@@ -166,7 +171,8 @@ describe('EvmAccountType', () => {
                 .mockImplementation((message, origin) => {
                 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(new MessageEvent('message', {
                     origin: mockHostOrigin,
@@ -198,7 +204,8 @@ describe('EvmAccountType', () => {
                 .mockImplementation((message, origin) => {
                 const { type, data } = message;
                 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(new MessageEvent('message', {
                     origin: mockHostOrigin,
@@ -226,7 +233,8 @@ describe('EvmAccountType', () => {
                 .mockImplementationOnce((message, origin) => {
                 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(new MessageEvent('message', {
                     origin: mockHostOrigin,
@@ -266,7 +274,8 @@ describe('EvmAccountType', () => {
                 .mockImplementation((message, origin) => {
                 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(new MessageEvent('message', {
                     origin: mockHostOrigin,
@@ -299,7 +308,8 @@ describe('EvmAccountType', () => {
                 .mockImplementation((message, origin) => {
                 const { type, data } = message;
                 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(new MessageEvent('message', {
                     origin: mockHostOrigin,
@@ -327,7 +337,8 @@ describe('EvmAccountType', () => {
                 .mockImplementationOnce((message, origin) => {
                 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(new MessageEvent('message', {
                     origin: mockHostOrigin,
@@ -367,7 +378,8 @@ describe('EvmAccountType', () => {
                 .mockImplementation((message, _origin) => {
                 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,
                         data: {
@@ -377,7 +389,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,
                         data: {

package/lib/esm/provider/index.js

@@ -9,6 +9,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 import { ProviderRpcError, RpcErrorCodes } from './errors';
 import { sdkLogger } from '../logger';
+import { generateTraceId, X_PORTAL_TRACE_ID_HEADER } from '../shared/trace';
 export var RequestMethod;
 (function (RequestMethod) {
     RequestMethod["eth_accounts"] = "eth_accounts";
@@ -258,8 +259,10 @@ class Provider {
      * @param args The arguments of the request being made
      * @returns Promise<any>
      */
-    request({ chainId: requestChainId, method, params, sponsorGas, signatureApprovalMemo, }) {
+    request({ chainId: requestChainId, method, params, sponsorGas, signatureApprovalMemo, traceId: providedTraceId, }) {
         return __awaiter(this, void 0, void 0, function* () {
+            const traceId = providedTraceId !== null && providedTraceId !== void 0 ? providedTraceId : generateTraceId();
+            sdkLogger.info(`[PortalProvider] request started | method=${method} | traceId=${traceId}`);
             const isSignerMethod = signerMethods.includes(method);
             const chainId = this.getCAIP2ChainId(requestChainId);
             if (!isSignerMethod && !method.startsWith('wallet_')) {
@@ -268,6 +271,7 @@ class Provider {
                     chainId,
                     method,
                     params,
+                    traceId,
                 });
                 this.emit('portal_signatureReceived', {
                     chainId,
@@ -288,6 +292,7 @@ class Provider {
                     params,
                     sponsorGas,
                     signatureApprovalMemo,
+                    traceId,
                 });
                 if (transactionHash) {
                     this.emit('portal_signatureReceived', {
@@ -377,9 +382,8 @@ class Provider {
      * @param args The arguments of the request being made
      * @returns Promise<any>
      */
-    handleGatewayRequest({ chainId, method, params, }) {
+    handleGatewayRequest({ chainId, method, params, traceId, }) {
         return __awaiter(this, void 0, void 0, function* () {
-            // Prepare the request body
             const requestBody = {
                 body: JSON.stringify({
                     jsonrpc: '2.0',
@@ -388,11 +392,8 @@ class Provider {
                     params,
                 }),
                 method: 'POST',
-                headers: {
-                    'Content-Type': 'application/json',
-                },
+                headers: Object.assign({ 'Content-Type': 'application/json' }, (traceId && { [X_PORTAL_TRACE_ID_HEADER]: traceId })),
             };
-            // Pass request off to the gateway
             const result = yield fetch(this.portal.getRpcUrl(chainId), requestBody);
             return result.json();
         });
@@ -403,7 +404,7 @@ class Provider {
      * @param args The arguments of the request being made
      * @returns Promise<any>
      */
-    handleSigningRequest({ chainId, method, params, sponsorGas, signatureApprovalMemo, }) {
+    handleSigningRequest({ chainId, method, params, sponsorGas, signatureApprovalMemo, traceId, }) {
         return __awaiter(this, void 0, void 0, function* () {
             const isApproved = passiveSignerMethods.includes(method)
                 ? true
@@ -430,9 +431,9 @@ class Provider {
                 case RequestMethod.eth_signTypedData_v4:
                 case RequestMethod.personal_sign: {
                     this.enforceEip155ChainId(chainId);
-                    const result = yield this.portal.mpc.sign(Object.assign({ chainId: chainId, method, params: this.buildParams(method, params), rpcUrl: this.portal.getRpcUrl(chainId), sponsorGas }, (signatureApprovalMemo !== undefined && {
+                    const result = yield this.portal.mpc.sign(Object.assign(Object.assign({ chainId: chainId, method, params: this.buildParams(method, params), rpcUrl: this.portal.getRpcUrl(chainId), sponsorGas }, (signatureApprovalMemo !== undefined && {
                         signatureApprovalMemo,
-                    })));
+                    })), { traceId }));
                     return result;
                 }
                 case RequestMethod.sol_signAndConfirmTransaction:
@@ -440,14 +441,10 @@ class Provider {
                 case RequestMethod.sol_signMessage:
                 case RequestMethod.sol_signTransaction: {
                     this.enforceSolanaChainId(chainId);
-                    const result = yield this.portal.mpc.sign({
-                        chainId: chainId,
-                        method,
-                        params: this.buildParams(method, params),
-                        rpcUrl: this.portal.getRpcUrl(chainId),
-                        sponsorGas,
+                    const result = yield this.portal.mpc.sign(Object.assign({ chainId: chainId, method, params: this.buildParams(method, params), rpcUrl: this.portal.getRpcUrl(chainId), sponsorGas,
+                        traceId }, (signatureApprovalMemo !== undefined && {
                         signatureApprovalMemo,
-                    });
+                    })));
                     return result;
                 }
                 default:

package/lib/esm/provider/index.test.js

@@ -17,6 +17,8 @@ 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', () => (Object.assign(Object.assign({}, jest.requireActual('../shared/trace')), { generateTraceId: jest.fn(() => 'mock-trace-id-12345'), X_PORTAL_TRACE_ID_HEADER: 'X-Portal-Trace-Id' })));
 describe('Provider', () => {
     beforeEach(() => {
         portal.autoApprove = true;
@@ -152,6 +154,7 @@ describe('Provider', () => {
                         method: RequestMethod.eth_sendTransaction,
                         params: 'test',
                         rpcUrl: mockRpcUrl,
+                        traceId: 'mock-trace-id-12345',
                     });
                     expect(provider.emit).toHaveBeenCalledWith('portal_signatureReceived', {
                         chainId: 'eip155:1',
@@ -188,6 +191,7 @@ describe('Provider', () => {
                         method: RequestMethod.eth_signTransaction,
                         params: 'test',
                         rpcUrl: mockRpcUrl,
+                        traceId: 'mock-trace-id-12345',
                     });
                     expect(provider.emit).toHaveBeenCalledWith('portal_signatureReceived', {
                         chainId: 'eip155:1',
@@ -224,6 +228,7 @@ describe('Provider', () => {
                         method: RequestMethod.eth_sign,
                         params: ['test'],
                         rpcUrl: mockRpcUrl,
+                        traceId: 'mock-trace-id-12345',
                     });
                     expect(provider.emit).toHaveBeenCalledWith('portal_signatureReceived', {
                         chainId: 'eip155:1',
@@ -260,6 +265,7 @@ describe('Provider', () => {
                         method: RequestMethod.eth_signTypedData_v3,
                         params: ['test'],
                         rpcUrl: mockRpcUrl,
+                        traceId: 'mock-trace-id-12345',
                     });
                     expect(provider.emit).toHaveBeenCalledWith('portal_signatureReceived', {
                         chainId: 'eip155:1',
@@ -296,6 +302,7 @@ describe('Provider', () => {
                         method: RequestMethod.eth_signTypedData_v4,
                         params: ['test'],
                         rpcUrl: mockRpcUrl,
+                        traceId: 'mock-trace-id-12345',
                     });
                     expect(provider.emit).toHaveBeenCalledWith('portal_signatureReceived', {
                         chainId: 'eip155:1',
@@ -332,6 +339,7 @@ describe('Provider', () => {
                         method: RequestMethod.personal_sign,
                         params: ['test'],
                         rpcUrl: mockRpcUrl,
+                        traceId: 'mock-trace-id-12345',
                     });
                     expect(provider.emit).toHaveBeenCalledWith('portal_signatureReceived', {
                         chainId: 'eip155:1',
@@ -368,6 +376,7 @@ describe('Provider', () => {
                         method: RequestMethod.sol_signAndConfirmTransaction,
                         params: ['test'],
                         rpcUrl: mockRpcUrl,
+                        traceId: 'mock-trace-id-12345',
                     });
                     expect(provider.emit).toHaveBeenCalledWith('portal_signatureReceived', {
                         chainId: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
@@ -404,6 +413,7 @@ describe('Provider', () => {
                         method: RequestMethod.sol_signAndSendTransaction,
                         params: ['test'],
                         rpcUrl: mockRpcUrl,
+                        traceId: 'mock-trace-id-12345',
                     });
                     expect(provider.emit).toHaveBeenCalledWith('portal_signatureReceived', {
                         chainId: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
@@ -440,6 +450,7 @@ describe('Provider', () => {
                         method: RequestMethod.sol_signMessage,
                         params: ['test'],
                         rpcUrl: mockRpcUrl,
+                        traceId: 'mock-trace-id-12345',
                     });
                     expect(provider.emit).toHaveBeenCalledWith('portal_signatureReceived', {
                         chainId: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
@@ -476,6 +487,7 @@ describe('Provider', () => {
                         method: RequestMethod.sol_signTransaction,
                         params: ['test'],
                         rpcUrl: mockRpcUrl,
+                        traceId: 'mock-trace-id-12345',
                     });
                     expect(provider.emit).toHaveBeenCalledWith('portal_signatureReceived', {
                         chainId: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
@@ -576,6 +588,7 @@ describe('Provider', () => {
                         method: RequestMethod.eth_sendTransaction,
                         params: 'test',
                         rpcUrl: mockRpcUrl,
+                        traceId: 'mock-trace-id-12345',
                     });
                     expect(mockSignatureReceivedHandler).toHaveBeenCalledWith({
                         chainId: 'eip155:1',
@@ -627,6 +640,7 @@ describe('Provider', () => {
                         method: RequestMethod.eth_signTransaction,
                         params: 'test',
                         rpcUrl: mockRpcUrl,
+                        traceId: 'mock-trace-id-12345',
                     });
                     expect(mockSignatureReceivedHandler).toHaveBeenCalledWith({
                         chainId: 'eip155:1',
@@ -678,6 +692,7 @@ describe('Provider', () => {
                         method: RequestMethod.eth_sign,
                         params: ['test'],
                         rpcUrl: mockRpcUrl,
+                        traceId: 'mock-trace-id-12345',
                     });
                     expect(mockSignatureReceivedHandler).toHaveBeenCalledWith({
                         chainId: 'eip155:1',
@@ -729,6 +744,7 @@ describe('Provider', () => {
                         method: RequestMethod.eth_signTypedData_v3,
                         params: ['test'],
                         rpcUrl: mockRpcUrl,
+                        traceId: 'mock-trace-id-12345',
                     });
                     expect(mockSignatureReceivedHandler).toHaveBeenCalledWith({
                         chainId: 'eip155:1',
@@ -780,6 +796,7 @@ describe('Provider', () => {
                         method: RequestMethod.eth_signTypedData_v4,
                         params: ['test'],
                         rpcUrl: mockRpcUrl,
+                        traceId: 'mock-trace-id-12345',
                     });
                     expect(mockSignatureReceivedHandler).toHaveBeenCalledWith({
                         chainId: 'eip155:1',
@@ -831,6 +848,7 @@ describe('Provider', () => {
                         method: RequestMethod.personal_sign,
                         params: ['test'],
                         rpcUrl: mockRpcUrl,
+                        traceId: 'mock-trace-id-12345',
                     });
                     expect(mockSignatureReceivedHandler).toHaveBeenCalledWith({
                         chainId: 'eip155:1',
@@ -882,6 +900,7 @@ describe('Provider', () => {
                         method: RequestMethod.sol_signAndConfirmTransaction,
                         params: ['test'],
                         rpcUrl: mockRpcUrl,
+                        traceId: 'mock-trace-id-12345',
                     });
                     expect(mockSignatureReceivedHandler).toHaveBeenCalledWith({
                         chainId: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
@@ -933,6 +952,7 @@ describe('Provider', () => {
                         method: RequestMethod.sol_signAndSendTransaction,
                         params: ['test'],
                         rpcUrl: mockRpcUrl,
+                        traceId: 'mock-trace-id-12345',
                     });
                     expect(mockSignatureReceivedHandler).toHaveBeenCalledWith({
                         chainId: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
@@ -984,6 +1004,7 @@ describe('Provider', () => {
                         method: RequestMethod.sol_signMessage,
                         params: ['test'],
                         rpcUrl: mockRpcUrl,
+                        traceId: 'mock-trace-id-12345',
                     });
                     expect(mockSignatureReceivedHandler).toHaveBeenCalledWith({
                         chainId: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
@@ -1035,6 +1056,7 @@ describe('Provider', () => {
                         method: RequestMethod.sol_signTransaction,
                         params: ['test'],
                         rpcUrl: mockRpcUrl,
+                        traceId: 'mock-trace-id-12345',
                     });
                     expect(mockSignatureReceivedHandler).toHaveBeenCalledWith({
                         chainId: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
@@ -1078,9 +1100,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/lib/esm/shared/logger.js

@@ -0,0 +1,56 @@
+/**
+ * Configurable logger for the iframe SDK. Respects logLevel so that when the
+ * parent sets logLevel to 'none', no messages are written to the console.
+ */
+const LOG_LEVEL_PRIORITY = {
+    none: 0,
+    error: 1,
+    warn: 2,
+    info: 3,
+    debug: 4,
+};
+class SdkLoggerImpl {
+    constructor() {
+        this.logLevel = 'none';
+    }
+    configure(logLevel) {
+        this.logLevel = logLevel;
+    }
+    getLogLevel() {
+        return this.logLevel;
+    }
+    shouldLog(level) {
+        return LOG_LEVEL_PRIORITY[level] <= LOG_LEVEL_PRIORITY[this.logLevel];
+    }
+    log(level, message, ...args) {
+        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 (_a) {
+            // no-op if console is unavailable or throws
+        }
+    }
+    debug(message, ...args) {
+        this.log('debug', message, ...args);
+    }
+    warn(message, ...args) {
+        this.log('warn', message, ...args);
+    }
+    error(message, ...args) {
+        this.log('error', message, ...args);
+    }
+}
+export const sdkLogger = new SdkLoggerImpl();

package/lib/esm/shared/trace/index.js

@@ -0,0 +1,51 @@
+/**
+ * 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() {
+    if (typeof crypto !== 'undefined' &&
+        typeof crypto.randomUUID === 'function') {
+        return crypto.randomUUID();
+    }
+    if (typeof crypto !== 'undefined' &&
+        typeof crypto.getRandomValues === 'function') {
+        return fallbackUuidV4WithCrypto(crypto);
+    }
+    return fallbackUuidV4WithMathRandom();
+}
+function fallbackUuidV4WithCrypto(crypto) {
+    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() {
+    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/lib/esm/shared/types/index.js

@@ -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
 export * from './common';

package/package.json

@@ -3,7 +3,7 @@
   "description": "Portal MPC Support for Web",
   "author": "Portal Labs, Inc.",
   "homepage": "https://portalhq.io/",
-  "version": "3.11.0",
+  "version": "3.12.0",
   "license": "MIT",
   "main": "lib/commonjs/index",
   "module": "lib/esm/index",

package/src/index.test.ts

@@ -1033,6 +1033,7 @@ describe('Portal', () => {
         mockAddress,
         'USDC',
         '1',
+        undefined,
       )
     })
   })

package/src/index.ts

@@ -56,6 +56,7 @@ import Delegations from './integrations/delegations'
 import PasskeyService from './passkeys'
 import { EvmAccountType } from './namespaces/evmAccountType'
 import { sdkLogger } from './logger'
+import { generateTraceId } from './shared/trace'
 import type { LogLevel, ILogger } from '../types'
 
 class Portal {
@@ -627,22 +628,29 @@ class Portal {
     chain: string,
     params: SendAssetParams,
   ): Promise<string> {
+    const traceId = params.traceId ?? generateTraceId()
+    sdkLogger.debug(
+      '[Portal] sendAsset started (single traceId for build + sign)',
+      { traceId },
+    )
+
     try {
       // Convert the chain to a chain ID
       const chainId = this.convertChainToChainId(chain)
 
-      // Build the transaction
+      // Build the transaction (same traceId for correlation with backend)
       const buildTxResponse = await this.buildTransaction(
         chainId,
         params.to,
         params.token,
         params.amount,
+        traceId,
       )
 
       // Get the chain namespace
       const chainNamespace = chainId.split(':')[0] ?? ''
 
-      // Send the transaction based on chain namespace
+      // Send the transaction based on chain namespace (same traceId on request)
       let response
       switch (chainNamespace) {
         case 'eip155': {
@@ -652,6 +660,7 @@ class Portal {
             params: [buildTxResponse.transaction],
             sponsorGas: params.sponsorGas,
             signatureApprovalMemo: params.signatureApprovalMemo,
+            traceId,
           })
           break
         }
@@ -662,6 +671,7 @@ class Portal {
             params: [buildTxResponse.transaction],
             sponsorGas: params.sponsorGas,
             signatureApprovalMemo: params.signatureApprovalMemo,
+            traceId,
           })
           break
         }
@@ -1076,8 +1086,9 @@ class Portal {
     to: string,
     token: string,
     amount: string,
+    traceId?: string,
   ): Promise<BuiltTransaction> {
-    return this.mpc?.buildTransaction(chainId, to, token, amount)
+    return this.mpc?.buildTransaction(chainId, to, token, amount, traceId)
   }
 
   /*******************************

package/src/logger/index.ts

@@ -1,11 +1,4 @@
-export type LogLevel = 'none' | 'error' | 'warn' | 'info' | 'debug'
-
-export interface ILogger {
-  error(...args: unknown[]): void
-  warn(...args: unknown[]): void
-  info(...args: unknown[]): void
-  debug(...args: unknown[]): void
-}
+import type { LogLevel, ILogger } from '../../types'
 
 const LOG_LEVEL_PRIORITY: Record<LogLevel, number> = {
   none: 0,