How should we handle the Lockup Dynamic campaign's segments?

[andreivladbrg]

In one of our calls, the design decision regarding the Lockup Dynamic segments was to pass them into the constructor and hardcode them within the contract:

v2-periphery/src/SablierV2AirstreamCampaignLD.sol

Lines 27 to 29 in 5d55a7e

	/// @notice The array of segments needed for creating the LockupDynamic stream, which implicitly provides the total
	/// streaming duration of each airstream.
	LockupDynamic.SegmentWithDelta[] public segments;

In practice, this won't work for winners with different airdrop amounts, because in the segment struct, we have an amount variable that, when summed up, it should be equal to the airdrop amount.

https://github.com/sablier-labs/v2-core/blob/456744002f62d0627f10b958d41937ed1e68d95e/src/libraries/Helpers.sol#L209-L213

One potential solution I've considered is including the segments (if not the all array of structs, we can include only the amounts) for each airdrop winner in the Merkle tree. However, I'm unsure how this might complicate the frontend and server-side aspects.

@razgraf, do you think this would be achievable?

What do you think? Are there other solutions we could explore?

Should we continue with the Lockup Dynamic campaign, or prioritize the release of the Lockup Linear campaign first?

[razgraf]

General understanding

In theory we can store whatever we want in the Merkle Tree's leafs, so we can go for a hash of:

• the address and the amount (Lockup Linear)
• the address and the segment array (potentially Lockup Dynamic)

From my initial research, the frontend will have to

1. Extract the details for a given user (from the raw list we'll keep on IPFS)
2. Generate a proof from those details
3. Send the proof and the raw details to the contact, which will perform the verification step
   ↳ MerkleProof.verify(proof, root, keccak256(abi.encodePacked(...details)))

There's even a nice library from OZ to pre-verify this at frontend level. It accompanies the OZ Merkle Proof contract.

Concrete answers

Now, to address the points in the OP:

However, I'm unsure how this might complicate the frontend and server-side aspects.

Well, it's a matter of file size mostly. The more data we fit into the raw claim list → the bigger the file → the heavier it gets to download it, parse it etc. Same for when we process it.

I don't have numbers to back this up yet, but repeating the segments over and over again will definitely affect performance for lists > 1000 recipients (depending on how many segments there are).

It is achievable nevertheless, but we can work on optimizing it.

What do you think? Are there other solutions we could explore?

Of course! I must explore this more thoroughly but we could optimize by:

• Storing a single set of segments (globally) with percentages of the individual amounts (e.g. for a step function, users unlock - at the same time - 10% of their amount. For an exponential cliff, they all unlock 10% at the moment of the cliff)
  • Global: PercentageSegments[]: [{delta:86400, exponent:1, percentage:10}, {delta:86400, exponent:3, percentage:90}, ...]
  • Tree: {recipient, amount}
• Storing multiple sets of segments (globally) and referencing them by position/id (similar to the 1st point but extended to support multiple shapes in the same contract - although this I believe is overkill for now)

Should we continue with the Lockup Dynamic campaign, or prioritize the release of the Lockup Linear campaign first?

I believe we should definitely prioritize Lockup Linear, but, I'd also love to bundle both when we being the audit. @PaulRBerg would love to hear your thoughts here.

[PaulRBerg]

Great catch @andreivladbrg and nice write-up.

This finding makes me staunchly against continuing the integration of Lockup Dynamic into the first release of Airstreams. There is a risk of not being able to finish the project by the end of the year.

I am suggesting a minimalistic and fallibilist approach:

1. Integrate Lockup Linear end-to-end (contracts, frontend, and Merkle backend)
2. Audit
3. Launch and shill the heck out of Airstreams
4. Gauge the user growth and community's response
5. Decide if Lockup Dynamic is worth pursuing for Airstreams

[smol-ninja]

Thanks for starting this discussion @andreivladbrg. I would like to share my perspective on the following concept:

Storing multiple sets of segments (globally) and referencing them by position/id

I believe it might be improbable in practice for users to define a unique segment for each recipient. More commonly, users might prefer defining different sets of segments for different set of recipients, such as different vesting structures for LPs, shareholders, and employees. In such scenarios, users can create multiple Airstreams, each tailored to accommodate its unique set of segments for specific set of recipients.

Having considered this, I align with @razgraf's proposition of storing a single set of segments globally with percentages of individual amounts. This can be an immutable variable and during the claiming process, we can convert percentages into amounts to construct Lockup Dynamic segment structure

Update

I now think storing different distribution segments wouldn't be overkill as well. We can introduce allocationSegments map and Merkle proof can include position ID from allocationSegments

// segments is of the form {delta:86400, exponent:1, percentage:10}.
// Requirement sum(percentage) == 100
mapping(uint256 position => LockupDynamic.SegmentWithDelta[] segments) private allocationSegments;

.....

bytes32 leaf = keccak256(bytes.concat(keccak256(abi.encode(index, recipient, amount, position))));

[PaulRBerg]

If we implement LockupTranched instead of LockupDynamic, this whole issue becomes much easier to handle!

• https://github.com/sablier-labs/company-discussions/discussions/23
• https://github.com/sablier-labs/company-discussions/discussions/19

[PaulRBerg]

As I realized on the earlier call with @razgraf and @andreivladbrg, what I said above is a misconception.

With LockupTranched, the "whole issue" does NOT become "much easier to handle".

From the perspective of MerkleStreamer, handling the LT segments is as complicated as handling the LD segments because the difficulty stems primarily from how the amounts are provided. There are two approaches:

1. Pass one amount to claim and generate the segments on the fly
2. Pass all segment amounts to claim

I think the first approach wouldn't work because there would be rounding errors. But maybe I'm wrong - when we implement either LT or LD, we should perform some checks @andreivladbrg.

[smol-ninja]

Do both of these approaches assume equal segment lengths?

If not, the first approach wouldn't work since, without duration/milestone information, generating segments on the fly would be impossible.

In the second approach, information on milestones would also need to be provided while claiming.

[PaulRBerg]

Good question - the answer is no; we can't assume equal-length segments.

So, the 2nd approach is the only one that works.

[PaulRBerg]

Can we close this, @andreivladbrg?

[andreivladbrg]

yes, we will pass the segments/tranches in the claim function