LogoLogo
  • ๐ŸŒŠSuperfluid
  • Protocol Overview
    • ๐Ÿ’กWhat is Superfluid?
    • ๐Ÿ“„In-Depth Overview
      • Super Tokens
      • Super Agreements
        • ๐ŸšฐMoney Streaming (CFA)
        • โœณ๏ธDistributions (IDA)
        • ๐ŸŒŠStreaming Distributions
      • Super Apps
      • Superfluid Host
    • ๐Ÿง Use Cases
      • Recurring Payments
      • DeFi
      • Social & Community
      • Gaming
    • ๐Ÿ“”Glossary of Terms
  • Developers
    • ๐ŸƒQuickstart
    • ๐Ÿช™Super Tokens
      • Super Tokens - Solidity
      • Super Tokens - SDK Core
      • Super Tokens - Frontend Examples
      • Types of Super Tokens
      • Deploy a Super Token
        • Deploying a Wrapper Super Token
        • Deploying a Self Governed Super Token
        • Deploying a Pure Super Token
      • In-Depth
        • Tracking Super Token Balances
        • ERC777 in Super Tokens
      • Test Super Token Faucet
    • ๐ŸŒŠMoney Streaming (CFA)
      • Solidity
        • Read Methods
          • getFlowInfo
          • getFlowRate
          • getNetFlowRate
        • Write Methods
          • createFlow
          • updateFlow
          • deleteFlow
          • With User Data
          • With Context
      • SDK Core
        • Read Methods
          • getFlow
          • getNetFlow
          • getAccountFlowInfo
        • Write Methods
          • createFlow
          • updateFlow
          • deleteFlow
      • Access Control List (ACL)
        • Solidity
          • createFlowFrom
          • updateFlowFrom
          • deleteFlowFrom
          • setFlowPermissions
          • setMaxFlowPermissions
          • revokeFlowPermissions
          • increaseFlowRateAllowanceWithPermissions
          • decreaseFlowRateAllowanceWithPermissions
          • getFlowPermissions
        • SDK Core
          • createFlowByOperator
          • updateFlowByOperator
          • deleteFlowByOperator
          • updateFlowOperatorPermissions
          • revokeFlowOperatorPermissions
          • increaseFlowRateAllowanceWithPermissions
          • getFlowOperatorData
      • Frontend Examples
      • More...
        • Flow Rate Time Frames
        • Building Batched Streams in Safe
        • Flow NFTs
    • โœณ๏ธDistributions (IDA)
      • IDA - Solidity
      • IDA - SDK Core
      • IDA - Frontend Examples
    • ๐Ÿค–Super Apps
      • Super Apps in Depth
      • Super App Callbacks
        • Calling Agreements In Super Apps
      • User Data
        • NFT Billboard Example
      • SuperAppBaseFlow
      • Super App Examples
      • Super App Deployment Guide
    • ๐ŸงบBatch Calls
      • Batch Calls - SDK Core
      • Batch Calls - Frontend Examples
    • โš™๏ธAutomations
      • Auto-Wrap
        • Dev Guide
      • Stream Scheduler
        • Dev Guide
      • Vesting Scheduler
        • Dev Guide
      • Stream Accounting API
        • Dev Guide
      • Automation Subgraphs
        • Stream Scheduler Subgraph
        • Vesting Scheduler Subgraph
        • Auto Wrap Subgraph
    • ๐Ÿ—๏ธIntegration Guides
      • For Your Integration: The Basics
        • Supporting Super Tokens
        • Supporting Money Streams
        • Supporting Instant Distributions
      • Gating with Superfluid Subscriptions & Guild.xyz
      • Displaying Token Balances
      • Useful Queries for Your Integration
        • Instant Distribution Events
        • Money Streaming Events
        • Super Token Events
        • Other Helpful Queries
      • Constructing Links to The Superfluid Dashboard
    • ๐Ÿ”Superfluid Subscriptions
      • Superfluid Checkout Widget
      • Implementing Subscriptions in your App
    • SDK Core General
      • Initialization
      • Functionality
      • Getting Data
      • Resolver
      • Reference Docs
    • Solidity General
      • Calling Super Agreements
      • Libraries
      • Resolver
    • Testing Guide
      • Hardhat Testing
      • Foundry Testing
      • In-Depth
        • Hardhat Mainnet Fork Testing
        • Super App Testing on Mainnet Forks
    • Subgraph
    • Reference
      • Deploying The Framework
      • EVM Contracts
      • SDK Redux
      • Superfluid Console
      • Superfluid Protocol Addresses
    • Contract Addresses
  • Sentinels
    • ๐Ÿฅ…Liquidations & TOGA
    • ๐Ÿค–Running a Sentinel
    • ๐Ÿ—บ๏ธSolvency Dashboard
  • Resources
    • ๐ŸŒŠSuperfluid Wave Pool
    • ๐Ÿ“œSuperfluid on Ethereum Mainnet
    • ๐Ÿ’ฐBounty Program
    • ๐Ÿ›ก๏ธSecurity & Bug Bounties
    • ๐Ÿ’กProject Ideas
    • ๐Ÿ—ณ๏ธToken Dashboard Submission
    • ๐ŸŽฅVideos
    • Superfluid Deployment Guide
    • Learn about Ethereum
    • Code of Conduct
