Build the next big decentralized application with Cleargraph

A multi-purpose GraphQL runtime for Ethereum, now available in public beta.

Cleargraph is a multi-purpose GraphQL runtime for decentralized applications (dApps) and wallets. Its API is infrastructure that makes it easy for application developers to create products and services that take advantage of the Ethereum blockchain without sacrificing usability, flexibility, or security. Cleargraph is the essential missing link between conventional application development and on-chain smart contracts.

The Cleargraph API server is open source and released under the permissive Apache 2.0 license. It is written in Typescript, a statically typed JavaScript superset from Microsoft. You can host your own instance of the Cleargraph API, or use our hosted version at https://api.cleargraph.com.

In this article, I’ll take a deeper look into the motivations behind why we chose to build Cleargraph, how our team made some of our design decisions, and how you can help us improve it.

🌐 Why GraphQL?

We designed Cleargraph to improve upon the current state-of-affairs when developing cross-platform decentralized applications (dApps). Through our experience designing numerous tokens, games, and other blockchain-based applications, we noticed consistent sources of duplicated effort, especially in application logic which interfaces between the application and the Ethereum chain.

Supporting multiple simultaneous user interfaces (including desktop, iOS, and Android) further exacerbated the issues. Not only was the code repetitive across clients, but gradual improvement of clients while ensuring backward compatibility was difficult to achieve.

There are many user experience features of Cleargraph that require more than the standard Ethereum JSON RPC API to implement. Among these include core user feature expectations, such as listing all previous transactions made by an address, including internal transactions and those performed on a different device. It is becoming an increasingly common pattern in dApp development to store these “secondary indices” on a server and allow clients to query them over an API. This requirement has made a client-server approach necessary for Cleargraph to meet the high bar of casual dApp users.

After surveying alternatives and based on our prior experience with the technology, we decided to use GraphQL to power the Cleargraph API. GraphQL is a cutting-edge, well-supported technology developed at Facebook which was designed from the ground up to address many of the same issues we faced. While it is a radical departure from more classical API design approaches, GraphQL adopts lessons-learned from REST and addresses many of its key weaknesses.

GraphQL is the best choice for the back-end of decentralized applications and wallets. Amongst many other benefits, it offers:

  • Composability and expressivity—In GraphQL, clients specify the exact data fields that they require in every request. Queries are composable which reduces the number of round-trips required to deliver data-driven user interfaces. A client can request a user’s profile information, token balances, and previous transactions all in a single GraphQL request thanks to the power of the GraphQL language.
  • Flexible type safety—The GraphQL type system allows for strong guarantees of the correctness of an API request. For example, we define custom scalars, such as EthereumAddressString and HexValue to automatically perform validation on these data types at all API boundaries. The Cleargraph API explicitly represents Ethereum value types (ether, wei, Gwei, etc.) and can automatically convert between them in any request depending on the client. Types allow GraphQL APIs to be self-documenting and introspectable, right within your browser.
  • Backward and forward compatibility—Designed to support evolving requirements of both clients and servers, GraphQL decouples the development of front-ends and back-ends without sacrificing functionality. This is especially useful when supporting legacy codebases and clients on multiple platforms. Additionally, the ability to add new fields without affecting older clients removes the need for API versioning.

Show me!

Sometimes, seeing is believing. As a quick peak, take a look at these example queries or play with the API in your browser.

A couple useful Cleargraph queries.

TL;DR

GraphQL allows Cleargraph to encapsulate the domain space of the blockchain directly and enriches it with useful functionality, thus making dApp development more approachable to conventional application developers. By adopting GraphQL and employing some of its more advanced features such as query caching and subscriptions, Cleargraph unlocks a level of expressivity and agility for dApps developers that was impractical using other techniques.

👨‍👩‍👧‍👦 Decentralized identity

We believe a decentralized identity system represents a transformative shift in our relationship with technology. To support the advanced identity-related features of Cleargraph-enabled apps, the Cleargraph API has first-class support for a range of emerging standards in the Ethereum ecosystem.

