To make your Ðapp work with on Ethereum, you can use the web3
object provided by the web3.js library. Under the hood it communicates to a local node through RPC calls. web3.js works with AlethZero, geth and Mist, and also in an external browser if one of the former nodes are running locally.
web3
contains the eth
object - web3.eth
(for specifically Ethereum blockchain interactions) and the shh
object - web3.shh
(for Whisper interaction). Over time we'll introduce other objects for each of the other web3 protocols.
As this API is designed to work with a local RPC node and all its functions are by default use synchronous HTTP requests.
If you want to make asynchronous request, you can pass an optional callback as the last parameter to most functions. All callbacks are using an error first callback style:
web3.eth.getBlock(48, function(error, result){
if(!error)
console.log(result)
else
console.error(error);
})
You will always get a BigNumber object for balance values as JavaScript is not able to handle big numbers correctly. Look at the following examples:
"101010100324325345346456456456456456456"
// "101010100324325345346456456456456456456"
101010100324325345346456456456456456456
// 1.0101010032432535e+38
web3.js depends on the BigNumber Library and adds it automatically.
var balance = new BigNumber('131242344353464564564574574567456');
// or var balance = web3.eth.getBalance(someAddress);
balance.plus(21).toString(10); // toString(10) converts it to a number string
// "131242344353464564564574574567477"
The next example wouldn't work as we have more than 20 floating points, therefore it is recommended to keep you balance always in wei and only transform it to other units when presenting to the user:
var balance = new BigNumber('13124.234435346456466666457455567456');
balance.plus(21).toString(10); // toString(10) converts it to a number string, but can only show max 20 floating points
// "13145.23443534645646666646" // you number would be cut after the 20 floating point
The web3
object provides all methods.
var web3 = require('web3')
web3.version.api
String
- The ethereum js api version.
var version = web3.version.api;
console.log(api); // "0.2.0"
web3.version.client
String
- The client/node version.
var version = web3.version.client;
console.log(version); // "Mist/v0.9.3/darwin/go1.4.1"
web3.version.network
String
- The network protocol version.
var version = web3.version.network;
console.log(version); // 54
web3.version.ethereum
String
- The ethereum protocol version.
var version = web3.version.ethereum;
console.log(version); // 60
web3.version.whisper
String
- The whisper protocol version.
var version = web3.version.whisper;
console.log(version); // 20
web3.setProvider(providor)
Should be called to set provider.
none
undefined
web3.setProvider(new web3.providers.HttpProvider('http://localhost:8545')); // 8080 for cpp/AZ, 8545 for go/mist
// or
web3.setProvider(new web3.providers.QtSyncProvider());
web3.reset()
Should be called to reset state of web3. Resets everything except manager. Uninstalls all filters. Stops polling.
none
undefined
web3.reset();
web3.sha3(string [, callback])
String
- The string to hash using the SHA3 algorithmFunction
- (optional) If you pass a callback the HTTP request is made asynchronous. See this note for details.String
- The SHA3 of the given data.
var str = web3.sha3("Some ASCII string to be hashed");
console.log(str); // "0x536f6d6520415343494920737472696e6720746f20626520686173686564"
var hash = web3.sha3(str);
console.log(hash); // "0xb21dbc7a5eb6042d91f8f584af266f1a512ac89520f43562c6c1e37eab6eb0c4"
web3.toHex(mixed);
Converts any value into HEX.
String|Number|Object|Array|BigNumber
- The value to parse to HEX. If its an object or array it will be JSON.stringify
first. If its a BigNumber it will make it the HEX value of a number.String
- The hex string of mixed
.
var str = web3.toHex({test: 'test'});
console.log(str); // '0x7b2274657374223a2274657374227d'
web3.toAscii(hexString);
Converts a HEX string into a ASCII string.
String
- A HEX string to be converted to ascii.String
- An ASCII string made from the given hexString
.
var str = web3.toAscii("0x657468657265756d000000000000000000000000000000000000000000000000");
console.log(str); // "ethereum"
web3.fromAscii(string [, padding]);
Converts any ASCII string to a HEX string.
String
- An ASCII string to be converted to HEX.Number
- The number of bytes the returned HEX string should have. String
- The converted HEX string.
var str = web3.fromAscii('ethereum');
console.log(str); // "0x657468657265756d"
var str2 = web3.fromAscii('ethereum', 32);
console.log(str2); // "0x657468657265756d000000000000000000000000000000000000000000000000"
web3.toDecimal(hexString);
Converts a HEX string to its number representation.
String
- An HEX string to be converted to a number.Number
- The number representing the data hexString
.
var number = web3.toDecimal('0x15');
console.log(number); // 21
web3.fromDecimal(number);
Converts a number or number string to its HEX representation.
Number|String
- A number to be converted to a HEX string.String
- The HEX string representing of the given number
.
var value = web3.fromDecimal('21');
console.log(value); // "0x15"
web3.fromWei(number, unit)
Converts a number of wei into the following ethereum units:
kwei
/ada
mwei
/babbage
gwei
/shannon
szabo
finney
ether
kether
/grand
/einstein
mether
gether
tether
Number|String|BigNumber
- A number or BigNumber instance.String
- One of the above ether units.String|BigNumber
- Either a number string, or a BigNumber instance, depending on the given number
parameter.
var value = web3.fromWei('21000000000000', 'finney');
console.log(value); // "0.021"
web3.toWei(number, unit)
Converts an ethereum unit into wei. Possible units are:
kwei
/ada
mwei
/babbage
gwei
/shannon
szabo
finney
ether
kether
/grand
/einstein
mether
gether
tether
Number|String|BigNumber
- A number or BigNumber instance.String
- One of the above ether units.String|BigNumber
- Either a number string, or a BigNumber instance, depending on the given number
parameter.
var value = web3.toWei('1', 'ether');
console.log(value); // "1000000000000000000"
web3.toBigNumber(numberOrHexString);
Converts a given number into a BigNumber instance.
See the note on BigNumber.
Number|String
- A number, number string or HEX string of a number.BigNumber
- A BigNumber instance representing the given value.
var value = web3.toBigNumber('200000000000000000000001');
console.log(value); // instanceOf BigNumber
console.log(value.toNumber()); // 2.0000000000000002e+23
console.log(value.toString(10)); // '200000000000000000000001'
web3.net.listening
This property is read only and says whether the node is actively listening for network connections or not.
Boolean
- true
if the client is actively listening for network connections, otherwise false
.
var listening = web3.net.listening;
console.log(listening); // true of false
web3.net.peerCount
This property is read only and returns the number of connected peers.
Number
- The number of peers currently connected to the client.
var peerCount = web3.net.peerCount;
console.log(peerCount); // 4
Contains the ethereum blockchain related methods.
var eth = web3.eth;
web3.eth.defaultBlock
This default block is used for the following methods (optionally you can overwrite the defaultBlock by passing it as the last parameter):
Default block parameters can be one of the following:
Number
- a block numberString
- "earliest"
, the genisis blockString
- "latest"
, the latest block (current head of the blockchain)String
- "pending"
, the currently mined block (including pending transactions)Default is latest
Number|String
- The default block number to use when querying a state.
var defaultBlock = web3.eth.defaultBlock;
console.log(defaultBlock); // 'latest'
// set the default block
web3.eth.defaultBlock = 231;
web3.eth.coinbase
This property is read only and returns the coinbase address were the mining rewards go to.
String
- The coinbase address of the client.
var coinbase = web3.eth.coinbase;
console.log(coinbase); // "0x407d73d8a49eeb85d32cf465507dd71d507100c1"
web3.eth.mining
This property is read only and says whether the node is mining or not.
Boolean
- true
if the client is mining, otherwise false
.
var mining = web3.eth.mining;
console.log(mining); // true or false
web3.eth.gasPrice
This property is read only and returns the current gas price. The gas price is determined by the x latest blocks median gas price.
BigNumber
- A BigNumber instance of the current gas price in wei.
See the note on BigNumber.
var gasPrice = web3.eth.gasPrice;
console.log(gasPrice.toString(10)); // "10000000000000"
web3.eth.accounts
This property is read only and returns a list of accounts the node controls.
Array
- An array of addresses controlled by client.
var accounts = web3.eth.accounts;
console.log(accounts); // ["0x407d73d8a49eeb85d32cf465507dd71d507100c1"]
web3.eth.blockNumber
This property is read only and returns the current block number.
Number
- The number of the most recent block.
var number = web3.eth.blockNumber;
console.log(number); // 2744
web3.eth.register(addressHexString [, callback])
(Not Implemented yet)
Registers the given address to be included in web3.eth.accounts
. This allows non-private-key owned accounts to be associated as an owned account (e.g., contract wallets).
String
- The address to registerFunction
- (optional) If you pass a callback the HTTP request is made asynchronous. See this note for details.?
web3.eth.register("0x407d73d8a49eeb85d32cf465507dd71d507100ca")
web3.eth.unRegister(addressHexString [, callback])
(Not Implemented yet) Unregisters a given address.
String
- The address to unregister.Function
- (optional) If you pass a callback the HTTP request is made asynchronous. See this note for details.?
web3.eth.unregister("0x407d73d8a49eeb85d32cf465507dd71d507100ca")
web3.eth.getBalance(addressHexString [, defaultBlock] [, callback])
Get the balance of an address at a given block.
String
- The address to get the balance of.Number|String
- (optional) If you pass this parameter it will not use the default block set with web3.eth.defaultBlock.Function
- (optional) If you pass a callback the HTTP request is made asynchronous. See this note for details.String
- A BigNumber instance of the current balance for the given address in wei.
See the note on BigNumber.
var balance = web3.eth.getBalance("0x407d73d8a49eeb85d32cf465507dd71d507100c1");
console.log(balance); // instanceof BigNumber
console.log(balance.toString(10)); // '1000000000000'
console.log(balance.toNumber()); // 1000000000000
web3.eth.getStorageAt(addressHexString, position [, defaultBlock] [, callback])
Get the storage at a specific position of an address.
String
- The address to get the storage from.Number
- The index position of the storage.Number|String
- (optional) If you pass this parameter it will not use the default block set with web3.eth.defaultBlock.Function
- (optional) If you pass a callback the HTTP request is made asynchronous. See this note for details.String
- The value in storage at the given position.
var state = web3.eth.getStorageAt("0x407d73d8a49eeb85d32cf465507dd71d507100c1", 0);
console.log(state); // "0x03"
web3.eth.getCode(addressHexString [, defaultBlock] [, callback])
Get the code at a specific address.
String
- The address to get the code from.Number|String
- (optional) If you pass this parameter it will not use the default block set with web3.eth.defaultBlock.Function
- (optional) If you pass a callback the HTTP request is made asynchronous. See this note for details.String
- The data at given address addressHexString
.
var code = web3.eth.getCode("0xd5677cf67b5aa051bb40496e68ad359eb97cfbf8");
console.log(code); // "0x600160008035811a818181146012578301005b601b6001356025565b8060005260206000f25b600060078202905091905056"
web3.eth.getBlock(blockHashOrBlockNumber [, returnTransactionObjects] [, callback])
Returns a block matching the block number or block hash.
String|Number
- The block number or hash. Or the string "earliest"
, "latest"
or "pending"
as in the default block parameter.Boolean
- (optional, default false
) If true
, the returned block will contain all transactions as objects, if false
it will only contains the transaction hashes.Function
- (optional) If you pass a callback the HTTP request is made asynchronous. See this note for details.Object
- The block object:
number
: Number
- the block number.hash
: String
, 32 Bytes - hash of the block.parentHash
: String
, 32 Bytes - hash of the parent block.nonce
: String
, 8 Bytes - hash of the generated proof-of-work.sha3Uncles
: String
, 32 Bytes - SHA3 of the uncles data in the block.logsBloom
: String
, 256 Bytes - the bloom filter for the logs of the block.transactionsRoot
: String
, 32 Bytes - the root of the transaction trie of the blockstateRoot
: String
, 32 Bytes - the root of the final state trie of the block.miner
: String
, 20 Bytes - the address of the beneficiary to whom the mining rewards were given.difficulty
: BigNumber
- integer of the difficulty for this block.totalDifficulty
: BigNumber
- integer of the total difficulty of the chain until this block.extraData
: String
- the "extra data" field of this block.size
: Number
- integer the size of this block in bytes.gasLimit
: Number
- the maximum gas allowed in this block.gasUsed
: Number
- the total used gas by all transactions in this block.timestamp
: Number
- the unix timestamp for when the block was collated.transactions
: Array
- Array of transaction objects, or 32 Bytes transaction hashes depending on the last given parameter.uncles
: Array
- Array of uncle hashes.var info = web3.eth.block(3150);
console.log(info);
/*
{
"number": 3,
"hash": "0xef95f2f1ed3ca60b048b4bf67cde2195961e0bba6f70bcbea9a2c4e133e34b46",
"parentHash": "0x2302e1c0b972d00932deb5dab9eb2982f570597d9d42504c05d9c2147eaf9c88",
"nonce": "0xfb6e1a62d119228b",
"sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
"logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
"transactionsRoot": "0x3a1b03875115b79539e5bd33fb00d8f7b7cd61929d5a3c574f507b8acf415bee",
"stateRoot": "0xf1133199d44695dfa8fd1bcfe424d82854b5cebef75bddd7e40ea94cda515bcb",
"miner": "0x8888f1f195afa192cfee860698584c030f4c9db1",
"difficulty": BigNumber,
"totalDifficulty": BigNumber,
"size": 616,
"extraData": "0x",
"gasLimit": 3141592,
"gasUsed": 21662,
"timestamp": 1429287689,
"transactions": [
"0x9fc76417374aa880d4449a1f7f31ec597f00b1f6f3dd2d66f4c9c6c445836d8b"
],
"uncles": []
}
*/
web3.eth.getBlockTransactionCount(hashStringOrBlockNumber [, callback])
Returns the number of transaction in a given block.
String|Number
- The block number or hash. Or the string "earliest"
, "latest"
or "pending"
as in the default block parameter.Function
- (optional) If you pass a callback the HTTP request is made asynchronous. See this note for details.Number
- The number of transactions in the given block.
var number = web3.eth.getBlockTransactionCount("0x407d73d8a49eeb85d32cf465507dd71d507100c1");
console.log(number); // 1
web3.eth.getUncle(blockHashStringOrNumber, uncleNumber [, returnTransactionObjects] [, callback])
Returns a blocks uncle by a given uncle index position.
String|Number
- The block number or hash. Or the string "earliest"
, "latest"
or "pending"
as in the default block parameter.Number
- The index position of the uncle.Boolean
- (optional, default false
) If true
, the returned block will contain all transactions as objects, if false
it will only contains the transaction hashes.Function
- (optional) If you pass a callback the HTTP request is made asynchronous. See this note for details.Object
- the returned uncle. For a return value see web3.eth.getBlock().
Note: An uncle doesn't contain individual transactions.
var uncle = web3.eth.getUncle(500, 0);
console.log(uncle); // see web3.eth.getBlock
web3.eth.getTransaction(transactionHash [, callback])
Returns a transaction matching the given transaction hash.
String
- The transaction hash.Function
- (optional) If you pass a callback the HTTP request is made asynchronous. See this note for details.Object
- A transaction object its hash transactionHash
:
hash
: String
, 32 Bytes - hash of the transaction.nonce
: Number
- the number of transactions made by the sender prior to this one.blockHash
: String
, 32 Bytes - hash of the block where this transaction was in. null
when the transaction is pending.blockNumber
: Number
- block number where this transaction was in. null
when the transaction is pending.transactionIndex
: Number
- integer of the transactions index position in the block.from
: String
, 20 Bytes - address of the sender.to
: String
, 20 Bytes - address of the receiver. null
when its a contract creation transaction.value
: BigNumber
- value transferred in Wei.gasPrice
: BigNumber
- price paid per gas in Wei.gas
: Number
- gas used.input
: String
- the data send along with the transaction.var blockNumber = 668;
var indexOfTransaction = 0
var transaction = web3.eth.getTransaction(blockNumber, indexOfTransaction);
console.log(transaction);
/*
{
"hash": "0x9fc76417374aa880d4449a1f7f31ec597f00b1f6f3dd2d66f4c9c6c445836d8b",
"nonce": 2,
"blockHash": "0xef95f2f1ed3ca60b048b4bf67cde2195961e0bba6f70bcbea9a2c4e133e34b46",
"blockNumber": 3,
"transactionIndex": 0,
"from": "0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b",
"to": "0x6295ee1b4f6dd65047762f924ecd367c17eabf8f",
"value": BigNumber,
"gas": 314159,
"gasPrice": BigNumber,
"input": "0x57cb2fc4"
}
*/
getTransactionFromBlock(hashStringOrNumber, indexNumber [, callback])
Returns a transaction based on a block hash or number and the transactions index position.
String
- A block number or hash. Or the string "earliest"
, "latest"
or "pending"
as in the default block parameter.Number
- The transactions index position.Function
- (optional) If you pass a callback the HTTP request is made asynchronous. See this note for details.Object
- A transaction object, see web3.eth.getTransaction:
var transaction = web3.eth.getTransactionFromBlock('0x4534534534', 2);
console.log(transaction); // see web3.eth.getTransaction
web3.eth.getTransactionCount(addressHexString [, defaultBlock] [, callback])
Get the numbers of transactions send from this address.
String
- The address to get the numbers of transactions from.Number|String
- (optional) If you pass this parameter it will not use the default block set with web3.eth.defaultBlock.Function
- (optional) If you pass a callback the HTTP request is made asynchronous. See this note for details.Number
- The number of transactions send from the given address.
var number = web3.eth.getTransactionCount("0x407d73d8a49eeb85d32cf465507dd71d507100c1");
console.log(number); // 1
web3.eth.sendTransaction(transactionObject [, callback])
Sends a transaction to the network.
Object
- The transaction object to send:from
: String
- The address for the sending account.to
: String
- (optional) The destination address of the message, left undefined for a contract-creation transaction.value
: Number|String|BigNumber
- (optional) The value transferred for the transaction in Wei, also the endowment if it's a contract-creation transaction.gas
: Number|String|BigNumber
- (optional, default: To-Be-Determined) The amount of gas to use for the transaction (unused gas is refunded).gasPrice
: Number|String|BigNumber
- (optional, default: To-Be-Determined) The price of gas for this transaction in wei, defaults to the mean network gas price.data
: String
- (optional) Either a byte string containing the associated data of the message, or in the case of a contract-creation transaction, the initialisation code.Number|String
- (optional) If you pass this parameter it will not use the default block set with web3.eth.defaultBlock.Function
- (optional) If you pass a callback the HTTP request is made asynchronous. See this note for details.String
- The address of the newly created contract, or the 32 Bytes transaction hash as HEX string.
// compiled solidity source code using https://chriseth.github.io/cpp-ethereum/
var code = "603d80600c6000396000f3007c01000000000000000000000000000000000000000000000000000000006000350463c6888fa18114602d57005b600760043502
8060005260206000f3";
web3.eth.sendTransaction({data: code}, function(err, address) {
if (!err)
console.log(address); // "0x7f9fade1c0d57a7af66ab4ead7c2eb7b11a91385"
});
web3.eth.call(callObject [, defaultBlock] [, callback])
Executes a message call transaction, which is directly executed in the VM of the node, but never mined into the blockchain.
Object
- A transaction object see web3.eth.sendTransaction, with the difference that for calls the from
property is optional as well.Number|String
- (optional) If you pass this parameter it will not use the default block set with web3.eth.defaultBlock.Function
- (optional) If you pass a callback the HTTP request is made asynchronous. See this note for details.String
- The returned data of the call, e.g. a codes functions return value.
var result = web3.eth.call({
to: "0xc4abd0339eb8d57087278718986382264244252f",
data: "0xc6888fa10000000000000000000000000000000000000000000000000000000000000003"
});
console.log(result); // "0x0000000000000000000000000000000000000000000000000000000000000015"
// can be 'latest' or 'pending'
var filter = web3.eth.filter(filterString);
// OR object are log filter options
var filter = web3.eth.filter(options);
// watch for changes
filter.watch(function(error, result){
if (!error)
console.log(result);
});
String|Object
- The string "latest"
or "pending"
to watch for changes in the latest block or pending transactions respectively. Or a filter options object as follows:fromBlock
: Number|String
- The number of the earliest block (latest
may be given to mean the most recent and pending
currently mining, block).toBlock
: Number|String
- The number of the latest block (latest
may be given to mean the most recent and pending
currently mining, block).address
: String
- An address or a list of addresses to only get logs from particular account(s).topics
: Array of Strings
- An array of values which must each appear in the log entries. The order is important, if you want to leave topics use null
, e.g. [null, '0x00...']
.Object
- A filter object with the following methods:
filter.get()
: Returns all of the log entries that fit the filter.filter.watch(callback)
: Watches for state changes that fit the filter and calls the callback. See this note for details.filter.stopWatching()
: Stops the watch and uninstalls the filter in the node. Should always be called once it is done.Object
- A log object as follows:
logIndex
: Number
- integer of the log index position in the block.transactionIndex
: Number
- integer of the transactions index position log was created from.transactionHash
: String
, 32 Bytes - hash of the transactions this log was created from.blockHash
: String
, 32 Bytes - hash of the block where this log was in. null
when the log is pending.blockNumber
: Number
- the block number where this log was in. null
when the log is pending.address
: String
, 32 Bytes - address from which this log originated.data
: String
- contains one or more 32 Bytes non-indexed arguments of the log.topics
: Array of Strings
- Array of 0 to 4 32 Bytes DATA
of indexed log arguments. (In solidity: The first topic is the hash of the signature of the event (e.g. Deposit(address,bytes32,uint256)
), except you declared the event with the anonymous
specifier.)Note For event filter return values see Contract Events
var filter = web3.eth.filter('pending');
filter.watch(function (error, log) {
console.log(log); // {"address":"0x0000000000000000000000000000000000000000","data":"0x0000000000000000000000000000000000000000000000000000000000000000", ...}
});
// get all past logs again.
var myResults = filter.get();
...
// stops and uninstalls the filter
filter.stopWatching();
web3.eth.contract(abiArray)
Creates a contract object for a solidity contract, which can be used to initiate contracts on an address. You can read more about events here.
Array
- ABI array with descriptions of functions and events of the contract.Object
- A contract object, which can be initiated as follows:
var MyContract = web3.eth.contract(abiArray);
var myContractInstance = new MyContract(myContractAddress);
// contract abi
var abi = [{
name: 'myMethod',
type: 'function',
inputs: [{ name: 'a', type: 'string' }],
outputs: [{name: 'd', type: 'string' }]
}, {
name: 'myEvent',
type: 'event',
inputs: [{name: 'a', type: 'int', indexed: true},{name: 'b', type: 'bool', indexed: false]
}];
// creation of contract object
var MyContract = web3.eth.contract(abi);
// initiate contract for an address
var myContractInstance = new MyContract('0x43gg423k4h4234235345j3453');
var result = myContractInstance.myConstantMethod('myParam');
console.log(result) // '0x25434534534'
myContractInstance.myStateChangingMethod('someParam1', 23, {value: 200, gas: 2000});
var filter = myContractInstance.myEvent({a: 5});
filter.watch(function (error, result) {
if (!error)
console.log(result);
/*
{
address: '0x0123123121',
topics: "0x12345678901234567890123456789012", "0x0000000000000000000000000000000000000000000000000000000000000005",
data: "0x0000000000000000000000000000000000000000000000000000000000000001",
...
}
*/
});
// Automatically determines the use of call or sendTransaction based on the method type
myContractInstance.myMethod(param1 [, param2, ...] [, transactionObject]);
// Explicitly calling this method
myContractInstance.myMethod.call(param1 [, param2, ...] [, transactionObject]);
// Explicitly sending a transaction to this method
myContractInstance.myMethod.sendTransaction(param1 [, param2, ...] [, transactionObject]);
The contract object exposes the contracts methods, which can be called using parameters and a transaction object.
String|Number
- (optional) Zero or more parameters of the function.Object
- (optional) The last parameter can be a transaction object, see web3.eth.sendTransaction parameter 1 for more.String
- If its a call the result data, if its a send transaction a created contract address, or the transaction hash, see web3.eth.sendTransaction for details.
// creation of contract object
var MyContract = web3.eth.contract(abi);
// initiate contract for an address
var myContractInstance = new MyContract('0x43gg423k4h4234235345j3453');
var result = myContractInstance.myConstantMethod('myParam');
console.log(result) // '0x25434534534'
myContractInstance.myStateChangingMethod('someParam1', 23, {value: 200, gas: 2000});
var event = myContractInstance.MyEvent({valueA: 23}, additionalFilterObject)
// watch for changes
event.watch(function(error, result){
if (!error)
console.log(result);
});
You can use events like filters and they have the same methods, but you pass different objects to create the event filter.
Object
- Indexed return values you want to filter the logs by, e.g. {'valueA': 1, 'valueB': [myFirstAddress, mySecondAddress]}
.Object
- Additional filter options, see filters parameter 1 for more.Object
- An event object as follows:
args
: Object
- The arguments coming from the event.event
: String
- The event name.logIndex
: Number
- integer of the log index position in the block.transactionIndex
: Number
- integer of the transactions index position log was created from.transactionHash
: String
, 32 Bytes - hash of the transactions this log was created from.address
: String
, 32 Bytes - address from which this log originated.blockHash
: String
, 32 Bytes - hash of the block where this log was in. null
when the log is pending.blockNumber
: Number
- the block number where this log was in. null
when the log is pending.var MyContract = web3.eth.contract(abi);
var myContractInstance = new MyContract('0x43gg423k4h4234235345j3453');
// watch for an event
var myEvent = myContractInstance.MyEvent({some: 'args'}, additionalFilterObject);
myEvent.watch(function(error, result){
...
});
// would get all past logs again.
var myResults = myEvent.get();
...
// would stop and uninstall the filter
myEvent.stopWatching();
web3.eth.getCompilers([callback])
Gets a list of available compilers.
Function
- (optional) If you pass a callback the HTTP request is made asynchronous. See this note for details.Array
- An array of strings of available compilers.
var number = web3.eth.getCompilers();
console.log(number); // ["lll", "solidity", "serpent"]
web3.eth.compile.solidity(sourceString [, callback])
Compiles solidity source code.
String
- The solidity source code.Function
- (optional) If you pass a callback the HTTP request is made asynchronous. See this note for details.String
- The compiled solidity code as HEX string.
var source = "" +
"contract test {\n" +
" function multiply(uint a) returns(uint d) {\n" +
" return a * 7;\n" +
" }\n" +
"}\n";
var code = web3.eth.compile.solidity(source);
console.log(code); // "0x603880600c6000396000f3006001600060e060020a600035048063c6888fa114601857005b6021600435602b565b8060005260206000f35b600081600702905091905056"
web3. eth.compile.lll(sourceString [, callback])
Compiles LLL source code.
String
- The LLL source code.Function
- (optional) If you pass a callback the HTTP request is made asynchronous. See this note for details.String
- The compiled LLL code as HEX string.
var source = "...";
var code = web3.eth.compile.lll(source);
console.log(code); // "0x603880600c6000396000f3006001600060e060020a600035048063c6888fa114601857005b6021600435602b565b8060005260206000f35b600081600702905091905056"
web3.eth.compile.serpent(sourceString [, callback])
Compiles serpent source code.
String
- The serpent source code.Function
- (optional) If you pass a callback the HTTP request is made asynchronous. See this note for details.String
- The compiled serpent code as HEX string.
var source = "...";
var code = web3.eth.compile.serpent(source);
console.log(code); // "0x603880600c6000396000f3006001600060e060020a600035048063c6888fa114601857005b6021600435602b565b8060005260206000f35b600081600702905091905056"
web3.db.putString(db, key, value)
This method should be called, when we want to store a string in the local leveldb database.
String
- The database to store to.String
- The name of the store.String
- The string value to store.Boolean
- true
if successfull, otherwise false
.
param is db name, second is the key, and third is the string value.
web3.db.putString('testDB', 'key', 'myString') // true
web3.db.getString(db, key)
This method should be called, when we want to get string from the local leveldb database.
String
- The database to store to.String
- The name of the store.String
- The stored value.
param is db name and second is the key of string value.
var value = web3.db.getString('testDB', 'key');
console.log(value); // "myString"
web3.db.putHex(db, key, value)
This method should be called, when we want to store binary data in HEX form in the local leveldb database.
String
- The database to store to.String
- The name of the store.String
- The HEX string to store.Boolean
- true
if successfull, otherwise false
.
web3.db.putHex('testDB', 'key', '0x4f554b443'); // true
web3.db.getHex(db, key)
This method should be called, when we want to get a binary data in HEX form from the local leveldb database.
String
- The database to store to.String
- The name of the store.String
- The stored HEX value.
param is db name and second is the key of value.
var value = web3.db.getHex('testDB', 'key');
console.log(value); // "0x4f554b443"
var shh = web3.shh;
web3.shh.post(object [, callback])
This method should be called, when we want to post whisper message to teh network.
Object
- The post object:from
: String
, 60 Bytes HEX - (optional) The identity of the sender.to
: String
, 60 Bytes HEX - (optional) The identity of the receiver. When present whisper will encrypt the message so that only the receiver can decrypt it.topics
: Array of Strings
- Array of topics Strings
, for the receiver to identify messages.payload
: String|Number|Object
- The payload of the message. Will be autoconverted to a HEX string before.priority
: Number
- The integer of the priority in a rang from ... (?).ttl
: Number
- integer of the time to live in seconds.Function
- (optional) If you pass a callback the HTTP request is made asynchronous. See this note for details.Boolean
- returns true
if the message was send, otherwise false
.
var identity = web3.shh.newIdentity();
var topic = 'example';
var payload = 'hello whisper world!';
var message = {
from: identity,
topics: [topic],
payload: payload,
ttl: 100,
workToProve: 100 // or priority TODO
};
web3.shh.post(message);
web3.shh.newIdentity([callback])
Should be called to create new identity.
Function
- (optional) If you pass a callback the HTTP request is made asynchronous. See this note for details.String
- A new identity HEX string.
var identity = web3.shh.newIdentity();
console.log(identity); // "0xc931d93e97ab07fe42d923478ba2465f283f440fd6cabea4dd7a2c807108f651b7135d1d6ca9007d5b68aa497e4619ac10aa3b27726e1863c1fd9b570d99bbaf"
web3.shh.hasIdentity(identity, [callback])
Should be called, if we want to check if user has given identity.
String
- The identity to check.Function
- (optional) If you pass a callback the HTTP request is made asynchronous. See this note for details.Boolean
- returns true
if the identity exists, otherwise false
.
var identity = web3.shh.newIdentity();
var result = web3.shh.hasIdentity(identity);
console.log(result); // true
var result2 = web3.shh.hasIdentity(identity + "0");
console.log(result2); // false
// TODO: not implemented yet
// TODO: not implemented yet
var filter = web3.shh.filter(options)
// watch for changes
event.watch(function(error, result){
if (!error)
console.log(result);
});
Watch for incoming whisper messages.
Object
- The filter options:topics
: Array of Strings
- Filters messages by this topic(s). You can use the following combinations:['topic1', 'topic2'] == 'topic1' && 'topic2'
['topic1', ['topic2', 'topic3']] == 'topic1' && ('topic2' || 'topic3')
[null, 'topic1', 'topic2'] == ANYTHING && 'topic1' && 'topic2'
-> null
works as a wildcardto
: Filter by identity of receiver of the message. If provided and the node has this identity, it will decrypt incoming encrypted messages.Function
- (optional) If you pass a callback the HTTP request is made asynchronous. See this note for details.Object
- The incoming message:
from
: String
, 60 Bytes - The sender of the message, if a sender was specified.to
: String
, 60 Bytes - The receiver of the message, if a receiver was specified.expiry
: Number
- Integer of the time in seconds when this message should expire (?).ttl
: Number
- Integer of the time the message should float in the system in seconds (?).sent
: Number
- Integer of the unix timestamp when the message was sent.topics
: Array of String
- Array of String
topics the message contained.payload
: String
- The payload of the message.workProved
: Number
- Integer of the work this message required before it was send (?).