πŸ“œ
Interacting With Superfluid Smart Contracts
Using Superfluid at the Smart Contract Level

Working With Superfluid Using Solidity

Inside of the Interactive Tutorials section, you can learn how to use the Superfluid Core SDK to work with money streams or instant distributions. Under the hood, what you're really doing is interacting with Superfluid agreements. Money streams are created by interacting primarily with the constant flow agreement (CFA), while calls related to instant distributions are done by working with the instant distribution agreement (IDA).
To get started, you'll need to be sure to import, at minimum, the Superfluid host interface & agreement interface that you'd like to work with. In a situation where you'd like to use both the CFA and IDA in the same contract, you would import these contracts like this:
1
pragma solidity ^0.8.0
2
​
3
import { ISuperfluid }from "@superfluid-finance/ethereum-contracts/contracts/interfaces/superfluid/ISuperfluid.sol"; //"@superfluid-finance/ethereum-monorepo/packages/ethereum-contracts/contracts/interfaces/superfluid/ISuperfluid.sol";
4
​
5
import { IConstantFlowAgreementV1 } from "@superfluid-finance/ethereum-contracts/contracts/interfaces/agreements/IConstantFlowAgreementV1.sol";
6
​
7
import { IInstantDistributionAgreementV1 } from "@superfluid-finance/ethereum-contracts/contracts/interfaces/agreements/IInstantDistributionAgreementV1.sol";
Copied!
If you'd like to interact with a Superfluid agreement directly by using solidity, you need to make a function call first to the Superfluid host contract. You'll call the callAgreement or callAgreementWithContext function on the host contract (Superfluid.sol), and pass in a few parameters:
ISuperAgreement agreementClass - the the agreement you're going to interact with (either the CFA or IDA)
bytes memory calldata - the transaction you're calling on the agreement you're interacting with, compiled to bytecode (using one of solidity's encoding methods)
bytes memory userData - any additional data you'd like to include with your function call. If you don't plan to add userData, you can pass in an empty bytes value (i.e. "0x"). You can learn more about this parameter here.
Here's an example of how this looks in action when interacting with the constant flow agreement. This pattern will be the same whether you're creating, updating, or deleting flows.
1
//creating a flow in pure solidity
2
host.callAgreement(
3
cfa,
4
abi.encodeWithSelector(
5
cfa.createFlow.selector,
6
token,
7
receiver,
8
flowRate,
9
new bytes(0) // placeholder - always pass in bytes(0)
10
),
11
"0x" //userData
12
);
Copied!
The following is an example for interacting with the instant distribution agreement using solidity. This pattern is the same for each interaction you'd like to make with the IDA:
1
// distributing tokens with the instant distribution agreement
2
host.callAgreement(
3
ida,
4
abi.encodeWithSelector(
5
ida.distribute.selector,
6
token,
7
index,
8
amountToDistribute,
9
new bytes(0) // placeholder ctx
10
),
11
"0x" // user data
12
);
Copied!
NOTE: If you're interacting with agreements inside of a Super App callback, this process will work differently. See this section for details.

Common Mistakes

One other thing to keep in mind is the value of msg.sender when working with Superfluid from a contract. For example, developers will occasionally want to create a function which will let an account create a flow into the contract itself. So, they'll write a function that looks like this, expecting it to create a flow into the contract from the msg.sender of the function:
1
//this will fail because a contract cannot create a flow to itself
2
​
3
function createFlowFail(ISuperToken DAIx, int96 flowRate) external {
4
cfaV1.createFlow(address(this), DAIx, flowRate);
5
}
Copied!
In the above function, you have set the receiver on the cfaV1.createFlow function to be the contract's address. Under the hood, even though msg.sender on the broader createFlowFail function is an external address, the msg.sender on the cfa.createFlow call to the Superfluid protocol is the address of the contract. The Superfluid callAgreement function will see that the contract is trying to create a flow into itself, and revert.
If you want to create a flow into a contract, we recommend that you use either the Core-SDK from outside of a contract or a 2nd contract which already has some balance of Super Tokens.
A similar mistake which stems from this msg.sender misunderstanding occurs when developers want to allow external accounts to create flows directly to other accounts via a function on the contract. For example:
1
//remember that this will revert if the contract has a zero balance of DAIx
2
//msg.sender on the call to the Superfluid framework is the contract
3
​
4
function createFlow2Receiver(address receiver, ISuperToken DAIx, int96 flowRate) external {
5
cfaV1.createFlow(receiver, DAIx, flowRate);
6
}
Copied!
Recall that the value of msg.sender on the cfaV1.createFlow function will be the contract's address, not the external address calling the broader createFlow2Receiver function. If you're intending to create a flow from the contract to another address, then this code is what you need (just make sure your contract has a balance of Super tokens!). However, if you're running this with the expectation that it will open a flow directly from an external account calling the function to the intended receiver, it will not work as expected.