Documentation for delegatecall.

4 files changed, 19 insertions, 46 deletions

diff --git a/docs/contracts.rst b/docs/contracts.rst
index b2358af5..2ab03849 100644
--- a/docs/contracts.rst
+++ b/docs/contracts.rst
@@ -679,7 +679,7 @@ Such contracts cannot be compiled (even if they contain implemented functions al
 
 If a contract inherits from an abstract contract and does not implement all non-implemented functions by overriding, it will itself be abstract.
 
-.. index:: ! library, callcode
+.. index:: ! library, callcode, delegatecall
 
 .. _libraries:
 
@@ -688,7 +688,8 @@ Libraries
 ************
 
 Libraries are similar to contracts, but their purpose is that they are deployed
-only once at a specific address and their code is reused using the `CALLCODE`
+only once at a specific address and their code is reused using the `DELEGATECALL`
+(`CALLCODE` until homestead)
 feature of the EVM. This means that if library functions are called, their code
 is executed in the context of the calling contract, i.e. `this` points to the
 calling contract and especially the storage from the calling contract can be
@@ -755,12 +756,12 @@ reference parameters, can have multiple storage reference
 parameters and in any position.
 
 The calls to `Set.contains`, `Set.insert` and `Set.remove`
-are all compiled as calls (`CALLCODE`s) to an external
+are all compiled as calls (`DELEGATECALL`s) to an external
 contract/library. If you use libraries, take care that an
-actual external function call is performed, so `msg.sender`
-does not point to the original sender anymore but to the the
-calling contract and also `msg.value` contains the funds
-sent during the call to the library function.
+actual external function call is performed.
+`msg.sender`, `msg.value` and `this` will retain their values
+in this call, though (prior to Homestead, `msg.sender` and
+`msg.value` changed, though).
 
 As the compiler cannot know where the library will be
 deployed at, these addresses have to be filled into the
@@ -780,34 +781,6 @@ Restrictions for libraries in comparison to contracts:
 
 (these might be lifted at a later point)
 
-Common pitfalls for libraries
-=============================
-
-.. index:: msg;sender
-
-The value of `msg.sender`
--------------------------
-
-The value for `msg.sender` will be that of the contract which is calling the library function.
-
-For example, if A calls contract B which internally calls library C, then within the function call of library C, `msg.sender` will be the address of contract B.
-
-The reason for this is that the expression `LibraryName.functionName()`
-performs an external function call using `CALLCODE`, which maps to a real EVM
-call just like `otherContract.functionName()` or `this.functionName()`.  This
-call extends the call depth by one (limited to 1024), stores the caller (the
-current contract) as `msg.sender`, and then executes the library contract's
-code against the current contracts storage.  This execution occurs in a
-completely new memory context meaning that memory types will be copied and
-cannot be passed by reference.
-
-Transferring Ether
--------------------------
-
-It is *in principle* possible to transfer ether using
-`LibraryName.functionName.value(x)()`, but as `CALLCODE` is used, the Ether
-will just end up at the current contract.
-
 .. index:: ! using for, library
 
 .. _using-for:
diff --git a/docs/control-structures.rst b/docs/control-structures.rst
index 989e14ba..9f0f5b5d 100644
--- a/docs/control-structures.rst
+++ b/docs/control-structures.rst
@@ -145,7 +145,7 @@ Assigning *to* a state variable always creates an independent copy. On the other
 Exceptions
 ==========
 
-There are some cases where exceptions are thrown automatically (see below). You can use the `throw` instruction to throw an exception manually. The effect of an exception is that the currently executing call is stopped and reverted (i.e. all changes to the state and balances are undone) and the exception is also "bubbled up" through Solidity function calls (exceptions are `send` and the low-level functions `call` and `callcode`, those return `false` in case of an exception).
+There are some cases where exceptions are thrown automatically (see below). You can use the `throw` instruction to throw an exception manually. The effect of an exception is that the currently executing call is stopped and reverted (i.e. all changes to the state and balances are undone) and the exception is also "bubbled up" through Solidity function calls (exceptions are `send` and the low-level functions `call`, `delegatecall` and `callcode`, those return `false` in case of an exception).
 
 Catching exceptions is not yet possible.
 
diff --git a/docs/introduction-to-smart-contracts.rst b/docs/introduction-to-smart-contracts.rst
index 711e7082..22dbbcb7 100644
--- a/docs/introduction-to-smart-contracts.rst
+++ b/docs/introduction-to-smart-contracts.rst
@@ -406,15 +406,15 @@ a location in the caller's memory preallocated by the caller.
 Calls are **limited** to a depth of 1024, which means that for more complex
 operations, loops should be preferred over recursive calls.
 
-.. index:: callcode, library
+.. index:: delegatecall, callcode, library
 
-Callcode and Libraries
-======================
+Delegatecall / Callcode and Libraries
+=====================================
 
-There exists a special variant of a message call, named **callcode**
+There exists a special variant of a message call, named **delegatecall**
 which is identical to a message call apart from the fact that
 the code at the target address is executed in the context of the calling
-contract.
+contract and `msg.sender` and `msg.value` do not change their values.
 
 This means that a contract can dynamically load code from a different
 address at runtime. Storage, current address and balance still
@@ -461,4 +461,4 @@ The remaining Ether stored at that address is sent to a designated
 target and then the storage and code is removed.
 
 Note that even if a contract's code does not contain the `SELFDESTRUCT`
-opcode, it can still perform that operation using callcode.
+opcode, it can still perform that operation using delegatecall or callcode.
diff --git a/docs/types.rst b/docs/types.rst
index a09a490d..13e2a23e 100644
--- a/docs/types.rst
+++ b/docs/types.rst
@@ -54,7 +54,7 @@ Operators:
 Division always truncates (it just maps to the DIV opcode of the EVM), but it does not truncate if both
 operators are :ref:`literals<integer_literals>` (or literal expressions).
 
-.. index:: address, balance, send, call, callcode
+.. index:: address, balance, send, call, callcode, delegatecall
 
 Address
 -------
@@ -82,7 +82,7 @@ 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`.
 
-* `call` and `callcode`
+* `call`, `callcode` and `delegatecall`
 
 Furthermore, to interface with contracts that do not adhere to the ABI,
 the function `call` is provided which takes an arbitrary number of arguments of any type. These arguments are padded to 32 bytes and concatenated. One exception is the case where the first argument is encoded to exactly four bytes. In this case, it is not padded to allow the use of function signatures here.
@@ -95,9 +95,9 @@ the function `call` is provided which takes an arbitrary number of arguments of
 
 `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 `callcode` 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 `callcode` 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 callcode to be used.
+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.
 
-Both `call` and `callcode` are very low-level functions and should only be used as a *last resort* as they break the type-safety of Solidity.
+All three functions `call`, `delegatecall` and `callcode` are very low-level functions and should only be used as a *last resort* as they break the type-safety of Solidity.
 
 .. note::
     All contracts inherit the members of address, so it is possible to query the balance of the