!5312odin/vault-gas-reserve → develop2fafbf2957

Keep gas in vaults for the tokens they hold (VaultTokenGasReserve)

AI-generatedEverything on this page was written by an AI agent from the diff: the summaries, the narration, the diagrams, the flags and the glossary. It can be wrong or incomplete, so check it against the code before you rely on it.

8commits
48files
7.5klines changed
322lines to read
0 = offnew mimir default
nonemigration

Where the diff is

How a vault is picked for an outbound

The reserve and the chain-wide pending list slot into the existing selection path.

newchanged

4-minute explainer

What changed

Gas reserve per token

Gas-asset outbounds leave mimir × MaxGas per held token.

reservespendablegas in vault holding USDT

Fallback without reserve

Leftover or sub-fee tail → re-run exactly as with the key off.

pass 1 · reserveremainder or fragment?key-off selection

Chain-wide pending outbounds

Key on: every queued outbound on the chain counts, except in the fallback.

off: same asseton: whole chain

Off by default

Key at 0: same vault choice, one extra KV read.

vault choice unchanged+1 mimir read → gas_usedno migration

State + upgrade

Mimirs

  • newVaultTokenGasReserve0

Keeper interface

KeeperVault
+ GetPendingOutboundsByChain

Line by line · every changed logic line, narrated

8:04runtime
8code chapters
100%logic lines narrated (255/255)
9flagged spots
speed

Chapters

What to check

Ask an AI about this change

Chat assistantClaude, ChatGPT, … (reads a link)

Coding agentClaude Code, Cursor, … (reads the repo)

The context file is context.md. Use Copy with context for an AI that can't open links; it pastes the whole file in.

Glossary

Asgard vault
A TSS-controlled vault that holds L1 funds; active ones are preferred over retiring ones for outbounds.
Fragment
An output of a multi-vault split below outbound fee plus dust; prepareTxOutItem would drop it, so the reserve pass gives way to the key-off selection. manager_txout_current.go ↗
Gas asset
A chain's native fee coin (ETH, TRX); tokens on that chain (USDT, USDC) need it to move.
MaxGas
The most gas one outbound on a chain may spend; vault selection keeps at least this much gas asset. manager_txout_current.go ↗
Mimir
On-chain key/value overrides voted by node operators; VaultTokenGasReserve is a new one, default 0. docs/mimir.md ↗
Pending outbounds
Queued, unsigned txout items; their amounts and MaxGas are subtracted from vault balances before selection. keeper_vault.go ↗
Ragnarok
Shutting down a chain or pool and sweeping its funds out; it never holds a reserve back.
VaultTokenGasReserve
MaxGas multiples a vault keeps per non-gas token when picked for a gas-asset outbound; above 0 also makes pending outbounds chain-wide, except in the fallback. constants_v1.go ↗