RFC: web3.js Port

Team and Background

Since 2017 I’ve been involved with user-facing blockchain applications. As any DApp developer knows, the first thing you do when building a DApp is run npm i web3. I’ve debugged web3.js at a library level enough to help with troubleshooting and bug fixing on GitHub. I also created a wrapper library, called web3-yeet, which only exposes what 80% of DApps actually need, with a better DX.

Project and Justification

For those unfamiliar with web3.js, it is an npm package that wraps almost all of the RPC calls used to interact with Ethereum nodes. In fact, without web3.js and Infura, one can argue that Ethereum would have never reached its current level of adoption. Without a familiar Javascript SDK, DApp creation will stagnate because developers will rather do “vendor lock-in” with Ethereum, the platform with most users, over upcoming projects. If we focus on DX, it is possible to lower barrier-to-entry and improve chances of developers moving in.

Technical Specification and Implementation

The absolute must of “porting” web3.js over to Nervos is to preserve the API surface. The package need to behave almost as transparently to developers as passing in a “platform” parameter. We need to think of developers as our adoption audience, and not confuse their target audience with ours.

The implementation will keep the Typescript support, and it will adapt wherever Ethereum and Nervos differ, just enough to make the difference clear without having to learn anything new.


The primary goal is to deliver a web3.js port that interacts with Nervos nodes.

A rough workplan may look as shown below:

  1. Determine which API surface to freeze for the spec.
  2. Port the RPC layer. Preserve the API surface, but make calls to Nervos.
  3. Refactor package structures to match Nervos’s naming and branding.

Specifically step 2 and 3 will require development and QC iterations to ensure that the package isn’t buggy. (web3.js often receives complaints of being a mess, so if Nervos can provide a superior DX, we give developer adoption yet another advantage.)

Closing Arguments

It is important not to lose sight of who the target audience is: developers. If we look at tooling provided by Google Cloud Platform for example, we can see a reflection of the project it represents. Even if the platform is top quality, if developers feel frustrated with trying to interact with it, they will look for alternatives. Nervos needs to provide an SDK with a familiar and ergonomic feel so that developers won’t just test the platform: they will test and stay.


This could be a really awesome infrastructure step if it comes out:muscle:


Is DX DirectX?

This is the Chinese version I try to translate:

自2017年以来,我一直從事面向用户的区块链应用程序。任何 DApp 开发人员都知道,搭建 DApp 时要做的第一件事就是运行 npm i web3 . 我已经在库级别对 web3.js 进行了足够的调试,並在 GitHub上进行故障排除和 bug 修复。我还创建了一个名为web3-yeet 的包装库,它只公开 80% 的 DApps 实际需要的东西,并使用了更好的 DX。

对于那些不熟悉 web3.js 的人来说,web3.js Port 是一个 npm 包,封装了几乎所有用于与 Ethereum 节点交互的 RPC 调用。事实上,如果没有 web3.js 和 Infura ,人们可能会认为 Ethereum 永远不会达到目前的普及水平。没有熟悉的Javascript SDK, DApp的创建将停滞不前,因为开发人员更愿意用Ethereum这个拥有大多数用户的平台来“锁定”未来的项目。如果我们专注于DX,就有可能降低进入壁垒,并提高开发者进入的机会。

将 web3.js “移植”到 Nervos 的绝对必要性是保留 API 介面。套件需要像传递“平台”参数一样对开发人员透明。我们需要将开发者视为我们的采用受众,而不是将他们的目标受众与我们的混淆。
我們的实现将持續支持 Typescript,并且它将适应Ethereum和Nervos的任何不同之处,在不需要学习任何新内容就可以清楚地显示出不同之处。

主要目标是交付一个能与 Nervos 节点交互的 web3.js 端口。

  1. 決定规范冻结哪个 API 介面。
  2. 連接 RPC 层。保留 API 介面,但调用到 Nervos。
    3.重构套件结构以匹配 Nervos 的命名和标记。


重要的是不要忘记開發者是目标受众。例如,如果我们查看 Google Cloud 提供的工具,我们可以看到它所代表的项目的反映。即使平台是高质量的,如果开发者对尝试与它交互感到沮丧,他们也会寻找替代方案。Nervos 需要为 SDK 提供一种熟悉的、符合人体工学的感觉,这样开发者就不会只测试平台:他们会测试并继续使用。


Developer Experience :slight_smile:

Great initiative, fuego!!! :fire:

1 Like

In fact I’m curious about how to align ckb development with web3.js, as there is huge fundamental difference of dapp design pattern between the two blockchains.

1 Like

How about using ethers.js interfaces? Ethers.js is much leaner, smaller with good separation of concerns.

I’m open to implementing either interface. I think that overall web3.js is more prevalent, so going by the numbers, that’s the better choice.

1 Like

@OFRBG Can you please provide additional information on how your implementation will work specifically with CKB and its programming model? The concern here is that not enough consideration has been made regarding CKB and its difference with other platforms.

Hey @Ben, it is true that the cell model could be hard to translate, but I say it is doable as long as we define the equivalences for the API surface satisfactorily. That is, when we run a web3.eth.sendTransaction({from, to, value}) call, we will have to work on top of underlying assumptions of what from, to, value mean. Once developers want to make full use of the blockchain’s API, they might need to either 1) pass in extra config parameters, or 2) use a Nervos-specific API. In my experience from developing minor DApps, methods beyond sendTransaction and getting transaction results are very seldom needed.

The original concept is to let developers move over and try production-grade Nervos development without actually having to learn about the basis model. I think it is wrong to expect end-developers to actually have to know how their code and transactions are being handled, much like we don’t really care how AWS allocated vCPU or RAM for instances.