web3-providers-connex

This project implements the JSON-RPC provider defined in EIP-1193 for the VeChain Thor protocol. The provider is made to be compatible with web3.js and ethers.js, allowing developers to use the two libs to interact with a Thor node.

⚠️ Repository Notice: End-of-Life (EOL)

This repository is now archived and has reached its end-of-life (EOL). We have transitioned to a new and improved repository that will continue to receive updates, support, and new features.

Important Dates:

• Final Version Release: November 4th, 2024
• End-of-Support Date: December 31st, 2024
• Repository Archive Date: December 31st, 2024

New Repository

You can start using the VeChain SDK for the latest updates and developments.

Thank You

Thank you to all contributors and users for supporting this project. We appreciate your interest and encourage you to explore the new repository for ongoing improvements and features.

---

For any further questions or migration guidance, please reach out using our support portal.

Installation

npm i @vechain/web3-providers-connex

Examples

Using EIP-1193 provider

Checking account balance

import { Provider } from '@vechain/web3-providers-connex'

// connexObj is an instance of Connex
const provider = new Provider({connex: connexObj})
const balance = await provider.request({ 
  method: 'eth_getBalance', 
  params: ['0x...'] 
})

Obtaining a connex instance in Node.js

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

const net = new SimpleNet(url-to-thor-node)
const wallet = new SimpleWallet()
// import private key if needed
wallet.import('0x...')
const driver = await Driver.connect(net, wallet)
const connexObj = new Framework(driver)

Sending VET

const txId = await provider.request({
  method: 'eth_sendTransaction',
  params: [{ 
    from: '0x...', 
    to: '0x...', 
    value: '0x...' 
  }]
})

Working with web3.js:

import { ProviderWeb3 } from '@vechain/web3-providers-connex'
import { Web3 } from 'web3' 

const provider = new ProviderWeb3({ connex: connexObj })
const web3 = new Web3(provider)

Working with ethers.js

import * as thor from '@vechain/web3-providers-connex'
import { ethers } from 'ethers'

const provider = thor.ethers.modifyProvider(
  new ethers.BrowserProvider(
    new thor.Provider({ 
      connex: connexObj,
      wallet: walletObj,	// MUST provide to call [getSigner] method 	 
    })
  )
)

Obtaining a signer

const signer = provider.getSigner(address)

Deploying a contract

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

const contractAddress = await base.getAddress()
const contract = new ethers.Contract(contractAddress, abi, signer)

Methods modifyProvider and modifyFactory are used to patch the original code of ethers.js that is incompatible with the Thor protocol.

Request at a particular block hight

APIs eth_getBalance, eth_getCode, eth_getStorageAt and eth_call allow users to specify a particular block height [1]. To do that, we need to provide a Net object when creating a provider:

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

const provider = new thor.Provider({ 
  connex: connexObj,
  net: netObj
})

const web3 = new Web3(
  new thor.ProviderWeb3({ 
    connex: connexObj,
    net: netObj
  })
)

const providerEthers = thor.ethers.modifyProvider(
  new ethers.BrowserProvider(
    new thor.Provider({ 
      connex: connexObj,
      net: netObj
    })
  )
)

Fee delegation

Fee delegation can be enabled by passing the delegator URL when constructing an instance of Provider/ProviderWeb3:

import { Provider } from '@vechain/web3-providers-connex';

const provider = new Provider({
  connex: Obj,
  delegate: {
    url: url-to-delegator
  }
})

or calling enableDelegate:

provider.enableDelegate({ url: url-to-delegator });

You can also disable fee delegation by

provider.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 instead of the transaction sender's account.

You can build your own delegator by implementing VIP201. See /test/web3/feeDelegate.test.ts for a quick demo.

More Examples

More examples can be found in /test/

Supported APIs

eth_accounts

eth_blockNumber

eth_call

eth_estimateGas

eth_gasPrice

Returning 0x0

eth_getBalance

eth_getBlockByNumber

eth_getBlockByHash

eth_chainId

eth_getCode

eth_getLogs

eth_getStorageAt

eth_getTransactionByHash

eth_getTransactionCount

Returning 0x0

eth_getTransactionReceipt

eth_isSyncing

eth_requestAccounts

eth_sendRawTransaction

Requiring passing a Net object when constructing an instance of Provider or ProviderWeb3

eth_sendTransaction

eth_subscribe, eth_unsubscribe

Supported subscription type: newHeads, logs

evm_mine

net_version

Equivalent to eth_chainId

web3_clientVersion

Returning string thor

debug_traceTransaction

debug_traceCall

Implementation Notes

1. Fields blockHash and transactionHash return the values of blockId and transactionId defined in the Thor protocol, respectively
2. APIs eth_estimateGas, eth_call, eth_getTransactionReceipt, debug_traceTransaction and debug_traceCall only return information associated with the first clause in a transaction
3. Unsupported returning fields (all set to zero):

• cumulativeGasUsed
• difficulty
• gasPrice
• logsBloom
• nonce
• sha3Uncles
• totalDifficulty

4. For the default block number options [1], only latest and earliest are supported

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.