Powered by GitBook
On this page
  • Agreement Abstraction
  • Importing and Initialization
  • Basic Usage
  • Callback Usage
  • API Specification

Was this helpful?

  1. Developers
  2. Distributions (IDA)

IDA - Solidity

The Super Token Library allows you to work with instant distributions in Solidity

PreviousDistributions (IDA)NextIDA - SDK Core

Last updated 2 years ago

Was this helpful?

SuperTokenV1Library Contract

Example Code & Guide

Agreement Abstraction

The objective of the SuperTokenV1Library is to abstract the code required to call an agreement. Below is a comparative example of how an index might be created with and without the library.

function createWithoutLibrary() external {
    _host.callAgreement(
        _ida,
        abi.encodeWithSelector(
            _ida.createIndex.selector,
            publisher,
            indexId,
            new bytes(0)
        ),
        new bytes(0)
    );
}

function createWithLibrary(ISuperToken token) external {
    token.createIndex(indexId);
}

Importing and Initialization

import {
    ISuperfluid,
    ISuperToken
} from "@superfluid-finance/ethereum-contracts/contracts/interfaces/superfluid/ISuperfluid.sol";

import {
    IInstantDistributionAgreementV1
} from "@superfluid-finance/ethereum-contracts/contracts/interfaces/agreements/IInstantDistributionAgreementV1.sol";

import {
    SuperTokenV1Library
} from "@superfluid-finance/ethereum-contracts/contracts/apps/SuperTokenV1Library.sol";

contract MyContract {
    // use the SuperTokenV1Library for the ISuperToken type
    using SuperTokenV1Libary for ISuperToken;
    
    ISuperToken public token;
    
    constructor(
        ISuperToken _token,
    ) {
       
       token = _token
    }
    
    // your code here...
}

Basic Usage

Once this is initialized, we can use the library to create, read, update, and delete IDAv1 agreements as demonstrated in this createIndex example.

function myFunction(ISuperToken token, uint32 indexId) {
    token.createIndex(indexId);
}

Callback Usage

To use this library inside of a Super App callback, you will need to use the equivalent function with WithCtx at the end of it. For example, instead of creating an index in a callback with createIndex, you should use createIndexWithCtx and return the result, newCtx, of type bytes memory.

function afterAgreementCreated(
    ISuperToken superToken,
    address /*agreementClass*/,
    bytes32 /*agreementId*/,
    bytes calldata /*agreementData*/,
    bytes calldata /*cbdata*/,
    bytes calldata ctx
} external override returns (bytes memory newCtx) {

    require(msg.sender == address(host), "only host");
    uint32 indexId = 0;
    return superToken.createIndexWithCtx(indexId, ctx);

}

API Specification

The following documents the library function's declaration along with the usage the function, assuming the InitData struct is named _idav1Lib.

