mirror of
https://github.com/ethereum/solidity
synced 2023-10-03 13:03:40 +00:00
1114 lines
35 KiB
ReStructuredText
1114 lines
35 KiB
ReStructuredText
.. index:: ! contract
|
|
|
|
##########
|
|
Contracts
|
|
##########
|
|
|
|
Contracts in Solidity are what classes are in object oriented languages. They
|
|
contain persistent data in state variables and functions that can modify these
|
|
variables. Calling a function on a different contract (instance) will perform
|
|
an EVM function call and thus switch the context such that state variables are
|
|
inaccessible.
|
|
|
|
.. index:: ! contract;creation
|
|
|
|
******************
|
|
Creating Contracts
|
|
******************
|
|
|
|
Contracts can be created "from outside" or from Solidity contracts.
|
|
When a contract is created, its constructor (a function with the same
|
|
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 = [
|
|
{
|
|
"inputs":[
|
|
{"name":"x","type":"uint256"},
|
|
{"name":"y","type":"uint256"}
|
|
],
|
|
"type":"constructor"
|
|
},
|
|
{
|
|
"constant":true,
|
|
"inputs":[],
|
|
"name":"x",
|
|
"outputs":[{"name":"","type":"bytes32"}],
|
|
"type":"function"
|
|
}
|
|
];
|
|
|
|
var MyContract_ = web3.eth.contract(source);
|
|
MyContract = web3.eth.contract(MyContract_.CONTRACT_NAME.info.abiDefinition);
|
|
// deploy new contract
|
|
var contractInstance = MyContract.new(
|
|
10,
|
|
11,
|
|
{from: myAccount, gas: 1000000}
|
|
);
|
|
|
|
.. index:: constructor;arguments
|
|
|
|
Internally, constructor arguments are passed after the code of
|
|
the contract itself, but you do not have to care about this
|
|
if you use ``web3.js``.
|
|
|
|
If a contract wants to create another contract, the source code
|
|
(and the binary) of the created contract has to be known to the creator.
|
|
This means that cyclic creation dependencies are impossible.
|
|
|
|
::
|
|
|
|
contract OwnedToken {
|
|
// TokenCreator is a contract type that is defined below.
|
|
// It is fine to reference it as long as it is not used
|
|
// to create a new contract.
|
|
TokenCreator creator;
|
|
address owner;
|
|
bytes32 name;
|
|
|
|
// This is the constructor which registers the
|
|
// creator and the assigned name.
|
|
function OwnedToken(bytes32 _name) {
|
|
owner = msg.sender;
|
|
// We do an explicit type conversion from `address`
|
|
// to `TokenCreator` and assume that the type of
|
|
// the calling contract is TokenCreator, there is
|
|
// no real way to check that.
|
|
creator = TokenCreator(msg.sender);
|
|
name = _name;
|
|
}
|
|
|
|
function changeName(bytes32 newName) {
|
|
// Only the creator can alter the name --
|
|
// the comparison is possible since contracts
|
|
// are implicitly convertible to addresses.
|
|
if (msg.sender == address(creator))
|
|
name = newName;
|
|
}
|
|
|
|
function transfer(address newOwner) {
|
|
// Only the current owner can transfer the token.
|
|
if (msg.sender != owner) return;
|
|
// We also want to ask the creator if the transfer
|
|
// is fine. Note that this calls a function of the
|
|
// contract defined below. If the call fails (e.g.
|
|
// due to out-of-gas), the execution here stops
|
|
// immediately.
|
|
if (creator.isTokenTransferOK(owner, newOwner))
|
|
owner = newOwner;
|
|
}
|
|
}
|
|
|
|
contract TokenCreator {
|
|
function createToken(bytes32 name)
|
|
returns (OwnedToken tokenAddress)
|
|
{
|
|
// Create a new Token contract and return its address.
|
|
// From the JavaScript side, the return type is simply
|
|
// "address", as this is the closest type available in
|
|
// the ABI.
|
|
return new OwnedToken(name);
|
|
}
|
|
|
|
function changeName(OwnedToken tokenAddress, bytes32 name) {
|
|
// Again, the external type of "tokenAddress" is
|
|
// simply "address".
|
|
tokenAddress.changeName(name);
|
|
}
|
|
|
|
function isTokenTransferOK(
|
|
address currentOwner,
|
|
address newOwner
|
|
) returns (bool ok) {
|
|
// Check some arbitrary condition.
|
|
address tokenAddress = msg.sender;
|
|
return (sha3(newOwner) & 0xff) == (bytes20(tokenAddress) & 0xff);
|
|
}
|
|
}
|
|
|
|
.. index:: ! visibility, external, public, private, internal
|
|
|
|
.. _visibility-and-accessors:
|
|
|
|
************************
|
|
Visibility and Accessors
|
|
************************
|
|
|
|
Since Solidity knows two kinds of function calls (internal
|
|
ones that do not create an actual EVM call (also called
|
|
a "message call") and external
|
|
ones that do), there are four types of visibilities for
|
|
functions and state variables.
|
|
|
|
Functions can be specified as being ``external``,
|
|
``public``, ``internal`` or ``private``, where the default is
|
|
``public``. For state variables, ``external`` is not possible
|
|
and the default is ``internal``.
|
|
|
|
``external``:
|
|
External functions are part of the contract
|
|
interface, which means they can be called from other contracts and
|
|
via transactions. An external function ``f`` cannot be called
|
|
internally (i.e. ``f()`` does not work, but ``this.f()`` works).
|
|
External functions are sometimes more efficient when
|
|
they receive large arrays of data.
|
|
|
|
``public``:
|
|
Public functions are part of the contract
|
|
interface and can be either called internally or via
|
|
messages. For public state variables, an automatic accessor
|
|
function (see below) is generated.
|
|
|
|
``internal``:
|
|
Those functions and state variables can only be
|
|
accessed internally (i.e. from within the current contract
|
|
or contracts deriving from it), without using ``this``.
|
|
|
|
``private``:
|
|
Private functions and state variables are only
|
|
visible for the contract they are defined in and not in
|
|
derived contracts.
|
|
|
|
.. note::
|
|
Everything that is inside a contract is visible to
|
|
all external observers. Making something ``private``
|
|
only prevents other contracts from accessing and modifying
|
|
the information, but it will still be visible to the
|
|
whole world outside of the blockchain.
|
|
|
|
The visibility specifier is given after the type for
|
|
state variables and between parameter list and
|
|
return parameter list for functions.
|
|
|
|
::
|
|
|
|
contract C {
|
|
function f(uint a) private returns (uint b) { return a + 1; }
|
|
function setData(uint a) internal { data = a; }
|
|
uint public data;
|
|
}
|
|
|
|
In the following example, ``D``, can call ``c.getData()`` to retrieve the value of
|
|
``data`` in state storage, but is not able to call ``f``. Contract ``E`` is derived from
|
|
``C`` and, thus, can call ``compute``.
|
|
|
|
::
|
|
|
|
contract C {
|
|
uint private data;
|
|
|
|
function f(uint a) private returns(uint b) { return a + 1; }
|
|
function setData(uint a) { data = a; }
|
|
function getData() public returns(uint) { return data; }
|
|
function compute(uint a, uint b) internal returns (uint) { return a+b; }
|
|
}
|
|
|
|
|
|
contract D {
|
|
function readData() {
|
|
C c = new C();
|
|
uint local = c.f(7); // error: member "f" is not visible
|
|
c.setData(3);
|
|
local = c.getData();
|
|
local = c.compute(3, 5); // error: member "compute" is not visible
|
|
}
|
|
}
|
|
|
|
|
|
contract E is C {
|
|
function g() {
|
|
C c = new C();
|
|
uint val = compute(3, 5); // acces to internal member (from derivated to parent contract)
|
|
}
|
|
}
|
|
|
|
.. index:: ! accessor;function, ! function;accessor
|
|
|
|
Accessor Functions
|
|
==================
|
|
|
|
The compiler automatically creates accessor functions for
|
|
all public state variables. For the contract given below, the compiler will
|
|
generate a function called ``data`` that does not take any
|
|
arguments and returns a ``uint``, the value of the state
|
|
variable ``data``. The initialization of state variables can
|
|
be done at declaration.
|
|
|
|
::
|
|
|
|
contract C {
|
|
uint public data = 42;
|
|
}
|
|
|
|
|
|
contract Caller {
|
|
C c = new C();
|
|
function f() {
|
|
uint local = c.data();
|
|
}
|
|
}
|
|
|
|
The accessor functions have external visibility. If the
|
|
symbol is accessed internally (i.e. without ``this.``),
|
|
it is evaluated as a state variable and if it is accessed externally
|
|
(i.e. with ``this.``), it is evaluated as a function.
|
|
|
|
::
|
|
|
|
contract C {
|
|
uint public data;
|
|
function x() {
|
|
data = 3; // internal access
|
|
uint val = this.data(); // external access
|
|
}
|
|
}
|
|
|
|
The next example is a bit more complex:
|
|
|
|
::
|
|
|
|
contract Complex {
|
|
struct Data {
|
|
uint a;
|
|
bytes3 b;
|
|
mapping (uint => uint) map;
|
|
}
|
|
mapping (uint => mapping(bool => Data[])) public data;
|
|
}
|
|
|
|
It will generate a function of the following form::
|
|
|
|
function data(uint arg1, bool arg2, uint arg3) returns (uint a, bytes3 b) {
|
|
a = data[arg1][arg2][arg3].a;
|
|
b = data[arg1][arg2][arg3].b;
|
|
}
|
|
|
|
Note that the mapping in the struct is omitted because there
|
|
is no good way to provide the key for the mapping.
|
|
|
|
.. index:: ! function;modifier
|
|
|
|
.. _modifiers:
|
|
|
|
******************
|
|
Function Modifiers
|
|
******************
|
|
|
|
Modifiers can be used to easily change the behaviour of functions, for example
|
|
to automatically check a condition prior to executing the function. They are
|
|
inheritable properties of contracts and may be overridden by derived contracts.
|
|
|
|
::
|
|
|
|
contract owned {
|
|
function owned() { owner = msg.sender; }
|
|
address owner;
|
|
|
|
// This contract only defines a modifier but does not use
|
|
// it - it will be used in derived contracts.
|
|
// The function body is inserted where the special symbol
|
|
// "_" in the definition of a modifier appears.
|
|
// This means that if the owner calls this function, the
|
|
// function is executed and otherwise, an exception is
|
|
// thrown.
|
|
modifier onlyOwner {
|
|
if (msg.sender != owner)
|
|
throw;
|
|
_;
|
|
}
|
|
}
|
|
|
|
|
|
contract mortal is owned {
|
|
// This contract inherits the "onlyOwner"-modifier from
|
|
// "owned" and applies it to the "close"-function, which
|
|
// causes that calls to "close" only have an effect if
|
|
// they are made by the stored owner.
|
|
function close() onlyOwner {
|
|
selfdestruct(owner);
|
|
}
|
|
}
|
|
|
|
|
|
contract priced {
|
|
// Modifiers can receive arguments:
|
|
modifier costs(uint price) {
|
|
if (msg.value >= price) {
|
|
_;
|
|
}
|
|
}
|
|
}
|
|
|
|
|
|
contract Register is priced, owned {
|
|
mapping (address => bool) registeredAddresses;
|
|
uint price;
|
|
|
|
function Register(uint initialPrice) { price = initialPrice; }
|
|
|
|
function register() costs(price) {
|
|
registeredAddresses[msg.sender] = true;
|
|
}
|
|
|
|
function changePrice(uint _price) onlyOwner {
|
|
price = _price;
|
|
}
|
|
}
|
|
|
|
contract Mutex {
|
|
bool locked;
|
|
modifier noReentrancy() {
|
|
if (locked) throw;
|
|
locked = true;
|
|
_;
|
|
locked = false;
|
|
}
|
|
|
|
/// This function is protected by a mutex, which means that
|
|
/// reentrant calls from within msg.sender.call cannot call f again.
|
|
/// The `return 7` statement assigns 7 to the return value but still
|
|
/// executes the statement `locked = false` in the modifier.
|
|
function f() noReentrancy returns (uint) {
|
|
if (!msg.sender.call()) throw;
|
|
return 7;
|
|
}
|
|
}
|
|
|
|
Multiple modifiers can be applied to a function by specifying them in a
|
|
whitespace-separated list and will be evaluated in order.
|
|
|
|
.. warning::
|
|
In an earlier version of Solidity, ``return`` statements in functions
|
|
having modifiers behaved differently.
|
|
|
|
Explicit returns from a modifier or function body only leave the current
|
|
modifier or function body. Return variables are assigned and
|
|
control flow continues after the "_" in the preceding modifier.
|
|
|
|
Arbitrary expressions are allowed for modifier arguments and in this context,
|
|
all symbols visible from the function are visible in the modifier. Symbols
|
|
introduced in the modifier are not visible in the function (as they might
|
|
change by overriding).
|
|
|
|
.. index:: ! constant
|
|
|
|
**********
|
|
Constants
|
|
**********
|
|
|
|
State variables can be declared as constant (this is not yet implemented
|
|
for array and struct types and not possible for mapping types).
|
|
|
|
::
|
|
|
|
contract C {
|
|
uint constant x = 32**22 + 8;
|
|
string constant text = "abc";
|
|
}
|
|
|
|
This has the effect that the compiler does not reserve a storage slot
|
|
for these variables and every occurrence is replaced by their constant value.
|
|
|
|
The value expression can only contain integer arithmetics.
|
|
|
|
|
|
.. index:: ! fallback function, function;fallback
|
|
|
|
.. _fallback-function:
|
|
|
|
*****************
|
|
Fallback Function
|
|
*****************
|
|
|
|
A contract can have exactly one unnamed function. This function cannot have
|
|
arguments and cannot return anything.
|
|
It is executed on a call to the contract if none of the other
|
|
functions matches the given function identifier (or if no data was supplied at
|
|
all).
|
|
|
|
Furthermore, this function is executed whenever the contract receives plain
|
|
Ether (without data). In such a context, there is very little gas available to
|
|
the function call (to be precise, 2300 gas), so it is important to make fallback functions as cheap as
|
|
possible.
|
|
|
|
In particular, the following operations will consume more gas than the stipend provided to a fallback function:
|
|
|
|
- Writing to storage
|
|
- Creating a contract
|
|
- Calling an external function which consumes a large amount of gas
|
|
- Sending Ether
|
|
|
|
Please ensure you test your fallback function thoroughly to ensure the execution cost is less than 2300 gas before deploying a contract.
|
|
|
|
.. warning::
|
|
Contracts that receive Ether but do not define a fallback function
|
|
throw an exception, sending back the Ether (this was different
|
|
before Solidity v0.4.0). So if you want your contract to receive Ether,
|
|
you have to implement a fallback function.
|
|
|
|
::
|
|
|
|
contract Test {
|
|
function() { x = 1; }
|
|
uint x;
|
|
}
|
|
|
|
|
|
// This contract rejects any Ether sent to it. It is good
|
|
// practise to include such a function for every contract
|
|
// in order not to lose Ether.
|
|
contract Rejector {
|
|
function() { throw; }
|
|
}
|
|
|
|
|
|
contract Caller {
|
|
function callTest(address testAddress) {
|
|
Test(testAddress).call(0xabcdef01); // hash does not exist
|
|
// results in Test(testAddress).x becoming == 1.
|
|
Rejector r = Rejector(0x123);
|
|
r.send(2 ether);
|
|
// results in r.balance == 0
|
|
}
|
|
}
|
|
|
|
.. index:: ! event
|
|
|
|
.. _events:
|
|
|
|
******
|
|
Events
|
|
******
|
|
|
|
Events allow the convenient usage of the EVM logging facilities,
|
|
which in turn can be used to "call" JavaScript callbacks in the user interface
|
|
of a dapp, which listen for these events.
|
|
|
|
Events are
|
|
inheritable members of contracts. When they are called, they cause the
|
|
arguments to be stored in the transaction's log - a special data structure
|
|
in the blockchain. These logs are associated with the address of
|
|
the contract and will be incorporated into the blockchain
|
|
and stay there as long as a block is accessible (forever as of
|
|
Frontier and Homestead, but this might change with Serenity). Log and
|
|
event data is not accessible from within contracts (not even from
|
|
the contract that created a log).
|
|
|
|
SPV proofs for logs are possible, so if an external entity supplies
|
|
a contract with such a proof, it can check that the log actually
|
|
exists inside the blockchain (but be aware of the fact that
|
|
ultimately, also the block headers have to be supplied because
|
|
the contract can only see the last 256 block hashes).
|
|
|
|
Up to three parameters can
|
|
receive the attribute ``indexed`` which will cause the respective arguments
|
|
to be searched for: It is possible to filter for specific values of
|
|
indexed arguments in the user interface.
|
|
|
|
If arrays (including ``string`` and ``bytes``) are used as indexed arguments, the
|
|
sha3-hash of it is stored as topic instead.
|
|
|
|
The hash of the signature of the event is one of the topics except if you
|
|
declared the event with ``anonymous`` specifier. This means that it is
|
|
not possible to filter for specific anonymous events by name.
|
|
|
|
All non-indexed arguments will be stored in the data part of the log.
|
|
|
|
::
|
|
|
|
contract ClientReceipt {
|
|
event Deposit(
|
|
address indexed _from,
|
|
bytes32 indexed _id,
|
|
uint _value
|
|
);
|
|
|
|
function deposit(bytes32 _id) {
|
|
// Any call to this function (even deeply nested) can
|
|
// be detected from the JavaScript API by filtering
|
|
// for `Deposit` to be called.
|
|
Deposit(msg.sender, _id, msg.value);
|
|
}
|
|
}
|
|
|
|
The use in the JavaScript API would be as follows:
|
|
|
|
::
|
|
|
|
var abi = /* abi as generated by the compiler */;
|
|
var ClientReceipt = web3.eth.contract(abi);
|
|
var clientReceipt = ClientReceipt.at(0x123 /* address */);
|
|
|
|
var event = clientReceipt.Deposit();
|
|
|
|
// watch for changes
|
|
event.watch(function(error, result){
|
|
// result will contain various information
|
|
// including the argumets given to the Deposit
|
|
// call.
|
|
if (!error)
|
|
console.log(result);
|
|
});
|
|
|
|
// Or pass a callback to start watching immediately
|
|
var event = clientReceipt.Deposit(function(error, result) {
|
|
if (!error)
|
|
console.log(result);
|
|
});
|
|
|
|
.. index:: ! log
|
|
|
|
Low-Level Interface to Logs
|
|
===========================
|
|
|
|
It is also possible to access the low-level interface to the logging
|
|
mechanism via the functions ``log0``, ``log1``, ``log2``, ``log3`` and ``log4``.
|
|
``logi`` takes ``i + 1`` parameter of type ``bytes32``, where the first
|
|
argument will be used for the data part of the log and the others
|
|
as topics. The event call above can be performed in the same way as
|
|
|
|
::
|
|
|
|
log3(
|
|
msg.value,
|
|
0x50cb9fe53daa9737b786ab3646f04d0150dc50ef4e75f59509d83667ad5adb20,
|
|
msg.sender,
|
|
_id
|
|
);
|
|
|
|
where the long hexadecimal number is equal to
|
|
``sha3("Deposit(address,hash256,uint256)")``, the signature of the event.
|
|
|
|
Additional Resources for Understanding Events
|
|
==============================================
|
|
|
|
- `Javascript documentation <https://github.com/ethereum/wiki/wiki/JavaScript-API#contract-events>`_
|
|
- `Example usage of events <https://github.com/debris/smart-exchange/blob/master/lib/contracts/SmartExchange.sol>`_
|
|
- `How to access them in js <https://github.com/debris/smart-exchange/blob/master/lib/exchange_transactions.js>`_
|
|
|
|
.. index:: ! inheritance, ! base class, ! contract;base, ! deriving
|
|
|
|
***********
|
|
Inheritance
|
|
***********
|
|
|
|
Solidity supports multiple inheritance by copying code including polymorphism.
|
|
|
|
All function calls are virtual, which means that the most derived function
|
|
is called, except when the contract is explicitly given.
|
|
|
|
Even if a contract inherits from multiple other contracts, only a single
|
|
contract is created on the blockchain, the code from the base contracts
|
|
is always copied into the final contract.
|
|
|
|
The general inheritance system is very similar to
|
|
`Python's <https://docs.python.org/3/tutorial/classes.html#inheritance>`_,
|
|
especially concerning multiple inheritance.
|
|
|
|
Details are given in the following example.
|
|
|
|
::
|
|
|
|
contract owned {
|
|
function owned() { owner = msg.sender; }
|
|
address owner;
|
|
}
|
|
|
|
|
|
// Use "is" to derive from another contract. Derived
|
|
// contracts can access all non-private members including
|
|
// internal functions and state variables. These cannot be
|
|
// accessed externally via `this`, though.
|
|
contract mortal is owned {
|
|
function kill() {
|
|
if (msg.sender == owner) selfdestruct(owner);
|
|
}
|
|
}
|
|
|
|
|
|
// These abstract contracts are only provided to make the
|
|
// interface known to the compiler. Note the function
|
|
// without body. If a contract does not implement all
|
|
// functions it can only be used as an interface.
|
|
contract Config {
|
|
function lookup(uint id) returns (address adr);
|
|
}
|
|
|
|
|
|
contract NameReg {
|
|
function register(bytes32 name);
|
|
function unregister();
|
|
}
|
|
|
|
|
|
// Multiple inheritance is possible. Note that "owned" is
|
|
// also a base class of "mortal", yet there is only a single
|
|
// instance of "owned" (as for virtual inheritance in C++).
|
|
contract named is owned, mortal {
|
|
function named(bytes32 name) {
|
|
Config config = Config(0xd5f9d8d94886e70b06e474c3fb14fd43e2f23970);
|
|
NameReg(config.lookup(1)).register(name);
|
|
}
|
|
|
|
// Functions can be overridden, both local and
|
|
// message-based function calls take these overrides
|
|
// into account.
|
|
function kill() {
|
|
if (msg.sender == owner) {
|
|
Config config = Config(0xd5f9d8d94886e70b06e474c3fb14fd43e2f23970);
|
|
NameReg(config.lookup(1)).unregister();
|
|
// It is still possible to call a specific
|
|
// overridden function.
|
|
mortal.kill();
|
|
}
|
|
}
|
|
}
|
|
|
|
|
|
// If a constructor takes an argument, it needs to be
|
|
// provided in the header (or modifier-invocation-style at
|
|
// the constructor of the derived contract (see below)).
|
|
contract PriceFeed is owned, mortal, named("GoldFeed") {
|
|
function updateInfo(uint newInfo) {
|
|
if (msg.sender == owner) info = newInfo;
|
|
}
|
|
|
|
function get() constant returns(uint r) { return info; }
|
|
|
|
uint info;
|
|
}
|
|
|
|
Note that above, we call ``mortal.kill()`` to "forward" the
|
|
destruction request. The way this is done is problematic, as
|
|
seen in the following example::
|
|
|
|
contract mortal is owned {
|
|
function kill() {
|
|
if (msg.sender == owner) selfdestruct(owner);
|
|
}
|
|
}
|
|
|
|
|
|
contract Base1 is mortal {
|
|
function kill() { /* do cleanup 1 */ mortal.kill(); }
|
|
}
|
|
|
|
|
|
contract Base2 is mortal {
|
|
function kill() { /* do cleanup 2 */ mortal.kill(); }
|
|
}
|
|
|
|
|
|
contract Final is Base1, Base2 {
|
|
}
|
|
|
|
A call to ``Final.kill()`` will call ``Base2.kill`` as the most
|
|
derived override, but this function will bypass
|
|
``Base1.kill``, basically because it does not even know about
|
|
``Base1``. The way around this is to use ``super``::
|
|
|
|
contract mortal is owned {
|
|
function kill() {
|
|
if (msg.sender == owner) selfdestruct(owner);
|
|
}
|
|
}
|
|
|
|
|
|
contract Base1 is mortal {
|
|
function kill() { /* do cleanup 1 */ super.kill(); }
|
|
}
|
|
|
|
|
|
contract Base2 is mortal {
|
|
function kill() { /* do cleanup 2 */ super.kill(); }
|
|
}
|
|
|
|
|
|
contract Final is Base2, Base1 {
|
|
}
|
|
|
|
If ``Base1`` calls a function of ``super``, it does not simply
|
|
call this function on one of its base contracts, it rather
|
|
calls this function on the next base contract in the final
|
|
inheritance graph, so it will call ``Base2.kill()`` (note that
|
|
the final inheritance sequence is -- starting with the most
|
|
derived contract: Final, Base1, Base2, mortal, owned).
|
|
The actual function that is called when using super is
|
|
not known in the context of the class where it is used,
|
|
although its type is known. This is similar for ordinary
|
|
virtual method lookup.
|
|
|
|
.. index:: ! base;constructor
|
|
|
|
Arguments for Base Constructors
|
|
===============================
|
|
|
|
Derived contracts need to provide all arguments needed for
|
|
the base constructors. This can be done at two places::
|
|
|
|
contract Base {
|
|
uint x;
|
|
function Base(uint _x) { x = _x; }
|
|
}
|
|
|
|
|
|
contract Derived is Base(7) {
|
|
function Derived(uint _y) Base(_y * _y) {
|
|
}
|
|
}
|
|
|
|
Either directly in the inheritance list (``is Base(7)``) or in
|
|
the way a modifier would be invoked as part of the header of
|
|
the derived constructor (``Base(_y * _y)``). The first way to
|
|
do it is more convenient if the constructor argument is a
|
|
constant and defines the behaviour of the contract or
|
|
describes it. The second way has to be used if the
|
|
constructor arguments of the base depend on those of the
|
|
derived contract. If, as in this silly example, both places
|
|
are used, the modifier-style argument takes precedence.
|
|
|
|
.. index:: ! inheritance;multiple, ! linearization, ! C3 linearization
|
|
|
|
Multiple Inheritance and Linearization
|
|
======================================
|
|
|
|
Languages that allow multiple inheritance have to deal with
|
|
several problems, one of them being the `Diamond Problem <https://en.wikipedia.org/wiki/Multiple_inheritance#The_diamond_problem>`_.
|
|
Solidity follows the path of Python and uses "`C3 Linearization <https://en.wikipedia.org/wiki/C3_linearization>`_"
|
|
to force a specific order in the DAG of base classes. This
|
|
results in the desirable property of monotonicity but
|
|
disallows some inheritance graphs. Especially, the order in
|
|
which the base classes are given in the ``is`` directive is
|
|
important. In the following code, Solidity will give the
|
|
error "Linearization of inheritance graph impossible".
|
|
|
|
::
|
|
|
|
contract X {}
|
|
contract A is X {}
|
|
contract C is A, X {}
|
|
|
|
The reason for this is that ``C`` requests ``X`` to override ``A``
|
|
(by specifying ``A, X`` in this order), but ``A`` itself
|
|
requests to override ``X``, which is a contradiction that
|
|
cannot be resolved.
|
|
|
|
A simple rule to remember is to specify the base classes in
|
|
the order from "most base-like" to "most derived".
|
|
|
|
.. index:: ! contract;abstract, ! abstract contract
|
|
|
|
******************
|
|
Abstract Contracts
|
|
******************
|
|
|
|
Contract functions can lack an implementation as in the following example (note that the function declaration header is terminated by ``;``)::
|
|
|
|
contract Feline {
|
|
function utterance() returns (bytes32);
|
|
}
|
|
|
|
Such contracts cannot be compiled (even if they contain implemented functions alongside non-implemented functions), but they can be used as base contracts::
|
|
|
|
contract Cat is Feline {
|
|
function utterance() returns (bytes32) { return "miaow"; }
|
|
}
|
|
|
|
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, delegatecall
|
|
|
|
.. _libraries:
|
|
|
|
************
|
|
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 ``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
|
|
accessed. As a library is an isolated piece of source code, it can only access
|
|
state variables of the calling contract if they are explicitly supplied (it
|
|
would have no way to name them, otherwise).
|
|
|
|
Libraries can be seen as implicit base contracts of the contracts that use them.
|
|
They will not be explicitly visible in the inheritance hierarchy, but calls
|
|
to library functions look just like calls to functions of explicit base
|
|
contracts (``L.f()`` if ``L`` is the name of the library). Furthermore,
|
|
``internal`` functions of libraries are visible in all contracts, just as
|
|
if the library were a base contract. Of course, calls to internal functions
|
|
use the internal calling convention, which means that all internal types
|
|
can be passed and memory types will be passed by reference and not copied.
|
|
In order to realise this in the EVM, code of internal library functions
|
|
(and all functions called from therein) will be pulled into the calling
|
|
contract and a regular ``JUMP`` call will be used instead of a ``DELEGATECALL``.
|
|
|
|
.. index:: using for, set
|
|
|
|
The following example illustrates how to use libraries (but
|
|
be sure to check out :ref:`using for <using-for>` for a
|
|
more advanced example to implement a set).
|
|
|
|
::
|
|
|
|
library Set {
|
|
// We define a new struct datatype that will be used to
|
|
// hold its data in the calling contract.
|
|
struct Data { mapping(uint => bool) flags; }
|
|
|
|
// Note that the first parameter is of type "storage
|
|
// reference" and thus only its storage address and not
|
|
// its contents is passed as part of the call. This is a
|
|
// special feature of library functions. It is idiomatic
|
|
// to call the first parameter 'self', if the function can
|
|
// be seen as a method of that object.
|
|
function insert(Data storage self, uint value)
|
|
returns (bool)
|
|
{
|
|
if (self.flags[value])
|
|
return false; // already there
|
|
self.flags[value] = true;
|
|
return true;
|
|
}
|
|
|
|
function remove(Data storage self, uint value)
|
|
returns (bool)
|
|
{
|
|
if (!self.flags[value])
|
|
return false; // not there
|
|
self.flags[value] = false;
|
|
return true;
|
|
}
|
|
|
|
function contains(Data storage self, uint value)
|
|
returns (bool)
|
|
{
|
|
return self.flags[value];
|
|
}
|
|
}
|
|
|
|
|
|
contract C {
|
|
Set.Data knownValues;
|
|
|
|
function register(uint value) {
|
|
// The library functions can be called without a
|
|
// specific instance of the library, since the
|
|
// "instance" will be the current contract.
|
|
if (!Set.insert(knownValues, value))
|
|
throw;
|
|
}
|
|
// In this contract, we can also directly access knownValues.flags, if we want.
|
|
}
|
|
|
|
Of course, you do not have to follow this way to use
|
|
libraries - they can also be used without defining struct
|
|
data types, functions also work without any storage
|
|
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 (``DELEGATECALL``) to an external
|
|
contract/library. If you use libraries, take care that an
|
|
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).
|
|
|
|
The following example shows how to use memory types and
|
|
internal functions in libraries in order to implement
|
|
custom types without the overhead of external function calls:
|
|
|
|
::
|
|
|
|
library BigInt {
|
|
struct bigint {
|
|
uint[] limbs;
|
|
}
|
|
|
|
function fromUint(uint x) internal returns (bigint r) {
|
|
r.limbs = new uint[](1);
|
|
r.limbs[0] = x;
|
|
}
|
|
|
|
function add(bigint _a, bigint _b) internal returns (bigint r) {
|
|
r.limbs = new uint[](max(_a.limbs.length, _b.limbs.length));
|
|
uint carry = 0;
|
|
for (uint i = 0; i < r.limbs.length; ++i) {
|
|
uint a = limb(_a, i);
|
|
uint b = limb(_b, i);
|
|
r.limbs[i] = a + b + carry;
|
|
if (a + b < a || (a + b == uint(-1) && carry > 0))
|
|
carry = 1;
|
|
else
|
|
carry = 0;
|
|
}
|
|
if (carry > 0) {
|
|
// too bad, we have to add a limb
|
|
uint[] memory newLimbs = new uint[](r.limbs.length + 1);
|
|
for (i = 0; i < r.limbs.length; ++i)
|
|
newLimbs[i] = r.limbs[i];
|
|
newLimbs[i] = carry;
|
|
r.limbs = newLimbs;
|
|
}
|
|
}
|
|
|
|
function limb(bigint _a, uint _limb) internal returns (uint) {
|
|
return _limb < _a.limbs.length ? _a.limbs[_limb] : 0;
|
|
}
|
|
|
|
function max(uint a, uint b) private returns (uint) {
|
|
return a > b ? a : b;
|
|
}
|
|
}
|
|
|
|
|
|
contract C {
|
|
using BigInt for BigInt.bigint;
|
|
|
|
function f() {
|
|
var x = BigInt.fromUint(7);
|
|
var y = BigInt.fromUint(uint(-1));
|
|
var z = x.add(y);
|
|
}
|
|
}
|
|
|
|
As the compiler cannot know where the library will be
|
|
deployed at, these addresses have to be filled into the
|
|
final bytecode by a linker
|
|
(see :ref:`commandline-compiler` for how to use the
|
|
commandline compiler for linking). If the addresses are not
|
|
given as arguments to the compiler, the compiled hex code
|
|
will contain placeholders of the form ``__Set______`` (where
|
|
``Set`` is the name of the library). The address can be filled
|
|
manually by replacing all those 40 symbols by the hex
|
|
encoding of the address of the library contract.
|
|
|
|
Restrictions for libraries in comparison to contracts:
|
|
|
|
- No state variables
|
|
- Cannot inherit nor be inherited
|
|
- Cannot recieve Ether
|
|
|
|
(These might be lifted at a later point.)
|
|
|
|
.. index:: ! using for, library
|
|
|
|
.. _using-for:
|
|
|
|
*********
|
|
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).
|
|
|
|
The effect of ``using A for *;`` is that the functions from
|
|
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
|
|
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
|
|
available without having to add further code.
|
|
|
|
Let us rewrite the set example from the
|
|
:ref:`libraries` in this way::
|
|
|
|
// This is the same code as before, just without comments
|
|
library Set {
|
|
struct Data { mapping(uint => bool) flags; }
|
|
|
|
function insert(Data storage self, uint value)
|
|
returns (bool)
|
|
{
|
|
if (self.flags[value])
|
|
return false; // already there
|
|
self.flags[value] = true;
|
|
return true;
|
|
}
|
|
|
|
function remove(Data storage self, uint value)
|
|
returns (bool)
|
|
{
|
|
if (!self.flags[value])
|
|
return false; // not there
|
|
self.flags[value] = false;
|
|
return true;
|
|
}
|
|
|
|
function contains(Data storage self, uint value)
|
|
returns (bool)
|
|
{
|
|
return self.flags[value];
|
|
}
|
|
}
|
|
|
|
|
|
contract C {
|
|
using Set for Set.Data; // this is the crucial change
|
|
Set.Data knownValues;
|
|
|
|
function register(uint value) {
|
|
// Here, all variables of type Set.Data have
|
|
// corresponding member functions.
|
|
// The following function call is identical to
|
|
// Set.insert(knownValues, value)
|
|
if (!knownValues.insert(value))
|
|
throw;
|
|
}
|
|
}
|
|
|
|
It is also possible to extend elementary types in that way::
|
|
|
|
library Search {
|
|
function indexOf(uint[] storage self, uint value) returns (uint) {
|
|
for (uint i = 0; i < self.length; i++)
|
|
if (self[i] == value) return i;
|
|
return uint(-1);
|
|
}
|
|
}
|
|
|
|
|
|
contract C {
|
|
using Search for uint[];
|
|
uint[] data;
|
|
|
|
function append(uint value) {
|
|
data.push(value);
|
|
}
|
|
|
|
function replace(uint _old, uint _new) {
|
|
// This performs the library function call
|
|
uint index = data.indexOf(_old);
|
|
if (index == uint(-1))
|
|
data.push(_new);
|
|
else
|
|
data[index] = _new;
|
|
}
|
|
}
|
|
|
|
Note that all library calls are actual EVM function calls. This means that
|
|
if you pass memory or value types, a copy will be performed, even of the
|
|
``self`` variable. The only situation where no copy will be performed
|
|
is when storage reference variables are used.
|