web3-plugin-near

Inspiration

web3.js has about 2 million downloads per month. So, what if we enable some of the developers to develop on NEAR based on their knowledge and experience with web3.js? What if we could increase code portability between Ethereum and NEAR and vice versa? Would not be also nice to provide the developers with an additional option when developing with NEAR? The answer to previous questions seems to be yes for a portion of the developers. And a portion related to 2 million downloads seems worth it :)

What it does

It provide the functionality of near-api-js but in the web3.js style. And here is some elaboration on a 3 key benefits of developing a web3.js plugin for NEAR:

First, the development experience and the learning curve:

Developers who already use web3.js can quickly start working with Near and its ecosystem with fewer things to read and learn. All they need to do is provide the web3.js library with a link to a Near provider, add with the plugin, they can start working just like they used to. And even though, there will be slight differences that they'll have to adjust for, that we we do our best to reducing them to the minimum. Interacting with near in a was similar to what the developers are used to would attract lots of developers and decrease their learning curve. And they can still later shift to, for example to near-api-js any time. We do not expect every developer to use the web3.js plugin. But, we expect that a good portion of developers will find it attractive and useful.

Second, code portability:

Code that already exists for DApps that uses web3.js, could be easily adapted to work with Near. Users would only have to make small changes to their current code. For example, the code used to catch exceptions that indicate an unresponsive provider won't need to be changed. This also means developers can use the same code base for both Ethereum based networks and Near, with a bit of custom handling.

Last, diversity:

It is good to provide the developers with an additional alternative to development experience provided by near-api-js. So, developers can pick the library that they feel more comfortable working with.

How we built it

This has been implemented following the best practices for implementing a web3.js plugin. After also getting some knowledge about NEAR and its JSON RPC endpoints.

Challenges we ran into

In a short working time, to learn about NEAR and its ecosystem. And then to provide a working plugin published on npm.

Accomplishments that we're proud of

NEAR Plugin

Create NEAR Plugin and publish it to the npm registry

The web3.js plugin for NEAR has been publish to
https://www.npmjs.com/package/@conx3/web3-plugin-near and it is useable inside this example playground: https://codesandbox.io/p/sandbox/broken-haze-9krygq?file=%2Findex.js Additionally, some tests has been written to test some of the functionality.

Implement all basic NEAR RPC methods

However, there is a difference between calling those function at near-api-js and in this plugin. In this plugin, the internal handling is similar to web3.js. So the provider errors could be caught in the same way the developer would catch with web3.js.

Implement alternative methods to ethereum RPC methods available currently at web3.eth.[RPC_METHOD]

Implement web3.near.accounts that act a bit similar to web3.eth.accounts

Implement web3.near.Contract that act a bit similar to web3.eth.Contract

NEAR Aurora Plugin

Aurora is a very interesting EVM that would play a nice role in the NEAR ecosystem. And, more web3.js plugins for NEAR ecosystem would be implemented also in the future.

