Vesting tokens using ZWallet

0Chain
Search…
Explorer
ZWallet CLI
Get Started
Zwallet Operations
Locking Tokens using ZWallet
Staking on miners and sharders
Vesting tokens using ZWallet
Troubleshooting
Zbox CLI
Setup a 0Chain Testnet
Blobber
0miner
0Chain Diagnostics Glossary
Vesting tokens using ZWallet
Vesting pool allows the transfer of locked tokens to desired destination after a certain period of time. For every vesting pool configuration there is a minimum lock demand, maximum number of transfers, minimum and maximum duration of locking.
Checking vesting pool config
ZWallet allows vesting of tokens through a Vesting Pool smart contract config which can be viewed using vp-config command.
Sample Command:
1
./zwallet vp-config
Copied!
Sample Response:
1
min_lock: 0.01
2
min_duration: 2m0s
3
max_duration: 2h0m0s
4
max_destinations: 3
5
max_description_length: 20
Copied!
In the above response you can see all the constraints(lock demand, lock duration, and transfer limits) for a particular ZWallet vesting pool config.
Creating a vesting pool
Creating a new vesting pool through ZWallet can be done using the ./zwallet vp-add command which require specific parameters. To view parameters use the --helpflag.
1
Add a vesting pool.
2
​
3
Usage:
4
  zwallet vp-add [flags]
5
​
6
Flags:
7
      --d strings            list of colon separated 'destination:amount' values,
8
                             use -d flag many times to provide few destinations, for example 'dst:1.2'
9
      --description string   pool description, optional
10
      --duration duration    vesting duration till end, required
11
      --fee float            transaction fee, optional
12
  -h, --help                 help for vp-add
13
      --lock float           lock tokens for the pool, optional
14
      --start_time int       start_time, Unix seconds, default is now
15
​
Copied!
Here, descriptions for the vesting pool is optional ,while the --ddestination flag by which certain amount of tokens gets transferred to receiver's wallet requires values in the form of wallet client_id: amount of tokens. The destination--dparameter has to be repeated for transferring to more than one destination whereas lock duration and minimum locked tokens for the vesting pool is required and has to match specified vesting pool config limit. Also, the number of tokens locked should match or more than the sum of destination amounts specified to create a read pool.
Here is a sample command for transferring 1 token to a single destination wallet after 10 minutes:
1
./zwallet vp-add --duration 10m --d 48965bc485e6d42c02c2d53548ad90b79cc9cb2b26f6cfd3331bb0e5f10c7a14:1 --lock 2  
Copied!
Command for transferring tokens to multiple destination wallets after 5minutes:
1
./zwallet vp-add --duration 5m --lock 5 --d af6c894e2f5dd76b6df1329e924b4177e58692d165090f52b0cc11c639b3bb92:1 --d 8c4e3623964442e7ff9b9f52e5e7a5d8248a85856cf369f71149b7b922653396:2
Copied!
Response:
1
Vesting pool added successfully: 2bba5b05949ea59c80aed3ac3474d7379d3be737e8eb5a968c52295e48333ead:vestingpool:3464e71dd1c6e03ce4c81eb793dec97b36f28ff63380c3923db482280b302c6e
Copied!
On a successful response the pool id is generated in form of a vesting pool. The pool by default will transfer the tokens after 10 minutes from the time it is created. If you want the transfer at a later time you have to specify the --start_time flag.
Note: The destination wallets should be registered on the blockchain before creating a read pool.
Checking vesting pool list for a wallet
./zwallet vp-list command is used to display the vesting pool list for a given wallet. Parameters can be viewed using --help flag.
1
Usage:
2
  zwallet vp-list [flags]
3
​
4
Flags:
5
      --client_id string   client_id, default is current client
6
  -h, --help               help for vp-list
7
​
8
​
Copied!
Here, client_id for a particular wallet can be fetched using cat command. If not specified it will use the wallet at ~/.zcn/wallet.json
Sample Command:
1
./zwallet vp-list
Copied!
Sample Output:
1
2bba5b05949ea59c80aed3ac3474d7379d3be737e8eb5a968c52295e48333ead:vestingpool:31057638b65c3a8334c11ba3035e36316de046869f39c5f28a14a05df78edaa1
2
-  2bba5b05949ea59c80aed3ac3474d7379d3be737e8eb5a968c52295e48333ead:vestingpool:3464e71dd1c6e03ce4c81eb793dec97b36f28ff63380c3923db482280b302c6e
3
-  2bba5b05949ea59c80aed3ac3474d7379d3be737e8eb5a968c52295e48333ead:vestingpool:6021c16f7dcfd1926cce021e2f3af419509a56e32f6025514125528596c34a3c
4
​
Copied!
Note: There can be empty finalized block error during the execution of vp-info command. Check the troubleshooting section for solution.
Checking vesting pool info
./zwallet vp-info can be used to view information for a particular vesting pool. Parameters can be viewed using the ./zwallet vp-info --help
1
Usage:
2
  zwallet vp-info [flags]
3
​
4
Flags:
5
  -h, --help             help for vp-info
6
      --pool_id string   pool identifier
7
​
8
​
Copied!
Here, pool_id is required to fetch information for a particular vesting pool. Users can view pool_id by using the vp-list command.
Sample command:
1
./zwallet vp-info --pool_id 2bba5b05949ea59c80aed3ac3474d7379d3be737e8eb5a968c52295e48333ead:vestingpool:d16baced7162edb84536c95aa8de895a9494bf39a43a4f591350db98f0329886
2
​
Copied!
Response:
1
pool_id:     
2
2bba5b05949ea59c80aed3ac3474d7379d3be737e8eb5a968c52295e48333ead:vestingpool:d16baced7162edb84536c95aa8de895a9494bf39a43a4f591350db98f0329886
3
balance:      5
4
can unlock:   2 (excess)
5
sent:         0 (real value)
6
pending:      3 (not sent, real value)
7
vested:       3 (virtual, time based value)
8
description:  
9
start_time:   2021-05-08 00:06:00 +1000 AEST
10
expire_at:    2021-05-08 00:11:00 +1000 AEST
11
destinations:
12
  - id:          af6c894e2f5dd76b6df1329e924b4177e58692d165090f52b0cc11c639b3bb92
13
    vesting:     1
14
    can unlock:  1 (virtual, time based value)
15
    sent:        0 (real value)
16
    pending:     1 (not sent, real value)
17
    vested:      1 (virtual, time based value)
18
    last unlock: 2021-05-08 00:06:00 +1000 AEST
19
  - id:          8c4e3623964442e7ff9b9f52e5e7a5d8248a85856cf369f71149b7b922653396
20
    vesting:     2
21
    can unlock:  2 (virtual, time based value)
22
    sent:        0 (real value)
23
    pending:     2 (not sent, real value)
24
    vested:      2 (virtual, time based value)
25
    last unlock: 2021-05-08 00:06:00 +1000 AEST
26
client_id:    e6bca3f65f3ac102cd972ee2a85c4ee8318fd63cce91f14a76e81d024451213e
Copied!
In the response, you will see the total tokens locked (5) and total tokens that can be unlocked (tokens that are not vested). According to the above response three tokens are vested and still has to be transferred(pending) to two different destination wallets after expiration time.
Note: There can be empty finalized block error during the execution of vp-info command. Check the troubleshooting section for resolution.
Triggering a vesting pool
./zwallet vp-trigger command is used to instantly transfer vesting tokens to destination wallets before expiration time. Parameters can be viewed using the ./zwallet vp-trigger --help command.
1
Usage:
2
  zwallet vp-trigger [flags]
3
​
4
Flags:
5
  -h, --help             help for vp-trigger
6
      --pool_id string   pool identifier, required
7
​
Copied!
Here, pool_id is required to trigger a particular vesting pool, pool_id can be viewed using the vp-list command. To demonstrate the vp-triggerfunctionality we will consider a vesting pool which has some vested tokens to transfer to destination wallets. Here is vp-infoof a vesting pool before triggering.
1
pool_id:      2bba5b05949ea59c80aed3ac3474d7379d3be737e8eb5a968c52295e48333ead:vestingpool:31057638b65c3a8334c11ba3035e36316de046869f39c5f28a14a05df78edaa1
2
balance:      2
3
can unlock:   1 (excess)
4
sent:         0 (real value)
5
pending:      1 (not sent, real value)
6
vested:       0.2166666666 (virtual, time based value)
7
description:
8
start_time:   2021-05-18 21:15:16 +0000 UTC
9
expire_at:    2021-05-18 21:25:16 +0000 UTC
10
destinations:
11
  - id:          48965bc485e6d42c02c2d53548ad90b79cc9cb2b26f6cfd3331bb0e5f10c7a14
