Merge branch 'master' of github.com:forta-network/docs

docs/api-reference.md

@@ -2,7 +2,7 @@
 
 Forta currently supports GraphQL API access to intelligence emitted by detection bots. Each bot’s documentation will describe the types of intelligence it generates, and will often have details about the detection methodology used. For Premium Feeds in particular, bot documentation should also feature example queries you can use to get up and running quickly. The API endpoint is [https://api.forta.network/graphql](https://api.forta.network/graphql) and an API key is required. 
 
-Note: Your query must also include the specific bot ID(s) you want intelligence from. 
+Note: Your query must also include the specific bot ID(s) you want intelligence from. When querying for `alerts` you  must specify `bots` when querying for `labels` you must specify `sourceid`. 
 
 
 ### **Before you can access the API, you must:**

docs/bot-json-rpc-provider.md

@@ -0,0 +1,118 @@
+# V2 Bot JSON-RPC Provider Setup
+
+With v2 detection bots, developers can scan any EVM-compatible chain by bringing their own RPC endpoints. This guide discusses a few options for setting up your bot's RPC provider for local development and production.
+
+## Public RPC URLs
+
+The simplest way to get started is to use a public RPC endpoint for your specific chain. These endpoints are free to use, but typically come with rate limits to prevent misuse. Depending on the rate limits, your bot's performance will vary. Unless you are certain that your bot will stay within the set limits, we don't recommend using public RPC URLs in production. However, you may find these convenient for local development.
+
+## Private RPC URLs
+
+Another common way to communicate with RPC providers is to create a private RPC endpoint which typically contains some sort of secret API key within the URL itself. These are usually offered through a freemium payment model with more generous rate limits. However, hardcoding the RPC URL (and secret API key) within the bot itself is a security issue because the bot Docker images are stored in a public repository which anyone can view. For this reason, private RPC URLs are better suited for local development but not for production.
+
+## JWT-Authenticated RPC URLs
+
+Certain RPC providers have the option to create a JWT-authenticated RPC endpoint that can **_only be accessed by scan nodes that are running your bot_**. Setting up this kind of RPC endpoint is easy and requires registering the Forta public key with the provider. Suggested providers that support this kind of authentication mechanism include (but are not limited to) [Alchemy](https://www.alchemy.com/), [dRPC](https://drpc.org/) and [Infura](https://www.infura.io/). The main benefit of using such a RPC endpoint is that you can hardcode the RPC URL into the bot without giving away public access to anyone who can view the bot's Docker image.
+
+### Registering the Forta public key
+
+For example, to [create a JWT-authenticated RPC URL on Alchemy](https://docs.alchemy.com/docs/how-to-use-jwts-for-api-requests) you would do the following:
+
+1. Go to the [Alchemy JWT Public Keys dashboard](https://dashboard.alchemy.com/settings/jwt-public-keys)
+2. Click "Import Public Key"
+3. Enter a name for this new key
+4. Select the App ID (i.e. RPC endpoint) you want to associate with the public key
+5. Copy and paste the Forta public key (as seen below)
+6. Click "Create" to register the key
+7. Click on the created key's name to expand it and view the key ID e.g. `67694d31-0d90-47a4-8241-0a8546958512a`
+8. Use the key ID inside your bot e.g.
+
+=== "Typescript/Javascript"
+
+    ``` Typescript
+    scanEthereum({
+      rpcUrl: 'https://eth-mainnet.g.alchemy.com/v2',
+      rpcKeyId: '67694d31-0d90-47a4-8241-0a8546958512a',
+      ...
+    })
+    ```
+
+=== "Python"
+
+    ``` Python
+    scan_ethereum({
+      'rpc_url': 'https://eth-mainnet.g.alchemy.com/v2',
+      'rpc_key_id': '67694d31-0d90-47a4-8241-0a8546958512a',
+      ...
+    })
+    ```
+
+### Forta public key
+
+```
+-----BEGIN PUBLIC KEY-----
+MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA0hsWiVoSFlrUsYPDRPjJ
+n9zghdlcVREmfSZgzdr5u//Y7Cv97waAhSB3xN8qjst5Uy/rD7fFD/6GN6FHMMg+
+fu0f/pLPJSby/mu+YBCg1LtsAXlLub8LaY20xUb4cBNHy++SzI1cQOjkqH9/vHO7
+V2aS3tc6+OS62Dy6NstB4ITskLmZdA8fJdye2LWS/DS95K37DCfIgFqxktFDovjW
+oCbJPTL4A/0Bs7tCEjUb4X7Z5v065W7Ly8W3W0m3oM09Bwr018WE+EzsSthE+E98
+nGpOUiStgoaKlDMRY+zrcjOTCHPzLn7C5aUOsyGuRJF+vy37ouq4YZSlbg87FcGw
+XuLONya3ZDR0caDMFOtD+fuDmFMSKk52ua+afNTygn5jDAGr+RNWcfGx0OeSbwO0
+5zmQ1FkIiqkoScunGFE74hYLcdCFx8CiwZzhKiwx2wRvgXnjzkZVCYZ6RwsyWADw
+MqHcc+S/+hYLUg0UNNHVSD+aJDjzneOc/DKL2h7Y3cdjX7tfJPobOaguYF+JdEzj
+VjL3a0dfT/2BHyzlpPBwCmSOZQwUqyzJV05rQfoVeqyZJhp6e1hTwTWi4Fff7TH5
+/jtZ8cixEzCblehA3dDD5XEvaWDEG+n0Qk6ZeH016c2dkrkLMQoHR+p+p3KL6PoW
+0xyzcLXL4r5ALWLwpeqSaasCAwEAAQ==
+-----END PUBLIC KEY-----
+```
+
+## Forta RPC Cache
+
+When running on scan nodes in **_production_**, v2 detection bots also have access to a RPC cache (courtesy of the Forta Network). The cache provides access to basic blockchain data including blocks, transactions and logs. The cache is _short-lived_ and only stores blockchain data for the **past 5 minutes for certain chains**. Currently the following 8 chains are supported by the cache:
+
+- Ethereum (includes trace data)
+- Polygon
+- Base
+- BSC
+- Avalanche
+- Arbitrum
+- Fantom (includes trace data)
+- Optimism
+
+## Local RPC URLs
+
+Note that JWT-authenticated RPC URLs can only work inside of a scan node (i.e. only in production). When developing locally, these URLs will not work as they require a scan node environment. To work around this when developing locally, you can specify a local RPC URL in your bot that will be used **_only when running locally_**. This way you can use public/private RPC URLs locally without exposing them to the world. For example, you would put the public/private URLs inside your `forta.config.json` like so:
+
+```json
+{
+  ...
+  "localRpcUrls": {
+    "1": "https://cloudflare-eth.com/",
+    "137": "https://polygon-rpc.com"
+  }
+}
+```
+
+and then use them inside your bot like this:
+
+=== "Typescript/Javascript"
+
+    ``` Typescript
+    scanEthereum({
+      localRpcUrl: '1',
+      rpcUrl: 'https://eth-mainnet.g.alchemy.com/v2', // only used in prod
+      rpcKeyId: '67694d31-0d90-47a4-8241-0a8546958512a', // only used in prod
+      ...
+    })
+    ```
+
+=== "Python"
+
+    ``` Python
+    scan_polygon({
+      'local_rpc_url': '137',
+      'rpc_url': 'https://polygon-mainnet.g.alchemy.com/v2', # only used in prod
+      'rpc_key_id': '89694d31-0c50-58b4-8241-0e0543959513b', # only used in prod
+      ...
+    })
+    ```

docs/bridging-fort.md

@@ -2,17 +2,30 @@
 
 You may need to bridge your FORT tokens from Ethereum to Polygon in order to stake on scan nodes or detection bots. This page will describe how to bridge your FORT tokens.
 
-1. Go to [https://wallet.polygon.technology/](https://wallet.polygon.technology/) and click on Polygon Bridge
-   ![Polygon Bridge](bridging-1.png)
-2. Log in by connecting your wallet
-   ![Connect wallet](bridging-2.png)
-3. Click "Deposit" and then click the dropdown list of tokens
-   ![Deposit](bridging-3.png)
-4. You may see the FORT token is not displayed. Click on "Manage token list"
-   ![Manage token list](bridging-4.png)
-5. Click on "Tokens", paste the FORT contract address (0x41545f8b9472D758bB669ed8EaEEEcD7a9C4Ec29) and then click "Add FORT"
-   ![Add FORT](bridging-5.png)
-6. You will now be able to find FORT in the list of tokens. Click on FORT
-   ![Select FORT](bridging-6.png)
-7. Select the amount of FORT you want to bridge and then click "Transfer" to bridge your tokens to Polygon
-   ![Transfer FORT](bridging-7.png)
+1. Go to [https://portal.polygon.technology/](https://portal.polygon.technology/) connect your wallet and click on **Bridge** in the left side menu.
+
+![homepage](bridge-guide-1.png)
+
+2. Here is where you will be able to configure your token transfer. Make sure that the **Transfer From** section (indicated as num. 1 in the diagram below) is set to Ethereum. Select the **FORT** token from the bottom right, you may need to search for the token here. Then enter the total number of FORT tokens you wish to bridge over. The **Transfer To** section (indicated as num. 2 in the diagram below) must be set to **Polygon POS**.
+
+![bridge config](bridge-guide-2.png)
+![bridge search](bridge-guide-3.png)
+
+  **Please Note:**
+  **DO NOT** bridge your FORT tokens over to Polygon zkEVM.
+  You must have some ETH in your wallet in order to pay the gas fee. 
+  The correct contract address for the FORT token on Ethereum is 0x41545f8b9472D758bB669ed8EaEEEcD7a9C4Ec29.
+  The correct contract address for the FORT token on Polygon is 0xd2863157539b1D11F39ce23fC4834B62082F6874.
+
+3. Once you have your configuration complete, click on the large purple button at the the bottom that says **"Bridge FORT to Polygon"**. Confirm the transaction within your wallet UI. Once the transaction is complete you can begin delegating your FORT to the Forta Network.
+
+  **Please Note:** 
+  Bridging transactions can take around 30 minutes on average to complete. Do not be alarmed if you don't see your FORT tokens on          Polygon immediatley. 
+
+![confirm](bridge-guide-4.png)
+
+
+
+
+
+Navigate web3 with confidence by [adding the Forta Network Metamask Snap to your wallet](https://snaps.metamask.io/snap/npm/forta-network/metamask-snap/). Learn more about how to protect yourself from scams with Forta [here](https://docs.forta.network/en/latest/Forta-for-Metamask/).

docs/deploying-app.md

@@ -16,7 +16,7 @@ After deploying, you can [view bot logs](maintaining.md#viewing-bot-logs) using
 
 Documentation for your bot is **required** in order to deploy. It should let others know what conditions your bot is detecting and what sort of alerts it will fire. Documentation will always be in the README.md file in your project folder (we have provided example documentation to help you get started). Please update the README.md for your specific bot.
 
-You will also find the [Forta Detection Bot License](https://github.com/forta-network/forta-bot-sdk/blob/master/starter-project/LICENSE.md){:target="_blank"} included in your project LICENSE.md file (and copied over in your Dockerfile). This is **required** for every detection bot deployed to the network.
+You will also find the [Forta Detection Bot License](https://github.com/forta-network/forta-bot-sdk/blob/master/starter-project/LICENSE.md){:target="\_blank"} included in your project LICENSE.md file (and copied over in your Dockerfile). This is **required** for every detection bot deployed to the network.
 
 ## Pushing your bot image
 
@@ -31,6 +31,7 @@ This will build your bot image and push it to a repository where scan nodes can
 ```
 successfully pushed image with reference bafybeifutbdhewyz7lfl4z7bfry6xfscaewwhe4n3uqi2gdj67js6plwre@sha256:3904d36d3527ae4135e479dd223c37dde1e6052ae47fdbf3305ebd506d4e34d2
 ```
+
 Copy the image reference (i.e. `bafybeifutbdhewyz7lfl4z7bfry6xfscaewwhe4n3uqi2gdj67js6plwre@sha256:3904d36d3527ae4135e479dd223c37dde1e6052ae47fdbf3305ebd506d4e34d2`) to your clipboard and head over to [Forta App](https://app.forta.network/).
 
 ## Import your keyfile into Metamask
@@ -60,14 +61,15 @@ Your Metamask should now be connected to Forta App. You should see your wallet a
 In order to deploy your bot, you will need to complete a short form by navigating to the Detection Bots page (from the menu at the top right):
 
 1. Click the Deploy Bot button to bring up the form. The bot ID will be automatically generated for you
-2. Fill in the rest of the fields with your bot's information like name, description, version and which blockchains you want to scan (currently supported chains are Ethereum, Polygon, Binance Smart Chain, Avalanche, Arbitrum, Optimism, and Fantom)
-3. For the Documentation field, select the README.md from your project folder. This will be uploaded to IPFS
-4. For the Docker Image field, paste in the image reference you copied earlier from the `npm run push` command
-5. If your code repository is public, fill in the Repository field
-6. Click the "Sign to proceed" button
-7. A Metamask dialog will appear asking you to sign the bot metadata. Click the Sign button
-8. A confirmation form will display your bot metadata, including the IPFS hash of the bot metadata and documentation. If these look good, click the Deploy Bot button to initiate the deployment transaction
-9. A Metamask dialog will appear asking you to confirm the deployment transaction. Review the details and click the Confirm button
+2. Fill in the rest of the fields with your bot's information like name, description, version
+3. For the Blockchains To Shard field, you can **optionally** specify a comma-delimited list of chain IDs to shard your bot by the specified blockchains (e.g. 1, 137, 8453)
+4. For the Documentation field, select the README.md from your project folder. This will be uploaded to IPFS
+5. For the Docker Image field, paste in the image reference you copied earlier from the `npm run push` command
+6. If your code repository is public, fill in the Repository field
+7. Click the "Sign to proceed" button
+8. A Metamask dialog will appear asking you to sign the bot metadata. Click the Sign button
+9. A confirmation form will display your bot metadata, including the IPFS hash of the bot metadata and documentation. If these look good, click the Deploy Bot button to initiate the deployment transaction
+10. A Metamask dialog will appear asking you to confirm the deployment transaction. Review the details and click the Confirm button
 
 ## Staking
 

docs/deploying-cli.md

@@ -1,6 +1,6 @@
 # Deploying your bot with the CLI
 
-This page covers how to deploy your bot using the `forta-agent` CLI tool.
+This page covers how to deploy your bot using the `forta-bot` CLI tool.
 
 ## Enable logging (optional)
 
@@ -16,7 +16,7 @@ After deploying, you can [view bot logs](maintaining.md#viewing-bot-logs) using
 
 Documentation for your bot is **required** in order to deploy. It should let others know what conditions your bot is detecting and what sort of alerts it will fire. Documentation will always be in the README.md file in your project folder (we have provided example documentation to help you get started). Please update the README.md for your specific bot.
 
-You will also find the [Forta Detection Bot License](https://github.com/forta-network/forta-bot-sdk/blob/master/starter-project/LICENSE.md){:target="_blank"} included in your project LICENSE.md file (and copied over in your Dockerfile). This is **required** for every detection bot deployed to the network.
+You will also find the [Forta Detection Bot License](https://github.com/forta-network/forta-bot-sdk/blob/master/starter-project/LICENSE.md){:target="\_blank"} included in your project LICENSE.md file (and copied over in your Dockerfile). This is **required** for every detection bot deployed to the network.
 
 ## Configuration
 
@@ -25,14 +25,7 @@ A few configuration values must be set in your package.json in order to deploy:
 - `name` of your bot project should be specified
 - `description` should be a short human-readable description of what your bot does
 - `version` of your bot should also be set as well
-- `chainIds` of the blockchains that your bot will be scanning should be specified as an array of integers. You must specify at least one and up to as many as you need. The supported chain IDs are:
-    - 1 (Ethereum)
-    - 137 (Polygon)
-    - 56 (Binance Smart Chain)
-    - 43114 (Avalanche)
-    - 42161 (Arbitrum)
-    - 10 (Optimism)
-    - 250 (Fantom)
+- `chainIds` are **optional**, use this to shard your bot by the specified chains as an array of integers
 - `repository` is **optional**, but providing a link to your code helps build trust in your bot
 
 ## Deploying
@@ -46,12 +39,15 @@ npm run publish
 This will build a Docker image for your bot using the Dockerfile in your project folder and push it to an image repository where scan nodes can find it. A manifest will be generated for your bot (which includes a reference to the Docker image) and be published to the Bot Registry contract.
 
 !!! warning "Signing the manifest"
-    The bot manifest will need to be signed using your keyfile (located in ~/.forta), so **you will be prompted for the password** (unless you specified `keyfilePassword` in forta.config.json).
 
-When successfully deployed, you should see a message in your output similar to 
+        The bot manifest will need to be signed using your keyfile (located in ~/.forta), so **you will be prompted for the password** (unless you specified `keyfilePassword` in forta.config.json).
+
+When successfully deployed, you should see a message in your output similar to
+
 ```
-successfully added agent id 0x855b1556a45637abf05c63407437f6f305b4627c4361fb965a78e5731999c0c7 with manifest QmcWPhPQ3un47QpZKKJZxD5ih3TXgk91ehLeUw6we2ncYg
+successfully added bot id 0x855b1556a45637abf05c63407437f6f305b4627c4361fb965a78e5731999c0c7 with manifest QmcWPhPQ3un47QpZKKJZxD5ih3TXgk91ehLeUw6we2ncYg
 ```
+
 This message contains your bot ID (i.e. `0x855b1556a45637abf05c63407437f6f305b4627c4361fb965a78e5731999c0c7`) as well as your manifest IPFS reference (i.e. `QmcWPhPQ3un47QpZKKJZxD5ih3TXgk91ehLeUw6we2ncYg`). You can view the manifest by requesting it from any IPFS gateway (e.g. [`https://ipfs.io/ipfs/QmcWPhPQ3un47QpZKKJZxD5ih3TXgk91ehLeUw6we2ncYg`](https://ipfs.io/ipfs/QmcWPhPQ3un47QpZKKJZxD5ih3TXgk91ehLeUw6we2ncYg))
 
 ## Staking

docs/deposit-fort-vault.md

@@ -1,6 +1,8 @@
 # Deposit Your FORT in the Token Vault via Forta App
 
-The FORT Token Vault is a simple and streamlined way to contribute your FORT tokens to securing the Forta Network. The vault allows you to simply deposit FORT tokens into the vault and rest is taken care of for you. Start earning rewards for your contribution without having to choose and decide between different individual pools. 
+The FORT Vault is a simple and streamlined way to contribute your FORT tokens to securing the Forta Network. The vault allows you to simply deposit FORT tokens into the vault and rest is taken care of for you. Start earning rewards for your contribution without having to choose and decide between different individual pools. 
+
+<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/MWCCNRk5IbQ?si=oPr8g6thLLwe24Ab" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
 
 1. Make sure your FORT is on the Polygon network. If you have your FORT on Ethereum Mainnet, follow [these steps](https://docs.forta.network/en/latest/bridging-fort/) to bridge it to Polygon. 
 
@@ -28,6 +30,6 @@ After your approval transaction is confirmed, click the **Deposit** button and a
 
 ## Withdrawing from the FORT Token Vault and Claiming Rewards
 
-Initiating a withdrawal request from the FORT Token Vault will result in a percentage amount of FORT returned to you at the time of withdrawal based on the availability of liquidity in the vault. To claim the remaining FORT, you must wait the **10 day cooling off period** to initiate a withdrawal transaction for the remainder of your FORT tokens. 
+Initiating a withdrawal request from the FORT Vault will result in a percentage amount of FORT returned to you at the time of withdrawal based on the availability of liquidity in the vault. To claim the remaining FORT, you must wait the **10 day cooling off period** to initiate a withdrawal transaction for the remainder of your FORT tokens. 
 
 Rewards are automatically included in your total FORT deposit amount and will continue to grow.