Skip to content

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. This page will cover how to use this powerful new handler function.

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,
        },
      ],
    },
  };
};

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 (as for the second bot), then all the alerts generated by that bot 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.