Optimism QuickNode Endpoint Armor

What is Endpoint Armor?

Endpoint Armor is a security add-on developed by QuickNode, which allows you to restrict your QuickNode endpoint to specific methods and set rate limits for each method. Endpoint Armor guards your endpoint against exploitation in public-facing uses, such as operating a front-end website for a decentralized app. It does this by providing a secure URL that is rate limited and configurable to your specific usage. You can also set global rate limits for the entire endpoint, as well as rate limits per unique visitor.

Endpoint Armor's Primary Features

Endpoint Rate Limits: These are global rate limits that apply to the entire endpoint, providing an overarching control mechanism for managing traffic to the endpoint.
Visitor Rate Limits: These limits are specific to each unique visitor to a website, ensuring that rate limits apply individually to different users accessing the endpoint.
Method Limitations: This feature allows only the methods explicitly listed in this setting, with the option to set either method-specific rate limits or global rate limits.

Info

Please note that the typical QuickNode URLs with authentication tokens will not be affected by this configuration and can still be used normally. Only the secure URL generated by Endpoint Armor will have these settings applied.

Ideal Security Settings

When enabling Endpoint Armor on an endpoint, ensure that token-based authentication is enabled, as the primary security measure. Please be aware that disabling token-based authentication will result in Endpoint Armor not functioning as intended. To maintain a seamless and effective security setup, please don't make changes to other security page settings, as doing so may impact the proper functioning of Endpoint Armor.

Configuration Structure

The configuration JSON object consists of several keys, each representing different aspects of rate limiting and method access control.

endpointRateLimits

endpointRateLimits key specifies the global rate limits for the entire endpoint. These limits are applied irrespective of the individual method or visitor, providing an overarching control mechanism for managing the traffic to the endpoint. The endpointRateLimits can be specified in the following ways (all are optional):

reqPerHour: Defines the maximum number of requests that can be made to the endpoint in an hour.
reqPerMinute: Sets the maximum number of requests allowed per minute.
reqPerSecond: Limits the number of requests to a per-second maximum.

endpointRateLimits Configuration Example

{
    "methods": {
        "eth_call": {
            "contractAllowlist": [
                "0xdAC17F958D2ee523a2206206994597C13D831ec7",
                "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
            ]
        },
        "eth_chainId": "enabled",
        "eth_getLogs": {
            "latestBlocks": 100
        },
        "eth_gasPrice": "enabled",
        "eth_blockNumber": {
            "reqPerSecond": 1
        }
    },
    "endpointRateLimits": {
        "reqPerHour": 1000,
        "reqPerMinute": 20,
        "reqPerSecond": 1
    }
}

visitorRateLimits

visitorRateLimits defines the rate limits applied per unique visitor to a website. These limits are particularly relevant when requests include headers from a browser, indicating they are originating from individual users as opposed to server-side processes. The visitorRateLimits can be specified in the following ways (all are optional):

reqPerHour: Maximum number of requests allowed per hour.
reqPerMinute: Maximum number of requests allowed per minute.
reqPerSecond: Maximum number of requests allowed per second.

visitorRateLimits Configuration Example

{
    "methods": {
        "eth_call": {
            "contractAllowlist": [
                "0xdAC17F958D2ee523a2206206994597C13D831ec7",
                "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
            ]
        }
    },
    "visitorRateLimits": {
        "reqPerMinute": 10
    }
}

methods

methods object is an allowlist of methods that are permitted for the endpoint. Each key within this object corresponds to a valid method name. The value associated with each method key can be a string "enabled" to simply enable the method, or an object specifying various rate limits. For a method to be used on the endpoint, it must be specified in this object. For each method, the following rate limits can be specified (all are optional):

reqPerHour: Maximum number of requests allowed per hour.
reqPerMinute: Maximum number of requests allowed per minute.
reqPerSecond: Maximum number of requests allowed per second.

Methods Configuration Example 1

{
  "methods": {
    "eth_chainId": {
      "reqPerHour": 1000,
      "reqPerMinute": 100,
      "reqPerSecond": 10
    }
  }
}

In this example, the method eth_chainId is allowed with specific rate limits set for requests per hour, minute, and second.

Methods Configuration Example 2

{
  "methods": {
    "eth_chainId": "enabled"
  }
}

In this example, the method eth_chainId is allowed with no rate limits.

Method-Specific Options

There are some methods that have specific options that can be set in addition to the request limits. These are all optional. The following methods have specific options that can be set:

eth_call:
- contractAllowlist: An array of contract addresses that can be called. Only the contracts specified in this array can be called with eth_call when this option is set.
eth_getLogs and eth_getBlockByNumber:
- latestBlocks: The limit of blocks that can be queried from the latest block. The latest block is determined by eth_blockNumber for EVM. For example, if the latest block number is 1000, and latestBlocks is set at 100, any range of blocks above block 900 (inclusive) can be queried.
- minBlockNumber: The lowest block number that can be queried. For example, if minBlockNumber is set to 1000, any block number below 1000 (inclusive) cannot be queried.
- maxBlockNumber: The highest block number that can be queried. For example, if maxBlockNumber is set to 1000, any block number above 1000 (inclusive) cannot be queried.

Method-Specific Options Configuration Example

{
  "methods": {
    "eth_getBlockByNumber": {
      "minBlockNumber": 18000000
    },
    "eth_getLogs": {
      "reqPerSecond": 10,
      "latestBlocks": 100,
    },
    "eth_call": {
      "contractAllowlist": ["0x2106C00Ac7dA0A3430aE667879139E832307AeAa"],
    },
  },
}

To learn more about how to use Endpoint Armor, refer to our comprehensive guide on Endpoint Armor.

We ❤️ Feedback!

If you have any feedback or questions about this documentation, let us know. We'd love to hear from you!