Forta Detection Bot SDK and CLI

Visit forta.org to learn more about Forta. See the developer documentation at docs.forta.network

Bug Bounty

We have a bug bounty program on Immunefi. Please report any security issues you find through the Immunefi dashboard, or reach out to [email protected]

Changelog

0.1.48

• Expose filterLog as standalone utility function
• Check for empty addresses when populating TransactionEvent.addresses field
• Add support for label embeddings

0.1.47

• Updated JS and TS starter project dependencies

0.1.46

• Updated axios and jest dependencies

0.1.45

• Added support for uniqueKey field in labels

0.1.44

• Added Network chain ID enum for Base

0.1.43

• Added support for healthCheck method to report bot health
• Updated grpc proto definition

0.1.42

• Added support for external bots with the sendAlerts SDK method

0.1.41

• Add retry logic when querying alerts for bots that use handleAlert

0.1.40

• Reduce the page size of queries made when fetching alerts for bots using handleAlert

0.1.39

• Reduce the size of queries made when fetching alerts for bots using handleAlert

0.1.38

• Fix Python Finding.unique_key parsing

0.1.37

• Increase grpc response size limits
• Fix Python pagination issue when querying get_labels
• Improve error messages from alerts API

0.1.36

• Updated type definition for FindingSource

0.1.35

• Updated starter project templates

0.1.34

• Added new optional fields uniqueKey and source to findings
• Added support for new bot manifest fields: longDescription, licenseUrl, promoUrl

0.1.33

• Updated Python child process behaviour to exit on exceptions

0.1.32

• Added getLabels method to query the Forta API for labels

0.1.31

• Fixed issue when publishing bot manifest without speciyfing chain settings

0.1.30

• Expanded alert query lookback window when running handleAlert locally
• Improved sharding configuration validation

0.1.29

• Added new stake CLI command to stake on a detection bot
• Fixed Python error handling to also reject NodeJS promise

0.1.28

• Added retry logic for CLI run command to improve reliability of running bots locally
• Improved error handling for Python bots by showing stack traces

0.1.27

• Fixed issue for parsing findings returned from Python bots

0.1.26

• Added new FindingType value of Scam

0.1.25

• Added bot license

0.1.24

• Increased max findings response size to 250kB
• Updated label metadata field to be a map

0.1.23

• Added metadata field to Labels

0.1.22

• Updated run command to wait 60 seconds between alert queries for bots using handleAlert locally

0.1.21

• Added support for address bloom filters on AlertEvent
• Updated CLI errors to return a non-zero exit code
• Changed Alert interface into a class
• Increased maximum number of findings returned in a response to 50

0.1.20

• Fixed labels parsing when querying for alerts

0.1.19

• Added support for running shards i.e. multiple bot instances
• Added labels to alerts
• Updated handleAlert subscriptions to allow specifying filter by chainId
• Updated grpc controller to ensure initialize handler only invoked once
• Updated grpc proto definition

0.1.18

• Updated grpc proto definition to add alert.chainId field

0.1.17

• Added support for remove field for Labels
• Fixed filter_function bug in Python SDK
• Fixed fetchJwt SDK method to return mock value during development
• Fixed fetchJwt JS SDK method to return string instead of object
• Added repository URL to starter project package.json

0.1.16

• Updated grpc proto definitions for Labels
• Updated run --file command to also accept hashes
• Add alert and sequence npm commands to starter projects
• Updated BotSubscription to make alertId optional and also allow passing alertIds

0.1.15

• Fixed grpc proto definitions

0.1.14

• Added support for handleAlert handler
• Added support for specifying labels on findings

0.1.13

• Return findings from runHandlersOnBlock and runHandlersOnTransaction methods

0.1.12

• Remove sha3 dependency from Python SDK

0.1.11

• Bug fix to the fetch_jwt method in the Python sdk

0.1.10

• Added new methods fetchJwt, decodeJwt and verifyJwt to Typescript sdk for generating and verifying a jwt token from a scan node
• Added new method fetch_jwt, decode_jwt, and verify_jwt to Python sdk for generating and verifying a jwt token from a scan node
• Limit size of findings returned from handleBlock and handleTransaction callbacks

0.1.9

