JSPM

  • Created
  • Published
  • Downloads 28
  • Score
    100M100P100Q68098F
  • License MIT

A fork of Ethers.js with added support for Otterscan/Erigon OTS namespace methods for blockchain explorer functionality.

Package Exports

  • @cowrieio/ethers-otterscan
  • @cowrieio/ethers-otterscan/abi
  • @cowrieio/ethers-otterscan/address
  • @cowrieio/ethers-otterscan/constants
  • @cowrieio/ethers-otterscan/contract
  • @cowrieio/ethers-otterscan/crypto
  • @cowrieio/ethers-otterscan/hash
  • @cowrieio/ethers-otterscan/providers
  • @cowrieio/ethers-otterscan/transaction
  • @cowrieio/ethers-otterscan/utils
  • @cowrieio/ethers-otterscan/wallet
  • @cowrieio/ethers-otterscan/wordlists

Readme

Ethers.js + Otterscan

npm (tag) npm bundle size (version) npm (downloads)


A fork of Ethers.js with added support for Otterscan / Erigon's OTS namespace.

This package extends the popular Ethers.js library with specialized provider methods for interacting with Erigon nodes that expose the ots_* JSON-RPC methods. These methods provide efficient access to blockchain explorer data without requiring external indexers.

🆕 Otterscan Features

The OtterscanProvider class extends JsonRpcProvider with the following additional methods:

  • Transaction Analysis

    • traceTransaction() - Get detailed execution traces
    • getInternalOperations() - Get internal operations (transfers, creates, etc.)
    • getTransactionErrorData() - Get raw revert data for failed transactions
    • getTransactionRevertReason() - Get human-readable revert reasons
  • Block Information

    • getBlockDetails() - Get block data with issuance and fee information
    • getBlockTransactions() - Get paginated block transactions with receipts
  • Address History

    • searchTransactionsBefore() - Search transactions before a block
    • searchTransactionsAfter() - Search transactions after a block
    • iterateAddressHistory() - Async iterator for transaction history
  • Utilities

    • hasCode() - Efficiently check if address is a contract
    • getTransactionBySenderAndNonce() - Find transaction by sender/nonce
    • getContractCreator() - Get contract creation details
    • otsApiLevel() - Check supported OTS API level

Installation

npm install @cowrieio/ethers-otterscan

Usage

import { OtterscanProvider } from '@cowrieio/ethers-otterscan';

// Connect to an Erigon node with OTS namespace enabled
const provider = new OtterscanProvider('https://your-erigon-node.com');

// Check OTS availability
await provider.ensureOts(8); // Requires API level 8+

// Get transaction trace
const traces = await provider.traceTransaction('0x...');
console.log(traces); // Array of trace entries

// Search address history between blocks
for await (const { tx, receipt } of provider.iterateAddressHistory(
  '0x...', 
  19000000,  // start block
  19010000   // end block
)) {
  console.log(`Transaction: ${tx.hash}`);
}

// Get internal operations
const ops = await provider.getInternalOperations('0x...');
console.log(ops); // Array of internal operations

TypeScript Support

Full TypeScript support with proper types for all OTS methods:

import { OtterscanProvider, type OtsTraceEntry } from '@cowrieio/ethers-otterscan';

const provider = new OtterscanProvider('https://your-erigon-node.com');
const traces: OtsTraceEntry[] = await provider.traceTransaction('0x...');

Compatibility

  • Ethers.js: Based on Ethers.js v6.15.0
  • Erigon: Compatible with Erigon nodes running OTS namespace
  • Networks: Works with any EVM-compatible network running Erigon

Requirements

Your Erigon node must be configured with the OTS namespace enabled:

# Start Erigon with OTS namespace
erigon --http.api "eth,erigon,trace,ots" --http --http.addr "0.0.0.0"

Upstream Compatibility

This fork maintains full compatibility with the upstream Ethers.js library. All existing Ethers.js functionality works exactly as documented in the official Ethers.js documentation.

Differences from Upstream

  • Added: OtterscanProvider class with OTS namespace support
  • Added: TypeScript interfaces for all OTS response types
  • Added: Comprehensive test coverage for OTS methods
  • No breaking changes to existing Ethers.js functionality

Testing Nodes

OTS methods are supported on any Erigon node with OTS namespace enabled in launch arguments.

Documentation

Contributing

This is a community-maintained fork. Contributions are welcome!

  1. Fork the repository
  2. Make your changes
  3. Add tests for new functionality
  4. Submit a pull request

Relationship to Upstream

This package is a fork of ethers-io/ethers.js with additional functionality. It is not officially endorsed by the Ethers.js maintainers.

  • Upstream: ethers - The official Ethers.js library
  • This fork: @cowrieio/ethers-otterscan - Community fork with Otterscan support

License

MIT License (including all dependencies), same as upstream Ethers.js.

Credits

  • Ethers.js by Richard Moore - The amazing library this fork is based on
  • Otterscan - The blockchain explorer that defines the OTS namespace
  • Erigon - The Ethereum client that implements OTS methods