faucet-config.example.yaml

# PoWFaucet config (example)
version: 2

### General Settings

# faucet database (defaults to local sqlite)
database:
  driver: "sqlite"
  file: "faucet-store.db"

# logfile for faucet events (comment out for no logging)
faucetLogFile: "faucet-events.log"

# path to file to write the process pid to (comment out to disable)
faucetPidFile: "faucet-pid.txt"

# faucet http/ws server port
serverPort: 8888

# number of http proxies in front of this faucet
httpProxyCount: 0

# random secret string that is used by the faucet to "sign" session data, so sessions can be restored automatically by clients when faucet is restarted / crashed
# use a random string and do not share / reuse it anywhere. Everyone knowing this secret is theoretically able to claim rewards from the faucet without mining.
faucetSecret: "RandomStringThatShouldBeVerySecret!"

# ETH execution layer RPC host
#ethRpcHost: "http://127.0.0.1:8545/"
ethRpcHost: "https://rpc.holesky.ethpandaops.io"

# faucet wallet private key (hex, without 0x prefix)
ethWalletKey: "feedbeef12340000feedbeef12340000feedbeef12340000feedbeef12340000"

# EVM chain id (null for auto-detect from RPC)
ethChainId: null

# symbol (short name) of the coin that can be mined
faucetCoinSymbol: "HolETH"

# type of coin that can be mined
# native = native coin (ETH)
# erc20 = ERC20 token
faucetCoinType: "native"

# coin contract address (only for faucetCoinType = erc20)
#faucetCoinContract: "0x94373a4919B3240D86eA41593D5eBa789FEF3848" # WETH9 on holesky

# transaction gas limit
# use 21000 to prevent transactions to contracts, null for dynamic calculation
ethTxGasLimit: 21000

# max transaction gas fee (in wei)
# used as limit for legacy transactions (faucet won't build transactions with higher gas price)
ethTxMaxFee: 100000000000 # 100 gwei

# max transaction priority fee (in wei)
ethTxPrioFee: 2000000000 # 2 gwei

# max number of unconfirmed transactions to create simultaneously
ethMaxPending: 12

# queue transactions and wait for funding when faucet is out of funds (show "No Funds" error when false)
ethQueueNoFunds: true

# link to eth transaction explorer with {txid} as placeholder for transaction id or null for no link
ethTxExplorerLink: "https://holesky.etherscan.io/tx/{txid}"

# min/max drop amount (max is the default if no module lowers it)
maxDropAmount: 1000000000000000000 # 1 ETH
minDropAmount: 10000000000000000 # 0.01 ETH

# maximum session time (from start till payout)
# only relevant if one of the enabled protection mechanisms introduces a session delay (eg. mining)
sessionTimeout: 43200 # 12h

# session cleanup time
# session data will be removed from the faucet DB after that time
sessionCleanup: 2592000 # 30 days

# session save time
# how often session updates will be written to DB
sessionSaveTime: 120

