Universa Web Client (v1.1.0, test)

User Manual


Table of Contents

Table of Contents

Introduction

First steps

Universa Web Client interface

Account authorization

Key pair dialog

Left navigation menu

Contracts

Contract templates

Contract editor

Signing and submission to Universa

Wallets

Keys

Account

Messenger

Use cases

A new token

Issue it

Account a new token on your balance

Chat with a friend

Send new tokens over chat

Tickets for a gig


Introduction

This Web Client for Universa network allows users to create, update, exchange, check and revoke the smart contracts.

To start working with the Universa Web Client, and for most operations with the Universa network, you need to know about the concept of key pairs, which is commonly used in cryptography and digital signatures.

A key pair is the set of two keys, the private key and the public key, which are matched together and let you perform such operations as document signing.

The public key is one key of the pair, that may be made publicly available – shared with any companions and parties. On the opposite, the private key is the key you must keep as secret as possible – stored in secure (and preferably encrypted) storage.

Your private key allows you to sign the documents and contracts; everybody who has your public key may verify the signature to confirm that the signature indeed belongs to you. Attention: if someone gains access to your private key, they may pretend as being yourself, sign the documents on your behalf, and perform any other operations as if they were you!

On the other hand, if you lose access to your private key, you won’t be able to confirm your ownership of any contracts or contract-defined assets you have, you will be unable to transfer them if they need it. So you must backup your private key and preferably all the important contracts you own, using some alternative methods: even the Universa personnel cannot access and restore them on your behalf.


First steps

When you open Universa Web Client for the first time, you see the main interface right away.

You may either create a new account (clicking the Authorize link) to enter the Messenger and be able to chat and send the contracts to other users, or start working with the smart contracts directly.

Authorization is not even required to work with the smart contracts! (Though when authorized, the contracts you’ve created will be stored in your crypto cloud storage).


Universa Web Client interface

Account authorization

When you click “Authorize” link, you’ll see the interface allowing you to login to an existing Messenger / Cloud account (using “Login” tab on the top), or register a new one (using “Register” tab near it).

The authorization dialog contains the key pair management dialog (see above) where you can create a new key pair or upload it; this key pair management dialog is available in many other places of the client. But when trying to login, additionally to the key pair creation or selection, you can also use yet another method of logging it: your own nick and some password. If you create your account here, you can configure the password later, in the “Account” section.

Key pair dialog

The key pair management interface looks the same across various places of the app where a key (key pair) is needed. The first time you may face it, is if you press Authorize link on the left menu panel to log in.

In this interface, you can either select a key from the dropdown list, create a new one, or upload it (if you already have the file with your private key available). Do not forget to type in the name before pressing Upload or one of the buttons used for generating the key pair. You can also download an existing key at any time by pressing the corresponding button. You will get the file with the .unikey extension, and you must keep it securely, as it represents your digital persona.

Left navigation menu

The left menu choices represent the main features of Universa Web Client: “Contracts”, “Wallets”, “Keys” and Messenger (you need to create an Account to use the messenger). The “Account” option appears as soon as you login using some key pair.

Contracts

The Contracts section is where all the contracts you are working with, are listed. On the first time you open the Web Client, you’ll have no contracts listed. You can create an empty contract by pressing “Create new” button in top right corner, or click the dashed line framed card in the middle of the page. You can also create a new contract from one of the available templates.

If you are not authorized in any account, the contracts you create will be stored in your browser local storage only; if you are authorized in an account, they will be stored in the crypto cloud.

Contract templates

The first template is called “New token contract”. It allows you to emit your own cryptocurrency, token, or a money-like asset.

As you click it, you’ll get a simplified contract creation form allowing you to fill your new asset name, short name (or code), minimal splittable unit (like cents for dollar which are equal to $0.01, or satoshis for Bitcoin which are equal to 0.00000001 BTC), and the total amount of units you want emit. The description is optional. Enter the values, hit save – and now you have a new contract in your list and some amount of whole new currency in your wallet. If you then open the contract again and go to contract full edit mode you’ll see what defines it as a new token contract:

  1. Data fields in definition describing currency name and code: unit full name, short name.
  2. The amount field in data section of contract state. This shows how many units this particular contract holds.
  3. The last but not the least – the permissions. Like with any currency, it is very important to be able to change money and give it to another person. That’s why you’ll need two permissions: split/join permission and change owner permission. The first one allows someone to chip some units into a separate contract; and the second one allows to transfer ownership of that contract to a person you want to “pay” to.

