Page: Node HTTP API
2019-11-21 11:11
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 contractsspent_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 contractorigin_id
is origin hashId of stored contractcontract_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 UrateCallback
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