Brainstorming solutions to implement instant airdrop contract

[smol-ninja]

^{Originally discussed in https://github.com/sablier-labs/company-discussions/discussions/55.}

Solution 1: Merkle Lockup like contract

Use Factory to deploy a contract similar to Merkle Lockup.

Pros:

1. Familiar user experience akin to Merkle Lockup.
2. Easier to implement.
3. Each creator has control over their deployed contract.

Cons:

1. Does not consolidate TVL, causing fragmented liquidity across multiple contracts. In Merkle Lockup, this isn't a problem because each claim leads to TVL increase of Lockup contracts.
2. Harder to monitor on-chain key KPIs such as combined TVL, total users, and gas usage.

Solution 2: Single Bespoke Contract

A single contract uses campaign ID to store campaign related information without deploying a separate contract for each campaign.

Pros:

1. Single contract for all instant airdrop campaigns.
2. Simplifies monitoring of token flow, gas usage, unique users, and TVL.
3. Allows clawback before start time or after expiry.
4. No need for individual contract deployments.

Cons:

1. No contract admin means risk of unrecoverable accidental asset transfers.
2. May require UI to adapt to a new contract interface.

Click to expand mock interface code

interface ISablierMerkleDrop {
    /// @notice Admin of the campaign.
    function admin(uint256 campaignId) external returns (address);

    /// @notice The ERC-20 asset to distribute.
    function asset(uint256 campaignId) external returns (IERC20);

    /// @notice The cut-off point for the campaign, as a Unix timestamp. A value of zero means there is no expiration.
    function expiration(uint256 campaignId) external returns (uint40);

    /// @notice Returns a flag indicating whether a claim has been made for a given index.
    /// @dev Uses a bitmap to save gas.
    /// @param index The index of the recipient to check.
    function hasClaimed(uint256 campaignId, uint256 index) external returns (bool);

    /// @notice Returns a flag indicating whether the campaign has expired.
    function hasExpired(uint256 campaignId) external view returns (bool);

    /// @notice The content identifier for indexing the campaign on IPFS.
    function ipfsCID(uint256 campaignId) external view returns (string memory);

    /// @notice The root of the Merkle tree used to validate the proofs of inclusion.
    function merkle_root(uint256 campaignId) external returns (bytes32);

    /// @notice Returns the amount of tokens available to claim.
    function remainingClaimAmount(uint256 campaignId) external view returns (uint256);

    /// @notice Returns the start time of the campaign, upto which sender can clawback the funds.
    function startTime(uint256 campaignId) external view returns (uint40);

    /// @notice Returns the amount of tokens available to claim.
    function TotalClaimAmount(uint256 campaignId) external view returns (uint256);

    // **************** NON-CONSTANT FUNCTIONS *********** //

    /// @notice Creates a new campaign.
    function create(Params memory params) external returns (uint256 campaignId);

    /// @notice Claws back the tokens from the campaign until startTime or after expiration.
    function clawback(uint256 campaignId, address to, uint128 amount) external onlyCampaignAdmin(campaignId);

    /// @notice Makes the claim and withdraw tokens.
    function claim(
        uint256 campaignId,
        uint256 index,
        address recipient,
        uint128 amount,
        bytes32[] calldata merkleProof
    )
        external;
}

My comment

I am in favour of 2nd solution because I think having on-chain KPIs is important in the absence of stream creations. I'd like to hear everyone's opinion on this. Feel free to suggest more solution.

cc @sablier-labs/everybody

Related discussions

• Gas guzzling is a key KPI for instant airdrops contract

[razgraf]

Is the option where we do everything the same, but also trigger an instant withdraw worth considering? The advantage in this is: there's still a stream (so the UI would be compatible) which shows up in the dashboard, there's an NFT which people can see and hold as a badge, the volume still goes through our lockup contracts.

I know it's probably far from gas efficient, but wasn't sure if it was discussed before.

[smol-ninja]

Is the option where we do everything the same, but also trigger an instant withdraw worth considering?

For instant airdrop contract, yes. When user claims, the token will be transferred in the same tx. For Merkle lockup contract, I mentioned this in #997 that if we switch to createWithTimestamps we can enable withdrawing tokens in the same tx by setting end time in the past.

The advantage in this is: there's still a stream (so the UI would be compatible) which shows up in the dashboard, there's an NFT which people can see and hold as a badge, the volume still goes through our lockup contracts.
it's probably far from gas efficient

So for this, the relevant discussion would be #997.

[PaulRBerg]

I'm against using Lockup for one-time drops: (i) gas inefficient and (ii) complicated reverse lookups onchain. It'd be complicated to infer that the user received a one-time airdrop if they see an NFT getting created, multiple contracts involved, etc.

[PaulRBerg]

Thanks for breaking down the available options.

It really is a tough call, but I suggest going with Solution 1. Here's my rationale:

• The cons of Solution 2 are big
  • First and foremost, the UI as it currently stands could not be used with Solution 2. The terminology would have to be changed, the action flow, etc. This is a significant development cost that must not be overlooked.
  • Not being able to recover funds is very bad considering that people will definitely make errors.
• It's an industry standard to create a bespoke contract per airdrop campaign.
• TVL trackers will have to adapt (if they haven't already) to the reality of tracking TVL across multiple contracts with identical bytecodes.
• Independent of the one-time airdrop contract, it'd be wise to find a solution for tracking the existing MerkleLockup campaigns. Many campaigns have short vesting periods, which makes the Lockup TVL transitory.
• Like many things in life, usage will follow a Pareto distribution: a few one-time airdrop campaigns will drive most of the usage. Even if we don't manage to track all contracts, we can pinpoint to these contracts to ramp up our user metrics.

[smol-ninja]

Many good points. I was originally inclined towards option 2 but have changed my mind to vote for option 1. Your arguements are convincing enough.

[andreivladbrg]

Thanks, Shub, for opening this.

First, I want to clarify what your final decision is, @PaulRBerg, as you stated both:

1. I’m against using Lockup for one-time drops.
2. I suggest going with Solution 1.

At first, I’ll be honest, I considered option 2 (a bespoke contract) to be the better one, but after reading Paul’s comment, I changed my mind to option 1.

[PaulRBerg]

Solution 1 involves a MerkleLockup-like contract, not MerkleLockup itself.

[smol-ninja]

Solution 1 involves a MerkleLockup-like contract, not MerkleLockup itself.

I guess you meant MerkleLockup-like contract (merkleLL and merkleLT) not Sablier Lockup itself (Lockup Linear / Lockup Dynamic). Right?

[PaulRBerg]

Correct

[smol-ninja]

Thank you both for your inputs. Created an issue: #995 to implement option 1.

[smol-ninja]

On the name of the contract, would SablierMerkleInstant.sol be good? Removed "V2" because of package tethering approach.

[PaulRBerg]

That works, but what about MerkleAirdrop? Simple and clear.

[smol-ninja]

I think MerkleAirdrop is a broad category that encapsulates MerkleLL and MerkleLT as well since they also use Merkle tree to facilitate the airdrops via Lockup streams.

[PaulRBerg]

OK, good point, let's stick with Instant for the time being.

[smol-ninja]

Posting here the PR's description as it requires some more discussion.

Description

• Although this PR does not change APIs for SablierV2MerkleLL and SablierV2MerkleLT contracts, it makes some changes to them in order to allow all three Merkle contracts to share common code.

Alternate possibilities

• If we wish to make no changes at all to the Merkle Lockup contracts, then another solution would be to duplicate the common code inside SablierMerkleInstant itself.
• If we are going to deploy SablierMerkleInstant in the next release and not prior to that, then we can also change the API structure for SablierV2MerkleLL and SablierV2MerkleLT such that Lockup specific variables (cancelable and transferable) can be removed from the common constructer parameters, as they are not relevant to Merkle Instant contract.

I'd recommend briefly review the changes in this PR.

[PaulRBerg]

We have agreed to update Core to allow end times in the past, which means that we will have to redeploy the MerkleLL and MerkleLT contracts in the next release.

Thus, it should be fine to change the API for MerkleLL and MerkleLT so that we take the existence of Instant into account.

such that Lockup specific variables (cancelable and transferable) can be removed from the common constructer parameters

Let's do it. Why did you call this an alternate possibility, though?

[andreivladbrg]

Initially posted here (with the idea of changing the API in mind)

---

My answer depends on the timeline when we want to release (as you also pointed out).

AFAIK, the app will have a dedicated page for one-time airdrops, @razgraf, correct me if I am wrong. So, in this case, it requires additional work, so making a new release(change the API) for this IMO is fine.

---

As a smart contract architecture, it doesn’t make sense to include cancelable and transferable flags in the ConstructorParams struct. Moreover, the abstract contract can even be renamed so that it doesn’t include "Lockup", because it no longer has any property unique to our Lockup contracts. It has logic for a classic Merkle contract and some additional logic (clawback, grace period)

So, my proposal would be this:

Solidity interfaces

interface ISablierMerkle {
    function ASSET() external returns (IERC20);
    function EXPIRATION() external returns (uint40);
    function getFirstClaimTime() external view returns (uint40);
    function hasClaimed(uint256 index) external returns (bool);
    function hasExpired() external view returns (bool);
    function ipfsCID() external view returns (string memory);
    function MERKLE_ROOT() external returns (bytes32);
    function name() external returns (string memory);
    function clawback(address to, uint128 amount) external;
}

interface ISablierMerkleInstant is ISablierMerkle {
    function claim(uint256 index, address recipient, uint128 amount, bytes32[] calldata merkleProof) external;
}

interface ISablierMerkleLL is ISablierMerkle {
    function CANCELABLE() external returns (bool);
    function LOCKUP_LINEAR() external view returns (ISablierV2LockupLinear);
    function streamDurations() external view returns (uint40 cliff, uint40 duration);
    function TRANSFERABLE() external returns (bool);
}

interface ISablierMerkleLT is ISablierMerkle {
    function CANCELABLE() external returns (bool);
    function LOCKUP_TRANCHED() external view returns (ISablierV2LockupTranched);
    function getTranchesWithPercentages() external view returns (MerkleLT.TrancheWithPercentage[] memory);
    function TOTAL_PERCENTAGE() external view returns (uint40 cliff, uint40 duration);
    function TRANSFERABLE() external returns (bool);
    function claim(uint256 index, address recipient, uint128 amount, bytes32[] calldata merkleProof) external;
}

[smol-ninja]

Thank you both for your insights.

it doesn’t make sense to include cancelable and transferable flags in the ConstructorParams struct

Yes, agree. That is my 2nd point in the alternate possibilities section.

I agree with renaming it to ISablierMerkle. Seems like we have a consensus.

[smol-ninja]

Renaming ISablierMerkleLockup to ISablierMerkle would also mean using Merkle term as a replacement for MerkleLockup throughout the codebase. And renaming MerkleLockup library to Merkle library in Datatypes. Therefore, the use of the keyword Merkle can be misleading as it has its own meaning.

Thus, I ended up with the following refactors:

1. abstract ISablierMerkleLockup → abstract ISablierMerkleBase
2. library MerkleLockup → library MerkleBase
3. interface ISablierMerkleLockupFactory → interface ISablierMerkleFactory

Let me know if you have any strong opinion against it.

[PaulRBerg]

I like the proposed refactor.

[smol-ninja]

I am struggling to find a good name for merkle-lockup folder. Now that we would have merkleLL, merkleLT and merkleInstant, calling it merkle-lockup wouldn't do justice to the new merkle instant contract.

I refactored it to just merkle but it doesn't go so well since we import Merkle contract from murky.sol.

I thought of renaming it to merkle-base, but again, it does not go so well since merkle-base is just the base contract.

What should we call this category that encapsulates merkle-lockup-linear, merke-lockup-tranched and merkle-instant? or any suggestion for name? merkle-campaign?

[smol-ninja]

Decided to go with merkle-campaign.

[PaulRBerg]

merkle-campaign works for me

[smol-ninja]

Completed via #999.