12
    vesting:     1
13
    can unlock:  0.2166666666 (virtual, time based value)
14
    sent:        0 (real value)
15
    pending:     1 (not sent, real value)
16
    vested:      0.2166666666 (virtual, time based value)
17
    last unlock: 2021-05-18 21:15:16 +0000 UTC
18
​
Copied!
As you can see, 1 token will be transferred to the destination after expire time . Lets use the vp-triggeron this pool and transfer the tokens right away.
Command:
1
./zwallet vp-trigger --pool_id 2bba5b05949ea59c80aed3ac3474d7379d3be737e8eb5a968c52295e48333ead:vestingpool:31057638b65c3a8334c11ba3035e36316de046869f39c5f28a14a05df78edaa1
Copied!
Response:
1
Vesting triggered successfully.
Copied!
Verify by using the vp-info command the Vesting pool info should not show tokens in sent.
1
pool_id:      2bba5b05949ea59c80aed3ac3474d7379d3be737e8eb5a968c52295e48333ead:vestingpool:31057638b65c3a8334c11ba3035e36316de046869f39c5f28a14a05df78edaa1
2
balance:      1.3816666667
3
can unlock:   1 (excess)
4
sent:         0.6183333333 (real value)
5
pending:      0.3816666667 (not sent, real value)
6
vested:       0.7266666666 (virtual, time based value)
7
description:
8
start_time:   2021-05-18 21:15:16 +0000 UTC
9
expire_at:    2021-05-18 21:25:16 +0000 UTC
10
destinations:
11
  - id:          48965bc485e6d42c02c2d53548ad90b79cc9cb2b26f6cfd3331bb0e5f10c7a14
12
    vesting:     1
13
    can unlock:  0.1083333333 (virtual, time based value)
14
    sent:        0.6183333333 (real value)
15
    pending:     0.3816666667 (not sent, real value)
16
    vested:      0.7266666666 (virtual, time based value)
17
    last unlock: 2021-05-18 21:21:27 +0000 UTC
18
​
Copied!
Unlocking tokens of a vesting pool
.zwallet vp-unlock command can be used to unlock tokens from a vesting pool by both the owner and destination wallets. Note that owner can only unlock tokens which are not yet vested while receiver can only unlock vested tokens.
Parameters can be viewed using the ./zwallet vp-unlock --help.
1
Usage:
2
  zwallet vp-unlock [flags]
3
​
4
Flags:
5
  -h, --help             help for vp-unlock
6
      --pool_id string   pool identifier, required
7
​
Copied!
Here, pool_id is a required flag to unlock the particular vesting pool from the destination or owner wallet side. To show vp-unlock functionality we will do unlocking of tokens from owner wallet side then the destination side.
Unlocking tokens from owner wallet
First let's unlock the vesting pool from owner wallet which has some tokens yet to be vested. The wallet balance and vesting pool info before unlocking are as follows:
1
Balance: 1.3039999999 (1.1422844399124015 USD)
Copied!
1
pool_id:      2bba5b05949ea59c80aed3ac3474d7379d3be737e8eb5a968c52295e48333ead:vestingpool:074de87c15855db511352491131f31ddc79f35ef2c912137e12a8f5aeb2fee81
2
balance:      3
3
can unlock:   1 (excess)
4
sent:         0 (real value)
5
pending:      2 (not sent, real value)
6
vested:       0.1433333333 (virtual, time based value)
7
description:
8
start_time:   2021-05-18 21:55:53 +0000 UTC
9
expire_at:    2021-05-18 22:15:53 +0000 UTC
10
destinations:
11
  - id:          48965bc485e6d42c02c2d53548ad90b79cc9cb2b26f6cfd3331bb0e5f10c7a14
12
    vesting:     2
13
    can unlock:  0.1433333333 (virtual, time based value)
14
    sent:        0 (real value)
15
    pending:     2 (not sent, real value)
16
    vested:      0.1433333333 (virtual, time based value)
17
    last unlock: 2021-05-18 21:55:53 +0000 UTC
18
client_id:    48965bc485e6d42c02c2d53548ad90b79cc9cb2b26f6cfd3331bb0e5f10c7a14
19
​
Copied!
There is a single token which yet has to be vested and is available to unlock in the can unlock variable above. Use vp-unlock to unlock that.
Command:
1
./zwallet vp-unlock --pool_id 2bba5b05949ea59c80aed3ac3474d7379d3be737e8eb5a968c52295e48333ead:vestingpool:074de87c15855db511352491131f31ddc79f35ef2c912137e12a8f5aeb2fee81
Copied!
Response:
1
Tokens unlocked successfully
Copied!
Wallet balance after unlocking:
1
Balance: 2.3039999999 (2.0208453119122893 USD)
Copied!
Unlocking tokens from destination wallet
Tokens can only be unlocked when they are vested. Here is a vesting pool info and a wallet balance of receiver wallet before unlocking of vesting tokens:
1
Balance: 2.3039999999 (1.99410739191345 USD)
Copied!
1
pool_id:      2bba5b05949ea59c80aed3ac3474d7379d3be737e8eb5a968c52295e48333ead:vestingpool:ddc459b2f186719020ec999dd377e097347e1204f95ee0674cd1a454c384260e
2
balance:      2
3
can unlock:   1 (excess)
4
sent:         0 (real value)
5
pending:      1 (not sent, real value)
6
vested:       1 (virtual, time based value)
7
description:
8
start_time:   2021-05-18 22:13:16 +0000 UTC
9
expire_at:    2021-05-18 22:15:16 +0000 UTC
10
destinations:
11
  - id:          48965bc485e6d42c02c2d53548ad90b79cc9cb2b26f6cfd3331bb0e5f10c7a14
12
    vesting:     1
13
    can unlock:  1 (virtual, time based value)
14
    sent:        0 (real value)
15
    pending:     1 (not sent, real value)
16
    vested:      1 (virtual, time based value)
17
    last unlock: 2021-05-18 22:13:16 +0000 UTC
18
client_id:    48965bc485e6d42c02c2d53548ad90b79cc9cb2b26f6cfd3331bb0e5f10c7a14
Copied!
From the above vesting pool information one vested token is available to unlock in destinations section. Let's unlock that token from receiver's wallet.
Command:
1
./zwallet vp-unlock --pool_id 2bba5b05949ea59c80aed3ac3474d7379d3be737e8eb5a968c52295e48333ead:vestingpool:ddc459b2f186719020ec999dd377e097347e1204f95ee0674cd1a454c384260e
Copied!
Response:
1
Tokens unlocked successfully.
Copied!
Receiver's Wallet balance after unlocking:
1
Balance: 3.3039999999 (2.9055805519120583 USD)
Copied!
Stopping vesting for a destination
./zwallet vp-stopcommand is used to stop transferring of tokens to a destination wallets. The owner can stop vesting for a destination and unlock the rest of tokens not yet vested.
Parameters can be viewed using./zwallet vp-stop --help command.
1
Usage:
2
  zwallet vp-stop [flags]
3
​
4
Flags:
5
      --d string         destination to stop vesting, required
6
  -h, --help             help for vp-stop
7
      --pool_id string   pool identifier, required
8
​
Copied!
Here, pool_id with --d(client _id of the destination wallet) is required. Both can be fetched using the vp-infocommand.
For showing the vp-stop functionality we are considering the vesting pool which has some tokens vested for destinations. Here is a vp-infofor that pool.
1
pool_id:      2bba5b05949ea59c80aed3ac3474d7379d3be737e8eb5a968c52295e48333ead:vestingpool:6cf68385b9200419a6f1e54ea7809a2859298e19b567cbbe9d69736b9ee61c44                                                                          
2
balance:      2
3
can unlock:   1 (excess)
4
sent:         0 (real value)
5
pending:      1 (not sent, real value)
6
vested:       0.1 (virtual, time based value)
7
description:
8
start_time:   2021-05-18 22:35:17 +0000 UTC
9
expire_at:    2021-05-18 22:45:17 +0000 UTC
10
destinations:
11
  - id:          48965bc485e6d42c02c2d53548ad90b79cc9cb2b26f6cfd3331bb0e5f10c7a1                                                                              4
12
    vesting:     1
13
    can unlock:  0.1 (virtual, time based value)
14
    sent:        0 (real value)
15
    pending:     1 (not sent, real value)
16
    vested:      0.1 (virtual, time based value)
17
    last unlock: 2021-05-18 22:35:17 +0000 UTC
