@portal-hq/web 3.16.0 → 3.17.0-alpha.0

package/src/index.ts

@@ -8,6 +8,7 @@ import {
 import {
   GetAssetsResponse,
   BuiltTransaction,
+  BuiltEip155Transaction,
   BuiltTronTransaction,
   EvaluateTransactionOperationType,
   EvaluateTransactionParam,
@@ -35,6 +36,14 @@ import {
   type SimulatedTransaction,
   type Transaction,
   type TypedData,
+  type BuildBatchedUserOpRequest,
+  type BuildBatchedUserOpResponse,
+  type BroadcastBatchedUserOpRequest,
+  type BroadcastBatchedUserOpResponse,
+  type UserOperationCall,
+  type SendBatchUserOpRequest,
+  type SendBatchUserOpTransaction,
+  type SendBatchedAssetsRequest,
 } from './shared/types'
 
 import {
@@ -1285,6 +1294,442 @@ class Portal {
     return this.mpc?.buildTransaction(chainId, to, token, amount, traceId)
   }
 
+  /*******************************
+   * Account Abstraction Methods
+   *******************************/
+
+  public async buildBatchedUserOp(
+    data: BuildBatchedUserOpRequest,
+  ): Promise<BuildBatchedUserOpResponse> {
+    return this.mpc?.accountAbstractionBuildBatchedUserOp(data)
+  }
+
+  public async broadcastBatchedUserOp(
+    data: BroadcastBatchedUserOpRequest,
+  ): Promise<BroadcastBatchedUserOpResponse> {
+    return this.mpc?.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
+   */
+  public async sendBatchUserOp(
+    data: SendBatchUserOpRequest,
+  ): Promise<BroadcastBatchedUserOpResponse> {
+    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 = data.traceId ?? 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: UserOperationCall[] = []
+    for (let index = 0; index < data.transactions.length; index++) {
+      calls.push(
+        await this.buildUserOpCall(
+          data.chain,
+          data.transactions[index],
+          traceId,
+          index,
+          'Portal.sendBatchUserOp',
+        ),
+      )
+    }
+
+    // Build the batched UserOperation.
+    let buildResponse: BuildBatchedUserOpResponse
+    try {
+      buildResponse = await this.mpc?.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
+   */
+  public async sendBatchedAssets(
+    data: SendBatchedAssetsRequest,
+  ): Promise<BroadcastBatchedUserOpResponse> {
+    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 = data.traceId ?? generateTraceId()
+
+    // 1. Build the user's actual calls once — they don't change between passes.
+    const userCalls: UserOperationCall[] = []
+    for (let index = 0; index < data.transactions.length; index++) {
+      userCalls.push(
+        await 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 = gr.placeholderAmount ?? '0.01'
+    let placeholderFeeCall: UserOperationCall
+    try {
+      placeholderFeeCall = await 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: BuildBatchedUserOpResponse
+    try {
+      estimateResponse = await this.mpc?.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: string
+    try {
+      feeAmount = await 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: UserOperationCall
+    try {
+      feeCall = await 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: BuildBatchedUserOpResponse
+    try {
+      buildResponse = await this.mpc?.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`.
+   */
+  private async buildUserOpCall(
+    chain: string,
+    tx: SendBatchUserOpTransaction,
+    traceId: string,
+    index: number,
+    ctx: string,
+  ): Promise<UserOperationCall> {
+    let builtTx: BuiltTransaction
+    try {
+      builtTx = await 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 as {
+      transaction?: Record<string, unknown>
+      metadata?: Record<string, unknown>
+    }
+    if (typeof rawTx?.transaction?.to !== 'string' || !rawTx.transaction.to) {
+      throw new Error(
+        `[${ctx}] buildTransaction returned unexpected shape for transaction at index ${index}`,
+      )
+    }
+    const eip155Tx = builtTx as BuiltEip155Transaction
+
+    // 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 {
+      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.
+   */
+  private resolveUserOpGasCostWei(
+    buildResponse: BuildBatchedUserOpResponse,
+    ctx: string,
+  ): bigint {
+    const wei = buildResponse?.metadata?.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)
+  }
+
+  private toBigIntOrThrow(value: unknown, field: string, ctx: string): bigint {
+    try {
+      // BigInt() accepts both decimal ('1000000000') and hex ('0x3b9aca00') strings.
+      return BigInt(value as string | number)
+    } catch {
+      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.
+   */
+  private async signAndBroadcastBuiltUserOp(
+    buildResponse: BuildBatchedUserOpResponse,
+    chain: string,
+    signatureApprovalMemo: string | undefined,
+    traceId: string,
+    ctx: string,
+  ): Promise<BroadcastBatchedUserOpResponse> {
+    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: unknown = 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: string
+    try {
+      const hashToSign = userOpHash.startsWith('0x')
+        ? userOpHash.slice(2)
+        : userOpHash
+      signature = await 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 await this.mpc?.accountAbstractionBroadcastBatchedUserOp(
+        { chain, userOperation, signature },
+        traceId,
+      )
+    } catch (error) {
+      throw new Error(
+        `[${ctx}] Failed to broadcast UserOperation: ${error instanceof Error ? error.message : String(error)}`,
+      )
+    }
+  }
+
   /*******************************
    * Swaps Methods
    *******************************/
@@ -1551,6 +1996,15 @@ export {
   type TransactionHistoryItem,
   type SolanaTransactionDetails,
   type Transaction,
+  type UserOperationCall,
+  type BuildBatchedUserOpRequest,
+  type BuildBatchedUserOpResponse,
+  type BroadcastBatchedUserOpRequest,
+  type BroadcastBatchedUserOpResponse,
+  type SendBatchUserOpTransaction,
+  type SendBatchUserOpRequest,
+  type GasReimbursement,
+  type SendBatchedAssetsRequest,
 } from './shared/types'
 
 export type {

package/src/mpc/index.test.ts

@@ -80,6 +80,10 @@ import {
   mockBlockaidScanTokensResponse,
   mockBlockaidScanUrlRequest,
   mockBlockaidScanUrlResponse,
+  mockBuildBatchedUserOpRequest,
+  mockBuildBatchedUserOpResponse,
+  mockBroadcastBatchedUserOpRequest,
+  mockBroadcastBatchedUserOpResponse,
 } from '../__mocks/constants'
 import portalMock from '../__mocks/portal/portal'
 import { PortalMpcError } from './errors'
@@ -4447,4 +4451,164 @@ describe('Mpc', () => {
         })
     })
   })
+
+  describe('accountAbstractionBuildBatchedUserOp', () => {
+    const args = mockBuildBatchedUserOpRequest
+    const res = mockBuildBatchedUserOpResponse
+
+    it('should successfully build a user operation', (done) => {
+      jest
+        .spyOn(mpc.iframe?.contentWindow!, 'postMessage')
+        .mockImplementation((message: any, 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) => {
+      jest
+        .spyOn(mpc.iframe?.contentWindow!, 'postMessage')
+        .mockImplementationOnce((message: any, 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(PortalMpcError)
+          expect(e.message).toEqual('test')
+          expect(e.code).toEqual(1)
+          done()
+        })
+    })
+  })
+
+  describe('accountAbstractionBroadcastBatchedUserOp', () => {
+    const args = mockBroadcastBatchedUserOpRequest
+    const res = mockBroadcastBatchedUserOpResponse
+
+    it('should successfully broadcast a user operation', (done) => {
+      jest
+        .spyOn(mpc.iframe?.contentWindow!, 'postMessage')
+        .mockImplementation((message: any, 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) => {
+      jest
+        .spyOn(mpc.iframe?.contentWindow!, 'postMessage')
+        .mockImplementationOnce((message: any, 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(PortalMpcError)
+          expect(e.message).toEqual('test')
+          expect(e.code).toEqual(1)
+          done()
+        })
+    })
+  })
 })