Architecture Overview

design philosophy the tokenflow architecture was designed with the following principles security first — every function that touches user funds is guarded, validated, and revert safe composability — built around existing defi standards (erc 20, erc 4626, and uniswap routers) transparency — each transaction emits events for tracking and verification; nothing is hidden extensibility — each vault operates independently, enabling new index funds without redeploying the core decentralized autonomy — each fund governs itself via its own index token — no central tokenflow governance layer these principles ensure the protocol can grow organically into a family of independently governed, interoperable, and composable index vaults high level architecture at a system level, tokenflow consists of six main components component description fundmanager factory and registry for creating new vaults (index funds) deploys fundvault + fundshare pair fundvault erc 4626 like vault that holds the assets of an index, mints and burns fundshare tokens, and executes deposits, redemptions, and rebalances fundshare (participationtoken) erc 20 token representing ownership in the fund tradable on dexs, used for governance tradeexecutor library that constructs and executes trades via uniswap’s universal router while enforcing slippage and impact limits oraclerouter aggregates price feeds for each token in eth terms, providing nav and slippage validation feecollector aggregates all protocol fees and handles distribution to buyback/burn or treasury addresses every deployed fund is a self contained economic system it has its own vault, share token, oracle configuration, and governance the fundmanager only acts as a factory and indexer , not a controller on chain architecture diagram on chain architecture diagram \[user wallet] │ │ deposit eth ▼ \[fundvault] ─────→ \[tradeexecutor] ─────→ \[uniswap router] │ │ │<── oracle price feeds ───┘ │ ├── mint/burn ───→ \[fundshare (erc20)] │ ├── fee flow ───→ \[feecollector] │ └── governance ─→ on chain proposals (per vault) \[user wallet] │ │ deposit eth ▼ \[fundvault] ─────→ \[tradeexecutor] ─────→ \[uniswap router] │ │ │<── oracle price feeds ───┘ │ ├── mint/burn ───→ \[fundshare (erc20)] │ ├── fee flow ───→ \[feecollector] │ └── governance ─→ on chain proposals (per vault) this structure ensures separation of responsibilities, modularity, and composability each part can be upgraded or replaced independently while maintaining predictable behavior this structure ensures separation of responsibilities, modularity, and composability each part can be upgraded or replaced independently while maintaining predictable behavior contract responsibilities 1\ fundmanager purpose deploy and track all funds (vaults + tokens) functions createfund(params) — deploys a new fundvault + fundshare token registers the fund’s metadata (name, symbol, constituents, fee caps, oracle sources) stores a list of active funds for ui discovery security controls ownable — only protocol deployer can create new funds immutable configuration for fee caps and address templates events fundcreated(address vault, address token, string name, string symbol) 2\ fundvault purpose core accounting engine manages deposits, withdrawals, swaps, and rebalances for its specific index key functions depositeth(uint256 minsharesout) — user deposits eth, vault executes swaps, and mints shares redeem(uint256 shares, uint256 minethout) — burns shares and returns eth rebalancetotarget(address\[] tokens, uint256\[] targetweights) — adjusts holdings updateweights(address\[] tokens, uint256\[] weights) — modifies basket composition navpershare() — returns the current nav per fundshare token getsnapshot() — view function returning nav, weights, supply, and price impact guardrails internal logic tracks asset weights and holdings in storage uses tradeexecutor for all swap operations uses oraclerouter for price validation emits events on every economic action security features non reentrant deposit/redeem paths circuit breakers (pause on invalid oracles, stale prices, or abnormal deviations) maxpriceimpactbps guard to limit slippage emergency pause (guardian role, time locked) 3\ fundshare (participationtoken) purpose erc 20 token representing proportional ownership of the vault’s tvl it is also the governance token for that fund features minting only the corresponding vault can mint on deposit burning vault burns tokens on redemption or auto burn trading tax smart contract includes a configurable fee (e g , 1%) applied to transfers through uniswap pairs governance token holders can vote on proposals affecting that specific vault events transfer, approval, burn, governanceproposal, votecast 4\ tradeexecutor purpose secure trade interface between the vault and external dexs built as a library or contract module callable by any vault functions executebuys() — performs eth → tokens swaps to achieve target allocations executesells() — performs token → eth swaps for redemptions or rebalances validates minimum output amounts and enforces price impact caps uses uniswap’s universal router for aggregation security checks cumulative slippage < threshold verifies oracle price vs actual execution price deviation supports twap order batching for large trades 5\ oraclerouter purpose centralized price reference for nav, slippage control, and rebalancing architecture pulls eth denominated prices for each asset accepts data from multiple sources uniswap twap, chainlink, or custom oracles maintains freshness and deviation thresholds (e g , 2 hours max age, ±2 5% tolerance) functions ethvalueof(address token, uint256 amount) gettwapprice(address token) updateoraclebatch() — for authorized updaters to refresh prices security ownable + allowlisted updater addresses fails safe stale or invalid price reverts deposits/redemptions 6\ feecollector purpose consolidates fees from all vaults and handles distribution logic sources of fees deposit and redemption fees (in eth) 20% allocation from dex trading tax optional management fees functions collect() — pulls fees from vaults buybackandburn() — converts eth → fundshares → burns them distributetotreasury() — sends treasury portion to the vault’s management address getbalance() — returns accumulated eth balance events feescollected, buybackexecuted, tokensburned data flow — end to end example scenario user deposits eth user calls depositeth() on the vault vault requests latest prices from oraclerouter vault computes target token allocations vault sends eth to tradeexecutor, which executes swaps via uniswap vault mints fundshare tokens to the user’s wallet deposit and swap data are logged via events feecollector updates eth fee balance result user receives fundshares; vault portfolio updates; all data recorded on chain governance flow — per vault each vault operates its own governance loop using its fundshare token governance process any holder above a threshold (e g , 0 5% of supply) can create a proposal proposal defines fee changes, weight updates, new assets, or parameter updates voting period 7 days if quorum and majority reached → proposal queued in time lock (24–48 hours) after time lock, proposal executes automatically on chain via vault contract governance smart contract roles vault governor per vault proxy managing proposals executor applies changes through the vault’s admin interface guardian emergency pause authority (multi sig) storage and accounting each vault maintains these key storage variables variable type description tokens\[] address\[] list of constituent tokens weights\[] uint256\[] target weight per token (basis points) balances\[] uint256\[] current holdings per token totalshares uint256 total fundshare supply feesettings struct fee caps and allocations lastoracleupdate uint256 timestamp of last price update maxpriceimpactbps uint16 slippage limit paused bool emergency flag each variable is public or viewable through getsnapshot() for front end display and analytics event system the protocol emits granular events for full traceability event description fundcreated emitted when a new vault is deployed deposited user deposits eth and receives fundshares redeemed user redeems fundshares for eth rebalanced vault executes reallocation weightsupdated index composition changed feescollected fees moved to feecollector tokensburned fundshares burned during deflationary loop governanceproposal new governance proposal created votecast governance vote cast oracleupdated price data refreshed these events feed subgraphs (e g , the graph) for dashboard analytics, historical tvl tracking, and performance charts external integrations wallets wallets can interact directly via depositeth() and redeem() with simple abi calls they can also integrate tokenflow into their built in swap flows by fetching vault metadata and price info from the fundmanager registry dex aggregators aggregators can quote fundshare prices via the uniswap pool or nav snapshot api they can route trades directly into tokenflow vaults to optimize for slippage and arbitrage analytics dashboards subgraphs track nav over time fees collected and burned token weights and rebalance history supply and burn events this transparency invites trust and third party analytics (e g , dune, defillama) security architecture reentrancy guard protects mint/redeem/rebalance functions pause mechanism immediate halt on suspicious activity price impact guard transaction reverts if deviation > 5% oracle sanity checks nav calculation rejects stale or deviated prices time locked governance ensures no instant parameter changes audited codebase external audits mandatory before each fund deployment bug bounty program incentivizes community discovery of vulnerabilities future architecture extensions the system is modular and ready for expansion cross chain vaults future l2 deployments (base, arbitrum) with canonical bridged fundshares automated dca modules scheduled eth deposits over time yield routing use yield bearing tokens (e g , ausdc) as underlying assets off chain keeper network decentralized rebalancing automation (gelato/chainlink keepers) dynamic indexing algorithmic asset selection based on liquidity or volatility metrics summary tokenflow’s architecture unifies etf style structure , dex native execution , and autonomous fund logic into a single on chain framework layer purpose characteristics application layer user wallets, dapps, dexs front end ux, composability vault layer fundvaults + fundshares core logic, asset management execution layer tradeexecutor + uniswap liquidity routing data layer oraclerouter + subgraphs nav, prices, analytics governance layer per vault voting decentralized control treasury layer feecollector sustainable funding tokenflow’s modular smart contract stack ensures scalability, transparency, and autonomy — enabling any community to create and manage its own index, while keeping the system secure and composable within defi