From a011ffdd486990ec7d2e9dc0b25ed04c63b84974 Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Tue, 24 May 2016 12:09:59 -0400 Subject: Corrected capitalisation on index.rst --- docs/index.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 178f34d9..61081e1c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -45,19 +45,19 @@ Available Solidity Integrations Solidity syntax highlighting for SublimeText editor. * `Atom Solidity package `_ - Plugin for the atom editor that features syntax highlighting, compilation and a runtime environment (requires backend node). + Plugin for the Atom editor that features syntax highlighting, compilation and a runtime environment (requires backend node). * `Atom Solidity Linter `_ - Plugin for the atom editor that provides solidity linting + Plugin for the Atom editor that provides Solidity linting. * `Visual Studio Code extension `_ Solidity plugin for Microsoft Visual Studio Code that includes syntax highlighting and the Solidity compiler. * `Emacs Solidity `_ - Plugin for the emacs editor providing syntax highlighting and compilation error reporting. + Plugin for the Emacs editor providing syntax highlighting and compilation error reporting. -* `VIM Solidity `_ - Plugin for the VIM editor providing syntax highlighting. +* `Vim Solidity `_ + Plugin for the Vim editor providing syntax highlighting. Language Documentation ---------------------- -- cgit v1.2.3 From 91459ffc76f2c0e7e42e967b9b6278ddbe37166e Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Wed, 25 May 2016 10:14:57 -0400 Subject: Corrected underline length --- docs/units-and-global-variables.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/units-and-global-variables.rst b/docs/units-and-global-variables.rst index 8f910c80..dd9f4a6f 100644 --- a/docs/units-and-global-variables.rst +++ b/docs/units-and-global-variables.rst @@ -48,7 +48,7 @@ namespace and are mainly used to provide information about the blockchain. Block and Transaction Properties ------------------------------------- +-------------------------------- - ``block.coinbase`` (``address``): current block miner's address - ``block.difficulty`` (``uint``): current block difficulty -- cgit v1.2.3 From bc3e17192f43f746bfa68ffac55f3e888195a4e1 Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Wed, 25 May 2016 10:19:52 -0400 Subject: Made it apparent that block.blockhash is function --- docs/miscellaneous.rst | 2 +- docs/units-and-global-variables.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/miscellaneous.rst b/docs/miscellaneous.rst index 6b327c56..787ff23a 100644 --- a/docs/miscellaneous.rst +++ b/docs/miscellaneous.rst @@ -162,7 +162,7 @@ Global Variables - ``block.difficulty`` (``uint``): current block difficulty - ``block.gaslimit`` (``uint``): current block gaslimit - ``block.number`` (``uint``): current block number -- ``block.blockhash`` (``function(uint) returns (bytes32)``): hash of the given block - only works for 256 most recent blocks +- ``block.blockhash(uint blockNumber) returns (bytes32)``: hash of the given block - only works for 256 most recent blocks - ``block.timestamp`` (``uint``): current block timestamp - ``msg.data`` (``bytes``): complete calldata - ``msg.gas`` (``uint``): remaining gas diff --git a/docs/units-and-global-variables.rst b/docs/units-and-global-variables.rst index dd9f4a6f..05b55cc9 100644 --- a/docs/units-and-global-variables.rst +++ b/docs/units-and-global-variables.rst @@ -54,7 +54,7 @@ Block and Transaction Properties - ``block.difficulty`` (``uint``): current block difficulty - ``block.gaslimit`` (``uint``): current block gaslimit - ``block.number`` (``uint``): current block number - - ``block.blockhash`` (``function(uint) returns (bytes32)``): hash of the given block - only for 256 most recent blocks + - ``block.blockhash(uint blockNumber) returns (bytes32)``: hash of the given block - only works for 256 most recent blocks - ``block.timestamp`` (``uint``): current block timestamp - ``msg.data`` (``bytes``): complete calldata - ``msg.gas`` (``uint``): remaining gas -- cgit v1.2.3 From a6785113b5e145418ab09aa2a77319aa33dbf0c9 Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Wed, 25 May 2016 10:21:03 -0400 Subject: Sorted block attributes alphabetically --- docs/miscellaneous.rst | 2 +- docs/units-and-global-variables.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/miscellaneous.rst b/docs/miscellaneous.rst index 787ff23a..4608f32d 100644 --- a/docs/miscellaneous.rst +++ b/docs/miscellaneous.rst @@ -158,11 +158,11 @@ Cheatsheet Global Variables ================ +- ``block.blockhash(uint blockNumber) returns (bytes32)``: hash of the given block - only works for 256 most recent blocks - ``block.coinbase`` (``address``): current block miner's address - ``block.difficulty`` (``uint``): current block difficulty - ``block.gaslimit`` (``uint``): current block gaslimit - ``block.number`` (``uint``): current block number -- ``block.blockhash(uint blockNumber) returns (bytes32)``: hash of the given block - only works for 256 most recent blocks - ``block.timestamp`` (``uint``): current block timestamp - ``msg.data`` (``bytes``): complete calldata - ``msg.gas`` (``uint``): remaining gas diff --git a/docs/units-and-global-variables.rst b/docs/units-and-global-variables.rst index 05b55cc9..40cf7dac 100644 --- a/docs/units-and-global-variables.rst +++ b/docs/units-and-global-variables.rst @@ -50,11 +50,11 @@ namespace and are mainly used to provide information about the blockchain. Block and Transaction Properties -------------------------------- + - ``block.blockhash(uint blockNumber) returns (bytes32)``: hash of the given block - only works for 256 most recent blocks - ``block.coinbase`` (``address``): current block miner's address - ``block.difficulty`` (``uint``): current block difficulty - ``block.gaslimit`` (``uint``): current block gaslimit - ``block.number`` (``uint``): current block number - - ``block.blockhash(uint blockNumber) returns (bytes32)``: hash of the given block - only works for 256 most recent blocks - ``block.timestamp`` (``uint``): current block timestamp - ``msg.data`` (``bytes``): complete calldata - ``msg.gas`` (``uint``): remaining gas -- cgit v1.2.3 From c0e10b1cf07d0ae5414ede6d66961fb87e832f64 Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Wed, 25 May 2016 10:22:04 -0400 Subject: Added the type of .balance --- docs/miscellaneous.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/miscellaneous.rst b/docs/miscellaneous.rst index 4608f32d..5e9c1375 100644 --- a/docs/miscellaneous.rst +++ b/docs/miscellaneous.rst @@ -180,7 +180,7 @@ Global Variables - ``this`` (current contract's type): the current contract, explicitly convertible to ``address`` - ``super``: the contract one level higher in the inheritance hierarchy - ``selfdestruct(address)``: destroy the current contract, sending its funds to the given address -- ``
.balance``: balance of the address in Wei +- ``
.balance`` (``uint256``): balance of the address in Wei - ``
.send(uint256) returns (bool)``: send given amount of Wei to address, returns ``false`` on failure. .. index:: visibility, public, private, external, internal -- cgit v1.2.3 From 2667874587b831fce36fc12b60a6b6588dfc463b Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Wed, 25 May 2016 10:22:31 -0400 Subject: Removed ending periods for consistency --- docs/miscellaneous.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/miscellaneous.rst b/docs/miscellaneous.rst index 5e9c1375..01a7a04c 100644 --- a/docs/miscellaneous.rst +++ b/docs/miscellaneous.rst @@ -175,13 +175,13 @@ Global Variables - ``sha256(...) returns (bytes32)``: compute the SHA256 hash of the (tightly packed) arguments - ``ripemd160(...) returns (bytes20)``: compute RIPEMD of 256 the (tightly packed) arguments - ``ecrecover(bytes32, uint8, bytes32, bytes32) returns (address)``: recover address associated with the public key from elliptic curve signature -- ``addmod(uint x, uint y, uint k) returns (uint)``: compute ``(x + y) % k`` where the addition is performed with arbitrary precision and does not wrap around at ``2**256``. -- ``mulmod(uint x, uint y, uint k) returns (uint)``: compute ``(x * y) % k`` where the multiplication is performed with arbitrary precision and does not wrap around at ``2**256``. +- ``addmod(uint x, uint y, uint k) returns (uint)``: compute ``(x + y) % k`` where the addition is performed with arbitrary precision and does not wrap around at ``2**256`` +- ``mulmod(uint x, uint y, uint k) returns (uint)``: compute ``(x * y) % k`` where the multiplication is performed with arbitrary precision and does not wrap around at ``2**256`` - ``this`` (current contract's type): the current contract, explicitly convertible to ``address`` - ``super``: the contract one level higher in the inheritance hierarchy - ``selfdestruct(address)``: destroy the current contract, sending its funds to the given address - ``
.balance`` (``uint256``): balance of the address in Wei -- ``
.send(uint256) returns (bool)``: send given amount of Wei to address, returns ``false`` on failure. +- ``
.send(uint256) returns (bool)``: send given amount of Wei to address, returns ``false`` on failure .. index:: visibility, public, private, external, internal -- cgit v1.2.3 From aafc65a2750fa1fc7ebb27a87d6024571e526318 Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Wed, 25 May 2016 10:27:46 -0400 Subject: Made explicit that we use KECCAK-256 --- docs/miscellaneous.rst | 2 +- docs/units-and-global-variables.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/miscellaneous.rst b/docs/miscellaneous.rst index 01a7a04c..f972532c 100644 --- a/docs/miscellaneous.rst +++ b/docs/miscellaneous.rst @@ -171,7 +171,7 @@ Global Variables - ``now`` (``uint``): current block timestamp (alias for ``block.timestamp``) - ``tx.gasprice`` (``uint``): gas price of the transaction - ``tx.origin`` (``address``): sender of the transaction (full call chain) -- ``sha3(...) returns (bytes32)``: compute the Ethereum-SHA3 hash of the (tightly packed) arguments +- ``sha3(...) returns (bytes32)``: compute the Ethereum-SHA3 (KECCAK-256) hash of the (tightly packed) arguments - ``sha256(...) returns (bytes32)``: compute the SHA256 hash of the (tightly packed) arguments - ``ripemd160(...) returns (bytes20)``: compute RIPEMD of 256 the (tightly packed) arguments - ``ecrecover(bytes32, uint8, bytes32, bytes32) returns (address)``: recover address associated with the public key from elliptic curve signature diff --git a/docs/units-and-global-variables.rst b/docs/units-and-global-variables.rst index 40cf7dac..8b6ffda7 100644 --- a/docs/units-and-global-variables.rst +++ b/docs/units-and-global-variables.rst @@ -89,7 +89,7 @@ Mathematical and Cryptographic Functions ``mulmod(uint x, uint y, uint k) returns (uint)``: compute ``(x * y) % k`` where the multiplication is performed with arbitrary precision and does not wrap around at ``2**256``. ``sha3(...) returns (bytes32)``: - compute the Ethereum-SHA-3 hash of the (tightly packed) arguments + compute the Ethereum-SHA-3 (KECCAK-256) hash of the (tightly packed) arguments ``sha256(...) returns (bytes32)``: compute the SHA-256 hash of the (tightly packed) arguments ``ripemd160(...) returns (bytes20)``: -- cgit v1.2.3 From 0c03577adeb4a396d2e56c4f65d7fd4506baad7e Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Wed, 25 May 2016 10:32:53 -0400 Subject: Removed leading space --- docs/units-and-global-variables.rst | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/units-and-global-variables.rst b/docs/units-and-global-variables.rst index 8b6ffda7..d0a60d28 100644 --- a/docs/units-and-global-variables.rst +++ b/docs/units-and-global-variables.rst @@ -50,20 +50,20 @@ namespace and are mainly used to provide information about the blockchain. Block and Transaction Properties -------------------------------- - - ``block.blockhash(uint blockNumber) returns (bytes32)``: hash of the given block - only works for 256 most recent blocks - - ``block.coinbase`` (``address``): current block miner's address - - ``block.difficulty`` (``uint``): current block difficulty - - ``block.gaslimit`` (``uint``): current block gaslimit - - ``block.number`` (``uint``): current block number - - ``block.timestamp`` (``uint``): current block timestamp - - ``msg.data`` (``bytes``): complete calldata - - ``msg.gas`` (``uint``): remaining gas - - ``msg.sender`` (``address``): sender of the message (current call) - - ``msg.sig`` (``bytes4``): first four bytes of the calldata (i.e. function identifier) - - ``msg.value`` (``uint``): number of wei sent with the message - - ``now`` (``uint``): current block timestamp (alias for ``block.timestamp``) - - ``tx.gasprice`` (``uint``): gas price of the transaction - - ``tx.origin`` (``address``): sender of the transaction (full call chain) +- ``block.blockhash(uint blockNumber) returns (bytes32)``: hash of the given block - only works for 256 most recent blocks +- ``block.coinbase`` (``address``): current block miner's address +- ``block.difficulty`` (``uint``): current block difficulty +- ``block.gaslimit`` (``uint``): current block gaslimit +- ``block.number`` (``uint``): current block number +- ``block.timestamp`` (``uint``): current block timestamp +- ``msg.data`` (``bytes``): complete calldata +- ``msg.gas`` (``uint``): remaining gas +- ``msg.sender`` (``address``): sender of the message (current call) +- ``msg.sig`` (``bytes4``): first four bytes of the calldata (i.e. function identifier) +- ``msg.value`` (``uint``): number of wei sent with the message +- ``now`` (``uint``): current block timestamp (alias for ``block.timestamp``) +- ``tx.gasprice`` (``uint``): gas price of the transaction +- ``tx.origin`` (``address``): sender of the transaction (full call chain) .. note:: The values of all members of ``msg``, including ``msg.sender`` and -- cgit v1.2.3 From e72f819111a71ee53dcabec1bfead34fb0b9d349 Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Wed, 25 May 2016 10:37:30 -0400 Subject: Corrected descriptions of hashes --- docs/miscellaneous.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/miscellaneous.rst b/docs/miscellaneous.rst index f972532c..da35d9e1 100644 --- a/docs/miscellaneous.rst +++ b/docs/miscellaneous.rst @@ -171,9 +171,9 @@ Global Variables - ``now`` (``uint``): current block timestamp (alias for ``block.timestamp``) - ``tx.gasprice`` (``uint``): gas price of the transaction - ``tx.origin`` (``address``): sender of the transaction (full call chain) -- ``sha3(...) returns (bytes32)``: compute the Ethereum-SHA3 (KECCAK-256) hash of the (tightly packed) arguments -- ``sha256(...) returns (bytes32)``: compute the SHA256 hash of the (tightly packed) arguments -- ``ripemd160(...) returns (bytes20)``: compute RIPEMD of 256 the (tightly packed) arguments +- ``sha3(...) returns (bytes32)``: compute the Ethereum-SHA-3 (KECCAK-256) hash of the (tightly packed) arguments +- ``sha256(...) returns (bytes32)``: compute the SHA-256 hash of the (tightly packed) arguments +- ``ripemd160(...) returns (bytes20)``: compute the RIPEMD-160 hash of the (tightly packed) arguments - ``ecrecover(bytes32, uint8, bytes32, bytes32) returns (address)``: recover address associated with the public key from elliptic curve signature - ``addmod(uint x, uint y, uint k) returns (uint)``: compute ``(x + y) % k`` where the addition is performed with arbitrary precision and does not wrap around at ``2**256`` - ``mulmod(uint x, uint y, uint k) returns (uint)``: compute ``(x * y) % k`` where the multiplication is performed with arbitrary precision and does not wrap around at ``2**256`` -- cgit v1.2.3 From a29aaa3776f028d635307d6ef9a889ea3a01427d Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Wed, 25 May 2016 10:44:35 -0400 Subject: Added section on address-related constants --- docs/units-and-global-variables.rst | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/units-and-global-variables.rst b/docs/units-and-global-variables.rst index d0a60d28..594807c0 100644 --- a/docs/units-and-global-variables.rst +++ b/docs/units-and-global-variables.rst @@ -111,6 +111,21 @@ same as ``sha3(uint16(0x12))``. It might be that you run into Out-of-Gas for ``sha256``, ``ripemd160`` or ``ecrecover`` on a *private blockchain*. The reason for this is that those are implemented as so-called precompiled contracts and these contracts only really exist after they received the first message (although their contract code is hardcoded). Messages to non-existing contracts are more expensive and thus the execution runs into an Out-of-Gas error. A workaround for this problem is to first send e.g. 1 Wei to each of the contracts before you use them in your actual contracts. This is not an issue on the official or test net. +.. index:: send, balance + +Address Related +--------------- + +``
.balance`` (``uint256``): + balance of the address in Wei +``
.send(uint256) returns (bool)``: + send given amount of Wei to address, returns ``false`` on failure + +.. warning:: + Since it is possible for calls to ``send`` to fail, such as + if there are insufficient funds, it is good practice to + check the return value whenever calling ``send``. + .. index:: this, selfdestruct Contract Related -- cgit v1.2.3 From 2d32041552bf135d9b24b49c8ed526215c82ffdc Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Wed, 25 May 2016 10:52:11 -0400 Subject: Named the global function parameters --- docs/miscellaneous.rst | 6 +++--- docs/units-and-global-variables.rst | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/miscellaneous.rst b/docs/miscellaneous.rst index da35d9e1..b7a4bb7a 100644 --- a/docs/miscellaneous.rst +++ b/docs/miscellaneous.rst @@ -174,14 +174,14 @@ Global Variables - ``sha3(...) returns (bytes32)``: compute the Ethereum-SHA-3 (KECCAK-256) hash of the (tightly packed) arguments - ``sha256(...) returns (bytes32)``: compute the SHA-256 hash of the (tightly packed) arguments - ``ripemd160(...) returns (bytes20)``: compute the RIPEMD-160 hash of the (tightly packed) arguments -- ``ecrecover(bytes32, uint8, bytes32, bytes32) returns (address)``: recover address associated with the public key from elliptic curve signature +- ``ecrecover(bytes32 hash, uint8 v, bytes32 r, bytes32 s) returns (address)``: recover address associated with the public key from elliptic curve signature - ``addmod(uint x, uint y, uint k) returns (uint)``: compute ``(x + y) % k`` where the addition is performed with arbitrary precision and does not wrap around at ``2**256`` - ``mulmod(uint x, uint y, uint k) returns (uint)``: compute ``(x * y) % k`` where the multiplication is performed with arbitrary precision and does not wrap around at ``2**256`` - ``this`` (current contract's type): the current contract, explicitly convertible to ``address`` - ``super``: the contract one level higher in the inheritance hierarchy -- ``selfdestruct(address)``: destroy the current contract, sending its funds to the given address +- ``selfdestruct(address recipient)``: destroy the current contract, sending its funds to the given address - ``
.balance`` (``uint256``): balance of the address in Wei -- ``
.send(uint256) returns (bool)``: send given amount of Wei to address, returns ``false`` on failure +- ``
.send(uint256 amount) returns (bool)``: send given amount of Wei to address, returns ``false`` on failure .. index:: visibility, public, private, external, internal diff --git a/docs/units-and-global-variables.rst b/docs/units-and-global-variables.rst index 594807c0..3dc87841 100644 --- a/docs/units-and-global-variables.rst +++ b/docs/units-and-global-variables.rst @@ -94,7 +94,7 @@ Mathematical and Cryptographic Functions compute the SHA-256 hash of the (tightly packed) arguments ``ripemd160(...) returns (bytes20)``: compute RIPEMD-160 hash of the (tightly packed) arguments -``ecrecover(bytes32 data, uint8 v, bytes32 r, bytes32 s) returns (address)``: +``ecrecover(bytes32 hash, uint8 v, bytes32 r, bytes32 s) returns (address)``: recover the address associated with the public key from elliptic curve signature In the above, "tightly packed" means that the arguments are concatenated without padding. @@ -118,7 +118,7 @@ Address Related ``
.balance`` (``uint256``): balance of the address in Wei -``
.send(uint256) returns (bool)``: +``
.send(uint256 amount) returns (bool)``: send given amount of Wei to address, returns ``false`` on failure .. warning:: @@ -134,7 +134,7 @@ Contract Related ``this`` (current contract's type): the current contract, explicitly convertible to :ref:`address` -``selfdestruct(address)``: +``selfdestruct(address recipient)``: destroy the current contract, sending its funds to the given :ref:`address` Furthermore, all functions of the current contract are callable directly including the current function. -- cgit v1.2.3 From cb2a4df6e5345abd6a9c911d98092f534c217691 Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Wed, 1 Jun 2016 13:15:17 -0400 Subject: Corrected typo --- docs/types.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/types.rst b/docs/types.rst index 1d027d23..996383a9 100644 --- a/docs/types.rst +++ b/docs/types.rst @@ -95,7 +95,7 @@ the function ``call`` is provided which takes an arbitrary number of arguments o nameReg.call("register", "MyName"); nameReg.call(bytes4(sha3("fun(uint256)")), a); -``call`` returns a boolean indicating whether the invoked function terminated (``true``) or caused an EVM exception (`false:code:`). It is not possible to access the actual data returned (for this we would need to know the encoding and size in advance). +``call`` returns a boolean indicating whether the invoked function terminated (``true``) or caused an EVM exception (``false``). It is not possible to access the actual data returned (for this we would need to know the encoding and size in advance). In a similar way, the function ``delegatecall`` can be used: The difference is that only the code of the given address is used, all other aspects (storage, balance, ...) are taken from the current contract. The purpose of ``delegatecall`` is to use library code which is stored in another contract. The user has to ensure that the layout of storage in both contracts is suitable for delegatecall to be used. Prior to homestead, only a limited variant called ``callcode`` was available that did not provide access to the original ``msg.sender`` and ``msg.value`` values. -- cgit v1.2.3 From 9da7a4c17c2245e869475d031cb23587c33f5045 Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Wed, 1 Jun 2016 13:18:43 -0400 Subject: Link address-type and address-global methods --- docs/types.rst | 2 ++ docs/units-and-global-variables.rst | 2 ++ 2 files changed, 4 insertions(+) diff --git a/docs/types.rst b/docs/types.rst index 996383a9..2cd3654b 100644 --- a/docs/types.rst +++ b/docs/types.rst @@ -72,6 +72,8 @@ Members of Addresses * ``balance`` and ``send`` +For a quick reference, see :ref:`balance` and :ref:`send`. + It is possible to query the balance of an address using the property ``balance`` and to send Ether (in units of wei) to an address using the ``send`` function: diff --git a/docs/units-and-global-variables.rst b/docs/units-and-global-variables.rst index 3dc87841..aa3551bf 100644 --- a/docs/units-and-global-variables.rst +++ b/docs/units-and-global-variables.rst @@ -121,6 +121,8 @@ Address Related ``
.send(uint256 amount) returns (bool)``: send given amount of Wei to address, returns ``false`` on failure +For more information, see the section on :ref:`address`. + .. warning:: Since it is possible for calls to ``send`` to fail, such as if there are insufficient funds, it is good practice to -- cgit v1.2.3 From 84a8c0c008acf80a70c60dbfc0f5c3666abcd676 Mon Sep 17 00:00:00 2001 From: chriseth Date: Tue, 31 May 2016 14:13:02 +0200 Subject: Document some pitfalls in connection with "send". --- docs/miscellaneous.rst | 18 ++++++++++++++++++ docs/types.rst | 6 ++++++ 2 files changed, 24 insertions(+) diff --git a/docs/miscellaneous.rst b/docs/miscellaneous.rst index b7a4bb7a..504c4e0e 100644 --- a/docs/miscellaneous.rst +++ b/docs/miscellaneous.rst @@ -148,6 +148,24 @@ Pitfalls Unfortunately, there are some subtleties the compiler does not yet warn you about. - In ``for (var i = 0; i < arrayName.length; i++) { ... }``, the type of ``i`` will be ``uint8``, because this is the smallest type that is required to hold the value ``0``. If the array has more than 255 elements, the loop will not terminate. +- If a contract receives Ether (without a function being called), the fallback function is executed. The contract can only rely + on the "gas stipend" (2300 gas) being available to it at that time. This stipend is not enough to access storage in any way. + To be sure that your contract can receive Ether in that way, check the gas requirements of the fallback function. +- If you want to send ether using ``address.send``, there are certain details to be aware of: + 1. If the recipient is a contract, it causes its fallback function to be executed which can in turn call back into the sending contract + 2. Sending Ether can fail due to the call depth going above 1024. Since the caller is in total control of the call + depth, they can force the transfer to fail, so make sure to always check the return value of ``send``. Better yet, + write your contract using a pattern where the recipient can withdraw Ether instead. + 2. Sending Ether can also fail because the recipient goes out of gas (either explicitly by using ``throw`` or + because the operation is just too expensive). If the return value of ``send`` is checked, this might provide a + means for the recipient to block progress in the sending contract. Again, the best practise here is to use + a "withdraw" pattern instead of a "send" pattern. +- Loops that do not have a fixed number of iterations, e.g. loops that depends on storage values, have to be used carefully: + Due to the block gas limit, transactions can only consume a certain amount of gas. Either explicitly or just due to + normal operation, the number of iterations in a loop can grow beyond the block gas limit, which can cause the complete + contract to be stalled at a certain point. This does not apply at full extent to ``constant`` functions that are only executed + to read data from the blockchain. Still, such functions may be called by other contracts as part of on-chain operations + and stall those. Please be explicit about such cases in the documentation of your contracts. ********** Cheatsheet diff --git a/docs/types.rst b/docs/types.rst index 2cd3654b..6d4e928c 100644 --- a/docs/types.rst +++ b/docs/types.rst @@ -86,6 +86,12 @@ and to send Ether (in units of wei) to an address using the ``send`` function: .. note:: If ``x`` is a contract address, its code (more specifically: its fallback function, if present) will be executed together with the ``send`` call (this is a limitation of the EVM and cannot be prevented). If that execution runs out of gas or fails in any way, the Ether transfer will be reverted. In this case, ``send`` returns ``false``. +.. warning:: + There are some dangers in using ``send``: The transfer fails if the call stack depth is at 1023 + (this can always be forced by the caller) and it also fails if the recipient runs out of gas. So in order + to make safe Ether transfers, always check the return value of ``send`` or even better: + Use a pattern where the recipient withdraws the money. + * ``call``, ``callcode`` and ``delegatecall`` Furthermore, to interface with contracts that do not adhere to the ABI, -- cgit v1.2.3 From f03d315bad93f0c5660b5b83520ec8fdece7194b Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Wed, 1 Jun 2016 13:25:36 -0400 Subject: Updated incorrect list number --- docs/miscellaneous.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/miscellaneous.rst b/docs/miscellaneous.rst index 504c4e0e..ac41ebca 100644 --- a/docs/miscellaneous.rst +++ b/docs/miscellaneous.rst @@ -156,7 +156,7 @@ Unfortunately, there are some subtleties the compiler does not yet warn you abou 2. Sending Ether can fail due to the call depth going above 1024. Since the caller is in total control of the call depth, they can force the transfer to fail, so make sure to always check the return value of ``send``. Better yet, write your contract using a pattern where the recipient can withdraw Ether instead. - 2. Sending Ether can also fail because the recipient goes out of gas (either explicitly by using ``throw`` or + 3. Sending Ether can also fail because the recipient goes out of gas (either explicitly by using ``throw`` or because the operation is just too expensive). If the return value of ``send`` is checked, this might provide a means for the recipient to block progress in the sending contract. Again, the best practise here is to use a "withdraw" pattern instead of a "send" pattern. -- cgit v1.2.3 From 1f19b938366364acb7b628dbefa9af9249bf936d Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Wed, 1 Jun 2016 13:59:16 -0400 Subject: Copied warning message from cherry-picked commit --- docs/units-and-global-variables.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/units-and-global-variables.rst b/docs/units-and-global-variables.rst index aa3551bf..ee9d60d6 100644 --- a/docs/units-and-global-variables.rst +++ b/docs/units-and-global-variables.rst @@ -124,9 +124,10 @@ Address Related For more information, see the section on :ref:`address`. .. warning:: - Since it is possible for calls to ``send`` to fail, such as - if there are insufficient funds, it is good practice to - check the return value whenever calling ``send``. + There are some dangers in using ``send``: The transfer fails if the call stack depth is at 1023 + (this can always be forced by the caller) and it also fails if the recipient runs out of gas. So in order + to make safe Ether transfers, always check the return value of ``send`` or even better: + Use a pattern where the recipient withdraws the money. .. index:: this, selfdestruct -- cgit v1.2.3 From 4a2c8fa9b79c39ddb9918e435c4941c324a4ac4f Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Mon, 30 May 2016 13:36:14 -0400 Subject: uint20 is not a type --- docs/types.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/types.rst b/docs/types.rst index 6d4e928c..99fb7a3c 100644 --- a/docs/types.rst +++ b/docs/types.rst @@ -624,10 +624,10 @@ For convenience, it is not always necessary to explicitly specify the type of a variable, the compiler automatically infers it from the type of the first expression that is assigned to the variable:: - uint20 x = 0x123; + uint24 x = 0x123; var y = x; -Here, the type of ``y`` will be ``uint20``. Using ``var`` is not possible for function +Here, the type of ``y`` will be ``uint24``. Using ``var`` is not possible for function parameters or return parameters. .. warning:: -- cgit v1.2.3 From 0b4b5e10461d6dfefb8aea7eea107400e3de2c31 Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Thu, 2 Jun 2016 09:13:27 -0400 Subject: Make address link look better --- docs/units-and-global-variables.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/units-and-global-variables.rst b/docs/units-and-global-variables.rst index ee9d60d6..02cd134e 100644 --- a/docs/units-and-global-variables.rst +++ b/docs/units-and-global-variables.rst @@ -117,11 +117,9 @@ Address Related --------------- ``
.balance`` (``uint256``): - balance of the address in Wei + balance of the :ref:`address` in Wei ``
.send(uint256 amount) returns (bool)``: - send given amount of Wei to address, returns ``false`` on failure - -For more information, see the section on :ref:`address`. + send given amount of Wei to :ref:`address`, returns ``false`` on failure .. warning:: There are some dangers in using ``send``: The transfer fails if the call stack depth is at 1023 -- cgit v1.2.3 From fc121b9ba7665f4b0470b3f347a0cac51ac311e0 Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Thu, 2 Jun 2016 09:14:53 -0400 Subject: Documented max stack depth at 1024 --- docs/types.rst | 2 +- docs/units-and-global-variables.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/types.rst b/docs/types.rst index 99fb7a3c..16eccb16 100644 --- a/docs/types.rst +++ b/docs/types.rst @@ -87,7 +87,7 @@ and to send Ether (in units of wei) to an address using the ``send`` function: If ``x`` is a contract address, its code (more specifically: its fallback function, if present) will be executed together with the ``send`` call (this is a limitation of the EVM and cannot be prevented). If that execution runs out of gas or fails in any way, the Ether transfer will be reverted. In this case, ``send`` returns ``false``. .. warning:: - There are some dangers in using ``send``: The transfer fails if the call stack depth is at 1023 + There are some dangers in using ``send``: The transfer fails if the call stack depth is at 1024 (this can always be forced by the caller) and it also fails if the recipient runs out of gas. So in order to make safe Ether transfers, always check the return value of ``send`` or even better: Use a pattern where the recipient withdraws the money. diff --git a/docs/units-and-global-variables.rst b/docs/units-and-global-variables.rst index 02cd134e..3a12c630 100644 --- a/docs/units-and-global-variables.rst +++ b/docs/units-and-global-variables.rst @@ -122,7 +122,7 @@ Address Related send given amount of Wei to :ref:`address`, returns ``false`` on failure .. warning:: - There are some dangers in using ``send``: The transfer fails if the call stack depth is at 1023 + There are some dangers in using ``send``: The transfer fails if the call stack depth is at 1024 (this can always be forced by the caller) and it also fails if the recipient runs out of gas. So in order to make safe Ether transfers, always check the return value of ``send`` or even better: Use a pattern where the recipient withdraws the money. -- cgit v1.2.3 From c2bb2d2a724a03e95c2f83bd318c249468cf10fe Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Thu, 2 Jun 2016 09:22:24 -0400 Subject: Added newlines to fix build error --- docs/miscellaneous.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/miscellaneous.rst b/docs/miscellaneous.rst index ac41ebca..4e61b283 100644 --- a/docs/miscellaneous.rst +++ b/docs/miscellaneous.rst @@ -152,6 +152,7 @@ Unfortunately, there are some subtleties the compiler does not yet warn you abou on the "gas stipend" (2300 gas) being available to it at that time. This stipend is not enough to access storage in any way. To be sure that your contract can receive Ether in that way, check the gas requirements of the fallback function. - If you want to send ether using ``address.send``, there are certain details to be aware of: + 1. If the recipient is a contract, it causes its fallback function to be executed which can in turn call back into the sending contract 2. Sending Ether can fail due to the call depth going above 1024. Since the caller is in total control of the call depth, they can force the transfer to fail, so make sure to always check the return value of ``send``. Better yet, @@ -160,6 +161,7 @@ Unfortunately, there are some subtleties the compiler does not yet warn you abou because the operation is just too expensive). If the return value of ``send`` is checked, this might provide a means for the recipient to block progress in the sending contract. Again, the best practise here is to use a "withdraw" pattern instead of a "send" pattern. + - Loops that do not have a fixed number of iterations, e.g. loops that depends on storage values, have to be used carefully: Due to the block gas limit, transactions can only consume a certain amount of gas. Either explicitly or just due to normal operation, the number of iterations in a loop can grow beyond the block gas limit, which can cause the complete -- cgit v1.2.3 From a7b5e21e6672425cbbe2ac57ae2cf0bf40d62bec Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Thu, 2 Jun 2016 09:27:55 -0400 Subject: Fixed a bad reference --- docs/units-and-global-variables.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/units-and-global-variables.rst b/docs/units-and-global-variables.rst index 3a12c630..7fcb2d7a 100644 --- a/docs/units-and-global-variables.rst +++ b/docs/units-and-global-variables.rst @@ -111,7 +111,8 @@ same as ``sha3(uint16(0x12))``. It might be that you run into Out-of-Gas for ``sha256``, ``ripemd160`` or ``ecrecover`` on a *private blockchain*. The reason for this is that those are implemented as so-called precompiled contracts and these contracts only really exist after they received the first message (although their contract code is hardcoded). Messages to non-existing contracts are more expensive and thus the execution runs into an Out-of-Gas error. A workaround for this problem is to first send e.g. 1 Wei to each of the contracts before you use them in your actual contracts. This is not an issue on the official or test net. -.. index:: send, balance +.. _balance: +.. _send: Address Related --------------- -- cgit v1.2.3 From bb83fd5adb22fe919dca49cecd012c6dd4bc64f3 Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Thu, 2 Jun 2016 09:29:53 -0400 Subject: Changed reference name --- docs/types.rst | 2 +- docs/units-and-global-variables.rst | 3 +-- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/types.rst b/docs/types.rst index 16eccb16..6a69f5be 100644 --- a/docs/types.rst +++ b/docs/types.rst @@ -72,7 +72,7 @@ Members of Addresses * ``balance`` and ``send`` -For a quick reference, see :ref:`balance` and :ref:`send`. +For a quick reference, see :ref:`address_related`. It is possible to query the balance of an address using the property ``balance`` and to send Ether (in units of wei) to an address using the ``send`` function: diff --git a/docs/units-and-global-variables.rst b/docs/units-and-global-variables.rst index 7fcb2d7a..aa0056d2 100644 --- a/docs/units-and-global-variables.rst +++ b/docs/units-and-global-variables.rst @@ -111,8 +111,7 @@ same as ``sha3(uint16(0x12))``. It might be that you run into Out-of-Gas for ``sha256``, ``ripemd160`` or ``ecrecover`` on a *private blockchain*. The reason for this is that those are implemented as so-called precompiled contracts and these contracts only really exist after they received the first message (although their contract code is hardcoded). Messages to non-existing contracts are more expensive and thus the execution runs into an Out-of-Gas error. A workaround for this problem is to first send e.g. 1 Wei to each of the contracts before you use them in your actual contracts. This is not an issue on the official or test net. -.. _balance: -.. _send: +.. _address_related: Address Related --------------- -- cgit v1.2.3 From ccd54ed87e78a4d13968e1d585cd5238d5805789 Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Fri, 3 Jun 2016 09:20:18 -0400 Subject: Added back 'For more information...' statement --- docs/units-and-global-variables.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/units-and-global-variables.rst b/docs/units-and-global-variables.rst index aa0056d2..167c694d 100644 --- a/docs/units-and-global-variables.rst +++ b/docs/units-and-global-variables.rst @@ -121,6 +121,8 @@ Address Related ``
.send(uint256 amount) returns (bool)``: send given amount of Wei to :ref:`address`, returns ``false`` on failure +For more information, see the section on :ref:`address`. + .. warning:: There are some dangers in using ``send``: The transfer fails if the call stack depth is at 1024 (this can always be forced by the caller) and it also fails if the recipient runs out of gas. So in order -- cgit v1.2.3