@elacity-js/contracts-ua-executor

Transaction executor that bundles contract calls into Particle Network Universal Account meta-transactions. This allows cross-chain transaction execution through a single smart-account flow.

Overview

Instead of committing each contract call individually, this executor collects one or more ICommitableContractTransaction objects, builds a Universal Account transaction bundle, signs it, and broadcasts it via the Particle UA SDK. A built-in receipt fetcher polls the UA API until the transaction reaches a terminal state, then resolves on-chain receipts.

Quick Start

import { EthersAdapter } from '@elacity-js/contracts-ethers-adapter';
import { UniversalAccountTransactionExecutor } from '@elacity-js/contracts-ua-executor';
import { StandardChannel } from '@elacity-js/contracts';
import { UniversalAccount } from '@particle-network/universal-account-sdk';

// 1. Set up the runner (must implement IContractRunner & IProvider)
const runner = new EthersAdapter(signer);

// 2. Configure the UA executor
const ua = new UniversalAccount(/* ... */);
const executor = new UniversalAccountTransactionExecutor(runner, {
  ua,
  chainId: 8453, // Base
  signMessage: (msg) => signer.signMessage(msg),
});

// 3. Bundle and execute transactions
const channel = new StandardChannel(channelAddress, runner);
const result = await executor.execute([
  channel.mint(uri, opType, opRawData, sellRawData),
  channel.setApprovalForAll(operator, true),
]);

// 4. Wait for on-chain receipts
const receipts = await result.wait();
// receipts: IContractTransactionReceipt[]

How wait() Works

When you call result.wait():

1. The UAReceiptFetcher polls ua.getTransaction(transactionId) until the status reaches a terminal state (Finished or Refund finished)
2. It extracts the relevant user operations matching your contract addresses
3. For each operation with a txHash, it fetches the on-chain transaction via provider.getTransaction() and calls .wait() for the receipt
4. Returns an array of IContractTransactionReceipt objects

Exports

• UniversalAccountTransactionExecutor: Implements ITransactionExecutor for bundled UA meta-transactions
• UAExecutorConfig: Configuration type for the executor
• TransactionDetails and related types: Full Particle UA transaction response typings

Configuration

| Field | Type | Description | | --- | --- | --- | | ua | UniversalAccount | Particle Universal Account instance | | chainId | number | Target chain ID (e.g. 8453 for Base) | | signMessage | (message: string) => Promise<string> | Signs the UA rootHash with the EOA | | expectTokens | Array<{ type, amount }> | Optional tokens the smart account should have available |

Building

Run nx build contracts-ua-executor to build the library.

Running unit tests

Run nx test contracts-ua-executor to execute the unit tests via Jest.