“New vote/ticket/share contract” is very similar to token contract. This is also an asset, but it is mostly intended to represent a pack of shares or stocks, where each single stock is the minimal unit. In real world, a single stock may also represent a right for a single vote in any shareholders voting. The only difference is that unlike the token unit, you can’t split a single share in two or more: 1 whole share is the minimal unit that can be chipped this pack of shares can be split to. Another real world entity that maps to this contract well, is the regular ticket to a gig: you cannot split a ticket, or get a 0.1 share of a ticket.

Besides adding or creating a contract, you can also upload any existing contract file. The extension of Universa Contract files is .unicon. To upload it, press the “Upload” button in the top right corner. The contract will automatically be verified in Universa network, so after that you may just press Back.

Note that the contracts created using the default contract templates are not “Pay to Bearer” contracts: the fact that you have a contract describing some amount of token of shares doesn’t mean that you own this amount of shares. To own them legally, you should have received this contract from a person who owned them legally too, and who signed the operation of transferring them from their account to yours, with their own signature (private key), and registered this transfer in Universa; this creates an implicit chain of signatures since the very first contract that issued the tokens/shares and gave them to the issuer, till the one which gave you the ownership rights for your part of tokens/shares. But for now, as a creator of the contract, you own what you’ve created, too.

Contract editor

Creating an empty contract causes the full-featured contract editor to appear, where you can see the contract structure. Editing the template-based contract will open the corresponding template-based-editor; however, it is still possible to open the full editor by pressing “Open full contract” in the top right corner.

In the full contract editor you can see the structure of the contract. It has 4 main sections: About, Signing, Definition and State.

The “About” section contains the general information about the contract, such as: name, revision number, timestamps and the available signatures.

“Sign this contract” section is where you can sign The the contract with the keys you have, by pressing “Add your signature”. As you can see on the figure, there is another version of “Key pair management” block. Nevertheless it has exactly the same functionality as the original one.

As you sign the contract, you can look at the “About” section to confirm your signature has been added.

The “Rename” section is a minor section where you may rename your contract. Just enter the new name and press “Save and close”.

The “Definition” section (on the left side of the screen) lets you to specify five aspects: issuer role, additional roles, period, permissions and data.
Issuer is a special predefined role mandatory in every contract (more on the roles below).
Period defines the validity period of a contract.

Additional roles are various custom roles defined by the user (more on the roles below). Permissions regulate what can be done with a contract and by whom. Every permission is defined for particular role (more on permissions below). Data is a tree with the nodes being simple names and leaves being name-value pairs. The value is one of the following: text, number, file, date.

The “State” section (on the right side of the screen) determines revision number, creation date of a contract, two special roles: owner and creator. “State” also contains additional roles and data in the same way as “Definition” does.

Contract roles are the ones permissions are defined for. Every role could be one of three types:

  1. The easiest to understand is the “Simple role”. The simple role is defined by just a public key(s). Universa considers you have this role if you have the corresponding private key(s).
  2. A Link to Role means just a link to another role. In this case having this role requires having the linked role as well.
  3. A Role List involves a list (or set) of other roles, and some condition on them, that must be satisfied. It may function in multiple modes:
  1. Any role from list – this role is considered present, if any role from the listed ones satisfy it. For example, for multiple family members you may specify that “Any role from the list” (of family members) has a right to use the shared apartments.
  2. All roles from list – this role is considered present, if all roles from the listed ones satisfy it. For example, for multiple family members you may specify that “All role from the list” (of family members) must sign the contract, to transfer
  3. At least N from list – this role is considered present, if at least N (specified as “Role quorum size”) members of the list satisfy it. For example, for 5 multiple family members you may specify that “At least N from list” (and set “Role quorum size” to 3) must sign the contract, to permit purchasing a new TV set; so it is sufficient for any 3 family members to agree on purchase, to make it done.

There are three predefined roles in every contract: issuer, creator and owner. Issuer must always be a Simple Role. The other two can be of any type.

Permissions allow Universa to specify how the changes made to newly submitted version of contract must be authorized (see “Signing and submission to Universa” below for detailed explanations). All permissions regulate changes made to state of a contract. The Definition of a contract can’t be changed.

