Viewing and Freezing with CAPE

Sun, June 26, 2022

By: Jeb Bearer

Hey everyone! Hopefully by now many of you have created some of your own assets using CAPE, and noticed that when creating an asset there is a place to configure viewing and freezing keys. We have claimed that these keys can be used to view otherwise-private transaction data, and to freeze assets of your asset type. However, neither of these functionalities are built into the GUI yet. Fear not! In this post I will show you how to view and freeze the assets you have created using a command line tool we’ve built. This will give you a feel for how it works as we work on incorporating this functionality into the GUI. If you’re feeling adventurous, follow along!

Disclaimer: this tutorial is aimed at more technical users. You should have some familiarity with using the terminal. You should also already be familiar with using the CAPE GUI.

Disclaimer: the CLI is an experimental tool that is not polished. We are showing you how to use it to demonstrate the viewing and freezing capability, but we will not be supporting it to the same extent as we support the GUI.

First, make sure you have the latest release of the wallet, which now includes the CLI tool as well as a few other improvements:

docker-compose down

docker-compose pull

docker-compose up

Next, you’ll need to create a viewable, freezable asset, if you haven’t already. You can do this using the GUI. Go to Account → Viewing Keys and click Generate new viewing key, then do the same for Freezing Keys. Next go to New CAPE Asset and choose A new ERC-20 based asset or A new CAPE domestic asset — viewing and freezing work the same for both. Configure the asset how you want, but be sure to configure viewing and freezing — check both Enable viewing of transaction amounts and Enable viewing of transaction addresses and enter the CAPE viewing key you created before, then check Enable freezing of asset transactions and enter the CAPE freezing key you created before. Then click Create new CAPE asset and confirm the transaction.

In order to really test viewing and freezing, you need someone else to own some of your asset. If you created an ERC-20 based asset, go to Wrap and wrap some into your wallet. If you created a domestic asset, your wallet should already have some after the mint. You can now go to Send and send some of your new asset to a buddy. If you need an address to send some of your test tokens to, feel free to send some our way: ADDR~VHH40oB82UI_QxhnsFAj7L1eDLs-n7vA69YaAGWqLhda

Once someone else has received some of your asset, it is time to show off the viewing and freezing interfaces in the CLI. First close the wallet GUI, to avoid any interference, and stop docker-compose if it is still running. Next, you need to figure out the directory where the GUI saved your keystore files, so run:

docker-compose run wallet-api ls /.espresso/keystores

It should output something like KEYSTORE~dGVzdEo. This is the name of your keystore file. Now we can run the wallet CLI using the same keystore file, using the keystore name from the previous step:

docker-compose run wallet-api /app/wallet-cli --storage /.espresso/keystores/KEYSTORE~whatever

Follow the prompts to log into your wallet using the password you created in the GUI. This will start the wallet CLI, which is an interactive read-eval-print loop. You can enter help to see a list of available commands. The ones we will be using are assets, asset, view, freeze, and unfreeze. Note that the descriptions of these commands from the help command currently contain some internal debugging information. We will be polishing up these descriptions in the future.

Exhibit: Logging into the CLI

We need a viewable and freezable asset to work with. Enter assets and look for one with vf next to it, which indicates viewable and freezable. You can get more information about an asset code using asset ASSET_CODE~whatever.

Exhibit: List assets

When you’ve found the asset code of the viewable and freezable asset that you created earlier, you can view it using view ASSET_CODE~whatever. This will print out a table of UTXOs of this asset type.

Exhibit: View assets

You should see at least one record corresponding to the assets you transferred to your buddy. This is significant! Normally, in CAPE, you cannot see other users’ asset records at all, but with the viewing key, you can!

Notice that one of the fields displayed for each record is FROZEN, which should be false for each record you are currently seeing. Since this asset is freezable, we can change that! Freezing is functionality that is already used by some of the most popular Ethereum assets, like stablecoins, so we wanted to enable it within CAPE as well. Find the record you sent to your buddy earlier, and note the owner address and amount. Then enter the command, replacing $OWNER with the address of the record owner and $AMOUNT with the amount of the record:

freeze ASSET_CODE~whatever $OWNER $AMOUNT 0

This will freeze $AMOUNT tokens of your asset belonging to $OWNER. The command should output a transaction receipt, like TXN~whatever. You can view the status of the freeze transaction by entering transaction TXN~whatever. It will be pending at first, but after a few minutes, it should be accepted.

Exhibit: Freezing Asset Records

Once the freeze transaction is accepted, you can once again view the asset with view ASSET_CODE~whatever. You should see a new record with the same amount and owner, but now FROZEN should be true. Have your buddy confirm that the spendable balance of your asset in their wallet is now zero. Their wallet should look something like this:

Exhibit: Frozen Assets in the GUI

We have frozen their assets! That wasn’t very nice, though, so let’s unfreeze the record and allow them to spend it again:

unfreeze ASSET_CODE~whatever $OWNER $AMOUNT 0

This command is exactly the same as the freeze command you typed earlier, but with unfreeze instead. Again, it outputs a transaction receipt, and you can wait until the transaction is accepted and then view the asset again. FROZEN should be changed back to true, and your buddy should once again have a positive balance of your asset in their wallet.

Exhibit: Unfreeze Asset Records

That’s it! I hereby turn you loose to view, freeze, and unfreeze to your heart’s content, but real quick, there are a couple of caveats you should know about. This is a very early version of this software, and we plan to relax these restrictions in the future.

• You can only view assets that are also freezable
• You can only view unspent records. The CLI does not currently track spent records, nor can you view which transaction created or consumed a given record.
• Freeze transactions do not give change. This means if you are viewing a record of amount 100, and you try to freeze 90, you will actually end up freezing the whole record of 100 tokens. Freezing always freezes at least as much as you request. Unfreezing works the same way, so if you unfreeze 90, the whole record of 100 will be unfrozen.