The Super Token Library allows you to work with instant distributions in Solidity
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.
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 typeusingSuperTokenV1LibaryforISuperToken; 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.
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.
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:
First is the standard function shown in the Basic Usage section above.
Second is an override of the standard usage to include arbitrary user data.
Third is the WithCtx function shown in the Callback Usage section above.
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 declarationfunctioncreateIndex(ISuperToken token,uint32 indexId) internal;// usagetoken.createIndex(indexId);
Create Index with User Data
// library function declarationfunctioncreateIndex(ISuperToken token,uint32 indexId,bytesmemory userData) internal;// usagetoken.createIndex(indexId, userData);
Create Index in a Super App Callback
// library function declarationfunctioncreateIndexWithCtx(ISuperToken token,uint32 indexId,bytesmemory ctx // ctx passed to the callback function) internalreturns (bytesmemory newCtx);// usagereturn 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 decalarationfunctionupdateIndexValue(ISuperToken token,uint32 indexId,uint128 indexValue) internal;// usagetoken.updateIndexValue(indexId, indexValue);
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 declarationfunctiondistribute(ISuperToken token,uint32 indexId,uint256 amount) internal;// usagetoken.distribute(indexId, amount);
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 declarationfunctionapproveSubscription(ISuperToken token,address publisher,uint32 indexId) internal;// usagetoken.approveSubscription(publisher, indexId);