web3-providers-connex v0.7.4

web3-providers-connex

Web3.js provider implemented using Connex.js and Thor restful APIs. It makes it possible to use web3.js and ethers.js to interact with VeChain Thor protocol.

Installation

npm i web3-providers-connex

Usage

To get a web3 object:

import * as thor from 'web3-providers-connex';

// connexObj is an instance of Connex
const provider = new thor.ConnexProvider({ connex: connexObj });
const web3 = new Web3(provider);

To get an ethers JsonRpcProvider:

import * as thor from 'web3-providers-connex';

// connex is an instance of Connex
const provider = thor.ethers.modifyProvider(
  new ethers.providers.Web3Provider(
    new thor.ConnexProvider({ connex: connex })
  )
);

To get an ethers JsonRpcSigner:

const signer = provider.getSigner(address);

To deploy a contract

const factory = thor.ethers.modifyFactory(
  new ethers.ContractFactory(abi, bin, signer)
);
const contract = await factory.deploy(...args);

Methods modifyProvider and modifyFactory are used to replace methods jsonRpcProvider.sendTransaction and contractFactory.deploy shipped with ethers.js to bypass the contract address computation that is incompatible with the Thor protocol.

Guides

Request at a Particular Block Hight

There are a few Eth JSON-RPC APIs where users can specify a particular block height when requesting information 1. To enable this feature, you need to provide a Net object when creating a ConnexProvider object as illustrated as follows:

import { SimpleNet } from '@vechain/connex-driver';
import * as thor from 'web3-providers-connex';

// url: thor node address (e.g., https://sync-mainnet.veblocks.net/)
const net = new SimpleNet(url);
const cp = new thor.ConnexProvider({ 
  connex: connexObj,
  net: net
});

For the default block number options 1, only latest and earliest are supported. The followings are the affected ETH JSON-RPC APIs: eth_getBalance, eth_getCode, et_getStorageAt and eth_call.

Fee delegation

Fee delegation can be enabled by passing the delegator URL to the ConnexProvider constructor:

import * as thor from 'web3-providers-connex';

const cp = new thor.ConnexProvider({
  connex: Obj,
  delegate: {
    url: 'https://delegator.url'
  }
})

or calling enableDelegate:

cp.enableDelegate({ url: 'https://delegator.url' });

You can also disable fee delegation by

cp.disableDelegate();

A delegator is a web service that co-signs and returns a signature for transactions it accepts. The gas fee would then be deducted from the delegator's account rather than the transaction sender's account.

You can build your own delegator by implementing VIP201. Alternatively, you can use public fee delegation services (e.g., provided by vechain.energy).

Get a Connex instance in the Node.js environment

import { Framework } from '@vechain/connex-framework';
import { Driver, SimpleNet, SimpleWallet } from '@vechain/connex-driver';

const net = new SimpleNet(nodeUrl);
const wallet = new SimpleWallet();
// Import private key: 
wallet.import(pk)

const driver = await Driver.connect(net, wallet);
const connex = new Framework(driver);

Examples

You can check https://github.com/zzGHzz/web3-providers-connex/tree/main/test for more examples.

Implemented ETH JSON-RPC APIs

The table below lists all the implemented JSON-RPC APIs. All the web3/ethers APIs that invoke the APIs are therefore available.

License

This software is licensed under the GNU Lesser General Public License v3.0, also included in LICENSE file in repository.

References

1(https://eth.wiki/json-rpc/API).