Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.filter.fun/llms.txt

Use this file to discover all available pages before exploring further.

filter.fun’s settlement pipeline is the part of the system that has to be right. Trading fees can be tweaked. UI can be redesigned. But once a season ends, the contracts move real WETH into rollover, hold bonus, POL, mechanics, treasury, and the champion bounty — and that movement has to be exact, atomic, and unforgeable.This page documents the eight invariants the contracts hold, the Foundry test suite that proves them, and the voluntary disclosure window that’s open before formal audit begins.

​
How a season’s WETH actually flows

Every wei in this diagram has a destination, every destination has a contract, and every contract has invariants. Below is what’s enforced.

​
The eight invariants

1. Conservation

Every wei in is accounted for. The sum of allocated value across rollover, hold bonus, mechanics, POL, treasury, and champion bounty equals the total WETH collected from filtered LP. No leaks. No double-spends. No unattributed balances.

2. Settlement math exactness

The 45 / 25 / 10 / 10 / 10 split (after the 2.5% champion bounty) is enforced by contract math, not promised in marketing. The constants are basis points; the arithmetic happens on-chain at finalization.

3. POL atomicity

POL is deployed exactly once per season, only at finalization, only into the winner’s pool. Once deployed, the LP tokens are locked in POLVault permanently — no withdraw path exists.

4. Merkle root immutability

Once published, the season’s rollover root is forever the canonical truth for who can claim what. There is no function to republish or modify it. Bonus root same.

5. Reentrancy safety

Every fund-moving function refuses re-entry, including against malicious receiver contracts whose transfer hooks try to call back into the pipeline. Fuzz tests with adversarial receivers revert cleanly.

6. Oracle authority boundary

Only the configured oracle address can submit settlement. All other callers revert at the function entry guard. No upgrade mechanism permits changing that without explicit governance action.

7. No mid-season POL deployment

POL stays as WETH inside SeasonPOLReserve between filter events. Any code path that would deploy it earlier than finalizeSeason is a bug, not a feature.

8. Dust handling

Rounding from integer division goes to treasury. It is never lost, never accumulated in an unaccounted balance, and never silently rounds away from a holder.

​
How to verify these claims yourself

You don’t have to take filter.fun’s word for it.
  • The contracts: starl3xx/filter-fun — open-source Solidity. Settlement pipeline lives in packages/contracts/src/: SeasonVault, POLManager, BonusDistributor, TournamentVault, CreatorCommitments.
  • The invariant suite: PR #50 on filter-fun — the Foundry test suite that codifies all eight invariants and runs in CI on every change. Failures block merge.
  • The deployed Sepolia addresses: tracked in packages/contracts/deployments/base-sepolia.json in the contracts repo. Mainnet addresses will appear here once Phase 2 launches.
  • The smoke runbook: Sepolia smoke-test — end-to-end exercise of one season including settlement and claim, with verifiable cast commands at every step.

​
Voluntary disclosure window

Found something? We want to know.
filter.fun does not currently run a paid bug bounty program. This is a voluntary disclosure window — your contribution is recognized but not financially compensated. A formal bounty program is expected to launch post-mainnet via a specialized platform (Immunefi or similar) once the treasury and legal framework are in place.
Pre-audit voluntary review window: the contracts are open for community review for a 14-day window before formal audit engagement begins. Submit findings to the address below.
  • Contact: security@filter.fun (placeholder — replace with the real PGP-protected address before publishing this page)
  • PGP key: linked from the contact address (placeholder until published)
  • Disclosure window: please don’t disclose publicly until a fix is shipped or 90 days have passed, whichever comes first
  • Recognition: with your permission, valid findings get hall-of-fame credit on this page
  • Scope: the settlement pipeline contracts (SeasonVault, POLManager, BonusDistributor, TournamentVault, CreatorCommitments), plus the bag-lock contract from PR #43, plus any contract under packages/contracts/src/ deployed in the manifest
  • Out of scope: the indexer, the web app, third-party dependencies (V4 PoolManager, WETH9), social-engineering, denial-of-service against RPC providers
What we want most: anything that violates one of the eight invariants above under any sequence of valid operations. The invariant suite proves they hold under random fuzzed sequences — what it can’t prove is that the invariants are the right invariants. That’s where adversarial review beats automated tests.
  • Threat model — the seven adversaries the pipeline defends against, and how
  • Audit status — pre-audit phase status, audit firm engagement, mainnet activation gate
  • Risks — what the system doesn’t promise to participants