Getting Started with OCAP Playground

Author： Shijun （FE of ArcBlock Engineering Team）

If you have a basic understanding of blockchain technology, or even developed a simple blockchain application yourself, I am wondering if you have been confused by different interfaces and data formats of various chains. The biggest obstacle for massive blockchain application development is the requirement of running a full node for each blockchain to read or write data on the blockchain, even for the experienced developers, it takes a lot of time to do these "dirty work".

As a developer, you must be wondering, Is there a more developer-friendly and traditional application like way to develop blockchain apps? Engineers at ArcBlock have long pondered this issue, and after several months of development, ArcBlock will officially announce a solution that supports multi-chain data access: Open Chain Access Protocol (often referred as OCAP).

If you are interested in OCAP service or want to develop blockchain applications in a more familiar way, I strongly suggest that you take 5 minutes to read this article, in which we will introduce the basic usage of OCAP Playground from a developer's perspective.

What is OCAP Playground ？

Before adopting any new technology, it is necessary to figure out what it is, so what is the OCAP Playground? We can define it from the following 3 perspectives.

1. Small Front-End for OCAP Service

Almost all complex modern systems fall into the large back-end and small front-end pattern, ArcBlock's OCAP service is no exception. The front-end that can be touched and feel from the user's perspective is just the tip of an iceberg:

iceburg

The OCAP Playground is a small front-end to the OCAP service and is the visible part of the entire OCAP service. Developers can easily explore the capabilities of OCAP service in OCAP Playground. The interactivity and data visualization ability of Playground enables developers to discover and get inspired during the exploring process and helps to get developers ready to build DApps on OCAP services.

2. Live Documentation for OCAP Service

Because OCAP provides all interfaces in accordance with the GraphQL specification, thanks to the single endpoint and strong typing of GraphQL, OCAP Playground becomes a live and real-time documentation for OCAP service. Developers can browse documents and search documents in Playground, and enjoy the intelligent autocompletion in the query editor, just like writing code in their familiar IDE.

3. First DApp in ArcBlock Ecosystem

If we treat OCAP service as a black box, then the OCAP Playground's role in the entire ArcBlock ecosystem can be shown as follows:

relationship

How to Use OCAP Playground ？

Before getting our hands dirty, we need some preparation work.

Preparation Work

Build the mental model of blockchain data

A conceptual understanding of a technology enables us to master it faster, and almost all blockchain data share the same mental model as follows:

blockchain-mental-model.png

  • Account: Account is like the combination of our account and password in the bank. Both Bitcoin and Ethereum account are composed of three parts: address, public key and private key. The address is equivalent to the user name. , and the public key + private key is equivalent to the password;
  • Transaction: Transaction, is money transfer between any two accounts on the blockchain or a call to a smart contract by any account;
  • Block: Block, is a block of data generated through some consensus algorithm (such as POW, POS, DPOS) by the blockchain network, a block may contain multiple transactions.

Most DApps that store all or part of their data on the blockchain are actually reading or writing account, transaction, and block related data on the blockchain, so most OCAP service API are built around these 3 entities.

Know a little GraphQL syntax

OCAP service uses GraphQL as the query language, and the creator of jQuery John Resig thinks that GraphQL is The New REST. GraphQL is a much better API solution when considering endpoint specification, error definition, data type, parameter validation, and API documentation. The GraphQL community is evolving very fast. Some digital currency exchanges have begun to provide API using GraphQL.

You may be wondering: anyone who wants to develop DApps on OCAP service has to learn GraphQL first? The answer is yes, but you don't have to worry about it. The syntax of GraphQL is rather simple. Even if you have never used it, you can start using the OCAP Playground. In the following example, you can feel its intuitiveness and simplicity.

Hello OCAP Playground!

Talk is cheap, show me the code, open ocap.arcblock.io in your favorite browser, the default screen of OCAP Playground is divided into 2 columns, left column is a query editor, and right column is the result viewer, if it is the first time you visiting the playground, a default query is populated into the query editor and the query results is displayed automatically.

playground default

How to initiate a custom query? Clear the query editor, enter the following query, the query asks OCAP service for the data of the genesis bitcoin block, read more about the data structure of bitcoin block here:

Then click the "Run" button, or just press keyboard shortcuts CTRL + Enter(should be CMD + Enter on Mac), then you can see the bitcoin genesis block data is displayed as JSON format in result viewer.

From the data, we can tell that, the bitcoin genesis block contains only 1 transaction, the block hash is 000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f.

