Replace createWithDurations with createWithTimestamps in Airstreams

[smol-ninja]

Offers

1. One Time Airdrop: Although more expensive than having dedicated one-time airdrop logic, it allows claim and withdraw in a single tx.
2. Ranged Airstreams: This implementation supports airstreams with uniform start and end times.
3. Legacy airstreams¹

Context

Relying on createWithDurations in MerkleLockup has the following limitations:

1. Airstreams cannot start and end at the same time regardless of when they are claimed.
2. Airstreams cannot be used for one-time airdrop because the end time must be greater than the start time, preventing token withdrawal in the same transaction.

It can only be used to create a campaign where streams begin vesting only when claimed. But what if we can also achieve the same functionality using createWithTimestamps?

Proposal

Replace createWithDurations with createWithTimestamps. This would require replacing streamDurations with a bespoke timestamp variable but with a slight modification:

MerkleLockup.Timestamps public override timestamps;

MerkleLockup.Timestamps {
    uint40 startTime;
    uint40 cliffDuration;
    uint40 endDuration;
}

When a user claims, calculate cliffTime and endTime as follows to create ranged airstreams:

• cliffTime = startTime + cliffDuration
• endTime = startTime + endDuration

I will explain below why it looks different than LockupLinear.Timestamp.

One-time airdrops

This can be achieved by setting the end time in the past. But since Lockup requires end time to be in the future, we will have to change that and allow end time to be in the past as long as the following inequality holds: startTime < cliffTime < endTime.

Note

Even though, one-time airdrop can be unlocked with this approach, I am not against having a bespoke contract for it (see discussion sablier-labs/v2-periphery#370). Its a similar argument as to why we chose to release Lockup Tranched even though the same curve can also be achieved by Lockup Dynamic - gas efficiency.

Legacy Airstreams

To create the same airstreams that we allow today, we will allow startTime to be 0. When its 0, Lockup Linear's startTime will default to block.timestamp, making cliffTime and endTime:

• cliffTime = block.timestamp + cliffDuration
• endTime = block.timestamp + endDuration

This would create airstreams that begin vesting when the user claims and end at different dates, similar to the current behaviour.

cc @sablier-labs/engineers.

Footnotes

1. Legacy airstreams are the current airstreams supported by Merkle Lockup. They have start time set as claim time and end time at a fixed duration. ↩

[andreivladbrg]

Thanks for opening this; I am in favor of this proposal.

Question: This change would be only for linear, right? For tranched, we can’t use createWithTimestamps, right?

[smol-ninja]

I used Lockup Linear as an example for simplicity, but the same idea applies to Lockup Tranched by allowing the last tranche timestamp to be in the past. Ranged airstreams can also have tranches.

Similarly in lockup dynamic, the last segment timestamp can be allowed to be in the past. Therefore, a general statement would be that any lockup stream can have an end time in the past.

[razgraf]

I, too, like where this is going!

[PaulRBerg]

Initial Understanding

Thanks Shub for this. It's an interesting proposal, but I have reservations.

Am I correct that this would entail a change in the Core contracts, too? This is what you meant here, right:

we will have to change that and allow end time to be in the past as long as the following inequality holds: startTime < cliffTime < endTime.

If yes, that's not good. Disallowing end times in the past served as a way to prevent user errors:

https://github.com/cantinasec/review-sablier/issues/7

Further Criticism

• The name of MerkleLockup.Timestamps is misleading. The meme below captures my reservations better than any words could.
• Lockup is architected the way it is for a purpose - to enable onchain vesting/ distribution of assets. We shouldn't alter the core protocol to implement a periphery feature.

Suggestions

• Implement a separate one-time airdrop contract
• Implement your proposal to enable ranged airstreams, but find a different name for MerkleLockup.Timestamps

[smol-ninja]

Am I correct that this would entail a change in the Core contracts, too? If yes, that's not good. Disallowing end times in the past served as a way to prevent user errors: https://github.com/cantinasec/review-sablier/issues/7

Yes. As I mentioned it to Andrei, I believe it should not be acknowledged as an issue at all. Even in the current design, users can mistakenly set an end time to be just one second in the future, resulting in immediate vesting. These are user errors. Restricting end times to the future limits many use cases, as I mentioned in the original post.

---

The name of MerkleLockup.Timestamps is misleading

I agree and we can come up with new names. I used Timestamps as a placeholder. (PS: the meme is really good 🤣)

We shouldn't alter the core protocol to implement a periphery feature

Yes and I agree with this principle. However, by not allowing endTime to be in the past, it restricts many use cases including ranged airstreams.

I'm not against having a separate one-time airdrop contract. While this solution may be used for a one-time airdrop, a bespoke contract is preferable for gas efficiency. The goal of this discussion is to enable ranged airstreams, one-time airdrops, and legacy streams simultaneously. Currently, the design only supports legacy streams

By replacing createWithDurations with createWithTimestamps, we can unlock more Airstreams' potential without losing any current functionality.

[PaulRBerg]

Even in the current design, users can mistakenly set an end time to be just one second in the future

That's a good point!

I agree and we can come up with new names

Great!

by not allowing endTime to be in the past, it restricts many use cases including sablier-labs/v2-periphery#279.

Another good point.

Though it's ranged airstreams, not streams. A subtle but important difference.

---

Ok so here's my updated proposal:

• Switch to createWithTimestamps and the Elephant-Penguin type that blends durations and timestamps into a new struct
• Update Core to allow end time in the past to enable ranged airstreams
• Build a bespoke airdrop contract for increased gas efficiency

[smol-ninja]

Cool. @andreivladbrg if you agree as well, I will create an issue in core (to allow end time to be in the past) and an issue in periphery (Switch to createWithTimestamps).

[andreivladbrg]

Go for it!

[PaulRBerg]

Beautiful alignment

[smol-ninja]

Linked issues

1. Allow end time of lockup streams to be in the past #982
2. Replace createWithDurations with createWithTimestamps in claim function #996