Universa Glossary

General network architecture

Universa Network

Universa Network is the worldwide network of Universa nodes, providing the functionality of distributed and decentralized registration and validation of smart contracts, and storing the validation data in decentralized manner with the means of Universa Blockchain technology.

In most cases, it is only the fact of validation (of some smart contract) which is stored by the network, not the data of the smart contract itself. The network is publicly available, with the “read” operations (to check if some smart contract is valid) being completely free, and the “write” operations (to register the fact of validity of some smart contract or its revision, or to revoke it) requires you to consume some amount of U – and U is kept in smart contracts too! –, which can be purchased for UTN tokens only (which are, again, smart-contract-stored).

You can check the actual status of Universa Network using the Universa Network Scanner.


Node is a single server in Universa Network, running a copy of Universa Node software (see its sources at GitHub:  UniversaBlockchain/universa/…/universa_node).

Each node stores the copy of Universa Blockchain data and synchronizes it with other nodes. Also, it is available for connection from clients, and can:

  • register the new smart contracts – or new revisions of the already registered smart contracts – validating them in process;
  • say whether a smart contract is currently approved by the Universa network, for a given smart contract (or Hash ID of the smart contract).

If you are interested in running your own node, please consult the Node Owner Central.

Crypto Cloud

Crypto Cloud is the web service developed by the Universa team; this web service is not a part of Universa network.

It is used by some systems and clients, including the Web Client, to store the Universa-specific data (in particular, smart contracts or private/public keys), with the end-user encryption – that is, all the data is encrypted and decrypted only on the side of the user, with the user-provided keys (making it impossible for third parties to access it without the private key of the user).

As it is capable of storing the smart contracts and keys, and used by the clients – it is one (but not the only possible) of client data storage implementations.

Glossary: UBot

UBot is a JavaScript-based executable code that runs on the decentralized cloud of UBot servers and is capable to add any Turing-complete dApp-style based logic, using the well-known JavaScript language and basically all its computational force and features (including access to the external oracles). If Universa smart contracts are the data (stored and validated by Universa), UBots are the code.

Contrary to the other blockchain/DLT services having various dApp-running features, the code in the UBots is not what makes the smart contracts smart (the role-permission based model and the references is). But it perfectly complements the existing smart contract features, making it possible, for example, to create/sign contracts in decentralized and automatic way.

Note the UBots are not intended to be executed on the same environment as the existing Nodes, therefore not impeding the performance of the Universa Mainnet.

For more details, see the UBots overview article.

Smart contracts

Smart Contract

In Universa, smart contract is a binary document with the expansible machine-readable structure, similar to the concepts of  Ricardian contract.

Contract lifecycle

For Universa smart contracts, the original author of any smart contract writes its initial version and registers it. Then, the other users of the smart contract, whoever owns it, can edit it somehow and register any new revisions of this smart contract (successfully registering any new revision will automatically and atomically revoke the previously approved revision).

The structure of initial version may (and typically does) impose multiple restrictions on how the contract could be edited in the future by its subsequent users. For example, such restrictions and limitations may specify how some particular field or data in the document may be edited, who could edit it, what values it may accept, what constraints should be satisfied by any document edit, etc. Creating such set of limitations and constraints is the goal of the contract author. These limitations imposed on the document are exactly what makes the contracts smart.

“Smartness” features of the smart contracts

Typically, each smart contract contains multiple sections:

  • definition – the section which contents is never changed between the revisions of the smart contract. It may contain any freeform data, but also some specially formed permissions/references; various limitations specified in this section will live throughout the whole life of the document; and they will be necessary for every future revision of the document.
  • state – the section which contents is usually changed between the revisions of the smart contract. It may contain any freeform data, but also, similarly to the definition section, may contain specially-formed requirements and permissions. Most typically, the definition section contains the rules how the data in the state section could be varied between revisions; though the logic may be more complex.
  • transactional – the section which keeps the “transient” data of the contract during any single transaction/edit only; the data in this section is not assumed to survive multiple subsequent edits of the document.

