Token Economy Platform
A complete token economy on Base, upgradeable ERC-20, holder dashboard, admin console, and chain-indexing backend.
The platform is a complete token economy on Base, Ethereum's L2: an upgradeable ERC-20 smart contract with a fixed 1,000,000,000-token cap, a public website with a login-gated holder dashboard, a role-based admin console, and an indexing backend that keeps everything in sync with the chain. We delivered the full stack, smart contracts, backend API, two frontends, and documentation, as a pnpm/Turborepo monorepo of five independently deployable workspaces.
Everyday users register with email, connect a browser wallet, claim a one-time sign-up reward, and buy tokens two ways: at the contract's fixed price or at market through a built-in Uniswap V2 swap with live quotes and managed allowances. The operating team gets a separate admin application for reward distribution, Uniswap liquidity management, contract settings, and transaction oversight, with every sensitive action written to an audit log.
Because a blockchain is a poor database for user-facing screens, the platform maintains its own indexed view of on-chain activity. The chain remains the source of truth, balances, supply, and claim status are always re-read from the contract, while Firestore stores a validated, deduplicated transaction history for fast dashboards. A committed deployment record documents the contract's deployment to Base mainnet.
Four deliverables that must agree with each other
Launching a branded token is not one deliverable but four. The token contract has to enforce economics, a hard supply cap, controlled distribution, purchase rules, that cannot be patched after launch without an upgrade path. Everyday users need to buy, hold, and withdraw tokens without understanding gas, allowances, or block confirmations.
The operating team needs to distribute rewards, manage a Uniswap liquidity pool, and change platform parameters with accountability for every action. And the platform needs its own indexed view of on-chain activity that stays truthful to the chain, all under an added constraint visible throughout the code: it had to run reliably on free-tier RPC infrastructure, where providers cap how much chain history can be read per request.
Chain as truth, Firestore as the read model
We structured the system as a monorepo with hard app boundaries, contracts, backend, user web app, admin SPA, and docs site, with shared internal packages for the contract ABI and user-facing error messages. Balances and supply figures are always re-read from the contract, while Firestore stores an indexed copy of transaction history; a validation endpoint decodes each transaction receipt and refuses anything that did not actually touch the token contract or the configured Uniswap router.
Upgradeability was introduced deliberately: the platform shipped first on a conventional ERC-20 with role-based access control, then moved to a transparent-proxy upgradeable contract, with scripted ownership transfer and a handoff-state inspection tool for passing control to the client's wallet safely. Admin actions follow a split trust model: contract-changing operations are signed from the administrator's own connected wallet, which must hold the on-chain role, while the server holds a key only for the optional, isolated automated reward queue.
Contract, dashboard, console, and automation
The token is a capped-supply ERC-20 built on OpenZeppelin, upgradeable behind a transparent proxy with Permit, Votes, FlashMint, Burnable, and Pausable extensions. Its mechanics implement the platform's economy directly on-chain: a payable fixed-price purchase function, a strictly one-per-wallet sign-up reward minted under the supply cap, distributor-restricted single and batch payouts, and owner controls for price, purchase toggling, and pausing, every action emitting an event the backend can index.
Users register through Firebase Auth, connect a wallet via RainbowKit, and claim a sign-up reward gated twice, once per wallet on-chain and once per web account in the database, so neither multiple wallets nor account re-registration can farm it. The dashboard shows token and ETH balances with USD values from a Chainlink price feed, circulating-supply statistics, reward history, and a typed transaction history, alongside fixed-price and Uniswap market purchase flows and a guided withdrawal.
The admin console, behind Firebase login with SUPER_ADMIN, ADMIN, and VIEWER roles, provides a live overview read directly from the contract, a transaction monitor that re-verifies pending transactions against the chain, single and batch reward distribution, contract settings, and a full Uniswap V2 liquidity console. Reward distribution runs manually from an admin's wallet or automatically through a queue processed by a backend worker and a secret-protected cron endpoint, with an audit entry recorded per item.
Two purchase paths
Fixed-price on-chain purchase through the contract's buyTokens function, or market buys via a built-in Uniswap V2 swap with live quotes, slippage handling, and managed approve/allowance flows.
Double-gated sign-up rewards
One-time claims tracked on-chain per wallet and in the database per web account, stamped with the token address so a redeployment resets claims cleanly.
Holder dashboard
Token and ETH balances with Chainlink-priced USD values, circulating-supply statistics, a token chart, reward history, and typed transaction history with guided withdrawals.
Role-based admin console
Live contract overview, transaction monitoring with on-chain re-verification, reward distribution, contract settings, and audit logging under SUPER_ADMIN, ADMIN, and VIEWER roles.
Uniswap liquidity management
Create or top up the token/WETH pool, inspect reserves, and remove liquidity with LP-token approvals and slippage controls, all from the admin console.
Automated reward distribution
An admin-managed queue processed by a dedicated distributor worker, in-process or via a secret-protected cron endpoint, with confirmation tracking and a per-item audit trail.
- 01
Upgradeable contract with scripted handoff
Solidity with OpenZeppelin 5 behind a transparent proxy, deployed via Hardhat with TypeChain, Basescan verification, transient-storage reentrancy guards, and ownership-transfer scripts for verifiable handoff to the client's wallet.
- 02
Transaction validation instead of trust
The backend never records what a client claims happened: it fetches the receipt, checks the transaction targeted the token contract or approved router, decodes the emitted events, and classifies the transaction itself.
- 03
RPC-frugal chain indexing
Chunked eth_getLogs scans with configurable pacing, an optional Alchemy fast path, per-wallet incremental sync cursors, layered caches, and a live-RPC fallback, engineered to run within free-tier RPC quotas.
- 04
Split trust model
Parameter changes and manual distributions require the administrator's own wallet to hold the on-chain role; the server-held key exists only for the opt-in automated queue, so a compromised server cannot re-price the token or drain the treasury.
- 05
Graceful degradation
Missing Firestore indexes fall back to in-memory sorting, a missing database falls back to live RPC scans, and a missing contract address degrades endpoints to explicit 503s rather than errors.
- A capped-supply, upgradeable ERC-20 with fixed-price purchase, sign-up rewards, and controlled distribution, with a Base mainnet deployment record committed in the repository.
- A public website and holder dashboard where non-expert users can register, connect a wallet, claim a reward, buy, track balances in USD, and withdraw.
- An admin console covering the full operating loop, monitoring, manual and automated reward distribution, liquidity management, contract settings, and audit logging.
- Client-ready documentation: a step-by-step demo guide, contract deployment guide, a requirements-to-implementation checklist, and a Mintlify docs site.