Congratulations, you have successfully completed the first query in OCAP Playground.

Complex query in OCAP Playground

Are there any transaction data in the Bitcoin genesis block? If so, who is the receiver? How much bitcoin has been sent? Is it true that Nakamoto created 50 bitcoin for himself in the genesis block?

With the help of OCAP Playground, we can verify that by ourselves. We can initiate a single query to take all the required block data without any redundancy. Most existing blockchain data query services will return the full block data, which is often too large and can slow down our application.

Paste the following query in query editor, you are also encouraged to enter the following query by hand, during the process, you will learn the capabilities of the query editor:

This query added transaction related fields to the genesisBlock query type, read more about bitcoin transaction data format here, run the query, and you will get the following results:

From the data we can tell that, there is just 1 transaction in genesis block, and the transaction sent 50 bitcoin to the account with address 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa, is the 50 bitcoin spent by Nakamoto?

We can dive deeper with transactionsByAddress query type in OCAP Playground.

Using Table View of OCAP Playground

Now we can make a bold assumption that Nakamoto's Bitcoin address is 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa, does this address send or received more transactions since the genesis block? How much are transfered in those transactions?

We can use the following query to check out transactions of Nakamoto's account:

And the result is:

Apparently, the Bitcoin created in genesis block is never touched. Did anyone send bitcoins to this account? We can answer this question using the following query:

Because a single address may contain many of transactions, OCAP service paginated large datasets for better performance, we can get total number of transactions using page.total field in the query.

There are 1252 transactions to Nakamoto's account, you can check every transaction's sender and amount if you want to.

To provide a better preview of the query results, OCAP Playground will detect the result for list type data, and render them as a table:

playground table

In the meantime, to give developers a better understanding of the data, we have done lots of work when displaying field values in the table:

  • transfer amount/fees, block reward are converted to human-readable format;
  • Block hash, account address, and transaction hash are converted into a link, which will redirect developer to the block explorer such as bitcoin.com and etherscan.io;
  • Provides a preview and full view if there are too many columns to display, developer can click the button in the upper right corner of the table to expand the full view;

If the query result contains nested data, such as transaction inputs and transaction outputs, or multiple transactions in a block, it can also be visualized properly in table view. Want to have a try? You can try to execute the query in the next section and check the render results in the table view.

Using Chart View of OCAP Playground

A picture is worth a thousand words, engineers at ArcBlock have done a lot a work to get blockchain data visualization done right, take the following query for example:

This query returns all transactions send to account 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa, because bitcoin network is distributed by nature, money flow in the network can be visualized using Sankey Diagram, we treat accounts as nodes in the network, and transactions as data flow between nodes, switch to chart view in the result reviewer, and select sankey in chart type, we get the following visualization:

playground sankey

We can tell that, all transactions have a very small amount, it's very likely that the Blockchain community is donating to Nakamoto.

If you encountered any interesting visualization when playing with the sankey diagram, please share with me.

More queries supported by OCAP Playground ?

All above examples are talking about bitcoin from beginning to end, what about multi-blockchain support? If you did get your hands dirty with OCAP Playground when reading this article, you must have found out how to switch between different blockchain: Playground supports creating multiple queries in the form of tabs, each tab can choose a different blockchain, you can switch blockchain using the dropdown button at the top left corner of the tab.

Queries supported by different chains are almost identical. For example, the following query types are supported for both Ethereum and Bitcoin, but the data structure may be slightly different.

  • blockByHeight, query block data by block height
  • blockByHash, query block data by block hash
  • blocksByHeight, query block list by block height range
  • transactionByIndex, query specific transactions in a specific block
  • transactionsByIndex, query all transactions in a specific block
  • transactionByHash, query transaction data by transaction hash
  • transactionsByAddress, query the transaction list by account
  • accountByAddress, query account details by address

Tokens are an important part of the Ethereum ecosystem, they also generated large amounts of data on the Ethereum blockchain, query transactions by token is also supported in OCAP service with query type [transactionsByToken](https://ocap.arcblock.io/doc/ethereum/#transactionsbytoken), is it convenient?

What if you encounter any problem when playing with OCAP Playground? The OCAP service logs every exception on both the back end and the front end. If any bugs are found, We will fix them as soon as possible.

One more thing

Any suggestions on playground improvements? please send your suggestions to me: shijun@arcblock.io

The curtain of the blockchain era has already begun. I believe that every developer has a role to play in the mature and massive adoption of blockchain technology. It is better to jump right in to do something rather than standing on the sidelines.