Build the next big decentralized application with Clear
A multi-purpose GraphQL runtime for Ethereum, now available in public beta.
Clear is available via our 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. Clear is the essential missing link between conventional application development and on-chain smart contracts.
The Clear 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 Clear.
In this article, I’ll take a deeper look into the motivations behind why we chose to build Clear, how our team made some of our design decisions, and how you can help us improve it.
🌐 Why GraphQL?
We designed Clear 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 Clear 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 Clear 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 Clear. 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
EthereumAddressStringandHexValueto automatically perform validation on these data types at all API boundaries. The Clear 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:
TL;DR
GraphQL allows Clear Protocol 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, Clear 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 for apps developed on Clear Protocol, the Clear 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 Clear Protocol’s decentralized username system. Now you can send ether, tokens, and signed messages to alex.distributedsystems.eth instead of an arcane hexadecimal encoded address.
The Clear resolves ENS domain names transparently, letting clients treat them as if they were conventional Ethereum addresses. Additionally, the Clear 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 Clear-enabled applications, while minimizing the exposure of your friends list itself?
The Clear 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 Clear identity system, including support for:
- Delegated and subsidiary identity management to support the creation of multi-sig identity contracts and advanced custodial services
- User-defined “badges” or claims that make possible reputation systems and permissioned liquidity pools of tokenized securities
- Resolving identifiers according to the Decentralized Identifiers standard
🔎 Deep contract & transaction inspection
Smart contracts are complex beasts. In addition to fetching data from the Ethereum blockchain and sending signed transactions, the Clear 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 Clear 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. Clear 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 Clear API?
All application developers are welcome to use the Clear API, starting today. When interfacing with the Clear 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.
❓ How can I help?
Contributions to Clear 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 Clear! Make sure to follow us on Medium to stay updated on the latest in decentralized applications on GitHub.
Interested in joining our team? Check our careers page or drop us a line at careers@distributedsystems.com 🚩