Ethereum Name Service

One of the biggest sticking-points in the usability of blockchain applications is the use of hexadecimal addresses to send/receive cryptoassets. This isn’t the first time technology has faced this problem: on the Internet, IP addresses are a relatively unfriendly representation of a networked device. The DNS system solved this problem by creating a human-readable namespace that was available for purchase, so you could navigate to google.com instead of 172.217.6.46.

The production-ready Ethereum Name Service does for Ethereum addresses what the DNS system did for IP addresses. However, unlike DNS, ENS is a fully-decentralized system that does not rely on a closed group of domain registrars which arbitrarily define prices. We believe ENS is an important step in the maturation of the dApp ecosystem that enables far more user-friendly experiences. ENS forms the basis of Cleargraph’s decentralized username system. Now you can send ether, tokens, and signed messages to alex.cleargraph.eth instead of an arcane hexadecimal encoded address.

The Cleargraph API resolves ENS domain names transparently, letting clients treat them as if they were conventional Ethereum addresses. Additionally, the Cleargraph API employs the reverse address lookup features of ENS to turn addresses back into domain names, further improving upon the user experience of decentralized applications that it powers.

Address resolution is also a security feature useful in preventing phishing attacks, which are increasingly common low-level attack vectors on users of dApps. One can imagine a future where all users and applications have an ENS domain that can be used to uniquely identify them and verify their integrity.

Private contact discovery

Even with ENS addresses providing a long-term solution for decentralized usernames, there’s still a bootstrapping problem. How do you detect which of your friends are using Cleargraph-enabled applications, while minimizing the exposure of your friends list itself?

The Cleargraph API can power the contact discovery features of the applications it powers by tapping into the decentralized social network on everyone’s device: the address book. Users can optionally link phone numbers to Ethereum addresses using a two-factor authentication system. We rely on a Signal-inspired “global salt, strong hash, truncate” scheme to preserve the privacy of our users and hope to improve it using some new technologies in the future.

Future work

We have a lot planned for the Cleargraph identity system, including support for:

🔎 Deep contract & transaction inspection

Smart contracts are complex beasts. In addition to fetching data from the Ethereum blockchain and sending signed transactions, the Cleargraph API is packed with useful tools that make it easier for application developers to build cross-platform user experiences. Amongst these features include:

Tokens and collectibles (NFTs)

ERC 20 and ERC 721 tokens have taken the cryptocurrency world by storm, and have become some of most important standards in the industry. The Cleargraph API supports querying any compatible token contract using just the contract’s address and features a rich API that lets you find token names, symbols, balances, and allowances.

Multi-network

Scope your requests to the Ethereum mainnet or testnets to make support for multiple chains a snap. Support for multiple blockchains is on the horizon.

Raw Ethereum ABI support

Your clients can provide inline Ethereum ABI to interact with arbitrary smart contracts on the Ethereum blockchain. Cleargraph also provides predefined shortcuts for common ERC standards and transaction cost estimation.

Search transactions by address

Inspect the status and emitted events of all transactions related to an address, powered by Etherscan. We intend to offer transaction flexible filters powered by GraphQL subscriptions.

⚡️ How do I use the Cleargraph API?

All application developers are welcome to use the Cleargraph API, starting today. When interfacing with the Cleargraph API, we suggest using a GraphQL client. We highly recommend the awesome ones from the Apollo team. There’s a GraphQL client in nearly any language you pick.

The GraphQL endpoint for Cleargraph is:

https://api.cleargraph.com (try it in browser!)

❓ How can I help?

Contributions to Cleargraph are welcome. Our issues are maintained on GitHub and pull requests are appreciated. We’d love help with feature additions, documentation improvements, and more thorough tests.


On behalf of the entire Distributed Systems team, we hope you enjoy using Cleargraph! Make sure to follow us on Medium to stay updated on the latest in decentralized applications and star dsys/cleargraph on GitHub.

Interested in joining our team? Check our careers page or drop us a line at careers@distributedsystems.com 🚩