Llama Locker

Llama Locker allows users to lock their LLAMA tokens and earn a share of the yield generated by the treasury over time. It manages epochs, reward token distribution, and token locking/unlocking, ensuring fair and transparent reward distribution.

Lock Mechanism

• Locked NFTs cannot be withdrawn for 4 epochs (4 weeks) and are eligible to receive a proportionate share of yields during this period.
• Unlike the CVX Lock style, which requires active kicking out of tokens after the lock duration ends, LlamaLocker offers a more user-friendly approach.
• NFT owners can withdraw their NFTs in the epoch after the lock duration ends. If not withdrawn, the NFTs will automatically re-lock for the subsequent lock duration, streamlining the process and saving users on gas costs.

Example of Lock Mechanism

1. Alice locks Llama #1 on January 28, 2024, at 22:49:42 GMT.
2. Llama #1 starts accruing yields from February 1, 2024, at 00:00:00 GMT (next epoch).
3. Withdrawal of Llama #1 is possible anytime from February 29, 2024, at 00:00:00 GMT to March 7, 2024, at 00:00:00 GMT (one-week epoch).
4. If Llama #1 remains unwithdrawn during this window, it will automatically re-lock starting March 7, 2024, at 00:00:00 GMT.

Getting Started

Ensure you are using the latest version of Foundry:

foundryup

Install dependencies:

forge install

Run the tests:

forge test

Example output:

$ forge test
[⠊] Compiling...
[⠑] Compiling 1 files with Solc 0.8.23
[⠘] Solc 0.8.23 finished in 1.71s
Compiler run successful!

Ran 1 test for test/LlamaLocker.t.sol:LlamaLockerTest
[PASS] test_renounceOwnership_InvalidAction() (gas: 13389)
Suite result: ok. 1 passed; 0 failed; 0 skipped; finished in 1.44ms (93.38µs CPU time)

Ran 4 tests for test/AddRewardTokens.t.sol:AddRewardTokensTest
[PASS] test_addRewardTokens_InvalidRewardToken() (gas: 92195)
[PASS] test_addRewardTokens_InvalidRewardTokenCount() (gas: 13954)
[PASS] test_addRewardTokens_Unauthorized() (gas: 14191)
[PASS] test_addRewardTokens_Valid() (gas: 133255)
Suite result: ok. 4 passed; 0 failed; 0 skipped; finished in 1.60ms (179.63µs CPU time)

Ran 8 tests for test/Whitelist.t.sol:RewardDistributionTest
[PASS] test_disableWhitelist_InvalidAction() (gas: 20211)
[PASS] test_disableWhitelist_Unauthorized() (gas: 13655)
[PASS] test_disableWhitelist_Valid() (gas: 19409)
[PASS] test_lock_InvalidAction() (gas: 115192)
[PASS] test_lock_Valid() (gas: 225023)
[PASS] test_setRoot_InvalidAction() (gas: 15583)
[PASS] test_setRoot_Unauthorized() (gas: 13695)
[PASS] test_setRoot_Valid() (gas: 19625)
Suite result: ok. 8 passed; 0 failed; 0 skipped; finished in 1.65ms (751.29µs CPU time)

Ran 6 tests for test/LockMechanism.t.sol:LockMechanismTest
[PASS] test_lock_InvalidTokenCount() (gas: 11454)
[PASS] test_lock_Valid() (gas: 496076)
[PASS] test_unlock_InvalidLockOwner() (gas: 225991)
[PASS] test_unlock_InvalidTokenCount() (gas: 9265)
[PASS] test_unlock_InvalidUnlockWindow() (gas: 246840)
[PASS] test_unlock_ValidUnlockWindow() (gas: 222618)
Suite result: ok. 6 passed; 0 failed; 0 skipped; finished in 1.71ms (784.38µs CPU time)

Ran 5 tests for test/RewardDistribution.t.sol:RewardDistributionTest
[PASS] test_distributeRewardToken_Claimables() (gas: 1020171)
[PASS] test_distributeRewardToken_InvalidRewardAmount() (gas: 134541)
[PASS] test_distributeRewardToken_InvalidRewardToken() (gas: 17599)
[PASS] test_distributeRewardToken_InvalidTotalShares() (gas: 136631)
[PASS] test_distributeRewardToken_Unauthorized() (gas: 13900)
Suite result: ok. 5 passed; 0 failed; 0 skipped; finished in 2.06ms (1.10ms CPU time)

Ran 1 test for test/OffchainQuery.sol:LockMechanismTest
[PASS] test_getLocks() (gas: 11133290)
Suite result: ok. 1 passed; 0 failed; 0 skipped; finished in 11.34ms (9.86ms CPU time)

Ran 6 test suites in 161.35ms (19.81ms CPU time): 25 tests passed, 0 failed, 0 skipped (25 total tests)

Generate Merkle Tree

Install dependencies:

pnpm install

Update the whitelist.txt file.

Then get the merkle tree root and proofs via the following command:

pnpm run gen:merkle

Check the proof inside merkle-proofs.json.

Front End Integration

There are two main actions for users:

1. Lock NFT: Users can lock their NFT via lock(proofs, tokenIds) for whitelisted user and lock(tokenIds) for public.
2. Unlock NFT: Users can unlock their NFT via unlock.

Additional information:

• Claimable rewards are available via claimables(account).
• Claimed rewards are available via getClaimedRewards(account).
• Lock information can be retrieved via locks(nftId).

To compute the next unlock for the specified NFT, use the following formula:

lockedDuration = currentTimestamp - lockedAt
lockedDurationInEpoch = lockedDuration / EPOCH_DURATION
modulo = lockedDurationInEpoch % LOCK_DURATION_IN_EPOCH
unlockNextEpoch = LOCK_DURATION_IN_EPOCH - modulo
unlockStart = currentTimestamp + (unlockNextEpoch * EPOCH_DURATION)
unlockEnd = unlockStart + EPOCH_DURATION

unlockStart and unlockEnd define a time window in Unix timestamp when users can unlock their locked NFTs.

Admin actions:

• Admin can add a new reward token via addRewardToken.
• Admin can distribute weekly rewards via distributeRewardToken.
• Admin need to approve the LlamaLocker contract before executing distributeRewardToken.
• Admin can set new merkle tree root via setRoot(root) (for rolling whitelist)
• Admin can disable the whitelist via disableWhitelist() (for public launch)