• Use forta ipfs node for info command
• Added new method getAlerts to Typescript sdk to that fetches alerts using forta's alert graphql api
• Added new method get_alerts to Python sdk to that fetches alerts using forta's alert graphql api
• Fixing docker build issue

0.1.8

• Updated chainId validation of run command to print out warning instead of throwing error
• Added info and logs commands as npm scripts of starter projects
• Updated uploadImage function to accept image tag suffix

0.1.7

• Added two new cli commands: info and logs
• Validate chainId of jsonRpcUrl when running bot
• Generate unique bot id when initializing bot
• Adjust block polling time based on chainId when running bot locally

0.1.6

• Fix sort order for chainIds array

0.1.5

• Fix issue for CLI publish command when querying account balance

0.1.4

• Update gRPC agent.proto to add Finding.addresses
• Add support for addresses field to Finding
• Add verification for account balance and ownership when running publish CLI command
• Provide default gas estimates when interacting with registry smart contract functions
• Include logIndex in result of TransactionEvent.filterLog
• Include address in result of TransactionEvent.filterFunction
• Add Finding.from alias method for Finding.fromObject

0.1.3

• Set contextPath when building image

0.1.2

• Update starter project README

0.1.1

• Update AgentRegistry contract ABI
• Add default chainIds to starter project package.json
• Fix Python starter project dependencies

0.1

• Update gRPC agent.proto to deprecate TransactionEvent.Receipt
• Update SDK to remove receipt, status and gasUsed properties from TransactionEvent
• Add getTransactionReceipt convenience method to SDK
• Update CLI run command to not fetch transaction receipts
• Update starter projects to detect for large Tether transfers
• Update terms of use URL

0.0.41

• Set default jsonRpcUrl to https://cloudflare-eth.com
• Expose CLI functionality using configureContainer method
• Update CLI init command to also run npm install

0.0.40

• Fix Python SDK support for new chains
• Add terms of use prompt to CLI init command
• Update starter project Dockerfile to include line to enable logging

0.0.39

• Add keyfilePassword config field for CI/CD pipelines
• Set default ipfsGatewayUrl to https://ipfs.forta.network
• Update getJsonRpcUrl to not throw error when running unit tests
• Update agent image build process to always target amd64 architecture

0.0.38

• Add description field to agent manifest from package.json

0.0.37

• Add support for specifying multiple addresses in filterLog and filterFunction commands
• Add --nocache option to forta-agent run command to disable writing to cache
• Fix forta-agent run command to process blocks sequentially when listening for realtime data

0.0.36

• Add support for specifying chainIds in package.json

0.0.35

• Add support for private agents with the setPrivateFindings method
• Deprecate everestId attribute of Finding
• Deprecate filterEvent method of TransactionEvent

0.0.34

• Add disk caching for the forta-agent run command

0.0.33

• Add support for specifying multiple transactions/blocks for the forta-agent run command
• Include CLI version in published manifest
• Add getEthersBatchProvider utility function to Javascript SDK
• Export the keccak256 utility function from Javascript and Python SDK

0.0.32

• Actually fix published npm artifact

0.0.31

• Fix published npm artifact

0.0.30

• Fix agent publishing on Apple M1 chips

0.0.29

• Add address field to result of filterLog method
• Fix from property in agent manifest
• Increase gas price for transactions from CLI commands
• Add check to ensure agent documentation is not empty

0.0.28

• Fix handling of network value in Python SDK

0.0.27

• Change base Docker image for starter projects to node12-alpine
• Export ethers object from Javascript SDK
• Add getEthersProvider convenience method to SDK
• Add filterLog and filterFunction convenience methods to TransactionEvent in SDK
• Export web3 object from Python SDK
• Add get_web3_provider convenience method to Python SDK
• Add filter_log and filter_function convenience methods to TransactionEvent in Python SDK
• Add agentId config property to support Forta Connect publishing
• Include results of push command in publish.log
• Improve CLI keyfile lookup
• Fix CLI exit when running Python agents
• Don't export getFortaConfig and get_forta_config from SDK

0.0.26

• Use more raw JSON-RPC calls in CLI

0.0.25

