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
| Event | Emitted 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
| Event | Emitted 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
| Event | Emitted 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
| Event | Emitted 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
| Event | Emitted 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, RoleAdminChanged | Standard 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.
- Cancellation is
WithdrawalRequested(nftId, 0). There is no separate cancel event and no readiness flag on-chain. A request withsharesBps == 0clears the pending request. HlBridgeInboundCompleteddoes not carry post-state. The vault clamps the bridged-margin attribution to zero, so a projection that subtractsamountReturnedUsdcfrom its own running total can go negative when a hedge returns more than it was sent. Clamp at zero, and treatfinalReturn == trueas clearing the attribution regardless of amount.- A zero attribution is not a finished hedge. The vault tracks Hyperliquid finality
separately, as
hlLifecycleOpenongetPosition.HlBridgeOutboundopens it. OnlyHlBridgeInboundCompletedwithfinalReturn == truecloses it, orHlClaimFinalizedfor a claim. A return withfinalReturn == falsenever 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 revertsHlMarginOutstandinguntil the lifecycle closes. A final return of zero is valid and is how the keeper closes a lifecycle whose attribution is already repaid. - An open claim is an open lifecycle on a closed position.
EmergencyWithdrawnwith noPositionBurnedin the same transaction means a claim ticket opened, even whenhlClaimUsdcis zero. That happens when earlier returns had repaid the attribution and the venue was not yet finished.settleHlClaimstill pays the owner against such a ticket. - 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
KeeperLossChargedwill drift high; read the budget view for the true state. - The pool registry arrives once, in the deployment transaction.
PoolRegisterednames each allowlisted pool's non-USDC token, and that is what attributesLpMintedandLpBurnedamount0/amount1: the pair is that token and USDC, ordered as Uniswap orders them, so the lower of the two addresses istoken0. Index from the vault's deploy block or the mapping is missing. A pool withisValuationPool == falseis still mintable; it just is not what values the token. - 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
| Question | How to answer it |
|---|---|
| Who owns it | TuoPositionNFT.ownerOf(nftId) |
| What is it worth on-chain | TuoVault.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 pay | TuoVault.previewWithdraw(nftId) returns the gross, fee and net figures for the requested share, subject to the same revert |
| Can it be serviced now | Compare 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 state | TuoVault.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.