Funded [Factoshi-1] Graff - A GraphQL wrapper for the factomd RPC API

Grant round: Grant Round 2019-03

Total Grant Pool: 121,449.00 FCT

Final results

Grant FCT Requested Cumulative FCT Score Funded
900.00 900.00 1.00 Yes
660.00 1,560.00 2.00 Yes
9,000.00 10,560.00 3.00 Yes
8,747.00 19,307.00 6.00 Yes
8,093.00 27,400.00 7.06 Yes
1,126.00 28,526.00 8.44 Yes
38,940.00 67,466.00 8.83 Yes
13,750.00 81,216.00 9.10 Yes
22,500.00 103,716.00 9.22 Yes
2,950.00 106,666.00 10.09 Yes
10,000.00 116,666.00 10.15 Yes
680.00 117,346.00 11.12 Yes
2,400.00 119,746.00 14.73 Yes
9,000.00 128,746.00 14.75 No
33,333.00 162,079.00 15.37 No
1,939.00 164,018.00 15.45 No
800.00 164,818.00 15.59 No
Not approved 13.97
Not approved 15.36
Not approved 15.36
Not approved 16.91
Status
Not open for further replies.

Alex

Factoshi
Executive Summary
Graff is a GraphQL wrapper for the factomd RPC API. It enables users to make queries to factomd that exploit and mirror factomd's natural graph data structure. Furthermore, it provides a simple way to open a websocket connection with a factomd endpoint to enable an event-driven application model via subscriptions.

The work on this project is already complete; this is a backpay grant.

Graff primer: https://blog.factoshi.io/graff-a-graphql-wrapper-for-the-factomd-rpc-api/
GitHub repo: https://github.com/Factoshi/graff
Demo API: https://graff.factoshi.io/

ANO / Committee
Group: Factoshi
FCT address: FA2tsEih6kyzNSBtbkzZ31HUGF8QQB7RPBFouBVfYyUZk24QkPr2
FCT: 2950

Total FCT Requested
2950

Start Date
2019-07-31

Completion Date
2019-07-31

Project Description
A full description of the project is available in the blog post cited above and is available again here. Please read that blog post to better understand what GraphQL is, why it is useful, and how it can be used to query factomd.

Graff has been built to handle the varying demands of a production environment:

1. Extends factomd's RPC authentication so that users can operate it within a permissioned context.
2. First class support for Docker to ensure easy integration with the Factom ecosytem.
3. Several configuration options (with sensible defaults) to limit the opportunity for users to execute a malicious query that could result in a denial of service.
4. Intelligent caching mechanism to reduce load on factomd.
5. First class support for Redis, so services under heavy load can scale effortlessly with a shared cache, as demonstrated in this docker-compose recipe (which uses Nginx to load balance requests).
6. Offers a GUI playground that can be used to interact directly with the API without the need to write any code, which is very useful during application development.

The GUI playground is an excellent way to explore the API. There are two ways to access that playground:

1. Factoshi's demo playground, which is using 3 load-balanced instances of Graff and a shared Redis cache inspired by the recipe referenced above.
2. Spin up your own demo instance in seconds using the following command:

Bash:
# command assumes factomd is available at localhost with default ports

docker run --rm \
    -e GQL_PLAYGROUND=true \
    -e GQL_INTROSPEC=true \
    --network host \
    factoshi/graff:latest
Query documentation can be found by clicking the "Docs" tag on the righthand side of the playground window. Here is a demo query to get you started:

Code:
# If you're using the Factoshi courtesy node then this query is already cached, so it won't even hit factomd.
# Try a unique entry block hash to see a query that makes it through to factomd.

query {
  entryBlock(hash: "b72fa3a32192d6c37c60d9f8c8327eaff03c8daca3da14d0e7265ae0bb3e79e2") {
    chainId
    sequenceNumber
    directoryBlock {
      height
      timestamp
    }
    entryPage(first: 5, offset: 10) {
      pageLength
      offset
      totalCount
      entries {
        externalIds
        content
      }
    }
  }
}
Problem Statement
Again, please view the aforementioned article, which covers the problem this API aims to solve in depth.

Briefly, Graff solves several potential problems that the factomd API inherits from general REST/RPC APIs, which are typically characterised by wasted bandwidth, increased latency, and greater application complexity:

1. Overfetching: Factomd returns more data than you need.
2. Underfetching or the N+1 problem: It is often necessary to make several sequential requests to get the data you need from factomd (e.g. to fetch the factoid block head you need to request the directory block head first).
3. Event polling: To lean about new events, it is necessary to continually poll the state of the blockchain.
4. Lack of Pagination: It is not possible to paginate results return by factomd.

Goals and Objectives
The goal of this project was to make a beta release of a scalable GraphQL wrapper for the factomd API that can easily integrate into a production environment.

Success Criteria
A beta release of the API has been made; the project was a success.

Timelines and Milestones
N/A

Budget
The funds requested are to compensate for the time invested into planning, research, development and testing the API.

Assumed Price Per FCT
$4.25

Competition
Several APIs have been built for the Factom protocol, including both private and open source. OpenAPI is likely the closest thing that could be considered a competitor. However, OpenAPI is a REST API, which is a substantially different approach to GraphQL.

