solidity/docs/structure-of-a-contract.rst

.. index:: contract, state variable, function, event, struct, enum, function;modifier

.. _contract_structure:

***********************
Structure of a Contract
***********************

Contracts in Solidity are similar to classes in object-oriented languages.
Each contract can contain declarations of :ref:`structure-state-variables`, :ref:`structure-functions`,
:ref:`structure-function-modifiers`, :ref:`structure-events`, :ref:`structure-structs-types` and :ref:`structure-enum-types`.
Furthermore, contracts can inherit from other contracts.

.. _structure-state-variables:

State Variables
===============

State variables are values which are permanently stored in contract storage.

::

  contract SimpleStorage {
    uint storedData; // State variable
    // ...
  }

See the :ref:`types` section for valid state variable types and
:ref:`visibility-and-accessors` for possible choices for 
visability.

.. _structure-functions:

Functions
=========

Functions are the executable units of code within a contract.

::

  contract SimpleAuction {
    function bid() { // Function
      // ...
    }
  }

:ref:`function-calls` can happen internally or externally
and have different levels of visibility (:ref:`visibility-and-accessors`)
towards other contracts. 

.. _structure-function-modifiers:

Function Modifiers
==================

Function modifiers can be used to amend the semantics of functions in a declarative way
(see :ref:`modifiers` in contracts section).

::
  
  contract Purchase {
    address public seller;
    
    modifier onlySeller() { // Modifier
        if (msg.sender != seller) throw;
        _
    }
    
    function abort() onlySeller { // Modifier usage
        // ...
    }
  }

 in the section on contracts for a more in-depth explanation.

.. _structure-events:

Events
======

Events are convenience interfaces with the EVM logging facilities.

::

  contract SimpleAuction {
    event HighestBidIncreased(address bidder, uint amount); // Event
    
    function bid() {
      // ...
      HighestBidIncreased(msg.sender, msg.value); // Triggering event
    }
  }

See :ref:`events` in contracts section for information on how events are declared 
and can be used from within a dapp.

.. _structure-structs-types:

Structs Types
=============

Structs are custom defined types that can group several variables (see 
:ref:`structs` in types section).

::

  contract Ballot {
    struct Voter { // Struct
      uint weight;
      bool voted;
      address delegate;
      uint vote;
    }
  }

.. _structure-enum-types:

Enum Types
==========

Enums can be used to create custom types with a finite set of values (see 
:ref:`enums` in types section).

::
  
  contract Purchase {
    enum State { Created, Locked, Inactive } // Enum
  }