Bot Protection

Background

The Bot Protection contract was created for dApps looking to protect their contracts from being botted.

Vital for applications on zero-gas fee or low-gas fee chains, Bot Protection is built on-top of OpenZeppelin and Authority.

The contract brings with it a simple, yet flexible set of limits and optional blacklisting capabilities that enables a smart contract to protect itself from being “botted”.

“Botted” - the act of a bots being used to simulate user action.

Installation

NPM

npm add @dirtroad/sediment

Yarn

yarn add @dirtroad/sediment

pnpm

pnpm add @dirtroad/sediment

Using Bot Protection

RewardToken.sol

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

import "@openzeppelin/contracts/token/ERC20/ERC20.sol";
import "@dirtroad/sediment/contracts/authority/Authority.sol";

contract RewardToken is ERC20, Authority {

    constructor(address defaultAdmin, address minter) ERC20("Reward Token", "RTKN") {
        _grantRole(DEFAULT_ADMIN_ROLE, _msgSender());
        _grantRole(MINTER_ROLE, minter);
    }

    function mint(address to, uint256 amount) public onlyRole(MINTER_ROLE) {
        _mint(to, amount);
    }
}

DailyReward.sol

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

import "@openzeppelin/contracts/token/ERC20/IERC20.sol";
import "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
import "@dirtroad/sediment/contracts/security/BotProtection.sol";

contract DailyReward is BotProtection {

    using SafeERC20 for IERC20;

    IERC20 public rewardToken;

    constructor(IERC20 _rewardToken) BotProtection(ProtectionLevel.EXTREME, true) {
        rewardToken = _rewardToken;
    }

    function claim() external checkForBot(_msgSender()) {
        rewardToken.mint(_msgSender(), 100 * 10 ** 18);
    }
}

API

Solidity API

BotProtection

Contract for rate limiting functionality based on function calls.

ProtectionLevel

enum ProtectionLevel {
  OFF,
  LOW,
  MEDIUM,
  HIGH,
  EXTREME
}

Limit

struct Limit {
  uint64 lastRequest;
  uint8 strikes;
  bool isBlacklisted;
}

cooldown

uint64 cooldown

level

enum BotProtection.ProtectionLevel level

strikes

uint8 strikes

useBlacklist

bool useBlacklist

limits

mapping(address => struct BotProtection.Limit) limits

checkForBot

modifier checkForBot(address addr)

Modifier to check for bot activity and apply rate limiting.

Parameters

Name	Type	Description
addr	address	The address to check for bot activity.

RemoveFromBlacklist

event RemoveFromBlacklist(address[] addresses)

SetProtectionLevel

event SetProtectionLevel(enum BotProtection.ProtectionLevel protectionLevel)

ToggleBlacklist

event ToggleBlacklist(bool enabled)

constructor

constructor(enum BotProtection.ProtectionLevel _level, bool _useBlacklist) public

Constructor to initialize the contract with protection level and blacklist usage.

Parameters

Name	Type	Description
_level	enum BotProtection.ProtectionLevel	The initial protection level.
_useBlacklist	bool	Flag indicating whether to use blacklist.

_setProtectionLevel

function _setProtectionLevel(enum BotProtection.ProtectionLevel protectionLevel) internal virtual

Internal function to set protection level parameters.

Parameters

Name	Type	Description
protectionLevel	enum BotProtection.ProtectionLevel	The protection level to set.

removeFromBlacklist

function removeFromBlacklist(address[] addresses) public virtual

Function to remove addresses from blacklist.

Parameters

Name	Type	Description
addresses	address[]	The addresses to remove from blacklist.

setProtectionLevel

function setProtectionLevel(enum BotProtection.ProtectionLevel protectionLevel) public virtual

Function to set the protection level.

Parameters

Name	Type	Description
protectionLevel	enum BotProtection.ProtectionLevel	The protection level to set.

toggleBlacklist

function toggleBlacklist() public virtual

Function to toggle the blacklist on/off.

Default Levels

These levels can be overwritten by overriding the the _setProtectionLevel function.

Level	Cooldown	Strikes
OFF	0	0
LOW	60 seconds	5
MEDIUM	5 minutes	5
HIGH	60 minutes	5
EXTREME	24 hours	3