Inside a Universa Smart Contract

In the past weeks you could have read the introductory articles about some internal architecture of the Universa Blockchain and the revisions of smart contracts. As you know now, transactions are not added to linear blocks to a chain, but each transaction is a revision of a smart contract in a swarm of Directed Acyclic Graphs. 

But what is a smart contract actually, and how does its architecture look like?

Inside a Smart Contract

First of all, the terminology ‘smart contract’ is widely used but also not applied in the right way. It sounds like it’s about a complex contract which is executed within the blockchain in a smart way.

In the Universa Blockchain each transaction is a (new) smart contract. And it may be a contract, but it could also be a document, digital process or agreement. We can call all these operations ‘smart documents’, ‘smart processes’ or whatever you like.

If we take a closer look at a smart contract in the Universa Blockchain, we can see that it has three sections:

  1. Definition
  2. State
  3. Transactional


The first part of the structure contains data that must be invariant in any revision of this contract. If a transaction is executed, this data must be immutable. Changing it is not possible. 

If the data is changed,the Universa nodes prohibit the registration of the transaction. After all, the nodes compare this data of the new revision with the previous one.


The state contains data that can be altered in the revision of this contract. The particular details of what and how it may be altered, can be specified inside definition.permissions. Parameters which are set into the definition or the state are things like ‘creator’, ‘issuer’ or ‘owner’.


The third part of the structure contains data that will not (necessarily) be kept in the contract, but is bound just to the specific transaction. For example: If you pay a merchant you can put a record about the payment reason/invoice code into the transactional data.

These are the three sections within a smart contract which contain all the data regarding a specific transaction. We call all of this ‘just data’, but what can this data be about?

Universa Token contract 

Let’s take the Universa Token (UTN) origin contract as an example. You can check it yourself at the universaexplorer. It shows general data/information about the roles and the owner. 

You can also read the definition data (which should remain unchanged during the revisions). No matter which revision of the contract you owe, you will always see this data attached to it:

The second section is the state data, which shows the amount of the supply of the UTN. This might be confusing, since you would expect the supply to be fixed or immutable. 

However, a transaction (or revision of this root contract) of a token, uses the split-join functions. This is one of the use cases of a smart contract. Split-join operation on a contract is mainly used for coin-contracts. 

Simply put, the root contract of the UTN token consists of the amount of 4 997 891 952 tokens.

Due to the dynamically flexible amounts of the UTN-UTNP swaps, Universa does not have the exact details of the balances and amounts of UTNP in circulation. This can be tracked however, but such a tool is not built yet.

If from this contract a payment is executed, this amount will be split to let’s say 1 997 891 952 and 3 000 000 000. This is possible because this amount is in the state data of the contract (hence it can be adjusted). 

By now, we have two contracts (revisions) of the same root contract, both having (or: being) their own amount of tokens. For each payment or transaction with this token, the amount will be split, sent and thereafter merged (or joined) at the side of the recipient. You can read more about this case at KB.

By the way, the Origin ID (the ID of the root contract for a token) is the most important in the ideology for fixed-supply tokens. 

As you may know, in the world of blockchain the terms mutable and immutable are very important. Think about the maximal supply, the owner and the issuer of a contract. With both sections definition and state this can be guaranteed for each particular use case.

Permissions and Roles

There are also methods to specify who exactly owns permissions of a contract. This can be a SimpleRole (specified with just a single private key), a RoleLink (referring to another role, like ‘owner’) or ListRole (which refers to a list of multiple other roles).

That’s actually very interesting. Because it’s possible to make a role like “a list of 5 people, and ALL of them must sign the document”. Or make make a role like “List of 6 people and ANY of them must sign the document. It’s even possible to create a 15-out-of-16 construction. This adds extra security to operations for e.g. cold storage possibilities or multi party decision making.

In practical usage, besides just the role basic definition, any role may even contain some extra references to check and to add extra custom verification logic. These references can be defined in either the definition, state or transactional. It may be a reference to a name, transactional_id, fields or signed_by.

There are many ways to specify the data, roles and permissions of a smart contract/document. Once it’s registered, the smart contract can be used/verified/executed and it gets revised for each transaction. This results in different Item States for each revision that will be added to the DAG.

Item State

Let’s go back to the UTN contract as an example. The status of the item is UNDEFINED. 

Important: this is because the split-join function is operated and not because the UTN token does ‘not work or exist anymore’.

There are several state for the smart contracts, based on the consensus of the network.

  1. APPROVED, the primary ’successful’ state for the contract
  2. LOCKED, the consensus about the state is yet positive, but the contract is already locked during the preparation to archive it.

It’s also possible that there’s a negative consensus amongst the nodes:


At last, there are four options for smart contracts (or transactions) in which the consensus is not found:

  1. UNDEFINED, because it’s for example already revoked long ago.

You can read more about these statuses at the Knowledge Based site. In the next article we’ll dive further into the use cases of these smart documents. Stay tuned.

Help translating this post to German French Dutch Italian Spanish Croatian Russian. Contact @starnold to participate!

Related posts

Identity of Universa (and Ricardian) Smart Contracts


Asymmetric cryptography in the Universa Blockchain


What makes the Universa Blockchain so secure? HashID


Leave a Comment