As explained in BEP9, some business plans decide to lock certain amount tokens for pre-defined periods of time, and the only vest in the future according to the schedules. For example, some projects may lock some allocation of the issued tokens as a commitment by the founding team; some business scenarios also need to lock some tokens as collateral for value.
You can only lock tokens on your own account. TimeLock will transfer locked tokens to a purely-code-controlled escrow account and before the lock time expires. A purely-code-controlled escrow account is a kind of account which is derived from a hard-coded string in binance chain protocol. This kind of account has no its own private key and it's only controled by code in protocol. The code for calculating escrow account is the same as how it's done in cosmos-sdk:
TimeLockCoinsAccAddr = sdk.AccAddress(crypto.AddressHash([]byte("BinanceChainTimeLockCoins")))
The account for mainnet is: bnb1hn8ym9xht925jkncjpf7lhjnax6z8nv24fv2yq and the account for testnet is: tbnb1hn8ym9xht925jkncjpf7lhjnax6z8nv2mu9wy3 The specific user will not be able to claim them back, including restrictions where they cannot use, transfer or spend these tokens.
You must use --broadcast to submit your transaction to the blockchain, otherwise it will return an unsigned transaction.
| Field | Type | Description |
|---|---|---|
| Description | string | Description of the lock operation. Max length of description is 128 bytes. |
| Amount | []Coin | A set of tokens to be locked |
| LockTime | int64 | The time when these tokens can be unlocked. LockTime is a future timestamp (seconds elapsed from January 1st, 1970 at UTC) and max LockTime should be before 10 years from now. |
| broadcast | bool | if you want to submit your transaction to the blockchain |
0.01 BNB will be charged on TimeLock transactions.
On testnet, you can lock 1BNB for 1 day.
./tbnbcli token time-lock --amount "100000000:BNB" --from <key-name> --description " test timelock" --lock-time <lock-timestamp> --chain-id Binance-Chain-Nile --trust-node --node http://data-seed-pre-0-s3.binance.org:80 --broadcast
On mainnet, you can lock 1BNB for 1 day.
./bnbcli token time-lock --amount "100000000:BNB" --from <key-name> --description " test timelock" --lock-time <lock-timestamp> --chain-id Binance-Chain-Tigris --node http://dataseed1.binance.org:80 --broadcast
TimeUnlock will claim the locked tokens back when the specified lock time has passed.
| Field | Type | Description |
|---|---|---|
| address | string | the address you want to query |
| time-lock-id | int64 | the id of your locking, it's incremental |
0.01 BNB will be charged on ReLock transactions.
On testnet, you can unlock tokens
./tbnbcli token time-unlock --from <your-address> --time-lock-id <lock-id> --chain-id Binance-Chain-Nile --trust-node --node http://data-seed-pre-0-s3.binance.org:80
On mainnet, you can unlock tokens.
./bnbcli token time-unlock --from <key-name> --time-lock-id <lock-id> --chain-id Binance-Chain-Tigris --node http://dataseed1.binance.org:80
Example output for trying to unlock tokens whose locking period is not expired:
ERROR: {"codespace":7,"code":7,"abci_code":458759,"message":"Can not unlock: lock time(2019-06-28 09:26:54 +0000 UTC) is after now(2019-06-27 08:31:54.680643156 +0000 UTC)"}
TimeRelock can extend lock times, increase the amount of locked tokens or modify the description of an existing lock record.
PLease note that you either increase the expire time or amount of your lock of tokens which are not unlocked.
| Field | Type | Description |
|---|---|---|
| time-lock-id | int64 | the id of your locking, it's incremental |
| Amount | []Coin | A set of tokens to be locked |
| LockTime | int64 | The time when these tokens can be unlocked. LockTime is a future timestamp(seconds elapsed from January 1st, 1970 at UTC) and max LockTime should be before 10 years from now. |
| broadcast | bool | if you want to submit your transaction to the blockchain |
0.01 BNB will be charged on UnLock transactions.
On testnet, you can relock tokens
./tbnbcli token time-relock --time-lock-id <lock-id> --increase-amount-to <amount of tokens> --from <key-name> --chain-id Binance-Chain-Nile --node=data-seed-pre-2-s1.binance.org:80 --broadcast
On mainnet, you can relock tokens
./bnbcli token time-relock --time-lock-id <lock-id> --increase-amount-to <amount of tokens> --from <key-name> --chain-id Binance-Chain-Tigris --node http://dataseed1.binance.org:80 --broadcast
Output if you don't add more tokens or don't extend your locking period, you will get the following error:
ERROR: {"codespace":7,"code":6,"abci_code":458758,"message":"Invalid lock amount: new locked coins(100000000BNB) should be more than original locked coins(100000000BNB)"}
QueryTimeLock will query a lock record of a given address by the id. If this locking is ended, then no info will be returned.
| Field | Type | Description |
|---|---|---|
| time-lock-id | int64 | the id of your locking, it's incremental |
On testnet, you can query lock history by ID:
./tbnbcli token query-time-lock --from <your-key-name> --time-lock-id <lock-id> --chain-id Binance-Chain-Nile --trust-node --node http://data-seed-pre-0-s3.binance.org:80
On mainnet, you can query lock history:
./bnbcli token query-time-lock --from <your-key-name> --time-lock-id <lock-id> --chain-id Binance-Chain-Tigris --trust-node --node http://dataseed1.binance.org:80
Example output:
[
{
"id": "1",
"description": " test timelock",
"amount": [
{
"denom": "BNB",
"amount": "100000000"
}
],
"lock_time": "2019-06-27T01:59:52Z"
}
]
QueryTimeLocks will query all lock records of a given address.
| Field | Type | Description |
|---|---|---|
| address | string | the address you want to query |
On testnet, you can query lock history by address:
./tbnbcli token query-time-locks --address <your-address> --chain-id Binance-Chain-Nile --trust-node --node http://data-seed-pre-0-s3.binance.org:80
On mainnet, you can query lock history by address:
./bnbcli token query-time-locks --address <your-address> --chain-id Binance-Chain-Tigris --trust-node --node http://dataseed1.binance.org:80
Example output:
[
{
"id": "1",
"description": " test timelock",
"amount": [
{
"denom": "BNB",
"amount": "100000000"
}
],
"lock_time": "2019-06-27T01:59:52Z"
},
{
"id": "2",
"description": " test timelock",
"amount": [
{
"denom": "BNB",
"amount": "100000000"
}
],
"lock_time": "2019-06-28T09:26:54Z"
}
]