### Protection mechanisms
modules:
  ## IP-Info module
  ipinfo:
    # enable / disable IP-Info protection
    enabled: true

    # ip info lookup api url (default: http://ip-api.com/json/{ip}?fields=21155839)
    apiUrl: "http://ip-api.com/json/{ip}?fields=21155839"

    # ip info caching time
    cacheTime: 86400 # 1 day

    # require valid ip info (throw error if lookup failed)
    required: false

    # ip info based restrictions
    restrictions:
      # percentage of drop amount if IP is in a hosting range (default: 100), 0 to block entirely
      hosting: 10

      # percentage of drop amount if IP is in a proxy range (default: 100), 0 to block entirely
      proxy: 10

      # percentage of drop amount if IP is from given country code (DE/US/...), 0 to block entirely
      #US: 100

    # ip info pattern based restrictions
    restrictionsPattern:
      "^.*Tencent Cloud.*$": 10
      "^.*UCLOUD.*$": 10
      "^.*Server Hosting.*$": 10
      "^.*SCloud.*$": 10

  ethinfo:
    # enable / disable max balance protection
    enabled: true

    # check balance and deny session if balance exceeds the limit (in wei)
    maxBalance: 50000000000000000000 # 50 ETH

    # deny sessions for contract addresses
    denyContract: true

  ## Faucet Balance module
  faucet-balance:
    # enable / disable faucet balance protection
    enabled: true

    # reward restriction based on faucet wallet balance. lowest value applies
    fixedRestriction:
      1000000000000000000000: 90 # 90% if lower than 1000 ETH
      100000000000000000000: 10 # 10% if lower than 100 ETH

    # dynamic reward restriction based on faucet balance
    # alternative to fixedRestriction, if both are set, the lower factor gets applied
    # limits the rewards linearly according to the faucet balance (100% >= targetBalance, 0% <= spareFundsAmount)
    dynamicRestriction:
      targetBalance: 1100000000000000000000 # no restriction with faucet balance > 1100 ETH

  ## Faucet Outflow module
  faucet-outflow:
    # enable / disable faucet outflow protection
    enabled: true

    # dynamic reward restriction based on faucet outflow
    # alternative to static faucetBalanceRestrictedReward
    # limits the rewards according to the faucet outflow
    # the faucet keeps track of the outflow via a internal "outflow balance".
    # amount/duration wei are added to that balance every second.
    # whenever some reward is mined, it is subtracted from that balance.
    # So, whenever the balance gets negative, there is more mining activity than the allowed outflow and the reward is reduced linearly down to 0% when it reaches lowerLimit.
    # Whenever the balance gets positive, there is less mining activity than allowed. The positive balance is a 'buffer' for activity spikes, anything above upperLimit gets burned.

    # limit outflow to 1000ETH per day
    amount: 1000000000000000000000 # 1000 ETH
    duration: 86400 # 1 day
    # outflow balance limits
    lowerLimit: -500000000000000000000 # -500 ETH (when outflow balance gets smaller or equal to this, the reward will be 0%)
    upperLimit: 500000000000000000000 # 500 ETH

  ## Github login protection
  github:
    # enable / disable github login protection
    enabled: false

    # github api credentials
    appClientId: "" # client id from github app
    appSecret: "" # app secret from github app

    # authentication timeout
    authTimeout: 86400

    # github account checks
    checks:
      - minAccountAge: 604800 # min account age (7 days)
        minRepoCount: 10 # min number of repositories (includes forked ones)
        minFollowers: 10 # min number of followers
        minOwnRepoCount: 5 # min number of own repos (non-forked)
        minOwnRepoStars: 5 # min number of stars on own repos (non-forked)
        required: true # require passing this check or throw error
        message: "Your github account does not meet the minimum requirements" # custom error message

      - minFollowers: 50
        minOwnRepoCount: 10
        minOwnRepoStars: 1000
        rewardFactor: 2 # double reward if account looks trustful

    # recurring restrictions based on github account
    restrictions:
      # max 10 sessions / 10 ETH per day for each github account
      - limitCount: 10
        limitAmount: 10000000000000000000 # 10 ETH
        duration: 86400 # 1 day

  ## Mainnet Wallet module
  mainnet-wallet:
    # enable / disable mainnet wallet protection
    enabled: false

    # RPC host for mainnet
    rpcHost: "https://rpc.flashbots.net/"

    # require minimum balance on mainnet wallet
    minBalance: 10000000000000000 # 0.01 ETH

    # require minimum number of transactions from mainnet wallet (nonce count)
    minTxCount: 5

  ## Recurring Limits module
  recurring-limits:
    # enable / disable recurring limits protection
    enabled: true

    limits: # array of individual limits, which all need to be passed
      - limitCount: 10
        limitAmount: 10000000000000000000 # 10 ETH
        duration: 86400 # 1 day
      - limitCount: 20
        limitAmount: 20000000000000000000 # 20 ETH
        duration: 172800 # 2 days
        byAddrOnly: true

  ## Concurrency Limit module
  concurrency-limit:
    # enable / disable concurrency limit
    enabled: true

    # Concurrency limits are checked one after another
    concurrencyLimitByIP: 1 # only allow 1 concurrent session (sessions in 'running' state at the same time for the same ip)
    concurrencyLimitByUserAndTargetAddress: 1 # only allow 1 concurrent session (sessions in 'running' state at the same time for the same userId + target addr)

    byAddrOnly: false # only check concurrency by target address
    byIPOnly: false # only check concurrency by IP address
    #messageByAddr: "" # custom error message when limit is exceeded by same target address
    #messageByIP: "" # custom error message when limit is exceeded by same IP address

  ## Proof of Work (mining) protection
  pow:
    # enable / disable PoW protection
    enabled: true

    # reward amount per eligible hash (in wei)
    #powShareReward: 12500000000000000  # 0.0125
    powShareReward: 2000000000000000 # 0.002 ETH

    # penalty for not responding to a verification request (percent of powShareReward)
    # shouldn't be too high as this can happen regularly in case of connection loss or so
    verifyMinerMissPenaltyPerc: 10 # 10% of powShareReward

    # reward for responding to a verification request in time (percent of powShareReward)
    # some extra reward for slow miners
    # comment out to disable rewards for verification requests
    verifyMinerRewardPerc: 15 # 15% of powShareReward

    # maximum mining session time (in seconds)
    powSessionTimeout: 18000 # 5h

    # maximum number of seconds a session can idle until it gets closed
    powIdleTimeout: 1800 # 30min

    # maximum allowed mining hashrate (will be throttled to this rate when faster)
    powHashrateSoftLimit: 1000 # soft limit (enforced client side)
    powHashrateHardLimit: 1100 # hard limit (reject shares with too high nonces)

    # number of 0-bits the scrypt hash needs to start with to be eligible for a reward
    powDifficulty: 11

    # mining algorithm to use
    powHashAlgo: "argon2" # scrypt / cryptonight / argon2

    # pow module settings have been trimmed for readability.
    # you can find all available settings on https://github.com/pk910/PoWFaucet/wiki/Operator-Wiki#module-pow

  ## Passport protection
  passport:
    enabled: false
    scorerApiKey: "" # Gitcoin Passport Scorer API Key
    trustedIssuers:
      - "did:key:z6MkghvGHLobLEdj1bgRLhS4LPGJAvbMA1tn2zcRyqmYU5LC" # Gitcoin Passport
    passportCachePath: "passport-cache"

    refreshCooldown: 300 # allow refreshing every 5mins
    cacheTime: 86400 # cache passports for 1 day (does not affect manual refreshing)

    stampDeduplicationTime: 604800 # allow reusing a stamp in another passport after 7 days

    boostFactor:
      1: 1.1 # x1.1 if score >= 1
      5: 1.5 # x1.5 if score >= 5
      10: 2 # x2 if score >= 10
    stampScoring:
      "Google": 1
      "Twitter": 1
      "Ens": 2
      "GnosisSafe": 2
      "Poh": 4
      "POAP": 1
      "GitPOAP": 1
      "Facebook": 1
      "FacebookFriends": 1
      "FacebookProfilePicture": 1
      "Brightid": 8
      "Github": 1
      "Coinbase": 1
      "FiveOrMoreGithubRepos": 1
      "TenOrMoreGithubFollowers": 2
      "FiftyOrMoreGithubFollowers": 4
      "ForkedGithubRepoProvider": 1
      "StarredGithubRepoProvider": 1
      "Linkedin": 1
      "Discord": 1
      "TwitterTweetGT10": 1
      "TwitterFollowerGT100": 1
      "TwitterFollowerGT500": 2
      "TwitterFollowerGTE1000": 3
      "TwitterFollowerGT5000": 5
      "SelfStakingBronze": 1
      "SelfStakingSilver": 1
      "SelfStakingGold": 1
      "CommunityStakingBronze": 1
      "CommunityStakingSilver": 1
      "CommunityStakingGold": 1
      "ClearTextSimple": 1
      "ClearTextTwitter": 1
      "ClearTextGithubOrg": 1
      "SnapshotProposalsProvider": 1
      "SnapshotVotesProvider": 1
      "EthGasProvider": 1
      "FirstEthTxnProvider": 1
      "EthGTEOneTxnProvider": 1
      "GitcoinContributorStatistics#numGrantsContributeToGte#1": 1
      "GitcoinContributorStatistics#numGrantsContributeToGte#10": 1
      "GitcoinContributorStatistics#numGrantsContributeToGte#25": 2
      "GitcoinContributorStatistics#numGrantsContributeToGte#100": 2
      "GitcoinContributorStatistics#totalContributionAmountGte#10": 1
      "GitcoinContributorStatistics#totalContributionAmountGte#100": 2
      "GitcoinContributorStatistics#totalContributionAmountGte#1000": 2
      "GitcoinContributorStatistics#numRoundsContributedToGte#1": 1
      "GitcoinContributorStatistics#numGr14ContributionsGte#1": 1
      "GitcoinGranteeStatistics#numOwnedGrants#1": 1
      "GitcoinGranteeStatistics#numGrantContributors#10": 1
      "GitcoinGranteeStatistics#numGrantContributors#25": 1
      "GitcoinGranteeStatistics#numGrantContributors#100": 2
      "GitcoinGranteeStatistics#totalContributionAmount#100": 1
      "GitcoinGranteeStatistics#totalContributionAmount#1000": 2
      "GitcoinGranteeStatistics#totalContributionAmount#10000": 4
      "GitcoinGranteeStatistics#numGrantsInEcoAndCauseRound#1": 1
      "gtcPossessionsGte#100": 2
      "gtcPossessionsGte#10": 1
      "ethPossessionsGte#32": 1
      "ethPossessionsGte#10": 1
      "ethPossessionsGte#1": 1
      "NFT": 1
      "Lens": 1
      "ZkSync": 1

