🥅
Liquidations & TOGA

How does Superfluid keep streams solvent? Who's job is it?
Liquidation and Solvency
When opening a stream, the protocol will take a small buffer or deposit. By leaving their streams open for too long, stream creators stand to lose this buffer. This mechanism creates the main incentive for users to close their Superfluid streams before running out of tokens. It is a user's own responsibility to close their stream.
superApps can also draw an owedDeposit, allowing them to open a stream of the same size, without needing an initial balance.
Here's the general flow of solvency states for Super Tokens in a Constant Flow Agreement:
1. Solvent
Everyone is in good standing. The sender's balance is greater than 0. The stream flows to the receiver as expected, and there are enough tokens to back the stream.
2. Critical
The sender's balance is now zero, and the permissions on the stream now allow anyone to close it. Until the stream is actually closed, funds are paid to the receiver's wallet using the sender's initial buffer.
The critical period is subdivided into 2 sub-periods:
a) Patrician Period: starts when the stream becomes critical (duration defined as governance parameter)
b) Plebs Period: spans the remaining timeframe until the stream becomes insolvent
When the stream is closed, any remaining buffer is taken and assigned/distributed either to the PIC or a Pleb.
If the stream is closed during the Plebs Period, we call the account closing the stream a Pleb.
3. Insolvent
If the stream isn't closed, and the sender's deposit is completely consumed, then the insolvent period begins. The stream will continue to the receiver, however since these tokens don't actually exist in the sender's wallet, we must keep track of this deficit so that the Super Token itself can remain solvent within the Superfluid Protocol.
We also call this open ended timeframe the Pirate Period.
When the stream is eventually closed, the deficit is taken from the PICs stake as a slashing fee. This slashing fee is then burned, to offset the tokens created by the insolvent stream. Additionally, a reward equal in amount to the buffer amount before its consumption is issued to the account closing the stream, whom we call a Pirate.. This reward is also detracted from the PICs stake.
Patricians, Plebs and Pirates (3Ps)
Each token has an account called a PIC (Patrician in Charge).
Every time a stream is closed while Critical during the Patrician Period, the remaining amount of the buffer balance of the closed stream is taken and added to the PICs stake as a reward.
Every time a stream is closed while Critical during the Plebs Period, the remaining buffer is rewarded to the Pleb.
Every time a stream is closed while Insolvent, the PIC is slashed, and the Pirate is rewarded with the full buffer amount.
The monopoly on rewards during the Patrician Period gives PICs an incentive to make sure streams are closed during that timeframe.
They can set up one or multiple redundant instances of the superfluid-sentinel (and/or other mechanisms for closing streams) to ensure this. Note that the PIC account is not needed (not in a hot wallet) for this operations as the rewards incurred during the patrician period will be added to the PIC stake regardless of transaction sender.
Plebs act as a fallback in case PICs fail to do their job despite of the incentives.
The earlier in the Pleb Period a Pleb closes the stream, the more buffer there's left as a reward.
Unlike the PIC, individual Plebs and Pirates don't have a monopoly. Whoever manages to get a stream closing transaction included first during the Plebs / Pirate Period, gets the reward.
Patrician, Pleb and Pirate are roles which map to accounts in specific circumstances.
The same account could have any of those roles in the context of various stream closing transactions, defined by the timing of that transaction and the state of the TOGA contract (list of PICs) at the time of transaction execution. The reference sentinel implementation provides configuration options influencing that behaviour and timing of transactions.
Note that thanks to this flexible roles model, PICs have an incentive to close streams even after missing the Patrician Period:
1.they can still get rewards, essentially acting as a Pleb or Pirate in the context of that transaction
2.due to the slashing of the deficit from their stake, their incentive to close insolvent streams grows linearly over time
Toga payoff table
TOGA - Transparent OnGoing Auction
Since the role of a PIC comes with a monopoly on rewards incurred during the Patrician Period, a fair mechanism for assigning this role is needed. Such a mechanism is provided by the TOGA.
To become a PIC for a token, aspiring Patricians must post a stake to the TOGA contract, in the token they are trying to become a PIC for. If the new stake is higher than the existing stake, the new Patrician becomes the PIC, and the previous Patrician gets their current stake back.
PICs can't remove their stake at will through a single transaction, but rather, they have to specify an exitRate, which defines the flowrate of a Stream to their account. The exitRate is also not completely arbitrary, it is limited such that the stake will remain above zero for at least a week.
All liquidation rewards are added to the stake, thus - depending on the exitRate set by the PIC and the number of size of streams becoming critical - the stake of a PIC could shrink, grow or stay the same over time. (The maximum allowed exitRate is calculated based on the worst case of no rewards being added during that timeframe.)
In order to become the PIC, you can either use the Dapp at https://toga.superfluid.finance/ or use ERC777.send() to post the desired stake to the TOGA contract - optinally with an exitRate set in the data parameter if you don't like the default exitRate. The TOGA contract implements an ERC777 callback for the auction mechanism.
!! CAUTION !! Do NOT use ERC20.transfer() for TOGA bids, because those may not trigger the needed callback in the future.
Current Parameters
Polygon
Gnosis Chain
Optimism
Arbitrum
Goerli
Deposit
4 hour deposit
4 hour maximum owedDeposit
30 minutes patrician period
TOGA
1 week minimum exitPeriod
4 week default exitPeriod
Deposit
4 hour deposit
4 hour maximum owedDeposit
30 minutes patrician period
TOGA
1 week minimum exitPeriod
4 week default exitPeriod
Deposit
4 hour deposit
4 hour maximum owedDeposit
30 minutes patrician period
TOGA
1 week minimum exitPeriod
4 week default exitPeriod
Deposit
4 hour deposit
4 hour maximum owedDeposit
30 minutes patrician period
TOGA
1 week minimum exitPeriod
4 week default exitPeriod
Deposit
1 hour deposit
1 hour maximum owedDeposit
12 minutes patrician period
TOGA
1 week minimum exitPeriod
4 week default exitPeriod
Note that this parameter definitions in terms of time units refer to simplified idealized scenarios and are basically lower bounds.

The deposit related timeframes directly apply for streams where the sender account has no incoming streams and where the net flowrate is thus equal to the outgoing flowrate. If however the sender account has incoming streams, this timeframes are stretched proportionally. If for example the aggregate incoming flowrate is half of the aggregate outgoing flowrate, the time for the buffer to be consumed (critial period) doubles, as do the patrician period and the plebs period. If the aggregate incoming flowrate equals the aggregate outgoing flowrate (net flowrate = zero), those periods become potentially infinite (as long as the net flowrate doesn't change), because in that case the buffer wouldn't be consumed further, but not restored either, leaving outgoing streams critical in perpetuity.

For the TOGA exitPeriod, something similar applies - it's the lower bound for how long it would take a PIC to stream out the stake with a given exitRate, assuming nothing is added to the stake during that time. In practice, accrued liquidation rewards may be added to the stake during that time, leading to a proportional extension of the exitPeriod. In theory such added rewards could even completely offset the exitRate, leading to a net growing stake. In that case the PIC could periodically increase the exitRate (a larger stake allows for a larger exitRate) and would eventually be able to set an exitRate which leads to a shrinking stake.
These parameters can be changed by Governance decision. Previously established deposit for Constant Flow Agreements is grandFathered, so future changes can't impact existing agreements.
The TOGA contract is set as the rewardAddress in the Superfluid host. The rewardAddress may be changed to a different address. Every SuperToken may have a different rewardAddress, so it's possible that different SuperTokens have different implementations.
Developers - Previous
Contract Addresses
Next - Sentinels
Running a Sentinel
Last modified 1d ago