These sections may contain some other smart contract features, such as:

To learn further how to create the Smart Contracts in Universa, you may visit the Smart Contract Designer Central section of the KB.

Comparison to other approaches

This “structured document” approach (that the smart contract is a document rather than something else) reflects the viewpoint of most of the business world (which considers a contract is just some specific variant of document, and contract processing is just a subset of document flow).

Though it may contradict the vocabularies/traditions/customs of some other blockchain technologies, e.g. Ethereum, Hyperledger Fabric – which consider that smart contract is some application executed in a distributed environment, a “Dapp”.

In Universa, to create a smart contract, you “write a document”, not ”develop a distributed application”.


In Universa Smart Contracts, permissions are the rules specifying (1) who and (2) how can perform any operations on this document/contract.

Among them are:

  • ChangeOwnerPermission – to change the state.owner field of the contract to any new role;
  • ChangeRolePermission – to alter any (specified) role of the contract to any new role;
  • ModifyDataPermission – to edit some fields of the contract; and what fields specifically;
  • ChangeNumberPermission – to edit some numeric data in the contract; and how exactly (the limits of the numeric value, step, etc.);
  • SplitJoinPermission – how multiple (“compatible”) smart contracts can be combined together (joined) or separated to multiple other smart contracts, maintaining some total value in the process, and effectively adding fungibility to this smart contract, i.e. turning this smart contract into some kind of token;
  • RevokePermission – to revoke the contract explicitly.

For the whole set of supported permissions, see the source code:  UniversaBlockchain/universa/…/contract/permissions.


In Universa Smart Contracts, roles are a method to specify who exactly owns some permission.

Among them are:

  • SimpleRole – when the permission bearer is specified with just a single private key – actually, its matching public key or Key Address. Effectively means, “for success, the document should be signed by the specific private key having the Key Address AAAA”).
  • RoleLink – refers to some other role; often that is some predefined role like owner. Effectively means (in case of linking the state.owner role), “for success, the document should be signed by its current owner no matter who owns it at the moment”.
  • ListRole – refer to a list of multiple other roles, together with the “mode” of using them together:
    • Mode.ALL – for the role to be satisfied, all of the listed roles should be satisfied;
    • Mode.ANY – for the role to be satisfied, any of the listed roles (even just one) should be satisfied;
    • Mode.QUORUM – for the role to be satisfied, (at least) some specified number of the listed rolesshould be satisfied.

Other role types may appear later.

In practical usage, besides just the role basic definition, any role may even contain some extra references to check.

For the whole set of supported roles, see the source code:  UniversaBlockchain/universa/…/contract/roles.


In Universa Smart Contracts, references (sometimes called constraints) are a method to add extra custom verification logic to any roles.

One, and the original usage of that, is to refer to any roles in any other contracts, specified somehow (e.g. by the requirements on their fields). The syntax of the references, though, allows to add advanced logic rules (e.g. depending on the field values and how they correlate to each other).

Some examples of using the references (but their syntax is way wider than that):

  • The role in question must be taken from the attached contract, which must be in APPROVED state and have the specified Origin ID;
  • The role may be a regular SimpleRole (see roles for explanation), but is applicable only if the contract registration time is later than January 1, 2048;
  • The role may be a regular SimpleRole but is applicable only when some attached contract (in APPROVED state) has a data field enabled set to true.

For advanced details and references logic specification, see References article.


Normally in Universa methodology, a smart contract may be any general purpose document. But, if, among all the permissions, it has the properly defined SplitJoinPermission – it effectively becomes a “fungible asset”, and can be called a token.

Any token contract will have the following features (according to the definition of the SplitJoinPermission):

  • It has some numeric value, which can vary in a specified range (and with a specified minimal unit).
  • It can be split to multiple (otherwise compatible and alike) contracts, changing the owners of some contracts in process if needed; the total value of these contracts will be the same as of the original contract.
  • Multiple contracts (most likely, created previously by the split operations of the compatible contracts) can be joined into a single contract, if they are owned by the same owner; the total value of these joined contracts will be the same as of the result contract.

