# nethermindeth-general-agents-module

> Forta Agents for common approaches

Latest version **1.0.11** (published 2021-10-06) · GPL-3.0 license · 0 weekly downloads

## Install

```sh
npm install nethermindeth-general-agents-module
pnpm add nethermindeth-general-agents-module
yarn add nethermindeth-general-agents-module
bun add nethermindeth-general-agents-module
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.11 |
| Published | 2021-10-06 |
| First published | 2021-10-06 |
| Weekly downloads | 0 |
| License | GPL-3.0 |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 127.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Nethermind |
| Maintainers | nethermindeth |

## Links

- npm: https://www.npmjs.com/package/nethermindeth-general-agents-module
- Repository: https://github.com/NethermindEth/general-agents-module
- Homepage: https://github.com/NethermindEth/general-agents-module#readme
- Issues: https://github.com/NethermindEth/general-agents-module/issues
- npm.io page: https://npm.io/package/nethermindeth-general-agents-module

## Dependencies (1)

- [forta-agent](https://npm.io/package/forta-agent.md) 0.0.18

## Recent versions

- 1.0.11 (latest) — 2021-10-06
- 1.0.10 — 2021-10-06

## README

# General Agent Module

## Description

This module contains some common approaches for building Forta Agents. You will also find some tools for writing tests for these agents. These approaches can be composed for creating more complex agents or used only for checking without returning their findings.

## Installation

- Using npm: `npm install @nethermindeth/general-agents-module`

or

- Clone the repo
- npm install
- npm run test

## General Types

There are multiple types used across all the modules.

-  `metadataVault`
    > This type works as a store for every data that is passed to the `FindingGenerator`. It is a `dict` with `string` as keys and `any` type in its values.
-  `FindingGenerator`
    > All the approaches receive a function with this type. This function will be in charge of creating the Findings when the agent's conditions are met. This function can receive a `metadataVault` as a parameter where finding relevant information will be pass, this information can be used for creating more informative findings. This type is an alias for `(metadata?: metadataVault) => Finding`. The information set in the `metadataVault` for every approach will be described in the approach documentation.

## Approaches

### - Function Call Detector Agent

This approach detects method calls on Smart Contracts. You need to provide the signature of the method you want to detect. You can also provide options for specifying extra filters as "what account made the call" or "what contract was called".
#### How to use it
```ts
import { provideFunctionCallsDetectorAgent } from "@nethermindeth/general-agent-module";

const agent = provideFunctionCallsDetectorAgent(findingGenerator, functionSignature, agentOptions?);
```

#### Arguments

- `findingGenerator`: The purpose of this argument was explained in the "General Types" section. The function provided as an argument will receive a `metadataVault` with the keys:
  - `from`: The account calling the method.
  - `to`: The Smart Contract called.
  - `input`: The transaction data.
- `functionSignature`: The signature of the method you want to detect.
- `agentOptions`: This is an optional argument, it contains extra information for adding extra filtering to your detections. It is a JS object with the following optional properties:
  - `from`: If provided, the approach will only detect method calls from the specified account.
  - `to`: If provided, the approach will only detect method calls to the specified Smart Contract.


### - Event Checker Agent

This approach detects events emitted. You need to provide the signature of the event you want to detect. You can also provide other arguments for specifying extra filters as "who did emit the event" or manually adding a specific filtering function.
#### How to use it
```ts
import { provideEventCheckerHandler } from "@nethermindeth/general-agent-module";

