@nexeth/heimdall

@nexeth/heimdall is a powerful tool designed to abstract the complexity of listening to blockchain events on Ethereum, built on top of viem. It allows for easy monitoring of blocks, transactions, transaction hashes, and transaction receipts, providing a simplified interface for interaction with the Ethereum blockchain.

Features

• Listen for new blocks on the Ethereum blockchain.
• Monitor transactions within new blocks.
• Get transaction hashes and receipts for further processing.
• Built on top of, and easy integration with viem

Installation

To use @nexeth/heimdall in your project, you need to install it using npm or yarn. It is also recommended to install viem as a dependency.

npm install viem @nexeth/heimdall

or

yarn add viem @nexeth/heimdall

Quick Start

1. Import @nexeth/heimdall into your project:

import { createHeimdall } from "@nexeth/heimdall";

2. Configure Heimdall with your Ethereum chain details. This configuration takes a viem chain object

import { mainnet } from "viem/chains";

const heimdall = createHeimdall({
  chain: mainnet,
});

3. Start listening to blockchain events

// Listen to new blocks
heimdall.onBlock((block) => {
  console.log("New block:", block);
});

// Listen to transactions within new blocks
heimdall.onTransaction((transaction) => {
  console.log("New transaction:", transaction);
});

API Reference

This section details the functionalities available through @nexeth/heimdall, providing descriptions for constructors, methods, and their parameters.

Constructor

createHeimdall(config: HeimdallConfig): Heimdall

Creates a new instance of Heimdall with the specified configuration.

• Parameters:
  • config: HeimdallConfig - Configuration object for Heimdall.
    • chain: Object specifying the blockchain to listen to. It should include properties like name (blockchain name) and rpcUrl (the URL to the blockchain's RPC endpoint). Chain options can be imported from viem

Example

A new instance can be instantiated using either function or class syntax

import { mainnet } from "viem/chains";

const heimdall = new Heimdall({ chain: mainnet });
// or
const heimdall = createHeimdall({ chain: mainnet });

Methods

onBlock(callback: BlockActionCallback): string

Registers a callback to be executed on every new block.

• Parameters:
  • callback: BlockActionCallback - A function that takes a Block object as its parameter and returns void. This callback is called with the block information whenever a new block is mined.
• Returns: A unique identifier (uuid) for the registered action, which can be used to remove the action later.

Example

heimdall.onBlock((block) => {
  console.log("New block:", block);
});

onTransaction(callback: TransactionActionCallback): string

Registers a callback to be executed for every transaction in new blocks.

• Parameters:
  • callback: TransactionActionCallback - A function that takes a transaction object as its parameter. This callback is called for each transaction found in a new block.
• Returns: A unique identifier (uuid) for the registered action.

heimdall.onTransaction((transaction) => {
  console.log("New transaction:", transaction);
});

onTransactionHash(callback: TransactionHashActionCallback): string

Registers a callback to be executed, providing the hash for every transaction in new blocks.

• Parameters:
  • callback: TransactionHashActionCallback - A function that receives a transaction hash as its parameter. This callback is called with the transaction hash for each transaction in a new block.
• Returns: A unique identifier (uuid) for the registered action.

heimdall.onTransactionHash((hash) => {
  console.log("New transaction hash:", hash);
});

onTransactionReceipt(callback: TransactionReceiptActionCallback): string

Registers a callback to be executed for every transaction receipt in new blocks.

• Parameters:
  • callback: TransactionReceiptActionCallback - A function that takes a transaction receipt object as its parameter. This callback is called for each transaction receipt found for transactions in a new block.
• Returns: A unique identifier (uuid) for the registered action.

heimdall.onTransactionReceipt((receipt) => {
  console.log("New transaction receipt:", receipt);
});

removeAction(uuid: string): void

Removes a previously registered action.

• Parameters:
  • uuid: string - The unique identifier of the action to remove.

const heimdall = new Heimdall({ chain: mainnet });

const uuid = heimdall.onBlock(() => {});

heimdall.removeAction(uuid);

Contributing

We welcome contributions from the community! If you'd like to contribute to @nexeth/heimdall, please fork the repository and submit a pull request.

1. Fork the repository
2. Create your feature branch: git checkout -b my-new-feature
3. Commit your changes: git commit -am 'Add some feature'
4. Push to the branch: git push origin my-new-feature
5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.