Uniclient: UUTN Wallets

Overview

UUTN Wallets is the feature of uniclient that automates handling and maintenance of contract registration payments and fees:

1. It lets you avoid messing with multiple key files if all you want is some basic private key for every operation, and some U files you purchased for it (what should be sufficient for most of the use cases except probably most obscure ones).
2. It simplifies handling your U files (which store the U reserves to be used for fees), which are registered to your primary private key.
3. When you U reserves are low, it even automatically top-up the U reserve using some UTN contracts you own.

Each UUTN wallet is a place where your default private key is stored (so it will sign your contracts by default); your default U reserve is stored; and even your UTN contracts (that can be used to top-up your U reserve) are stored.

Usage scenarios

Initialization

User creates the default UUTN wallet and puts his U contract into it, together with the key required to sign U contract.

uniclient --put-into-wallet --keys mykey.private.unikey my_u_contract.unicon

This will create the default wallet at ~/.universa/uutnwallet, that holds some U and the key required.

Using the wallet

User can now register contracts without even thinking about payments. Uniclient will handle all the payments using the default wallet.

uniclient --register contract.unicon

The example output is below:

Looking for U contract in UUTN wallet.
Loaded wallet '~/.universa/uutnwallet' Balance is: U 919 UTN 0
U contract is found in UUTN wallet: /Users/romanu/.universa/uutnwallet/u_contract.unicon
...
registration
...

As you can see, the U contract is automatically found and used to provide the payment for registration.

Topping-up the U balance

After the user has registered some contracts, the U balance may reach 0; the UUTN feature makes it possible to top-up the U balance easily.

Manual U purchase

The user can now manually purchase more U, receive the smart contract containing Us, and add this contract to the existing wallet.

uniclient --put-into-wallet my_other_u_contract.unicon

OR

uniclient --put-into-wallet my_other_u_contract.unicon --keys my_other_key.private.unikey

... in case if the key has been changed.

Semi-automatic U purchase

Using the --u-rate command, the user can get the current U price in UTNs (or actually, how many Us are given for a single UTN).

uniclient --u-rate

Then, using the --u-for-utn command, the user may reserve the required amount of U for UTN; they should pass --amount option to specify how many U needed to reserve.

uniclient --u-for-utn --amount 5

… to reserve 5 U, using the UTN contract stored in the UUTN wallet.

Auto-top-up using the UTN contract

The user can automate the payments even further, by adding the UTN contract together with its key to the wallet.

uniclient --put-into-wallet 100UTN.unicon  # (specify key if necessary)

UUTN wallets have the “auto purchase U” feature. In configuration file (YAML-formatted) stored in /path/to/wallet/*config*, there is a section called auto_payment.

auto_payment:
  min_balance: 50
  amount: 100

By default, the minimum balance (when auto purchase should happen) is 50 U, and the amount being bought is 100 U.

After the user has added an UTN contract to the wallet, the next time they try to register some contract, an auto purchase will happen. It is displayed like this:

Looking for U contract in UUTN wallet.
Loaded wallet '~/.universa/uutnwallet' Balance is: U 34 UTN 3.97
U balance is less than threshold of 50. Trying to buy more Us
U purchase transaction is saved to : ~/.universa/uutnwallet/u_purchase_1531229737.unicon
Purchase in progress...
Purchase in progress...
Auto purchase completed. New U contract is: ~/.universa/uutnwallet/U_100_1.unicon
U contract is  found in UUTN wallet: ~/.universa/uutnwallet/U_100.unicon
...
registration
...

With the new feature of UUTN wallets, the user can almost completely forget about handling payments manually. The only thing required is putting some UTN contracts to the wallet occasionally.

Multiple wallets

It is possible to create more than just a default single wallet. This is performed by specifying some custom wallet path:

uniclient --put-into-wallet ~/uutnwallets/wallet1 --keys mykey.private.unikey my_u_contract.unicon

… and then upon registration you use it like this:

uniclient --register contract.unicon --wallet ~/uutnwallets/wallet1 

Errors handling

Another good thing about UUTN wallet is that it handles various errors from adding contract, without requiring a key to restore from network errors automatically.

The only errors Uniclient could not recover from are:

• disk errors;
• the contracts has been used manually, outside of regular wallet procedures;
• the configuration file is inconsistent and broken.