Design Lockup Linear to support Cliff Linear vesting

[smol-ninja]

Important

The below proposal is for future release of Lockup and not v2.2.

Context

In the current design of Lockup linear, the amount unlocked at cliff is a function of the time elapsed. That is, if the cliff timestamp is 30% ahead of the start time, this would unlock 30% of the total amount at the cliff. This makes it less flexible for creating a cliff linear vesting.

Note

In a cliff linear vesting, token distributions include a preset amount unlocked at the cliff followed by a linear distribution. The amount unlocks at the cliff can be any and does not need to follow the curve slope.

Existing solution

A Cliff linear vesting can be created using Lockup Dynamic (LD). It has a few problems:

1. It is not intuitive to use LD for creating Linear streams with cliffs.
2. Creating a cliff linear vesting stream is less gas efficient (same argument as why we chose to implement lockup tranched).
3. Despite having a cliff feature in Lockup Linear (LL), it does not support Cliff linear vesting.

Proposed solution

Modify the Lockup Linear design to allow the creation of cliff linear vesting streams. So that,

1. LL can be used to create streams with unlocks instantly followed by a linear curve (as requested by one of our users).
2. LL can be used to create a stream with a fixed amount of unlock at a cliff time followed by a linear curve.
3. it becomes more gas-efficient than doing the same with LD.
4. Existing curves such as Unlock-cliff and Unlock-linear on Sablier UI will become gas efficient. Because they are created using LD at present.

Thoughts @sablier-labs/everybody?

[smol-ninja]

Supporting examples from SAFE distribution:

• 25M tokens are available immediately, with the remaining 25M vested over 4 years
• An initial airdrop of 25M tokens, with half available immediately and the rest vested over 4 years

[PaulRBerg]

Sorry for taking so long to respond here!

This is a great idea. Before reading your post, I thought that a proper cliff has to be obey the mathematical rules of the rest of the curve, i.e., in the case of LL to be a function of elapsed time as it is currently implemented. However, ChatGPT proved me wrong.

Am I right that your proposal has two parts:

1. Free the cliff in Lockup Linear from having to be a function of elapsed time
2. Add an optional amount that gets instantly unlocked (related: Immediately transfer the streamed portion when creating streams #912)

If yes, I am in favor of the proposal. It makes a lot of sense.

Tagging @sablier-labs/engineers for additional feedback. I think we should include this change in Lockup v1.3.0

[smol-ninja]

Thanks for taking time to review the proposal. To answer your questions:

Free the cliff in Lockup Linear from having to be a function of elapsed time

Yes.

Add an optional amount that gets instantly unlocked

Yes. Instead of amount, we might also add two percentages representing: (i) instant unlocked amount (ii) cliff amount.

if block.timestamp < cliffTime:
    streamedAmount = deposited * instantUnlockPct # instant unlocked amount
else:
    # elapsed time is defined from cliff time
    elapsedTime = (block.timestamp - cliffTime) / (endTime - cliffTime)
    streamedAmount = deposited * instantUnlockPct # instant unlocked amount
                   + deposited * cliffUnlockPct  # cliff unlocked amount
                    # stream linearly from cliff time
                   + deposited * (1 - instantUnlockPct - cliffUnlockPct) * elapsedTime

[PaulRBerg]

Got it, thanks for confirming.

While these are cool ideas and I agree that implementing them would be beneficial, I also realize now that the LockupLinear name would be misleading. With the new design, at least a portion of the curve would be non-linear.

I can't think of any neat name off the top of my head. Maybe LockupBasic?

P.S. this would also have implications for the URL aliases in the UI, i.e. LL, LL2, etc.

cc @sablier-labs/frontend

[smol-ninja]

Even though it's piecewise linear, I don't think LockupLinear would be misleading. The terms Linear, Dynamic, and Tranched can represent (or we can make them represent) the continuous streaming portion of the stream, where cliff and instant unlocks are a part of it. If there is no cliff, then they are fully linear and in the presence of a cliff, they are piecewise linear.

I'm looking forward to hearing others' opinions on this.

[PaulRBerg]

Makes sense. Happy to keep LockupLinear in this case.

There's also the backward-compatibility cost (renaming LL would be a pain for the subgraph, etc.)

[razgraf]

I agree with @smol-ninja. While Linear is the core part, cliffs and initial unlocks can be defined as "features".

[razgraf]

Your suggestion sounds great! Fully support this for our next EVM Lockup release.

[PaulRBerg]

Created an issue to track this:

#1043

[smol-ninja]

A user requested unlock-cliff with 0 cliff amount. Post this implementation, we will also be able to offer such kind of streams through airstream campaigns which is not possible today due to lack of LD airstreams cc @maxdesalle.

[PaulRBerg]

Great stuff.

However, in order to provide a general-purpose solution for requests like this, we should implement a fully customizable segment generator UI.