Putting to one side the difference between REST and GraphQL, the two APIs still contrast quite sharply. OpenAPI is a good choice where the user wishes to manage their own EC wallet, users, and blockchain data. Graff, on the other hand, is completely stateless, and does not depend on an intermediary database.

This is a tradeoff, and neither approach is inherently better than the other. Whilst OpenAPI gains power from being able to store data, Graff gains agility and ease of administration by interfacing directly with the factomd RPC API. It can be torn down as easily as it can be set up, as it is not necessary to protect a database.

In short, I do not believe Graff has any direct competitors, but instead adds a complementary service that further enriches the ecosystem.

Additional Information
N/A

Indemnification and Waiver
By submitting a grant proposal or participating in the grant proposal process, the submitter hereby agrees to release, waive, discharge the Guides, Authority Set Members, Standing Parties, and their respective employees, contractors, agents, representatives, successors, and assigns (collectively, the “Releasees”) from any and all liabilities, claims, and demands of whatever kind of nature, either in law or in equity, which arise or may hereafter arise from participating in the grant proposal process, except for those caused by the willful misconduct or intentional torts of the Releasees. The submitter further agrees to indemnify and hold harmless the Releasees against all liabilities, obligations, losses, damages, penalties, claims, actions, judgments, costs, or expenses which may be imposed on, asserted against or incurred by any Releasee as a result of, or arising out of, or relating to this grant process contemplated by this document, including without limitation, any judgment, settlement, attorneys’ fees and other costs or expenses incurred in connection with the defense of any actual or threatened action or proceeding, except for the liabilities caused by the willful misconduct or intentional torts of the Releasees.
The submitter warrants and represents that he or she has all necessary power and authority to represent all applicants contained in the grant proposal: (i) to submit the proposal and (ii) to agree to this Indemnification and Waiver.
Note: Please see the Factom governance document (Doc 001) for definitions of Guides, Authority Set Members, and Standing Parties. Grant proposals submitted in another format shall include this indemnification and waiver in its entirety.
 
Last edited by a moderator:

Chappie

Factomize Bot
The Forum Q/A process has now started. The community may ask questions until Aug 12, 2019 at 23:59 UTC.

Other important dates:
  • After the question period ends on Aug 12, 2019 at 23:59 UTC, you may continue to answer last minute questions until Aug 13, 2019 at 23:59 UTC
  • Once the answer period ends, voting will start one minute later on Aug 14, 2019 at 00:00 UTC
  • Voting will be closed on Aug 16, 2019 at 23:59 UTC and the final results will immediately become available.
 

Mike Buckingham

Cube3
Website Committee
Governance Working Group
As a complementary service that further enriches our ecosystem this development is something we should be really appreciative of. Resolving the dilemma of fetching the right amount of information is terrific. I particularly liked the blogs which described it and started to make it accessible to more people. To have done this up front from Factoshi's own resources so that the community only have to invest in something that works is commendable. Thank you.
 
Thanks for taking the initiative to work on this useful library for the Factom protocol. Given the oversubscribed nature of this grant round we can't commit to supporting it until we do rankings of all the grants and see what the trade-offs are, but we will try to find room in our rankings to support this grant as we think it's valuable.
 

Chappie

Factomize Bot
This is a final warning that the community has just 24 hours from now to ask any last minute questions.

Other important dates:
  • After the question period ends on Aug 12, 2019 at 23:59 UTC, you may continue to answer last minute questions until Aug 13, 2019 at 23:59 UTC
  • Once the answer period ends, voting will start one minute later on Aug 14, 2019 at 00:00 UTC
  • Voting will be closed on Aug 16, 2019 at 23:59 UTC and the results will immediately become available.
 

Paul Bernier

LUCIAP
Core Committee
Core Developer
Even though the commit history of the repo already speaks by itself I just want to say that I had the opportunity to follow the development of Graff and I can testify of the amount of work and care Alex put into this project. And as others already said, GraphQL is particularly relevant to the context. I cannot guarantee yet if this grant will fit into the "paid tier" of our ranking but I wanted to state that this is an exemplary backpay grant by my standards.
 

Valentin Ganev

Factomatic
As others have mentioned, this work is a great addition to Factom development ecosystem. I also think that Factoshi deserves to get a compensation for it, not least because of the great work you have been doing at 50% efficiency. We will support your application!
 

Chappie

Factomize Bot
The Forum Question Period has now ended. Teams will have until Aug 13, 2019 at 23:59 UTC to answer any last-minute questions.

Other important dates:
  • Once the answer period ends, voting will start one minute later on Aug 14, 2019 at 00:00 UTC
  • Voting will be closed on Aug 16, 2019 at 23:59 UTC and the results will immediately become available.
 

Chappie

Factomize Bot
The Answer Period has now ended and Standing Parties may now vote.

Voting will be closed on Aug 16, 2019 at 23:59 UTC and the final results will immediately become available.

Instructions for Standing Parties:
  • You may vote in any thread or on this page. The ranks are mirrored once you save.
  • Drag and drop using the three-lined icon at the left of the grant proposal and hit "Save" when done.
  • If you change rankings and leave the page without saving, those changes will be reversed and not count.
  • You may change your vote as many times as you like prior to the vote being closed.
  • If you "Abstain" that means your vote won't be counted no matter what you ranked that proposal.
  • If you deselect "Approve" how you rank the grant matters, but 60% of voters must approve the grant for it to be funded.
 
Status
Not open for further replies.
Top