Run a Scan Node
This page contains the steps and technical recommendations to help you set up your node. Please always refer to this documentation for the most up-to-date information.
If you have not seen the full list of onboarding steps yet, please see them first through here.
Before continuing, please make sure that you have filled out the application form and agreed to terms of participation first. You can feel free to follow this documentation and start your node while your application is being reviewed but please also keep in mind that your application may get rejected.
Fortification Phase 1
At this phase, only Forta-approved nodes are allowed onto the network and staking is done by Forta Foundation on behalf of participants. In the next phase, participants will have the option to stake FORT on their nodes. Unstaked nodes do not get assigned detection bots and do not generate any rewards.
Scan Node Requirements
The following are the requirements for running a Forta scan node.
- 64-bit Linux distribution
- CPU with 4+ cores
- 16GB RAM
- Connection to Internet
- Docker v20.10+
- 100GB SSD (in addition to full node requirements)
- Recommended: Full node (any chain)
Example: Run your Ethereum full node
erigon-rpcdaemon --http.vhosts '*' --http.port 8545 --http.addr 0.0.0.0 --http.corsdomain '*' --http.api 'eth,net,web3,trace' --private.api.addr=localhost:9090
erigon --private.api.addr=localhost:9090
Ethereum node access
Be sure to set --http.vhosts
to allow hostname access, and enable eth,net,web3
HTTP APIs. Note that trace
is only applicable for Ethereum mainnet.
Synchronize system time
To produce correct timestamps on the alerts and avoid authorization problems at the time of publishing alerts, you must ensure at all times that the system time is correct. If the system time is not correct, your node will fail to publish alerts and may generate no rewards as a result.
We suggest using systemd-timesyncd
which is widely available and sufficient as a time synchronization daemon. After started, it will periodically synchronize the system time in background.
To enable, systemd-timesyncd
and check the result, you can do:
$ sudo systemctl enable systemd-timesyncd
$ sudo systemctl start systemd-timesyncd
$ timedatectl status
Local time: Tue 2022-01-01 17:00:00 -03
Universal time: Tue 2022-01-01 20:00:00 UTC
RTC time: Tue 2022-01-01 20:00:00
Time zone: America/Argentina/Buenos_Aires (-03, -0300)
System clock synchronized: yes
NTP service: active <------------------- (it worked)
RTC in local TZ: no
Install and Configure Docker
Install Docker (at least v20.10)
Add a file called daemon.json
to your /etc/docker
directory with the following contents:
{
"default-address-pools": [
{
"base":"172.17.0.0/12",
"size":16
},
{
"base":"192.168.0.0/16",
"size":20
},
{
"base":"10.99.0.0/16",
"size":24
}
]
}
Avoid networking conflicts
Please confirm these network ranges don't conflict with your node's network, especially if you use VPC peering, VPNs, or other non-trivial networking settings.
Restart docker with systemctl restart docker
Ensure docker is running. You can run docker ps
and you should not get any errors and see a list of header columns.
Run Docker as a non-root user
To run docker as a non-root user, do the following:
Add the docker group (it may already exist)
sudo groupadd docker
Add your user to that group.
sudo usermod -aG docker your-user
You must exit and login again to take effect
Make sure Docker is running
Once docker ps
gives you a list of headers, continue to the next section.
Install Forta
The Forta scan node software is available for popular 64-bit Linux distributions using official Forta repositories. Package installation methods are verifiable (auto-verified during installation) and help you install required dependencies.
Install via YUM (CentOS, Fedora, Red Hat Enterprise Linux etc.)
$ sudo curl https://dist.forta.network/repositories/yum/Forta.repo -o /etc/yum.repos.d/Forta.repo -s
$ sudo yum install forta
Install via APT (Ubuntu, Debian etc.)
$ sudo curl https://dist.forta.network/pgp.public -o /usr/share/keyrings/forta-keyring.asc -s
$ echo 'deb [signed-by=/usr/share/keyrings/forta-keyring.asc] https://dist.forta.network/repositories/apt stable main' | sudo tee -a /etc/apt/sources.list.d/forta.list
$ sudo apt-get update
$ sudo apt-get install forta
Install Manually
Install Docker (at least v20.10)
Download the latest x86-64 release binary and install
$ sudo curl https://dist.forta.network/artifacts/forta -o /usr/local/bin/forta
Make the binary executable
$ sudo chmod 755 /usr/local/bin/forta
Initial Setup
Forta scan node's CLI allows you to set up your first Forta configuration directory along with creating and managing your scan node's private key.
Initialize Forta Directory
Initialization creates a private key that will sign the alerts from your scan node. You must set the FORTA_PASSPHRASE
environment variable or provide the --passphrase flag to the init
command.
Initialize Forta using the forta init
command
$ forta init --passphrase <your_passphrase>
Forta Directory
By default, the forta directory is located in ~/.forta
. If you would like to use a different directory, either set the FORTA_DIR
env var or provide the --dir
flag to every command. Init command will initialize your Forta configuration and key to this directory.
This command generates a config directory, a private key and outputs your address.
Scanner address: 0xAAA8C491232cB65a65FBf7F36b71220B3E695AAA
Successfully initialized at /yourname/.forta
This is the value that will be registered in the scan node registry smart contract (as uint256
).
If you need to find out your address later again, you can run forta account address
.
Backup Forta Directory
🚨 If you delete scan node data without backup, you cannot restore your scan node. 🚨
🔐 You should never lose your private key in ~/.forta/.keys
and your passphrase. 🔐
To avoid losing the control of your node address and save yourself configuration time, you can back up your Forta directory at ~/.forta
to some place only you can access. At the time of setting up your node on a new server and restore your scan node data, it is sufficient to just copy the backed up Forta directory to ~/.forta
. After doing this, you can verify that it has worked by doing forta account address
and seeing if the outputted node address is correct.
Without your passphrase, your private key cannot be decrypted so backing up your passphrase is as equally important as backing up the directory. Losing the passphrase is another way of losing your private key file in ~/.forta/.keys
. If you choose to back up your passphrase, make sure you store it in a different location than your ~/.forta
directory to reduce risks of losing the control of your node if a backup location of yours gets exposed to an attacker.
Recovery
Not required for node setup
If you have visited this documentation to set up your node, you can safely skip this Recovery section. It is placed here to inform you about potential problems if you lose data and for troubleshooting if needed later.
"I lost my scan node data, now what?"
Losing the scan node private key will require you to transfer your stake to a new scan node address after you finish setting up your new node. Same applies if your node private key and/or passphrase was stolen and you would like to switch to a new address.
The scan node private key does not own or control the staked FORT.
The first thing to check to see is if you own the shares to your stake by querying 11. sharesOf
method in Forta staking contract on Polygonscan by inputting:
-
subjectType: 0
-
subject: Your scan node address
-
account: Your owner wallet address
If the result is 0 after clicking the Query button, your owner wallet does not own the stake shares for your node and thus you cannot move your stake.
If you are able to move your stake, you can follow the steps in the Stake on your Scan Node section. Due to security reasons, this can take time.
Configure systemd
If forta
ever stops running, it must be restarted. If you used a package installation method, there is a Forta systemd service that can be enabled and overridden with your passphrase and config directory environment variables.
To override systemd service environment, you can set the variables in /etc/systemd/system/forta.service.d/env.conf
like:
[Service]
Environment="FORTA_DIR=<your_forta_config_dir>"
Environment="FORTA_PASSPHRASE=<your_forta_passphrase>"
Configure config.yml
In your Forta directory, there now is a config.yml
file. You must configure that file so that your scan node knows how to get its blockchain data.
Your scan node will be registered to scan a single chain. To let your scan node pull chain data, you need to provide a valid scan.jsonRpc.url
.
Public JSON-RPC APIs
While there are public endpoints available for many chains, please note that the quality of an endpoint drives the quality of a scan node's output which in turn affects rewards and slashing. We strongly recommend providing your own blockchain node or using a paid provider when possible.
If you are scanning Ethereum mainnet, trace.jsonRpc.url
must also be set as an endpoint that supports trace_block
method. If you have your own Ethereum node that supports it (e.g. Erigon), you can use that node. If not, you can use an endpoint from a paid plan like Alchemy Growth plan.
JSON-RPC APIs
Detection bots are able to call JSON-RPC APIs using the scan node's configured endpoints. By default, this is the scan.jsonRpc.url
but one can separate bot-specific traffic by specifying a jsonRpcProxy.jsonRpc.url
. We suggest setting this as your own node's JSON-RPC API endpoint if you are running one. If not, it is better to set this as a different JSON-RPC API endpoint than scan.jsonRpc.url
.
If your node is scanning chains other than Ethereum mainnet, please checkout the final section to see options.
Here is an example configuration to scan Ethereum mainnet using Alchemy Growth plan:
chainId: 1
# The scan settings are used to retrieve the transactions that are analyzed
scan:
jsonRpc:
url: https://eth-mainnet.alchemyapi.io/v2/KEY
trace:
jsonRpc:
url: https://eth-mainnet.alchemyapi.io/v2/KEY
# The proxy settings are used for detection bots to make their own json-rpc calls.
# By default, this is set to the scan node url value. We recommend setting
# this differently than the scan node url value if you are using a paid plan.
jsonRpcProxy:
jsonRpc:
url: http://different-api:8545
Another example configuration to scan Ethereum mainnet using your Erigon node, which is much simpler:
chainId: 1
scan:
jsonRpc:
url: http://your-node:8545
trace:
jsonRpc:
url: http://your-node:8545
# Defaulting to scan node url because it is not set - the best option when running a node
# jsonRpcProxy:
# jsonRpc:
# url: http://your-node:8545
Register Scan Node
Your scan node has an Ethereum address that makes two main features possible:
- Receiving detection bots to run
- Asserting an authority on the outputted alerts
While this address remains as the main identity, it must be owned by a different wallet. After registration, the scan node is minted as an NFT (ERC721) and transferred to this owner. You can check the smart contract documentation here.
In the future, the owner wallet will allow you to disable your scan node remotely and avoid slashing while you do maintenance (for a short period) or when you decide to shut down your node entirely. Right now, forta disable
and forta enable
commands are available to you to do the same using the scan node private key.
To register your node to the registry contract, you can run forta register --owner-address <address>
. Make sure you have set the chainId
in your config.yml correctly before executing this. Your scan node can be registered only once and to scan a specific chain. The owner wallet address needs to be a different address than your scan node address.
Action requires funds
You need to fund your scan node address with some Polygon (Mainnet) MATIC to be able to send this transaction. You can find out your scan node address with forta account address
.
After your registration transaction is included in the next block, you can start your node as described in the next section. However, your node will not be assigned any detection bots or generate any rewards until the application you submitted through the application form succeeds.
If your application succeeds, you will receive an email with a link to a second form. Once your node is running, complete this second form with your node address (found via forta account address
) as soon as possible so Forta Foundation can stake on your behalf. We only stake on running nodes to avoid impacting overall network reliability.
Run Scan Node
Start Docker
Ensure Docker is running use the docker command docker ps
. If it is not running, start docker before running Forta.
Start Forta via systemd
Run the systemd service to start Forta
sudo systemctl daemon-reload
sudo systemctl enable forta
sudo systemctl start forta
Start Forta manually
Run the forta run
command to start processing blocks.
$ forta run --passphrase <your_passphrase>
Verify Execution
Run forta status
command to see how your scanner is doing. As more services start, this status output will be dynamically updated. If you see any yellows or reds, please check the error messages, your config and your machine's network connectivity. If you can't make any sense of it, please let us know.
You can also view the forta-scanner logs for batches of alerts.
$ docker logs -f forta-scanner
Bot Assignments
Your scan node might not have any bots assigned. This is okay. As bots are added to the network, the network will assign bots to your node.
To see a list of bots that the node is running, use this command.
$ docker ps | grep forta-agent
Scanning other chains
It's best to use your own full node for scanning. If you don't have a node, here are some API alternatives that you can use:
BSC
You can choose from public BSC endpoints at https://docs.binance.org/smart-chain/developer/rpc.html.
chainId: 56
scan:
jsonRpc:
url: https://bsc-dataseed.binance.org/
trace:
enabled: false
Polygon
chainId: 137
scan:
jsonRpc:
url: https://polygon-rpc.com/
trace:
enabled: false
Avalanche
chainId: 43114
scan:
jsonRpc:
url: https://api.avax.network/ext/bc/C/rpc
trace:
enabled: false
Arbitrum
chainId: 42161
scan:
jsonRpc:
url: https://arb1.arbitrum.io/rpc
trace:
enabled: false
Optimism
chainId: 10
scan:
jsonRpc:
url: https://mainnet.optimism.io
trace:
enabled: false
Fantom
chainId: 250
scan:
jsonRpc:
url: https://rpc.ftm.tools/
trace:
jsonRpc:
url: https://rpcapi-tracing.fantom.network/
Monitor SLA
To monitor whether your scan node is performing well, use the SLA-API