Tuo docs

Events and integration

The public event surface of the Tuo vault, the projection rules an indexer must follow, and how to read a position's state.

Everything that changes a position emits an event, and every event is declared on the vault's interface. This page is for anyone building an indexer, a dashboard or a monitor on top of Tuo.

Only interact with the addresses on Deployed addresses. The Sepolia rehearsal build predates the current ABI and does not emit the event set below.

Events by lifecycle

Deposits and positions

EventEmitted when
PositionOpened(nftId, owner, productCode, depositToken, depositAmount, usdcCredited)A new position is opened. usdcCredited is the basis
PositionToppedUp(nftId, depositToken, depositAmount, usdcCredited, newBasisUsdc)An existing position receives more capital
PositionBurned(nftId)The NFT is burned: by a 100% withdrawal, by an emergency exit when no Hyperliquid lifecycle is open, or by finalizeHlClaim

Withdrawals

EventEmitted when
WithdrawalRequested(nftId, sharesBps)The owner requests an exit of sharesBps of the position. sharesBps == 0 is a cancellation
PositionWithdrawn(nftId, sharesBps, grossUsdc, feeUsdc, netUsdc, withdrawalToken, tokenAmountOut, newBasisUsdc)The owner completes a withdrawal. grossUsdc == feeUsdc + netUsdc exactly
EmergencyWithdrawn(nftId, feeUsdc, hlClaimUsdc)The owner takes the emergency exit. hlClaimUsdc is the nominal margin still attributed to Hyperliquid, now the principal of a claim ticket that stays open until the owner finalizes it. It can be zero while the ticket is open; see the projection rules
EmergencyTokenPaid(nftId, token, amount)One in-kind payout, one event per token: during an emergency exit, or of a balance too small to price on a full withdrawal
HlClaimSettled(nftId, grossUsdc, feeUsdc, netUsdc)The keeper returns hedge value against a claim ticket, through the vault. grossUsdc == feeUsdc + netUsdc exactly; the claim stays open
HlClaimFinalized(nftId, shortfallUsdc)The owner closes the claim ticket. shortfallUsdc is the bridged margin that never came back; PositionBurned follows

Keeper actions

EventEmitted when
IdleSwapped(nftId, tokenIn, tokenOut, amountIn, amountOut)The keeper swaps an idle balance through an allowlisted aggregator
LpMinted(nftId, lpTokenId, pool, tickLower, tickUpper, liquidity, amount0, amount1)A concentrated liquidity range is opened
LpBurned(nftId, lpTokenId, amount0, amount1, fees0, fees1)A range is closed. fees0 and fees1 are the trading fees collected
HlBridgeOutbound(nftId, operator, amountUsdc)Hedge margin leaves the vault for the position's bound operator
HlBridgeInboundCompleted(nftId, amountReturnedUsdc, finalReturn)Margin comes back. finalReturn == true is the keeper attesting that no more will, and it is the only thing that closes the position's Hyperliquid lifecycle
KeeperLossCharged(nftId, lossUsdc, windowLossUsdc, ceilingUsdc)A keeper action produced a measured loss. windowLossUsdc is the loss bucket's level after its refill and this charge, not a total over a window; ceilingUsdc is the bucket's ceiling

Fees

EventEmitted when
FeesAccrued(nftId, feeUsdc, totalAccruedUsdc)A performance fee is taken in USDC on a withdrawal, or withheld from a claim return by settleHlClaim
TokenFeesAccrued(nftId, token, amount, totalAccrued)A performance fee is withheld in kind on an emergency exit
FeesClaimed(recipient, amountUsdc)The treasury sweeps accrued USDC fees
TokenFeesClaimed(token, recipient, amount)The treasury sweeps accrued fees in another token

Administration

EventEmitted when
HlOperatorUpdated(operator, allowed)The treasury adds or removes a Hyperliquid operator. The only on-chain signal that the set of addresses customer margin may leave toward has changed
PoolRegistered(pool, token, isValuationPool)A Uniswap V3 pool is frozen into the allowlist at construction, once per configured pool. isValuationPool marks the one pool a token's valuation reads; a later pool for the same token is allowlisted without pricing anything
ProductRegistered(productCode, label, maxHedgeBps, maxLpCount)A product is added to the registry
ProductOpenUpdated(productCode, openForDeposits)A product is opened or closed for new positions
PerNftCapUpdated(perNftCapUsdc)The per-position cap changes
KeeperSwapSlippageUpdated(keeperSwapSlippageBps)The keeper swap tolerance is seeded at construction or changed by the treasury
FeeRecipientUpdated(feeRecipient)The fee recipient changes
DepositsPauseUpdated(paused)Deposits are paused or unpaused
RoleGranted, RoleRevoked, RoleAdminChangedStandard OpenZeppelin AccessControl events

