NotABot

NotABot Integration Guide

Integrate a human check with one contract call. NotABot aggregates Worldcoin, Gitcoin Passport, PoH, and BrightID behind a stable oracle interface for DEXes, L1/L2 chains, and dApps.
Base Sepolia
Status Sepolia
View-only oracle
One contract call

Quick Start

1. Clone & Copy

git clone https://github.com/ArturInspector/notabot.git
cp packages/hardhat/contracts/base/HumanityProtected.sol .
cp packages/hardhat/contracts/interfaces/IHumanityOracle.sol .

2. Inherit & Use

import "./HumanityProtected.sol";

contract MyGame is HumanityProtected {
  constructor() HumanityProtected(ORACLE_ADDR) {}
  function play() external onlyHuman { }
}

Solidity Integration

import "./HumanityProtected.sol";

// MainAggregator on Status Network
address constant ORACLE = 0x8Cec9277d761f947e29EBeACc4035DDCDB10c2BD;

contract YourContract is HumanityProtected {
    constructor() HumanityProtected(ORACLE) {}
    
    // Only verified humans can call
    function protectedFunction() external onlyHuman {
        // your logic
    }
    
    // Require minimum trust score (2+ verifications)
    function premiumFeature() external minTrustScore(2) {
        // requires 2+ sources
    }
}

Usage Examples

contract GameNFT is ERC721, HumanityProtected {
  function mint() external onlyHuman {
    _safeMint(msg.sender, nextTokenId++);
  }
}

API Reference

onlyHuman

modifier onlyHuman
Restricts function to verified humans only. Reverts if caller has 0 verifications.
Example
function mint() external onlyHuman {
  _mint(msg.sender);
}

minTrustScore

modifier minTrustScore(uint256)
Requires minimum number of verifications. Trust score = HMT token balance.
Example
function premium() external minTrustScore(2) {
  // requires 2+ verifications
}

Math & Security

Bayesian Aggregation

NotABot uses Bayes' theorem to combine probabilities from multiple independent verification sources. Each source provides an independent estimate of the probability that a user is human.
Formula:
P(Human∣E1,E2,...,En)=1−∏i=1n(1−Pi)P(Human | E_1, E_2, ..., E_n) = 1 - \prod_{i=1}^{n}(1 - P_i)
Where PiP_i is the confidence score from source ii, calculated as Pi=TPRiTPRi+FPRiP_i = \frac{TPR_i}{TPR_i + FPR_i}.
Example:
If Worldcoin (99.9%), Gitcoin (90.9%), and PoH (79.5%) all verify a user:
Pfinal=1−(1−0.999)(1−0.909)(1−0.795)=99.999%P_{final} = 1 - (1-0.999)(1-0.909)(1-0.795) = 99.999\%

Attack Detection

The contract automatically detects suspicious patterns that may indicate Sybil attacks:
  • Rapid verification bursts: More than 5 verifications in 24 hours
  • Low quality scores: All verifications from Gitcoin with score < 30
  • Pattern analysis: Cross-source correlation detection
On-chain Events:
event AnomalyDetected(address indexed user, string reason);
event AttackConfirmed(uint8 indexed sourceId, address indexed user);

Adaptive Confidence Updates

When an attack is confirmed, the system automatically updates the False Positive Rate (FPR) for that source, which adjusts its confidence score:
Update Formula:
FPRnew=confirmedAttackstotalVerificationsFPR_{new} = \frac{confirmedAttacks}{totalVerifications}
confidencenew=TPRTPR+FPRnewconfidence_{new} = \frac{TPR}{TPR + FPR_{new}}
This creates a self-improving system where sources with higher attack rates automatically receive lower confidence scores, making the system more resilient over time.
Example:
If a source has 1000 verifications and 10 confirmed attacks:
FPR=101000=1%FPR = \frac{10}{1000} = 1\%
confidence=0.950.95+0.01=98.96%confidence = \frac{0.95}{0.95 + 0.01} = 98.96\%

Network & Gas

Networks: Status Network Sepolia (1660990954) • Base Sepolia (84532)
MainAggregator (same on both): 0x8Cec9277d761f947e29EBeACc4035DDCDB10c2BD
Check Gas: ~2,300 gas
Cost: ~$0.0001 per check
Type: View call (read-only)