const agent = provideEventCheckerHandler(findingGenerator, eventSignature, address?, filter?);
```

#### Arguments

- `findingGenerator`: The purpose of this argument was explained in the "General Types" section. The function provided as an argument will receive a `metadataVault` with the keys:
  - `topics`: An array containing the event's topics.
  - `data`: The event's data
  - `address`: The address emitting the event.
- `address`: If provided, the approach will only detect events emitted from the specified account.
- `filter`: If provided, the approach will only detect events that are not discarded by the filter. This function has the type `(log: Log, index?: number, array?: Log[]) => boolean`, it will be used as argument for the common `filter` arrays function.

### - Eth Transfer Agent

This approach detects eth transfers. You can also provide more arguments for specifying extra filters as "who made the transfer", "who is the receiver", and a minimum amount for detecting transfers

#### How to use it

```ts
import { provideETHTransferAgent } from "@nethermindeth/general-agent-module";

const agent = provideETHTransferAgent(findingGenerator, agentOptions?);
```

#### Arguments

- `findingGenerator`: The purpose of this argument was explained in the "General Types" section. The function provided as an argument will receive a `metadataVault` with the keys:
  - `from`: The account making the transfer.
  - `to`: The account receiving the transfer.
  - `amount`: The amount of `eth` sent in `wei`.
- `agentOptions`: This is an optional argument, it contains extra information for adding extra filtering to your detections. It is a JS object with the following optional properties:
  - `from`: If provided, the approach will only detect transfers from the specified account.
  - `to`: If provided, the approach will only detect transfers to the specified account.
  - `valueThreshold`: If provided, the approach will only detect transfers with a greater or equal amount of `eth` in `wei`.

### - ERC20 Transfer Agent

This approach detects ERC-20 transfers. You will need to provide the address of the ERC-20 contract you want to detect transfers of. You can also provide more arguments for specifying extra filters as "who made the transfer", "who is the receiver of the transfer". and a minimum amount for detecting transfers.

#### How to use it

```ts
import { provideERC20TransferAgent } from "@nethermindeth/general-agent-module";

const agent = provideERC20TransferAgent(findingGenerator,  tokenAddress, agentOptions?);
```

#### Arguments
- `findingGenerator`: The purpose of this argument was explained in the "General Types" section. The function provided as an argument will receive a `metadataVault` with the keys:
  - `from`: The account making the transfer.
  - `to`: The account receiving the transfer.
  - `amount`: The number of tokens sent
- `tokenAddress`: The address of the ERC-20 contract you want to detect transfers of.
- `agentOptions`: This is an optional argument, it contains extra information for adding extra filtering to your detections. It is a JS object with the following optional properties:
  - `from`: If provided, the approach will only detect transfers from the specified account.
  - `to`: If provided, the approach will only detect transfers to the specified account.
  - `valueThreshold`: If provided, the approach will only detect transfers with a greater or equal number of tokens.

## Utils

###  TestTransactionEvent

This is a helper class for creating `TransactionEvents` using the fluent interface pattern.

#### How to use it

```ts
import { TestTransactionEvent } from "@nethermindeth/general-agent-module";

const txEvent: TransactionEvent = new TestTransactionEvent().setFrom(address1).setTo(address2);
```

There are multiple methods you can use for creating the exact `TransactionEvent` you want:
- `setFrom(address)` This method sets the `transaction.from` field in the event.
- `setTo(address)` This method sets the `transaction.to` field in the event.
- `setValue(value)` This method sets the `transaction.value` field in the event.
- `setData(data)` This method sets the `transaction.data` field in the event.
- `setGasUsed(value)` This method sets the `receipt.gasUsed` field in the event.
- `setStatus(status)` This method sets the `receipt.status` field in the event.
- `setTimestamp(timestamp)` This method sets the `block.timestamp` field in the event.
- `addEventLog(eventSignature, address, topics, data)` This method add a log to the `receipt.logs` field. The only mandatory argument is the `eventSignature`, `address` argument is the zero address by default, `topics` is a list with only the `keccak256` hash of the signature by default, and `data` is the empty string by default.
- `addInvolvedAddress(address)` This method add an address to `addresses` field.
- `addTrace({ to, from, input, output })` This method adds an item to the `traces` field. All the fields in the argument are optional.

---
_Source: https://npm.io/package/nethermindeth-general-agents-module · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._