Each function has four variants:

  1. First is the standard function shown in the Basic Usage section above.

  2. Second is an override of the standard usage to include arbitrary user data.

  3. Third is the WithCtx function shown in the Callback Usage section above.

  4. Fourth is an override of the WithCtx function to include arbitrary user data.

Note that each function below includes the "library function declaration". This is not necessary to write in your own code and is simply there for reference. The code following "usage" is what you would write in your own contract.

For more information on each parameter, please refer to the code comment documentation for each function in the library.

Create Index

Creates an index with a super token and an index id. The function caller is the publisher of the index.

// library function declaration
function createIndex(
    ISuperToken token,
    uint32 indexId
) internal;

// usage
token.createIndex(indexId);

Create Index with User Data

// library function declaration
function createIndex(
    ISuperToken token,
    uint32 indexId,
    bytes memory userData
) internal;

// usage
token.createIndex(indexId, userData);

Create Index in a Super App Callback

// library function declaration
function createIndexWithCtx(
    ISuperToken token,
    uint32 indexId,
    bytes memory ctx // ctx passed to the callback function
) internal returns (bytes memory newCtx);

// usage
return token.createIndexWithCtx(indexId, ctx);

Update Index Value

Updates the value of the index. This updates the real time balances of all approved subscribers in a single transaction. Notice that this is similar to distribute, except here you must specify the new total index value in the indexValue parameter. This fails if it is not greater than the last index value.

// library function decalaration
function updateIndexValue(
    ISuperToken token,
    uint32 indexId,
    uint128 indexValue
) internal;

// usage
token.updateIndexValue(indexId, indexValue);

Update Index Value with User Data

// library function declaration
function updateIndexValue(
    ISuperToken token,
    uint32 indexId,
    uint128 indexValue,
    bytes memory userData
) internal;

// usage
token.updateIndexvalue(indexId, indexValue, userData);

Update Index Value in a Super App Callback

// library function declaration
function updateIndexValueWithCtx(
    ISuperToken token,
    uint32 indexId,
    uint128 indexValue,
    bytes memory ctx,
) internal returns(bytes memory newCtx);

// usage
return token.updateIndexValueWithCtx(indexId, indexValue, ctx);

Update Index Value in a Super App Callback

// library function declaration
function updateIndexValueWithCtx(
    ISuperToken token,
    uint32 indexId,
    uint128 indexValue,
    bytes memory ctx,
) internal returns(bytes memory newCtx);

// usage
return token.updateIndexValueWithCtx(indexId, indexValue, ctx);

Distribute

This function is functionally similar to updateIndexValue, but instead of having to specify the new indexValue, you can pass an amount by which the indexValue should be incremented. This is simply another way to distribute tokens.

// library function declaration
function distribute(
    ISuperToken token,
    uint32 indexId,
    uint256 amount
) internal;

// usage
token.distribute(indexId, amount);

Distribute with User Data

// library function declaration
function distribute(
    ISuperToken token,
    uint32 indexId,
    uint256 amount,
    bytes memory userData
) internal;

// usage
token.distribute(indexId, amount, userData);

Distribute in a Super App Callback

// library function declaration
function distributeWithCtx(
    ISuperToken token,
    uint32 indexId,
    uint256 amount,
    bytes memory ctx,
) internal returns (bytes memory newCtx);

// usage
return token.distributeWithCtx(indexId, amount, ctx);

Approve Subscription

Approves a subscription to an index. This is called by the subscriber to the index and can be called even before units are issued to the subscriber, though the index must at least exist first.

// library function declaration
function approveSubscription(
    ISuperToken token,
    address publisher,
    uint32 indexId
) internal;

// usage
token.approveSubscription(publisher, indexId);

Approve Subscription with User Data

// library function declaration
function approveSubscription(
    ISuperToken token,
    address publisher,
    uint32 indexId,
    bytes memory userData
) internal;

// usage
token.approveSubscription(publisher, indexId, userData);

Approve Subscription in a Super App Callback

// library function declaration
function approveSubscriptionWithCtx(
    ISuperToken token,
    address publisher,
    uint32 indexId,
    bytes memory ctx,
) internal returns (bytes memory newCtx);

