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
waitForCompletionhelper 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