IDAv1 Library

Search…
📕
IDAv1 Library
The IDAv1 Library is a thin layer of abstraction on the Instant Distribution Agreement V1. This guide covers how to import, initialize, and use the library, as well as documentation for each function.
Agreement Abstraction
The objective of the IDAv1Library 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.
1
function createWithoutLibrary() external {
2
    _host.callAgreement(
3
        _ida,
4
        abi.encodeWithSelector(
5
            _ida.createIndex.selector,
6
            publisher,
7
            indexId,
8
            new bytes(0)
9
        ),
10
        new bytes(0)
11
    );
12
}
13
​
14
function createWithLibrary() external {
15
    _idav1Lib.createIndex(publisher, indexId);
16
}
Copied!
Importing and Initialization
1
import {
2
    ISuperfluid
3
} from "@superfluid-finance/ethereum-contracts/contracts/interfaces/superfluid/ISuperfluid.sol";
4
​
5
import {
6
    IInstantDistributionAgreementV1
7
} from "@superfluid-finance/ethereum-contracts/contracts/interfaces/agreements/IInstantDistributionAgreementV1.sol";
8
​
9
import {
10
    IDAv1Library
11
} from "@superfluid-finance/ethereum-contracts/contracts/apps/IDAv1Library.sol";
12
​
13
contract MyContract {
14
    // use the IDAv1Library for the InitData struct
15
    using IDAv1Library for IDAv1Library.InitData;
16
    
17
    // declare `_idaLib` of type InitData
18
    IDAv1Library.InitData internal _idaLib;
19
    
20
    constructor(
21
        ISuperfluid host,
22
        IInstantDistributionAgreementV1 ida
23
    ) {
24
        // assign it the host and ida addresses
25
        _idav1Lib = IDAv1Library.InitData(host, ida);
26
    }
27
    // ...
28
}
Copied!
First, we bring ISuperfluid.sol, IInstantDistributionAgreementV1, and IDAv1Library into scope from the @superfluid-finance package for Ethereum contracts.
We will need to use a struct in the library called InitData. This struct is defined in the library as follows.
1
struct InitData {
2
    ISuperfluid host,
3
    IInstantDistributionAgreementV1
4
}
Copied!
We use the IDAv1Library for the InitData struct, then we create a local state variable called _idav1Lib of type InitData.
Finally, we define the _idav1Lib with the host and ida addresses passed into the constructor.
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.
1
function myFunction(ISuperfluidToken token, uint32 indexId) {
2
    _idav1Lib.createIndex(token, indexId);
3
}
Copied!
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.
1
function afterAgreementCreated(
2
    ISuperToken superToken,
3
    address /*agreementClass*/,
4
    bytes32 /*agreementId*/,
5
    bytes calldata /*agreementData*/,
6
    bytes calldata /*cbdata*/,
7
    bytes calldata ctx
8
} external override returns (bytes memory newCtx) {
9
​
10
    require(msg.sender == address(_idav1Lib.host), "only host");
11
    uint32 indexId = 0;
12
    return _idav1Lib.createIndexWithCtx(ctx, superToken, indexId);
13
​
14
}
Copied!
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.
1
// library function declaration
2
function createIndex(
3
    ISuperfluidToken token,
4
    uint32 indexId
5
) internal;
6
​
7
// usage
8
_idav1Lib.createIndex(token, indexId);
Copied!
Create Index with User Data
1
// library function declaration
2
function createIndex(
3
    ISuperfluidToken token,
4
    uint32 indexId,
5
    bytes memory userData
6
) internal;
7
​
8
// usage
9
_idav1Lib.createIndex(token, indexId, userData);
Copied!
Create Index in a Super App Callback
1
// library function declaration
2
function createIndexWithCtx(
3
    bytes memory ctx, // ctx passed to the callback function
4
    ISuperfluidToken token,
5
    uint32 indexId
6
) internal returns (bytes memory newCtx);
7
​
8
// usage
9
return _idav1Lib.createIndexWithCtx(ctx, token, indexId);
Copied!
Create Index with User Data in a Super App Callback
1
// library function declaration
2
function createIndexWithCtx(
3
    bytes memory ctx, // ctx passed to the callback function
4
    ISuperfluidToken token,
5
    uint32 indexId,
6
    bytes memory userData
7
) internal returns (bytes memory newCtx);
8
​
9
// usage
10
return _idav1Lib.createIndexWithCtx(ctx, token, indexId, userData);
Copied!
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.
1
// library function decalaration
2
function updateIndexValue(
3
    ISuperfluidToken token,
4
    uint32 indexId,
5
    uint128 indexValue
6
) internal;
7
​
8
// usage
9
_idav1Lib.updateIndexValue(token, indexId, indexValue);
Copied!
​
Update Index Value with User Data
1
// library function declaration
2
function updateIndexValue(
3
    ISuperfluidToken token,
4
    uint32 indexId,
5
    uint128 indexValue,
6
    bytes memory userData
7
) internal;
8
​
9
// usage
10
_idav1Lib.updateIndexvalue(token, indexId, indexValue, userData);
Copied!
Update Index Value in a Super App Callback
1
// library function declaration
2
function updateIndexValueWithCtx(
3
    bytes memory ctx,
4
    ISuperfluidToken token,
5
    uint32 indexId,
6
    uint128 indexValue
7
) internal returns(bytes memory newCtx);
8
​
9
// usage
10
return _idav1Lib.updateIndexValueWithCtx(ctx, token, indexId, indexValue);
Copied!
Update Index Value with User Data in a Super App Callback
1
// library function declaration
2
function updateIndexValueWithCtx(
3
    bytes memory ctx,
4
    ISuperfluidToken token,
5
    uint32 indexId,
6
    uint128 indexValue,
7
    bytes memory userData
8
) internal returns(bytes memory newCtx);
9
​
10
// usage
11
return _idav1Lib.updateIndexValueWithCtx(ctx, token, indexId, indexValue, userData);
Copied!
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.
1
// library function declaration
2
function distribute(
3
    ISuperfluidToken token,
4
    uint32 indexId,
5
    uint256 amount
6
) internal;
7
​
8
// usage
9
_idav1Lib.distribute(token, indexId, amount);
Copied!
Distribute with User Data
1
// library function declaration
2
function distribute(
3
    ISuperfluidToken token,
4
    uint32 indexId,
5
    uint256 amount,
6
    bytes memory userData
7
) internal;
8
​
9
// usage
10
_idav1Lib.distribute(token, indexId, amount, userData);
Copied!
Distribute in a Super App Callback
1
// library function declaration
2
function distributeWithCtx(
3
    bytes memory ctx,
4
    ISuperfluidToken token,
5
    uint32 indexId,
6
    uint256 amount
7
) internal returns (bytes memory newCtx);
8
​
9
// usage
10
return _idav1Lib.distributeWithCtx(ctx, token, indexId, amount);
Copied!
Distribute with User Data in a Super App Callback
1
// library function declaration
2
function distributeWithCtx(
3
    bytes memory ctx,
4
    ISuperfluidToken token,
5
    uint32 indexId,
6
    uint256 amount,
7
    bytes memory userData
8
) internal returns (bytes memory newCtx);
9
​
10
// usage
11
return _idav1Lib.distributeWithCtx(ctx, token, indexId, amount, userData);
Copied!
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.
1
// library function declaration
2
function approveSubscription(
3
    ISuperfluidToken token,
4
    address publisher,
5
    uint32 indexId
6
) internal;
7
​
8
// usage
9
_idav1Lib.approveSubscription(token, publisher, indexId);
Copied!
Approve Subscription with User Data
1
// library function declaration
2
function approveSubscription(
3
    ISuperfluidToken token,
4
    address publisher,
5
    uint32 indexId,
6
    bytes memory userData
7
) internal;
8
​
9
// usage
10
_idav1Lib.approveSubscription(token, publisher, indexId, userData);
Copied!
Approve Subscription in a Super App Callback
1
// library function declaration
2
function approveSubscriptionWithCtx(
3
    bytes memory ctx,
4
    ISuperfluidToken token,
5
    address publisher,
6
    uint32 indexId
7
) internal returns (bytes memory newCtx);
8
​
9
// usage
10
return _idav1Lib.approveSubscriptionWithCtx(ctx, token, publisher, indexId);
Copied!
Approve Subscription with User Data in a Super App Callback
1
// library function declaration
2
function approveSubscriptionWithCtx(
3
    bytes memory ctx,
4
    ISuperfluidToken token,
5
    address publisher,
6
    uint32 indexId,
7
    bytes memory userData
8
) internal returns (bytes memory newCtx);
9
​
10
// usage
11
return _idav1Lib.approveSubscriptionWithCtx(ctx, token, publisher, indexId, userData);
Copied!
Revoke Subscription
Revokes a previously approved subscription. This is called by the subscriber.
1
// library function declaration
2
function revokeSubscription(
3
    ISuperfluidToken token,
4
    address publisher,
5
    uint32 indexId
6
) internal;
7
​
8
// usage
9
_idav1Lib.revokeSubscription(token, publisher, indexId);
Copied!
Revoke Subscription with User Data
1
// library function declaration
2
function revokeSubscription(
3
    ISuperfluidToken token,
4
    address publisher,
5
    uint32 indexId,
6
    bytes memory userData
7
) internal;
8
​
9
// usage
10
_idav1Lib.revokeSubscription(token, publisher, indexId, userData);
Copied!
Revoke Subscription in a Super App Callback
1
// library function declaration
2
function revokeSubscriptionWithCtx(
3
    bytes memory ctx,
4
    ISuperfluidToken token,
5
    address publisher,
6
    uint32 indexId
7
) internal returns (bytes memory newCtx);
8
​
9
// usage
10
return _idav1Lib.revokeSubscriptionWithCtx(ctx, token, publisher, indexId);
Copied!
Revoke Subscription with User Data in a Super App Callback
1
// library function declaration
2
function revokeSubscriptionWithCtx(
3
    bytes memory ctx,
4
    ISuperfluidToken token,
5
    address publisher,
6
    uint32 indexId,
7
    bytes memory userData
8
) internal returns (bytes memory newCtx);
9
​
10
// usage
11
return _idav1Lib.revokeSubscriptionWithCtx(ctx, token, publisher, indexId, userData);
Copied!
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.
1
// library function declaration
2
function updateSubscriptionUnits(
3
    ISuperfluidToken token,
4
    uint32 indexId,
5
    address subscriber,
6
    uint128 units
7
) internal;
8
​
9
// usage
10
_idav1Lib.updateSubscriptionUnits(token, indexId, subscriber, units);
Copied!
Update Subscription Units with User Data
1
// library function declaration
2
function updateSubscriptionUnits(
3
    ISuperfluidToken token,
4
    uint32 indexId,
5
    address subscriber,
6
    uint128 units,
7
    bytes memory userData
8
) internal;
9
​
10
// usage
11
_idav1Lib.updateSubscriptionUnits(token, indexId, subscriber, units, userData);
Copied!
Update Subscription Units in a Super App Callback
1
// library function declaration
2
function updateSubscriptionUnitsWithCtx(
3
    bytes memory ctx,
4
    ISuperfluidToken token,
5
    uint32 indexId,
6
    address subscriber,
7
    uint128 units
8
) internal returns (bytes memory newCtx);
9
​
10
return _idav1Lib.updateSubscriptionUnitsWithCtx(ctx, token, indexId, subscriber, units)
Copied!
Update Subscription Units with User Data in a Super App Callback
1
// library function declaration
2
function updateSubscriptionUnitsWithCtx(
3
    bytes memory ctx,
4
    ISuperfluidToken token,
5
    uint32 indexId,
6
    address subscriber,
7
    uint128 units,
8
    bytes memory userData
9
) internal returns (bytes memory newCtx);
10
​
11
return _idav1Lib.updateSubscriptionUnitsWithCtx(ctx, token, indexId, subscriber, units, userData)
Copied!
Delete Subscription
Deletes an existing subscription, setting the subscriber's units to zero. This is called by the publsiher.
1
// library function declaration
2
function deleteSubscription(
3
    ISuperfluidToken token,
4
    address publisher,
5
    uint32 indexId,
6
    address subscriber
7
) internal;
8
​
9
// usage
10
_idav1Lib.deleteSubscription(tokne, publisher, indexId, subscriber);
Copied!
Delete Subscription with User Data
1
// library function declaration
2
function deleteSubscription(
3
    ISuperfluidToken token,
4
    address publisher,
5
    uint32 indexId,
6
    address subscriber,
7
    bytes memory userData
8
) internal;
9
​
10
// usage
11
_idav1Lib.deleteSubscription(tokne, publisher, indexId, subscriber, userData);
Copied!
Delete Subscription in a Super App Callback
1
// library function declaration
2
function deleteSubscriptionWithCtx(
3
    bytes memory ctx,
4
    ISuperfluidToken token,
5
    address publisher,
6
    uint32 indexId,
7
    address subscriber
8
) internal returns (bytes memory newCtx);
9
​
10
// usage
11
return _idav1Lib.deleteSubscriptionWithCtx(ctx, token, publisher, indexId, subscriber);
Copied!
Delete Subscription with User Data in a Super App Callback
1
// library function declaration
2
function deleteSubscriptionWithCtx(
3
    bytes memory ctx,
4
    ISuperfluidToken token,
5
    address publisher,
6
    uint32 indexId,
7
    address subscriber,
8
    bytes memory userData
9
) internal returns (bytes memory newCtx);
10
​
11
// usage
12
return _idav1Lib.deleteSubscriptionWithCtx(ctx, token, publisher, indexId, subscriber, userData);
Copied!
Claim
Claims a pendind distribution of an index. This is called by the subscriber and updates their real time balance instantly.
1
// library function declaration
2
function claim(
3
    ISuperfluidToken token,
4
    address publisher,
5
    uint32 indexId,
6
    address subscriber
7
) internal;
8
​
9
// usage
10
_idav1Lib.claim(token, publisher, indexId, subscriber);
Copied!
Claim with User Data
1
// library function declaration
2
function claim(
3
    ISuperfluidToken token,
4
    address publisher,
5
    uint32 indexId,
6
    address subscriber,
7
    bytes memory userData
8
) internal;
9
​
10
// usage
11
_idav1Lib.claim(token, publisher, indexId, subscriber, userData);
Copied!
Claim in a Super App Callback
1
// library function declaration
2
function claimWithCtx(
3
    byte memory ctx,
4
    ISuperfluidToken token,
5
    address publisher,
6
    uint32 indexId,
7
    address subscriber
8
) internal returns (bytes memory newCtx);
9
​
10
// usage
11
return _idav1Lib.claimWithCtx(ctx, token, publisher, indexId subscriber);
Copied!
Claim with User Data in a Super App Callback
1
// library function declaration
2
function claimWithCtx(
3
    byte memory ctx,
4
    ISuperfluidToken token,
5
    address publisher,
6
    uint32 indexId,
7
    address subscriber,
8
    bytes memory userData
9
) internal returns (bytes memory newCtx);
10
​
11
// usage
12
return _idav1Lib.claimWithCtx(ctx, token, publisher, indexId subscriber, userData)
Copied!
​
CFAv1 Library
IDAv1 Library Example
Last modified 13d ago
Copy link
Contents
Agreement Abstraction
Importing and Initialization
Basic Usage
Callback Usage
API Specification
Agreement Abstraction

Importing and Initialization

Basic Usage

Callback Usage

API Specification

Create Index

Create Index with User Data

Create Index in a Super App Callback

Create Index with User Data in a Super App Callback

Update Index Value

​

Update Index Value with User Data

Update Index Value in a Super App Callback

Update Index Value with User Data in a Super App Callback

Distribute

Distribute with User Data

Distribute in a Super App Callback

Distribute with User Data in a Super App Callback

Approve Subscription

Approve Subscription with User Data

Approve Subscription in a Super App Callback

Approve Subscription with User Data in a Super App Callback

Revoke Subscription

Revoke Subscription with User Data

Revoke Subscription in a Super App Callback

Revoke Subscription with User Data in a Super App Callback

Update Subscription Units

Update Subscription Units with User Data

Update Subscription Units in a Super App Callback

Update Subscription Units with User Data in a Super App Callback

Delete Subscription

Delete Subscription with User Data

Delete Subscription in a Super App Callback

Delete Subscription with User Data in a Super App Callback

Claim

Claim with User Data

Claim in a Super App Callback

Claim with User Data in a Super App Callback
