When a protocol fails
A vault invests your USDC in other protocols, such as lending markets and yield-bearing tokens. Each of those protocols can fail. This section explains, situation by situation, what the vault program does when that happens, who acts, and what it means for Senior and Junior holders.
Every situation described here is checked by automated tests. The tests run the vault program against test protocols and against copies of the real protocols' programs and accounts taken from Solana mainnet. Where a page gives measured figures, they come from those tests and are rounded.
The words you need first
A few terms appear on every page of this section. The glossary has more.
- Leg. One investment position of the vault, for example "USDC lent on Kamino". A vault can have up to 8 legs; the program does not allow more.
- Adapter. A small Solana program that connects the vault to one protocol. It deposits, withdraws and, most importantly, reports what the leg is worth.
- Valuation report. The adapter's answer to "what is this leg worth?" It contains three numbers in USDC: a cautious low value (roughly what the leg would fetch if it were sold now,
value_low), a book value (the protocol's own accounting value,value_mid) and a high value (an upper bound,value_high). The range from low to high is the leg's band. A report can also carry warning flags. - Freshness. Before the vault mints or burns shares, every leg that holds money must have been valued recently. Each vault sets its own limit in Solana slots, and the program allows at most 150. A slot is one Solana block, roughly 400 milliseconds, so 150 slots is about one minute.
- Guardian. A key, set per vault, that can only make the vault safer: pause it, mark a leg down, or suspend a leg. It cannot move money or raise any limit.
- Recovery. A vault state that starts after a large loss. New deposits and new investments stop while the incident is handled.
- Coverage. Junior's share of the vault's total value. Junior absorbs losses first, so coverage measures how much protection Senior has. Each vault sets a minimum coverage, and a Junior withdrawal that would take coverage below it is refused.
Why the vault needs incident rules
The vault program can only see what an adapter reports. It cannot read a news feed or know that a protocol was exploited an hour ago. So the program combines automatic rules with a human role:
- Automatic rules handle what the numbers show. A reported loss is booked at once, Junior first. A value that jumps up is accepted only slowly. A report that is malformed or flagged is refused.
- The guardian handles what the numbers do not show. When a protocol is hacked but still reports its old value, only a person or an off-chain monitor can tell. The guardian then marks the leg down (caps its value at a number the guardian chooses), or suspends it (sets it aside with its last value) if it simply cannot be valued.
The five tools the vault uses
| Tool | What it does | Who triggers it |
|---|---|---|
| Booking a loss | Lowers Junior first, then Senior, as soon as a lower value is reported | Anyone, through refresh_leg and sync_vault |
| Freshness check | Stops deposits, withdrawal funding and investment moves when a leg has not been valued for too long | Automatic |
| Impairment mark | Caps a leg's value at a number the guardian chooses (0 writes it off) and starts Recovery | Guardian or admin, mark_leg_impaired |
| Suspension | Sets aside a leg that cannot be valued, keeps its last value and lets the rest of the vault keep working | Guardian or admin, suspend_leg and unsuspend_leg |
| Settlement | Winds the vault down and pays out recovered cash, Senior first | Admin, begin_settlement |
Table: the five mechanisms that every situation in this section is built from.
How a failure reaches you
The flowchart below shows the path from "something is wrong with a protocol" to what happens with your shares.
flowchart TD
A[Something goes wrong in a protocol] --> B{Does the adapter's report show it?}
B -- "Yes: a lower value" --> C[Loss is booked at once, Junior first]
C --> D{Is the loss above the incident threshold<br/>or does it reach Senior?}
D -- No --> E[Vault stays Active]
D -- Yes --> F[Vault enters Recovery]
B -- "Yes: an error, a flag or a malformed report" --> G[The leg cannot be refreshed]
G --> H[About one minute later the leg is stale<br/>and the whole vault stops share changes]
H --> I{Guardian acts}
I -- "suspend_leg" --> J[Vault runs again,<br/>leg keeps its last value]
I -- "mark_leg_impaired" --> F
B -- "No: the books still look normal" --> K[Vault keeps running at the old value]
K --> L[Guardian learns of it off-chain<br/>and calls mark_leg_impaired]
L --> F
F --> M{Can the money come back?}
M -- "Yes" --> N[Returned value repays Senior,<br/>then Junior, then the admin resumes]
M -- "No" --> O[Admin starts Settlement:<br/>cash is paid Senior first]Figure: the three ways a protocol failure becomes visible to the vault, and where each one leads.
The key takeaway is that there are three different starting points. A loss the adapter reports is handled automatically. A protocol that stops answering freezes the vault until the guardian acts. A hack that the protocol's own books do not show needs the guardian to notice it.
The example vault used on these pages
The examples in this section start from the same small vault, unless a page says otherwise. The numbers are illustrative and chosen to keep the arithmetic easy:
| Item | Amount |
|---|---|
| Junior, held by June | 1,000 USDC |
| Senior, held by Alice | 4,000 USDC |
| Invested in the leg the example is about | 3,000 USDC |
| Idle cash in the vault (5,000 − 3,000) | 2,000 USDC |
| Coverage (Junior ÷ total) | 1,000 ÷ 5,000 = 20% |
| Minimum coverage set for this vault | 20% |
Table: the example vault; its coverage starts exactly at its minimum, so any Junior loss blocks Junior withdrawals.
Alice and June are example holders: Alice holds Senior and June holds Junior. Amounts are in whole USDC; the program itself counts in base units of 0.000001 USDC, because USDC has 6 decimal places.
Situations covered
| What happens | Page |
|---|---|
| The protocol honestly reports a lower value | An honest loss |
| A hack is discovered and the guardian marks the leg | A hack the protocol has not reported |
| Money is stolen, but the protocol's books still show it | A hack nobody has noticed yet |
| The protocol stops answering, and the guardian suspends the leg | A protocol stops working |
| The protocol answers with wrong data | Wrong or manipulated data |
| A stablecoin or receipt token loses its peg | Depegs |
| An exit was already in progress when trouble started | Exits in flight |
| The issuer of a token freezes, takes or changes it | The token issuer acts |
| Several legs fail at once, or a failure spreads | Several legs at once |
| An adapter is upgraded or called with the wrong accounts | Adapter changes |
Table: every situation in this section and the page that explains it.
For a view by protocol instead of by situation, read Protocol by protocol.
How the behaviour is checked
The tests answer three different questions.
- Do the vault's own rules hold? Tests run the vault against simple test programs: a lending market, an adapter that reports whatever the test asks, and a program that fails on purpose.
- Can each real protocol fail in these ways? Tests confirm, for example, that pausing Kamino really makes its adapter refuse to value the leg.
- How does each real adapter behave? Tests run the same situations on copies of the real protocols' programs and accounts, taken from Solana mainnet.
Every transaction in every test is also checked automatically: the books must balance, USDC must be conserved across all known accounts, no withdrawal may be paid above the cautious price, and a failed transaction must change nothing. A further check fails if a situation that an adapter supports has no test.
What this section does not promise
These pages describe the program's rules and what the tests show. They do not promise that a loss will be recovered, that the guardian will act within a given time, or that every possible failure has a test. A failure of the vault program itself is a different risk, described in Vault risks.