VOTINGESCROW.md

VotingEscrow

State Transitions

This table has functions along the rows, with the state required to call the function. Side effects and the output of the function are listed in the boxes. An empty box means that that state cannot be used as an input into that function.

For example, if we take "Empty State" and createLock, this means that given no input, a call to createManagedLockFor will create a managed permanent nft.

• Mint refers to the mint event. Burn refers to the burn event. Convert implies state transition from one state to another (e.g. normal to normal permanent).
• Increases/decreases amount refers to LockedBalance.amount being increased/decreased.
• Extends locktime refers to LockedBalance.end being extended.
• Delegating involves modifying the delegatee field in the latest tokenId's checkpoint, as well as incrementing the delegatee's delegatedBalance field in the delegatee's latest checkpoint.
• Dedelegating involves deleting the delegatee field in the latest tokenId's checkpoint, as well as decrementing the prior delegatee's delegatedBalance field in the delegatee's latest checkpoint.
• Note that for merge, only the to NFT is allowed to be of type normal permanent.
• The last two rows refer to functions that exist in RewardsDistributor.

Function	Empty State	Normal	Normal Permanent	Locked	Managed Permanent
createLock	- Mints normal.
createManagedLockFor	- Mints managed permanent.
depositManaged		- Converts to locked. - Increases managed amount. - Increases (managed) delegatee balance.	- Dedelegates. - Converts to locked. - Increases managed amount. - Increases (managed) delegatee balance.
withdrawManaged				- Converts to normal. - May increase amount (locked rewards). - Extends locktime to maximum. - Decreases managed balance. - Decreases (managed) delegatee balance.
depositFor		- Increases amount.	- Increases amount. - Increases delegatee balance.		- Increases amount. - Deposits into LMR. - Increases delegatee balance.
increaseAmount		- Increases amount.	- Increases amount. - Increases delegatee balance.		- Increases amount. - Increases delegatee balance.
increaseUnlockTime		- Extends locktime.
withdraw		- Burns normal.
merge		- Burns from normal. - Increases to amount.	- Burns from normal. - Increases to amount. - Increases delegatee balance.
split		- Burns normal. - Mints two normal.	- Dedelegates - Burns normal. - Mints two normal.
lockPermanent		- Converts to normal permanent.
unlockPermanent			- Dedelegates - Converts to normal.
delegate			- Dedelegates. - Delegates.		- Dedelegates. - Delegates.
delegateBySig			- Dedelegates. - Delegates.		- Dedelegates. - Delegates.
distributor.claim		- Collect rebases.	- Collect rebases.		- Collect rebases.
distributor.claimMany		- Collect rebases.	- Collect rebases.		- Collect rebases.

Note that when a normal nft calls functions like depositFor, increaseAmount etc, dedelegation still occurs but is skipped as the tokenId has no delegatee.

Valid States

LockedBalance has several valid states:

• LockedBalance(amount, locktime, false) when an nft is in normal state. locktime is at most block.timestamp + MAXTIME.
• LockedBalance(amount, 0, true)when an nft is in normal permanent.
• LockedBalance(0, 0, true) when a managed nft has no deposits.
• LockedBalance(0, 0, false) when an nft is burnt or in locked state.

A token's LockedBalance is updated whenever amount, end or isPermanent changes.

UserPoint has several valid states:

• UserPoint(slope, bias, ts, 0) when an nft is in normal state.
• UserPoint(0, 0, ts, permanent) when an nft is in permanent state, with the value of permanent equal to the nft's LockedBalance.amount.
• UserPoint(0, 0, ts, 0) when an nft is burnt.

A token's UserPoint is updated whenever LockedBalance changes. The global point is also updated at the same time. If there are multiple writes to a token's UserPoint or the GlobalPoint in one block, it will overwrite the prior point. Points retrieved from the user point history and global point history will always have unique timestamps. For user points and global points, the first checkpoint at index 0 is always empty. The first point is written to index 1. A UserPoints for a certain tokenId will always have a unique timestamp and block number. The same is true for GlobalPoints.

(Voting) checkpoints have several valid states:

• Checkpoint(ts, owner, 0, 0) when an nft is not delegating (i.e. in normal / normal permanent / locked / managed permanent state and is not delegating) and has not been delegated to.
• Checkpoint(ts, owner, delegatedBalance, 0)when an nft is not delegating (i.e. in normal / normal permanent / locked / managed permanent state and is not delegating) but has been delegated to.
• Checkpoint(ts, owner, 0, delegatee) when an nft is delegating (permanent locks only) and has not received any delegations.
• Checkpoint(ts, owner, delegatedBalance, delegatee) when an nft is delegating (permanent locks only) and has received delegations.
• Checkpoint(ts, 0, delegatedBalance, 0) when an nft is burnt. delegatedBalance may be non-zero as this nft may still be delegated to. But it cannot vote as it has no owner.

The initial voting checkpoint is created on the minting of a token. Subsequent voting checkpoints are created whenever the owner, delegatedBalance or delegatee changes. Ownership can change from transfers, or from burn (e.g. merge, split, withdraw). delegatee can change from delegation / dedelegation. delegatedBalance is updated on the delegatee whenever a delegation / dedelegation takes place. If there are multiple writes to a token's voting checkpoints in one block, it will overwrite the prior point. Points retrieved from the checkpoint history will always have unique timestamps. For voting checkpoints, the first checkpoint is written to index 0.