Returning Grants

A Gentle Guide to Returning Grants

You have decided to return a clawback vesting grant that you have received back to its funder. This is a step-by-step guide to doing so.

As a prerequisite, you must know your account address and have access to your key. These instructions assume that you use a Ledger device to hold your key.

Building agd

If you do not obtain a precompiled agd binary, you'll have to create one. Follow the Getting Started instructions to install the SDK on your local machine. One extra step is required once you've cloned the repository - you must switch to the latest release instead of the master development branch:

git switch agoric-upgrade-13

Alternative build instructions once you've cloned the repository:

cd agoric-sdk
./bin/agd build

Ensure that agd is in your execution path by creating a link to agoric-sdk/bin/agd from some directory in your path.

Special note for MacOS

There is a bugfix (#8462) for a ledger-MacOS issues that is not yet merged. For MacOS, before you build, apply the following change:

diff --git a/golang/cosmos/go.mod b/golang/cosmos/go.mod
index f3b06910e..30c53e90a 100644
--- a/golang/cosmos/go.mod
+++ b/golang/cosmos/go.mod
@@ -143,7 +143,8 @@ require (
 
 // At least until post-v0.9.0 is released with
 // https://github.com/Zondax/hid/issues/4 resolved.
-replace github.com/zondax/hid => github.com/zondax/hid v0.9.1-0.20220302062450-5552068d2266
+// replace github.com/zondax/hid => github.com/zondax/hid v0.9.1-0.20220302062450-5552068d2266
+replace github.com/zondax/hid => github.com/zondax/hid v0.9.2
 
 replace github.com/99designs/keyring => github.com/cosmos/keyring v1.2.0

then run

(cd golang/cosmos && go mod tidy)

and then build agd.

Configure your client

You'll need to configure a local client in order to use your Ledger device to sign transactions. First, establish a new empty directory somewhere and change your shell into it.

mkdir ~/myreturn
cd ~/myreturn

Now we'll set some configuration parameters so we don't have to re-type them all the time (and risk forgetting or mistyping them).

agd --home . config keyring-backend os
agd --home . config chain-id agoric-3
agd --home . config node https://main.rpc.agoric.net:443
agd --home . config broadcast-mode block

You can set the keyring to use a different backend depending on your needs and platform.

WARNING WARNING WARNING You will NOT need to use your Ledger mnemonic seed phrase for these instructions. Never type your mnemonic into anything other than a Ledger device that you want to initialize.

Now attach your Ledger device. Exit any other applications which might be trying to talk to the device (e.g. Ledger Live). Then start the Cosmos app on the device. Now we can add a reference to your ledger-stored account into the local keychain:

agd --home . keys add myAgoric0 --ledger --coin-type 118
agd --home . keys show myAgoric0

(The first command will block until you manually approve the request on the ledger.)

The output of the last command should show the correct address of If you have multiple accounts associated with your Ledger and wish to use a non-default one, you can add as many entries as you need:

agd --home . keys add myAgoric1 --ledger --coin-type 118 --account 1
agd --home . keys add myAgoric2 --ledger --coin-type 118 --account 2

We'll set a shell variable to the account you want to use, so you can cut and paste the subsequent instructions. Substitute the key you want to use for myAgoric0 here.

me=myAgoric0
myaddr=$(agd --home . keys show $me -a)
echo $myaddr

IMPORTANT Confirm that the address is the one with the grant that you want to return. Otherwise redefine me and re-run the last two instructions until it is right.

Run a test transaction and record your pre-return account details

Take a look at your account details, bank balance, and staking state to ensure that they match what you see in your Keplr wallet:

agd --home . query auth account $myaddr
agd --home . query bank balances $myaddr
agd --home . query staking delegations $myaddr
agd --home . query staking unbonding-delegations $myaddr

Save the output to a file so we can confirm that the return-grants command worked correctly. Your account type should be ClawbackVestingAccount. If it is not, you're looking at the wrong address.

Now run a test transaction (not a query) to ensure that everything is working. A good test is to collect staking rewards, which you'll want to do anyhow. You can also transfer some tokens to a friend, or any other transaction you know how to run.

agd --home . tx distribution withdraw-all-rewards --from $me
agd --home . query auth account $myaddr
agd --home . query bank balances $myaddr
agd --home . query staking delegations $myaddr
agd --home . query staking unbonding-delegations $myaddr

Again, record the output for debugging, especially the transaction ID.

Run return-grants

Now is the moment of truth. The return-grants command will try to return the tokens listed in the OriginalVesting field of the query auth account output. This is your original grant, and subsequent grants merged into the same account, plus staking rewards withdrawn from unvested staked tokens.

The command will first try to return as much as it can from your bank balance. If it needs more, it will then transfer any unbonding delegations. If it needs still more, it will transfer delegations, in whole or in part, until the OriginalVesting amount has been transferred. Note that this might leave the account with no liquid tokens for paying fees. You might want to make sure you have a handful of tokens in another another account that you can send to the depleted account so that it can perform further transactions. In a pinch, you can buy a few with Kado.

Note that if you have been slashed, or if you have transferred any vested tokens out of the account, or if you've paid fees in excess of your rewards, the account might not have the desired number of tokens to return. In this case, the account will be left fully depleted and the obligation of returning the grant might not be fulfilled. Please contact management to discuss the situation.

So with all of the preceding looking good and recorded to a file, run the following:

agd --home . tx vesting return-grants --from $me --gas auto

and record the result in a file, especially the transaction ID. The --gas auto flag ensures that enough gas is provided for this expensive operation.

Lastly, check your account state again:

agd --home . query auth account $myaddr
agd --home . query bank balances $myaddr
agd --home . query staking delegations $myaddr
agd --home . query staking unbonding-delegations $myaddr