npm package: @nexeth/heimdall
Description: [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![npm (tag)](https://img.shields.io/npm/v/@nexeth/heimdall)](https://www.npmjs.com/package/@nexeth/heimdall) [![CI Tests](https://github.com/nexeth/ether
Latest version: 0.1.3

# @nexeth/heimdall

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![npm (tag)](https://img.shields.io/npm/v/@nexeth/heimdall)](https://www.npmjs.com/package/@nexeth/heimdall)
[![CI Tests](https://github.com/nexeth/ethereum-js/actions/workflows/test.yaml/badge.svg?branch=main)](https://github.com/nexeth/ethereum-js/actions/workflows/test.yaml)
![npm (downloads)](https://img.shields.io/npm/dm/@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`](https://www.npmjs.com/package/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.

```bash
npm install viem @nexeth/heimdall
```

or

```bash
yarn add viem @nexeth/heimdall
```

## Quick Start

1. Import `@nexeth/heimdall` into your project:

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

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

```ts
import { mainnet } from "viem/chains";

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

3. Start listening to blockchain events

```tsx
// 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

```tsx
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**

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.