diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/abi-spec.rst | 6 | ||||
| -rw-r--r-- | docs/common-patterns.rst | 8 | ||||
| -rw-r--r-- | docs/conf.py | 2 | ||||
| -rw-r--r-- | docs/contracts.rst | 71 | ||||
| -rw-r--r-- | docs/control-structures.rst | 4 | ||||
| -rw-r--r-- | docs/docs-css/custom.css | 14 | ||||
| -rw-r--r-- | docs/frequently-asked-questions.rst | 13 | ||||
| -rw-r--r-- | docs/grammar.txt | 7 | ||||
| -rw-r--r-- | docs/introduction-to-smart-contracts.rst | 4 | ||||
| -rw-r--r-- | docs/miscellaneous.rst | 7 | ||||
| -rw-r--r-- | docs/security-considerations.rst | 13 | ||||
| -rw-r--r-- | docs/style-guide.rst | 98 | ||||
| -rw-r--r-- | docs/types.rst | 33 |
13 files changed, 124 insertions, 156 deletions
diff --git a/docs/abi-spec.rst b/docs/abi-spec.rst index e4f8ed4f..366ca951 100644 --- a/docs/abi-spec.rst +++ b/docs/abi-spec.rst @@ -437,10 +437,10 @@ For example, :: - pragma solidity ^0.4.0; + pragma solidity >0.4.24; contract Test { - function Test() public { b = 0x12345678901234567890123456789012; } + constructor() public { b = 0x12345678901234567890123456789012; } event Event(uint indexed a, bytes32 b); event Event2(uint indexed a, bytes32 b); function foo(uint a) public { emit Event(a, b); } @@ -582,4 +582,4 @@ Note that constants will be packed using the minimum number of bytes required to This means that, for example, ``abi.encodePacked(0) == abi.encodePacked(uint8(0)) == hex"00"`` and ``abi.encodePacked(0x12345678) == abi.encodePacked(uint32(0x12345678)) == hex"12345678"``. -If padding is needed, explicit type conversions can be used: ``abi.encodePacked(uint16(0x12)) == hex"0012"``.
\ No newline at end of file +If padding is needed, explicit type conversions can be used: ``abi.encodePacked(uint16(0x12)) == hex"0012"``. diff --git a/docs/common-patterns.rst b/docs/common-patterns.rst index 739e136f..7c38b0e7 100644 --- a/docs/common-patterns.rst +++ b/docs/common-patterns.rst @@ -28,7 +28,7 @@ become the new richest. :: - pragma solidity ^0.4.11; + pragma solidity >0.4.24; contract WithdrawalContract { address public richest; @@ -36,7 +36,7 @@ become the new richest. mapping (address => uint) pendingWithdrawals; - function WithdrawalContract() public payable { + constructor() public payable { richest = msg.sender; mostSent = msg.value; } @@ -65,13 +65,13 @@ This is as opposed to the more intuitive sending pattern: :: - pragma solidity ^0.4.11; + pragma solidity >0.4.24; contract SendContract { address public richest; uint public mostSent; - function SendContract() public payable { + constructor() public payable { richest = msg.sender; mostSent = msg.value; } diff --git a/docs/conf.py b/docs/conf.py index fdb67367..55f4f1a8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -27,6 +27,8 @@ def setup(sphinx): from pygments_lexer_solidity import SolidityLexer sphinx.add_lexer('Solidity', SolidityLexer()) + sphinx.add_stylesheet('css/custom.css') + # -- General configuration ------------------------------------------------ # If your documentation needs a minimal Sphinx version, state it here. diff --git a/docs/contracts.rst b/docs/contracts.rst index 19eba047..53e50656 100644 --- a/docs/contracts.rst +++ b/docs/contracts.rst @@ -301,10 +301,10 @@ inheritable properties of contracts and may be overridden by derived contracts. :: - pragma solidity ^0.4.22; + pragma solidity >0.4.24; contract owned { - function owned() public { owner = msg.sender; } + constructor() public { owner = msg.sender; } address owner; // This contract only defines a modifier but does not use @@ -346,7 +346,7 @@ inheritable properties of contracts and may be overridden by derived contracts. mapping (address => bool) registeredAddresses; uint price; - function Register(uint initialPrice) public { price = initialPrice; } + constructor(uint initialPrice) public { price = initialPrice; } // It is important to also provide the // `payable` keyword here, otherwise the function will @@ -473,7 +473,7 @@ The following statements are considered modifying the state: } .. note:: - ``constant`` on functions is an alias to ``view``, but this is deprecated and will be dropped in version 0.5.0. + ``constant`` on functions used to be an alias to ``view``, but this was dropped in version 0.5.0. .. note:: Getter methods are marked ``view``. @@ -485,9 +485,6 @@ The following statements are considered modifying the state: prevent modifications to the state on the level of the EVM by adding ``pragma experimental "v0.5.0";`` -.. warning:: - The compiler does not enforce yet that a ``view`` method is not modifying state. It raises a warning though. - .. index:: ! pure function, function;pure .. _pure-functions: @@ -529,12 +526,15 @@ In addition to the list of state modifying statements explained above, the follo It is a non-circumventable runtime checks done by the EVM. .. warning:: - Before version 0.4.17 the compiler didn't enforce that ``pure`` is not reading the state. + Before version 0.4.17 the compiler did not enforce that ``pure`` is not reading the state. It is a compile-time type check, which can be circumvented doing invalid explicit conversions between contract types, because the compiler can verify that the type of the contract does not do state-changing operations, but it cannot check that the contract that will be called at runtime is actually of that type. +.. warning:: + Before version 0.5.0 the compiler did not enforce that ``view`` is not writing the state. + .. index:: ! fallback function, function;fallback .. _fallback-function: @@ -543,7 +543,7 @@ Fallback Function ================= A contract can have exactly one unnamed function. This function cannot have -arguments and cannot return anything. +arguments, cannot return anything and has to have ``external`` visibility. It is executed on a call to the contract if none of the other functions match the given function identifier (or if no data was supplied at all). @@ -591,7 +591,7 @@ Like any function, the fallback function can execute complex operations as long // Sending Ether to this contract will cause an exception, // because the fallback function does not have the `payable` // modifier. - function() public { x = 1; } + function() external { x = 1; } uint x; } @@ -599,7 +599,7 @@ Like any function, the fallback function can execute complex operations as long // This contract keeps all Ether sent to it with no way // to get it back. contract Sink { - function() public payable { } + function() external payable { } } contract Caller { @@ -990,7 +990,7 @@ default constructor: ``contructor() public {}``. :: - pragma solidity ^0.4.22; + pragma solidity >0.4.24; contract A { uint public a; @@ -1006,24 +1006,8 @@ default constructor: ``contructor() public {}``. A constructor set as ``internal`` causes the contract to be marked as :ref:`abstract <abstract-contract>`. -.. note :: - Prior to version 0.4.22, constructors were defined as functions with the same name as the contract. This syntax is now deprecated. - -:: - - pragma solidity ^0.4.11; - - contract A { - uint public a; - - function A(uint _a) internal { - a = _a; - } - } - - contract B is A(1) { - function B() public {} - } +.. warning :: + Prior to version 0.4.22, constructors were defined as functions with the same name as the contract. This syntax was deprecated and is not allowed anymore in version 0.5.0. .. index:: ! base;constructor @@ -1344,9 +1328,9 @@ custom types without the overhead of external function calls: using BigInt for BigInt.bigint; function f() public pure { - var x = BigInt.fromUint(7); - var y = BigInt.fromUint(uint(-1)); - var z = x.add(y); + BigInt.bigint memory x = BigInt.fromUint(7); + BigInt.bigint memory y = BigInt.fromUint(uint(-1)); + BigInt.bigint memory z = x.add(y); } } @@ -1404,22 +1388,23 @@ Using For The directive ``using A for B;`` can be used to attach library functions (from the library ``A``) to any type (``B``). These functions will receive the object they are called on -as their first parameter (like the ``self`` variable in -Python). +as their first parameter (like the ``self`` variable in Python). The effect of ``using A for *;`` is that the functions from -the library ``A`` are attached to any type. +the library ``A`` are attached to *any* type. -In both situations, all functions, even those where the -type of the first parameter does not match the type of -the object, are attached. The type is checked at the +In both situations, *all* functions in the library are attached, +even those where the type of the first parameter does not +match the type of the object. The type is checked at the point the function is called and function overload resolution is performed. -The ``using A for B;`` directive is active for the current -scope, which is limited to a contract for now but will -be lifted to the global scope later, so that by including -a module, its data types including library functions are +The ``using A for B;`` directive is active only within the current +contract, including within all of its functions, and has no effect +outside of the contract in which it is used. The directive +may only be used inside a contract, not inside any of its functions. + +By including a library, its data types including library functions are available without having to add further code. Let us rewrite the set example from the diff --git a/docs/control-structures.rst b/docs/control-structures.rst index cc1f7ca5..8ced0fbc 100644 --- a/docs/control-structures.rst +++ b/docs/control-structures.rst @@ -225,11 +225,11 @@ creation-dependencies are not possible. :: - pragma solidity ^0.4.0; + pragma solidity >0.4.24; contract D { uint x; - function D(uint a) public payable { + constructor(uint a) public payable { x = a; } } diff --git a/docs/docs-css/custom.css b/docs/docs-css/custom.css new file mode 100644 index 00000000..970148ed --- /dev/null +++ b/docs/docs-css/custom.css @@ -0,0 +1,14 @@ +pre { + white-space: pre-wrap; /* css-3 */ + white-space: -moz-pre-wrap; /* Mozilla, since 1999 */ + white-space: -pre-wrap; /* Opera 4-6 */ + white-space: -o-pre-wrap; /* Opera 7 */ + word-wrap: break-word; +} + +.wy-table-responsive table td, .wy-table-responsive table th { + white-space: pre-wrap; +} +.wy-table-responsive table td, .wy-table-responsive table th { + white-space: pre-wrap; +} diff --git a/docs/frequently-asked-questions.rst b/docs/frequently-asked-questions.rst index ca5a1aee..0d6fa033 100644 --- a/docs/frequently-asked-questions.rst +++ b/docs/frequently-asked-questions.rst @@ -136,14 +136,9 @@ See `struct_and_for_loop_tester.sol <https://github.com/fivedogit/solidity-baby- How do for loops work? ====================== -Very similar to JavaScript. There is one point to watch out for, though: +Very similar to JavaScript. Such as the following example: -If you use ``for (var i = 0; i < a.length; i ++) { a[i] = i; }``, then -the type of ``i`` will be inferred only from ``0``, whose type is ``uint8``. -This means that if ``a`` has more than ``255`` elements, your loop will -not terminate because ``i`` can only hold values up to ``255``. - -Better use ``for (uint i = 0; i < a.length...`` +``for (uint i = 0; i < a.length; i ++) { a[i] = i; }`` See `struct_and_for_loop_tester.sol <https://github.com/fivedogit/solidity-baby-steps/blob/master/contracts/65_struct_and_for_loop_tester.sol>`_. @@ -426,10 +421,10 @@ In the case of a ``contract A`` calling a new instance of ``contract B``, parent You will need to make sure that you have both contracts aware of each other's presence and that ``contract B`` has a ``payable`` constructor. In this example:: - pragma solidity ^0.4.0; + pragma solidity >0.4.24; contract B { - function B() public payable {} + constructor() public payable {} } contract A { diff --git a/docs/grammar.txt b/docs/grammar.txt index 5d977827..7b29fc62 100644 --- a/docs/grammar.txt +++ b/docs/grammar.txt @@ -58,7 +58,7 @@ ArrayTypeName = TypeName '[' Expression? ']' FunctionTypeName = 'function' FunctionTypeParameterList ( 'internal' | 'external' | StateMutability )* ( 'returns' FunctionTypeParameterList )? StorageLocation = 'memory' | 'storage' | 'calldata' -StateMutability = 'pure' | 'constant' | 'view' | 'payable' +StateMutability = 'pure' | 'view' | 'payable' Block = '{' Statement* '}' Statement = IfStatement | WhileStatement | ForStatement | Block | InlineAssemblyStatement | @@ -78,7 +78,7 @@ Break = 'break' Return = 'return' Expression? Throw = 'throw' EmitStatement = 'emit' FunctionCall -VariableDefinition = ('var' IdentifierList | VariableDeclaration | '(' VariableDeclaration? (',' VariableDeclaration? )* ')' ) ( '=' Expression )? +VariableDefinition = (VariableDeclaration | '(' VariableDeclaration? (',' VariableDeclaration? )* ')' ) ( '=' Expression )? IdentifierList = '(' ( Identifier? ',' )* Identifier? ')' // Precedence by order (see github.com/ethereum/solidity/pull/732) @@ -140,8 +140,7 @@ TupleExpression = '(' ( Expression? ( ',' Expression? )* )? ')' ElementaryTypeNameExpression = ElementaryTypeName -ElementaryTypeName = 'address' | 'bool' | 'string' | 'var' - | Int | Uint | Byte | Fixed | Ufixed +ElementaryTypeName = 'address' | 'bool' | 'string' | Int | Uint | Byte | Fixed | Ufixed Int = 'int' | 'int8' | 'int16' | 'int24' | 'int32' | 'int40' | 'int48' | 'int56' | 'int64' | 'int72' | 'int80' | 'int88' | 'int96' | 'int104' | 'int112' | 'int120' | 'int128' | 'int136' | 'int144' | 'int152' | 'int160' | 'int168' | 'int176' | 'int184' | 'int192' | 'int200' | 'int208' | 'int216' | 'int224' | 'int232' | 'int240' | 'int248' | 'int256' diff --git a/docs/introduction-to-smart-contracts.rst b/docs/introduction-to-smart-contracts.rst index 71f9bd8e..e1b61d8b 100644 --- a/docs/introduction-to-smart-contracts.rst +++ b/docs/introduction-to-smart-contracts.rst @@ -80,7 +80,7 @@ registering with username and password — all you need is an Ethereum keypair. :: - pragma solidity ^0.4.21; + pragma solidity >0.4.24; contract Coin { // The keyword "public" makes those variables @@ -94,7 +94,7 @@ registering with username and password — all you need is an Ethereum keypair. // This is the constructor whose code is // run only when the contract is created. - function Coin() public { + constructor() public { minter = msg.sender; } diff --git a/docs/miscellaneous.rst b/docs/miscellaneous.rst index 30ece7e1..1d5add9a 100644 --- a/docs/miscellaneous.rst +++ b/docs/miscellaneous.rst @@ -157,7 +157,7 @@ These steps are applied to each basic block and the newly generated code is used :: - var x = 7; + uint x = 7; data[7] = 9; if (data[x] != x + 2) return 2; @@ -397,11 +397,10 @@ Function Visibility Specifiers Modifiers ========= -- ``pure`` for functions: Disallows modification or access of state - this is not enforced yet. -- ``view`` for functions: Disallows modification of state - this is not enforced yet. +- ``pure`` for functions: Disallows modification or access of state. +- ``view`` for functions: Disallows modification of state. - ``payable`` for functions: Allows them to receive Ether together with a call. - ``constant`` for state variables: Disallows assignment (except initialisation), does not occupy storage slot. -- ``constant`` for functions: Same as ``view``. - ``anonymous`` for events: Does not store event signature as topic. - ``indexed`` for event parameters: Stores the parameter as topic. diff --git a/docs/security-considerations.rst b/docs/security-considerations.rst index 52a755ca..afdecb98 100644 --- a/docs/security-considerations.rst +++ b/docs/security-considerations.rst @@ -103,7 +103,7 @@ outlined further below: mapping(address => uint) shares; /// Withdraw your share. function withdraw() public { - var share = shares[msg.sender]; + uint share = shares[msg.sender]; shares[msg.sender] = 0; msg.sender.transfer(share); } @@ -180,13 +180,13 @@ Never use tx.origin for authorization. Let's say you have a wallet contract like :: - pragma solidity ^0.4.11; + pragma solidity >0.4.24; // THIS CONTRACT CONTAINS A BUG - DO NOT USE contract TxUserWallet { address owner; - function TxUserWallet() public { + constructor() public { owner = msg.sender; } @@ -200,7 +200,7 @@ Now someone tricks you into sending ether to the address of this attack wallet: :: - pragma solidity ^0.4.11; + pragma solidity >0.4.24; interface TxUserWallet { function transferTo(address dest, uint amount) public; @@ -209,11 +209,11 @@ Now someone tricks you into sending ether to the address of this attack wallet: contract TxAttackWallet { address owner; - function TxAttackWallet() public { + constructor() public { owner = msg.sender; } - function() public { + function() external { TxUserWallet(msg.sender).transferTo(owner, msg.sender.balance); } } @@ -224,7 +224,6 @@ If your wallet had checked ``msg.sender`` for authorization, it would get the ad Minor Details ============= -- 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. - Types that do not occupy the full 32 bytes might contain "dirty higher order bits". This is especially important if you access ``msg.data`` - it poses a malleability risk: You can craft transactions that call a function ``f(uint8 x)`` with a raw byte argument diff --git a/docs/style-guide.rst b/docs/style-guide.rst index 6b28f2ab..8311e925 100644 --- a/docs/style-guide.rst +++ b/docs/style-guide.rst @@ -114,15 +114,15 @@ No:: .. _maximum_line_length: -Maximum Line Length +Maximum Line Length =================== -Keeping lines under the `PEP 8 recommendation <https://www.python.org/dev/peps/pep-0008/#maximum-line-length>`_ to a maximum of 79 (or 99) +Keeping lines under the `PEP 8 recommendation <https://www.python.org/dev/peps/pep-0008/#maximum-line-length>`_ to a maximum of 79 (or 99) characters helps readers easily parse the code. Wrapped lines should conform to the following guidelines. -1. The first argument should not be attached to the opening parenthesis. +1. The first argument should not be attached to the opening parenthesis. 2. One, and only one, indent should be used. 3. Each argument should fall on its own line. 4. The terminating element, :code:`);`, should be placed on the final line by itself. @@ -132,38 +132,38 @@ Function Calls Yes:: thisFunctionCallIsReallyLong( - longArgument1, - longArgument2, + longArgument1, + longArgument2, longArgument3 ); No:: - thisFunctionCallIsReallyLong(longArgument1, - longArgument2, + thisFunctionCallIsReallyLong(longArgument1, + longArgument2, longArgument3 ); - - thisFunctionCallIsReallyLong(longArgument1, - longArgument2, + + thisFunctionCallIsReallyLong(longArgument1, + longArgument2, longArgument3 - ); - + ); + thisFunctionCallIsReallyLong( longArgument1, longArgument2, longArgument3 - ); + ); thisFunctionCallIsReallyLong( - longArgument1, - longArgument2, + longArgument1, + longArgument2, longArgument3 ); thisFunctionCallIsReallyLong( - longArgument1, - longArgument2, - longArgument3); + longArgument1, + longArgument2, + longArgument3); Assignment Statements @@ -215,7 +215,7 @@ No:: recipient, publicKey, amount, - options); + options); Source File Encoding ==================== @@ -274,11 +274,11 @@ Within a grouping, place the ``view`` and ``pure`` functions last. Yes:: contract A { - function A() public { + constructor() public { ... } - function() public { + function() external { ... } @@ -308,17 +308,17 @@ No:: // External functions // ... + function() external { + ... + } + // Private functions // ... // Public functions // ... - function A() public { - ... - } - - function() public { + constructor() public { ... } @@ -374,13 +374,13 @@ Don't include a whitespace in the fallback function: Yes:: - function() public { + function() external { ... } No:: - function () public { + function () external { ... } @@ -529,7 +529,7 @@ No:: function increment(uint x) public pure returns (uint) { return x + 1;} -You should explicitly label the visibility of all functions, including constructors. +You should explicitly label the visibility of all functions, including constructors. Yes:: @@ -540,7 +540,7 @@ Yes:: No:: function implicitlyPublic(uint val) { - doSomething(); + doSomething(); } The visibility modifier for a function should come before any custom @@ -663,19 +663,19 @@ Yes:: address a, address b, address c - ) - public + ) + public returns ( - address someAddressName, - uint256 LongArgument, + address someAddressName, + uint256 LongArgument, uint256 Argument ) - { + { doSomething() - + return ( - veryLongReturnArg1, - veryLongReturnArg2, + veryLongReturnArg1, + veryLongReturnArg2, veryLongReturnArg3 ); } @@ -686,16 +686,16 @@ No:: address a, address b, address c - ) - public - returns (address someAddressName, - uint256 LongArgument, + ) + public + returns (address someAddressName, + uint256 LongArgument, uint256 Argument) - { + { doSomething() - - return (veryLongReturnArg1, - veryLongReturnArg1, + + return (veryLongReturnArg1, + veryLongReturnArg1, veryLongReturnArg1); } @@ -706,7 +706,7 @@ manner as modifiers if the function declaration is long or hard to read. Yes:: contract A is B, C, D { - function A(uint param1, uint param2, uint param3, uint param4, uint param5) + constructor(uint param1, uint param2, uint param3, uint param4, uint param5) B(param1) C(param2, param3) D(param4) @@ -719,7 +719,7 @@ Yes:: No:: contract A is B, C, D { - function A(uint param1, uint param2, uint param3, uint param4, uint param5) + constructor(uint param1, uint param2, uint param3, uint param4, uint param5) B(param1) C(param2, param3) D(param4) @@ -730,7 +730,7 @@ No:: } contract A is B, C, D { - function A(uint param1, uint param2, uint param3, uint param4, uint param5) + constructor(uint param1, uint param2, uint param3, uint param4, uint param5) B(param1) C(param2, param3) D(param4) diff --git a/docs/types.rst b/docs/types.rst index 528807d9..217a2273 100644 --- a/docs/types.rst +++ b/docs/types.rst @@ -7,10 +7,8 @@ Types ***** Solidity is a statically typed language, which means that the type of each -variable (state and local) needs to be specified (or at least known - -see :ref:`type-deduction` below) at -compile-time. Solidity provides several elementary types which can be combined -to form complex types. +variable (state and local) needs to be specified. +Solidity provides several elementary types which can be combined to form complex types. In addition, types can interact with each other in expressions containing operators. For a quick reference of the various operators, see :ref:`order`. @@ -378,7 +376,7 @@ be passed via and returned from external function calls. Function types are notated as follows:: - function (<parameter types>) {internal|external} [pure|constant|view|payable] [returns (<return types>)] + function (<parameter types>) {internal|external} [pure|view|payable] [returns (<return types>)] In contrast to the parameter types, the return types cannot be empty - if the function type should not return anything, the whole ``returns (<return types>)`` @@ -548,7 +546,7 @@ memory-stored reference type do not create a copy. // the data location of memoryArray is memory function f(uint[] memoryArray) public { x = memoryArray; // works, copies the whole array to storage - var y = x; // works, assigns a pointer, data location of y is storage + uint[] storage y = x; // works, assigns a pointer, data location of y is storage y[7]; // fine, returns the 8th element y.length = 2; // fine, modifies x through y delete x; // fine, clears the array, also modifies y @@ -986,26 +984,3 @@ converted to a matching size. This makes alignment and padding explicit:: bytes32(uint256(x)); // pad on the left bytes32(bytes2(x)); // pad on the right -.. index:: ! type;deduction, ! var - -.. _type-deduction: - -Type Deduction -============== - -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:: - - uint24 x = 0x123; - var y = x; - -Here, the type of ``y`` will be ``uint24``. Using ``var`` is not possible for function -parameters or return parameters. - -.. warning:: - The type is only deduced from the first assignment, so - the loop in the following snippet is infinite, as ``i`` will have the type - ``uint8`` and the highest value of this type is smaller than ``2000``. - ``for (var i = 0; i < 2000; i++) { ... }`` - |