TokenFlow Documentation

TokenFlow (FLOW) is an ERC20 on Robinhood Chain with a single on-chain treasury. 100% of the supply is seeded into one Uniswap V4 pool at launch — no presale, no team allocation, no vesting. Pool fees fund the treasury, which buys a team-curated basket of stock tokens and memecoins in a perfectly balanced 1:1 proportion and streams every token it buys to FLOW stakers.

At a glance

How it works

Fee flow

Every FLOW swap on the Uniswap V4 pool pays a 5% pool fee. Those fees accumulate inside the pool position as the protocol's reward for providing the LP. A dedicated contract holds the LP NFT and exposes a single function — harvest() — that anyone can call at any time.

When harvest() fires, it collects accrued fees (and only fees — the principal liquidity is unreachable by anyone, including the team), swaps the FLOW portion to ETH, and routes the result:

• 80% → on-chain treasury, which buys reward tokens for stakers
• 20% → team wallet, paid pull-only so a reverting team wallet can never block a harvest

Measured against the trade itself, that is 4% to stakers and 1% to the team. The LP NFT is permanently owned by the harvester contract, which can only decrease liquidity by zero — fees come out, principal never does. There is no transferNFT, no permit, no path that ever extracts the liquidity itself.

Reward buys

The treasury holds ETH. Once its balance crosses the buy threshold (0.5 ETH by default), anyone can call triggerBuy() in a single transaction. The contract spends min(balance, 2 × threshold) and splits that ETH equally across every token in the basket — one swap leg per token, each with its own minimum-output check. Routes go over Uniswap V2, V3 or V4, bridged through USDG or WETH where no direct pair exists.

Per-buy spend cap

A single triggerBuy() spends at most 2× the buy threshold in ETH, even if the treasury holds more. No single call can drain the treasury.

The treasury never holds the basket

Each leg's output is forwarded to the staking contract in the same transaction. The treasury is a conduit for ETH, not a fund that accumulates tokens: it has no sell logic, no profit-taking, and no way to hold a bought token back from stakers.

Streaming

Every amount handed to the staking contract begins a 7-day stream for that token. Stakers accrue continuously, pro rata to their weight — the staked amount multiplied by the position's lock multiplier — against the total weight of all positions.

If a second buy of the same token lands while a stream is still running, the remainder is folded in and the 7-day window restarts. Streams pause whenever nothing is staked, so rewards are never stranded or paid to nobody.

Staking

Lock tiers

Staking is the only way to earn from the protocol. Five tiers are available, fixed as contract constants — the multiplier is set when the position opens and determines its share of every subsequent reward buy.

The curve plateaus deliberately: doubling the lock from 180 to 365 days adds far less than the first commitment did. A position's weight is amount × multiplier, and your share of any stream is your weight over the total weight staked.

Claiming & withdrawing

Rewards are claimed, never airdropped. A position's rewards and its principal both unlock at lockEnd; claim and withdraw revert before that point. There is no early exit — no penalty path, no fee to buy your way out.

Once a lock expires the position does not stop earning: it drops back to the Flexible 1.00x multiplier and keeps accruing until withdrawn. The drop is applied by claim, withdraw, or kick — a public function anyone can call, which the protocol's cron calls automatically so an expired position never keeps a multiplier it is no longer entitled to.

Parameters

Immutable constants

Set in the contracts and never changeable. Modifying any of these requires a new deployment.

Configurable bounds

The buy threshold can be tuned by the treasury owner — but only within a hard-coded range that is itself immutable. The setter reverts on any value outside these limits.

Widening the range — for instance, allowing a 20-ETH buy threshold — would require a v2 deployment, since the bounds themselves are coded as immutable constants and cannot be changed by any function. The staking contract has no configurable parameters at all: the tiers, multipliers and stream duration are constants.

Reward tokens

How tokens get added

The basket is curated entirely by the team. The community surfaces candidates through an off-chain leaderboard, but no chain action ever happens automatically.

1. Community proposes. Anyone signed in with X can propose any ERC20 address and vote on existing proposals. The leaderboard is public.
2. Team audits. Before adding anything on-chain, the team runs an audit pass on the candidate — checking honeypot and transfer-tax signals, and the depth of its pools across Uniswap V2/V3/V4 so a buy leg can execute without excessive price impact.
3. Owner adds. If the audit passes, the owner calls addEligibleToken(address, kind, pool) directly. There is no on-chain proposal contract, no proposal bond, and no automatic promotion from the leaderboard.

Add / remove behavior

Adding a token appends it to the basket. From the next buy onward, the ETH is split across the larger set — every token, including the new one, still receives exactly one equal share.

Removing a token stops future buys of it. What it cannot do is strand rewards: any amount already streaming continues to stream to the end of its 7-day window, and anything stakers have accrued stays claimable indefinitely. Removal takes a token out of future allocation; it never claws back what stakers have already earned.

The 10-token cap