There are five types of permissions:

  1. Revoke permission – the permission to revoke this contract. Universa will treat all revoked contracts as invalid. A person who has the permission to revoke the contract may revoke it any time; if a more complex role is specified for the Revoke permission (like, a Role list), that may mean a more complex condition or consensus should be reached to revoke a contract (e.g., imagine two parties signing a contract which they can break only on mutual agreement). Please always make sure that this permission is granted to at least some role! Otherwise it will be completely irrevocable, even by its sole owner.
  2. Change owner – the permission to modify the owner role. If the contract is related to the rights of ownership (or usage) of some entity, changing the owner basically means giving away the entity from the previous owner to the new one.
  3. Change number – the permission to modify some explicitly specified (in permission) numeric data field (limitations on range of changes can be specified as well).
  4. Split (join) – the permission that enables the contract to act as, or represent, a token, cryptocurrency, or otherwise measurable and quantized entity. When a contract has this field, it contains a set of other fields, the primary of which is Amount. At any time (unless some other restrictions are present in the contract) such contract may be split to a set of other contracts (imagine you splitting a pile of coins or between multiple parties), having the sum of the “amount” values precisely equal to the value in Amount field of original contract. Symmetrically, multiple contracts may be joined together (imagine you merge several such coin piles together into a larger pile).
  5. Modify data – modify some explicitly specified (in permission) data fields.

After having completed editing the contract, you may go just go back to the list from the contract editor. Any unsaved changes in this case will be saved in the draft copy of your contract (if the status of your contract is DRAFT, the changes will be saved in the contract itself). But using the save button you may explicitly fix the contract state in two different ways: “Save” – “As new version” and “Save and register”.

Saving “As new version” only makes sense for contracts that were previously submitted to Universa already. A new revision of the contract will be made for such a contract, and it will be stored locally, but not registered in the Universa blockchain. For contracts in DRAFT status this operation is similar to just pressing a “back” button.

On the contrary, “Save and register” operation is valid for contracts in DRAFT status only, and performs the most important operation: registering the contract on decentralized Universa blockchain.

Signing and submission to Universa

When the contract is submitted to Universa, Universa calculates a difference of the new revision with the previous revision. It then builds a list of roles required to made those changes. Finally it checks if the list of signatures (that contract was signed with) corresponds to the list of required roles. Decision is then made to accept of refuse this revision of a contract.

After creating a new contract you’ll see it in the list of available contracts. For every contract, the list shows the following information: its name, status (DRAFT / PENDING / APPROVED / DECLINED / UNDEFINED), revision, last edited, and roles who have signed it already. In this list, you can also delete or download the contract.

“DRAFT” status is the status of the contract which is stored only locally (in the internal storage of your browser). If you try to use another computer or the browser, even if you log in to the account (messenger) using the same private key, these contracts won’t be available unless you import them from the file.

“PENDING” is the status of the contract that is submitted to the Universa network and being verified at the moment.

“APPROVED” is the status of the contract that has been registered at the Universa network successfully.
“DECLINED” is the status of the contract that could not be registered at the Universa network; probably it has some internal errors.

“UNDEFINED” is the status of the contract for which the Universa network cannot confirm its validity. Maybe it is non-actual, or it has been revoked, or never has been registered in the Unviersa network.

If, at some point, you consider the status of the contract can have been changed externally (on another computer, or by some user who has the permissions to alter or revoke your contract), you can click the status of the contract. It will contact the Universa network and re-validate it.

You can also click the title of every contract (or for non-token/shares contract – the dedicated “Edit” button) to enter the editor of this contract. Also, for contracts that carry a splittable amount (such as, the contracts created using the Token or Shares templates), the “Pay” button is also available, that provides the more convenient interface of “paying” (or giving out) the part of that amount. The more advanced interface for such splittable contracts is available through the “Wallets” interface section.

Wallets

The “Wallets” section contains the information about all of your “token” or “shares” contracts aggregated by the appropriate contract. It shows the unit code (short name) of the “currency” asset, the name, the amount (balance) you own, and allows you to send out some amount of them.

In order to be aggregated in the wallet, the contract must be validated by Universa, and you should have the owner role of this contract (i.e. you should own this amount of asset). Owning some asset normally means being able to send some amount of it to another person.

Multiple (valid) contracts of the same asert will cause its balance to be the total value of these contracts. If you have the contracts, but Universa treats them as invalid/non-actual/“UNDEFINED”, their balance will not be included in the total balance.

The contracts will be considered as the contracts of the same “currency” / “token” / asset, if and only if originally, before any process of splitting and joining the contracts, they were originated from the same initial contract. Creating a second token contract, even having the same properties as the original contract (name, symbol / short code, minimal units, description, etc) will normally still make it a different asset type. For example, if one user issues a token contract with the “Crypto Gold” and “GLD” symbol, being splittable to as little as 0.01, and with the initial balance of 1 000 000, and starts using it as a token or a virtual currency; and then another user (or even the original one) issues a whole new contract, even though having the same “Crypto Gold” name and “GLD” symbol, being similarly splittable to 0.01, and even with the same initial (but new) balance of 1 000 000; this will be a completely new issued currency, rather than an extra portion of the original currency; and these two currencies will be incompatible in the wallets and balance, and in any contracts involving them, even though their human-visible representation looks similar. You cannot forge the already existing currency, token or ticket! (unless they were created with special features that permit re-issuing of the extra amounts).

