| ★ wanayoo — archive 1999 https://github.com/ethereum/wiki/wiki/JavaScript-API | Nouvelle recherche | Portail wanayoo |
To make your ÐApp work with on Ethereum, you'll need to know about the Ethereum Javascript bindings, or, if you like, magic Javascript objects. These bindings may be used with AlethZero, Mist and external browser. These bindings can be found at ethereum.js repository.
There is, at the global scope, one objects; the web3 object, containing data handling functions (commonly used for all other APIs). This object also contains other subprotocol objects including the eth object - web3.eth (for specifically Ethereum interaction) and the shh object - web3.shh (for Whisper interaction). Over time we'll introduce other objects for each of the other web3 protocols.
The canonical form of almost all parameters in this API is data represented as hex, prefixed with an 0x. There's automatic conversion from decimal strings to the hex representation (interpreted as a big-endian as is standard for Ethereum). So, the following two forms are identically interpreted:
"0x414243""4276803"In each case, they are interpreted as the number 4276803. To convert to or from other datatypes, such as strings and integers, there are a number of conversion functions, detailed later.
The web3 object can be used for general data handling.
var web3 = require('web3')Returns the SHA3 of the given data.
var str = web3.fromAscii("Some ASCII string to be hashed");
console.log(str); // "0x536f6d6520415343494920737472696e6720746f20626520686173686564"
var hash = web3.sha3(str);
console.log(hash); // "0xb21dbc7a5eb6042d91f8f584af266f1a512ac89520f43562c6c1e37eab6eb0c4"Returns an ASCII string made from the data _s.
var str = web3.toAscii("0x657468657265756d000000000000000000000000000000000000000000000000");
console.log(str); // ethereumReturns data of the ASCII string _s, auto-padded to _padding bytes (default to 32) and left-aligned.
var str = web3.fromAscii('ethereum');
console.log(str); // "0x657468657265756d000000000000000000000000000000000000000000000000"
var str2 = web3.fromAscii('ethereum', 32);
console.log(str2); // "0x657468657265756d000000000000000000000000000000000000000000000000"Returns the decimal string representing the data _s (when interpreted as a big-endian integer).
var value = web3.toDecimal('0x15');
console.log(value === "21"); // trueReturns the hex data string representing (in big-endian format) the decimal integer _s.
var value = web3.fromDecimal('21');
console.log(value === "0x15"); // trueShould be called to set provider.
web3.setProvider(new web3.providers.HttpSyncProvider());
// or
web3.setProvider(new web3.providers.QtSyncProvider());Should be called to reset state of web3. Resets everything except manager. Uninstalls all filters. Stops polling.
web3.reset();Should be called to get web3.eth object.
var eth = web3.eth;Returns the coinbase address of the client.
var coinbase = web3.eth.coinbase;
console.log(coinbase); // "0x407d73d8a49eeb85d32cf465507dd71d507100c1"Returns true if and only if the client is actively listening for network connections.
var listening = web3.eth.listening;
console.log(listening); // true of falseReturns true if and only if the client is actively mining new blocks.
var mining = web3.eth.mining;
console.log(mining); // true or falseReturns the special 256-bit number equal to the hard-coded testnet price of gas.
var gasPrice = web3.eth.gasPrice;
console.log(gasPrice); // "0x09184e72a000"Returns the special key-pair list object corresponding to the address of each of the accounts owned by the client that this ÐApp has access to.
var accounts = web3.eth.accounts;
console.log(accounts); // ["0x407d73d8a49eeb85d32cf465507dd71d507100c1"] Returns the number of peers currently connected to the client.
var peerCount = web3.eth.peerCount;
console.log(peerCount); // 4The default block number/age to use when querying state. When positive this is a block number, when 0 or negative it is a block age. -1 therefore means the most recently mined block, 0 means the block being currently mined (i.e. to include pending transactions). Defaults to -1.
var defaultBlock = web3.eth.defaultBlock;
console.log(defaultBlock); // -1Returns the number of the most recent block.
var number = web3.eth.number;
console.log(number); // 2744Returns the balance of the account of address given by the address _a
var balance = web3.eth.balanceAt("0x407d73d8a49eeb85d32cf465507dd71d507100c1");
console.log(balance); // "0x32884442997a37a000"Returns the value in storage at position given by the string _s of the account of address given by the address _a.
var state = web3.eth.stateAt("0x407d73d8a49eeb85d32cf465507dd71d507100c1", 0);
console.log(state); // "0x03"Dumps storage as json object.
var storage = web3.eth.storageAt("0x407d73d8a49eeb85d32cf465507dd71d507100c1");
console.log(storage); // { "0x" : "0x03" }Returns the number of transactions send from the account of address given by _a.
var number = web3.eth.countAt("0x407d73d8a49eeb85d32cf465507dd71d507100c1");
console.log(number); // 1Returns true if the account of address given by _a is a contract-account.
var code = web3.eth.codeAt("0xd5677cf67b5aa051bb40496e68ad359eb97cfbf8");
console.log(code); // "0x600160008035811a818181146012578301005b601b6001356025565b8060005260206000f25b600060078202905091905056"Returns the block with number _number. Return value is an object with the following keys:
hash: The block hash (i.e. the SHA3 of the RLP-encoded dump of the block's header). A 32-byte hash.parentHash: The parent block's hash (i.e. the SHA3 of the RLP-encoded dump of the parent block's header). A 32-byte hash.sha3Uncles: The SHA3 of the RLP-encoded dump of the uncles portion of the block (a 32-byte hash).miner: The address of the account that was rewarded for mining this block (né the coinbase address). A 20-byte address.stateRoot: The root of the state trie (a 32-byte hash).transactionsRoot: The root of the block's transactions trie (a 32-byte hash).difficulty: The PoW difficulty of this block (a big int).number: The number of this block (an integer).minGasPrice: The minimum price, in Wei, of one GAS, that the miner accepted for any transactions in this block (a big int).gasLimit: The gas limit of this block (an integer).gasUsed: The amount of gas used in this block (an integer).timestamp: The timestamp of this block (an integer).extraData: Any extra data this block contains (a byte array).nonce: The block's PoW nonce (a 32-byte hash).children: The hashes of any children this block has (an array of 32-byte hashes)totalDifficulty: The total difficulty of the entire chain up and including this block (a bigint).bloom: The bloom filter of this block (a 32-byte hash).var info = web3.eth.block(3150);
console.log(info);
/*{
"difficulty": "0x02a88f",
"extraData": "0x0000000000000000000000000000000000000000000000000000000000000000",
"gasLimit": 125000,
"hash": "80452e84d0d0599d779a4e466d0b70d50ca316499a8489604d5b9df436ccfeee",
"minGasPrice": "0x09184e72a000",
"miner": "0x407d73d8a49eeb85d32cf465507dd71d507100c1",
"nonce": "0xed0c6a53777b15880fb359dfd9368d002c959243a19c35ca1ae2e97f9bf78a53",
"number": 3150,
"parentHash": "0xf9de6948d835ed5257229b5103f9421a7f70c3ccc65fd31c0db85324e05702f5",
"sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
"stateRoot": "0xd878fcee309af964e8e70c66ec25b1e7de9eca9c4f49e90efddeea8f77a37e43",
"timestamp": 1416585210,
"transactionsRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421"
} */Returns the transaction number _i from block with number _number. Return value is an object with the following keys:
hash: The hash of the transaction. A 32-byte hash.input: The binary data that formed the input to the transaction, either the input data if it was a message call or the contract initialisation if it was a contract creation. A byte array.to: The address to which the transaction was sent. This may be the null address (address 0) if it was a contract-creation transaction (a 20-byte address).from: The cryptographically verified address from which the transaction was sent (a 20-byte address).gas: The amount of GAS supplied for this transaction to happen (an integer).gasPrice: The price offered to the miner to purchase this amount of GAS, in Wei/GAS (a big int).nonce: The transaction nonce (an integer).value: The amount of ETH to be transferred to the recipient with the transaction (a big int).var blockNumber = 668;
var indexOfTransaction = 0
var transaction = web3.eth.transaction(blockNumber, indexOfTransaction);
console.log(transaction);
/*
{
"from":"0x407d73d8a49eeb85d32cf465507dd71d507100c1",
"gas":520464,
"gasPrice":"0x09184e72a000",
"hash":"0xc6ef2fc5426d6ad6fd9e2a26abeab0aa2411b7ab17f30a99d3cb96aed1d1055b",
"input":"0x603880600c6000396000f3006001600060e060020a600035048063c6888fa114601857005b6021600435602b565b8060005260206000f35b600081600702905091905056",
"nonce":"0x",
"to":"0x0000000000000000000000000000000000000000",
"value":"0x"
}
*/
Returns the uncle number _i from block with number _number. Return value is an object with the following keys:
hash: The block hash (i.e. the SHA3 of the RLP-encoded dump of the block's header). A 32-byte hash.parentHash: The parent block's hash (i.e. the SHA3 of the RLP-encoded dump of the parent block's header). A 32-byte hash.sha3Uncles: The SHA3 of the RLP-encoded dump of the uncles portion of the block (a 32-byte hash).miner: The address of the account that was rewarded for mining this block (né the coinbase address). A 20-byte address.stateRoot: The root of the state trie (a 32-byte hash).transactionsRoot: The root of the block's transactions trie (a 32-byte hash).difficulty: The PoW difficulty of this block (a big int).number: The number of this block (an integer).minGasPrice: The minimum price, in Wei, of one GAS, that the miner accepted for any transactions in this block (a big int).gasLimit: The gas limit of this block (an integer).gasUsed: The amount of gas used in this block (an integer).timestamp: The timestamp of this block (an integer).extraData: Any extra data this block contains (a byte array).nonce: The block's PoW nonce (a 32-byte hash).var blockNumber = 500;
var indexOfUncle = 0
var uncle = web3.eth.uncle(blockNumber, indexOfUncle);
console.log(uncle);
/*
{
"difficulty":"0x",
"extraData":"0x0000000000000000000000000000000000000000000000000000000000000000",
"gasLimit":0,
"hash":"0000000000000000000000000000000000000000000000000000000000000000",
"miner":"0x0000000000000000000000000000000000000000",
"nonce":"0x0000000000000000000000000000000000000000000000000000000000000000",
"number":0,
"parentHash":"0x0000000000000000000000000000000000000000000000000000000000000000",
"sha3Uncles":"0x0000000000000000000000000000000000000000000000000000000000000000",
"stateRoot":"0x0000000000000000000000000000000000000000000000000000000000000000",
"timestamp":-1,
"transactionsRoot":"0x0000000000000000000000000000000000000000000000000000000000000000"
}
*/Creates a new message-call transaction.
_params, an anonymous object specifying the parameters of the transaction.
from, the address for the sending account;value, the value transferred for the transaction (in Wei), also the endowment if it's a contract-creation transaction;endowment, synonym for value;to, the destination address of the message, left undefined for a contract-creation transaction;data, either a byte string containing the associated data of the message, or in the case of a contract-creation transaction, the initialisation code;code, a synonym for data;gas, the amount of gas to purchase for the transaction (unused gas is refunded), defaults to the most gas your ether balance allows; andgasPrice, the price of gas for this transaction, defaults to the mean network gasPrice._fn, the callback function, called on completion of the transaction. If the transaction was a contract-creation transaction, it is passed with a single argument; the address of the new account.
// solidity source code
var source = "" +
"contract test {\n" +
" function multiply(uint a) returns(uint d) {\n" +
" return a * 7;\n" +
" }\n" +
"}\n";
var compiled = web3.eth.solidity(source);
var address = web3.eth.transact({code: compiled});
console.log(address); // "0x7f9fade1c0d57a7af66ab4ead7c2eb7b11a91385"Executes a new message-call immediately without creating a transaction on the block chain.
_params, an anonymous object specifying the parameters of the transaction, similar to that above.var options = {
to: "0xc4abd0339eb8d57087278718986382264244252f",
data: "0xc6888fa10000000000000000000000000000000000000000000000000000000000000003"
};
var result = web3.eth.call(options);
console.log(result); // "0x0000000000000000000000000000000000000000000000000000000000000015"Past messages may be filtered and their attributes inspected, and future messages (and the changes they implicitly bring) may be notified of. Returns the list of log entries in Ethereum matching the given _filter. The filter is an object including fields:
earliest: The number of the earliest block (-1 may be given to mean the most recent, currently mining, block).latest: The number of the latest block (-1 may be given to mean the most recent, currently mining, block).max: The maximum number of messages to return.skip: The number of messages to skip before the list is constructed. May be used with max to paginate messages into multiple calls.address: An address or a list of addresses to restrict log entries by requiring them to be made from a particular account.topic: A set of values which must each appear in the log entries.address: The address of the account whose execution of the message resulted in the log entry being made.topics: The topic(s) of the log.data: The associated data of the log.number: The block number from which this log is.web3.eth.watch(_filter): Creates a watch object to notify when the state changes in a particular way, given by _filter. Filter may be a log filter object, as defined above. It may also be either 'chain' or 'pending' to watch for changes in the chain or pending transactions respectively. Returns a watch object with the following methods:
changed(_f): Installs a handler, _f, which is called when the state changes due to logs that fit _filter. These (new) log entries are passed as a parameter in a format equivalent to the return value of web3.eth.logs.logs(): Returns all of the log entries that fit _filter.uninstall(): Uninstalls the watch. Should always be called once it is done with.var watch = web3.eth.watch('pending');
watch.changed(function (log) {
console.log(log); // {"address":"0x0000000000000000000000000000000000000000","data":"0x0000000000000000000000000000000000000000000000000000000000000000","number":0}
});This method should be called when we want to call / transact some solidity method from javascript. It returns an object which has the same methods available as solidity contract description.
You can read more about events here.
usage example:
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]
}]; // contract abi
var myContract = web3.eth.contract('0x0123123121', abi); // creation of contract object
myContract.myMethod('this is test string param for call'); // myMethod call (implicit, default)
myContract.call().myMethod('this is test string param for call'); // myMethod call (explicit)
myContract.transact().myMethod('this is test string param for transact'); // myMethod transact
var watch = myContract.myEvent({a: 5});
watch.changed(function (result) {
console.log(result);
/*
{
address: '0x0123123121',
topics: "0x12345678901234567890123456789012", "0x0000000000000000000000000000000000000000000000000000000000000005",
data: "0x0000000000000000000000000000000000000000000000000000000000000001",
number: 2
}
*/
});// TODO:Returns an array of available compilers
var number = web3.eth.compilers();
console.log(number); // ["lll", "solidity", "serpent"]Compiles the solidity source code _s and returns the output data.
var source = "" +
"contract test {\n" +
" function multiply(uint a) returns(uint d) {\n" +
" return a * 7;\n" +
" }\n" +
"}\n";
var code = web3.eth.solidity(source);
console.log(code); // "0x603880600c6000396000f3006001600060e060020a600035048063c6888fa114601857005b6021600435602b565b8060005260206000f35b600081600702905091905056"Compiles the LLL source code _s and returns the output data.
// TODO (_code)Compiles the serpent source code _s and returns the output data.
// TODO (_code)This method should be called, when we want to store number in local leveldb database. First param is db name, second is the key, and third is the value.
var result = web3.db.put('test', 'key', "5");
console.log(result); // true
var value = web3.db.get('test', 'key');
console.log(value); // "0x05"This method should be called, when we want to store string in local leveldb database. First param is db name, second is the key, and third is the string value.
var result = web3.db.putString('test', 'key', "5")
console.log(result); // true
var value = web3.db.get('test', 'key');
console.log(value); // "5"This method should be called, when we want to get number value from local leveldb database. First param is db name and second is the key of value.
var result = web3.db.put('test', 'key', "5");
console.log(result); // true
var value = web3.db.get('test', 'key');
console.log(value); // "0x05"This method should be called, when we want to get string value from local leveldb database. First param is db name and second is the key of string value.
var result = web3.db.putString('test', 'key', "5")
console.log(result); // true
var value = web3.db.get('test', 'key');
console.log(value); // "5"var shh = web3.shh;This method should be called, when we want to post whisper message. _message object may have following fields:
from: identity of senderto: identity of receiverpayload: message payloadttl: time to liveworkToProve: TODOtopic: string or array of strings, with message topicsvar identity = web3.shh.newIdentity();
var topic = 'example';
var payload = 'hello whisper world!';
var message = {
from: identity,
topic: [web3.fromAscii(topic)],
payload: web3.fromAscii(payload),
ttl: 100,
priority: 100
};
web3.shh.post(message);Should be called to create new identity.
var identity = web3.shh.newIdentity();
console.log(identity); // "0xc931d93e97ab07fe42d923478ba2465f283f440fd6cabea4dd7a2c807108f651b7135d1d6ca9007d5b68aa497e4619ac10aa3b27726e1863c1fd9b570d99bbaf"Should be called, if we want to check if user has given identity. Accepts one param. Returns true if he has, otherwise false.
var identity = web3.shh.newIdentity();
var result = web3.shh.haveIdentity(identity);
console.log(result); // true
var result2 = web3.shh.haveIdentity(identity + "0");
console.log(result2); // false// TODO: not implemented yet// TODO: not implemented yetThis method should be used, when you want to watch whisper messages. Available filter options are:
topic: string or array of strings. filter messages with this topicto: filter the identity of receiver of the messagevar topic = 'example';
var options = {
topic: [web3.fromAscii(topic)]
};
var watch = web3.shh.watch(options);
watch.arrived(function(res) {
console.log(res);
/* {
"expiry":1422565026,
"from":"0x3ec052fc3376f8a218b24b652803a5892038c39419a9a44923a61b113b7785d16ed1572df628859af3504670e4df31dcd8b3ee9a2110fd710c948690f0557394",
"hash":"0x33eb2da77bf3527e28f8bf493650b1879b08c4f2a362beae4ba2f71bafcd91f9",
"payload":"0x7b2274797065223a226d657373616765222c2263686174223a2265537668624d763939784c345442537741222c2274696d657374616d70223a7b222464617465223a313432323536343932363533377d2c22746f706963223a22222c2266726f6d223a7b226964656e74697479223a2230783365633035326663333337366638613231386232346236353238303361353839323033386333393431396139613434393233613631623131336237373835643136656431353732646636323838353961663335303436373065346466333164636438623365653961323131306664373130633934383639306630353537333934222c226e616d65223a22416365746f7465227d2c226d657373616765223a2273617361222c226964223a227a465232614e68594a666f4d4c62707333227d",
"sent":1422564926,
"to":"0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
"topics":["0x6578616d"],
"ttl":100,
"workProved":0
}
*/
});A simple HTML snippet that will display the user's primary account balance of Ether:
<html><body>
<div>You have <span id="ether">?</span> Weis</div>
<script>
web3.eth.watch('pending').changed(function() {
var balance = web3.eth.balanceAt(web3.eth.coinbase);
document.getElementById("ether").innerText = web3.toDecimal(balance);
</script>
</body></html>To test it, just put it in file and save. Load it in AlethZero and point the URL to file:///WHEREVER_YOU_SAVED_IT
Job done. Now go create.
more examples can be found here