aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/common-patterns.rst1
-rw-r--r--docs/conf.py2
-rw-r--r--docs/contracts.rst8
-rw-r--r--docs/control-structures.rst6
-rw-r--r--docs/index.rst9
-rw-r--r--docs/installing-solidity.rst48
-rw-r--r--docs/layout-of-source-files.rst24
-rw-r--r--docs/miscellaneous.rst118
-rw-r--r--docs/security-considerations.rst45
-rw-r--r--docs/style-guide.rst2
-rw-r--r--docs/types.rst10
11 files changed, 219 insertions, 54 deletions
diff --git a/docs/common-patterns.rst b/docs/common-patterns.rst
index 9096571e..422e2758 100644
--- a/docs/common-patterns.rst
+++ b/docs/common-patterns.rst
@@ -201,6 +201,7 @@ function finishes.
now >= creationTime + 12 days)
nextStage();
// The other stages transition by transaction
+ _
}
// Order of the modifiers matters here!
diff --git a/docs/conf.py b/docs/conf.py
index 8776ec43..d0e26362 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -49,7 +49,7 @@ master_doc = 'index'
# General information about the project.
project = 'Solidity'
-copyright = '2015, Ethereum'
+copyright = '2016, Ethereum'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
diff --git a/docs/contracts.rst b/docs/contracts.rst
index c02c1490..3d592ecf 100644
--- a/docs/contracts.rst
+++ b/docs/contracts.rst
@@ -23,6 +23,9 @@ name as the contract) is executed once.
From ``web3.js``, i.e. the JavaScript
API, this is done as follows::
+ // Need to specify some source including contract name for the data param below
+ var source = "contract CONTRACT_NAME { function CONTRACT_NAME(unit a, uint b) {} }";
+
// The json abi array generated by the compiler
var abiArray = [
{
@@ -41,7 +44,8 @@ API, this is done as follows::
}
];
- var MyContract = web3.eth.contract(abiArray);
+ var MyContract_ = web3.eth.contract(source);
+ MyContract = web3.eth.contract(MyContract_.CONTRACT_NAME.info.abiDefinition);
// deploy new contract
var contractInstance = MyContract.new(
10,
@@ -85,7 +89,7 @@ This means that cyclic creation dependencies are impossible.
// Only the creator can alter the name --
// the comparison is possible since contracts
// are implicitly convertible to addresses.
- if (msg.sender == creator)
+ if (msg.sender == address(creator))
name = newName;
}
diff --git a/docs/control-structures.rst b/docs/control-structures.rst
index 064996ac..9d7ebeac 100644
--- a/docs/control-structures.rst
+++ b/docs/control-structures.rst
@@ -113,7 +113,7 @@ The evaluation order of expressions is not specified (more formally, the order
in which the children of one node in the expression tree are evaluated is not
specified, but they are of course evaluated before the node itself). It is only
guaranteed that statements are executed in order and short-circuiting for
-boolean expressions is done.
+boolean expressions is done. See :ref:`order` for more information.
.. index:: ! assignment
@@ -422,7 +422,7 @@ The opcodes ``pushi`` and ``jumpdest`` cannot be used directly.
+-------------------------+------+-----------------------------------------------------------------+
| dup1 ... dup16 | | copy ith stack slot to the top (counting from top) |
+-------------------------+------+-----------------------------------------------------------------+
-| swap1 ... swap1 | `*` | swap topmost and ith stack slot below it |
+| swap1 ... swap16 | `*` | swap topmost and ith stack slot below it |
+-------------------------+------+-----------------------------------------------------------------+
| mload(p) | | mem[p..(p+32)) |
+-------------------------+------+-----------------------------------------------------------------+
@@ -661,7 +661,7 @@ variables. Take care that when you assign to variables that point to
memory or storage, you will only change the pointer and not the data.
There are two kinds of assignments: Functional-style and instruction-style.
-For functionaly-style assignments (``variable := value``), you need to provide a value in a
+For functional-style assignments (``variable := value``), you need to provide a value in a
functional-style expression that results in exactly one stack value
and for instruction-style (``=: variable``), the value is just taken from the stack top.
For both ways, the colon points to the name of the variable.
diff --git a/docs/index.rst b/docs/index.rst
index 940fe5e7..5ca5c4a9 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -38,9 +38,6 @@ Available Solidity Integrations
* `Visual Studio Extension <https://visualstudiogallery.msdn.microsoft.com/96221853-33c4-4531-bdd5-d2ea5acc4799/>`_
Solidity plugin for Microsoft Visual Studio that includes the Solidity compiler.
-* `Mix IDE <https://github.com/ethereum/mix/>`_
- Qt based IDE for designing, debugging and testing solidity smart contracts.
-
* `Package for SublimeText — Solidity language syntax <https://packagecontrol.io/packages/Ethereum/>`_
Solidity syntax highlighting for SublimeText editor.
@@ -59,6 +56,12 @@ Available Solidity Integrations
* `Vim Solidity <https://github.com/tomlion/vim-solidity/>`_
Plugin for the Vim editor providing syntax highlighting.
+Discontinued:
+
+* `Mix IDE <https://github.com/ethereum/mix/>`_
+ Qt based IDE for designing, debugging and testing solidity smart contracts.
+
+
Solidity Tools
-------------------------------
diff --git a/docs/installing-solidity.rst b/docs/installing-solidity.rst
index a5f9b0f2..33bba29b 100644
--- a/docs/installing-solidity.rst
+++ b/docs/installing-solidity.rst
@@ -61,12 +61,7 @@ Set up Homebrew:
brew upgrade
brew install boost --c++11 # this takes a while
- brew install cmake cryptopp miniupnpc leveldb gmp libmicrohttpd libjson-rpc-cpp
- # For Mix IDE and Alethzero only
- brew install xz d-bus
- brew install homebrew/versions/v8-315
- brew install llvm --HEAD --with-clang
- brew install qt5 --with-d-bus # add --verbose if long waits with a stale screen drive you crazy as well
+ brew install cmake cryptopp gmp
Ubuntu Trusty (14.04)
---------------------
@@ -74,21 +69,16 @@ Ubuntu Trusty (14.04)
Below are the instructions to install the minimal dependencies required
to compile Solidity on Ubuntu 14.04 (Trusty Tahr).
-.. note::
-
- These dependencies are not enough to compile the GUIs (Alethzero and Mix).
-
.. code-block:: bash
sudo apt-get -y install build-essential git cmake libgmp-dev libboost-all-dev \
- libjsoncpp-dev libleveldb-dev libcurl4-openssl-dev libminiupnpc-dev \
- libmicrohttpd-dev
+ libjsoncpp-dev
sudo add-apt-repository -y ppa:ethereum/ethereum
sudo add-apt-repository -y ppa:ethereum/ethereum-dev
sudo apt-get -y update
sudo apt-get -y upgrade # this will update cmake to version 3.x
- sudo apt-get -y install libcryptopp-dev libjson-rpc-cpp-dev
+ sudo apt-get -y install libcryptopp-dev libjsoncpp-dev
Ubuntu Xenial (16.04)
---------------------
@@ -100,15 +90,10 @@ One of the dependencies (Crypto++ Library, with version >= 5.6.2) can be
installed either by adding the Ethereum PPA (Option 1) or by backporting
``libcrypto++`` from Ubuntu Development to Ubuntu Xenial (Option 2).
-.. note::
-
- These dependencies are not enough to compile the GUIs (Alethzero and Mix).
-
.. code-block:: bash
sudo apt-get -y install build-essential git cmake libgmp-dev libboost-all-dev \
- libjsoncpp-dev libleveldb-dev libcurl4-openssl-dev libminiupnpc-dev \
- libjsonrpccpp-dev libmicrohttpd-dev
+ libjsoncpp-dev
# (Option 1) For those willing to add the Ethereum PPA:
sudo add-apt-repository -y ppa:ethereum/ethereum
@@ -133,29 +118,16 @@ Run this if you plan on installing Solidity only:
.. code-block:: bash
- git clone --recursive https://github.com/ethereum/webthree-umbrella.git
- cd webthree-umbrella
- ./webthree-helpers/scripts/ethupdate.sh --no-push --simple-pull --project solidity # update Solidity repo
- ./webthree-helpers/scripts/ethbuild.sh --no-git --project solidity --cores 4 -DEVMJIT=0 -DETHASHCL=0 # build Solidity only
-
-If you opted to install Alethzero and Mix:
-
-.. code-block:: bash
-
- git clone --recursive https://github.com/ethereum/webthree-umbrella.git
- cd webthree-umbrella && mkdir -p build && cd build
- cmake ..
+ git clone --recursive https://github.com/ethereum/solidity.git
+ cd solidity
+ mkdir build
+ cd build
+ cmake .. && make
If you want to help developing Solidity,
you should fork Solidity and add your personal fork as a second remote:
.. code-block:: bash
- cd webthree-umbrella/solidity
+ cd solidity
git remote add personal git@github.com:username/solidity.git
-
-Note that webthree-umbrella uses submodules, so solidity is its own git
-repository, but its settings are not stored in ``.git/config``, but in
-``webthree-umbrella/.git/modules/solidity/config``.
-
-
diff --git a/docs/layout-of-source-files.rst b/docs/layout-of-source-files.rst
index a0170c5a..ef6fd656 100644
--- a/docs/layout-of-source-files.rst
+++ b/docs/layout-of-source-files.rst
@@ -23,7 +23,7 @@ At a global level, you can use import statements of the following form:
import "filename";
-...will import all global symbols from "filename" (and symbols imported there) into the
+This statement imports all global symbols from "filename" (and symbols imported there) into the
current global scope (different than in ES6 but backwards-compatible for Solidity).
::
@@ -44,7 +44,7 @@ Another syntax is not part of ES6, but probably convenient:
import "filename" as symbolName;
-...is equivalent to ``import * as symbolName from "filename";``.
+which is equivalent to ``import * as symbolName from "filename";``.
Paths
-----
@@ -157,3 +157,23 @@ You can use Doxygen-style tags inside these comments to document
functions, annotate conditions for formal verification, and provide a
**confirmation text** which is shown to users when they attempt to invoke a
function.
+
+In the following example we document the title of the contract, the explanation
+for the two input parameters and two returned values.
+
+::
+
+ /** @title Shape calculator.*/
+ contract shapeCalculator{
+ /**@dev Calculates a rectangle's surface and perimeter.
+ * @param w Width of the rectangle.
+ * @param h Height of the rectangle.
+ * @return s The calculated surface.
+ * @return p The calculated perimeter.
+ */
+ function rectangle(uint w, uint h) returns (uint s, uint p){
+ s = w*h;
+ p = 2*(w+h);
+ }
+ }
+
diff --git a/docs/miscellaneous.rst b/docs/miscellaneous.rst
index 85fc286c..304fce14 100644
--- a/docs/miscellaneous.rst
+++ b/docs/miscellaneous.rst
@@ -95,6 +95,59 @@ is simplified to code which can also be compiled from
even though the instructions contained a jump in the beginning.
+.. index:: source mappings
+
+***************
+Source Mappings
+***************
+
+As part of the AST output, the compiler provides the range of the source
+code that is represented by the respective node in the AST. This can be
+used for various purposes ranging from static analysis tools that report
+errors based on the AST and debugging tools that highlight local variables
+and their uses.
+
+Furthermore, the compiler can also generate a mapping from the bytecode
+to the range in the source code that generated the instruction. This is again
+important for static analysis tools that operate on bytecode level and
+for displaying the current position in the source code inside a debugger
+or for breakpoint handling.
+
+Both kinds of source mappings use integer indentifiers to refer to source files.
+These are regular array indices into a list of source files usually called
+``"sourceList"``, which is part of the combined-json and the output of
+the json / npm compiler.
+
+The source mappings inside the AST use the following
+notation:
+
+``s:l:f``
+
+Where ``s`` is the byte-offset to the start of the range in the source file,
+``l`` is the length of the source range in bytes and ``f`` is the source
+index mentioned above.
+
+The encoding in the source mapping for the bytecode is more complicated:
+It is a list of ``s:l:f:j`` separated by ``;``. Each of these
+elements corresponds to an instruction, i.e. you cannot use the byte offset
+but have to use the instruction offset (push instructions are longer than a single byte).
+The fields ``s``, ``l`` and ``f`` are as above and ``j`` can be either
+``i``, ``o`` or ``-`` signifying whether a jump instruction goes into a
+function, returns from a function or is a regular jump as part of e.g. a loop.
+
+In order to compress these source mappings especially for bytecode, the
+following rules are used:
+
+ - If a field is empty, the value of the preceding element is used.
+ - If a ``:`` is missing, all following fields are considered empty.
+
+This means the following source mappings represent the same information:
+
+``1:2:1;1:9:1;2:1:2;2:1:2;2:1:2``
+
+``1:2:1;:9;2::2;;``
+
+
.. index:: ! commandline compiler, compiler;commandline, ! solc, ! linker
.. _commandline-compiler:
@@ -149,6 +202,69 @@ Tips and Tricks
Cheatsheet
**********
+.. index:: precedence
+
+.. _order:
+
+Order of Precedence of Operators
+================================
+
+The following is the order of precedence for operators, listed in order of evaluation.
+
++------------+-------------------------------------+--------------------------------------------+
+| Precedence | Description | Operator |
++============+=====================================+============================================+
+| *1* | Postfix increment and decrement | ``++``, ``--`` |
++ +-------------------------------------+--------------------------------------------+
+| | Function-like call | ``<func>(<args...>)`` |
++ +-------------------------------------+--------------------------------------------+
+| | Array subscripting | ``<array>[<index>]`` |
++ +-------------------------------------+--------------------------------------------+
+| | Member access | ``<object>.<member>`` |
++ +-------------------------------------+--------------------------------------------+
+| | Parentheses | ``(<statement>)`` |
++------------+-------------------------------------+--------------------------------------------+
+| *2* | Prefix increment and decrement | ``++``, ``--`` |
++ +-------------------------------------+--------------------------------------------+
+| | Unary plus and minus | ``+``, ``-`` |
++ +-------------------------------------+--------------------------------------------+
+| | Unary operations | ``after``, ``delete`` |
++ +-------------------------------------+--------------------------------------------+
+| | Logical NOT | ``!`` |
++ +-------------------------------------+--------------------------------------------+
+| | Bitwise NOT | ``~`` |
++------------+-------------------------------------+--------------------------------------------+
+| *3* | Exponentiation | ``**`` |
++------------+-------------------------------------+--------------------------------------------+
+| *4* | Multiplication, division and modulo | ``*``, ``/``, ``%`` |
++------------+-------------------------------------+--------------------------------------------+
+| *5* | Addition and subtraction | ``+``, ``-`` |
++------------+-------------------------------------+--------------------------------------------+
+| *6* | Bitwise shift operators | ``<<``, ``>>`` |
++------------+-------------------------------------+--------------------------------------------+
+| *7* | Bitwise AND | ``&`` |
++------------+-------------------------------------+--------------------------------------------+
+| *8* | Bitwise XOR | ``^`` |
++------------+-------------------------------------+--------------------------------------------+
+| *9* | Bitwise OR | ``|`` |
++------------+-------------------------------------+--------------------------------------------+
+| *10* | Inequality operators | ``<``, ``>``, ``<=``, ``>=`` |
++------------+-------------------------------------+--------------------------------------------+
+| *11* | Equality operators | ``==``, ``!=`` |
++------------+-------------------------------------+--------------------------------------------+
+| *12* | Logical AND | ``&&`` |
++------------+-------------------------------------+--------------------------------------------+
+| *13* | Logical OR | ``||`` |
++------------+-------------------------------------+--------------------------------------------+
+| *14* | Ternary operator | ``<conditional> ? <if-true> : <if-false>`` |
++------------+-------------------------------------+--------------------------------------------+
+| *15* | Assignment operators | ``=``, ``|=``, ``^=``, ``&=``, ``<<=``, |
+| | | ``>>=``, ``+=``, ``-=``, ``*=``, ``/=``, |
+| | | ``%=`` |
++------------+-------------------------------------+--------------------------------------------+
+| *16* | Comma operator | ``,`` |
++------------+-------------------------------------+--------------------------------------------+
+
.. index:: block, coinbase, difficulty, number, block;number, timestamp, block;timestamp, msg, data, gas, sender, value, now, gas price, origin, sha3, ripemd160, sha256, ecrecover, addmod, mulmod, cryptography, this, super, selfdestruct, balance, send
Global Variables
@@ -192,7 +308,7 @@ Function Visibility Specifiers
- ``public``: visible externally and internally (creates accessor function for storage/state variables)
- ``private``: only visible in the current contract
-- ``external``: only visible externally (only for functions) - i.e. can only be message-called (via ``this.fun``)
+- ``external``: only visible externally (only for functions) - i.e. can only be message-called (via ``this.func``)
- ``internal``: only visible internally
diff --git a/docs/security-considerations.rst b/docs/security-considerations.rst
index f1a5dc03..bae6e20b 100644
--- a/docs/security-considerations.rst
+++ b/docs/security-considerations.rst
@@ -138,6 +138,45 @@ Note that ``.send()`` does **not** throw an exception if the call stack is
depleted but rather returns ``false`` in that case. The low-level functions
``.call()``, ``.callcode()`` and ``.delegatecall()`` behave in the same way.
+tx.origin
+=========
+
+Never use tx.origin for authorization. Let's say you have a wallet contract like this:
+
+::
+
+ contract TxUserWallet {
+ address owner;
+
+ function TxUserWallet() {
+ owner = msg.sender;
+ }
+
+ function transfer(address dest, uint amount) {
+ if (tx.origin != owner) { throw; }
+ if (!dest.call.value(amount)()) throw;
+ }
+ }
+
+Now someone tricks you into sending ether to the address of this attack wallet:
+
+::
+
+ contract TxAttackWallet {
+ address owner;
+
+ function TxAttackWallet() {
+ owner = msg.sender;
+ }
+
+ function() {
+ TxUserWallet(msg.sender).transfer(owner, msg.sender.balance);
+ }
+ }
+
+If your wallet had checked msg.sender for authorization, it would get the address of the attack wallet, instead of the owner address. But by checking tx.origin, it gets the original address that kicked off the transaction, which is still the owner address. The attack wallet instantly drains all your funds.
+
+
Minor Details
=============
@@ -146,7 +185,11 @@ Minor Details
Furthermore, it is not enforced by the EVM, so a contract function that "claims"
to be constant might still cause changes to the state.
- 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.
+ 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
+ of ``0xff000001`` and with ``0x00000001``. Both are fed to the contract and both will
+ look like the number ``1`` as far as ``x`` is concerned, but ``msg.data`` will
+ be different, so if you use ``sha3(msg.data)`` for anything, you will get different results.
***************
Recommendations
diff --git a/docs/style-guide.rst b/docs/style-guide.rst
index 99db8147..c509a9d4 100644
--- a/docs/style-guide.rst
+++ b/docs/style-guide.rst
@@ -640,7 +640,7 @@ words. (for example:``MAX_BLOCKS``)
Modifiers
=========
-Function modifiers should use lowercase words separated by underscores.
+Use mixedCase.
Avoiding Collisions
diff --git a/docs/types.rst b/docs/types.rst
index 50e86ed0..0c5aaf1b 100644
--- a/docs/types.rst
+++ b/docs/types.rst
@@ -12,6 +12,9 @@ see :ref:`type-deduction` below) at
compile-time. 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`.
+
.. index:: ! value type, ! type;value
Value Types
@@ -211,7 +214,9 @@ a non-rational number).
String Literals
---------------
-String Literals are written with double quotes (``"abc"``). As with integer literals, their type can vary, but they are implicitly convertible to ``bytes`` if they fit, to ``bytes`` and to ``string``.
+String Literals are written with double quotes (``"abc"``). As with integer literals, their type can vary, but they are implicitly convertible to ``bytes1``, ..., ``bytes32`` if they fit, to ``bytes`` and to ``string``.
+
+String Literals support escape characters, such as ``\n``, ``\xNN`` and ``\uNNNN``. ``\xNN`` takes a hex value and inserts the appropriate byte, while ``\uNNNN`` takes a Unicode codepoint and inserts an UTF8 sequence.
.. index:: enum
@@ -542,7 +547,8 @@ shown in the following example:
Campaign c = campaigns[campaignID];
if (c.amount < c.fundingGoal)
return false;
- c.beneficiary.send(c.amount);
+ if (!c.beneficiary.send(c.amount))
+ throw;
c.amount = 0;
return true;
}
generated by cgit (git 2.34.1) at 2024-11-18 11:26:48 +0800