### Fund Management

# minimum balance to keep in the faucet wallet (in wei)
spareFundsAmount: 100000000000000000 # 0.1 ETH

# minimum balance to show the empty faucet error message
noFundsBalance: 1000000000000000000 # 1 ETH

# minimum balance to show the low funds warning
lowFundsBalance: 10000000000000000000 # 10 ETH

# low faucet balance warning message / false to disable the warning
lowFundsWarning: "The faucet is running out of funds! Faucet Balance: {1}"

# empty faucet error message / false to disable the error
noFundsError: "Sorry, the faucet is out of funds :("

# RPC unreachable error message / true to show the generic message / false to disable the error
rpcConnectionError: "The Faucet is currently not working properly (RPC error)"

# prevent creation of new sessions (used for maintenance)
#denyNewSessions: "Sorry, the faucet is currently in maintenance mode. Please try again later."

# Gitcoin claimer settings
gitcoinClaimerEnabled: false
gitcoinApiToken: "example.value"
gitcoinScorerId: 7833
gitcoinMinimumScore: 3

### Automatic wallet refill

# refill contract options
# advanced configuration to secure the faucet funds via a separate vault contract
# the faucet tries to refill its wallet balance from the vault contract when it gets empty
# see contract code in docs folder
ethRefillContract:
  #contract: "0xA5058fbcD09425e922E3E9e78D569aB84EdB88Eb"
  #abi: '[{"inputs":[{"internalType":"address","name":"addr","type":"address"}],"name":"getAllowance","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"uint256","name":"amount","type":"uint256"}],"name":"withdraw","outputs":[],"stateMutability":"nonpayable","type":"function"}]'
  #allowanceFn: "getAllowance"
  #withdrawFn: "withdraw"
  #withdrawGasLimit: 300000
  #checkContractBalance: true
  #contractDustBalance: 1000000000000000000  # 1 ETH
  #triggerBalance: 1100000000000000000000  # 1100 ETH
  #cooldownTime: 5430 # 1.5h + 30sec
  #requestAmount: 125000000000000000000 # 125 ETH

### Other Settings

# print faucet stats to log interval (10min default)
#faucetLogStatsInterval: 600

# faucet stats config (comment out to disable stats)
faucetStats:
  # faucet stats file
  logfile: "faucet-stats.log"