Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix: address broken link on lockup readme #200

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 29 additions & 21 deletions lockup/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,16 +4,18 @@

This contract acts as an escrow that locks and holds an owner's tokens for a lockup period.
The contract consists of lockup and vesting processes that go simultaneously.
A high-level overview could be found [in NEAR documentation](https://docs.near.org/docs/tokens/lockup).
A high-level overview could be found [in NEAR documentation](https://wiki.near.org/ecosystem/near-token/lockups).

A lockup period starts from the specified timestamp and lasts for the specified duration.
Tokens will be unlocked linearly.

Vesting is an additional mechanism. It also locks the tokens, and it allows to configure 2 more options:

1. Ability to terminate tokens vesting and refund non-vested tokens back.
2. Cliff vesting period.

The owner can add a full access key to the account if all conditions are met:

- No transaction is in progress;
- Vesting and lockup processes finished;
- The termination process is ended (if applicable). If there’s a termination process started, it has to finish;
Expand All @@ -25,6 +27,7 @@ This will allow the owner to turn this contract account into a regular account,

Lockup is a mechanism of linear unlocking of tokens that could not be terminated.
It is described by the following fields:

- `lockup_timestamp` - The moment when tokens start linearly unlocking;
- `lockup_duration` - [deprecated] Alternative way to set the moment when the tokens become unlock.
The duration from [the moment transfers were enabled](https://near.org/blog/near-mainnet-phase-2-unrestricted-decentralized/) to the moment when linear unlocking begins;
Expand All @@ -41,6 +44,7 @@ The contract can contain a vesting schedule and serve as a vesting agreement bet
The foundation is set at the moment of initializing the contract by the `foundation_account_id` field.

A vesting schedule is described by three timestamps in nanoseconds:

- `start_timestamp` - When the vesting starts. E.g. the start date of employment;
- `cliff_timestamp` - When the first part of lockup tokens becomes vested.
The remaining tokens will vest continuously until they are fully vested.
Expand All @@ -50,7 +54,7 @@ A vesting schedule is described by three timestamps in nanoseconds:
```
cliff_tokens_percentage = (cliff_timestamp - start_timestamp) / (end_timestamp - start_timestamp)
```
- `end_timestamp` - When the vesting ends.
- `end_timestamp` - When the vesting ends.

Once the `cliff_timestamp` passed, the tokens are vested on a pro-rata basis from the `start_timestamp` to the `end_timestamp`.

Expand All @@ -59,6 +63,7 @@ Once the `cliff_timestamp` passed, the tokens are vested on a pro-rata basis fro
The contract could have both lockup and vesting schedules.

The tokens start to become liquid at the timestamp:

```
liquidity_timestamp = max(max(transfers_enabled_timestamp + lockup_duration, lockup_timestamp), cliff_timestamp)
```
Expand Down Expand Up @@ -100,6 +105,7 @@ It's because the contract has to maintain the minimum required balance to cover
### Guarantees

With the guarantees from the staking pool contracts, whitelist, and voting contract, the lockup contract provides the following guarantees:

- The owner can not lose tokens or block contract operations by using methods under the staking section.
- The owner can not prevent the foundation from withdrawing the unvested balance in case of termination.
- The owner can not withdraw tokens locked due to lockup period, disabled transfers, or vesting schedule.
Expand All @@ -126,6 +132,7 @@ Once the lockup schedule starts before the vesting schedule (e.g. employment sta
## Interface

Here are some useful links to the documented codebase:

- [The initialization method](https://github.com/near/core-contracts/blob/master/lockup/src/lib.rs#L151-L190);
- [Basic types](https://github.com/near/core-contracts/blob/master/lockup/src/types.rs#L12);
- [Owner's methods](https://github.com/near/core-contracts/blob/master/lockup/src/owner.rs);
Expand All @@ -150,24 +157,24 @@ Arguments in JSON format

```json
{
"owner_account_id": "owner1",
"lockup_duration": "0",
"lockup_timestamp": "1535760000000000000",
"release_duration": "126230400000000000",
"transfers_information": {
"TransfersEnabled": {
"transfers_timestamp": "1602614338293769340"
}
},
"vesting_schedule": {
"VestingSchedule": {
"start_timestamp": "1535760000000000000",
"cliff_timestamp": "1567296000000000000",
"end_timestamp": "1661990400000000000"
}
},
"staking_pool_whitelist_account_id": "staking-pool-whitelist",
"foundation_account_id": "near"
"owner_account_id": "owner1",
"lockup_duration": "0",
"lockup_timestamp": "1535760000000000000",
"release_duration": "126230400000000000",
"transfers_information": {
"TransfersEnabled": {
"transfers_timestamp": "1602614338293769340"
}
},
"vesting_schedule": {
"VestingSchedule": {
"start_timestamp": "1535760000000000000",
"cliff_timestamp": "1567296000000000000",
"end_timestamp": "1661990400000000000"
}
},
"staking_pool_whitelist_account_id": "staking-pool-whitelist",
"foundation_account_id": "near"
}
```

Expand All @@ -178,11 +185,13 @@ near call lockup1 new '{"owner_account_id": "owner1", "lockup_duration": "0", "l
```

If you need to use only lockup logic, change `vesting_schedule` parameter:

```
"vesting_schedule": None
```

If you need to use only vesting logic, change these parameters as follows:

```
"lockup_duration": 0,
"lockup_timestamp": None,
Expand Down Expand Up @@ -248,7 +257,6 @@ near call lockup1 check_transfers_vote '{}' --accountId=owner1 --gas=75000000000

Let's assume transfers are enabled now.


#### Check liquid balance and transfer 10 NEAR

```bash
Expand Down