@cowrieio/ethers-ots

Ethers.js extension provider for Erigon's ots_ JSON-RPC namespace.

Extends JsonRpcProvider with methods optimized for blockchain explorer use cases — transaction traces, internal operations, paginated address history, and more — without requiring external indexers.

Install

npm install @cowrieio/ethers-ots ethers

ethers v6 is a peer dependency.

Usage

import { OtsProvider } from '@cowrieio/ethers-ots';

const provider = new OtsProvider('https://your-erigon-node.com');

// Check OTS availability
await provider.ensureOts();

// Transaction traces
const traces = await provider.traceTransaction('0x...');

// Internal operations (transfers, creates, selfdestructs)
const ops = await provider.getInternalOperations('0x...');

// Revert reasons
const reason = await provider.getTransactionRevertReason('0x...');

// Paginated address history
for await (const { tx, receipt } of provider.iterateAddressHistory(
  '0xaddress',
  19000000,  // start block
  19010000,  // end block
)) {
  console.log(tx.hash, receipt.timestamp);
}

API

Transaction Analysis

| Method | Description | |--------|-------------| | traceTransaction(txHash) | Execution trace (call tree) | | getInternalOperations(txHash) | Internal transfers, creates, selfdestructs | | getTransactionErrorData(txHash) | Raw revert data | | getTransactionRevertReason(txHash, customAbi?) | Decoded revert reason |

Block Data

| Method | Description | |--------|-------------| | getBlockDetails(blockNumber) | Block with issuance and fee info | | getBlockDetailsByHash(blockHash) | Same, by hash | | getBlockTransactions(blockNumber, page, pageSize) | Paginated block transactions with receipts |

Address History

| Method | Description | |--------|-------------| | searchTransactionsBefore(address, blockNumber, pageSize) | Paginated history (backward) | | searchTransactionsAfter(address, blockNumber, pageSize) | Paginated history (forward) | | iterateAddressHistory(address, startBlock, endBlock) | Async iterator over full history |

Utilities

| Method | Description | |--------|-------------| | hasCode(address, blockTag?) | Check if address is a contract | | getTransactionBySenderAndNonce(sender, nonce) | Find tx by sender + nonce | | getContractCreator(address) | Get contract deploy tx and creator | | otsApiLevel() | Check supported OTS API level | | ensureOts(minLevel?) | Assert OTS is available |

Types

All response types are owned by this package with native JS types (no hex strings):

• OtsTransaction — normalized transaction
• OtsReceipt — normalized receipt with timestamp
• OtsInternalOp — internal operation
• OtsTraceEntry — execution trace entry
• OtsBlockDetails — block with issuance/fees
• OtsSearchTransactionsPage — paginated search results
• OtsContractCreator — contract deploy info

Requirements

Your Erigon node must have the OTS namespace enabled:

erigon --http.api "eth,erigon,trace,ots"

License

MIT