18
client_id:    48965bc485e6d42c02c2d53548ad90b79cc9cb2b26f6cfd3331bb0e5f10c7a14
Copied!
Lets use the vp-unlock command to stop vesting for destinations, --dflag would be the client_id mentioned in the vp-info output.
Command:
1
./zwallet vp-stop --d 48965bc485e6d42c02c2d53548ad90b79cc9cb2b26f6cfd3331bb0e5f10c7a14 --pool_id 2bba5b05949ea59c80aed3ac3474d7379d3be737e8eb5a968c52295e48333ead:vestingpool:6cf68385b9200419a6f1e54ea7809a2859298e19b567cbbe9d69736b9ee61c44 
Copied!
Response:
1
Stop vesting for 48965bc485e6d42c02c2d53548ad90b79cc9cb2b26f6cfd3331bb0e5f10c7a14.
Copied!
To verify whether vesting to destinations has stopped use vp-info. Here is a output of vesting pool after vp-stop
1
pool_id:      2bba5b05949ea59c80aed3ac3474d7379d3be737e8eb5a968c52295e48333ead:vestingpool:6cf68385b9200419a6f1e54ea7809a2859298e19b567cbbe9d69736b9ee61c44
2
balance:      1.1433333334
3
can unlock:   1.1433333334 (excess)
4
sent:         0 (real value)
5
pending:      0 (not sent, real value)
6
vested:       0 (virtual, time based value)
7
description:
8
start_time:   2021-05-18 22:35:17 +0000 UTC
9
expire_at:    2021-05-18 22:45:17 +0000 UTC
10
destinations:
11
client_id:    48965bc485e6d42c02c2d53548ad90b79cc9cb2b26f6cfd3331bb0e5f10c7a14
Copied!
As you can see there are no destinations mentioned for vesting which is the desired behavior.
Deleting a vesting pool
./zwallet vp-delete command is used to delete a created vesting pool and unlock the tokens not yet vested. Parameters for vp-delete can be viewed using ./zwallet vp-delete --help.
1
Delete a vesting pool.
2
​
3
Usage:
4
  zwallet vp-delete [flags]
5
​
6
Flags:
7
  -h, --help             help for vp-delete
8
      --pool_id string   pool identifier, required
9
​
Copied!
Here, pool_id to fetch a particular vesting pool is a required flag.
To show vp-delete functionality lets consider a vesting pool with some vested tokens. Here is a vp-info for that pool:
1
pool_id:      2bba5b05949ea59c80aed3ac3474d7379d3be737e8eb5a968c52295e48333ead:vestingpool:ce8a294c1148d7a6a5b6745720bcade65ddae0a02261f59f89997050705771b4
2
balance:      2
3
can unlock:   1 (excess)
4
sent:         0 (real value)
5
pending:      1 (not sent, real value)
6
vested:       0.12 (virtual, time based value)
7
description:
8
start_time:   2021-05-18 23:01:01 +0000 UTC
9
expire_at:    2021-05-18 23:11:01 +0000 UTC
10
destinations:
11
  - id:          48965bc485e6d42c02c2d53548ad90b79cc9cb2b26f6cfd3331bb0e5f10c7a14
12
    vesting:     1
13
    can unlock:  0.12 (virtual, time based value)
14
    sent:        0 (real value)
15
    pending:     1 (not sent, real value)
16
    vested:      0.12 (virtual, time based value)
17
    last unlock: 2021-05-18 23:01:01 +0000 UTC
18
client_id:    48965bc485e6d42c02c2d53548ad90b79cc9cb2b26f6cfd3331bb0e5f10c7a14
19
​
Copied!
Lets delete the vesting pool by using .zwallet vp-delete command
1
./zwallet vp-delete --pool_id 2bba5b05949ea59c80aed3ac3474d7379d3be737e8eb5a968c52295e48333ead:vestingpool:ce8a294c1148d7a6a5b6745720bcade65ddae0a02261f59f89997050705771b4
Copied!
Response:
1
Vesting pool deleted successfully.
Copied!
To verify whether vesting pool is deleted run vp-infocommand and you will see this response
1
{"code":"resource_not_found","error":"resource_not_found: can't get pool: value not present"}
Copied!
Also, the deleted vesting pool will not be listed in vp-list output.
Staking on miners and sharders
Troubleshooting
Last modified 1mo ago
Copy link
Contents
Checking vesting pool config
Creating a vesting pool
Checking vesting pool list for a wallet
Checking vesting pool info
Triggering a vesting pool
Unlocking tokens of a vesting pool
Stopping vesting for a destination
Deleting a vesting pool