Aurora is an EVM-compatible blockchain built as a smart contract atop NEAR blockchain. This plugin would leverage Aurora custom RPC methods (https://doc.aurora.dev/evm/rpc/) and other custom behavior enabled at Aurora especially Cross-Contract Calls (XCC). More on Aurora XCC at https://github.com/aurora-is-near/aurora-contracts-sdk.

Create NEAR Aurora Plugin and publish it to the npm registry

The web3.js plugin for NEAR Aurora has been publish to
https://www.npmjs.com/package/@conx3/web3-plugin-near and it is useable inside this example playground: https://codesandbox.io/p/sandbox/broken-haze-9krygq?file=%2Findex.js. Additionally, some tests has been written to test some of the basic functionality.

web3.aurora is also accessible as web3.near.aurora

Aurora plugin could be used now as web3.near.aurora. However, its registration needs a bit of simplification. A PR would be opened later on web3.js registry for this and similar use cases.

Enable all Ethereum RPC methods on AuroraPlugin

Now all Ethereum RPC methods are callable on web3.aurora (and on web3.near.aurora as a consequence). However, there is a small modification needed to not expose the unsupported methods on web3.aurora and the AuroraPlugin class.

Support custom RPC methods on AuroraPlugin (the non-basic-Ethereum)

Some of the custom RPC endpoints available at Aurora Engine are now callable on AuroraPlugin as an example of this functionality. However, some of them seems to not be yet implemented in the current version running the main net and test net. Even though, they is marked as completed at: https://doc.aurora.dev/evm/rpc. So, this need to be double checked.

Running Tests

Testing NearPlugin

Executing yarn test near.test.ts would give something like:

 PASS  test/index.test.ts
  NearPlugin Tests
    NearPlugin method tests
      ✓ should call `getBlockNumber` method with expected param (10 ms)
      ✓ should call `block` method with expected param (3 ms)
      ✓ should call `getProtocolVersion` (3 ms)
      ✓ should call `isSyncing` (2 ms)
      ✓ should call `getGasPrice` (2 ms)
      ✓ should call `getCoinbase` (2 ms)
      ✓ should call `getCoinbase` (2 ms)

Test Suites: 1 passed, 1 total
Tests:       7 passed, 7 total
Snapshots:   0 total
Time:        1.685 s, estimated 2 s
Ran all test suites.
Done in 2.16s.

Note: Before running the tests, be sure to run NEAR development node before. You can follow: https://docs.near.org/develop/testing/kurtosis-localnet. And if this is not your first time following the steps for running a development node, just double check the values when running ~/launch-local-near-cluster.sh and ensure docker containers are running]

Testing AuroraPlugin

Executing yarn test aurora.test.ts would give something like:


 PASS  test/aurora.test.ts
  AuroraPlugin Tests
    AuroraPlugin can call Ethereum standard RPC endpoints
      ✓ should call `getBlockNumber` method with expected param (429 ms)
      ✓ should call `block` method with expected param (189 ms)
      ✓ should call `getProtocolVersion` (198 ms)
      ✓ should call `isSyncing` (194 ms)
      ✓ should call `getGasPrice` (196 ms)
      ✓ should call `getCoinbase` (129 ms)
      ✓ should call `getCoinbase` (153 ms)
    AuroraPlugin can call the additional Aurora endpoints
      ✓ should call `parityPendingTransactions` (195 ms)
      ○ skipped should call `txpoolStatus`
      ○ skipped should call `txpoolInspect`
      ○ skipped should call `txpoolContent`

Test Suites: 1 passed, 1 total
Tests:       3 skipped, 8 passed, 11 total
Snapshots:   0 total
Time:        3.969 s, estimated 4 s
Ran all test suites matching /aurora.test.ts/i.
Done in 4.42s.

Executing yarn test aurora.test.ts would give something like:

 PASS  test/near.aurora.test.ts
  AuroraPlugin Tests
    ✓ should have `web3.near.aurora` setup (1 ms)
    ✓ should call `getBlockNumber` method on `web3.near.aurora` (395 ms)

Test Suites: 1 passed, 1 total
Tests:       2 passed, 2 total
Snapshots:   0 total
Time:        2.658 s, estimated 3 s
Ran all test suites matching /near.aurora.test/i.
Done in 3.19s.

What we learned

A lot about NEAR.
Explored the possibility and capability of using some of the Ethereum development tools with NEAR as a non-EVM-compatible network.
Aurora and its handy Cross-Contract Calls (XCC).

What's next for web3-plugin-near

Finish the implementation for the planed namespaces for web3.near: web3.eth.[RPC_METHOD], web3.near.accounts, web3.near.Contract, web3.near.aura.
Port the functionality from https://www.npmjs.com/package/web3-plugin-craftsman to web3.near.Contract and web3.near.aura.Contract.
Keep stabilizing, improving and maintaining...

Built With

aurora
near-api-js
typescript
web3.js

Updates

Muhammad Altabba started this project — Nov 08, 2023 10:07 PM EST

Leave feedback in the comments!

Log in or sign up for Devpost to join the conversation.