Introducing the Celer Light Client SDK

4 min read


We are happy to announce that we have implemented an initial version of the Celer Web Light Client SDK, a Celer Network client that runs entirely in a browser or a WebView environment. We have also built Celer Web Wallet as the first demo application of the SDK. Both projects are completely open source and can be tested on the Ethereum Ropsten testnet. The courageous ones are free to give the experimental mainnet deployment a try. The code is still very much in the works as we keep fixing bugs and adding new functionalities, but we welcome any feedback and contribution.

Technical architecture

The Celer Web Light Client SDK is a TypeScript / JavaScript library implementing a subset of the Celer Network off-chain messaging protocol. Currently, it supports sending and receiving conditional payments with ETH or any ERC-20 token based on hashed timelock (HTLC), off-chain boolean conditions and on-chain boolean conditions. As the name suggests, it is intended to be a lightweight client embedded in browsers and WebViews, and lacks the capability of relaying payments.

Celer Web Light Client architecture

Under the hood, Celer Web Light Client implements the same open protocol that has been battle-tested with nearly $2M transaction volume on the Ethereum mainnet via the popular CelerX mobile eSports platform. Because the protocol is already implemented as protocol buffers describing gRPC messages, we conveniently chose gRPC-web to implement the messaging layer between the light client and the off-chain service provider (OSP) network. We use ethers.js to interact with wallet providers such as MetaMask, imToken and Trust Wallet. The user’s private key is managed by the wallet providers and the light client submits signature requests for off-chain communication. In the spirit of full decentralization, the light client stores off-chain channel states locally in IndexedDB via Dexie.js. On-chain smart contract interactions are done in a type-safe way via bindings generated with TypeChain.

Note that the light client is architecturally different from the previously open-sourced Celer Web SDK, which relies on a separately run client binary implemented in Golang. While we are putting more effort on the Web Light Client SDK, we do plan to continue supporting both SDKs and unify their APIs as much as possible.

Use cases

The Celer Web Light Client SDK can be used to build all kinds of in-browser dApps powered by the Celer state channel technology, such as instant atomic swaps, high-frequency prediction markets, micropayments for real-time streaming services, and many more. We will also be able to port the CelerX interactive gaming experience into browsers.

One particular use case, for which we have built a demo in the SDK repo, is an invoice solution for merchants. Celer payment messages are very flexible and versatile in that they are free to contain arbitrary “payment notes” optionally secured by cryptography. In the invoice demo, after the merchant displays an invoice number to the user for an item, the user sends a payment with that number as the payment note. The merchant releases the item after verifying the invoice number. We have published a Docker image for the merchant client that is capable of receiving payments and verifying invoices.

Coming soon

Celer App Channel support

Besides conditional payment networks, we are adding support to the light client for generalized two-party state channels powering Celer Apps like our signature game of Gomoku. We are looking into embedding ethereumjs-vm in the light client to process eth_calls locally, allowing developers to write functional style Celer App logic entirely in Solidity.

State Guardian Network (SGN) integration

A common problem in state channels, data availability is the concern that a user might have their channel maliciously settled by the counterparty with an old state by the counterparty. Celer Network tackles this problem with the State Guardian Network (SGN), a specialized sidechain on top of Ethereum where the validators guard the off-chain states as requested by the users. Celer Web Light Client will call the REST API gateway of the SGN and provide seamless backup of off-chain states in the background.

Synchronization of off-chain states across multiple devices

Remember that the light client stores off-chain states in IndexedDB on browsers, so it is really a “fat client” in some sense. It is a technical challenge when users want to interact with the same channel from multiple devices or even browser tabs, because different clients could run into a split-brain situation and end up with conflicting off-chain states. The ultimate solution we are working on is to have the SGN as the source of truth. We are currently testing out the SGN for a testnet deployment, but before it is ready on mainnet, we will provide a trust-minimized state custody in the OSPs and gRPC messages to synchronize the off-chain states.

Future work

Application-specific channel keys (AppKeys) support

While using in-browser Ethereum wallet providers for signature is best for security, the unfortunate consequence is that signing off-chain messages becomes a very tedious, confusing and inconsistent UX. For example, MetaMask enforces a pop-up filled with random hex bytes for each signature request, while some wallet providers on mobile WebViews allow users to trust a domain after the first signature request. Neither of which is ideal enough for high-frequency state channel interactions.

An alternative is to generate application specific keys only used in the state channels. We are looking into proposals such as EIP-1775 currently implemented the MetaMask Plugin API, and are researching ways to balance security and usability.

Node.js off-chain service provider (OSP) implementation

Even though the current implementation cannot be used as an intermediary node to relay payments, the TypeScript codebase can be easily refactored and extended to support a Node.js implementation of an off-chain service provider. All we need to do is to implement a few more off-chain message handlers and extract the code handling storage into a data access layer that interfaces with different databases. We think that a Node.js OSP would be a nice addition to the Golang implementation we are running today.


We believe that providing an open-source client implementation in TypeScript / JavaScript is crucial for wider adoption of the Celer state channel technology and we are very excited about all the potentials it opens up.

Please do feel free to check out the repo, play around with the demo, and join our Discord server for technical discussions and questions.

About Celer Network

Celer Network is a leading layer-2 scaling platform that enables fast, easy and secure off-chain transactions for not only crypto payments, but also generalized smart contract executions. It enables everyone to quickly build, operate, and use highly scalable decentralized applications through innovations in off-chain scaling techniques and incentive-aligned cryptoeconomics.

To stay updated, follow us via:

Website| Telegram | Twitter | Youtube | Facebook |

Meetup | Medium | Github | Discord |

Celer State Guardian Network Security Upgrade

In Celer, we prioritize security with a comprehensive approach to protocol, code, and defense-in-depth operational security. A coding vulnerability in the Proof-of-Stake (PoS) security...
Celer Network
2 min read

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: