Tuo docs

Architecture

The three Tuo contracts, the libraries behind them, their external dependencies, and the invariants the test suite holds them to.

Tuo deploys exactly three contracts. The deploy script first grows each pool's oracle ring to 2,000 slots where it holds fewer, then creates all three in one transaction: TuoVault's constructor deploys TuoPositionNFT and TuoSwapRouter itself and wires every role, so there is no window in which the contracts are live but not yet configured.

Contracts

ContractPurpose
TuoVaultCustody core. Deposit, withdrawal, emergency exit, the keeper surface, budgets, fee accrual, roles. One deployed contract split across four source files (TuoVault, TuoVaultViews, TuoVaultStorage, TuoVaultAdmin)
TuoPositionNFTPlain transferable ERC-721. ownerOf is the sole withdrawal authority. Mint and burn are vault-only. The only recipient refused on transfer is the vault itself
TuoSwapRouterVault-only execution wrapper for 0x and 1inch. Treasury-maintained aggregator allowlist, exact-amount approvals cleared after every call, balance-delta verification, strict full-spend of the input

Internal libraries

LibraryRole
TuoConstantsEvery protocol parameter in one place. See Parameters
TuoRolesThe three role identifiers
PerformanceFeeStateless 30%-of-profit math and the pro-rata basis reduction
PoolTwap30-minute pool TWAP reads and the spot-versus-TWAP deviation gate
PositionValuationUSDC value of a Uniswap V3 position at the TWAP tick

Topology

External dependencies

DependencyVersion or addressUsed for
OpenZeppelin Contracts5.6.1AccessControl, ERC-721, SafeERC20, ReentrancyGuard, Pausable
Uniswap v3-core1.0.2 (solc 0.8)Pool interfaces and tick math
Uniswap NonfungiblePositionManagerCanonical per networkMinting, burning and collecting concentrated liquidity
0x AllowanceHolderAllowlisted aggregatorEntry and exit swaps
1inch AggregationRouter v6Allowlisted aggregatorEntry and exit swaps
Circle CCTP v2Off-chain railMoving hedge margin between Arbitrum and Hyperliquid. The contracts never see which rail is used

Compiler and build

SettingValue
Solidity0.8.26, pinned
EVM versioncancun
OptimizerOn, 200 runs, via_ir
Metadatabytecode_hash = none, CBOR metadata off, to stay under the EIP-170 size limit
TuoVault runtime size24,434 bytes, 142 bytes below the ceiling

The metadata setting means explorer verification is a partial match rather than an exact match. The source still verifies.

Design rules

  • No proxies, no upgrades. What is deployed is what runs, for the life of the deployment.
  • No strategy on-chain. Range selection, hedge sizing and rebalance timing come from the off-chain engine and arrive as ordinary keeper calls. The chain's job is to keep every call inside a perimeter that cannot move funds away from the owner.
  • No shared pot. Every asset in the vault is attributed to exactly one position. There is no pooled accounting and no share token.
  • Measured-only settlement. The vault never values the Hyperliquid leg. Any settlement path reverts while the position's Hyperliquid lifecycle is open, and only the keeper's final return closes it, so a fee can only be charged on value the vault can see.
  • Reentrancy guards. Every customer and keeper call, and both fee sweeps, carries a reentrancy guard, and the valuation and keeper-budget views refuse a read taken mid-call. A full withdrawal burns the NFT before its payout. Not every path writes its state first: a deposit pulls and swaps the tokens before it records the position, and the emergency exit pays in kind before it burns the NFT.
  • Pull-payment fees. Fees accrue in the vault and are swept by the treasury. A fee recipient that cannot receive USDC blocks Tuo's revenue, never a customer's exit.

Invariants

The test suite runs a stateful fuzz harness driven by a hostile keeper: floor-priced fills, dust bridges, bridges aimed at another position's operator, dust-LP spam, attacker-routed swaps, and unrestricted position transfers between actors. These properties must hold after every sequence.

InvariantProperty
I1, I2USDC and WETH are fully attributed: the vault balance equals the sum of idle balances plus accrued fees
I3A position's basis never exceeds what was actually deposited
I4Value is conserved across the whole lifecycle, summing every operator
I5The keeper is never enriched
I6An NFT exists if and only if its position is active or its Hyperliquid lifecycle is open
I7The 10-action budget holds
I8The owner can always exit
I9Keeper-attributed loss stays inside the leaky-bucket loss budget
I10The Hyperliquid claim ledger is lossless: an NFT survives while the lifecycle is open, a ticket is closed only by its owner, and every return is charged exactly the cumulative fee delta
I11No bridge under the operational floor ever lands
I12Operators and positions are one-to-one: no two positions ever share an operator
I13The owner of an open claim can always finalize it and reach a terminal state
I14Outstanding hedge margin implies an open Hyperliquid lifecycle, so a repaid margin figure alone never opens settlement
I15A retired position holds no LP and no idle balance, so no close strands value

Alongside the invariants there are 26 unit suites, access-control tests that assert the exact account and role, tests with authorized-but-hostile callers, and fork tests against the real Arbitrum position manager, pools and a real aggregator. 426 tests in total.

Source

The repository is private during the guarded launch. Verified source for every deployed contract is linked from Deployed addresses. The licence is on Licence.

On this page