What should we include in the Merkle tree leaf for Dynamic/Tranched campaigns

[andreivladbrg]

The current version implemented for Dynamic contract hashes all relevant information for a specific recipient:

v2-periphery/src/SablierV2MerkleLockupLD.sol

Lines 53 to 70 in b5e7199

	/// @inheritdoc ISablierV2MerkleLockupLD
	function claim(
	uint256 index,
	address recipient,
	uint128 amount,
	LockupDynamic.SegmentWithDuration[] memory segments,
	bytes32[] calldata merkleProof
	)
	external
	override
	returns (uint256 streamId)
	{
	// Generate the Merkle tree leaf by hashing the corresponding parameters. Hashing twice prevents second
	// preimage attacks.
	bytes32 leaf = keccak256(bytes.concat(keccak256(abi.encode(index, recipient, amount, segments))));
	// Checks: validate the function.
	_checkClaim(index, leaf, merkleProof);

@gavriliumircea mentioned that including the segments in the tree leaf would be time-consuming (when creating the campaign) and also expensive in terms of API calls, and he suggested including only the (index, recipient, amount) in the Merkle tree leaf. The .csv would still include the segments, but they would be obtained when a claim is being made. (Mircea, correct me if I understood it wrong)

The other problem¹ is when the protocol fee is > 0, the amount in the claim function needs to be greater than the amount from the actual leaf amount. To address this, we either:

• add one more amount param in the function: treeLeafAmount and createAmount - this version would require the UI to calculate both amounts.
• calculate the leaf amount in the claim function by summing the segment amounts - this version would be more expensive in terms of gas.

Curious about your opinions @PaulRBerg @razgraf @smol-ninja. How should the Merkle tree look for Dynamic and Tranched contracts? There are also other discussions regarding UX flow, but they can be open on other repos.

Footnotes

1. This is a problem because we have an invariant on the core that says the segment amounts sum must equal the deposited amount, and in the create function, we need to pass an amount equal to the leaf amount + the fee amount. ↩

[PaulRBerg]

Thanks, will review later.

The other problem1 is when the protocol fee is > 0

We will very likely end up removing the fee as per the discussion in https://github.com/sablier-labs/company-discussions/discussions/2

[smol-ninja]

On first problem

There was an idea floated by @razgraf, see here, about storing a single set of segments globally for the whole dynamic campaign. A modified version of that idea can allow storing $N$ set of segments where max value of $N$ can be fixed based on tx gas limit.

mapping(uint256 N => LockupDynamic.SegmentWithDuration[] segments) private allocationSegments;

and then we can have the following design for the leaf

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

In the future, if we come across a user who wants to define unique segments for each claim, we can then discuss an upgrade, however, I think in practice, it is a very unlikely scenario. For most cases, it should work. What's your opinion on this?

[PaulRBerg]

What would the purpose of $N$ sets of segments be? AFAIK, all airstream campaigns assign the same vesting period to all users.

if we come across a user who wants to define unique segments for each claim, we can then discuss an upgrade, however, I think in practice, it is a very unlikely scenario

Not so unlikely - see this feature request for ranged airstreams.

But anyway, I don't see how this proposal helps. The ranges would have to be generated dynamically.

[smol-ninja]

What would the purpose of $N$ sets of segments be?

$N$ represents the different set of segments that an Airstream campaign can have. If a set of users are expected to claim from $N=1$ and a different set of users is expected to claim from $N=2$, that can be done by storing a global set of segments instead of generating them dynamically. Since $N$ will be part of Merkle tree, a user can only claim from his assigned set of segments.

However I still didn't get it why its a bad idea.

[PaulRBerg]

Some further thoughts here:

I see what you mean now. Previously, I had wrongly assumed that this idea would work only for MLLT, but not for MLLD. My rationale had to do with the combinatorial complexity implied by the co-existence of segment amounts, milestones, and exponents. However, I forgot that the "Exponential" shape used in the UI only uses one segment, which means that there's no combinatorial complexity. Ergo:

1. The allocationSegments is the same as _tranchesWithPercentages
2. There would have to be a sister array, e.g. _exponents, that maps the same IDs to sub-arrays of exponents (to avoid duplicating exponents ad infinitum)

However, this would NOT be a generalized solution in the sense that we would have to pre-empt the use cases for users. If an LD shape is not available in the global sets, we would have to rewrite the contract, audit it, etc.

Furthermore, all this makes me wonder ... what's the point with LD? What can it do that LT cannot do? What's the use case? Is it really just "Exponential" and "Cliff Exponential" which have 1 and 2 segments each, right?

This endeavor to implement MerkleLockup for LD seems like a solution searching for a problem.

P.S. the $N$ is effectively a "shape ID", so a better name would be id.

[smol-ninja]

I am pleased that you have comprehended my point. I should have phrased it better and in detail (a not for me for the next time).

1. The allocationSegments is the same as _tranchesWithPercentages.
2. There would have to be a sister array, e.g. _exponents, that maps the same IDs to sub-arrays of exponents (to avoid duplicating exponents ad infinitum).

Good point.

Furthermore, all this makes me wonder ... what's the point with LD? What can it do that LT cannot do? What's the use case? Is it just "Exponential" and "Cliff Exponential" which have 1 and 2 segments each, right?

Agree that we might have very little demand for MLLD and MLLT can work for most of the use cases. We can (and as we have decided to) hold onto it until we see demand for MLLD.

$N$ is effectively a "shape ID", so a better name would be id.

Agree.

This would NOT be a generalized solution in the sense that we would have to pre-empt the use cases for users

I disagree. Similar to MLLT where _tranchesWithPercentages is set by users at the time of deployment, allocationSegments should also be preset by the user. The assumption is that the campaign owner will set all the allowed set of segments when launching the MLLD campaign and wouldn't be able to change it later (again similar to how it works in MLLT). Therefore, it is still as generalised as MLLT.

[PaulRBerg]

Segments

Since the problem is different whether we're talking about LT or LD, I will provide a two-pronged response.

MerkleLockupLT

This is easy.

We can just apply Razvan's idea from here of storing a global array of percentages that would be used to dynamically generate the segments at claim time.

MerkleLockupLD

This is difficult.

LD is so general purpose that the only way to cater to all potential use cases is to include the segment data in the CSV array. However, as Mircea pointed out, that would significantly increase the costs of our web2 API (Pinata, etc.).

I see two ways out of this:

1. We forget about LD and implement only LT for MerkleLockup
2. We build specialized MerkleLockup "editions" that rely on LD, e.g., MerkleLockupExponential (effectively, mapping the streaming shapes to MerkleLockup editions)
   • MerkleLockupExponential is the only shape we received a feature request for - see context here

The .csv would still include the segments, but they would be obtained when a claim is being made. (Mircea, correct me if I understood it wrong)

I don't understand what you said here. Could you please restate this sentence, @andreivladbrg? I specifically don't understand why something that is part of the CSV would then have to be obtained when a claim is made.

Also, @gavriliumircea, it would be helpful if you could join the conversation and respond to Andrei's question.

Protocol Fee

The development cost is not worth it anymore, so please go ahead assuming that they will be removed. I will follow up in https://github.com/sablier-labs/company-discussions/discussions/2 now to persuade Max to let go.

[andreivladbrg]

without specifying information on set of segments / tranches, wouldn't users be able to create a stream with a different segments / tranches than assigned by the campaign creator as long as it satisfies sumAmount == totalAmount?

ohhh, yes 😂

this means they could initiate a claim using the first segment amount = total amount, with a duration of 1 second

[PaulRBerg]

@smol-ninja: without specifying information on set of segments / tranches, wouldn't users be able to create a stream with a different segments / tranches than assigned by the campaign creator as long as it satisfies sumAmount == totalAmount?

No, because the campaign contract would dynamically generate the segments from the hard-coded percentages.

@andreivladbrg: this means they could initiate a claim using the first segment amount = total amount, with a duration of 1 second

No, they couldn't do that.

[andreivladbrg]

No, because the campaign contract would dynamically generate the segments from the hard-coded percentages
No, they couldn't do that.

when there are hardcoded percentages, you are right, they can't

tho, i think @smol-ninja was referring to the LD scenario

[smol-ninja]

Agree its not a problem when we have hardcoded percentages in LT.

[PaulRBerg]

i think @smol-ninja was referring to the LD scenario

I was also referring to that scenario (in the context of my LD editions idea). You would have a MerkleLockupExponential contract with a global array of pre-defined segments, each segment containing a (i) percentage and (ii) an exponent.

[razgraf]

MerkleLockupLT: I think we can move ahead with this

MerkleLockupLD: The conversation revolved around creating a one-size-fits-all solution for LD support. Why don't we just assume the same as for LT and start with the same segments for everyone, only with different concrete amounts? Same idea you've referenced above from an old reply of mine. It would keep the CSV data mostly the same, and the implementation should be quite trivial.

I've seen a few requests for MerkleLockupLD (not sure we tracked them all in #23, I have a feeling I've heard it at least 3 or 4 times from potential users) but I don't think I've seen a literal request for everyone having a different stream shape in the same campaign. While the "editions" idea is cool (we can optimize case-by-case with it), we'd have to get it audited every time and I'm not sure if it solves the problem of having to store each different segment in the CSV (even if we know the final shape will be an exponential for example).

