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
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 tracesgetInternalOperations()
- Get internal operations (transfers, creates, etc.)getTransactionErrorData()
- Get raw revert data for failed transactionsgetTransactionRevertReason()
- Get human-readable revert reasons
Block Information
getBlockDetails()
- Get block data with issuance and fee informationgetBlockTransactions()
- Get paginated block transactions with receipts
Address History
searchTransactionsBefore()
- Search transactions before a blocksearchTransactionsAfter()
- Search transactions after a blockiterateAddressHistory()
- Async iterator for transaction history
Utilities
hasCode()
- Efficiently check if address is a contractgetTransactionBySenderAndNonce()
- Find transaction by sender/noncegetContractCreator()
- Get contract creation detailsotsApiLevel()
- 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
- Ethers.js Documentation - All standard Ethers.js functionality
- Otterscan Documentation - Details about OTS methods
- Erigon Documentation - Node configuration
Contributing
This is a community-maintained fork. Contributions are welcome!
- Fork the repository
- Make your changes
- Add tests for new functionality
- 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.