Eve library

Transaction Manager Service

Other

Revision 1

On this page

The transaction manager coordinates queued blockchain submissions with retry and confirmation handling. It is designed to sit between upstream product flows and low-level RPC providers, ensuring that intermittent failures, nonce management, and confirmation polling are centrally managed.

Features#

  • In-memory FIFO queue with single-flight processing
  • Exponential backoff retry scheduling plus attempt tracking
  • Confirmation polling via pluggable provider interface
  • EventEmitter hooks for observability (transactionQueued, transactionSubmitted, transactionRetryScheduled, transactionConfirmed, transactionFailed)
  • Metrics snapshot (getMetrics) for queue depth and success ratios
  • Promise-based waitForCompletion helper suitable for API responders

Provider Interface#

ts
type TransactionProvider = {
  sendTransaction(request: TransactionRequest): Promise<{ hash: string }>;
  waitForConfirmation(hash: string): Promise<TransactionReceipt>;
};

Implementations can wrap ethers.js, viem, or custom RPC clients. The manager remains agnostic to the underlying network.

Usage#

ts
import { TransactionManager } from './transaction-manager';

const provider = {
  sendTransaction: async (request) => rpcClient.sendTransaction(request),
  waitForConfirmation: async (hash) => rpcClient.waitForReceipt(hash),
};

const manager = new TransactionManager({
  provider,
  baseRetryDelayMs: 500,
  maxRetries: 5,
});

const { transactionId } = await manager.queueTransaction({
  chainId: 137,
  from: ACCOUNT_ADDRESS,
  to: CONTRACT_ADDRESS,
  data: encodedCalldata,
});

const result = await manager.waitForCompletion(transactionId);
if (result.status === 'confirmed') {
  console.log('🎉 confirmed at', result.receipt?.blockNumber);
} else {
  console.error('❌ failed:', result.error);
}

Tests#

bash
npx jest --config apps/lilith/svc-transaction-manager/jest.config.cjs --runInBand