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

201 lines
5.3 KiB
ReStructuredText
Raw Permalink Normal View History

2015-12-07 20:16:25 +00:00
.. index:: contract, state variable, function, event, struct, enum, function;modifier
.. _contract_structure:
2015-12-07 20:16:25 +00:00
***********************
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`,
2021-02-04 14:58:06 +00:00
:ref:`structure-function-modifiers`, :ref:`structure-events`, :ref:`structure-errors`, :ref:`structure-struct-types` and :ref:`structure-enum-types`.
2015-12-07 20:16:25 +00:00
Furthermore, contracts can inherit from other contracts.
2018-09-13 17:40:38 +00:00
There are also special kinds of contracts called :ref:`libraries<libraries>` and :ref:`interfaces<interfaces>`.
The section about :ref:`contracts<contracts>` contains more details than this section,
which serves to provide a quick overview.
.. _structure-state-variables:
State Variables
===============
2018-09-17 13:56:04 +00:00
State variables are variables whose values are permanently stored in contract
storage.
.. code-block:: solidity
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.4.0 <0.9.0;
contract SimpleStorage {
uint storedData; // State variable
// ...
}
See the :ref:`types` section for valid state variable types and
2017-02-02 23:52:34 +00:00
:ref:`visibility-and-getters` for possible choices for
2016-03-01 11:15:20 +00:00
visibility.
.. _structure-functions:
Functions
=========
2020-06-16 16:20:37 +00:00
Functions are the executable units of code. Functions are usually
defined inside a contract, but they can also be defined outside of
contracts.
.. code-block:: solidity
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.7.1 <0.9.0;
contract SimpleAuction {
2017-12-12 18:47:30 +00:00
function bid() public payable { // Function
// ...
}
}
2020-06-16 16:20:37 +00:00
// Helper function defined outside of a contract
function helper(uint x) pure returns (uint) {
return x * 2;
}
:ref:`function-calls` can happen internally or externally
2018-09-13 17:40:38 +00:00
and have different levels of :ref:`visibility<visibility-and-getters>`
towards other contracts. :ref:`Functions<functions>` accept :ref:`parameters and return variables<function-parameters-return-variables>` to pass parameters
and values between them.
.. _structure-function-modifiers:
Function Modifiers
==================
Function modifiers can be used to amend the semantics of functions in a declarative way
2018-09-13 17:40:38 +00:00
(see :ref:`modifiers` in the contracts section).
2019-09-16 12:33:43 +00:00
Overloading, that is, having the same modifier name with different parameters,
is not possible.
Like functions, modifiers can be :ref:`overridden <modifier-overriding>`.
.. code-block:: solidity
2016-05-13 14:32:35 +00:00
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.4.22 <0.9.0;
contract Purchase {
address public seller;
2016-05-13 14:32:35 +00:00
modifier onlySeller() { // Modifier
2018-01-03 14:30:01 +00:00
require(
msg.sender == seller,
"Only seller can call this."
);
_;
}
2016-05-13 14:32:35 +00:00
2018-08-09 13:36:00 +00:00
function abort() public view onlySeller { // Modifier usage
// ...
}
}
.. _structure-events:
Events
======
Events are convenience interfaces with the EVM logging facilities.
.. code-block:: solidity
// SPDX-License-Identifier: GPL-3.0
2023-09-07 14:13:10 +00:00
pragma solidity ^0.8.22;
2023-09-07 14:13:10 +00:00
event HighestBidIncreased(address bidder, uint amount); // Event
2016-05-13 14:32:35 +00:00
2023-09-07 14:13:10 +00:00
contract SimpleAuction {
2017-12-12 18:47:30 +00:00
function bid() public payable {
// ...
2018-02-16 16:32:30 +00:00
emit HighestBidIncreased(msg.sender, msg.value); // Triggering event
}
}
2016-05-13 14:32:35 +00:00
See :ref:`events` in contracts section for information on how events are declared
and can be used from within a dapp.
2021-02-04 14:58:06 +00:00
.. _structure-errors:
Errors
======
Errors allow you to define descriptive names and data for failure situations.
Errors can be used in :ref:`revert statements <revert-statement>`.
In comparison to string descriptions, errors are much cheaper and allow you
to encode additional data. You can use NatSpec to describe the error to
the user.
.. code-block:: solidity
2021-02-04 14:58:06 +00:00
// SPDX-License-Identifier: GPL-3.0
pragma solidity ^0.8.4;
/// Not enough funds for transfer. Requested `requested`,
/// but only `available` available.
error NotEnoughFunds(uint requested, uint available);
contract Token {
mapping(address => uint) balances;
function transfer(address to, uint amount) public {
uint balance = balances[msg.sender];
if (balance < amount)
revert NotEnoughFunds(amount, balance);
balances[msg.sender] -= amount;
balances[to] += amount;
// ...
}
}
See :ref:`errors` in the contracts section for more information.
.. _structure-struct-types:
Struct Types
=============
2016-05-13 14:32:35 +00:00
Structs are custom defined types that can group several variables (see
:ref:`structs` in types section).
.. code-block:: solidity
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.4.0 <0.9.0;
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 'constant values' (see
:ref:`enums` in types section).
.. code-block:: solidity
2016-05-13 14:32:35 +00:00
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.4.0 <0.9.0;
contract Purchase {
enum State { Created, Locked, Inactive } // Enum
}