The basket is hard-capped at 10 entries. addEligibleToken reverts when the basket is full and when the token is already present. The cap keeps a single triggerBuy() bounded — every buy performs one swap leg per basket token, so the cap is what keeps that transaction affordable and its gas predictable. Separately, the staking contract will track at most 50 distinct reward tokens over its lifetime.

Community leaderboard

X sign-in

The leaderboard is an off-chain product hosted alongside the dApp. Authentication is via X (Twitter) OAuth — sign in with X and you can propose tokens and vote. The protocol stores only the X handle, name, avatar, and a session cookie; nothing else is collected.

The leaderboard is purely advisory. It does not move funds. It does not auto-promote any token on-chain. It is a public signal that the team uses when curating the basket — nothing more.

Propose & vote rules

• Propose any ERC20 address. Idempotent — proposing an address that already exists is a no-op.
• Vote for any proposed token. One vote per X account per token; clicking again toggles it off. No proposal bond, no vote weight, no quadratic anything.
• Audit badge. Each proposal shows the team's audit status (passed / flagged / not yet audited) so voters know what's been reviewed.

Security

Guarantees

These properties hold by code, not by promise. They form the audit checklist for the contracts.

1. Staking has no admin. The staking contract has no owner, no roles, and no privileged functions whatsoever. Nobody can pause it, upgrade it, change a multiplier, or move a staker's principal.
2. Narrow treasury admin. The owner can tune the buy threshold inside [0.1, 10] ETH and add or remove basket tokens. There is no pause, no withdraw, no upgrade, no mint, no admin escape.
3. LP non-extractable. The contract that owns the Uniswap V4 LP position can only ever collect fees on it. There is no path that withdraws principal liquidity.
4. No mint. The full supply is minted once at construction. TokenFlow exposes no mint function to anyone.
5. Per-leg slippage bounds. Every swap leg carries its own minimum-output check and reverts if the route cannot fill it.
6. Equal allocation. The ETH split across basket tokens is computed by the contract, not supplied by the caller. No caller input influences how much any token receives.
7. Bounded buys. A single triggerBuy() spends at most 2× the threshold and performs at most 10 legs.
8. Pull-only team payout. The team's 20% is claimed, not pushed, so a reverting team wallet can never block a harvest.
9. Rewards cannot be stranded. Streams pause when nothing is staked, and removing a token never stops an in-flight stream or blocks a pending claim.
10. Principal is segregated. FLOW is never a reward token, so no reward accounting path can ever pay out staked principal.
11. Reentrancy guards on staking entry and exit. ETH transfers are explicit, checked calls.
12. No selfdestruct, no delegatecall to user-controlled addresses, no unvetted inline assembly.
13. Immutable external addresses. Routers, the V4 PoolManager and the FLOW address are constructor params that can never be changed.

The v1 trade-off

v1 ships with the deployer as the sole owner of the treasury and fee harvester — not a multisig, not a timelock. This is an intentional trade-off, and it's bounded by the rest of the design. The staking contract is unowned, so nothing below touches staked funds or accrued rewards.

A compromised owner key can do exactly three things:

• Move the buy threshold inside [0.1, 10] ETH
• Add a token to the basket (up to the cap of 10)
• Remove a token from the basket

What a compromised key cannot do: withdraw treasury funds, mint FLOW, pause the protocol, upgrade any contract, extract the LP, touch staked principal, stop an in-flight reward stream, or block a staker's claim.

Ownership is transferable through the standard OpenZeppelin transferOwnership path. Moving to a multisig — and later to a timelock — requires no contract changes.

Reference

Contracts

All contracts are Solidity 0.8.35 with OpenZeppelin Contracts 5.x. Sources are verified on Blockscout at deploy.

External addresses

Robinhood Chain dependencies, pinned in the contracts at deploy time.

Glossary

• FLOW — TokenFlow's ERC20 token. Robinhood Chain, 1B fixed supply.
• Treasury — The on-chain contract that holds ETH from pool fees and executes reward buys. It never keeps the tokens it buys.
• Basket — The team-curated list of tokens the treasury buys for stakers. Capped at 10. Called reward tokens in the app.
• Reward buy — One triggerBuy(). Splits the treasury's ETH equally across every basket token and forwards the results to staking.
• Stream — The 7-day window over which a bought token is paid out to stakers.
• Weight — A position's staked amount times its lock multiplier. Your share of a stream is your weight over total weight.
• Lock tier — One of five staking terms, from Flexible at 1.00x to 365 days at 2.50x. Fixed when the position opens.
• Claim — Taking accrued rewards. Available once the position's lock has ended; rewards are never airdropped.
• Kick — A public call that drops an expired position back to the 1.00x Flexible multiplier.
• Buy threshold — Treasury ETH balance required before triggerBuy() can fire. Default 0.5, owner-tunable inside [0.1, 10].
• Community leaderboard — Off-chain X-OAuth UI for proposing and voting on tokens. Purely advisory; never moves funds.

For questions: X (Twitter)