Item state

Item state

Topic: base low level architecture concept

This is one of architecture concepts important to know during the software development for Universa integration. Among such topics are:

See UniversaBlockchain/universa/…/node/ItemState.java for more details.

Overview

Initial registration

Each attempt to register some contract(s) invokes the procedure of consensus lookup. During and after this procedure, checking the Universa for the status of this contract may report the contract is in various states. Check whether the resulting state returned by the node belongs to one of “Consensus found” or “Consensus not found”, to determine further actions.

Subsequent state checks

For any state checks, it is much safer if the check is executed on multiple nodes simultaneously than on a single one. Thus you get a “read consensus”, which should decide your further course of actions. E.g., multiple nodes simultaneously may return the “UNDEFINED” state to you, and it is actually a read consensus among the nodes; and receiving the UNDEFINED during the check may mean that the ledger has dropped this contract already after it being revoked long ago.

Available item states

Consensus found

Positive consensus

APPROVED – the primary “successful” state for the contract. The Universa network consensus about this contract is positive.
LOCKED – the consensus about the state is yet positive, but the contract is already locked during the preparation to archive it.

Negative consensus

DECLINED – the Universa network consensus about this contract is negative.
REVOKED – the Universa network consensus about this contract has been positive earlier, but now the contract has been explicitly revoked and the consensus is negative.

Consensus not found

UNDEFINED – the contract is unknown to the system and cannot be processed in its current form (e.g., its structure hasn’t been properly initialized yet). If receiving in on contract registration, you should try to reregister this contract on any other node. If receiving this (consensually) on contract check, this should be treated as “the nodes do not know this contract at all”; in particular, this could be caused by this contract revoked long ago, so even the revokation fact is not stored anymore.
PENDING – the contract is now inside the process of consensus search, but there is no yet any decision about the result, neither positive or negative.
- PENDING_POSITIVE – the contract is inside the process of consensus search; the node (where the query is executed) has checked this contract and finds it compatible against its ledger, but the consensus voting is still in progress.
- PENDING_NEGATIVE – the contract is inside the process of consensus search; the node (where the query is executed) has checked this contract and finds it bad, but the consensus voting is still in progress.
DISCARDED – for some (validation) reason, this contract should be discarded without any further processing.
LOCKED_FOR_CREATION – rather special state to mark the contract which some other item is going to create if it becomes approved.