How FluxPool works

FluxPool lets a token's creator and its agent change how the pool behaves without ever changing the promise to holders. Agents tune the pool; what holders were promised stays locked. Not the agent, not the creator, not us.

A pool is made of a few parts, all part of an immutable layer with no proxy and no owner:

Behind the contracts, a backend indexes every pool, replays attacks, runs the block-writing pipeline and fires alerts. The app, agents and alerts all read the same events, so a change appears everywhere at once.

The shell wraps the core and checks four rules on every swap. If the core misbehaves, or fails outright, the shell still holds. These rules are the same in all three freedom modes.

How it keeps holding: there is no proxy, no owner and no admin function that can change a protection. The core is called as an external contract with a gas limit inside a try/catch, never with delegatecall. If the core reverts, runs out of gas or returns out-of-range values, the shell uses the base fee and lets the trade through. Permissions are fixed at deploy.

One deliberate detail: the shell does enable return deltas, but only so it can collect Programmable's 0.30% platform fee. Blocks are never given deltas, so no block can move tokens.

Each pool gets its own core: one implementation cloned with OpenZeppelin Clones. The core stores an ordered list of block addresses for each trade moment — today the before-swap and after-swap lanes — and calls each block in order.

Combining rules, deterministic so the composer can preview them: run blocks in lane order; the first block that rejects stops the lane and rejects the buy (sells still pass); fees add up and the shell clamps the total; a failing block is skipped, not fatal.

Who is the trader? In Uniswap v4 the sender is the router, not the person. The app passes the trader's address in hook data, but it is never relied on for protection. That is why anti-snipe limits are per swap and per block, not per wallet.

Blocks are deployed once and shared by every pool; their per-pool state is keyed by the calling core. These four settle how money flows and how trading opens.

The mode is chosen at launch and shown on the trust card. It decides how fast new settings and new code go live. The four protections hold in all three. Raising an agent's power and moving to a freer mode are always timelocked, so nobody can quietly turn a pool wild.

A failed check blocks a change for good. Switching to a safer mode also slows down changes already in the queue, because execute applies the stricter of the rules a change was queued under and the pool's current mode.

A queued block change lists the checks required to activate it. Designated attesters record results, and execute reverts unless every required check has passed. A failed check is final; a pass can still be downgraded to a failure.

An agent is just an address, so a scoped smart account with a session key works. A pool has one active agent in the first version. The creator registers it and sets its level; the contracts enforce the rest.

A playbook is a response the community approves in advance. Firing one is instant in every mode, because it can only tighten settings.

This is the part nobody else has. An agent describes a problem, and the pipeline decides whether a new block can go live, following the pool's mode.

Failures feed the next attempt, and attempts and runs per agent are capped. Tokens are logged, and a model outage pauses the pipeline instead of shipping a bad block. An agent-written block may declare which lanes it belongs to.

The reference agent shows what any agent can do, and it is built entirely on the public SDK, so it proves the interface works for outside agents too.

The watcher, rule engine and executor run as a long-lived process with a health check, aiming to fire within a few seconds of a trigger. If a model call fails, the playbook still fires and the explanation is filled in later. Stopping the agent never affects the shell's protections. A monthly spend cap, cached explanations and per-pool token logs keep the cost visible.

The deployed app runs the same explainer itself rather than waiting for the agent's process: a route in the app reads the journal events that have no text yet, asks a cheap OpenRouter model for one or two sentences — with the playbook's real trigger and cooldown read from the registry, so a fire can say why — and stores the result in its own database. The journal prefers that text over the deterministic summary and marks which entries carry it. Until the model key is set the pass is a no-op, and a failed call leaves the fire and its summary in place for the next pass.

Four layers run in CI: unit tests at every bound, fuzz tests over random settings and orderings, invariant tests over long random sequences in every mode, and attack scenarios replayed on a fork in a shared format. The backend tests the off-chain side.

Asserted after every simulated call, in every mode:

Every attack below has a passing scenario, on the contracts and, for the off-chain rows, in the backend:

Invariant runs use 10,000 sequences per mode in CI, about 400,000 calls each, and all six assertions pass with no reverts.

FluxPool's token launches through the same shell as everyone else's, with its economics written into the contracts rather than a blog post. This applies to our token's own pool only; other pools keep their own settings within the shell's limits. Pools pair against native ETH on Ethereum.

A few parameters are still open and must be set before deploy: the treasury Safe, the buyback operator, the market-cap bounds, the drop size and timing, and the launch window length.

FluxPool does not ship its own factory. Pools launch through Programmable, and FluxPool takes Path B: a Custom Launch on Ethereum with our shell as the hook, on Uniswap's official PoolManager, with a native ETH / token pool, following Programmable's Ethereum native-ETH launch. Programmable's 0.30% platform fee applies on top of ours and is enforced inside the hook, so no router can skip it.

Launch-day rules, learned the hard way:

A pool's hook is fixed at creation, so an existing token cannot be retrofitted. Instead it opens a new FluxPool pool and moves across.

Pulling the old liquidity matters: if liquidity stays split across pools, the protections leak. It works best for tokens whose team controls the liquidity and whose community is active.

Gas matters more on Ethereum, because every trader pays for the shell and its blocks on every swap. Measured per swap with native ETH: about 108k gas for a plain Uniswap v4 pool, about 181k to 208k for a FluxPool pool with no blocks, and about 252k to 284k with the two starter blocks. The first swap in each block costs a little more because the shell records that block's starting price. Keep lanes short on Ethereum: every block adds to every trade.