// usage
return token.approveSubscriptionWithCtx(publisher, indexId, ctx);

Revoke Subscription

Revokes a previously approved subscription. This is called by the subscriber.

// library function declaration
function revokeSubscription(
    ISuperToken token,
    address publisher,
    uint32 indexId
) internal;

// usage
token.revokeSubscription(publisher, indexId);

Revoke Subscription with User Data

// library function declaration
function revokeSubscription(
    ISuperToken token,
    address publisher,
    uint32 indexId,
    bytes memory userData
) internal;

// usage
token.revokeSubscription(publisher, indexId, userData);

Revoke Subscription in a Super App Callback

// library function declaration
function revokeSubscriptionWithCtx(
    ISuperToken token,
    address publisher,
    uint32 indexId,
    bytes memory ctx,
) internal returns (bytes memory newCtx);

// usage
return token.revokeSubscriptionWithCtx(publisher, indexId, ctx);

Update Subscription Units

Updates the number of units, or "shares", of the index assigned to a subscriber. This is called by the publisher of the index.

// library function declaration
function updateSubscriptionUnits(
    ISuperToken token,
    uint32 indexId,
    address subscriber,
    uint128 units
) internal;

// usage
token.updateSubscriptionUnits(indexId, subscriber, units);

Update Subscription Units with User Data

// library function declaration
function updateSubscriptionUnits(
    ISuperToken token,
    uint32 indexId,
    address subscriber,
    uint128 units,
    bytes memory userData
) internal;

// usage
token.updateSubscriptionUnits(indexId, subscriber, units, userData);

Update Subscription Units in a Super App Callback

// library function declaration
function updateSubscriptionUnitsWithCtx(
    ISuperToken token,
    uint32 indexId,
    address subscriber,
    uint128 units,
    bytes memory ctx,
) internal returns (bytes memory newCtx);

return token.updateSubscriptionUnitsWithCtx(indexId, subscriber, units, ctx)

Delete Subscription

Deletes an existing subscription, setting the subscriber's units to zero. This is called by the publsiher.

// library function declaration
function deleteSubscription(
    ISuperToken token,
    address publisher,
    uint32 indexId,
    address subscriber
) internal;

// usage
token.deleteSubscription(publisher, indexId, subscriber);

Delete Subscription with User Data

// library function declaration
function deleteSubscription(
    ISuperToken token,
    address publisher,
    uint32 indexId,
    address subscriber,
    bytes memory userData
) internal;

// usage
token.deleteSubscription(publisher, indexId, subscriber, userData);

Delete Subscription in a Super App Callback

// library function declaration
function deleteSubscriptionWithCtx(
    ISuperToken token,
    address publisher,
    uint32 indexId,
    address subscriber,
    bytes memory ctx,
) internal returns (bytes memory newCtx);

// usage
return token.deleteSubscriptionWithCtx(publisher, indexId, subscriber, ctx);

Claim

Claims a pending distribution of an index. This is called by the subscriber and updates their real time balance instantly.

// library function declaration
function claim(
    ISuperToken token,
    address publisher,
    uint32 indexId,
    address subscriber
) internal;

// usage
token.claim(publisher, indexId, subscriber);

Claim with User Data

// library function declaration
function claim(
    ISuperToken token,
    address publisher,
    uint32 indexId,
    address subscriber,
    bytes memory userData
) internal;

// usage
token.claim(publisher, indexId, subscriber, userData);

Claim in a Super App Callback

// library function declaration
function claimWithCtx(
    ISuperToken token,
    address publisher,
    uint32 indexId,
    address subscriber,
    bytes memory ctx,
) internal returns (bytes memory newCtx);

// usage
return token.claimWithCtx(publisher, indexId subscriber, ctx);
โœณ๏ธ
Logoprotocol-monorepo/SuperTokenV1Library.sol at dev ยท superfluid-finance/protocol-monorepoGitHub
Logosuper-examples/projects/instant-distribution-intro at main ยท superfluid-finance/super-examplesGitHub
Simple contract showing usage of many IDA functions