VoteEscrowDistribution

Description:

This contract handles the distribution of tokens (e.g., fees or rewards) to users based on their locked balances (voting power) in an associated VotingEscrow contract. It operates on a weekly epoch system, calculating and allowing users to claim their proportional share of tokens deposited into this contract. The claimed tokens are typically deposited back into the user's lock in the VotingEscrow contract, effectively compounding their rewards.

---

Constructor

constructor(address _voting_escrow)

Description:

Initializes the VoteEscrowDistribution contract upon deployment. It sets the start time aligned to the beginning of the current week, identifies the VotingEscrow contract and its underlying token, sets the deployer as the initial depositor (who can checkpoint tokens), and approves the VotingEscrow contract to spend the maximum amount of the token held by this contract (necessary for depositing claimed rewards).

Input Parameters:

Name	Type	Description
_voting_escrow	address	The address of the VotingEscrow contract managing the locks.

---

timestamp

function timestamp() external view returns (uint)

Description:

Returns the current block timestamp rounded down to the beginning of the current week (based on WEEK = 7 * 86400 seconds).

Return Value:

Type	Description
uint	The timestamp marking the start of the current week.

---

checkpoint_token

function checkpoint_token() external

Description:

Updates the distribution schedule based on the tokens newly received by this contract since the last checkpoint. It calculates the amount of new tokens and distributes them proportionally over the weeks that have passed since the last token checkpoint (last_token_time). This function must be called by the designated depositor.

This function should be called periodically by the depositor (e.g., weekly, or whenever reward tokens are sent to this contract) to make new rewards available for claiming.

Events Emitted: CheckpointToken(uint time, uint tokens)

---

ve_for_at

function ve_for_at(uint _tokenId, uint _timestamp) external view returns (uint)

Description:

Calculates the voting power (veToken balance) of a specific NFT lock (_tokenId) at a specified past timestamp (_timestamp). It reads historical data from the associated VotingEscrow contract.

Input Parameters:

Name	Type	Description
_tokenId	uint	The ID of the NFT representing the lock in the VotingEscrow contract.
_timestamp	uint	The specific past timestamp at which to calculate the veToken balance.

Return Value:

Type	Description
uint	The veToken balance (voting power) of the lock at the specified timestamp.

---

checkpoint_total_supply

function checkpoint_total_supply() external

Description:

Updates the contract's internal record of the total veToken supply (ve_supply) for past weeks. It reads checkpoint data from the associated VotingEscrow contract and calculates the supply at the beginning of each week from the last recorded time_cursor up to the current week.

This function ensures the ve_supply mapping used in claim calculations is up-to-date. It is often called internally by claim() or claim_many() if the time_cursor is behind the current time.

---

claimable

function claimable(uint _tokenId) external view returns (uint)

Description:

Calculates the total amount of tokens claimable for a specific NFT lock (_tokenId) based on its historical voting power relative to the total voting power and the tokens distributed each week. This is a read-only function and does not change the contract state.

Input Parameters:

Name	Type	Description
_tokenId	uint	The ID of the NFT representing the lock in the VotingEscrow contract.

Return Value:

Type	Description
uint	The amount of tokens currently claimable for the NFT.

---

claim

function claim(uint _tokenId) external returns (uint)

Description:

Claims the accumulated distributable tokens for a single NFT lock (_tokenId). It calculates the claimable amount, updates the user's claim tracking (time_cursor_of, user_epoch_of), and deposits the claimed tokens back into the user's lock within the associated VotingEscrow contract using deposit_for.

This function may trigger _checkpoint_total_supply() if required before calculating the claim.

Input Parameters:

Name	Type	Description
_tokenId	uint	The ID of the NFT representing the lock in the VotingEscrow contract.

Return Value:

Type	Description
uint	The amount of tokens successfully claimed and deposited.

Events Emitted: Claimed(uint tokenId, uint amount, uint claim_epoch, uint max_epoch)

---

claim_many

function claim_many(uint[] memory _tokenIds) external returns (bool)

Description:

Claims accumulated distributable tokens for multiple NFT locks specified in the _tokenIds array in a single transaction. It iterates through the array, performs the claim logic for each ID, and deposits the claimed tokens back into the respective locks in the VotingEscrow contract.

This function can be more gas-efficient than calling claim() multiple times individually. It stops processing the array if it encounters a tokenId of 0. May trigger _checkpoint_total_supply() if required.

Input Parameters:

Name	Type	Description
_tokenIds	uint[] memory	An array of NFT IDs for which to claim tokens.

Return Value:

Type	Description
bool	Returns true upon successful execution of the transaction.

Events Emitted: Claimed(uint tokenId, uint amount, uint claim_epoch, uint max_epoch) (for each successful claim in the loop)

---

setDepositor

function setDepositor(address _depositor) external

Description:

Allows the current depositor to transfer the depositor role to a new address. Only the address currently set as depositor can successfully call this function.

This is an administrative function used to change the authorised address responsible for calling checkpoint_token().

Input Parameters:

Name	Type	Description
_depositor	address	The address to designate as the new depositor.