Rate limiting and abuse prevention

One of the greatest security challenges in Web3 is the Sybil Attack: a single user spawning thousands of automated bots to drain native tokens or spam on-chain smart contracts.

When Socio3 V2 migrated to an ERC-4337 Account Abstraction design, we wanted to make the app 100% free for users. To achieve this, we set up two systems:

1. A Verifying Paymaster to sponsor transaction gas fees.
2. A POL Gas Faucet to gift new users native gas tokens to fund their tipping wallets.

Within hours of launching the faucet, bots attempted to drain the entire faucet contract. This lesson details the defensive patterns required to protect Web3 gateways from bot abuse.

1. The Faucet Rate Limiting Proxy

You should never allow a frontend client to request gas tokens directly from an on-chain faucet contract. If you do, bots will scan your frontend code, extract the payout trigger, and loop it programmatically.

In Socio3, faucet requests are proxied through a rate-limited Express endpoint (POST /api/faucet).

React Client ──▶ POST /api/faucet ──▶ Express Backend ──▶ Rate Limiter ──▶ Payout Transaction
                                                                 │
                                                       Checks Firestore for Cooldown

Here is the implementation:

// backend/routes/faucet.js
const express = require('express');
const { collection, query, where, getDocs, addDoc } = require('firebase/firestore');
const { db } = require('../config/firebase');
 
const router = express.Router();
const COOLDOWN_HOURS = 24;
 
router.post('/faucet', async (req, res) => {
  const { recipientAddress } = req.body;
 
  if (!recipientAddress || !recipientAddress.startsWith('0x')) {
    return res.status(400).json({ error: "Invalid recipient address" });
  }
 
  try {
    // 1. Query Firestore to check if this address has requested gas recently
    const faucetRef = collection(db, "faucet_requests");
    const q = query(
      faucetRef,
      where("address", "==", recipientAddress.toLowerCase()),
      where("timestamp", ">", Date.now() - COOLDOWN_HOURS * 60 * 60 * 1000)
    );
    
    const querySnapshot = await getDocs(q);
    if (!querySnapshot.empty) {
      return res.status(429).json({ error: "Faucet limit reached. Try again in 24 hours." });
    }
 
    // 2. Perform Faucet Payout (Proxying to Polygon Amoy faucet API)
    const payoutTx = await executePayout(recipientAddress);
 
    // 3. Record transaction in Firestore to enforce cooldown
    await addDoc(faucetRef, {
      address: recipientAddress.toLowerCase(),
      timestamp: Date.now(),
      txHash: payoutTx.hash
    });
 
    return res.status(200).json({ success: true, txHash: payoutTx.hash });
  } catch (error) {
    return res.status(500).json({ error: "Faucet transaction failed" });
  }
});

2. The Smart Contract Revert Trap (EOA Only)

A crucial architectural discovery in Socio3 V2 was that faucets must never send native tokens directly to a deployed Smart Account contract.

Here is why:

• Standard faucet transfers use a plain transaction with a fixed gas limit of 25,000 gas.
• If the recipient is an EOA (Externally Owned Account like MetaMask), the transfer consumes exactly 21,000 gas and succeeds.
• If the recipient is a Smart Account contract, the transfer invokes the contract's receive() or fallback() function. This delegates execution to the implementation contract, consuming >25,000 gas. The transaction reverts silently due to out-of-gas limits.

Faucet ──(25k Gas Transfer)──▶ MetaMask EOA (21k gas) ──────────▶ Success!
Faucet ──(25k Gas Transfer)──▶ Smart Account Contract (>25k gas) ──▶ Out of Gas (Revert)

The Design Solution: Always route faucet payouts to the user's EOA signer wallet (privyUserAddress). Once the EOA has funds, display a "Bridge to Smart Account" card in the UI, allowing the user to initiate a contract call to transfer the funds to their Smart Account.