zhao-hailei/testrpc

Fast Ethereum RPC client for testing and development

Welcome to testrpc

testrpc is a Node.js based Ethereum client for testing and development. It uses ethereumjs to simulate full client behavior and make developing Ethereum applications much faster. It also includes all popular RPC functions and features (like events) and can be run deterministically to make development a breeze.

INSTALL

testrpc is written in Javascript and distributed as a Node package via npm. Make sure you have Node.js installed, and your environment is capable of installing and compiling npm modules.

npm install -g ethereumjs-testrpc

Using Windows? See our Windows install instructions.

Ubuntu User? Follow the basic instructions for installing Node.js and make sure that you have npm installed, as well as the build-essential apt package (it supplies make which you will need to compile most things). Use the official Node.js packages, do not use the package supplied by your distribution.

Having problems? Be sure to check out the FAQ and if you're still having issues and you're sure its a problem with testrpc please open an issue.

USAGE

Command Line

$ testrpc <options>

Options:

• -a or --accounts: Specify the number of accounts to generate at startup.
• -b or --blocktime: Specify blocktime in seconds for automatic mining. Default is 0 and no auto-mining.
• -d or --deterministic: Generate deterministic addresses based on a pre-defined mnemonic.
• -m or --mnemonic: Use a specific HD wallet mnemonic to generate initial addresses.
• -p or --port: Port number to listen on. Defaults to 8545.
• -h or --hostname: Hostname to listen on. Defaults to Node's server.listen() default.
• -s or --seed: Use arbitrary data to generate the HD wallet mnemonic to be used.
• -g or --gasPrice: Use a custom Gas Price (defaults to 1)
• -l or --gasLimit: Use a custom Gas Limit (defaults to 0x47E7C4)
• -f or --fork: Fork from another currently running Ethereum client at a given block. Input should be the HTTP location and port of the other client, e.g. http://localhost:8545. You can optionally specify the block to fork from using an @ sign: http://localhost:8545@1599200.
• --debug: Output VM opcodes for debugging

You can also specify --account=... (no 's') any number of times passing arbitrary private keys and their associated balances to generate initial addresses:

$ testrpc --account="<privatekey>,balance" [--account="<privatekey>,balance"]

Note that private keys are 64 characters long, and must be input as a 0x-prefixed hex string. Balance can either be input as an integer or 0x-prefixed hex value specifying the amount of wei in that account.

An HD wallet will not be created for you when using --account.

Library

As a Web3 provider:

var TestRPC = require("ethereumjs-testrpc");
web3.setProvider(TestRPC.provider());

As a general http server:

var TestRPC = require("ethereumjs-testrpc");
var server = TestRPC.server();
server.listen(port, function(err, blockchain) {...});

Both .provider() and .server() take a single object which allows you to specify behavior of the TestRPC. This parameter is optional. Available options are:

• "accounts": Array of Object's. Each object should have a balance key with a hexadecimal value. The key secretKey can also be specified, which represents the account's private key. If no secretKey, the address is auto-generated with the given balance. If specified, the key is used to determine the account's address.
• "debug": boolean - Output VM opcodes for debugging
• "logger": Object - Object, like console, that implements a log() function.
• "mnemonic": Use a specific HD wallet mnemonic to generate initial addresses.
• "port": Port number to listen on when running as a server.
• "seed": Use arbitrary data to generate the HD wallet mnemonic to be used.
• "total_accounts": number - Number of accounts to generate at startup.
• "fork": string - Same as --fork option above.
• "time": Date - Date that the first block should start. Use this feature, along with the evm_increaseTime method to test time-dependent code.

IMPLEMENTED METHODS

The RPC methods currently implemented are:

• eth_accounts
• eth_blockNumber
• eth_call
• eth_coinbase
• eth_compileSolidity
• eth_estimateGas
• eth_gasPrice
• eth_getBalance
• eth_getBlockByNumber
• eth_getBlockByHash
• eth_getCode (only supports block number “latest”)
• eth_getCompilers
• eth_getFilterChanges
• eth_getFilterLogs
• eth_getLogs
• eth_getStorageAt
• eth_getTransactionByHash
• eth_getTransactionCount
• eth_getTransactionReceipt
• eth_hashrate
• eth_mining
• eth_newBlockFilter
• eth_newFilter (includes log/event filters)
• eth_sendTransaction
• eth_sendRawTransaction
• eth_sign
• eth_syncing
• eth_uninstallFilter
• net_listening
• net_peerCount
• net_version
• web3_clientVersion
• web3_sha3

There’s also special non-standard methods that aren’t included within the original RPC specification:

• evm_snapshot : Snapshot the state of the blockchain at the current block. Takes no parameters. Returns the integer id of the snapshot created.
• evm_revert : Revert the state of the blockchain to a previous snapshot. Takes a single parameter, which is the snapshot id to revert to. If no snapshot id is passed it will revert to the latest snapshot. Returns true.
• evm_increaseTime : Jump forward in time. Takes one parameter, which is the amount of time to increase in seconds. Returns the total time adjustment, in seconds.
• evm_mine : Force a block to be mined. Takes no parameters.

TESTING

Run tests via:

$ npm test

LICENSE

MPL-2.0