@portal-hq/web 3.16.0 → 3.17.0

package/lib/commonjs/mpc/index.test.js

@@ -3764,4 +3764,138 @@ describe('Mpc', () => {
             });
         });
     });
+    describe('accountAbstractionBuildBatchedUserOp', () => {
+        const args = constants_1.mockBuildBatchedUserOpRequest;
+        const res = constants_1.mockBuildBatchedUserOpResponse;
+        it('should successfully build a user operation', (done) => {
+            var _a;
+            jest
+                .spyOn((_a = mpc.iframe) === null || _a === void 0 ? void 0 : _a.contentWindow, 'postMessage')
+                .mockImplementation((message, origin) => {
+                const { type, data } = message;
+                expect(type).toEqual('portal:accountAbstraction:buildBatchedUserOp');
+                expect(data).toMatchObject(args);
+                expect(typeof message.traceId).toBe('string');
+                expect(origin).toEqual(mockHostOrigin);
+                window.dispatchEvent(new MessageEvent('message', {
+                    origin: mockHostOrigin,
+                    data: {
+                        type: 'portal:accountAbstraction:buildBatchedUserOpResult',
+                        data: res,
+                    },
+                }));
+            });
+            mpc
+                .accountAbstractionBuildBatchedUserOp(args)
+                .then((data) => {
+                expect(data).toEqual(res);
+                done();
+            })
+                .catch((_) => {
+                expect(0).toEqual(1);
+                done();
+            });
+        });
+        it('should error out if the iframe sends an error message', (done) => {
+            var _a;
+            jest
+                .spyOn((_a = mpc.iframe) === null || _a === void 0 ? void 0 : _a.contentWindow, 'postMessage')
+                .mockImplementationOnce((message, origin) => {
+                const { type, data } = message;
+                expect(type).toEqual('portal:accountAbstraction:buildBatchedUserOp');
+                expect(data).toMatchObject(args);
+                expect(typeof message.traceId).toBe('string');
+                expect(origin).toEqual(mockHostOrigin);
+                window.dispatchEvent(new MessageEvent('message', {
+                    origin: mockHostOrigin,
+                    data: {
+                        type: 'portal:accountAbstraction:buildBatchedUserOpError',
+                        data: {
+                            code: 1,
+                            message: 'test',
+                        },
+                    },
+                }));
+            });
+            mpc
+                .accountAbstractionBuildBatchedUserOp(args)
+                .then(() => {
+                expect(0).toEqual(1);
+                done();
+            })
+                .catch((e) => {
+                expect(e).toBeInstanceOf(errors_1.PortalMpcError);
+                expect(e.message).toEqual('test');
+                expect(e.code).toEqual(1);
+                done();
+            });
+        });
+    });
+    describe('accountAbstractionBroadcastBatchedUserOp', () => {
+        const args = constants_1.mockBroadcastBatchedUserOpRequest;
+        const res = constants_1.mockBroadcastBatchedUserOpResponse;
+        it('should successfully broadcast a user operation', (done) => {
+            var _a;
+            jest
+                .spyOn((_a = mpc.iframe) === null || _a === void 0 ? void 0 : _a.contentWindow, 'postMessage')
+                .mockImplementation((message, origin) => {
+                const { type, data } = message;
+                expect(type).toEqual('portal:accountAbstraction:broadcastBatchedUserOp');
+                expect(data).toMatchObject(args);
+                expect(typeof message.traceId).toBe('string');
+                expect(origin).toEqual(mockHostOrigin);
+                window.dispatchEvent(new MessageEvent('message', {
+                    origin: mockHostOrigin,
+                    data: {
+                        type: 'portal:accountAbstraction:broadcastBatchedUserOpResult',
+                        data: res,
+                    },
+                }));
+            });
+            mpc
+                .accountAbstractionBroadcastBatchedUserOp(args)
+                .then((data) => {
+                expect(data).toEqual(res);
+                done();
+            })
+                .catch((_) => {
+                expect(0).toEqual(1);
+                done();
+            });
+        });
+        it('should error out if the iframe sends an error message', (done) => {
+            var _a;
+            jest
+                .spyOn((_a = mpc.iframe) === null || _a === void 0 ? void 0 : _a.contentWindow, 'postMessage')
+                .mockImplementationOnce((message, origin) => {
+                const { type, data } = message;
+                expect(type).toEqual('portal:accountAbstraction:broadcastBatchedUserOp');
+                expect(data).toMatchObject(args);
+                expect(typeof message.traceId).toBe('string');
+                expect(origin).toEqual(mockHostOrigin);
+                window.dispatchEvent(new MessageEvent('message', {
+                    origin: mockHostOrigin,
+                    data: {
+                        type: 'portal:accountAbstraction:broadcastBatchedUserOpError',
+                        data: {
+                            code: 1,
+                            message: 'test',
+                        },
+                    },
+                }));
+            });
+            mpc
+                .accountAbstractionBroadcastBatchedUserOp(args)
+                .then(() => {
+                expect(0).toEqual(1);
+                done();
+            })
+                .catch((e) => {
+                expect(e).toBeInstanceOf(errors_1.PortalMpcError);
+                expect(e.message).toEqual('test');
+                expect(e.code).toEqual(1);
+                done();
+            });
+        });
+    });
 });

package/lib/commonjs/shared/types/accountAbstraction.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/commonjs/shared/types/index.js

@@ -32,3 +32,5 @@ __exportStar(require("./lifi"), exports);
 __exportStar(require("./noah"), exports);
 __exportStar(require("./hypernative"), exports);
 __exportStar(require("./blockaid"), exports);
+// Account Abstraction types
+__exportStar(require("./accountAbstraction"), exports);

package/lib/esm/index.js

@@ -967,6 +967,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 : 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 : 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
      *******************************/