About Agreement Framework

The agreements provide rich payment primitives to Super Tokens.

Under the hood, each agreement implements a simple interface ISuperAgreement and its main function realtimeBalanceOf:

    /**
     * @dev Calculate the real-time balance for the account of this agreement class
     * @param account Account the state belongs to
     * @param time Time used for the calculation
     * @return dynamicBalance Dynamic balance portion of real-time balance of this agreement
     * @return deposit Account deposit amount of this agreement
     * @return owedDeposit Account owed deposit amount of this agreement
     */
    function realtimeBalanceOf(
        ISuperfluidToken token,
        address account,
        uint256 time
    )
        external
        view
        returns (
            int256 dynamicBalance,
            uint256 deposit,
            uint256 owedDeposit
        );

A Super Token then simply iterates through its supported agreements and sum the values from realtimeBalanceOf as its balanceOf output.

Agreement Calls Host

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

• call the agreement callbacks (see "Agreement Life Cycle") of a super app,

• assist with app credit accounting,

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

User Interact with Agreements

The legacy way of interacting with the agreement is through the public-facing call proxies of the host contract.

Moving to a more token-centric design, these public-facing call proxies are being phased out, in favor of more ergonomic temporary solutions such as agreement forwarders.

Agreement Whitelisting

Agreements are whitelisted, since a super token trusts them to provide real-time balance to their accounts.

Agreement Life Cycle (aka. Hooks/Callbacks)

Here are the callbacks that the hooks for the life cycles of agreement data:

$ cat contracts/interfaces/superfluid/ISuperApp.sol  | grep function
    function beforeAgreementCreated(
    function afterAgreementCreated(
    function beforeAgreementUpdated(
    function afterAgreementUpdated(
    function beforeAgreementTerminated(
    function afterAgreementTerminated(

A Note From V2

In v1, the agreement is the main building blocks for new payment primitives. However this creates artificial silos between agreements. In v2, instead, design is centered around the payment primitives where data and function design can be shared between different these primitives.