Ganache Ethereum JSON-RPC documentation.
db_getHex(dbName: string, key: string): Promise<string>
Returns binary data from the local database
dbName: string: Database name.key: string: Key name.
Promise<string>: The previously stored data.
db_getString(dbName: string, key: string): Promise<string>
Returns string from the local database
dbName: string: Database name.key: string: Key name.
Promise<string>: The previously stored string.
db_putHex(dbName: string, key: string, data: string): Promise<boolean>
Stores binary data in the local database.
dbName: string: Database name.key: string: Key name.data: string: Data to store.
Promise<boolean>: true if the value was stored, otherwise false.
db_putString(dbName: string, key: string, value: string): Promise<boolean>
Stores a string in the local database.
dbName: string: Database name.key: string: Key name.value: string: String to store.
Promise<boolean>: returns true if the value was stored, otherwise false.
debug_traceTransaction(transactionHash: string, options?: TransactionTraceOptions): Promise<object>
Attempt to run the transaction in the exact same manner as it was executed on the network. It will replay any transaction that may have been executed prior to this one before it will finally attempt to execute the transaction that corresponds to the given hash.
In addition to the hash of the transaction you may give it a secondary optional argument, which specifies the options for this specific call. The possible options are:
disableStorage: {boolean} Setting this totruewill disable storage capture (default =false).disableMemory: {boolean} Setting this totruewill disable memory capture (default =false).disableStack: {boolean} Setting this totruewill disable stack capture (default =false).
transactionHash: stringoptions?: TransactionTraceOptions
Promise<object>: returns comment
// Simple.sol
// // SPDX-License-Identifier: MIT
// pragma solidity ^0.7.4;
//
// contract Simple {
// uint256 public value;
// constructor() payable {
// value = 5;
// }
// }
const simpleSol = "0x6080604052600560008190555060858060196000396000f3fe6080604052348015600f57600080fd5b506004361060285760003560e01c80633fa4f24514602d575b600080fd5b60336049565b6040518082815260200191505060405180910390f35b6000548156fea26469706673582212200897f7766689bf7a145227297912838b19bcad29039258a293be78e3bf58e20264736f6c63430007040033";
const [from] = await provider.request({ method: "eth_accounts", params: [] });
await provider.request({ method: "eth_subscribe", params: ["newHeads"] });
const txHash = await provider.request({ method: "eth_sendTransaction", params: [{ from, gas: "0x5b8d80", data: simpleSol }] });
await provider.once("message"); // Note: `await provider.once` is non-standard
const transactionTrace = await provider.request({ method: "debug_traceTransaction", params: [txHash] });
console.log(transactionTrace);eth_accounts(): Promise<string[]>
Returns a list of addresses owned by client.
Promise<string[]>: Array of 20 Bytes - addresses owned by the client.
eth_blockNumber(): Promise<Quantity>
Returns the number of the most recent block.
Promise<Quantity>: integer of the current block number the client is on.
eth_call(transaction: any, blockNumber: string | Buffer | Tag): Promise<Data>
Executes a new message call immediately without creating a transaction on the block chain.
transaction: anyblockNumber: string | Buffer | Tag
Promise<Data>: the return value of executed contract.
eth_chainId(): Promise<Quantity>
Returns the currently configured chain id, a value used in replay-protected transaction signing as introduced by EIP-155.
Promise<Quantity>: The chain id as a string.
const chainId = await provider.send("eth_chainId");
console.log(chainId);eth_coinbase(): Promise<Address>
Returns the client coinbase address.
Promise<Address>: 20 bytes - the current coinbase address.
eth_estimateGas(transaction: any, blockNumber: Buffer | Tag | string): Promise<Quantity>
Generates and returns an estimate of how much gas is necessary to allow the transaction to complete. The transaction will not be added to the blockchain. Note that the estimate may be significantly more than the amount of gas actually used by the transaction, for a variety of reasons including EVM mechanics and node performance.
transaction: anyblockNumber: Buffer | Tag | string
Promise<Quantity>: the amount of gas used.
eth_gasPrice(): Promise<Quantity>
Returns the current price per gas in wei.
Promise<Quantity>: integer of the current gas price in wei.
eth_getBalance(address: string, blockNumber: Buffer | Tag): Promise<Quantity>
Returns the balance of the account of given address.
address: string: 20 Bytes - address to check for balance.blockNumber: Buffer | Tag: integer block number, or the string "latest", "earliest" or "pending", see the default block parameter
Promise<Quantity>
eth_getBlockByHash(hash: string | Buffer, transactions: boolean): Promise<any>
Returns information about a block by block hash.
hash: string | Buffertransactions: boolean: Boolean - If true it returns the full transaction objects, if false only the hashes of the transactions.
Promise<any>: Block
eth_getBlockByNumber(number: string | Buffer, transactions: boolean): Promise<any>
Returns information about a block by block number.
number: string | Buffer: QUANTITY|TAG - integer of a block number, or the string "earliest", "latest" or "pending", as in the default block parameter.transactions: boolean: Boolean - If true it returns the full transaction objects, if false only the hashes of the transactions.
Promise<any>: the block, null if the block doesn't exist.
eth_getBlockTransactionCountByHash(hash: string | Buffer): Promise<Quantity>
Returns the number of transactions in a block from a block matching the given block hash.
hash: string | Buffer: DATA, 32 Bytes - hash of a block.
Promise<Quantity>
eth_getBlockTransactionCountByNumber(number: string | Buffer): Promise<Quantity>
Returns the number of transactions in a block from a block matching the given block number.
number: string | Buffer: QUANTITY|TAG - integer of a block number, or the string "earliest", "latest" or "pending", as in the default block parameter.
Promise<Quantity>
eth_getCode(address: Buffer, blockNumber: Buffer | Tag): Promise<unknown>
Returns code at a given address.
address: Buffer: 20 Bytes - addressblockNumber: Buffer | Tag: integer block number, or the string "latest", "earliest" or "pending", see the default block parameter
Promise<unknown>: the code from the given address.
eth_getFilterChanges(filterId: string): Promise<Data[]>
Polling method for a filter, which returns an array of logs, block hashes, or transaction hashes, depending on the filter type, which occurred since last poll.
filterId: string: the filter id.
Promise<Data[]>: an array of logs, block hashes, or transaction hashes, depending on the filter type, which occurred since last poll.
eth_getFilterLogs(filterId: string): Promise<object[]>
Returns an array of all logs matching filter with given id.
filterId: string
Promise<object[]>: Array of log objects, or an empty array.
eth_getLogs(filter: FilterArgs): Promise<object[]>
Returns an array of all logs matching a given filter object.
filter: FilterArgs: The filter options
Promise<object[]>: Array of log objects, or an empty array.
eth_getStorageAt(address: string, position: bigint | number, blockNumber: string | Buffer | Tag): Promise<Data>
Returns the value from a storage position at a given address.
address: stringposition: bigint | numberblockNumber: string | Buffer | Tag: integer block number, or the string "latest", "earliest" or "pending", see the default block parameter
Promise<Data>
eth_getTransactionByBlockHashAndIndex(hash: string | Buffer, index: string): Promise<any>
Returns information about a transaction by block hash and transaction index position.
hash: string | Buffer: DATA, 32 Bytes - hash of a block.index: string: QUANTITY - integer of the transaction index position.
Promise<any>
eth_getTransactionByBlockNumberAndIndex(number: string | Buffer, index: string): Promise<any>
Returns information about a transaction by block number and transaction index position.
number: string | Buffer: QUANTITY|TAG - a block number, or the string "earliest", "latest" or "pending", as in the default block parameter.index: string: QUANTITY - integer of the transaction index position.
Promise<any>
eth_getTransactionByHash(transactionHash: string): Promise<object>
Returns the information about a transaction requested by transaction hash.
transactionHash: string: 32 Bytes - hash of a transaction
Promise<object>
eth_getTransactionCount(address: string, blockNumber: Buffer | Tag): Promise<Quantity>
Returns the number of transactions sent from an address.
address: stringblockNumber: Buffer | Tag: integer block number, or the string "latest", "earliest" or "pending", see the default block parameter
Promise<Quantity>: integer of the number of transactions sent from this address.
eth_getTransactionReceipt(transactionHash: string): Promise<object>
Returns the receipt of a transaction by transaction hash.
Note That the receipt is not available for pending transactions.
transactionHash: string: 32 Bytes - hash of a transaction
Promise<object>: Returns the receipt of a transaction by transaction hash.
eth_getUncleByBlockHashAndIndex(hash: Data, index: Quantity): Promise<any>
Returns information about a uncle of a block by hash and uncle index position.
hash: Data: hash of a blockindex: Quantity: the uncle's index position.
Promise<any>
eth_getUncleByBlockNumberAndIndex(blockNumber: Buffer | Tag, uncleIndex: Quantity): Promise<any>
Returns information about a uncle of a block by hash and uncle index position.
blockNumber: Buffer | Tag: a block number, or the string "earliest", "latest" or "pending", as in the default block parameter.uncleIndex: Quantity: the uncle's index position.
Promise<any>
eth_getUncleCountByBlockHash(hash: string | Buffer): Promise<Quantity>
Returns the number of uncles in a block from a block matching the given block hash.
hash: string | Buffer: DATA, 32 Bytes - hash of a block.
Promise<Quantity>
eth_getUncleCountByBlockNumber(number: string | Buffer): Promise<Quantity>
Returns the number of uncles in a block from a block matching the given block hash.
number: string | Buffer
Promise<Quantity>
eth_getWork(filterId: Quantity): Promise<[] | [string, string, string]>
Returns: An Array with the following elements 1: DATA, 32 Bytes - current block header pow-hash 2: DATA, 32 Bytes - the seed hash used for the DAG. 3: DATA, 32 Bytes - the boundary condition ("target"), 2^256 / difficulty.
filterId: Quantity: A filter id
Promise<[] | [string, string, string]>: the hash of the current block, the seedHash, and the boundary condition to be met ("target").
eth_hashrate(): Promise<Quantity>
Returns the number of hashes per second that the node is mining with.
Promise<Quantity>: number of hashes per second.
eth_mining(): Promise<boolean>
Returns true if client is actively mining new blocks.
Promise<boolean>: returns true if the client is mining, otherwise false.
eth_newBlockFilter(): Promise<Quantity>
Creates a filter in the node, to notify when a new block arrives. To check
if the state has changed, call eth_getFilterChanges.
Promise<Quantity>: A filter id.
eth_newFilter(filter: RangeFilterArgs): Promise<Quantity>
Creates a filter object, based on filter options, to notify when the state
changes (logs). To check if the state has changed, call
eth_getFilterChanges.
If the from fromBlock or toBlock option are equal to "latest" the
filter continually append logs for whatever block is seen as latest at the
time the block was mined, not just for the block that was "latest" when the
filter was created.
A note on specifying topic filters:
Topics are order-dependent. A transaction with a log with topics [A, B] will be matched by the following topic filters:
[]“anything”[A]“A in first position (and anything after)”[null, B]“anything in first position AND B in second position (and anything after)”[A, B]“A in first position AND B in second position (and anything after)”[[A, B], [A, B]]“(A OR B) in first position AND (A OR B) in second position (and anything after)”
filter: RangeFilterArgs: The filter options
Promise<Quantity>
eth_newPendingTransactionFilter(): Promise<Quantity>
Creates a filter in the node, to notify when new pending transactions
arrive. To check if the state has changed, call eth_getFilterChanges.
Promise<Quantity>: A filter id.
eth_protocolVersion(): Promise<Data>
Returns the current ethereum protocol version.
Promise<Data>: The current ethereum protocol version.
eth_sendRawTransaction(transaction: string): Promise<Data>
Creates new message call transaction or a contract creation for signed transactions.
transaction: string
Promise<Data>: The transaction hash
eth_sendTransaction(transaction: any): Promise<Data>
Creates new message call transaction or a contract creation, if the data field contains code.
transaction: any
Promise<Data>: The transaction hash
eth_sign(address: string | Buffer, message: string | Buffer): Promise<string>
The sign method calculates an Ethereum specific signature with:
sign(keccak256("\x19Ethereum Signed Message:\n" + message.length + message))).
By adding a prefix to the message makes the calculated signature recognizable as an Ethereum specific signature. This prevents misuse where a malicious DApp can sign arbitrary data (e.g. transaction) and use the signature to impersonate the victim.
Note the address to sign with must be unlocked.
address: string | Buffermessage: string | Buffer
Promise<string>: Signature
eth_signTypedData(address: string | Buffer, typedData: TypedData): Promise<string>
address: string | Buffer: Address of the account that will sign the messages.typedData: TypedData: Typed structured data to be signed.
Promise<string>: Signature. As in eth_sign, it is a hex encoded 129 byte array
starting with 0x. It encodes the r, s, and v parameters from
appendix F of the yellow paper
in big-endian format. Bytes 0...64 contain the r parameter, bytes
64...128 the s parameter, and the last byte the v parameter. Note
that the v parameter includes the chain id as specified in EIP-155.
eth_submitHashrate(hashRate: string, clientID: string): Promise<boolean>
Used for submitting mining hashrate.
hashRate: string: a hexadecimal string representation (32 bytes) of the hash rateclientID: string: A random hexadecimal(32 bytes) ID identifying the client
Promise<boolean>: true if submitting went through succesfully and false otherwise.
eth_submitWork(nonce: Data, powHash: Data, digest: Data): Promise<boolean>
Used for submitting a proof-of-work solution
nonce: Data: The nonce found (64 bits)powHash: Data: The header's pow-hash (256 bits)digest: Data: The mix digest (256 bits)
Promise<boolean>: true if the provided solution is valid, otherwise false.
eth_subscribe(subscriptionName: SubscriptionName): PromiEvent<Quantity>
Starts a subscription to a particular event. For every event that matches the subscription a JSON-RPC notification with event details and subscription ID will be sent to a client.
subscriptionName: SubscriptionName
PromiEvent<Quantity>: A subscription id.
eth_syncing(): Promise<boolean>
Returns an object with data about the sync status or false.
Promise<boolean>: An object with sync status data or false, when not syncing: startingBlock: {bigint} - The block at which the import started (will only be reset, after the sync reached his head) currentBlock: {bigint} - The current block, same as eth_blockNumber highestBlock: {bigint} - The estimated highest block
eth_uninstallFilter(filterId: string): Promise<boolean>
Uninstalls a filter with given id. Should always be called when watch is no longer needed.
filterId: string: the filter id.
Promise<boolean>: true if the filter was successfully uninstalled, otherwise
false.
eth_unsubscribe(subscriptionId: SubscriptionId): Promise<boolean>
subscriptionId: SubscriptionId
Promise<boolean>
evm_increaseTime(seconds: number | string): Promise<number>
Jump forward in time by the given amount of time, in seconds.
seconds: number | string: Must be greater than or equal to0
Promise<number>: Returns the total time adjustment, in seconds.
evm_lockUnknownAccount(address: string): Promise<boolean>
Locks any unknown account.
Note: accounts known to the personal namespace and accounts returned by
eth_accounts cannot be locked using this method.
address: string: address the address of the account to lock
Promise<boolean>: true if the account was locked successfully, false if the
account was already locked. Throws an error if the account could not be
locked.
evm_mine(timestamp?: number): Promise<"0x0">
Force a single block to be mined.
Mines a block independent of whether or not mining is started or stopped. Will mine an empty block if there are no available transactions to mine.
timestamp?: number: the timestamp the block should be mined with. EXPERIEMENTAL: Optionally, specify anoptionsobject withtimestampand/orblocksfields. Ifblocksis given, it will mine exactlyblocksnumber of blocks, regardless of any other blocks mined or reverted during it's operation. This behavior is subject to change!
Promise<"0x0">: The string "0x0". May return additional meta-data in the future.
await provider.send("evm_mine", Date.now());console.log("start", await provider.send("eth_blockNumber"));
await provider.send("evm_mine", [{blocks: 5}]); // mines 5 blocks
console.log("end", await provider.send("eth_blockNumber"));evm_revert(snapshotId: string | number): Promise<boolean>
Revert the state of the blockchain to a previous snapshot. Takes a single parameter, which is the snapshot id to revert to. This deletes the given snapshot, as well as any snapshots taken after (Ex: reverting to id 0x1 will delete snapshots with ids 0x1, 0x2, etc... If no snapshot id is passed it will revert to the latest snapshot.
snapshotId: string | number: the snapshot id to revert
Promise<boolean>: true if a snapshot was reverted, otherwise false
const snapshotId = await provider.send("evm_snapshot");
const isReverted = await provider.send("evm_revert", [snapshotId]);const provider = ganache.provider();
const [from, to] = await provider.send("eth_accounts");
const startingBalance = BigInt(await provider.send("eth_getBalance", [from]));
// take a snapshot
const snapshotId = await provider.send("evm_snapshot");
// send value to another account (over-simplified example)
await provider.send("eth_subscribe", ["newHeads"]);
await provider.send("eth_sendTransaction", [{from, to, value: "0xffff"}]);
await provider.once("message"); // Note: `await provider.once` is non-standard
// ensure balance has updated
const newBalance = await provider.send("eth_getBalance", [from]);
assert(BigInt(newBalance) < startingBalance);
// revert the snapshot
const isReverted = await provider.send("evm_revert", [snapshotId]);
assert(isReverted);
const endingBalance = await provider.send("eth_getBalance", [from]);
assert.strictEqual(BigInt(endingBalance), startingBalance);evm_setAccountNonce(address: string, nonce: string): Promise<boolean>
Sets the given account's nonce to the specified value. Mines a new block before returning.
Warning: this will result in an invalid state tree.
address: stringnonce: string
Promise<boolean>: true if it worked
evm_setStorageAt(address: string, position: bigint | number, storage: string, blockNumber: string | Buffer | Tag): Promise<unknown>
address: stringposition: bigint | numberstorage: stringblockNumber: string | Buffer | Tag
Promise<unknown>
evm_setTime(time: string | Date | number): Promise<number>
Sets the internal clock time to the given timestamp.
Warning: This will allow you to move backwards in time, which may cause new blocks to appear to be mined before old blocks. This is will result in an invalid state.
time: string | Date | number
Promise<number>: The amount of seconds between the given timestamp and now.
evm_snapshot(): Promise<Quantity>
Snapshot the state of the blockchain at the current block. Takes no
parameters. Returns the id of the snapshot that was created. A snapshot can
only be reverted once. After a successful evm_revert, the same snapshot
id cannot be used again. Consider creating a new snapshot after each
evm_revert if you need to revert to the same point multiple times.
Promise<Quantity>: The hex-encoded identifier for this snapshot
const snapshotId = await provider.send("evm_snapshot");const provider = ganache.provider();
const [from, to] = await provider.send("eth_accounts");
const startingBalance = BigInt(await provider.send("eth_getBalance", [from]));
// take a snapshot
const snapshotId = await provider.send("evm_snapshot");
// send value to another account (over-simplified example)
await provider.send("eth_subscribe", ["newHeads"]);
await provider.send("eth_sendTransaction", [{from, to, value: "0xffff"}]);
await provider.once("message"); // Note: `await provider.once` is non-standard
// ensure balance has updated
const newBalance = await provider.send("eth_getBalance", [from]);
assert(BigInt(newBalance) < startingBalance);
// revert the snapshot
const isReverted = await provider.send("evm_revert", [snapshotId]);
assert(isReverted);
const endingBalance = await provider.send("eth_getBalance", [from]);
assert.strictEqual(BigInt(endingBalance), startingBalance);evm_unlockUnknownAccount(address: string, duration: number): Promise<boolean>
Unlocks any unknown account.
address: string: address the address of the account to unlockduration: number: (default: disabled) Duration in seconds how long the account should remain unlocked for. Set to 0 to disable automatic locking.
Promise<boolean>: true if the account was unlocked successfully, false if the
account was already unlocked. Throws an error if the account could not be
unlocked.
miner_setEtherbase(address: string): Promise<boolean>
Sets the etherbase, where mining rewards will go.
address: string
Promise<boolean>
miner_setExtra(extra: string): Promise<boolean>
Set the extraData block header field a miner can include.
extra: string
Promise<boolean>
miner_setGasPrice(number: string): Promise<boolean>
number: string: Sets the minimal accepted gas price when mining transactions. Any transactions that are below this limit are excluded from the mining process.
Promise<boolean>
miner_start(threads: number): Promise<boolean>
Resume the CPU mining process with the given number of threads.
Note: threads is ignored.
threads: number
Promise<boolean>: true
net_listening(): Promise<boolean>
Returns true if client is actively listening for network connections.
Promise<boolean>: true when listening, otherwise false.
net_peerCount(): Promise<Quantity>
Returns number of peers currently connected to the client.
Promise<Quantity>: integer of the number of connected peers.
net_version(): Promise<string>
Returns the current network id.
Promise<string>: The current network id. This value should NOT be JSON-RPC Quantity/Data encoded.
personal_importRawKey(rawKey: string, passphrase: string): Promise<Address>
Imports the given unencrypted private key (hex string) into the key store, encrypting it with the passphrase.
rawKey: stringpassphrase: string
Promise<Address>
the address of the new account.
personal_listAccounts(): Promise<string[]>
Returns all the Ethereum account addresses of all keys that have been added.
Promise<string[]>: the Ethereum account addresses of all keys that have been added.
personal_lockAccount(address: string): Promise<boolean>
Locks the account. The account can no longer be used to send transactions.
address: string
Promise<boolean>
personal_newAccount(passphrase: string): Promise<Address>
Generates a new account with private key. Returns the address of the new account.
passphrase: string
Promise<Address>: The new account's address
personal_sendTransaction(transaction: any, passphrase: string): Promise<Data>
Validate the given passphrase and submit transaction.
The transaction is the same argument as for eth_sendTransaction and contains the from address. If the passphrase can be used to decrypt the private key belogging to tx.from the transaction is verified, signed and send onto the network. The account is not unlocked globally in the node and cannot be used in other RPC calls.
transaction: anypassphrase: string
Promise<Data>
personal_unlockAccount(address: string, passphrase: string, duration: number): Promise<boolean>
Unlocks the account for use.
The unencrypted key will be held in memory until the unlock duration expires. The unlock duration defaults to 300 seconds. An explicit duration of zero seconds unlocks the key until geth exits.
The account can be used with eth_sign and eth_sendTransaction while it is unlocked.
address: string: 20 Bytes - The address of the account to unlock.passphrase: string: Passphrase to unlock the account.duration: number: (default: 300) Duration in seconds how long the account should remain unlocked for. Set to 0 to disable automatic locking.
Promise<boolean>: true if it worked. Throws an error if it did not.
shh_addToGroup(address: string): Promise<boolean>
Adds a whisper identity to the group
address: string
Promise<boolean>: true if the identity was successfully added to the group, otherwise false.
shh_getFilterChanges(id: string): Promise<any[]>
Polling method for whisper filters. Returns new messages since the last call of this method.
id: string: The filter id. Ex: "0x7"
Promise<any[]>: More Info: https://github.com/ethereum/wiki/wiki/JSON-RPC#shh_getfilterchanges
shh_getMessages(id: string): Promise<boolean>
Get all messages matching a filter. Unlike shh_getFilterChanges this returns all messages.
id: string: The filter id. Ex: "0x7"
Promise<boolean>: See: shh_getFilterChanges
shh_hasIdentity(address: string): Promise<boolean>
Checks if the client hold the private keys for a given identity.
address: string: The identity address to check.
Promise<boolean>: returns true if the client holds the privatekey for that identity, otherwise false.
shh_newFilter(to: string, topics: any[]): Promise<boolean>
Creates filter to notify, when client receives whisper message matching the filter options.
to: string: - ^(optional) Identity of the receiver. When present it will try to decrypt any incoming message if the client holds the private key to this identity.topics: any[]: Array of DATA topics which the incoming message's topics should match.
Promise<boolean>: returns true if the identity was successfully added to the group, otherwise false.
shh_newGroup(): Promise<string>
Creates a new group.
Promise<string>: the address of the new group.
shh_newIdentity(): Promise<string>
Creates new whisper identity in the client.
Promise<string>: result - the address of the new identiy.
shh_post(postData: WhisperPostObject): Promise<boolean>
Creates a whisper message and injects it into the network for distribution.
postData: WhisperPostObject
Promise<boolean>: returns true if the message was sent, otherwise false.
shh_uninstallFilter(id: string): Promise<boolean>
Uninstalls a filter with given id. Should always be called when watch is no longer needed. Additonally Filters timeout when they aren't requested with shh_getFilterChanges for a period of time.
id: string: The filter id. Ex: "0x7"
Promise<boolean>: true if the filter was successfully uninstalled, otherwise false.
shh_version(): Promise<string>
Returns the current whisper protocol version.
Promise<string>: The current whisper protocol version
web3_clientVersion(): Promise<string>
Returns the current client version.
Promise<string>: The current client version.