The router emits SwapExecuted, AggregatorAdded and AggregatorRemoved. The NFT emits the standard ERC-721 Transfer, and BaseURIUpdated(baseURI) when the treasury sets its base URI.

Projection rules

Anyone rebuilding position state from events should follow these rules. Each one has caught a real indexing bug.

  1. Cancellation is WithdrawalRequested(nftId, 0). There is no separate cancel event and no readiness flag on-chain. A request with sharesBps == 0 clears the pending request.
  2. HlBridgeInboundCompleted does not carry post-state. The vault clamps the bridged-margin attribution to zero, so a projection that subtracts amountReturnedUsdc from its own running total can go negative when a hedge returns more than it was sent. Clamp at zero, and treat finalReturn == true as clearing the attribution regardless of amount.
  3. A zero attribution is not a finished hedge. The vault tracks Hyperliquid finality separately, as hlLifecycleOpen on getPosition. HlBridgeOutbound opens it. Only HlBridgeInboundCompleted with finalReturn == true closes it, or HlClaimFinalized for a claim. A return with finalReturn == false never closes it, even when it repays the whole attribution, because a return leg can be sized from one venue ledger while proceeds remain on another. Settlement reverts HlMarginOutstanding until the lifecycle closes. A final return of zero is valid and is how the keeper closes a lifecycle whose attribution is already repaid.
  4. An open claim is an open lifecycle on a closed position. EmergencyWithdrawn with no PositionBurned in the same transaction means a claim ticket opened, even when hlClaimUsdc is zero. That happens when earlier returns had repaid the attribution and the venue was not yet finished. settleHlClaim still pays the owner against such a ticket.
  5. Withdrawals reduce charged keeper loss without an event. A partial withdrawal scales the position's charged loss down pro-rata so a full exit never leaves a charge against a zero ceiling. A projection that only follows KeeperLossCharged will drift high; read the budget view for the true state.
  6. The pool registry arrives once, in the deployment transaction. PoolRegistered names each allowlisted pool's non-USDC token, and that is what attributes LpMinted and LpBurned amount0 / amount1: the pair is that token and USDC, ordered as Uniswap orders them, so the lower of the two addresses is token0. Index from the vault's deploy block or the mapping is missing. A pool with isValuationPool == false is still mintable; it just is not what values the token.
  7. Key raw events on (chainId, txHash, logIndex) so a replay is idempotent, and index from finalized blocks if you cannot handle reorgs.

Reading a position

QuestionHow to answer it
Who owns itTuoPositionNFT.ownerOf(nftId)
What is it worth on-chainTuoVault.settlementNav(nftId). Reverts with HlMarginOutstanding while the Hyperliquid lifecycle is open (hlLifecycleOpen on getPosition); that is the normal state of a hedged position, not an error
What would a withdrawal payTuoVault.previewWithdraw(nftId) returns the gross, fee and net figures for the requested share, subject to the same revert
Can it be serviced nowCompare the preview against TuoVault.idleBalance(nftId, USDC). A withdrawal needs the settlement figure to resolve and the share to be covered by idle USDC. At 100% the share is the whole settlement figure, so any priced WETH or WBTC balance still idle reverts InsufficientIdle, and any open LP reverts LpsOutstanding
Keeper budget stateTuoVault.keeperBudgetOf(nftId), or keeperActionsToday(nftId) for the action half alone. actionsUsed counts whole action slots and rounds up, because the vault charges a whole slot against a balance that regenerates continuously: 10 - actionsUsed is exactly the metered keeper calls the position still admits, so a part-regenerated slot never reads as free

Subgraph and ABIs

A public subgraph indexes the raw events. During the guarded launch it targets the Sepolia rehearsal build under the Subgraph Studio slug tuo-arbitrum-sepolia; the Arbitrum One subgraph will be listed here at deployment. The subgraph is a convenience for reading events. It is never authoritative for valuation, which only the on-chain views and the off-chain NAV service provide.

Generated TypeScript ABIs are published from the repository as the @tuo/abis package once the mainnet deployment is live.

On this page