âš WARNING: This library has been deprecated.
Most users do not need near-web3-provider, and instead should simply change their Web3 endpoint as documented at: https://doc.aurora.dev/develop/networks
NEAR Protocol Web3 provider. Use it to connect your Ethereum frontend or Truffle to NEAR Protocol.
Node > 11.0
$ npm install near-web3-providerTests require running a local nearcore.
Install Rustup:
$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
Add wasm target to your toolchain:
$ rustup target add wasm32-unknown-unknown
Install and run NEARCore using Docker:
$ git clone https://github.com/nearprotocol/nearcore
$ cd nearcore
$ cargo build -p neard --release
$ ./target/release/neard --home=~/.near/local init
$ ./target/release/neard --home=~/.near/local run
Build test environment:
# grant executable access to build.sh if not yet done
chmod +x test/build.sh
# build solidity contracts
# necessary on first ever test run then update build per contract changes
cd test && ./build.sh && cd ..Run tests
$ npm run test
Tests currently take ~50 seconds to run.
The web3 Provider also needs to be tested against the near-evm contract.
Follow the testing instructions on the near-evm repo.
If you're developing against an in-flux contract, make sure to build the wasm code from near-evm and update the wasm code for the provider: test/artifacts/near_evm.wasm.
You can use this provider wherever a Web3 provider is needed.
const { NearProvider, nearlib, nearWeb3Extensions } = require('near-web3-provider');
const nearNetworkId = '<local, default, test, etc>'; // default is 'default'
const accountId = '<account id to use for tx>';
const keyStore = new nearlib.keyStores.<one of keyStores>;
const web = new Web3();
web.extend(nearWeb3Extensions(web)) // extend web3 to include customized near methods
web.setProvider(new NearProvider("<url to NEAR RPC>", keyStore, accountId, nearNetworkId));
web.eth.net.isListening();Add to your truffle-config.js:
// Import NearProvider and nearlib
const { NearProvider, nearlib } = require('near-web3-provider');
// Specify which NEAR network to use
const nearNetworkId = '<local, default, test, etc>';
// If developing against a local node, use http://localhost:3030
const url = 'https://rpc.nearprotocol.com';
// Specify where to store keys
const keyDir = 'neardev';
// Use standard near-shell structure for storing keys. See note below for other options.
const keyStore = new nearlib.keyStores.UnencryptedFileSystemKeyStore(keyDir);
// Account ID
const accountId = 'test.account';
module.exports = {
networks: {
near: {
network_id: "99",
skipDryRun: true,
provider: function() {
return new NearProvider(url, keyStore, accountId, nearNetworkId)
},
}
}
}See key store documentation for other options.
NEAR Protocol is a sharded, proof-of-stake blockchain. Keeping that in mind, some Ethereum concepts are naturally not shared with NEAR; for example, there is no concept of uncle blocks, pending blocks, or block difficulty.
As a sharded blockchain, the structure of NEAR blocks is also different. In Ethereum, blocks have transactions. In NEAR, blocks have chunks, and chunks have transactions.
near-web3-provider has been adapted to follow the Ethereum JSON RPC API and its web3 equivalents as closely as possible. Where there are no equivalents, empty values have been passed through. Other return values have been adapted to account for the difference in block structure (for example, the root of the transaction trie comes from a chunk rather than a block).
Mining, hashrates, ssh, and db methods are not supported.
-
Methods that have an extra default block parameter will function as
latest, regardless of the actual argument. This is a Near RPC limitation. -
eth_calldoes not supportfromorvaluearguments. This is a Near RPC limitation. -
eth_estimateGaswill always return0x0. Near RPC does not seem to support gas estimation for calls. -
Some fields in Ethereum data structures do not have a direct correspondence to Near data structures, therefore these fields are unimplemented or unreliable. Always consult implementation in near_to_eth_objects.js. Examples include:
- The tx receipts
statusfield is always0x1, regardless of the success of the transaction. transactionIndexis constant, and not reliable.
- The tx receipts
-
Some calls, like
eth_getTransactionByBlockHashAndIndexhave no sensible correspondence to Near block structure. -
Near doesn't keep track of nonces for contracts which is a required feature for the evm. Therefore both an evm nonce and near nonce exist for each account.
eth_getTransactionCountwill return a reference to the evm nonce. All other nonce fields in the web3-near-provider reference the near nonce.- evm nonce: nonce used for address calculation in the next EVM contract deployment from this EVM account
- near nonce: number of all near transactions (including evm transactions) executed by account
Unless specified, NearProvider returns the values specified in the web3 documentation for each method.
If a method has no direct translation, an Unsupported method error is returned.
Near uses base58 while Ethereum uses Keccak. This necessitates the need to convert between the two. With the exception of transaction hashes, Near hashes are converted to Ethereum-compatible hashes when using web3.
-
blockHash- a block hash is the hash equivalent of a Near block hash- denoted in
hexwithin the context of the near-web3-provider - denoted in
base58within the context of the rest of the near protocol
- denoted in
-
transactionHash- a transaction hash is the combination of a Near transaction hash (inbase58) concatenated with the accountId of the transaction's sender, and separated by:<base58TxHash>:<senderAccountId>within the context of the near-web3-provider<senderAccountId>:<base58TxHash>within the context of the rest of the near protocol
-
gas- Gas is denominated in yoctoNEAR -
value- Transaction values/amounts are denominated in yoctoNEAR -
to,from,address- Addresses are the EVM hash of a Near AccountId
web3.near.retrieveNear([transactionObject])
Transfers yoctoNEAR from evmAccount out of the evm to near account.
-
Object- the transaction object to send:to-String: near accountId to receive yoctoNEARvalue-Number|String|BN|BigNumber: amount of yoctoNEAR to attachgas-Number: amount of gas to use for the transaction in yoctoNEAR
Returns the transactionHash of the transaction: <base58TxHash>:<accountId>
web3.near.transferNear([transactionObject])
Transfers yoctoNEAR from sending evmAccount to the evmAccount corresponding to near accountId recipient (to)
-
Object- the transaction object to send:to-String: near accountId to receive yoctoNEAR to their corresponding evm addressvalue-Number|String|BN|BigNumber: amount of yoctoNEAR to attachgas-Number: amount of gas to use for the transaction in yoctoNEAR
Returns the transactionHash of the transaction: <base58TxHash>:<accountId>
web3.utils.hexToBase58(hexVal)
Converts hex value into base58 value. blockHash is represented in hex in the context of web3.eth functionality but represented within the near protocol as base58
Stringhex- valid with or without0xprepended
Returns String base58
web3.utils.base58ToHex(base58Val)
Converts base58 value into hex value. blockHash is represented in hex in the context of web3.eth functionality but represented within the near protocol as base58
Stringbase58
Returns String hex - prepended with 0x
web3.eth.getCoinbaseweb3.eth.isMiningweb3.eth.getHashrateweb3.eth.getBlockUncleCountweb3.eth.getUncleweb3.eth.getPendingTransactionsweb3.eth.signweb3.eth.estimateGasweb3.eth.getPastLogsweb3.eth.getWorkweb3.eth.submitWorkweb3.eth.requestAccountsweb3.eth.getChainIdweb3.eth.getNodeInfoweb3.eth.getProof
web3.eth.getProtocolVersion([callback])
Returns the Near protocol version of the node.
Promise returns String: the protocol version.
- Returns the Near protocol version instead of the Ethereum protocol version
web3.eth.isSyncing
Checks if the node is currently syncing and returns either a syncing object, or false.
Promise returns Object|Boolean - a syncing object, or false.
startingBlock- Unsupported, returns0x0currentBlock- Returns the latest block heighthighestBlock- Returns the latest block heightknownStates- Unsupported, returns0x0pulledStates- Unsupported, returns0x0
- This will almost always return
false - If a syncing object does return, the values are generally not useful
web3.eth.getGasPrice()
Returns the current gas price in yoctoNEAR.
Promise returns String - Number string of the current gas price in yoctoNEAR.
- The gas price is returned in yoctoNEAR instead of wei
- At the moment, the gas price is determined from the most recent block. web3 typically determines the gas price by the last few blocks median gas price.
web3.eth.getAccounts()
Returns a list of accounts the node controls.
Promise returns Array - An array of addresses controlled by node.
- Addresses are the EVM hash of a Near AccountId
web3.eth.getBlockNumber()
Returns the current block number
Promise returns Number - The number of the most recent block.
web3.eth.getBalance(address)
Returns the balance of an address.
Stringaddress- The address to get the balance of. This is the EVM address equivalent of a Near AccountId
Promise returns String - The current balance for the given address in yoctoNEAR.
- Due to Near RPC limitations, the balance of the address will always be from the latest block.
- Address is the EVM hash of a Near AccountId
web3.eth.getStorageAt(address, position)
Get the storage at a specific position of an address.
Stringaddress- The address to get the storage from. This is the EVM address equivalent of a Near AccountIdNumber|String|BN|BigNumberposition- the index position of the storage
Promise returns String - The value in storage at the given position.
- Due to Near RPC limitations, the balance of the address will always be from the latest block.
- Address is the EVM hash of a Near AccountId
web3.eth.getCode(address)
Get the code at a specific address
Stringaddress- The address to get the code from.
Promise returns String - The data at given address address.
- Due to Near RPC limitations, the balance of the address will always be from the latest block.
- Address is the EVM hash of a Near AccountId
web3.eth.getBlock(blockHashOrBlockNumber [, returnTransactionObjects])
Returns a block matching the block number or block hash
String|Number|BN|BigNumber- The block number or block hash. Or the string'genesis','latest','earliest', or'pending'Boolean- (optional, defaultfalse) If specifiedtrue, the returned block will contain all transactions as objects. By default it isfalseso, there is no need to explicitly specify false. And, iffalseit will only contain the transaction hashes.
Promise returns Object - The block object
number- The block numberhash- Hash equivalent of the base58 Near block hashparentHash- Hash equivalent of the base58 Near block's parent block hashnonce- Always returnsnull. This is typically the hash of the generated proof-of-work. There is no equivalent concept in Near.transactionsRoot- Always returns0x0000.... Since transactions are on chunks and chunks are on block, there is no equivalent of a transaction trie of the blocksize- Returns the weight of the blockgasLimit- The maximum gas allowed in this block. Returned in yoctoNEARgasUsed- The total used gas by all chunks in this block. A chunk may have a transaction, but that transaction may be processed in a different chunk.timestamp- The unix timestamp for when the block was collatedtransactions- Array of transaction objects, or the 32 byte transaction hashes equivalent of the base58 Near transaction hashes.sha3Uncles- Unsupported, undefined/null value returnedlogsBloom- Unsupported, undefined/null value returnedstateRoot- Unsupported, undefined/null value returnedminer- Unsupported, undefined/null value returneddifficulty- Unsupported, undefined/null value returnedtotalDifficulty- Unsupported, undefined/null value returnedextraData- Unsupported, undefined/null value returneduncles- Unsupported, undefined/null value returned
- Passing through
'genesis'or'earliest'will return block 0 - Passing through
'latest'or'pending'will return the latest block. There is no concept of pending blocks. - See Important Format Changes for information on
hash,gas,transactions
web3.eth.getBlockTransactionCount(blockHashOrBlockNumber)
Returns the number of transactions in a given block.
{String|Number|BN|BigNumber}- The block number or block hash. Or the string'genesis','latest','earliest', or'pending'
Promise returns Number - The number of transactions in the given block.
- Blocks have chunks and chunks have transactions; all the transactions are collected from a block's chunks and counted. Conceptually this is the same thing, but note that transactions do not actually reside in blocks.
web3.eth.getTransaction(transactionHash)
Returns a transaction matching the given transaction hash.
StringtransactionHash- the transaction hash
Promise returns Object - A transaction object
hash- Hash of the transaction<nearTxHash>:<accountId>(transaction's sender's accountId)nonce- The total number of near transactions made by the sender prior to this oneblockHash- hash equivalent of the block where this transaction was in (represented in hex instead of near's base58 format)blockNumber- Block number where this transaction was intransactionIndex- integer of the transactions index position in the blockfrom- EVM Address of the senderto- EVM address of the receivervalue- Value transferred in yoctoNEARgasPrice- Gas price set by the block in yoctoNEARgas- Gas consumed by the sender in yoctoNEARinput- tx data, encoded contract call or deployed bytecode
-
Due to the Near protocol, getting a transaction's status requires knowing both the transaction hash and the Near AccountId of the transaction's signer. To allow for this, transaction hashes in NearProvider are the base58 transaction hashes concatenated with the
signer_idof the transaction, and separated with a:.Example:
// A Near transaction hash (base58) const nearTxHash = 'ByGDjvYxVZDxv69c86tFCFDRnJqK4zvj9uz4QVR4bH4P'; // A Near AccountId. In particular, the AccountId of the transaction's signer const signerId = 'test.near' // Concatenate and separate with ':' const txHash = `${nearTxHash}:${signerId}; console.log(txHash); // ByGDjvYxVZDxv69c86tFCFDRnJqK4zvj9uz4QVR4bH4P:test.near -
See Important Format Changes for additional information.
web3.eth.getTransactionFromBlock(hashStringOrNumber, indexNumber)
Returns a transaction based on a block hash or number and the transaction's index position.
{String|Number|BN|BigNumber}hashStringOrNumberThe block number or block hash. Or the string'genesis','latest','earliest', or'pending'{Number}indexNumber- The transaction's index position
Promise returns Object - A transaction object. See web3.eth.getTransaction.
web3.eth.getTransactionReceipt(hash)
Returns the receipt of a transaction by transaction hash.
StringtransactionHash- the transaction hash. See web3.eth.getTransaction.
Promise returns Object - A transaction receipt object
status- Returnstrueif the transaction was successful,falseif the EVM reverted the transactionblockHashHash of the block where this transaction was in.blockNumber- Block number where this transaction was in.transactionHash- Hash of the transaction.transactionIndex- Integer of the transactions index position in the block.from- Address of the sender.to- Address of the receiver. null when its a contract creation transaction.contractAddress- The contract address created, if the transaction was a contract creation, otherwise null.cumulativeGasUsed- The total amount of gas used when this transaction was executed in the block.gasUsed- The amount of gas used by this specific transaction alone.logs- Array of log objects, which this transaction generated.
web3.eth.getTransactionCount(address)
Get the numbers of transactions sent from this address.
Stringaddress- The address to get the numbers of transactions from. Address is the EVM address of a Near AccountId
Promise returns Number - The total number of evm transactions sent from the given address
- Specifically, returns the nonce of evm transactions sent from the address. Near will only return the total transactions; selecting a block is not supported
- The return value refers to the total number of evm transactions not including near transactions outside the evm. All other transaction count nonces refer to total near transactions (which include evm transcations)
web3.eth.sendTransaction(transactionObject)Sends a transaction to the network.
-
Object- the transaction object to send:to-String: EVM destination addressvalue-Number|String|BN|BigNumber: amount of yoctoNEAR to attachgas-Number: amount of gas to use for the transaction in yoctoNEARdata-String: the encoded call data
Returns the transactionHash of the transaction: <base58TxHash>:<accountId>
- The sender is the default accountId. At this time, another account cannot be specified.
- All other optional properties on the transaction object are unsupported
Unsupported at the moment, always returns 0x0.
web3.eth.signTransaction(transactionObject)
Executes a new message call immediately without creating a transaction on the block chain.
Object- A transaction object, see web3.eth.sendTransaction, with the difference that only thetofield is required.
Promise returns String: The returned data of the call, e.g. a smart contract functions return value.
- Due to Near RPC limitations, this will always be called on the latest block.
- Update hardcoded
transactionIndex - Make sure all errors are handled
- Expose
utils.nearAccountToEvmAddress, otherwise users will not be able to pass through the EVM Address equivalent - Expose conversion utils like
base58ToHex,hexToBase58 - Add documentation about accessing provider methods (point to Near docs, explain relevant methods)