• Add new CLI command: push
• Replace web3.js with ethers.js
• Use raw JSON-RPC calls to fetch blocks and receipts in CLI
• Add limit of 5 alerts to starter projects

0.0.24

• Add new CLI command: keyfile
• Add keyfile npm script to starter projects
• Add repository field to agent manifest

0.0.23

• Transition to Polygon agent registry
• Provide default value for agentRegistryJsonRpcUrl
• Fix agent existence check

0.0.22

• Add new CLI commands: enable and disable
• Increase gas for transactions from CLI commands
• Remove duplicated BlockEvent properties
• Add obfuscation step to Javascript and Typescript starter project Dockerfile

0.0.21

• Improve init command to ensure that keystore folder exists

0.0.20

• Fix CLI keyfile resolution

0.0.19

• Make config file global by default (with option to override locally)
• Fix starter project npm scripts to support Windows
• Move agentId (derived from name) and version to package.json
• Remove documentation config property and hardcode to README.md
• Improve run command to not scan over same block
• Add project URLs to npm and PyPi pages

0.0.18

• Fix published npm artifact
• Add npm script to ensure we build before publishing

0.0.17

• Add initialize() handler to SDK
• Add output field to TraceResult
• Add Info option to FindingType enum
• Add more error logging to grpc controller
• Add more unit tests for CLI and SDK
• Add MIT license

0.0.16

• Fix handler initialization to maintain Python agent state
• Ensure that jsonRpcUrl is http(s) only
• Fix hex_to_int Python SDK method to accept integers
• Add error logging to grpc controller

0.0.15

• Update Typescript starter project npm scripts to build before running

0.0.14

• Add unit tests to Python starter project
• Fix hex_to_int Python SDK convenience method
• Fix Typescript starter project Dockerfile

0.0.13

• Update Python starter project requirements.txt
• Improve Python error handling

0.0.12

• Add Python SDK
• Add Python starter project
• Fix Python agent to run in single long-running process
• Fix race condition when listening for blocks
• Improve Python error handling
• Fix receipt status not being set correctly
• Remove handlers config property and hardcode agent filename

0.0.11

• Add keyfile config property to specify a keyfile when publishing
• Add publish.log file to log publishing result
• Add createTransactionEvent and createBlockEvent utility methods for tests
• Fix receipt addresses to be lowercase
• Add unit tests for CLI commands: init, run and publish
• Fix websocket connection preventing clean exit of CLI
• Exclude unit tests from build
• Fix file logging to append newline character

0.0.10

• Update jest type definitions to v27.0.1

0.0.9

• Add agent documentation to manifest when publishing
• Add agent documentation to starter projects
• Update agent registry address
• Export more classes from SDK
• Improve error message when unable to parse config file
• Remove usage of web sockets when listening for blockchain data
• Remove unnecessary call to eth_getTransaction

0.0.8

• Add support for Python agents
• Add more block data to BlockEvent
• Add unit tests for starter project
• Format addresses to be lowercase
• Improve error message when config file not found
• Hardcode Disco auth credentials
• Add retry logic if fetching transaction or receipt fails

0.0.7

• Add SDK support for tracing via traceRpcUrl config property
• Add support for --config CLI arg to specify a config file
• Add check for empty directory before initializing starter project
• Add Disco authentication when publishing
• Update filepath resolution to be OS-agnostic
• Include forta.config.json in starter project .gitignore

0.0.6

• Use new agent registry contract

0.0.5

• Hardcode scanner poolId
• Rename ipfsGatewayAuthHeader config property to ipfsGatewayAuth
• Add publish npm script to starter project

0.0.4

• Remove .npmignore file after initializing starter project

0.0.3

• Add getJsonRpcUrl and getFortaConfig SDK convenience methods
• Add more alias methods for TransactionEvent properties in SDK
• Add npm scripts to starter project package.json
• Export FortaConfig type from SDK
• Fix starter project .gitignore renaming issue when publishing npm package

0.0.2

• Update init to use existing keyfile if one exists (instead of always creating new one)
• Update starter project package.json to use forta-agent npm package

0.0.1

• Initialize repository
• Initialize CLI commands: init, run and publish
• Initialize Javascript and Typescript SDK
• Initialize Javascript and Typescript high gas starter project