1. Universa
  2. Software Developer Central
  3. Node HTTP API

Node HTTP API

This document describes the commands provided by each node with the authenticated command execution interface based on the http protocol. These are commands that are issued by clients and like components. Nodes normally do not execute commands on other nodes, there are UDP notifications that serve this purpose.

Missing part. The protocol description, sessions and so on.

Overview

Use this API for web based applications to work with the Universa.

API presents interface for work with prepared and ready contracts as packed binary. Contract should be packed as Parcel or as TransactionPack for specific types of contract. Answers is returned as Binder structure.

Registering contracts

Register contract via parcel

Most common way to register contract is register it via Parcel. Parcel is pair of your contract and U contract that will pay for processing. For register contract in the Universa via parcel use command 

approveParcel

with param packedItem with packed Parcel binary.

Command return Binder with key result. There are will be true if processing successfully started. Current processing state you can know via getParcelProcessingState command.

Register specific types of contracts without parcel

In some cases Universa allow you to register contracts without Parcel. Now you can do it for registering U contract. So, you can register described contracts via command 

approve

with param packedItem with packed TransactionPack binary.

Command return Binder with key itemResult. There are will be enum ItemResult with current processing result and state of the contract. Use getState command to check contract result and state later.

Check contracts states and its processing states

Check parcel processing state

After you launch parcel processing via approveParcel command, you can know its processing state. Do it using 

getParcelProcessingState

with param parcelId with hashId of the Parcel.

Command return Binder with key processingState. There are will be enum Node.ParcelProcessingState. States Node.ParcelProcessingState.FINISHED and Node.ParcelProcessingState.NOT_EXIST means Parcel is processed and removed from the Node. Use getState to know your contract state from now.

Check contract state

You can check contract state via command 

getState

with param itemId with hashId of the Contract you want to check.

Command return Binder with key itemResult. There are will be ItemResult type. ItemResult has field state with ItemState enum.

While processing and after contract has some states defined in the ItemState. This states means contract is being processing:

  • PENDING
  • PENDING_POSITIVE
  • PENDING_NEGATIVE

and this states means contract was processed:

  • APPROVED – all is ok, contract registered.
  • DECLINED – the contract can’t be accepted, for example, it has errors, wrong links, already processed.
  • REVOKED – the contract was recently revoked. This state is not kept for long, the network has short memory of discarded items.
  • UNDEFINED – the election failed for example due to severe network outage. You can try again soon.

Distributed store

The main goal is to provide secure distributed storage over the universa network.

Get the KD rate

Universa keep information in the pre-paid storage slots where both storage space and time are charged. The unit to measure data storage for some period of time is a storage unit, which allows store 1024 bytes of data for 24 hours, or, Kilo-Day, or KD.

storageGetRate

Returns the rate at the call moment, the cost of 1 KD in U. There is no guarantee the rate will not be changed in even near future.

Querying the slot info

querySlotInfo

with param slot_id with hashId of existing slot1 smart contract

Returns Binder, whose slot_state field contains slot state structure, like:

  • stored_bytes -> "2064"
  • prepaid_KD -> "100.0"
  • prepaid_from -> "1532301637"
  • paid_U -> "100"
  • spent_KD -> "0.0"
  • tracking_contract -> dictionary with info about stored contracts
  • spent_KD_time -> "1532301637"

Getting the stored contract

queryContract

with params slot_id+origin_id or slot_id+contract_id, where:

  • slot_id is hashId of existing slot1 smart contract
  • origin_id is origin hashId of stored contract
  • contract_id is hashId of certain stored contract

Returns Binder, whose contract field contains bytes of stored contract (for the origin_id the latest revision will be returned).

Names service

Provide the decentralized store for key and contract name records that allow identification of keys, addresses and contract origins.

Get the ND rate

The name storage works on the pre-paid basis. When UNS1 contract is first created, it must be accompanying with a initial payment in the paying parcel, chich should cover at least 360 name-days, or ND. As states from its name, 1ND provides 1 day of 1 name registration.

unsRate

Returns the rate at the call moment, the cost of 1 ND in U.

Querying the name info

queryNameRecord

with param string address or binary hashId origin, only one is allowed.

Returns Binder with structure, containing name record's info:

  • name
  • description
  • url

, or empty structure if nothing was found.

Getting the UNS1 contract copy

queryNameContract

with param name with registered name.

Returns Binder, whose packedContract field contains bytes of corresponding smart contract.

Follower contract service

The main goal is tracks contract registrations in any chain of contracts in the network for payment, when a new event occurs, send a request to the URL specified by the user, which contains the body of the new registered contract revision.

Get the OD rate and cost callback

The Follower contract works on the pre-paid basis.

When Follower contract is first created, it must be accompanying with a initial payment in the paying parcel, which should cover at least 100 origin-days, or cost 100 callbacks.

followerGetRate

Returns a Binder, containing the structure with the information, like:

  • rateOriginDays is the amount of OD at the call moment, that can be paid for 1 U
  • rateCallback is callback cost in U

Returns empty structure if nothing was found.

There is no guarantee the rate will not be changed in even near future.

Querying the follower contract info

In order to request information about the contract, use the command:

queryFollowerInfo

with param string address or binary hashId origin, only one is allowed.

Returns a Binder, which contains the follower state structure, like:

  • int paid_U -> "200"
  • double prepaid_OD -> "40.0"
  • long prepaid_from -> "1539690798"
  • int followed_origins-> "1"
  • double spent_OD-> "0.0"
  • long spent_OD_time-> "1539690798"
  • double callback_rate-> "10.0"
  • Binder callback_keys-> dictionary with info about following origins
  • Binder tracking_origins -> dictionary with callback URLs and callback keys

Service Commands