Exhaustive documentation and tooling for lockup contract

[MaksymZavershynskyi]

Background

The lockup contract implementation and intended usage has been changing over time. As the result we have users that have different expectations about the contract. Additionally, NEAR community intends to use lockup contract for upcoming community projects. Since the amount of assets locked through this contract is substantial, we need to make sure there is no space for ambiguity in UX and DevX. Because we expect casual community user to be able to operate the contract we need to provide convenient tools to operate with the contract.

Documentation and Tooling

Therefore we need to provide the following the community:

• An exhaustive documentation
  • Reference. Current reference-level documentation is accessible here: https://github.com/near/core-contracts/tree/master/lockup Unfortunately, it focuses only on the interface and less on the behavior. It also only explains only the most recent version of the contract
  • Explanation. Current explanation-level documentation lives here: https://docs.near.org/docs/tokens/lockup It might be sufficient for now, but it does not go over all of the cases outlined below.
  • How-to guides. We need a walk-through for every single use-case.

See explainer on the types of documentation here:

• Precise web-tooling
  • Viewing contract state. Ideally, this tool would include schematic representation similar to https://docs.near.org/docs/tokens/lockup that would update depending on the current state of the contract. We currently have https://near.github.io/account-lookup/ but it might not work for all use-cases outlined below.
  • Owner UI to operate with the contract. Right now contract users need to operate with it via CLI, which might not be acceptable if we want community to use these lockup contracts for casual projects;
  • Foundation UI to initialize/terminate the contract in-mass. Also, if we find out that our current contract has a bug in the termination logic, this UI would take care of the workaround that we currently need to perform manually.

We should consider having a separate landing page for the lockup contract that links all documentations and UI tools in one place, potentially using Docusaurus (see Rust SDK book) or Gitbook (see wiki NEAR).

Use-cases

Our documentation and tooling should explicitly cover and differentiate the following cases:

• v1, v2, and v3 contracts. AFAIU they have different behavior lockup [3.0.0]: Update lockup release duration #136 and we have users of all versions;
• Pre-Mainnet and Post-Mainnet initialization;
• With and without vesting schedule;
• Contracts that are allowed to vest fully and contracts that are terminated early;

We should also consider collaborating with https://metapool.app/ on integration since we store a large amount of tokens in these lockup contracts and it would be beneficial if they could be tokenized in a way similar to stNEAR.

Audits

Finally, we should order several audits of the contracts, UI tools, and documentation to ensure that they are all consistent and cover the cases exhaustively.

[MaksymZavershynskyi]

CC @frol , @telezhnaya , @thisisjoshford

[telezhnaya]

I agree with most things you said.

I want to add: if we still want to use lockup contract implementation actively, I think we should consider rewriting it one more time (I know, we are not happy about that). Less functionality gives less number of bugs. I suggest to get rid of 2 mechanisms:

1. voting mechanism: we don't need it anymore
2. lockup mechanism. That is so confusing that we have 2 separate mechanics to lock the tokens. They are implementing almost the same mechanic, and the reader should always keep in mind how they will be combined in the end. Look at these graphs, it's not intuitive at all. The main benefit of lockup mechanism is the ability to lock the tokens without the possibility to terminate the process by anyone. I suggest to use vesting logic for that, passing None to foundation_account_id.