My proposal for now:

• Implement MLLT with a global set of segments with percentages and an individual list of {recipient, amount}
• Implement MLLD with the same architecture
• Wait for requests from users for a generalized MLLD solution with segments-galore or reconsider based on the success of the above

Note: MerkleLockupLT = MerkleLockupLockupTranched, a bit repretitive although I'd keep the "LT" abbreviation intact - why not MerkleLT?
Note2: Coming from the Pond experience, it's also likely we'll attract future users just by having these features out there, so we should factor in the cost of opportunity aside from already realized requests from users

[PaulRBerg]

MerkleLockupLT: I think we can move ahead with this

Great

MerkleLockupLD: The conversation revolved around creating a one-size-fits-all solution for LD support.

Were you referring to Andrei and Shub's proposals?

Asking because I suggested the exact opposite with the LD editions idea, i.e., bespoke MerkleLockupFOO contracts that implement a particular LD shape.

Why don't we just assume the same as for LT and start with the same segments for everyone, only with different concrete amounts?

What's the point of this if we already have LT?

I've seen a few requests for MerkleLockupLD

How many of those would be addressable via LT? e.g. the monthly unlocks requested by Holograph could be handled via LT

While the "editions" idea is cool (we can optimize case-by-case with it), we'd have to get it audited every time

