From a011ffdd486990ec7d2e9dc0b25ed04c63b84974 Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Tue, 24 May 2016 12:09:59 -0400 Subject: [PATCH 01/23] 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 178f34d9f..61081e1c9 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 ---------------------- From 91459ffc76f2c0e7e42e967b9b6278ddbe37166e Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Wed, 25 May 2016 10:14:57 -0400 Subject: [PATCH 02/23] 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 8f910c80e..dd9f4a6fb 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 From bc3e17192f43f746bfa68ffac55f3e888195a4e1 Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Wed, 25 May 2016 10:19:52 -0400 Subject: [PATCH 03/23] 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 6b327c56e..787ff23a5 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 dd9f4a6fb..05b55cc93 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 From a6785113b5e145418ab09aa2a77319aa33dbf0c9 Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Wed, 25 May 2016 10:21:03 -0400 Subject: [PATCH 04/23] 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 787ff23a5..4608f32dc 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 05b55cc93..40cf7dacb 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 From c0e10b1cf07d0ae5414ede6d66961fb87e832f64 Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Wed, 25 May 2016 10:22:04 -0400 Subject: [PATCH 05/23] 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 4608f32dc..5e9c1375a 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 From 2667874587b831fce36fc12b60a6b6588dfc463b Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Wed, 25 May 2016 10:22:31 -0400 Subject: [PATCH 06/23] 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 5e9c1375a..01a7a04c4 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 From aafc65a2750fa1fc7ebb27a87d6024571e526318 Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Wed, 25 May 2016 10:27:46 -0400 Subject: [PATCH 07/23] 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 01a7a04c4..f972532c1 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 40cf7dacb..8b6ffda7f 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)``: From 0c03577adeb4a396d2e56c4f65d7fd4506baad7e Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Wed, 25 May 2016 10:32:53 -0400 Subject: [PATCH 08/23] 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 8b6ffda7f..d0a60d288 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 From e72f819111a71ee53dcabec1bfead34fb0b9d349 Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Wed, 25 May 2016 10:37:30 -0400 Subject: [PATCH 09/23] 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 f972532c1..da35d9e15 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`` From a29aaa3776f028d635307d6ef9a889ea3a01427d Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Wed, 25 May 2016 10:44:35 -0400 Subject: [PATCH 10/23] 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 d0a60d288..594807c00 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 From 2d32041552bf135d9b24b49c8ed526215c82ffdc Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Wed, 25 May 2016 10:52:11 -0400 Subject: [PATCH 11/23] 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 da35d9e15..b7a4bb7ac 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 594807c00..3dc87841e 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. From cb2a4df6e5345abd6a9c911d98092f534c217691 Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Wed, 1 Jun 2016 13:15:17 -0400 Subject: [PATCH 12/23] Corrected typo --- docs/types.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/types.rst b/docs/types.rst index 1d027d23e..996383a9a 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. From 9da7a4c17c2245e869475d031cb23587c33f5045 Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Wed, 1 Jun 2016 13:18:43 -0400 Subject: [PATCH 13/23] 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 996383a9a..2cd3654b7 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 3dc87841e..aa3551bf0 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 From 84a8c0c008acf80a70c60dbfc0f5c3666abcd676 Mon Sep 17 00:00:00 2001 From: chriseth Date: Tue, 31 May 2016 14:13:02 +0200 Subject: [PATCH 14/23] 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 b7a4bb7ac..504c4e0e9 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 2cd3654b7..6d4e928cc 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, From f03d315bad93f0c5660b5b83520ec8fdece7194b Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Wed, 1 Jun 2016 13:25:36 -0400 Subject: [PATCH 15/23] 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 504c4e0e9..ac41ebcab 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. From 1f19b938366364acb7b628dbefa9af9249bf936d Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Wed, 1 Jun 2016 13:59:16 -0400 Subject: [PATCH 16/23] 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 aa3551bf0..ee9d60d63 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 From 4a2c8fa9b79c39ddb9918e435c4941c324a4ac4f Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Mon, 30 May 2016 13:36:14 -0400 Subject: [PATCH 17/23] 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 6d4e928cc..99fb7a3c3 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:: From 0b4b5e10461d6dfefb8aea7eea107400e3de2c31 Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Thu, 2 Jun 2016 09:13:27 -0400 Subject: [PATCH 18/23] 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 ee9d60d63..02cd134e6 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 From fc121b9ba7665f4b0470b3f347a0cac51ac311e0 Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Thu, 2 Jun 2016 09:14:53 -0400 Subject: [PATCH 19/23] 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 99fb7a3c3..16eccb162 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 02cd134e6..3a12c630a 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. From c2bb2d2a724a03e95c2f83bd318c249468cf10fe Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Thu, 2 Jun 2016 09:22:24 -0400 Subject: [PATCH 20/23] 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 ac41ebcab..4e61b2839 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 From a7b5e21e6672425cbbe2ac57ae2cf0bf40d62bec Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Thu, 2 Jun 2016 09:27:55 -0400 Subject: [PATCH 21/23] 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 3a12c630a..7fcb2d7ad 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 --------------- From bb83fd5adb22fe919dca49cecd012c6dd4bc64f3 Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Thu, 2 Jun 2016 09:29:53 -0400 Subject: [PATCH 22/23] 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 16eccb162..6a69f5bec 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 7fcb2d7ad..aa0056d28 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 --------------- From ccd54ed87e78a4d13968e1d585cd5238d5805789 Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Fri, 3 Jun 2016 09:20:18 -0400 Subject: [PATCH 23/23] 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 aa0056d28..167c694db 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