@portal-hq/web 3.16.0 → 3.17.0

package/lib/commonjs/index.js

@@ -996,6 +996,300 @@ class Portal {
             return (_a = this.mpc) === null || _a === void 0 ? void 0 : _a.buildTransaction(chainId, to, token, amount, traceId);
         });
     }
+    /*******************************
+     * Account Abstraction Methods
+     *******************************/
+    buildBatchedUserOp(data) {
+        var _a;
+        return __awaiter(this, void 0, void 0, function* () {
+            return (_a = this.mpc) === null || _a === void 0 ? void 0 : _a.accountAbstractionBuildBatchedUserOp(data);
+        });
+    }
+    broadcastBatchedUserOp(data) {
+        var _a;
+        return __awaiter(this, void 0, void 0, function* () {
+            return (_a = this.mpc) === null || _a === void 0 ? void 0 : _a.accountAbstractionBroadcastBatchedUserOp(data);
+        });
+    }
+    /**
+     * Build, sign, and broadcast a batch of EIP-155 UserOperations (ERC-4337).
+     *
+     * Returns the broadcast response containing `userOpHash`. Broadcasting does not
+     * guarantee on-chain inclusion — UserOps are processed by a bundler that may
+     * delay or drop them. To wait for confirmation call:
+     *   `await portal.waitForConfirmation(result.data.userOpHash, data.chain)`
+     *
+     * @param data.chain                 - CAIP-2 chain ID; must start with 'eip155:'
+     * @param data.transactions          - Ordered list of transfers to batch
+     * @param data.signatureApprovalMemo - Optional memo for the signing approval prompt
+     * @param data.traceId               - Optional trace ID for request correlation
+     */
+    sendBatchUserOp(data) {
+        var _a, _b;
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!data.chain.startsWith('eip155:')) {
+                throw new Error('[Portal.sendBatchUserOp] UserOperations are only supported on EIP-155 (EVM) chains');
+            }
+            if (!data.transactions || data.transactions.length === 0) {
+                throw new Error('[Portal.sendBatchUserOp] transactions must contain at least one transaction');
+            }
+            // Validate every destination address before starting any async work.
+            for (const tx of data.transactions) {
+                if (!tx.to || !/^0x[0-9a-fA-F]{40}$/i.test(tx.to)) {
+                    throw new Error(`[Portal.sendBatchUserOp] Invalid 'to' address "${String(tx.to)}": must be a 42-character EVM address (0x + 40 hex chars)`);
+                }
+            }
+            const traceId = (_a = data.traceId) !== null && _a !== void 0 ? _a : (0, trace_1.generateTraceId)();
+            // Build each transaction sequentially. The iframe serializes all postMessages
+            // via _portalMessageQueue, so Promise.all would only create the illusion of
+            // parallelism while hiding failures from all-but-the-first transaction.
+            const calls = [];
+            for (let index = 0; index < data.transactions.length; index++) {
+                calls.push(yield this.buildUserOpCall(data.chain, data.transactions[index], traceId, index, 'Portal.sendBatchUserOp'));
+            }
+            // Build the batched UserOperation.
+            let buildResponse;
+            try {
+                buildResponse = yield ((_b = this.mpc) === null || _b === void 0 ? void 0 : _b.accountAbstractionBuildBatchedUserOp({ chain: data.chain, calls }, traceId));
+            }
+            catch (error) {
+                throw new Error(`[Portal.sendBatchUserOp] Failed to build UserOperation: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            // Validate, sign, and broadcast the built UserOperation, reusing the same
+            // traceId for end-to-end correlation.
+            return this.signAndBroadcastBuiltUserOp(buildResponse, data.chain, data.signatureApprovalMemo, traceId, 'Portal.sendBatchUserOp');
+        });
+    }
+    /**
+     * Build, sign, and broadcast a gas-subsidized batch where the end user
+     * reimburses the platform — in a fee token (e.g. USDC) — for the gas Portal's
+     * paymaster sponsored.
+     *
+     * The flow is two-pass because the reimbursement amount depends on the gas of
+     * the batch it's part of (a chicken-and-egg the helper resolves for you):
+     *   1. build `[...userCalls, feeCallPlaceholder]` to read the estimated gas cost
+     *      (`metadata.estimatedGasCostWei`; the placeholder ensures the estimate
+     *      reflects the FINAL batch shape)
+     *   2. convert that native gas cost → fee-token amount via your `convertGasToFeeAmount`
+     *   3. build `[...userCalls, feeCall]` with the real amount, sign, broadcast
+     *
+     * Important characteristics:
+     * - You are charging the build-time gas estimate (an upper bound), not the
+     *   post-execution actual — actual gas is unknowable before the op runs, and an
+     *   atomic batch must fix the reimbursement amount at sign time. Use `bufferBps`
+     *   to absorb gas-price drift between the two builds.
+     * - Conversion (native → fee token) is entirely yours; Portal does no FX.
+     * - Throws if the estimated gas cost is 0. Some chains/providers carry no
+     *   on-chain fee on the user operation (e.g. Ultra Relay bundler-level
+     *   sponsorship on Monad mainnet), so there's nothing to reimburse from; those
+     *   chains need a gas price sourced another way.
+     *
+     * @param data.chain           - CAIP-2 chain ID; must start with 'eip155:'
+     * @param data.transactions    - The end user's actual transfers to execute
+     * @param data.gasReimbursement - Fee token, recipient, and conversion callback
+     * @param data.signatureApprovalMemo - Optional memo for the signing approval prompt
+     * @param data.traceId         - Optional trace ID for request correlation
+     */
+    sendBatchedAssets(data) {
+        var _a, _b, _c, _d;
+        return __awaiter(this, void 0, void 0, function* () {
+            const ctx = 'Portal.sendBatchedAssets';
+            if (!data.chain.startsWith('eip155:')) {
+                throw new Error(`[${ctx}] UserOperations are only supported on EIP-155 (EVM) chains`);
+            }
+            if (!data.transactions || data.transactions.length === 0) {
+                throw new Error(`[${ctx}] transactions must contain at least one transaction`);
+            }
+            const gr = data.gasReimbursement;
+            if (!gr || typeof gr.convertGasToFeeAmount !== 'function') {
+                throw new Error(`[${ctx}] gasReimbursement.convertGasToFeeAmount (a function) is required`);
+            }
+            if (!gr.feeToken) {
+                throw new Error(`[${ctx}] gasReimbursement.feeToken is required`);
+            }
+            // Validate every destination address before starting any async work.
+            const evmAddress = /^0x[0-9a-fA-F]{40}$/i;
+            for (const tx of data.transactions) {
+                if (!tx.to || !evmAddress.test(tx.to)) {
+                    throw new Error(`[${ctx}] Invalid 'to' address "${String(tx.to)}": must be a 42-character EVM address (0x + 40 hex chars)`);
+                }
+            }
+            if (!gr.feeRecipient || !evmAddress.test(gr.feeRecipient)) {
+                throw new Error(`[${ctx}] Invalid gasReimbursement.feeRecipient "${String(gr.feeRecipient)}": must be a 42-character EVM address (0x + 40 hex chars)`);
+            }
+            const traceId = (_a = data.traceId) !== null && _a !== void 0 ? _a : (0, trace_1.generateTraceId)();
+            // 1. Build the user's actual calls once — they don't change between passes.
+            const userCalls = [];
+            for (let index = 0; index < data.transactions.length; index++) {
+                userCalls.push(yield this.buildUserOpCall(data.chain, data.transactions[index], traceId, index, ctx));
+            }
+            // 2. Build a placeholder fee call so the estimation pass reflects the final
+            //    batch shape (an N+1-call executeBatch). The amount does not affect the
+            //    gas estimate; only the call's presence and shape do.
+            const feeIndex = data.transactions.length;
+            const placeholderAmount = (_b = gr.placeholderAmount) !== null && _b !== void 0 ? _b : '0.01';
+            let placeholderFeeCall;
+            try {
+                placeholderFeeCall = yield this.buildUserOpCall(data.chain, { token: gr.feeToken, value: placeholderAmount, to: gr.feeRecipient }, traceId, feeIndex, ctx);
+            }
+            catch (error) {
+                throw new Error(`[${ctx}] Failed to build placeholder fee call: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            // 3. Estimation pass — build the full batch to read the gas it's bounded by.
+            let estimateResponse;
+            try {
+                estimateResponse = yield ((_c = this.mpc) === null || _c === void 0 ? void 0 : _c.accountAbstractionBuildBatchedUserOp({ chain: data.chain, calls: [...userCalls, placeholderFeeCall] }, traceId));
+            }
+            catch (error) {
+                throw new Error(`[${ctx}] Failed to estimate UserOperation gas: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            let gasCostWei = this.resolveUserOpGasCostWei(estimateResponse, ctx);
+            // Guard against a zero gas cost. Some chains/providers return no on-chain fee
+            // on the user operation (e.g. Ultra Relay bundler-level sponsorship on Monad
+            // mainnet), so the build-time cost is 0 — there's nothing to derive a
+            // reimbursement from. Fail loudly rather than silently charging the user 0.
+            if (gasCostWei === BigInt(0)) {
+                throw new Error(`[${ctx}] Estimated gas cost is 0 — this chain/provider carries no on-chain fee on the user operation (e.g. Ultra Relay bundler-level sponsorship). Cannot derive a reimbursement amount; supply the gas price another way for this chain.`);
+            }
+            // Apply optional buffer (basis points) to absorb gas-price drift before FX.
+            if (gr.bufferBps && gr.bufferBps > 0) {
+                gasCostWei =
+                    (gasCostWei * BigInt(10000 + Math.floor(gr.bufferBps))) / BigInt(10000);
+            }
+            // 4. Platform-owned conversion: native gas cost (wei) → fee-token amount.
+            let feeAmount;
+            try {
+                feeAmount = yield gr.convertGasToFeeAmount(gasCostWei);
+            }
+            catch (error) {
+                throw new Error(`[${ctx}] gasReimbursement.convertGasToFeeAmount threw: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            if (typeof feeAmount !== 'string' || feeAmount.length === 0) {
+                throw new Error(`[${ctx}] convertGasToFeeAmount must return a non-empty amount string, got "${String(feeAmount)}"`);
+            }
+            // 5. Build the real fee call with the converted amount.
+            let feeCall;
+            try {
+                feeCall = yield this.buildUserOpCall(data.chain, { token: gr.feeToken, value: feeAmount, to: gr.feeRecipient }, traceId, feeIndex, ctx);
+            }
+            catch (error) {
+                throw new Error(`[${ctx}] Failed to build fee reimbursement call: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            // 6. Final pass — build the batch we'll actually sign and broadcast.
+            let buildResponse;
+            try {
+                buildResponse = yield ((_d = this.mpc) === null || _d === void 0 ? void 0 : _d.accountAbstractionBuildBatchedUserOp({ chain: data.chain, calls: [...userCalls, feeCall] }, traceId));
+            }
+            catch (error) {
+                throw new Error(`[${ctx}] Failed to build UserOperation: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            return this.signAndBroadcastBuiltUserOp(buildResponse, data.chain, data.signatureApprovalMemo, traceId, ctx);
+        });
+    }
+    /**
+     * Build a single ERC-4337 call from a high-level transfer descriptor by routing
+     * it through `buildTransaction` (which resolves token contract + calldata and
+     * normalizes the amount). Native transfers carry `value` (the base-unit amount);
+     * ERC-20 transfers carry `data` and omit `value`.
+     */
+    buildUserOpCall(chain, tx, traceId, index, ctx) {
+        var _a;
+        return __awaiter(this, void 0, void 0, function* () {
+            let builtTx;
+            try {
+                builtTx = yield this.buildTransaction(chain, tx.to, tx.token, tx.value, traceId);
+            }
+            catch (error) {
+                throw new Error(`[${ctx}] Failed to build call for transaction at index ${index}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            // Validate the built transaction shape before casting. buildTransaction
+            // returns BuiltTransaction (a union type), so the cast is TypeScript-only and
+            // provides no runtime safety against a changed or unexpected backend response.
+            const rawTx = builtTx;
+            if (typeof ((_a = rawTx === null || rawTx === void 0 ? void 0 : rawTx.transaction) === null || _a === void 0 ? void 0 : _a.to) !== 'string' || !rawTx.transaction.to) {
+                throw new Error(`[${ctx}] buildTransaction returned unexpected shape for transaction at index ${index}`);
+            }
+            const eip155Tx = builtTx;
+            // Normalize the data field — guard against undefined/null/empty string from
+            // the backend. Empty data means no calldata (native transfer). rawAmount is
+            // passed as-is (decimal string e.g. '1000000000000000000'); the AA backend's
+            // build-user-operation endpoint accepts decimal or hex.
+            const txData = eip155Tx.transaction.data || '0x';
+            const isNativeTransfer = txData === '0x';
+            return Object.assign({ to: eip155Tx.transaction.to, data: txData }, (isNativeTransfer ? { value: eip155Tx.metadata.rawAmount } : {}));
+        });
+    }
+    /**
+     * Resolve the native gas cost (in wei) a built UserOperation is bounded by,
+     * from the backend-computed `metadata.estimatedGasCostWei` (`totalGas *
+     * maxFeePerGas`, an upper bound). Throws if the field is absent — the
+     * connect-api build-user-operation gas-cost change must be deployed.
+     */
+    resolveUserOpGasCostWei(buildResponse, ctx) {
+        var _a;
+        const wei = (_a = buildResponse === null || buildResponse === void 0 ? void 0 : buildResponse.metadata) === null || _a === void 0 ? void 0 : _a.estimatedGasCostWei;
+        if (wei == null || `${wei}`.length === 0) {
+            throw new Error(`[${ctx}] build response is missing metadata.estimatedGasCostWei; the connect-api build-user-operation gas-cost change must be deployed for the target environment`);
+        }
+        return this.toBigIntOrThrow(wei, 'metadata.estimatedGasCostWei', ctx);
+    }
+    toBigIntOrThrow(value, field, ctx) {
+        try {
+            // BigInt() accepts both decimal ('1000000000') and hex ('0x3b9aca00') strings.
+            return BigInt(value);
+        }
+        catch (_a) {
+            throw new Error(`[${ctx}] Could not parse ${field} as an integer: "${String(value)}"`);
+        }
+    }
+    /**
+     * Validate a built UserOperation, sign its hash with the SECP256K1 raw signer,
+     * and broadcast it. Shared by the batched-UserOp send paths.
+     */
+    signAndBroadcastBuiltUserOp(buildResponse, chain, signatureApprovalMemo, traceId, ctx) {
+        var _a;
+        return __awaiter(this, void 0, void 0, function* () {
+            const { userOperation, userOpHash } = buildResponse.data;
+            // Validate userOperation is parseable JSON before signing or broadcasting.
+            // A malformed string from the backend would produce an opaque bundler rejection.
+            try {
+                const parsed = JSON.parse(userOperation);
+                if (!parsed || typeof parsed !== 'object') {
+                    throw new Error('parsed value is not a JSON object');
+                }
+            }
+            catch (e) {
+                throw new Error(`[${ctx}] buildBatchedUserOp returned an invalid userOperation: ${e instanceof Error ? e.message : String(e)}`);
+            }
+            // Validate userOpHash is a valid 32-byte hex string before signing.
+            // Signing an empty or malformed hash wastes the signing operation and produces
+            // a signature that no bundler will accept.
+            if (!userOpHash || !/^(0x)?[0-9a-fA-F]{64}$/.test(userOpHash)) {
+                throw new Error(`[${ctx}] Invalid userOpHash received from buildBatchedUserOp: "${String(userOpHash)}"`);
+            }
+            // Sign the userOpHash — strip the 0x prefix before passing to rawSign.
+            let signature;
+            try {
+                const hashToSign = userOpHash.startsWith('0x')
+                    ? userOpHash.slice(2)
+                    : userOpHash;
+                signature = yield this.rawSign(PortalCurve.SECP256K1, hashToSign, {
+                    signatureApprovalMemo,
+                    traceId,
+                });
+            }
+            catch (error) {
+                throw new Error(`[${ctx}] Failed to sign userOpHash: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            // Broadcast the signed UserOperation, reusing the same traceId for end-to-end correlation.
+            try {
+                return yield ((_a = this.mpc) === null || _a === void 0 ? void 0 : _a.accountAbstractionBroadcastBatchedUserOp({ chain, userOperation, signature }, traceId));
+            }
+            catch (error) {
+                throw new Error(`[${ctx}] Failed to broadcast UserOperation: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        });
+    }
     /*******************************
      * Swaps Methods
      *******************************/

package/lib/commonjs/index.test.js

@@ -747,6 +747,237 @@ describe('Portal', () => {
             expect(portal.mpc.getSources).toHaveBeenCalledWith('eip155:1', 'test');
         }));
     });
+    describe('buildBatchedUserOp', () => {
+        it('should correctly call mpc.accountAbstractionBuildBatchedUserOp', () => __awaiter(void 0, void 0, void 0, function* () {
+            yield portal.buildBatchedUserOp(constants_1.mockBuildBatchedUserOpRequest);
+            expect(portal.mpc.accountAbstractionBuildBatchedUserOp).toHaveBeenCalledTimes(1);
+            expect(portal.mpc.accountAbstractionBuildBatchedUserOp).toHaveBeenCalledWith(constants_1.mockBuildBatchedUserOpRequest);
+        }));
+    });
+    describe('broadcastBatchedUserOp', () => {
+        it('should correctly call mpc.accountAbstractionBroadcastBatchedUserOp', () => __awaiter(void 0, void 0, void 0, function* () {
+            yield portal.broadcastBatchedUserOp(constants_1.mockBroadcastBatchedUserOpRequest);
+            expect(portal.mpc.accountAbstractionBroadcastBatchedUserOp).toHaveBeenCalledTimes(1);
+            expect(portal.mpc.accountAbstractionBroadcastBatchedUserOp).toHaveBeenCalledWith(constants_1.mockBroadcastBatchedUserOpRequest);
+        }));
+    });
+    describe('sendBatchUserOp', () => {
+        it('should build, sign, and broadcast a batched UserOperation', () => __awaiter(void 0, void 0, void 0, function* () {
+            const result = yield portal.sendBatchUserOp(constants_1.mockSendBatchUserOpRequest);
+            expect(result).toEqual(expect.objectContaining({
+                data: expect.objectContaining({ userOpHash: expect.any(String) }),
+                metadata: expect.objectContaining({ chainId: expect.any(String) }),
+            }));
+            // buildTransaction called once per transaction descriptor
+            expect(portal.mpc.buildTransaction).toHaveBeenCalledTimes(2);
+            expect(portal.mpc.buildTransaction).toHaveBeenCalledWith(constants_1.mockSendBatchUserOpRequest.chain, constants_1.mockSendBatchUserOpRequest.transactions[0].to, constants_1.mockSendBatchUserOpRequest.transactions[0].token, constants_1.mockSendBatchUserOpRequest.transactions[0].value, expect.any(String));
+            expect(portal.mpc.buildTransaction).toHaveBeenCalledWith(constants_1.mockSendBatchUserOpRequest.chain, constants_1.mockSendBatchUserOpRequest.transactions[1].to, constants_1.mockSendBatchUserOpRequest.transactions[1].token, constants_1.mockSendBatchUserOpRequest.transactions[1].value, expect.any(String));
+            // buildBatchedUserOp called with ERC-20 call shape (no value field) and the shared traceId
+            expect(portal.mpc.accountAbstractionBuildBatchedUserOp).toHaveBeenCalledTimes(1);
+            expect(portal.mpc.accountAbstractionBuildBatchedUserOp).toHaveBeenCalledWith({
+                chain: constants_1.mockSendBatchUserOpRequest.chain,
+                calls: [
+                    {
+                        to: constants_1.mockBuiltEip155Transaction.transaction.to,
+                        data: constants_1.mockBuiltEip155Transaction.transaction.data,
+                    },
+                    {
+                        to: constants_1.mockBuiltEip155Transaction.transaction.to,
+                        data: constants_1.mockBuiltEip155Transaction.transaction.data,
+                    },
+                ],
+            }, expect.any(String));
+            // rawSign called with SECP256K1 and the userOpHash with 0x prefix stripped
+            expect(portal.mpc.rawSign).toHaveBeenCalledTimes(1);
+            expect(portal.mpc.rawSign).toHaveBeenCalledWith(_1.PortalCurve.SECP256K1, constants_1.mockBuildBatchedUserOpResponse.data.userOpHash.slice(2), { signatureApprovalMemo: undefined, traceId: expect.any(String) });
+            // broadcastBatchedUserOp called with the built userOperation and signature, and the shared traceId
+            expect(portal.mpc.accountAbstractionBroadcastBatchedUserOp).toHaveBeenCalledTimes(1);
+            expect(portal.mpc.accountAbstractionBroadcastBatchedUserOp).toHaveBeenCalledWith({
+                chain: constants_1.mockSendBatchUserOpRequest.chain,
+                userOperation: constants_1.mockBuildBatchedUserOpResponse.data.userOperation,
+                signature: constants_1.mockSignedHash,
+            }, expect.any(String));
+        }));
+        it('should propagate the same traceId to buildBatchedUserOp and broadcastBatchedUserOp', () => __awaiter(void 0, void 0, void 0, function* () {
+            yield portal.sendBatchUserOp(constants_1.mockSendBatchUserOpRequest);
+            const buildTraceId = portal.mpc.accountAbstractionBuildBatchedUserOp.mock.calls[0][1];
+            const broadcastTraceId = portal.mpc.accountAbstractionBroadcastBatchedUserOp.mock.calls[0][1];
+            expect(typeof buildTraceId).toBe('string');
+            expect(buildTraceId).toEqual(broadcastTraceId);
+        }));
+        it('should include value in the call for native ETH transfers', () => __awaiter(void 0, void 0, void 0, function* () {
+            ;
+            portal.mpc.buildTransaction.mockResolvedValueOnce(constants_1.mockBuiltEip155TransactionNative);
+            yield portal.sendBatchUserOp({
+                chain: 'eip155:1',
+                transactions: [{ token: 'ETH', value: '0.1', to: '0x1111111111111111111111111111111111111111' }],
+            });
+            expect(portal.mpc.accountAbstractionBuildBatchedUserOp).toHaveBeenCalledWith({
+                chain: 'eip155:1',
+                calls: [
+                    {
+                        to: constants_1.mockBuiltEip155TransactionNative.transaction.to,
+                        data: '0x',
+                        value: constants_1.mockBuiltEip155TransactionNative.metadata.rawAmount,
+                    },
+                ],
+            }, expect.any(String));
+        }));
+        it('should not include value in the call for ERC-20 transfers', () => __awaiter(void 0, void 0, void 0, function* () {
+            yield portal.sendBatchUserOp({
+                chain: 'eip155:1',
+                transactions: [{ token: 'USDC', value: '1.0', to: '0x1111111111111111111111111111111111111111' }],
+            });
+            const calls = portal.mpc.accountAbstractionBuildBatchedUserOp.mock.calls[0][0].calls;
+            expect(calls[0]).not.toHaveProperty('value');
+        }));
+        it('should forward signatureApprovalMemo to rawSign', () => __awaiter(void 0, void 0, void 0, function* () {
+            yield portal.sendBatchUserOp(Object.assign(Object.assign({}, constants_1.mockSendBatchUserOpRequest), { signatureApprovalMemo: 'approve this batch' }));
+            expect(portal.mpc.rawSign).toHaveBeenCalledWith(_1.PortalCurve.SECP256K1, expect.any(String), { signatureApprovalMemo: 'approve this batch', traceId: expect.any(String) });
+        }));
+        it('should throw if chain is not eip155', () => __awaiter(void 0, void 0, void 0, function* () {
+            yield expect(portal.sendBatchUserOp(Object.assign(Object.assign({}, constants_1.mockSendBatchUserOpRequest), { chain: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp' }))).rejects.toThrow('[Portal.sendBatchUserOp] UserOperations are only supported on EIP-155 (EVM) chains');
+        }));
+        it('should throw if transactions array is empty', () => __awaiter(void 0, void 0, void 0, function* () {
+            yield expect(portal.sendBatchUserOp(Object.assign(Object.assign({}, constants_1.mockSendBatchUserOpRequest), { transactions: [] }))).rejects.toThrow('[Portal.sendBatchUserOp] transactions must contain at least one transaction');
+        }));
+        it('should throw with index context if buildTransaction fails for transaction 0', () => __awaiter(void 0, void 0, void 0, function* () {
+            ;
+            portal.mpc.buildTransaction.mockRejectedValueOnce(new Error('Network error'));
+            yield expect(portal.sendBatchUserOp({
+                chain: 'eip155:1',
+                transactions: [{ token: 'USDC', value: '1.0', to: '0x1111111111111111111111111111111111111111' }],
+            })).rejects.toThrow('[Portal.sendBatchUserOp] Failed to build call for transaction at index 0: Network error');
+        }));
+        it('should throw with index context if buildTransaction fails for transaction 1', () => __awaiter(void 0, void 0, void 0, function* () {
+            ;
+            portal.mpc.buildTransaction
+                .mockResolvedValueOnce(constants_1.mockBuiltEip155Transaction)
+                .mockRejectedValueOnce(new Error('Network error'));
+            yield expect(portal.sendBatchUserOp(constants_1.mockSendBatchUserOpRequest)).rejects.toThrow('[Portal.sendBatchUserOp] Failed to build call for transaction at index 1: Network error');
+        }));
+        it('should throw if buildBatchedUserOp fails', () => __awaiter(void 0, void 0, void 0, function* () {
+            ;
+            portal.mpc.accountAbstractionBuildBatchedUserOp.mockRejectedValueOnce(new Error('UserOp build failed'));
+            yield expect(portal.sendBatchUserOp(constants_1.mockSendBatchUserOpRequest)).rejects.toThrow('[Portal.sendBatchUserOp] Failed to build UserOperation: UserOp build failed');
+        }));
+        it('should throw if rawSign fails', () => __awaiter(void 0, void 0, void 0, function* () {
+            ;
+            portal.mpc.rawSign.mockRejectedValueOnce(new Error('Signing failed'));
+            yield expect(portal.sendBatchUserOp(constants_1.mockSendBatchUserOpRequest)).rejects.toThrow('[Portal.sendBatchUserOp] Failed to sign userOpHash: Signing failed');
+        }));
+        it('should throw if broadcastBatchedUserOp fails', () => __awaiter(void 0, void 0, void 0, function* () {
+            ;
+            portal.mpc.accountAbstractionBroadcastBatchedUserOp.mockRejectedValueOnce(new Error('Broadcast failed'));
+            yield expect(portal.sendBatchUserOp(constants_1.mockSendBatchUserOpRequest)).rejects.toThrow('[Portal.sendBatchUserOp] Failed to broadcast UserOperation: Broadcast failed');
+        }));
+    });
+    describe('sendBatchedAssets', () => {
+        const feeRecipient = '0x2222222222222222222222222222222222222222';
+        const baseRequest = {
+            chain: 'eip155:1',
+            transactions: [
+                {
+                    token: 'USDC',
+                    value: '1.0',
+                    to: '0x1111111111111111111111111111111111111111',
+                },
+            ],
+        };
+        it('should build twice, convert gas to a fee, sign, and broadcast', () => __awaiter(void 0, void 0, void 0, function* () {
+            const convertGasToFeeAmount = jest.fn().mockResolvedValue('0.5');
+            const result = yield portal.sendBatchedAssets(Object.assign(Object.assign({}, baseRequest), { gasReimbursement: { feeToken: 'USDC', feeRecipient, convertGasToFeeAmount } }));
+            expect(result).toEqual(constants_1.mockBroadcastBatchedUserOpResponse);
+            // Estimation pass + final pass = 2 builds.
+            expect(portal.mpc.accountAbstractionBuildBatchedUserOp).toHaveBeenCalledTimes(2);
+            // buildTransaction: 1 user tx + 1 placeholder fee + 1 real fee = 3.
+            expect(portal.mpc.buildTransaction).toHaveBeenCalledTimes(3);
+            // Conversion called once with gasCostWei = totalGas(100000) * maxFeePerGas(1e9).
+            expect(convertGasToFeeAmount).toHaveBeenCalledTimes(1);
+            expect(convertGasToFeeAmount).toHaveBeenCalledWith(BigInt('100000000000000'));
+            // Placeholder fee call built with the default '0.01'; real fee call with '0.5'.
+            expect(portal.mpc.buildTransaction).toHaveBeenCalledWith('eip155:1', feeRecipient, 'USDC', '0.01', expect.any(String));
+            expect(portal.mpc.buildTransaction).toHaveBeenCalledWith('eip155:1', feeRecipient, 'USDC', '0.5', expect.any(String));
+            expect(portal.mpc.rawSign).toHaveBeenCalledTimes(1);
+            expect(portal.mpc.accountAbstractionBroadcastBatchedUserOp).toHaveBeenCalledTimes(1);
+        }));
+        it('should apply bufferBps to the gas cost before conversion', () => __awaiter(void 0, void 0, void 0, function* () {
+            const convertGasToFeeAmount = jest.fn().mockResolvedValue('0.6');
+            yield portal.sendBatchedAssets(Object.assign(Object.assign({}, baseRequest), { gasReimbursement: {
+                    feeToken: 'USDC',
+                    feeRecipient,
+                    convertGasToFeeAmount,
+                    bufferBps: 1000, // +10%
+                } }));
+            // 1e14 * 11000 / 10000 = 1.1e14
+            expect(convertGasToFeeAmount).toHaveBeenCalledWith(BigInt('110000000000000'));
+        }));
+        it('should throw if the build response is missing estimatedGasCostWei', () => __awaiter(void 0, void 0, void 0, function* () {
+            const noGasCost = Object.assign(Object.assign({}, constants_1.mockBuildBatchedUserOpResponse), { metadata: { chainId: 'eip155:1' } });
+            portal.mpc.accountAbstractionBuildBatchedUserOp.mockResolvedValueOnce(noGasCost);
+            const convertGasToFeeAmount = jest.fn();
+            yield expect(portal.sendBatchedAssets(Object.assign(Object.assign({}, baseRequest), { gasReimbursement: { feeToken: 'USDC', feeRecipient, convertGasToFeeAmount } }))).rejects.toThrow('[Portal.sendBatchedAssets] build response is missing metadata.estimatedGasCostWei');
+            // Conversion should never run if we can't determine the gas cost.
+            expect(convertGasToFeeAmount).not.toHaveBeenCalled();
+        }));
+        it('should throw if the estimated gas cost is 0 (e.g. Ultra Relay zero-fee path)', () => __awaiter(void 0, void 0, void 0, function* () {
+            const zeroCost = Object.assign(Object.assign({}, constants_1.mockBuildBatchedUserOpResponse), { metadata: {
+                    chainId: 'eip155:1',
+                    totalGas: '2000000',
+                    maxFeePerGas: '0',
+                    estimatedGasCostWei: '0',
+                } });
+            portal.mpc.accountAbstractionBuildBatchedUserOp.mockResolvedValueOnce(zeroCost);
+            const convertGasToFeeAmount = jest.fn();
+            yield expect(portal.sendBatchedAssets(Object.assign(Object.assign({}, baseRequest), { gasReimbursement: { feeToken: 'USDC', feeRecipient, convertGasToFeeAmount } }))).rejects.toThrow('[Portal.sendBatchedAssets] Estimated gas cost is 0');
+            expect(convertGasToFeeAmount).not.toHaveBeenCalled();
+        }));
+        it('should reuse the same traceId across both builds', () => __awaiter(void 0, void 0, void 0, function* () {
+            const convertGasToFeeAmount = jest.fn().mockResolvedValue('0.5');
+            yield portal.sendBatchedAssets(Object.assign(Object.assign({}, baseRequest), { gasReimbursement: { feeToken: 'USDC', feeRecipient, convertGasToFeeAmount } }));
+            const calls = portal.mpc.accountAbstractionBuildBatchedUserOp.mock.calls;
+            expect(typeof calls[0][1]).toBe('string');
+            expect(calls[0][1]).toEqual(calls[1][1]);
+        }));
+        it('should throw if chain is not eip155', () => __awaiter(void 0, void 0, void 0, function* () {
+            yield expect(portal.sendBatchedAssets({
+                chain: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
+                transactions: baseRequest.transactions,
+                gasReimbursement: {
+                    feeToken: 'USDC',
+                    feeRecipient,
+                    convertGasToFeeAmount: () => '1',
+                },
+            })).rejects.toThrow('[Portal.sendBatchedAssets] UserOperations are only supported on EIP-155 (EVM) chains');
+        }));
+        it('should throw if transactions is empty', () => __awaiter(void 0, void 0, void 0, function* () {
+            yield expect(portal.sendBatchedAssets({
+                chain: 'eip155:1',
+                transactions: [],
+                gasReimbursement: {
+                    feeToken: 'USDC',
+                    feeRecipient,
+                    convertGasToFeeAmount: () => '1',
+                },
+            })).rejects.toThrow('[Portal.sendBatchedAssets] transactions must contain at least one transaction');
+        }));
+        it('should throw if convertGasToFeeAmount is missing', () => __awaiter(void 0, void 0, void 0, function* () {
+            yield expect(portal.sendBatchedAssets(Object.assign(Object.assign({}, baseRequest), { gasReimbursement: { feeToken: 'USDC', feeRecipient } }))).rejects.toThrow('[Portal.sendBatchedAssets] gasReimbursement.convertGasToFeeAmount (a function) is required');
+        }));
+        it('should throw if feeRecipient is not a valid EVM address', () => __awaiter(void 0, void 0, void 0, function* () {
+            yield expect(portal.sendBatchedAssets(Object.assign(Object.assign({}, baseRequest), { gasReimbursement: {
+                    feeToken: 'USDC',
+                    feeRecipient: '0xnope',
+                    convertGasToFeeAmount: () => '1',
+                } }))).rejects.toThrow('[Portal.sendBatchedAssets] Invalid gasReimbursement.feeRecipient');
+        }));
+        it('should surface an error thrown by the conversion callback', () => __awaiter(void 0, void 0, void 0, function* () {
+            const convertGasToFeeAmount = jest
+                .fn()
+                .mockRejectedValue(new Error('rate unavailable'));
+            yield expect(portal.sendBatchedAssets(Object.assign(Object.assign({}, baseRequest), { gasReimbursement: { feeToken: 'USDC', feeRecipient, convertGasToFeeAmount } }))).rejects.toThrow('[Portal.sendBatchedAssets] gasReimbursement.convertGasToFeeAmount threw: rate unavailable');
+        }));
+    });
     describe('storedClientBackupShare', () => {
         it('should correctly call mpc.storedClientBackupShare', () => __awaiter(void 0, void 0, void 0, function* () {
             yield portal.storedClientBackupShare(true, _1.BackupMethods.password);

package/lib/commonjs/mpc/index.js

@@ -14,7 +14,7 @@ const errors_1 = require("./errors");
 const logger_1 = require("../logger");
 const index_1 = require("../index");
 const trace_1 = require("../shared/trace");
-const WEB_SDK_VERSION = '3.16.0';
+const WEB_SDK_VERSION = '3.17.0';
 class Mpc {
     get ready() {
         return this._ready;
@@ -229,6 +229,7 @@ class Mpc {
                     param }, ((options === null || options === void 0 ? void 0 : options.signatureApprovalMemo) !== undefined && {
                     signatureApprovalMemo: options.signatureApprovalMemo,
                 })),
+                traceId: options === null || options === void 0 ? void 0 : options.traceId,
             });
         });
     }
@@ -916,6 +917,31 @@ class Mpc {
             });
         });
     }
+    /*******************************
+     * Account Abstraction Methods
+     *******************************/
+    accountAbstractionBuildBatchedUserOp(data, traceId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.handleRequestToIframeAndPost({
+                methodMessage: 'portal:accountAbstraction:buildBatchedUserOp',
+                errorMessage: 'portal:accountAbstraction:buildBatchedUserOpError',
+                resultMessage: 'portal:accountAbstraction:buildBatchedUserOpResult',
+                data,
+                traceId,
+            });
+        });
+    }
+    accountAbstractionBroadcastBatchedUserOp(data, traceId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.handleRequestToIframeAndPost({
+                methodMessage: 'portal:accountAbstraction:broadcastBatchedUserOp',
+                errorMessage: 'portal:accountAbstraction:broadcastBatchedUserOpError',
+                resultMessage: 'portal:accountAbstraction:broadcastBatchedUserOpResult',
+                data,
+                traceId,
+            });
+        });
+    }
     /***************************
      * Private Methods
      ***************************/