Obtaining Data

Target releaseMercury
Epic RHOL-480 - Getting issue details... STATUS
Document status
Document owner


  • Provide mechanisms for users to obtain data from the Blockchain

Background and strategic fit

Both users and dApp Developers will want block data pertaining to their transactions and dApps


  • This class of users do not want to run a validating node.   They do not want to put up stake in the network.
  • This class of users wants to run a distributed application, and obtain data from the application, so they can run analytics and mine the data from the blockchain.


#TitleUser StoryImportanceNotesTicket
1Code DeploymentAs a dApp developer, I get an answer back when the code is deployed if the code runs to completion, or an out of Phlo errorMust Have
  • Users get an answer if the code has run out of Phlogiston.  Otherwise, the code is run. 

2Transaction Receipts

As a dApp developer, when a deploy takes place with a name or set of names from my code api, I get to listen on the name for blocks. 

As a child shard, I need to listen for events taking place in the parent shard.

As a shard validator, I need to listen for events taking place in my shard so that the sharding client can create the correct events in the parent shard.

Must Have
  • The full block will not be returned to the client, only the data pertaining to transactions with the name will be returned.
  • There is no cost to obtain this data, as the transaction has already been paid for.
  • The client that will get the data back will be a thin client.  Data will come in on a return channel. The thin client will need to persist that data locally for future reference.
  • Blocks and their statuses that have the names.
  • Returns blocks that are not finalized, blocks come back as soon as they are proposed.
  • Can add a range of blocks to the request.

RHOL-441 - Getting issue details... STATUS

CORE-994 - Getting issue details... STATUS

RHOL-759 - Getting issue details... STATUS

3Exploratory Deployment

As a dApp developer, I want to learn about the state of specific processes.

 Must Have
  • Same as normal code deployment but can use unforgeable names and you're guaranteed that the deployment will be rolled back.
  • You have to know specific names in order to interact with them.
  • This mechanism will be a deployment, and will likely cost less than other deployments.  The state won't be updated as a result.  The code will be rolled back. Payment will be made to a single node.  
  • This query will not be on the blockchain.
  • Uses the node's latest finalized state.


  1. Expose the feature in the REPL
    1. Will need to be either a separate gRPC endpoint for a special flavor of the REPL
    2. Or an option on the Repl start.
  2. Expose the code that Michael has authored.   Medha Parlikar (Unlicensed) to ticket.  
    1. Wrap it up in a gRPC - would work like eval. 
    2. Need to update it to use the blockhash instead of the tuplespace hash.
    3. Include this in the front end application.

4Streaming API

  • Use a gRPC Proto to stream data off of the last finalized block.
  • Provide some pretty printing in advance.

5Full validationAs a dApp developer, I want all the block data for a shard.Nice to have
  • Run a full node, to obtain all the local block data.

6Read Only NodeAs a dApp developer, I want all the block data for a shardMust Have
  • Run a read only node, obtain all the block data locally.
7Gossip all blocksAs a dApp developer, I want all the block data for a shard.Nice to have
  • Contact a validator, see if they will gossip their blocks to you for a fee

8Harden against DOSAs a Node Operator, I want to know that my node cannot be subject to DOS attack via these API'sMust Have
  • Implement something similar to HashCash, where the caller has to perform some work before calling the API.  
  • Include the ability to turn up the difficulty/tune the difficulty depending on whether the network is being attacked.
  • Reference: http://www.hashcash.org/papers/hashcash.pdf
Out of scope of the platform

User interaction and design

Will need to include the API design for retrieving data.

Here's an example of some JS code that uses Rchain-API to query for results: https://gist.github.com/JoshOrndorff/b0fe7aed93d16beabc2885484c6e8c54

Related Requirements

1Retrieve data asynchronouslyAs a mobile app developer, I need to send all my request asynchronously, so that my apps are fast.Must Have
  • The RSong demo requests the song, song metadata and song artwork asynchronously.  It's not clear to Medha if this is a hard requirement.  There isn't any reason why the song can't be requested first, followed by the metadata.

2Monitor Requests for DataAs a validator, I need to know how much of my node's resources are spent on data access requests so that I can set the prices for transactions properly.Must Have
  • There has to be a dashboard that shows how many requests for data the node is servicing.  
  • There should also be a dashboard that shows how much data is being returned in these requests. This metric can be in aggregate if needed.

3PerformanceIn principle, A dApp developer will want to provide a user a transaction receipt with at least the same speed at which the transaction itself is processed.  Must Have
  • This means that half of the transaction processing time is in fact, in the retrieval of the transaction confirmation. 

4Deployment ID

Each deployment has a userid and timestamp, userid (public key associated with private key used to sign transaction ) for that particular deployment by the client software.  These keys should be looked up in the block store.

Must Have
  • Users need a way to retrieve transaction receipts for their deployments.

Traceability Matrix

key summary type created updated due assignee reporter priority status resolution

Not Doing