The split (1:M) and join (N:1) operations can actually perform simultaneously, joining multiple contracts (if owned by the same entity) and splitting them to new owners (N:M); the only requirements are similar: the contracts should have the compatible SplitJoin definition, and the total value “before” should be equal to the total value “after”.

The SplitJoinPermission defined in the contract, may be configured differently, making some token contracts split-joinable with some other compatible token contracts, but not with some other incompatible ones (e.g., “UTN tokens can be accumulated with other UTN tokens; GOLD tokens can be accumulated with other GOLD tokens; but UTN and GOLD tokens are incompatible with each other”). In layman terms, these compatible contracts comprise the contracts of some specific token.

The Universa clients which have the special-purpose features of working with tokens, are often called as having the wallet features.


U is an internal Universa measurement unit of energy required to execute some Universa transaction, i.e. to register some smart contracts/contract revisions.

The simplest and lightest transactions usually take just 1 U to be registered, more complex ones may require more. The details of calculation how much Us some transaction requires, are rather complex and low-level (you can find them at Quantization article in the Software Developer Central); but most of the times you just need to top-up your U balance (“reserve some U”) using UTN tokens.

Typically, the price of 1 U is around €0.01.

U smart contract:

  1. is not a token; not intended to be used for any payment means. It cannot even be combined with other U token, cannot be “sent out” – the only supported method of operation is spending (i.e. decreasing the amount), not sending.
  2. does not even supports changing the owner. The other reason why you cannot send it to someone and use it as a token, is that the owner of U smart contract is fixed at the moment of receiving the U contracts.
  3. is time-limited. At the time of writing the article (early 2019), the lifetime of any issued U contract is set to 1 year. After 1 year passed since issuing the contract, you should expect the contract becoming invalid and REVOKED/UNDEFINED.

See also:



Client of the Universa Network is, broadly speaking, any application (service, site, library, API) capable of connecting to Universa Network, create or edit the smart contracts somehow, register them in the network and validate as needed.

General-purpose official clients

There are several pre-made Universa clients (both applications/services, and programming APIs) providing wide spectre of features working with the smart contracts in general.

Some general-purpose Universa clients for end users (see also the End User Central for other important articles):

  • Web Client – a full-featured web application with friendly user interface, providing most features to work with the Universa smart contracts. Uses the Crypto Cloud as the Client Data Storage.
  • Uniclient – CLI (command-line interface) application for advanced users and software developers. For the Client Data Storage, uses the local filesystem of the computer where it is executed.

There are some APIs and software libraries to access the Universa network from your code, using various languages (Java/Scala, JavaScript, Ruby, Python, etc). For more details on Universa client APIs/libraries, see the Software Developer Central.

Third-party clients

Broadly speaking, if an application uses the Universa network somehow – it is a Universa client.

Functionality of such clients depend on how they are going to use the Universa Network. For example, some “crypto-kitties” style game may act as a Universa client, connecting to the Universa network; and, if each “cryptokitty” has its own smart contract, this game will update the smart contracts, register them, using some nifty and playable game interface. The client functionality will obviously be limited, though – supporting, most likely, just the smart contracts important for this game.

Another, more actual example: as MyDocuments.io service is using Universa to register each version of the document, it acts as the Universa client as well. It is not a general purpose client, either; it has no need to support other smart contracts besides those needed for the functionality of MyDocuments service.

Client Data Storage

Comparing to other blockchains (like Bitcoin/Ethereum), the specifics of Universa network and Universa Blockchain technology is that the Universa Blockchain normally does not store the data of the contracts in its distributed ledger. The Universa Blockchain works as a storage for contract validity only, but not for the content of the smart contract.

Thus, to work with the Universa contracts using some Universa client, it is not sufficient just to know the private key of the user, and get all the data of the user from the blockchain; the client should actually store the smart contracts (and private keys, if there are multiple of them) which are being worked with. Thus, each Universa client should have some Client Data Storage, which keeps track of all the involved and processed smart contracts.