Yes, we'd have to get it audited every time, but there doesn't seem to be any other alternative.

I'm not sure if it solves the problem of having to store each different segment in the CSV

It does solve it. The segments would be auto-generated at runtime. No need to put them in the CSV or the Merkle tree.

Implement MLLD with the same architecture

There's no point in doing this because MLLT can cover everything that could be covered by this specialized MLLD

for a generalized MLLD solution

As I've said in my previous reply above, this is impossible without putting the segments in both the CSV and the Merkle tree, but we can't do this due to performance reasons.

[PaulRBerg]

I'm sorry to insist @razgraf, but could you please respond to this today so that we can settle upon a course of action?

FYI, I'm in favor of implementing just MLLT. It should cover the vast majority of user needs while not complicating the development time.

We can then measure user response and implement MLLD later on (if need be).

[razgraf]

Not sure what to respond to? Also it's quite hard to follow so many quotes 😅

Were you referring to Andrei and Shub's proposals?

Yes. I touched upon your suggestion later in my reply.

How many of those would be addressable via LT?

Probably most of the ones we got until now. That's not mutually exclusive with implementing support for MLLD to potentially attract future users if the cost analysis yields a promising results a.k.a. it's worth bundling it with the MLLT implementation.

there doesn't seem to be any other alternative

