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: 8080

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

# title of the faucet
faucetTitle: "Holesky PoW Faucet"

# url to image displayed on the startpage
faucetImage: "/images/fauceth_420.jpg"

# some additional html to show on the startpage
faucetHomeHtml: |
  <div class='pow-info'>
    <h5>What is a PoW Faucet?</h5>
    This is an Ethereum Faucet running on the Holesky Testnet.<br>
    To prevent malicious actors from exhausting all available funds or 
    accumulating enough Ether to mount long running spam attacks, 
    this faucet requires some mining work to be done in exchange for 
    free testnet funds.
  </div>
  <div class='pow-info'>
    <h5>How does this work?</h5>
    Just enter your ETH Address and start mining. 
    When you've collected enough ETH, stop mining and claim your rewards.
  </div>
  <div class='pow-info'>
    <h5>How to help the faucet?</h5>
    Replenish the faucet by sending funds you don't need anymore to:<br>
    {faucetWallet}
  </div>

# 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
ethTxGasLimit: 21000

# use legacy (non-eip1559) transaction type
# true: Type 0 (Legacy Transactions), false: Type 2 (EIP1559 Transactions)
ethLegacyTx: false

# 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:

  ## Captcha Protection
  captcha:
    # enable / disable captcha protection
    enabled: true

    # captcha provider
    # hcaptcha:  HCaptcha (https://hcaptcha.com)
    # recaptcha: ReCAPTCHA (https://developers.google.com/recaptcha)
    # turnstile: Turnstile (https://www.cloudflare.com/products/turnstile)
    provider: "hcaptcha"

    # captcha site key
    siteKey: "00000000-0000-0000-0000-000000000000"

    # captcha secret key
    secret: "0xCensoredHCaptchaSecretKey"

    # require captcha to start a new session (default: false)
    checkSessionStart: false

    # require captcha to start claim payout (default: false)
    checkBalanceClaim: false
  
  ## ENS Name
  ensname:
    enabled: true

    # RPC Host for ENS name resolver (mainnet)
    rpcHost: "https://rpc.flashbots.net/"
    # Custom ENS Resolver contract address
    #ensAddr: "0x"
    
    # require ENS name
    required: false

  ## 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

    # require minimal erc20 token balances on mainnet wallet
    minErc20Balances: []
      #- name: "TestToken"
      #  address: "0x94373a4919B3240D86eA41593D5eBa789FEF3848" # WETH9 on holesky
      #  decimals: 18
      #  minBalance: 10000000000000000 # 0.01 WETH

  
  ## 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
    
    concurrencyLimit: 1 # only allow 1 concurrent session (sessions in 'running' state at the same time for the same ip / 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 / nickminer

    # 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

    skipProxyCheckScore: 0  # skip proxy check for IP when wallet score exceeds this
    skipHostingCheckScore: 0 # skip hosting check for IP when wallet score exceeds this
    allowGuestRefresh: false # allow passport refresh without active session (ie. refresh for skippimg hosting/proxy check)
    guestRefreshCooldown: 0 # refresh cooldown without active session (default to refreshCooldown if 0)

    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

  ## Zupass protection
  zupass:
    enabled: false
    zupassUrl: "https://zupass.org/"
    zupassApiUrl: "https://api.zupass.org/"
    redirectUrl: "https://sepolia-faucet.pk910.de/"
    event:
      name: "Devconnect 2023"
      eventIds:
        - "a1c822c4-60bd-11ee-8732-763dbf30819c" # Devconnect Cowork Space
    verify:
      signer: ["05e0c4e8517758da3a26c80310ff2fe65b9f85d89dfc9c80e6d0b6477f88173e", "29ae64b615383a0ebb1bc37b3a642d82d37545f0f5b1444330300e4c4eedba3f"]
    requireLogin: false
    concurrencyLimit: 2
    grants:
      - limitAmount: 100000000000000000000 # 100 ETH
        duration: 86400
        skipModules: ["recurring-limits"]
        rewardFactor: 2
      - limitCount: 1
        duration: 86400
        rewardFactor: 2
        skipModules: ["recurring-limits", "pow", "faucet-outflow", "faucet-balance", "ipinfo"]
    loginLogo: "/images/zupass_logo.jpg"
    loginLabel: "DevConnect attendee? Login with your Ticket."
    userLabel: "Authenticated with DevConnect Ticket."
    infoHtml: |
      Benefits of authenticating with your devconnect ticket:<br>
      <ul>
        <li>Request funds without mining (once a day)</li>
        <li>Skip IP based limitations</li>
        <li>Mine with double rewards (up to 100ETH/day)</li>
      </ul>



### 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."


  
### Advanced WebServer config

# allow external sites embedding this faucet
corsAllowOrigin:
#- "*"  # allow all - for development only!
#- "https://faucets.pk910.de"

### 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"

# build SEO optimized index.seo.html and deliver as index page
# the blank loader page just looks bad when parsed by search engines
buildSeoIndex: true

# some additional meta tags to add to the SEO optimized page
buildSeoMeta:
  keywords: "powfaucet,faucet,ethereum,ethereum faucet,evm,eth,pow"

resultSharing:
  preHtml: |
    <div class="sh-opt">
      Did you like the faucet? Give that project a 
      <iframe src="https://ghbtns.com/github-btn.html?user=pk910&repo=PoWFaucet&type=star&count=true" frameborder="0" scrolling="0" width="150" height="20" title="GitHub"></iframe>
    </div>
  #postHtml: |
  #  <div class="sh-opt">
  #  </div>
  caption: "Or support this faucet by sharing your result with a "

  # result sharing buttons
  twitter: "Boom! Just got {amount} Holesky ETH from {url} (Mining for {duration} with {hashrate} H/s) #holesky #faucet"
  mastodon: "Boom! Just got {amount} Holesky ETH from {url} (Mining for {duration} with {hashrate} H/s)"