There are multiple approaches of Client Data Storage, e.g.:

In Web Client

The Web Client stores the smart contracts using the end-user-encrypted Crypto Cloud. It also allows to export the contracts into downloadable .unicon files, and to import these .unicon files into the Crypto Cloud.

Storing the contracts in Crypto Cloud is extremely convenient and mostly transparent to the user. Using the Crypto-Cloud-enabled features like Chat, one may easily re-register the smart contract to another user and immediately send it to the new owner using. But please note that some other Univeras users are not necessarily using either the Web Client or Crypto Cloud, so for them to access the smart contracts, you may need to transfer them using different means, even fallback to sending them the .unicon files of the contracts.

In Uniclient

The Uniclient CLI tool may work with .unicon files directly, as well as have some basic means of storing the contracts on the filesystem. Please note Uniclient doesn’t support the Crypto Cloud storage.

In hardware Universa clients

For other blockchains, the “hardware wallet” (like Ledger Nano S, Trezor, etc) is typically just a secure device (in the flash drive formfactor) storing the private key and performing operations using it, but not allowing the private key itself to be copied out and stolen. Basically, each such a “hardware wallet” is just a “secure key storage”, while some apps running on the computer (where this device is connected) are working as the clients.

In Universa, it is really possible to implement a fully hardware client running all the operations on itself, and using Internet just to register the contracts, or check their state. Such a hardware client will even contain the embedded Client Data Storage, not requiring any external storages (even the Crypto Cloud) to keep the smart contracts being worked with.

In client APIs/libraries

The software developers using the client APIs are usually assumed to implement their own Client Data Storage for their own means. For some more specific details, the Software development: best practices could be consulted.


Wallet is a feature that can be provided by some Universa Clients, be those the usual end-user client applications/sites/services, or the software developer-oriented client APIs/libraries, for special-purpose working with the token smart contracts.

For a client (or API) to be considered having a properly implemented “wallet” feature, it should satisfy the following conditions:

  • It has the specific handling for the smart contracts having the SplitJoin permission, i.e. tokens.
    • It can aggregate the tokens to the groups upon the compatibility of their SplitJoin permission (i.e., grouping the by specific tokens). That is, “UTN tokens go together with UTN tokens, GOLD tokens go together with GOLD tokens”.
    • For the aggregated tokens, it keeps track which tokens are actually approved by the Universa Network, and filter only for currently approved ones.
    • The client may support a single or multiple private key of the user; the wallet feature must be able to filter only those tokens which are currently owned by any of the user private keys.
    • For each specific token, the wallet feature must be able to filter only approved and owned by user, and calculate their total sum. It will act as the total balance of this specific token in the wallet.
  • Its should be able to receive tokens: i.e, to receive/import the token contracts from external sources (i.e. if some other owner/client generates them), store them in the Client Data Storage, and aggregate them with the existing token contracts as explained above.
  • It should be able to send tokens: to perform SplitJoin operation on the stored token contracts, splitting out the desired sum (and joining the existing contracts if/when needed) to a new owner (and storing the remainder for the current owner); to register this operation in Universa Network; and to send/export the contracts for the new owner.

What “wallet” is not

  • “Wallet” is not some account in the network. You don’t “sign up” anywhere, you don’t create it in Universa Blockchain. All you create, is your private key, and you create it locally on your computer.
  • The existing general-purpose Universa Clients, such as the Web Client or Uniclient), are not wallets. They have much wider sets of features. Though, they may have “wallet” as one of their features.
  • Wallets do not have the addresses (though the private keys in these wallets do). In Universa, you cannot just send some contract “to some wallet address”. You have to 1. re-register the contract to the new owner address, 2. deliver the contract to the new owner (and their client, with their wallet feature) somehow. Some specific compatible clients maybe have shortcuts, though; e.g., using Web Client, you may easily send some contract to another user of Web Client.