Storage API | Züs Weekly Debrief (January 12, 2022)

Hope everyone is having a great start to the year so far. This week, Sculptex looks into the role of Storage API in interacting with Züs’ network. In addition, we saw a shift in progress to a major UI overhaul on the backend with continued progress toward finalizing apps and explorer prior to launch. The blockchain team continues to conduct testing, yielding continued improvements in network stabilization resulting in successful load testing.

Sculptex’s Corner: Züs Storage API 

“Although I mostly use command line tools (CLI) to interact withZüs myself, an extremely important part of any internet-connected project is its Storage API (Application Programming Interface). Most APIs come in the form of REST API endpoints (REpresentational State Transfer). This just means the endpoints reply with the latest information at the point in time. Together with a list of commands (aka paths, queries, parameters) that respond with appropriate data requested.

The Züs Storage API documentation can be found at api.0chain.net. Our endpoints are effectively the nodes on our network, so Miners, Sharders, and Blobbers for example. But first, we need to obtain them!

0dns

0dns is a repo of a service layer that facilitates the up-to-date list of active Miners and Sharders. This will be particularly important when View Change is fully implemented. For each test network, a 0dns instance is installed at the location of: < {NetworkURL}/dns >
On our beta network, for example, a 0dns instance is at: beta.0chain.net/dns
And the path to get the current network is: {DNS}/network

So: beta.0chain.net/dns/network

However, for the mainnet, a number of 0dns instances will be installed on various independent servers and should be chosen at random from this list to avoid centralization. For apps, an up-to-date list will no doubt be built into each build. So the 0dns simply responds with a current list of active miners and sharders in standard JSON format. These are then extracted and random Sharders or Miners should be chosen as the endpoint as appropriate.

Consensus

Depending on the task, it may be required to send requests to multiple Miners or Sharders in order to gain consensus. The consensus threshold will be dependent on the BlockChain configuration plus the number of Miners/Sharders in the Active Set.

Simple API calls

Sharders store blocks, so an example Sharder API call might be:{SharderURL}/v1/block/get?block={{block}}

e.g. https://beta.0chain.net/sharder01/v1/block/get?block={{block}}

Test networks share this common format, but everything up to the /v1/ should basically refer to ANY random Sharder from the 0dns response, so could just as easily be:
https://myzcnsharder.net/sharder02/v1/block/get?block={{block}}

If https://myzcnsharder.net/sharder02 was an active sharder at the time.

There are many other API calls that Sharders are used for, one being a current list of active Blobbers: < {SharderURL}/v1/screst/:id/getblobbers >

The :id in this instance must be replaced with the smart contract address that provides this service, e.g. 6dba10422e368813802877a85039d3985d96760ed844092319743fb3a76712d7

In turn, you might wish to query some of the Blobbers via its Storage API such as: < {BlobberURL}/allocation?id={{allocation_txn_hash}} >

Which will return information about the specified allocation for that particular Blobber.

Advanced API Calls

For many Miner and Blobber API calls, the API call has to be authorized via a wallet. This relates to all wallet transactional calls to Miners and all storage-related activity to Blobbers. So these calls require the inclusion of additional POSTed data including authorization signatures (generated via the wallet keys) to verify that the call is being made by the wallet owner.

Here is an example of a faucet command, (albeit the faucet will of course be deprecated for mainnet!)

{{for_each_miner}}/v1/transaction/put

With the following POSTed data:

• Hash — A SHA3–256 hash of a colon delimited string of [creation_date, client_id, to_client_id, transaction_value and the SHA3–256 hash of transaction_data]
• Signature — A BLS signature of the Hash
• Client Id — Your wallet id
• Public Key — The hex string of the BLS public key
• Creation date — The current unix epoch timestamp
• To client Id — The Id of the smart contract you wish to execute the transaction data on
• Transaction data — The default faucet transaction data (e.g. “transaction_data”: “{\”name\”:\”pour\”,\”input\”:{},\”name\”:null}”)

The above is the equivalent of a zwallet CLI command;

zwallet faucet — methodName pour — input “”

I won’t go into further detail here, so check out the documentation for further examples, or see the runnable examples at the following link. As you can see, a fairly standard function such as creating a faucet or something more involved like creating an allocation might consist of dozens or even hundreds of API calls (including querying multiple Blobbers individually).

Summary

This is why I much prefer using CLI tools which handle most of this from a single function call!

However, having this understanding of what goes on under the hood gives an appreciation of the complex functionality that is required to power our platform. Also, the APIs can be used for direct integrations where a customer wants to implement a new feature of their own not available in the CLI or does not wish to use golang.”