When you have a non-empty balance of some token/crypto-currency, you can send it to some person. After pressing the “Send” button in the wallet, you see the simplified contract editor form, where you just specify an amount of asset to be sent out (i.e. how much you are sending), and the public key of a new owner of this amount (i.e., who are you going to send it to). After saving this contract, two new contracts will be created, one for the amount to be sent out, and one for the change that gets returned to you (later you can find them by clicking the “transactions” button).

On the screenshot above, we’ve decided to send out 500 MOT tokens to the “receiver” in our chat, and such sending operation has split our initial contract (for 1 000 000 MOT) into the “outgoing” contract that was sent out, and the remainder / change. Note you can “pay” again from the remainder contract, but for the contract that went out you cannot even edit it anymore, as it has changed its owner. You can open and close the “wallets” (to see their comprising transactions) by clicking them.

Note that when you send out the asset, you can either upload the public keys of the recipients, or use the keys which you’ve received from the people you participating in chats with (See the “Messenger” section).

It is highly recommended that you also keep a copy of the contract files / remainders locally, by downloading them (press the “...” button, there is the “Download” option in the menu). The Universa itself doesn’t store the contracts, only their validity. Though when you are authorized and logged in, the contracts you’ve created are stored in your crypto cloud account.

Another way how to store them, is to use the chat / “Messenger” feature: when sending the contracts through the chat, they are stored in the crypto cloud in a form that only the ones participating in the chat have access to. Later, when you log into the chat from another computer, you’ll have access to all of the contracts received through the chat history.

Keys

The “Keys” section allows you to create yet another key pair or key pairs (through the key pair dialog similar to one in may other places), and manage the available keys and key pairs.

When using the Universa Web Client, no key pairs are stored or transferred to the server side – they are always stored in the local store of your browser. Running a session in the anonymous mode of the browser makes all the key pairs (including the just-generated ones) disappear from the memory and storage as soon as you close the window with the anonymous mode. If you want to use some key pair to sign the contracts or login to the system (account) in the future, you must download it and store in the safe place to protect from disappearing. This is not necessary though for the contacts you’ve made through the Messenger, as the public keys for your Messenger contacts are always downloaded as soon as you log into the Messenger.

Account

The built-in Messenger allows you to establish conversations with other parties, and exchange contracts. It also makes it easier to assign contract roles to others as you receive their public keys upon establishing conversation (this includes sending tokens to each other). You can get to the messenger by pressing “Authorize” button on the left panel. A key pair is used for authorization, with the key pair management interface already known from the other sections (which, in particular, allows you to create a brand new key pair, upload it from the disk, or use one of the key pairs stored in the browser).

On your first visit you’ll be asked for a nickname to register. Once nickname is registered you can make it searchable or not. The only way to establish communication in Universa messenger is finding other party by one of its searchable nickname (so if you don’t have any searchable nicknames no people could reach you).

Note that to find someone, it must be an exact match of the nickname: the cryptographic methods used lead to the nickname itself not being stored on the servers in its cleartext form, but only in its hashed representation. So the server side does not know the stored nicks; but if the user looks up some and provides a fully matching nick of the party, it will be found.

In the Account section, you can add, remove nicknames or toggle their searchability at any time. Also, you may unregister a nickname, making it available for registering by other parties. If you provide some information about yourself (like, your first name and last name), you can make it available to any of your contacts, so that they won’t see you as an “anonymous” user. This information is stored in the encrypted cloud, so that you get access to it as soon as you log into your account; but noone, even the Universa personnel, can neither read nor update your information.

If you configure a password (entering it twice, to be sure you haven’t made a mistype), you can use it, together with one of your nicks, to log into the account.

Messenger

The messenger conversations are listed on the Dialogs section of the left panel.

These look like an ordinary messenger windows except of the one thing: you have the list of the contracts available to you on the right, and at any moment, you can send any contract to the chat, and you can also download the contract (to store it locally in a safe place).

All contracts your receive through the chats are displayed in your contract list having its original name paired with the name of the sender. The contracts you own can be edited (just press the “Edit button” to enter the regular contract editor); and the splittable/joinable contracts (representing a token, pack of shares, or some similar asset) use the “Pay” button that opens the regular “Send units” form. If there are multiple contracts of the same kind, they are merged under a common “wallet” that can be opened and closed by the click.


