Skip to main content

Create a Lockup Dynamic stream

Lockup Dynamic are streams with custom streaming curves. In this guide, we will show you how to programmatically create a Lockup Dynamic stream.

This guide assumes that you have already gone through the Protocol Concepts section.

note

This guide interacts with the Core contracts directly.

caution

The code in this guide is not production-ready, and is implemented in a simplistic manner for the purpose of learning.

Set up a contract​

Declare the Solidity version used to compile the contract:

// SPDX-License-Identifier: GPL-3.0-or-later
pragma solidity >=0.8.22;

Import the relevant symbols from @sablier/v2-core:

import { IERC20 } from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
import { ud2x18 } from "@prb/math/src/UD2x18.sol";
import { ud60x18 } from "@prb/math/src/UD60x18.sol";
import { ISablierV2LockupDynamic } from "@sablier/v2-core/src/interfaces/ISablierV2LockupDynamic.sol";
import { Broker, LockupDynamic } from "@sablier/v2-core/src/types/DataTypes.sol";

Create a contract called LockupDynamicStreamCreator, and declare a constant DAI of type IERC20 and a constant LOCKUP_DYNAMIC of type ISablierV2LockupDynamic:

contract LockupDynamicStreamCreator {
    IERC20 public constant DAI = IERC20(0x68194a729C2450ad26072b3D33ADaCbcef39D574);
    ISablierV2LockupDynamic public constant LOCKUP_DYNAMIC =
        ISablierV2LockupDynamic(0x73BB6dD3f5828d60F8b3dBc8798EB10fbA2c5636);
}

In the code above, the contract addresses are hard-coded for demonstration purposes. However, in production, you would likely use input parameters to allow flexibility in changing the addresses.

Also, these addresses are deployed on Mainnet. If you need to work with a different chain, the Sablier addresses can be obtained from the Deployment Addresses page.

Create functions​

There are two create functions in the Lockup Linear contract:

Which one you choose depends upon your use case. In this guide, we will use createWithTimestamps.

Function definition​

Define a function called createStream which takes two parameters, amount0 and amount1, and which returns the id of the created stream:

function createStream(uint128 amount0, uint128 amount1) public returns (uint256 streamId) {
  // ...
}

Next, sum up the amount0 and amount1 parameters to get the total amount of the stream, which will be needed in many of the steps below:

uint256 totalAmount = amount0 + amount1;

ERC-20 steps​

To create a stream, the caller must approve the creator contract to pull the tokens from the calling address's account. Then, we have to also approve the Lockup dynamic contract to pull the assets that the creator contract will be in possession of after they are transferred from the calling address (you):

// Transfer the provided amount of DAI tokens to this contract
DAI.transferFrom(msg.sender, address(this), totalAmount);

// Approve the Lockup dynamic contract to spend DAI
DAI.approve(address(LOCKUP_DYNAMIC), totalAmount);

For more guidance on how to approve and transfer ERC-20 assets, see this article on the Ethereum website.

Parameters​

Lockup dynamic uses structs to encode the parameters of its create functions. The struct associated with createWithTimestamps is LockupDynamic.CreateWithTimestamps, and it can be initialized like this:

LockupDynamic.CreateWithTimestamps memory params;

Let's review each parameter in detail.

Sender​

The address streaming the assets, with the ability to cancel the stream:

params.sender = msg.sender;

Recipient​

The address receiving the assets:

params.recipient = address(0xCAFE);

Total amount​

The total amount of ERC-20 assets to be paid, including the stream deposit and any potential fees, all denoted in units of the asset's decimals.

params.totalAmount = totalAmount;

Asset​

The contract address of the ERC-20 asset used for streaming. In this example, we will stream DAI:

params.asset = DAI;

Cancelable​

Boolean that indicates whether the stream will be cancelable or not.

params.cancelable = true;

Transferable​

Boolean that indicates whether the stream will be transferable or not.

params.transferable = true;

Start time​

The Unix timestamp for when the stream will start.

In this example, the start time is set to 100 seconds into the future:

params.startTime = uint40(block.timestamp + 100 seconds);

Segments​

Segments are what the protocol uses to compose the custom distribution curve of a Lockup Dynamic stream. For a full exposition of segments, see the Segments guide.

The term "segment" refers to the splitting of the stream into separate partitions, with each segment characterized by a specific amount, exponent, and timestamp. These segments are supplied to the function in the form of an array containing LockupDynamic.Segment structs.

Let's define two dummy segments:

params.segments = new LockupDynamic.Segment[](2);
params.segments[0] = LockupDynamic.Segment({
    amount: amount0,
    exponent: ud2x18(1e18),
    timestamp: uint40(block.timestamp + 4 weeks)
});
params.segments[1] = (
    LockupDynamic.Segment({
        amount: amount1,
        exponent: ud2x18(3.14e18),
        timestamp: uint40(block.timestamp + 52 weeks)
    })
);

In this example, the first segment (amount0) will stream much faster than the second segment (amount1), because the exponents are different. As a rule of thumb: the higher the exponent, the slower the stream.

note

The segment timestamp must be in ascending order.

info

The ud2x18 function wraps a basic integer to the UD2x18 value type, which is part of the PRBMath library.

Broker​

An optional parameter that can be set in order to charge a fee as a percentage of totalAmount.

In the following example, we will leave this parameter uninitialized (i.e. set to zero), because it doesn't make sense to charge yourself a fee. In practice, this parameter will mostly be used by front-end applications.

params.broker = Broker(address(0), ud60x18(0));
info

Wondering what's up with that ud60x18 function? It's a casting function that wraps a basic integer to the UD60x18 value type. This type is part of the math library PRBMath, which is used in Sablier for fixed-point calculations.

Invoke the create function​

With all parameters set, we can now call the createWithTimestamps function, and assign the id of the newly created stream to a variable:

streamId = LOCKUP_DYNAMIC.createWithTimestamps(params);

The complete Lockup Dynamic stream creator contract​

Below you can see the complete functioning code: a contract that creates a Lockup Dynamic stream. You can access the code on GitHub through this link.

Lockup Dynamic Stream Creator
loading...