Consuming bot alerts

With the addition of the new handleAlert handler, bots are now able to subscribe to alerts from the Forta network. This enables increased composability and higher reuse of existing bots when building your own bot.

Prior to this change, developers could manually query for alerts using the getAlerts SDK method or directly using the Forta Alerts GraphQL API. With the handleAlert function, Forta makes threat detection more modular by treating bot reuse as a first-class feature. When developing locally, you will need to set the fortaApiKey property in your forta.config.json to consume alerts (and also have a paid plan). This page will cover how to use this powerful new handler function.

Apply for subsidy

Developers building this type of bots that consume data from other bots can apply for a subsidy to receive free use of the General Plan until their bots earn enough recurring revenue. Please fill this form to submit your application

Specifying bots to subscribe

In order to specify which bot's alerts you want to receive, you need to implement the initialize handler function and return an InitializeResponse object describing the desired alerts:

const BOT_ID_1 =
  "0x77281ae942ee1fe141d0652e9dad7d001761552f906fb1684b2812603de31049";
const BOT_ID_2 =
  "0x55636f5577694c83b84b0687eb77863850c50bd9f6072686c8463a0cbc5566e0";

const initialize: Initialize = async () => {
  return {
    alertConfig: {
      subscriptions: [
        {
          botId: BOT_ID_1,
          alertIds: ["ALERT-1", "ALERT-2"],
        },
        {
          botId: BOT_ID_2,
          chainId: 137,
        },
      ],
    },
  };
};

In the above code snippet, we are specifying 2 bots to subscribe to. For the first bot, we are also specifying the alertIds we are interested in. If no alertIds are specified, then all the alerts generated by that bot will be received. For the second bot, we are also specifying the chainId we are interested in (i.e. only alerts generated by the bot on Polygon chain (137) will be received). If no chainId is specified, then all the alerts generated for all chains will be received.

Also, remember to export the initialize and handleAlert (described below) handlers:

export default {
  initialize,
  handleAlert,
};

Consuming alerts

All subscribed alerts will be received as AlertEvent objects passed into the handleAlert function:

const handleAlert: HandleAlert = async (alertEvent: AlertEvent) => {
  const findings: Finding[] = [];

  if (alertEvent.botId === BOT_ID_1) {
    // do something
  } else if (alertEvent.botId === BOT_ID_2) {
    // do something else
  }
  return findings;
};

Upon receiving the alert, your bot can do further processing to detect scenarios you are interested in.

Testing alerts

New CLI commands were also added to support development of bots using handleAlert. You can test your bot against a specific alert using the forta-agent run --alert command (or npm run alert) by providing the alert hash e.g. npm run alert 0xabc123. You can provide a comma-delimited list to run multiple alerts.

Additionally, you may want to run a sequence of transactions/blocks/alerts to test your bot which can be done using the forta-agent run --sequence command (or npm run sequence). This allows for testing more complex scenarios that involve multiple handlers. Syntax is important here to distinguish between transactions/blocks/alerts i.e.

• alerts are specified by their hash (0xabc123)
• blocks are specified by their block number (1234)
• transactions are specified by their hash prefixed with "tx" (tx0xdef567)

An example sequence run could then be npm run sequence 0xabc123,1234,tx0xdef567 which would first run the alert, followed by the block, followed by the transaction.