diff --git a/docs/web3-eth.rst b/docs/web3-eth.rst index 2dc7758..ecdc63c 100644 --- a/docs/web3-eth.rst +++ b/docs/web3-eth.rst @@ -1724,82 +1724,17 @@ Returns > "0x603880600c6000396000f3006001600060e060020a600035048063c6888fa114601857005b6021600435602b565b8060005260206000f35b600081600702905091905056" + ------------------------------------------------------------------------------ -### web3.shh - -[Whisper Overview](https://github.com/ethereum/wiki/wiki/Whisper-Overview) - -------- -Example -------- - +web3.eth.getWork +===================== .. code-block:: javascript -var shh = web3.shh; + web3.eth.getWork([callback]) - ------------------------------------------------------------------------------- - -web3.shh.post -===================== - - web3.shh.post(object [, callback]) - -This method should be called, when we want to post whisper message to the network. - ----------- -Parameters ----------- - -1. ``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. -2. ``Function`` - (optional) Optional callback, returns an error object as first parameter and the result as second. - -------- -Returns -------- - - -``Boolean`` - returns ``true`` if the message was send, otherwise ``false``. - - -------- -Example -------- - - -.. code-block:: javascript - -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 -===================== - - web3.shh.newIdentity([callback]) - -Should be called to create new identity. +Gets work for miners to mine on. Returns the hash of the current block, the seedHash, and the boundary condition to be met ("target"). ---------- Parameters @@ -1807,14 +1742,57 @@ Parameters 1. ``Function`` - (optional) Optional callback, returns an error object as first parameter and the result as second. +------- +Returns +------- + +``Promise`` returns ``Array`` - the mining work with the following structure: + + - ``String`` 32 Bytes - at **index 0**: current block header pow-hash + - ``String`` 32 Bytes - at **index 1**: the seed hash used for the DAG. + - ``String`` 32 Bytes - at **index 2**: the boundary condition ("target"), 2^256 / difficulty. + +------- +Example +------- + + +.. code-block:: javascript + + web3.eth.getWork(); + .then(console.log); + > [ + "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", + "0x5EED00000000000000000000000000005EED0000000000000000000000000000", + "0xd1ff1c01710000000000000000000000d1ff1c01710000000000000000000000" + ] + + +------------------------------------------------------------------------------ + +web3.eth.submitWork +===================== + +.. code-block:: javascript + + web3.eth.submitWork(nonce, powHash, digest, [callback]) + +Used for submitting a proof-of-work solution. + +---------- +Parameters +---------- + +1. ``String`` 8 Bytes: The nonce found (64 bits) +2. ``String`` 32 Bytes: The header's pow-hash (256 bits) +3. ``String`` 32 Bytes: The mix digest (256 bits) +4. ``Function`` - (optional) Optional callback, returns an error object as first parameter and the result as second. ------- Returns ------- - -``String`` - A new identity HEX string. - +``Promise`` returns ``Boolean`` - Returns ``TRUE`` if the provided solution is valid, otherwise false. ------- Example @@ -1823,141 +1801,18 @@ Example .. code-block:: javascript -var identity = web3.shh.newIdentity(); -console.log(identity); // "0xc931d93e97ab07fe42d923478ba2465f283f440fd6cabea4dd7a2c807108f651b7135d1d6ca9007d5b68aa497e4619ac10aa3b27726e1863c1fd9b570d99bbaf" + web3.eth.submitWork([ + "0x0000000000000001", + "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", + "0xD1FE5700000000000000000000000000D1FE5700000000000000000000000000" + ]); + .then(console.log); + > true ------------------------------------------------------------------------------ -web3.shh.hasIdentity -===================== - - web3.shh.hasIdentity(identity, [callback]) - -Should be called, if we want to check if user has given identity. - ----------- -Parameters ----------- - -1. ``String`` - The identity to check. -2. ``Function`` - (optional) Optional callback, returns an error object as first parameter and the result as second. - -------- -Returns -------- - - -``Boolean`` - returns ``true`` if the identity exists, otherwise ``false``. - - -------- -Example -------- - - -.. code-block:: javascript - -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 - - ------------------------------------------------------------------------------- - -web3.shh.newGroup -===================== - -------- -Example -------- - -.. code-block:: javascript - -// TODO: not implemented yet - - ------------------------------------------------------------------------------- - -web3.shh.addToGroup -===================== - -------- -Example -------- - -.. code-block:: javascript - -// TODO: not implemented yet - - ------------------------------------------------------------------------------- - -web3.shh.filter -===================== - -.. code-block:: javascript - -var filter = web3.shh.filter(options) - -// watch for changes -filter.watch(function(error, result){ - if (!error) - console.log(result); -}); - - -Watch for incoming whisper messages. - ----------- -Parameters ----------- - -1. ``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 wildcard - * ``to``: Filter by identity of receiver of the message. If provided and the node has this identity, it will decrypt incoming encrypted messages. -2. ``Function`` - (optional) Optional callback, returns an error object as first parameter and the result as second. - -##### Callback return - -``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 (?). - ------------------------------------------------------------------------------- - -web3.eth.sendIBANTransaction -===================== - -.. code-block:: javascript - -var txHash = web3.eth.sendIBANTransaction('0x00c5496aee77c1ba1f0854206a26dda82a81d6d8', 'XE81ETHXREGGAVOFYORK', 0x100); - - -Sends IBAN transaction from user account to destination IBAN address. - ----------- -Parameters ----------- - -- ``string`` - address from which we want to send transaction -- ``string`` - IBAN address to which we want to send transaction -- ``value`` - value that we want to send in IBAN transaction - ------------------------------------------------------------------------------- +// TODO fabian is here web3.eth.iban ===================== @@ -2014,7 +1869,7 @@ var valid = web3.eth.iban.isValid("XE81ETHXREGGAVOFYORK"); console.log(valid); // true var valid2 = web3.eth.iban.isValid("XE82ETHXREGGAVOFYORK"); -console.log(valid2); // false, cause checksum is incorrect +console.log(valid2); // false, because checksum is incorrect var i = new web3.eth.iban("XE81ETHXREGGAVOFYORK"); var valid3 = i.isValid(); diff --git a/docs/web3-shh.rst b/docs/web3-shh.rst new file mode 100644 index 0000000..e50b765 --- /dev/null +++ b/docs/web3-shh.rst @@ -0,0 +1,253 @@ +======== +web3.shh +======== + + +TODO: add instantiation code with web3 and Shh package + + + +------------------------------------------------------------------------------ + +setProvider +===================== + +.. code-block:: javascript + + web3.eth.setProvider(myProvider) + +When called changes the current provider for all modules. + +---------- +Parameters +---------- + +1. ``Object`` - **myProvider**: :ref:`a valid provider `. + +------- +Returns +------- + +``Boolean`` + +------- +Example +------- + +.. code-block:: javascript + + eth.setProvider(new eth.providers.HttpProvider('http://localhost:8545')); + + +------------------------------------------------------------------------------ + +### web3.shh + +[Whisper Overview](https://github.com/ethereum/wiki/wiki/Whisper-Overview) + +------- +Example +------- + + +.. code-block:: javascript + +var shh = web3.shh; + + +------------------------------------------------------------------------------ + +web3.shh.post +===================== + + web3.shh.post(object [, callback]) + +This method should be called, when we want to post whisper message to the network. + +---------- +Parameters +---------- + +1. ``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. +2. ``Function`` - (optional) Optional callback, returns an error object as first parameter and the result as second. + +------- +Returns +------- + + +``Boolean`` - returns ``true`` if the message was send, otherwise ``false``. + + +------- +Example +------- + + +.. code-block:: javascript + +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 +===================== + + web3.shh.newIdentity([callback]) + +Should be called to create new identity. + +---------- +Parameters +---------- + +1. ``Function`` - (optional) Optional callback, returns an error object as first parameter and the result as second. + + +------- +Returns +------- + + +``String`` - A new identity HEX string. + + +------- +Example +------- + + +.. code-block:: javascript + +var identity = web3.shh.newIdentity(); +console.log(identity); // "0xc931d93e97ab07fe42d923478ba2465f283f440fd6cabea4dd7a2c807108f651b7135d1d6ca9007d5b68aa497e4619ac10aa3b27726e1863c1fd9b570d99bbaf" + + +------------------------------------------------------------------------------ + +web3.shh.hasIdentity +===================== + + web3.shh.hasIdentity(identity, [callback]) + +Should be called, if we want to check if user has given identity. + +---------- +Parameters +---------- + +1. ``String`` - The identity to check. +2. ``Function`` - (optional) Optional callback, returns an error object as first parameter and the result as second. + +------- +Returns +------- + + +``Boolean`` - returns ``true`` if the identity exists, otherwise ``false``. + + +------- +Example +------- + + +.. code-block:: javascript + +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 + + +------------------------------------------------------------------------------ + +web3.shh.newGroup +===================== + +------- +Example +------- + +.. code-block:: javascript + +// TODO: not implemented yet + + +------------------------------------------------------------------------------ + +web3.shh.addToGroup +===================== + +------- +Example +------- + +.. code-block:: javascript + +// TODO: not implemented yet + + +------------------------------------------------------------------------------ + +web3.shh.filter +===================== + +.. code-block:: javascript + +var filter = web3.shh.filter(options) + +// watch for changes +filter.watch(function(error, result){ + if (!error) + console.log(result); +}); + + +Watch for incoming whisper messages. + +---------- +Parameters +---------- + +1. ``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 wildcard + * ``to``: Filter by identity of receiver of the message. If provided and the node has this identity, it will decrypt incoming encrypted messages. +2. ``Function`` - (optional) Optional callback, returns an error object as first parameter and the result as second. + +##### Callback return + +``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 (?).