Still open before mainnet: compliance with Programmable's launch-protection policy and the Ethereum fee profile (the platform recipient is settled — it is the one Programmable publishes); the smart-account, bundler and paymaster stack for session keys; the agent, attester and pipeline keys plus model choices; where evidence is served publicly; and Programmable's verification API.

The simulator's host is switched on. /api/simulator/setup created a persistent sandbox, cloned the repository into it and installed Foundry, the contracts' submodules, the workspace and the contracts build. Requests resume that sandbox and reach the simulator by runningcurl inside it, because a function's own fetch to the sandbox's public port does not connect — and a port that answers the whole internet is a port anyone can spend this project's compute through, so the port is not exposed at all. Setup converges rather than runs once: re-running POST /api/simulator/setup moves the sandbox's checkout to the tip of the revision it is pinned to, rebuilds what changed and stops the server, so the next request starts the new code — which is how a change under services/ reaches the host. Both setup and health report the commit the checkout holds, so what the host is running is never a guess. Two things are worth knowing before relying on it. Starting the server is not the same as it being up: each worker deploys the whole stack on Anvil first — four minutes on the very first start with two workers, about fifteen seconds once the machine is warm — so the first request after a session has expired waits while that happens. And a draft names its blocks rather than addressing them, because the address a block has in the live deployment holds no code on the chain the simulator replays on: a setting's block travels by name, the way lanes already did, and the simulator resolves it against the chain it has. An address is still accepted, and one that chain does not have is reported as exactly that rather than as a failed launch. The next step for the host is to replay against a fork of the live chain, where the state a replay sees is the pool's real state.

Every block, including agent-written ones, implements this narrow interface:

The agent interface is the table under agents. The check names are those under checks. The journal events share stable names and fields so the indexer, alerts, SDK and track records can all read them:

Beyond those, the indexer also records rate-limit changes, playbook removals, attester and programmable-verification settings, pool registration, liquidity seeding and withdrawal, platform fee accrual and claims, core call failures, and the revenue router's Distributed and BoughtBack. The router's two events name no pool — one router is deployed per pool and neither event carries the id — so the indexer attributes them from the router's own immutable poolId(). Both the reference indexer and the copy that runs inside the app read them.

Attack scenarios are written as replayable JSON — a starting state, a swap sequence by block, and an expected outcome — and are replayed unchanged by both the Foundry runner and the simulator.

The app reads the contracts through the backend. Agents act through the SDK and MCP; holders watch on the token page. Rules for the app: always show what a change will do and whether it is instant or timelocked before anyone signs; link only the official contract; production never uses mock data.

Today the token page, the pools list, the composer, the launch form and the creator dashboard are live against this deployment. The indexer and the explainer both run inside this deployment, each as a route the platform calls on a schedule — this project is on Vercel Pro, so every minute; on Hobby the platform refuses anything more frequent than a daily pass. The pages read whatever the last pass wrote, so how fresh the numbers are follows that schedule, not the page's own refresh. There is no separate host to keep alive.

Trading is the pool's own router: an exact-input buy or sell sent through the shell, with the trader's slippage floor and deadline. The quote shown before signing is not a formula — it is the same swap simulated against the pool's current state, so the shell's dynamic fee and the price impact are already inside the number, and the floor is that number less the slippage the trader chose. A sell needs one approval first, because the router pulls the token from the wallet. The router holds no funds between calls, has no owner, no pause and no state to administer, and reports the trader to the pool's blocks rather than itself, so a per-block buy cap sees the holder. On Sepolia it is at 0x1e88ee14A8996007c578C183B7525A0CA7312e1a, set as NEXT_PUBLIC_FLUX_SWAP_ROUTER. With that unset, or with a pool whose key does not hash back to its id, the card says trading is off rather than pointing at a contract nobody deployed.

The dashboard reads money and the agent from the chain, not the indexer. The indexer knows what happened; only the shell knows what is claimable right now, and only the registries know whether a queued change can run. Collecting takes the whole pool key, which neither the shell nor the PoolManager will hand back, so the app rebuilds it and checks that it hashes back to the pool id before offering to collect — a key that does not match is refused rather than used against the wrong pool. Setting an agent is a plain wallet transaction from the creator, so it needs no bundler; the account-abstraction stack is for the agent's own session key, which is the part still to build.

The composer edits a draft, never a pool. It reads every block's bounds and defaults from the chain, so a value the contracts would reject cannot be chosen, and it reads the core's per-lane limit rather than assuming one. A block runs once per lane. AdaptiveFee is the one starter block that needs both lanes, because it measures selling after a swap and charges the fee before the next one. Playbooks are tighten-only by construction: an action's slider only offers values on the safer side of what the pool runs now, inside the registry's own limits (8 actions, a cooldown of 5 minutes to 7 days, at most 24 fires a day, and a window plus hold of at most 63 blocks). The crisis library the simulator replays is inlined from the contracts repository at build time, so this deployment serves the same scenarios the contracts are tested against. The draft lives in the browser until it is saved to a pool, and the simulator is reached over its own URL.

The launch form reads that same draft. It collects the token's details and the liquidity and lock choice, re-runs the composer's own layout and playbook checks so the two screens cannot disagree, and renders the trust card as buyers will see it — mode, lock, platform fee, the fee split read from the CreatorFee block's values, and the blocks each lane will run. Blocks are named, never addressed, in the launch review: the plan gives each one its own address when it deploys, so this deployment's addresses are not the ones that will be live. The ticker is collected and never rendered outside the form, and nothing is signed until the last step.