I have presented an alternative in my reply. The MLLD variant that stores a single set of global segments with percentages.

If you remember, the original point of MLLD+MLLT being developed together was to save up on audit costs as the proposed implementations (from #166) were quite similar.

The segments would be auto-generated at runtime.

Fair, my bad here.

There's no point in doing this because MLLT can cover everything that could be covered by this specialized MLLD

1. Exponentials
2. Not having to re-audit and re-deploy a factory "edition" every time a user wants a different set of segments which include Exponentials

generalized MLLD solution

but we can't do this due to performance reasons

We can work on it and find optimizations. See Shub's reply above. You store a set of potential configurations and link to which one is being used. This way we don't really have to store specifics in the CSV.

But - this can also come as a second iteration over the current MLLD + MLLT products, as it solves the problem of the generalized MLLD version (mostly because auditing it now wouldn't offer any "cost optimization" versus having two very similar Merkle contracts).

FYI, I'm in favor of implementing just MLLT

As stated in this reply, the original reason why I proposed delivering MLLD + MLLT was to optimize on audit costs. I believe we discussed this on a call between me, you and @gavriliumircea - with some context added afterwards in this discussion.

If you decide it's not worth it, I'll support that for the sake of moving faster with our planning. But I wasn't presented with a clear answer as to why it isn't worth it, yet.

[PaulRBerg]

I'm sorry for not responding here earlier. It is a technically nuanced discussion, and the fundraising got in the way of my responding.

For posterity, it is worth noting that we ditched support for MLLD.

The reason is that a generalized MLLD is not possible, that is, a ML factor that allows users to compose any curve (unlike in vanilla LD, where this IS possible). For more context, see my reply to Shub.

Exponentials

This is the only use case enabled by MLLD, but it's limited in the sense that it can work only for single-segment exponentials. Again, refer to my reply to Shub.

Not having to re-audit and re-deploy a factory "edition" every time

We would have to re-audit and re-deploy the MLLD factory because the global sets of exponents (i.e. your alternative idea) contains only a pre-defined set of exponentials. If a user demands a custom curve, a new ML factory is needed.

Thus, the audit cost optimization idea has been invalidated by the reality of the implementation complexity. Contrary to our original expectations, costs would be saved only if we held on to implementing it when we have a clearer picture of the most useful

Not sure what to respond to?

Sorry, I did not cross-post the question I asked on Slack. See this.

---

P.S. Fair criticism regarding the number of quotes. In the future, I will try to provide more structured responses and quote-reply only when particularly helpful.

[razgraf]

MLLD (and LD for that matter) usage through exponentials and combinations of exponentials and traditional shapes promoted by LT or LL is there, but it's limited in demand. They haven't been heavily requested, therefore they may not be worth while, can agree to that. Plus, if the audit cost isn't a differentiator, we could revert to your idea to use bespoke variants deployed from time to time based on user demand.

---

The global sets of exponents (i.e. your alternative idea) contains only a pre-defined set of exponentials

Hmm, pre-defined by the admin when they generate the ML contract through the factory (e.g. they pass a list of exponents and ranges to the factory). It's a user action, not an in-code one. Why are audits needed? (Did I understand the statement correctly?)

[PaulRBerg]

[PaulRBerg]

Request for MLLD from a new user, Arcana.

They want Unlock-Cliff which can only be supported by LD not by LT.

[PaulRBerg]

Should we close this, @andreivladbrg, @smol-ninja?

[andreivladbrg]

we can close it on my end

only if @smol-ninja needs to add something

[smol-ninja]

Lets close it.