Use cases

Please note that during all these operations, the data you create is either stored only in your browser, available to you (and probably to other people using this browser); or it is stored and sent through the chat and made available to the people you’ve decided to share it with, explicitly. The private keys never sent to the third parties, and are stored only on your browser, and used for signatures and encryption. The contracts are also not sent out automatically, unless you decide to send them through the chat (in this case, they are made available only to the parties participating in the chat), or submit it to Universa for registration (at this moment, they are sent out to the Universa nodes).

On the other hand, please make sure that no other third parties can access your computer in the meantime, as they may get access to the local storage of your browser.

For extra security, it is preferred that you use it in the “Anonymous mode” of your browser, so when you leave it, all the data is erased from the local storage. Note that even the contracts you’ve created, but have not backed up, may disappear in this case!

A new token

Issue it

Imagine you want to issue a whole new token. Let’s call it My Own Token.

Open the “Contracts” section, and click on the “New tokencontract” template.

You see the form of creating a new token contract. Fill it the values like displayed. “MOT” will be the ticker code, like the ones used in the real world: “USD”, “EUR”, etc. You may even decide to use something like “token cents”, so the minimal unit will be 0.01 (but it may go as low as 0.000000001).

When you are ready, press “Save” button, and choose “Save and register”. In the real Universa network (Mainnet), it would be a paid operation to register it in the primary blockchain; in the Testnet, it runs for free, but no guarantees are given that the blockchain will keep its status forever (quite opposite, the Testnet may be wiped at any moment, so it should be used for development purposes only, never for any real production load).

Account a new token on your balance

After you’ve created the new token, you can look at your contracts, and find it there (click the wallet to open, if you want to watch the contracts it consists of).

You can also find them in your wallet, together with any other splittable / payable assets.

Chat with a friend

Make sure you are authorized for the chat / Messenger. Click the “Authorize” button in the left menu, if you are not.

If you have a private key file already, you can upload it on the “Login” dialog. But if you are using it for the first time, click “Register”, enter your nick, make sure the “Anyone can find me by this nick” checkbox is checked; enter the name of the private key to be generated, and finally press either “2048” or “4096” to decide how large should be the private key. 2048 bit RSA keys are considered safe by the security experts; but for the ones who want the maximum security, the 4096 bits long RSA keys can be generated too.

Make sure to save this private key and store it in the safe place, so it won’t get lost after you close the browser and wipe its history!

After you’ve created your account, you can start a new chat, clicking the button with the square and the pencil on it.

Enter the nickname of your friend (assuming you know it already). If you’ve found them, you’ll see them in the list; there are also other recipients in the list you had a chat before. Click on your friend to designate you want them in the chat, and the press the “Create” button to create a chat with them.

You’ll see a new chat window, where you can basically chat with your friend and negotiate any details.

Send new tokens over chat

Imagine now you want to send some amount of your newly created tokens to your friend.

In the chat window, on the right side, you see your contracts available. The wallet with your new token is there too. Clicking the wallet, you can open it; and if you press the “Pay” button, you may send some of your token to your friend:

After you’ve entered how much you want to send, press the “Save” button in the top right corner, and choose “Save, register and send to recipient”.

It will immediately split the contract into two contracts,

register both in Universa blockchain, and also send the 500 MOT you’ve decided to your friend.

Please note that now the contracts list on the right side of the chat shows you the “remainder” contract, and the part that you’ve sent out.

And if you visit you “Wallets” section, it now displays only the remaining balance of your token.

Tickets for a gig

Imagine you own or manage a venue that is holding a gig; you want to issue the tickets for a gig and use Universa for that.

Similarly to creating a new token, you the “New vote/ticket/share contract” on the contract template page:

The form you see after that is rather similar to the form for token creation, just a slightly different.

In this form, you specify the initial settings for your gig. But, instead of doing “Save”, then “Save and register” (that submits this contract to Universa), you can “Save” / “As draft” instead; and them, from the contracts list, you can can click on your contract to start edit it, and then click “Open full contract” to configure full settings of your contract.

There are many options that define your contract, and you are free to configure them as much as you need. You can add the extra roles to it (for example, the role of someone like a “Door security” who can revoke your contract). While initially the vote / share role seems similar to the “token” role, you may alter the logic of it significantly using the full contract editor, and, for example, you can prohibit for the people to change the owner of the contract after they receive it, i.e. make the tickets non-transferable. Try using the editor creatively, and share your ideas with the Universa community!