About Buffer

A Superfluid Agreement can be an open-ended relationships between parties, e.g. ConstantFlowAgreement allows an open-ended constant flow between Bob and Alice. But Bob can run out of liquidity to sustain the flow, that's where Solvency Network comes in place to protect the network from insolvent accounts.

For the solvency network to have enough time to handle critical accounts and prevent them from becoming insolvent, the concept of "Buffer" is introduced. In order to do this, the Superfluid Agreement can take a deterministic amount of tokens as buffer (set by a governance parameter) from an user whereby the user may lose them if they don't fulfill certain obligations, e.g. delete his flow before he runs out of liquidity.

Terms:

• critical: when the availableBalance of the user is below 0.
• insolvent: when the availableBalance and sum of deposits is below 0 or Buffer drainage is below 0.

Note: In the code base, buffer is still referred to as deposit.

CFA Buffer Usage

Liquidation Period

Current design:

• A Governance parameter: CFAV1_PPP_CONFIG_KEY.
• Buffer is paid in the same token as the flow.
• Testnet: 1 hour; Mainnet: 4 hours.

Ideas:

• We need a universal estimateBuffer akin to the estimateGas in web3.
  • Short-cut: to use a upper-bound buffer estimation
• Alternative design using gas coin for buffer:
  • use “gas tank”,
  • or “payable” function everywhere to pay for them.

Buffer Drainage

The speed of the CFA Buffer drainage is a function of net flow rate of an account:

• When the account available balance is negative, the account is "critical",
• when the buffer runs out, the account is "insolvent",
• otherwise the account is "solvent", and "normal".

Buffer drainage RBis defined as 100 * (CFA Buffer remaining of the account / Total CFA buffer of the account) %.

PPP Liquidation Rules

The rule that determines who should get the remaining buffer of an account is called the "liquidation rules".

The current liquidation rules is dubbed as "PPP" or "3Ps":

"PPP: Patrician, Pleb, Pirate", but in the long run they are all dead Pepes.

• Liquidation period is configured in SuperfluidGovernanceConfigs.CFAV1_PPP_CONFIG_KEY instead.
• Patrician is configured in SuperfluidGovernanceConfigs.SUPERFLUID_REWARD_ADDRESS_CONFIG_KEY.
• Patrician period is also configured in SuperfluidGovernanceConfigs.CFAV1_PPP_CONFIG_KEY.
• Pleb period is then defined as when the buffer drainage has exceeded 100 (Patrician period / Liquidation period) %: when the account is in an insolvent state.
• Private period is then defined as when account is insolvent.

Buffer Clipping

TODO...

Minimum buffer:

Since the high granularity allows for the creation of streams with very small flow rate, it's possible to have streams with a buffer which doesn't cover the transaction cost of its liquidation.
In order to mitigate this, the protocol supports the option to configure minimum amounts for the buffer (aka minimum deposit). This amount can be set per token by governance, the amount is denominated in the respective token, see the Minimum Deposit Policy.

Buffer Examples

TODO...

Scribbling Notes from Protocol forum to be cleaned up

    - In order to cover minimum gas cost for sentinel.
    - Governance configuration per super token (default is 0).
    - Some sort of dynamic configuration is not yet in current implementation.
- PPP (Patrician/TOGA PIG, Pleb, Pirate) Rules
    - Simple: one outgoing stream account: 1 per hour outgoing = netflow -1 per hour; buffer is 4
        - it takes 4 hours to drain the deposit.
        - after the account becoming negative:
            - 0 to 1/16th buffer used, 0 to 15 minutes: patrician
            - 1/16 to 1 buffer used, 15 minutes to 4 hours: pleb
            - afterwards, pirate
    - Multiple streams case 1, 1 per hour outgoing + 0.5 per hour incoming = netflow -0.5 per hour; buffer is 4
        - it takes 8 hours to drain the deposit.
        - after the account becoming negative:
            - 0 - 1/16th buffer used; 0 to 30 minutes: patrician
            - 1/16 to 1 buffer used, 15 minutes to 8 hours: pleb
            - afterwards: pirate
    - Multiple streams case 2, 1 per hour outgoing + 1 per hour outgoing + 1 per hour incoming = netflow -1 per hour; ~~total outgoing 2 per hour; total incoming 1 per hour;~~ buffer is 8
        - it takes 8 hours to drain the deposit.
        - after the account becoming negative:
            - 0 - 1/16th buffer used; 0 to 30 minutes: patrician
            - 1/16 to 1 buffer used, 15 minutes to 8 hours: pleb
            - afterwards: pirate
    - Multiple streams case 3, 1 per hour outgoing + 1 per hour incoming + account balance negative = netflow 0; buffer is (somewhat less than) 4
        - it takes forever to drain the deposit.
        - after the account becoming negative:
            - the account is stuck in patrician, pleb or pirate period depending on how much deposit is left.
    - Other notes:
        - “after the account becoming negative:” ← this information is not on-chain, but might be very useful to make the calculation more straightforward.

IDA Buffer Usage

Due to a design shortcut and now a mistake, IDA also uses Buffer for "withholding" amount of tokens for index publisher before its index subscribers claim or approved the index. A review of the RTB structure will rectify this error.

GDA will need to use the buffer concept though.