Superfluid Host Overview

Superfluid host contract (Superfluid.sol) is the central contract that provides the following functionalities in the Superfluid framework:

Agreement System

First of all agreements are whitelisted, since a super token trusts them to provide real-time balance to their accounts.

The agreement framework consists of functions in the host contract that can only be called by a whitelisted agreement to:

• call the agreement callbacks of a super app,

• perform app credit accounting,

• jail a super app if it poses danger to the system or users.

To interact with the agreement, the call proxies of the host contract are used.

Super Token Factory

Super tokens can be created through the super token factory registered in the host contract. By doing so, the super token created delegates its logic contract update process to the governance process.

Note that, super tokens created not through the factory can still use the host contract.

App Registry

[[Super apps|About Super App] compose agreements and business logic together.

A contracts may opt-in being a super app through the app registry provided by the host contract.

Call Proxies

Call proxies is a technical to provide a transactional, secure and efficient heap-like shared memory data in EVM called "stamped Ctx" for both agreements and super app actions.

**** TO BE MOVED OLD NOTES ****

Batch Call

Super Agreement

Key features:

• Allow new agreement class to be whitelisted.
• callAgreement (contextless + contextual).
• IAgreementFramework:
  • for callbacks: callAppBeforeCallback, callAppAfterCallback, appCallbackPush, appCallbackPop
  • ctxUseAllowance: for app credit.
  • jailApp: for jail rules.

Design Points:

• Agreement Whitelisting:

  • No choice.

• Polymorphic agreement support:

  • No polymorphic approach: always add new entry functions for new agreement in host contract.
    • Pros: avoid duck tapes (hence type-safe)
    • Cons: more boiler plate.
  • callAgreement: duck tape "polymorphic" solution.
    • Pros: extremely flexible.
    • Cons: type-unsafe, may have security implications when handling calldata.
  • Better approach, e.g. "spec-haskell" type class, define AgreementOperation instances.
    • Pros: CORRECT WAY OF DOING THINGS.
    • Cons: not supported by dumb languages.

• App Jail:

  • Main objective: make sure that agreement is always destructible.
  • Zero tolerance jail:fdd
    • assuming hostile app,
    • being over protective to users so that they don't continue to interact with the callbacks.

Super App

Key Features:

• App Registry

  • Whitelisting modes:
    • registerAppWithKey
    • registerAppByFactory
    • [TODO] whitelistedDeployerWithExpirationDate

• Composability:

  • App Level
  • Callbacks
  • App Credit

• Ctx: transactional secure heap-memory in EVM

Design Points:

• App Registry:

  • whitelisting: to be removed as soon as we feel fit.

• Composability:

  • State Sync: Callbacks vs Async
  • App Credit:
    • objective: zero balance super app requirement for reasonable cases.
    • benchmark case: 1to1 flow forwarding.
  • App Level:
    • 1-level ~= global re-entrance protection

Extra Notes

• function overload: use or not use?
• function pointer: worth exploring a bit.
• more usage of user types: worth exploring in the future.
• generics: let's wait and see.