10 | {% endblock %}
11 |
--------------------------------------------------------------------------------
/docs/solidity-by-example.rst:
--------------------------------------------------------------------------------
1 | ###################
2 | سالیدیتی با مثال
3 | ###################
4 |
5 | .. include:: examples/voting.rst
6 |
7 | .. include:: examples/blind-auction.rst
8 |
9 | .. include:: examples/safe-remote.rst
10 |
11 | .. include:: examples/micropayment.rst
12 |
13 | .. include:: examples/modular.rst
14 |
--------------------------------------------------------------------------------
/docs/grammar.rst:
--------------------------------------------------------------------------------
1 | ****************
2 | گرامر زبان
3 | ****************
4 |
5 | .. a4:autogrammar:: SolidityParser
6 | :only-reachable-from: SolidityParser.sourceUnit
7 | :undocumented:
8 | :cc-to-dash:
9 |
10 | .. a4:autogrammar:: SolidityLexer
11 | :only-reachable-from: SolidityParser.sourceUnit
12 | :fragments:
13 | :cc-to-dash:
--------------------------------------------------------------------------------
/docs/requirements.txt:
--------------------------------------------------------------------------------
1 | # Older versions of sphinx-rtd-theme do not work with never docutils but have a bug in the dependency
2 | # which could result in it being installed anyway and the style (especially bullet points) being broken.
3 | # See https://github.com/readthedocs/sphinx_rtd_theme/issues/1115
4 | sphinx_rtd_theme>=0.5.2
5 |
6 | pygments-lexer-solidity>=0.7.0
7 | sphinx-a4doc>=1.2.1
8 |
9 | # Sphinx 2.1.0 is the oldest version that accepts a lexer class in add_lexer()
10 | sphinx>=2.1.0
11 |
--------------------------------------------------------------------------------
/docs/robots.txt.template:
--------------------------------------------------------------------------------
1 | User-Agent: *
2 | Sitemap: http://docs.soliditylang.org/sitemap.xml
3 | Host: docs.soliditylang.org
4 |
5 | Allow: /en/latest/
6 | Allow: /en/v0.7.6/
7 | Allow: /en/v{{ LATEST_VERSION }}/
8 | Allow: /_/downloads/en/latest/
9 | Allow: /_/downloads/en/0.7.6/
10 | Allow: /_/downloads/en/{{ LATEST_VERSION }}/
11 |
12 | # Prevent documentation for the development branches and older Solidity
13 | # versions from showing up in search results.
14 | Disallow: /en/*
15 | Disallow: /_/downloads/en/*
16 |
--------------------------------------------------------------------------------
/docs/_static/img/solid-share-arrow.svg:
--------------------------------------------------------------------------------
1 |
--------------------------------------------------------------------------------
/docs/internals/layout_in_calldata.rst:
--------------------------------------------------------------------------------
1 |
2 | .. index: calldata layout
3 |
4 | *******************
5 | چیدمانِ Call Data
6 | *******************
7 |
8 | دادههای ورودی برای فراخوانی تابع به فرمت تعریف شده توسط مشخصات :ref:`ABI specification ` فرض میشود. از جمله، مشخصات
9 | ABI به آرگومانها نیاز دارد که به مضرب 32 بایت اضافه شوند. فراخوانیهای تابع داخلی از یک قرارداد متفاوت
10 | استفاده میکنند.
11 |
12 |
13 | آرگومانهای constructor یک قرارداد مستقیماً در انتهای کد قرارداد و همچنین در رمزگذاری ABI اضافه
14 | میشوند. constructor از طریق یک آفست hard-coded، و نه با استفاده از آپکد ``codesize`` ، به
15 | آنها دسترسی خواهد داشت، البته بخاطر این موضوع هنگام اضافه کردن دادهها به کد تغییر میکند.
16 |
17 |
--------------------------------------------------------------------------------
/docs/credits-and-attribution.rst:
--------------------------------------------------------------------------------
1 | .. This page is meant to be linked to from the footer.
2 |
3 | :orphan:
4 |
5 | #######################
6 | Credits and Attribution
7 | #######################
8 |
9 | Website icons
10 | =============
11 |
12 | .. |icon-share-solid| image:: _static/img/solid-share-arrow.svg
13 | .. _share icon: https://fontawesome.com/v5.15/icons/share?style=solid
14 | .. _Font Awesome Free License: https://fontawesome.com/license/free
15 |
16 | +-------------------------+-----------------------------------------------------------------------+
17 | | Icon | Attribution |
18 | +=========================+=======================================================================+
19 | | |icon-share-solid| | - Source: `share icon`_ from Font Awesome 5.15.0. |
20 | | | - License: `Font Awesome Free License`_ (CC BY 4.0). |
21 | +-------------------------+-----------------------------------------------------------------------+
22 |
--------------------------------------------------------------------------------
/docs/types.rst:
--------------------------------------------------------------------------------
1 | .. index:: type
2 |
3 | .. _types:
4 |
5 | *****
6 | انواع
7 | *****
8 |
9 | سالیدیتی یک زبان نوع استاتیک است، به این معنی که نوع هر متغیر (state و local) باید مشخص شود. سالیدیتی چندین نوع اصلی را ارائه میدهد که میتوانند با هم ترکیب شوند و انواع پیچیدهای را تشکیل دهند.
10 |
11 | علاوه بر این، انواع میتوانند در عبارات حاوی عملگر با یکدیگر تعامل داشته باشند. برای مراجعه سریع به عملگرهای مختلف، به بخش :ref:`ترتیب تقدم عملگرها` مراجعه کنید
12 |
13 |
14 | مفهوم مقادیر " undefined " یا " “null " در سالیدیتی وجود ندارد، اما متغیرهای تازه اعلام شده همیشه :ref:`یک مقدار پیش فرض` وابسته به نوع آنها دارند. برای استفاده از مقادیر غیر منتظره، باید از :ref:`تابع revert` استفاده کنید تا کل تراکنش را برگردانید، یا یک تاپل را با مقدار ``bool`` دوم نشان دهید که موفقیت را نشان میدهد.
15 | انواع مقدار
16 |
17 |
18 |
19 | .. include:: types/value-types.rst
20 |
21 | .. include:: types/reference-types.rst
22 |
23 | .. include:: types/mapping-types.rst
24 |
25 | .. include:: types/operators.rst
26 |
27 | .. include:: types/conversion.rst
28 |
--------------------------------------------------------------------------------
/docs/contracts.rst:
--------------------------------------------------------------------------------
1 | .. index:: ! contract
2 |
3 | .. _contracts:
4 |
5 | ##########
6 | قراردادها
7 | ##########
8 |
9 | قراردادهای سالیدیتی مشابه کلاسهای زبانهای شیء گرا هستند. آنها حاوی دادههای ماندگار در متغیرهای حالت
10 | و توابع هستند که میتوانند این متغیرها را تغییر دهند. فراخوانی یک تابع در یک قرارداد متفاوت (instance)
11 | یک فراخوانی تابع EVM را انجام میدهد و بنابراین context را طوری تغییر میدهد که متغیرهای حالت در
12 | فراخوانی قرارداد غیرقابل دسترسی باشد. برای اینکه هر تغییری بیفتد، یک قرارداد و توابع آن باید فراخوانی شود.
13 | هیچ مفهوم "cron" در اتریوم وجود ندارد که بتواند به طور خودکار یک تابع را در یک رویداد خاص فراخوانی
14 | کند.
15 |
16 |
17 | .. include:: contracts/creating-contracts.rst
18 |
19 | .. include:: contracts/visibility-and-getters.rst
20 |
21 | .. include:: contracts/function-modifiers.rst
22 |
23 | .. include:: contracts/constant-state-variables.rst
24 | .. include:: contracts/functions.rst
25 |
26 | .. include:: contracts/events.rst
27 | .. include:: contracts/errors.rst
28 |
29 | .. include:: contracts/inheritance.rst
30 |
31 | .. include:: contracts/abstract-contracts.rst
32 | .. include:: contracts/interfaces.rst
33 |
34 | .. include:: contracts/libraries.rst
35 |
36 | .. include:: contracts/using-for.rst
--------------------------------------------------------------------------------
/docs/_static/js/toggle.js:
--------------------------------------------------------------------------------
1 | document.addEventListener('DOMContentLoaded', function() {
2 |
3 | function toggleCssMode(isDay) {
4 | var mode = (isDay ? "Day" : "Night");
5 | localStorage.setItem("css-mode", mode);
6 |
7 | var daysheet = $('link[href="_static/pygments.css"]')[0].sheet;
8 | daysheet.disabled = !isDay;
9 |
10 | var nightsheet = $('link[href="_static/css/dark.css"]')[0];
11 | if (!isDay && nightsheet === undefined) {
12 | var element = document.createElement("link");
13 | element.setAttribute("rel", "stylesheet");
14 | element.setAttribute("type", "text/css");
15 | element.setAttribute("href", "_static/css/dark.css");
16 | document.getElementsByTagName("head")[0].appendChild(element);
17 | return;
18 | }
19 | if (nightsheet !== undefined) {
20 | nightsheet.sheet.disabled = isDay;
21 | }
22 | }
23 |
24 | var initial = localStorage.getItem("css-mode") != "Night";
25 | var checkbox = document.querySelector('input[name=mode]');
26 |
27 | toggleCssMode(initial);
28 | checkbox.checked = initial;
29 |
30 | checkbox.addEventListener('change', function() {
31 | document.documentElement.classList.add('transition');
32 | window.setTimeout(() => {
33 | document.documentElement.classList.remove('transition');
34 | }, 1000)
35 | toggleCssMode(this.checked);
36 | })
37 |
38 | });
--------------------------------------------------------------------------------
/docs/_templates/versions.html:
--------------------------------------------------------------------------------
1 | {# Add rst-badge after rst-versions for small badge style. #}
2 |
--------------------------------------------------------------------------------
/docs/language-influences.rst:
--------------------------------------------------------------------------------
1 | ###################
2 | Language Influences
3 | ###################
4 |
5 | Solidity is a `curly-bracket language `_
6 | that has been influenced and inspired by several well-known programming languages.
7 |
8 | Solidity is most profoundly influenced by C++, but also borrowed concepts from languages like
9 | Python, JavaScript, and others.
10 |
11 | The influence from C++ can be seen in the syntax for variable declarations, for loops, the concept
12 | of overloading functions, implicit and explicit type conversions and many other details.
13 |
14 | In the early days of the language, Solidity used to be partly influenced by JavaScript.
15 | This was due to function-level scoping of variables and the use of the keyword ``var``.
16 | The JavaScript influence was reduced starting from version 0.4.0.
17 | Now, the main remaining similarity to JavaScript is that functions are defined using the keyword
18 | ``function``. Solidity also supports import syntax and semantics that
19 | are similar to those available in JavaScript. Besides those points, Solidity looks like
20 | most other curly-bracket languages and has no major JavaScript influence anymore.
21 |
22 | Another influence to Solidity was Python. Solidity's modifiers were added trying to model
23 | Python's decorators with a much more restricted functionality. Furthermore, multiple inheritance, C3 linearization,
24 | and the ``super`` keyword are taken from Python as well as the general assignment and copy semantics of value
25 | and reference types.
26 |
--------------------------------------------------------------------------------
/docs/logo.svg:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
28 |
--------------------------------------------------------------------------------
/docs/_static/css/toggle.css:
--------------------------------------------------------------------------------
1 | input[type=checkbox] {
2 | visibility: hidden;
3 | height: 0;
4 | width: 0;
5 | margin: 0;
6 | }
7 |
8 | .rst-versions .rst-current-version {
9 | padding: 10px;
10 | display: flex;
11 | justify-content: space-between;
12 | }
13 |
14 | .rst-versions .rst-current-version .fa-book,
15 | .rst-versions .rst-current-version .fa-v,
16 | .rst-versions .rst-current-version .fa-caret-down {
17 | height: 24px;
18 | line-height: 24px;
19 | vertical-align: middle;
20 | }
21 |
22 | .rst-versions .rst-current-version .fa-element {
23 | width: 80px;
24 | text-align: center;
25 | }
26 |
27 | .rst-versions .rst-current-version .fa-book {
28 | text-align: left;
29 | }
30 |
31 | .rst-versions .rst-current-version .fa-v {
32 | color: #27AE60;
33 | text-align: right;
34 | }
35 |
36 | label {
37 | margin: 0 auto;
38 | display: inline-block;
39 | justify-content: center;
40 | align-items: right;
41 | border-radius: 100px;
42 | position: relative;
43 | cursor: pointer;
44 | text-indent: -9999px;
45 | width: 50px;
46 | height: 21px;
47 | background: #000;
48 | }
49 |
50 | label:after {
51 | border-radius: 50%;
52 | position: absolute;
53 | content: '';
54 | background: #fff;
55 | width: 15px;
56 | height: 15px;
57 | top: 3px;
58 | left: 3px;
59 | transition: ease-in-out 200ms;
60 | }
61 |
62 | input:checked+label {
63 | background: #3a7ca8;
64 | }
65 |
66 | input:checked+label:after {
67 | left: calc(100% - 5px);
68 | transform: translateX(-100%);
69 | }
70 |
71 | html.transition,
72 | html.transition *,
73 | html.transition *:before,
74 | html.transition *:after {
75 | transition: ease-in-out 200ms !important;
76 | transition-delay: 0 !important;
77 | }
78 |
79 | nav.wy-nav-side {
80 | /* The default padding of 2em is too small and the "Keyword Index" link gets obscured
81 | * by the version toggle. */
82 | padding-bottom: 3em;
83 | }
84 |
--------------------------------------------------------------------------------
/docs/ext/html_extra_template_renderer.py:
--------------------------------------------------------------------------------
1 | import os.path
2 |
3 |
4 | def render_html_extra_templates(app):
5 | if app.builder.format != 'html':
6 | # Non-HTML builders do not provide .templates.render_string(). Note that a HTML
7 | # builder is still used also when building some other formats like json or epub.
8 | return
9 |
10 | for input_path, template_config in app.config.html_extra_templates.items():
11 | # Requiring absolute paths simplifies the implementation.
12 | if not os.path.isabs(input_path):
13 | raise RuntimeError(f"Template input path is not absolute: {input_path}")
14 | if not os.path.isabs(template_config['target']):
15 | raise RuntimeError(f"Template target path is not absolute: {template_config['target']}")
16 |
17 | with open(input_path, 'r', encoding='utf8') as input_file:
18 | # This runs Jinja2, which supports rendering {{ }} tags among other things.
19 | rendered_template = app.builder.templates.render_string(
20 | input_file.read(),
21 | template_config['context'],
22 | )
23 |
24 | with open(template_config['target'], 'w', encoding='utf8') as target_file:
25 | target_file.write(rendered_template)
26 |
27 | app.config.html_extra_path.append(template_config['target'])
28 |
29 |
30 | def setup(app):
31 | app.add_config_value('html_extra_templates', default={}, rebuild='', types=dict)
32 |
33 | # Register a handler for the env-before-read-docs event. Any event that's fired before static
34 | # files get copied would do.
35 | app.connect(
36 | 'env-before-read-docs',
37 | lambda app, env, docnames: render_html_extra_templates(app)
38 | )
39 |
40 | return {
41 | # NOTE: Need to access _raw_config here because setup() runs before app.config is ready.
42 | 'version': app.config._raw_config['version'], # pylint: disable=protected-access
43 | 'parallel_read_safe': True,
44 | 'parallel_write_safe': True,
45 | }
46 |
--------------------------------------------------------------------------------
/docs/internals/variable_cleanup.rst:
--------------------------------------------------------------------------------
1 | .. index: variable cleanup
2 |
3 | *********************
4 | پاکسازی متغیرها
5 | *********************
6 |
7 | وقتی value کوتاهتر از 256 بیت است، در برخی موارد بیتهای باقی مانده باید پاک شوند. کامپایلر سالیدیتی
8 | برای پاکسازی این بیتهای باقیمانده قبل از هر عملیاتی طراحی شده است که ممکن است توسط پتانسیل
9 | garbage در بیتهای باقیمانده تأثیر منفی بگذارد. به عنوان مثال، قبل از نوشتن یک value در مِمُوری،
10 | بیتهای باقیمانده باید پاک شوند، زیرا محتویات مِمُوری را میتوان برای محاسبه هش استفاده کرد یا به عنوان
11 | داده یک کال مسیج (message call) ارسال کرد. به طور مشابه، قبل از ذخیره یک value در storage،
12 | بیتهای باقی مانده باید پاک شوند زیرا در غیر این صورت میتوان garbled value را مشاهده کرد.
13 |
14 | توجه داشته باشید که دسترسی از طریق اسمبلی درون خطی چنین عملیاتی در نظر گرفته نمیشود: اگر از
15 | اسمبلی درون خطی برای دسترسی به متغیرهای سالیدیتی کوتاهتر از ۲۵۶ بیت استفاده میکنید، کامپایلر
16 | تضمین نمیکند که مقدار به درستی پاک شده است.
17 |
18 | علاوه بر این، اگر بلافاصله عملیات بعدی تحت تأثیر قرار نگیرد، بیتها را پاک نمیکنیم. به عنوان مثال، از
19 | آنجایی که هر مقدار غیر صفر توسط دستور ``JUMPI`` به صورت ``true`` در نظر گرفته میشود، ما مقادیر بولی را
20 | قبل از استفاده به عنوان شرط ``JUMPI`` پاک نمیکنیم.
21 |
22 | علاوه بر اصل طراحی بالا، کامپایلر سالیدیتی دادههای ورودی را هنگامی که روی پشته (stack) بارگذاری میشوند، پاک میکند.
23 |
24 | تایپهای مختلف قوانین متفاوتی برای پاکسازی مقادیر نامعتبر دارند:
25 |
26 |
27 | +---------------+---------------+-------------------+
28 | |Type |Valid Values |Invalid Values Mean|
29 | +===============+===============+===================+
30 | |enum of n |0 until n - 1 |exception |
31 | |members | | |
32 | +---------------+---------------+-------------------+
33 | |bool |0 or 1 |1 |
34 | +---------------+---------------+-------------------+
35 | |signed integers|sign-extended |currently silently |
36 | | |word |wraps; in the |
37 | | | |future exceptions |
38 | | | |will be thrown |
39 | | | | |
40 | | | | |
41 | +---------------+---------------+-------------------+
42 | |unsigned |higher bits |currently silently |
43 | |integers |zeroed |wraps; in the |
44 | | | |future exceptions |
45 | | | |will be thrown |
46 | +---------------+---------------+-------------------+
47 |
--------------------------------------------------------------------------------
/docs/contracts/interfaces.rst:
--------------------------------------------------------------------------------
1 | .. index:: ! contract;interface, ! interface contract
2 |
3 | .. _interfaces:
4 |
5 | **********
6 | Interfaces
7 | **********
8 |
9 | Interfaces are similar to abstract contracts, but they cannot have any functions implemented.
10 | There are further restrictions:
11 |
12 | - They cannot inherit from other contracts, but they can inherit from other interfaces.
13 | - All declared functions must be external.
14 | - They cannot declare a constructor.
15 | - They cannot declare state variables.
16 | - They cannot declare modifiers.
17 |
18 | Some of these restrictions might be lifted in the future.
19 |
20 | Interfaces are basically limited to what the Contract ABI can represent, and the conversion between the ABI and
21 | an interface should be possible without any information loss.
22 |
23 | Interfaces are denoted by their own keyword:
24 |
25 | .. code-block:: solidity
26 |
27 | // SPDX-License-Identifier: GPL-3.0
28 | pragma solidity >=0.6.2 <0.9.0;
29 |
30 | interface Token {
31 | enum TokenType { Fungible, NonFungible }
32 | struct Coin { string obverse; string reverse; }
33 | function transfer(address recipient, uint amount) external;
34 | }
35 |
36 | Contracts can inherit interfaces as they would inherit other contracts.
37 |
38 | All functions declared in interfaces are implicitly ``virtual`` and any
39 | functions that override them do not need the ``override`` keyword.
40 | This does not automatically mean that an overriding function can be overridden again -
41 | this is only possible if the overriding function is marked ``virtual``.
42 |
43 | Interfaces can inherit from other interfaces. This has the same rules as normal
44 | inheritance.
45 |
46 | .. code-block:: solidity
47 |
48 | // SPDX-License-Identifier: GPL-3.0
49 | pragma solidity >=0.6.2 <0.9.0;
50 |
51 | interface ParentA {
52 | function test() external returns (uint256);
53 | }
54 |
55 | interface ParentB {
56 | function test() external returns (uint256);
57 | }
58 |
59 | interface SubInterface is ParentA, ParentB {
60 | // Must redefine test in order to assert that the parent
61 | // meanings are compatible.
62 | function test() external override(ParentA, ParentB) returns (uint256);
63 | }
64 |
65 | Types defined inside interfaces and other contract-like structures
66 | can be accessed from other contracts: ``Token.TokenType`` or ``Token.Coin``.
67 |
68 | .. warning:
69 |
70 | Interfaces have supported ``enum`` types since :doc:`Solidity version 0.5.0 <050-breaking-changes>`, make
71 | sure the pragma version specifies this version as a minimum.
72 |
--------------------------------------------------------------------------------
/docs/contracts/abstract-contracts.rst:
--------------------------------------------------------------------------------
1 | .. index:: ! contract;abstract, ! abstract contract
2 |
3 | .. _abstract-contract:
4 |
5 | ******************
6 | قراردادهای انتزاعی (Abstract Contracts)
7 | ******************
8 |
9 | زمانی که حداقل یکی از توابع قراردادها اجرا نشود، باید قراردادها به صورت انتزاعی علامت گذاری شوند. ممکن
10 | است قراردادها بصورت انتزاعی علامت گذاری شوند حتی اگر همه توابع اجرا شوند.
11 |
12 |
13 | این را میتوان با استفاده از کلمه کلیدی ``abstract`` همانطور که در مثال زیر نشان داده شده است، انجام داد.
14 | توجه داشته باشید که این قرارداد باید بصورت انتزاعی تعریف شود، زیرا تابع ``()utterance`` تعریف شده
15 | است، اما پیاده سازی ارائه نشده است (هیچ پیاده سازی ``{ }`` body داده نشده است):
16 |
17 |
18 | .. code-block:: solidity
19 |
20 | // SPDX-License-Identifier: GPL-3.0
21 | pragma solidity >=0.6.0 <0.9.0;
22 |
23 | abstract contract Feline {
24 | function utterance() public virtual returns (bytes32);
25 | }
26 |
27 | چنین قراردادهای انتزاعی را نمیتوان مستقیماً به عنوان نمونه معرفی کرد. اگر یک قرارداد انتزاعی خود تمام توابع
28 | تعریف شده را اجرا کند، این نیز صادق است. در مثال زیر استفاده از یک قرارداد انتزاعی به عنوان کلاس پایه
29 | نشان داده شده است:
30 |
31 |
32 | .. code-block:: solidity
33 |
34 | // SPDX-License-Identifier: GPL-3.0
35 | pragma solidity >=0.6.0 <0.9.0;
36 |
37 | abstract contract Feline {
38 | function utterance() public pure virtual returns (bytes32);
39 | }
40 |
41 | contract Cat is Feline {
42 | function utterance() public pure override returns (bytes32) { return "miaow"; }
43 | }
44 |
45 | اگر یک قرارداد از یک قرارداد انتزاعی ارث برده باشد و تمام توابع اجرا نشده را با overriding اجرا نکند، باید به
46 | عنوان انتزاعی نیز مشخص شود.
47 |
48 |
49 | توجه داشته باشید که یک تابع بدون اجرا با :ref:`Function Type ` متفاوت است، اگرچه سینتکس آنها بسیار شبیه به هم باشد.
50 |
51 |
52 |
53 |
54 |
55 | مثال تابع بدون اجرا (اعلان تابع):
56 |
57 |
58 |
59 | .. code-block:: solidity
60 |
61 | function foo(address) external returns (address);
62 |
63 | مثال اعلان متغیری که نوع آن تابع است:
64 |
65 |
66 | .. code-block:: solidity
67 |
68 | function(address) external returns (address) foo;
69 |
70 | قراردادهای انتزاعی تعریف یک قرارداد را از اجرای آن جدا میکنند که باعث توسعه و مستندسازی بهتر و تسهیل
71 | الگوهایی مانند `Template method `_ و حذف موارد تکراری میشود. قراردادهای انتزاعی به همان شیوهای
72 | مفید هستند که تعریف methodها در یک رابط مفید است. این شیوهای است که طراحِ قراردادِ انتزاعی میگوید
73 | "هر فرزند من باید این روش را اجرا کند".
74 |
75 |
76 |
77 | .. note::
78 |
79 | قراردادهای انتزاعی نمیتوانند یک تابع مجازی پیاده سازی شده را با یک تابع پیاده سازی نشده override کنند.
80 |
81 |
--------------------------------------------------------------------------------
/docs/examples/modular.rst:
--------------------------------------------------------------------------------
1 | .. index:: contract;modular, modular contract
2 |
3 | *****************
4 | قراردادهای ماژولی
5 | *****************
6 |
7 | یک رویکرد ماژولی برای ساخت قراردادها، در کاهش پیچیدگیها و بهبود خوانایی، که به شناسایی باگها و آسیب پذیریها هنگام توسعه و بررسی کد کمک میکند. اگر رفتار یا هر ماژول را جداگانه تعیین و کنترل کنید، فعل و انفعالاتی را باید فقط در روابط بین مشخصات ماژول در نظر بگیرید و نه هر قسمت متحرک دیگر قرارداد.
8 | در مثال زیر، قرارداد از روش ``move`` :ref:`کتابخانه ` ``Balances`` برای بررسی اینکه بالانسهای ارسال شده بین آدرسها با آنچه شما انتظار دارید مطابقت دارد، استفاده میکند. به این ترتیب، کتابخانه ``Balances`` یک جز جداگانه است که موجودی حسابها را به درستی ردیابی میکند را ارائه میدهد. به راحتی میتوان تأیید کرد که کتابخانه ``Balances`` هرگز موجودی یا سرریز منفی تولید نمیکند و مجموع کل موجودی در طول مدت قرارداد ثابت نیست.
9 |
10 | .. code-block:: solidity
11 |
12 | // SPDX-License-Identifier: GPL-3.0
13 | pragma solidity >=0.5.0 <0.9.0;
14 |
15 | library Balances {
16 | function move(mapping(address => uint256) storage balances, address from, address to, uint amount) internal {
17 | require(balances[from] >= amount);
18 | require(balances[to] + amount >= balances[to]);
19 | balances[from] -= amount;
20 | balances[to] += amount;
21 | }
22 | }
23 |
24 | contract Token {
25 | mapping(address => uint256) balances;
26 | using Balances for *;
27 | mapping(address => mapping (address => uint256)) allowed;
28 |
29 | event Transfer(address from, address to, uint amount);
30 | event Approval(address owner, address spender, uint amount);
31 |
32 | function transfer(address to, uint amount) external returns (bool success) {
33 | balances.move(msg.sender, to, amount);
34 | emit Transfer(msg.sender, to, amount);
35 | return true;
36 |
37 | }
38 |
39 | function transferFrom(address from, address to, uint amount) external returns (bool success) {
40 | require(allowed[from][msg.sender] >= amount);
41 | allowed[from][msg.sender] -= amount;
42 | balances.move(from, to, amount);
43 | emit Transfer(from, to, amount);
44 | return true;
45 | }
46 |
47 | function approve(address spender, uint tokens) external returns (bool success) {
48 | require(allowed[msg.sender][spender] == 0, "");
49 | allowed[msg.sender][spender] = tokens;
50 | emit Approval(msg.sender, spender, tokens);
51 | return true;
52 | }
53 |
54 | function balanceOf(address tokenOwner) external view returns (uint balance) {
55 | return balances[tokenOwner];
56 | }
57 | }
58 |
--------------------------------------------------------------------------------
/docs/internals/layout_in_memory.rst:
--------------------------------------------------------------------------------
1 |
2 | .. index: memory layout
3 |
4 | ****************
5 | چیدمان در مِمُوری (Layout in Memory)
6 | ****************
7 |
8 | سالیدیتی چهار اسلات 32 بایتی را رزرو کرده که از محدودههای خاص (شامل نقاط پایانی) به شرح زیر استفاده شده:
9 |
10 | - ``0x00`` - ``0x3f`` آ(64 bytes): فضای Scratch برای متدهای هش کردن
11 | - ``0x40`` - ``0x5f`` آ(32 bytes): اندازه مِمُوری فعلی اختصاص داده شده (معروف به نشانگر حافظه آزاد )
12 | - ``0x60`` - ``0x7f`` آ(32 bytes): اسلات صفر
13 |
14 | فضای Scratch را میتوان بین دستورات (به عنوان مثال در اسمبلی درون خطی) استفاده کرد. اسلات صفر به
15 | عنوان مقدار اولیه برای آرایههای مِمُوری داینامیک استفاده میشود و هرگز نباید روی آن نوشته شود (اشارهگر
16 | مِمُوری آزاد در ابتدا به ``0x80`` اشاره میکند).
17 |
18 |
19 | سالیدیتی همیشه آبجکتهای جدید را در نشانگر مِمُوری آزاد قرار میدهد و مِمُوری هرگز آزاد نمیشود (این
20 | ممکن است در آینده تغییر کند).
21 |
22 |
23 |
24 | اِلمانهای موجود در آرایههای مِمُوری در سالیدیتی همیشه مضربی از 32 بایت را اشغال میکنند (این حتی
25 | برای ``[]bytes1`` صدق میکند، اما برای ``bytes`` و ``string`` صادق نمیباشد ). آرایههای مِمُوری چند
26 | بعدی نشانگر آرایههای مِمُوری هستند. طول یک آرایه داینامیک در اولین اسلات آرایه و به دنبال آن اِلمانهای
27 | آرایه ذخیره میشود.
28 |
29 |
30 |
31 |
32 | .. warning::
33 |
34 | برخی از عملیات در سالیدیتی وجود دارد که به فضای مِمُوری موقت بزرگتر از 64 بایت نیاز دارند و بنابراین در
35 | فضای اسکرچ قرار نمیگیرند. آنها در جایی قرار میگیرند که مِمُوری آزاد به آن اشاره میکند، اما با توجه به
36 | عمر کوتاه آنها، اشارهگر به روز نمیشود. مِمُوری ممکن است صفر شود یا صفر نشود. به همین دلیل، نباید
37 | انتظار داشت که مِمُوری آزاد به مِمُوری صفر اشاره کند.
38 |
39 |
40 |
41 | اگرچه ممکن است استفاده از ``msize`` برای رسیدن به یک فضای مِمُوری کاملاً صفر شده ایده خوبی به نظر
42 | برسد، استفاده از چنین اشارهگری بهطور غیرموقت و بدون بهروزرسانی نشانگر مِمُوری آزاد میتواند نتایج
43 | غیرمنتظرهای داشته باشد.
44 |
45 |
46 |
47 | تفاوت چیدمان در Storage
48 | ================================
49 |
50 | همانطور که در بالا توضیح داده شد، چیدمان در مِمُوری با چیدمان در :ref:`storage` متفاوت است. در زیر چند
51 | مثال وجود دارد.
52 |
53 |
54 | مثالی برای تفاوت در آرایهها
55 | --------------------------------
56 |
57 | آرایه زیر 32 بایت (1 اسلات) در storage اشغال میکند، اما 128 بایت (4 آیتم هر کدام با 32 بایت) در مِمُوری اشغال میکند.
58 |
59 |
60 | .. code-block:: solidity
61 |
62 | uint8[4] a;
63 |
64 |
65 |
66 | مثالی برای تفاوت در چیدمان Struct
67 | ---------------------------------------
68 | ساختار زیر 96 بایت (3 اسلات 32 بایتی) در storage اشغال میکند، اما 128 بایت (4 آیتم هر کدام با 32
69 | بایت) در مِمُوری اشغال میکند.
70 |
71 |
72 | .. code-block:: solidity
73 |
74 | struct S {
75 | uint a;
76 | uint b;
77 | uint8 c;
78 | uint8 d;
79 | }
80 |
--------------------------------------------------------------------------------
/docs/_static/css/custom.css:
--------------------------------------------------------------------------------
1 | h1,h2,h3,h4,h5,h6{
2 | direction: rtl;
3 | unicode-bidi: normal;
4 | }
5 |
6 | p{
7 |
8 | direction: rtl;
9 | unicode-bidi: normal;
10 | }
11 |
12 | dl, ol, ul {
13 | margin: 0;
14 | padding: 0;
15 | list-style: none;
16 | list-style-image: none;
17 | direction: rtl;
18 | }
19 |
20 | .wy-side-nav-search input[type=text] {
21 | width: 100%;
22 | border-radius: 50px;
23 | padding: 6px 12px;
24 | border-color: #2472a4;
25 | direction: rtl;
26 | }
27 | pre {
28 | white-space: pre-wrap; /* css-3 */
29 | white-space: -moz-pre-wrap; /* Mozilla, since 1999 */
30 | white-space: -pre-wrap; /* Opera 4-6 */
31 | white-space: -o-pre-wrap; /* Opera 7 */
32 | word-wrap: break-word;
33 | }
34 |
35 | .wy-table-responsive table td, .wy-table-responsive table th {
36 | white-space: normal;
37 | }
38 | .rst-content table.docutils td {
39 | vertical-align: top;
40 | }
41 |
42 | /* links */
43 | .rst-content a:not(:visited) {
44 | color: #002fa7;
45 | }
46 |
47 | .rst-content .highlighted {
48 | background: #eac545;
49 | }
50 |
51 | /* code block highlights */
52 | .rst-content pre {
53 | background: #fafafa;
54 | }
55 |
56 | .wy-side-nav-search img.logo {
57 | width: 100px !important;
58 | padding: 0;
59 | }
60 |
61 | .wy-side-nav-search > a {
62 | padding: 0;
63 | margin: 0;
64 | }
65 |
66 | /* project version (displayed under project logo) */
67 | .wy-side-nav-search .version {
68 | color: #272525 !important;
69 | }
70 |
71 | /* menu section headers */
72 | .wy-menu .caption {
73 | color: #65afff !important;
74 | }
75 |
76 | /* Link to Remix IDE shown next to code snippets */
77 | p.remix-link-container {
78 | position: relative;
79 | right: -100%; /* Positioned next to the the top-right corner of the code block following it. */
80 | }
81 |
82 | a.remix-link {
83 | position: absolute; /* Remove it from normal flow not to affect the original position of the snippet. */
84 | top: 0.5em;
85 | width: 3.236em; /* Size of the margin (= right-side padding in .wy-nav-content in the current theme). */
86 | }
87 |
88 | a.remix-link .link-icon {
89 | background: url("../img/solid-share-arrow.svg") no-repeat;
90 | display: block;
91 | width: 1.5em;
92 | height: 1.5em;
93 | margin: auto;
94 | }
95 |
96 | a.remix-link .link-text {
97 | display: none; /* Visible only on hover. */
98 | width: 3.3em; /* Narrow enough to get two lines of text. */
99 | margin: auto;
100 | text-align: center;
101 | font-size: 0.8em;
102 | line-height: normal;
103 | color: black;
104 | }
105 |
106 | a.remix-link:hover {
107 | opacity: 0.5;
108 | }
109 |
110 | a.remix-link:hover .link-text {
111 | display: block;
112 | }
113 |
--------------------------------------------------------------------------------
/docs/brand-guide.rst:
--------------------------------------------------------------------------------
1 | ####################
2 | Solidity Brand Guide
3 | ####################
4 |
5 | This brand guide features information on Solidity's brand policy and
6 | logo usage guidelines.
7 |
8 | The Solidity Brand
9 | ==================
10 |
11 | The Solidity programming language is an open-source, community project
12 | governed by a core team. The core team is sponsored by the `Ethereum
13 | Foundation `_.
14 |
15 | This document aims to provide information about how to best use the
16 | Solidity brand name and logo.
17 |
18 | We encourage you to read this document carefully before using the
19 | brand name or the logo. Your cooperation is highly appreciated!
20 |
21 | Solidity Brand Name
22 | ===================
23 |
24 | "Solidity" should be used to refer to the Solidity programming language
25 | solely.
26 |
27 | Please do not use "Solidity":
28 |
29 | - To refer to any other programming language.
30 |
31 | - In a way that is misleading or may imply association of unrelated
32 | modules, tools, documentation, or other resources with the Solidity
33 | programming language.
34 |
35 | - In ways that confuse the community as to whether the Solidity
36 | programming language is open-source and free to use.
37 |
38 | Solidity Logo License
39 | =====================
40 |
41 | .. image:: https://i.creativecommons.org/l/by/4.0/88x31.png
42 | :width: 88
43 | :alt: Creative Commons License
44 |
45 | The Solidity logo is distributed and licensed under a `Creative Commons
46 | Attribution 4.0 International License `_.
47 |
48 | This is the most permissive Creative Commons license and allows reuse
49 | and modifications for any purpose.
50 |
51 | You are free to:
52 |
53 | - **Share** — Copy and redistribute the material in any medium or format.
54 |
55 | - **Adapt** — Remix, transform, and build upon the material for any
56 | purpose, even commercially.
57 |
58 | Under the following terms:
59 |
60 | - **Attribution** — You must give appropriate credit, provide a link to
61 | the license, and indicate if changes were made. You may do so in any
62 | reasonable manner, but not in any way that suggests the the Solidity
63 | core team endorses you or your use.
64 |
65 | When using the Solidity logo, please respect the Solidity logo guidelines.
66 |
67 | Solidity Logo Guidelines
68 | ========================
69 |
70 | .. image:: logo.svg
71 | :width: 256
72 |
73 | *(Right click on the logo to download it.)*
74 |
75 | Please do not:
76 |
77 | - Change the ratio of the logo (do not stretch it or cut it).
78 |
79 | - Change the colors of the logo, unless it is absolutely necessary.
80 |
81 | Credits
82 | =======
83 |
84 | This document was, in parts, derived from the `Python Software
85 | Foundation Trademark Usage Policy `_
86 | and the `Rust Media Guide `_.
87 |
--------------------------------------------------------------------------------
/docs/types/operators.rst:
--------------------------------------------------------------------------------
1 | .. index:: assignment, ! delete, lvalue
2 |
3 | اپراتورهای شامل LValues
4 | ===========================
5 | اگر ``a`` یک LValue باشد (به عنوان مثال یک متغیر یا چیزی که میتوان به آن اختصاص داد)، عملگرهای زیر به صورت مختصر در دسترس هستند:
6 |
7 | ``a += e`` معادل ``a = a + e`` است. عملگرها ``=-`` ، ``=*`` ، ``=/`` ، ``%=`` ، ``=|`` ، ``=&`` و ``=^`` بر این
8 | اساس تعریف میشوند. ``++a`` و ``--a`` معادل ``a += 1`` / ``a -= 1`` هستند اما این عبارت هنوز مقدار
9 | قبلی ``a`` را دارد. در مقابل ، ``a--`` و ``a++`` تأثیر یکسانی در ``a`` دارند اما مقدار را پس از تغییر برمیگردانند.
10 |
11 |
12 | .. _delete:
13 |
14 | حذف
15 | ------
16 |
17 | ``delete a`` یک مقدار اولیه را برای نوع، به ``a`` اختصاص میدهد. یعنی برای اعداد صحیح معادل ``a = 0``
18 | است، اما همچنین میتواند در آرایه ها مورد استفاده قرار گیرد، جایی که یک آرایه پویا از طول صفر یا یک آرایه
19 | ایستا با همان طول را با تمام عناصر تنظیم شده روی مقدار اولیه خود اختصاص
20 | میدهد. ``delete a[x]`` مورد را در شاخص ``x`` آرایه حذف میکند و سایر عناصر و طول آرایه را دست
21 | نخورده باقی میگذارد. این کار به طور ویژه به این معنی است که در آرایه شکاف ایجاد میکند. اگر قصد حذف
22 | موارد را دارید، :ref:`mapping ` احتمالاً انتخاب بهتری است.
23 |
24 | برای structها، یک struct را با تنظیم مجدد همه اعضا اختصاص میدهد. به عبارت دیگر، مقدار ``a`` پس از
25 | ``delete a`` همانی است که اگر ``a`` بدون انتساب اعلام شود، با توجه به هشدار زیر:
26 |
27 |
28 | ``delete`` تأثیری در نگاشت ندارد (زیرا ممکن است کلیدهای نگاشت دلخواه باشند و به طور کلی ناشناخته باشند).
29 | بنابراین اگر یک struct را حذف کنید، همه اعضا را که نگاشت نباشند مجدد تنظیم میکند و همچنین
30 | به عضوها بازگشت مییابد مگر اینکه آنها نگاشت باشند. با این حال، کلیدهای جداگانه و به آنچه نگاشت میشوند
31 | میتوانند حذف شوند: اگر ``a`` نگاشت باشد، سپس ``delete a[x]`` مقدار ذخیره شده در ``x`` را حذف خواهد کرد.
32 |
33 |
34 | توجه به این نکته مهم است که ``delete a`` واقعاً مانند انتساب به ``a`` رفتار میکند، یعنی یک شی جدید
35 | را در ``a`` ذخیره میکند. این تمایز زمانی قابل مشاهدهاست که ``a`` متغیر مرجع باشد: فقط یک aرا خود
36 | مجدد تنظیم میکند نه مقداری که قبلاً به آن اشاره کرده بود.
37 |
38 |
39 |
40 | .. code-block:: solidity
41 |
42 | // SPDX-License-Identifier: GPL-3.0
43 | pragma solidity >=0.4.0 <0.9.0;
44 |
45 | contract DeleteExample {
46 | uint data;
47 | uint[] dataArray;
48 |
49 | function f() public {
50 | uint x = data;
51 | delete x; // sets x to 0, does not affect data
52 | delete data; // sets data to 0, does not affect x
53 | uint[] storage y = dataArray;
54 | delete dataArray; // this sets dataArray.length to zero, but as uint[] is a complex object, also
55 | // y is affected which is an alias to the storage object
56 | // On the other hand: "delete y" is not valid, as assignments to local variables
57 | // referencing storage objects can only be made from existing storage objects.
58 | assert(y.length == 0);
59 | }
60 | }
61 |
--------------------------------------------------------------------------------
/docs/ext/remix_code_links.py:
--------------------------------------------------------------------------------
1 | import base64
2 | import docutils # pragma pylint: disable=import-error
3 |
4 | from sphinx.util import logging # pragma pylint: disable=import-error
5 |
6 | # NOTE: 2000 should generally be safe for all browsers, while 8000 for most of them.
7 | MAX_SAFE_URL_LENGTH = 10000
8 |
9 | logger = logging.getLogger(__name__)
10 |
11 |
12 | def insert_node_before(child, new_sibling):
13 | assert child in child.parent.children
14 |
15 | for position, node in enumerate(child.parent.children):
16 | if node == child:
17 | child.parent.insert(position, new_sibling)
18 | break
19 |
20 |
21 | def remix_code_url(source_code, language, solidity_version):
22 | # NOTE: base64 encoded data may contain +, = and / characters. Remix seems to handle them just
23 | # fine without any escaping.
24 | base64_encoded_source = base64.b64encode(source_code.encode('utf-8')).decode('ascii')
25 | return f"https://remix.ethereum.org/?language={language}&version={solidity_version}&code={base64_encoded_source}"
26 |
27 |
28 | def build_remix_link_node(url):
29 | link_icon_node = docutils.nodes.inline()
30 | link_icon_node.set_class('link-icon')
31 |
32 | link_text_node = docutils.nodes.inline(text="open in Remix")
33 | link_text_node.set_class('link-text')
34 |
35 | reference_node = docutils.nodes.reference('', '', internal=False, refuri=url)
36 | reference_node.set_class('remix-link')
37 | reference_node += [link_icon_node, link_text_node]
38 |
39 | paragraph_node = docutils.nodes.paragraph()
40 | paragraph_node.set_class('remix-link-container')
41 | paragraph_node += reference_node
42 | return paragraph_node
43 |
44 |
45 | def insert_remix_link(app, doctree, solidity_version):
46 | if app.builder.format != 'html' or app.builder.name == 'epub':
47 | return
48 |
49 | for literal_block_node in doctree.traverse(docutils.nodes.literal_block):
50 | assert 'language' in literal_block_node.attributes
51 | language = literal_block_node.attributes['language'].lower()
52 | if language in ['solidity', 'yul']:
53 | text_nodes = list(literal_block_node.traverse(docutils.nodes.Text))
54 | assert len(text_nodes) == 1
55 |
56 | remix_url = remix_code_url(text_nodes[0], language, solidity_version)
57 | url_length = len(remix_url.encode('utf-8'))
58 | if url_length > MAX_SAFE_URL_LENGTH:
59 | logger.warning(
60 | "Remix URL generated from the code snippet exceeds the maximum safe URL length "
61 | " (%d > %d bytes).",
62 | url_length,
63 | MAX_SAFE_URL_LENGTH,
64 | location=(literal_block_node.source, literal_block_node.line),
65 | )
66 |
67 | insert_node_before(literal_block_node, build_remix_link_node(remix_url))
68 |
69 |
70 | def setup(app):
71 | # NOTE: Need to access _raw_config here because setup() runs before app.config is ready.
72 | solidity_version = app.config._raw_config['version'] # pylint: disable=protected-access
73 |
74 | app.connect(
75 | 'doctree-resolved',
76 | lambda app, doctree, docname: insert_remix_link(app, doctree, solidity_version)
77 | )
78 |
79 | return {
80 | 'version': solidity_version,
81 | 'parallel_read_safe': True,
82 | 'parallel_write_safe': True,
83 | }
84 |
--------------------------------------------------------------------------------
/docs/internals/source_mappings.rst:
--------------------------------------------------------------------------------
1 | .. index:: source mappings
2 |
3 | ***************
4 | Mappingهای سورس
5 | ***************
6 |
7 | به عنوان بخشی از خروجی AST، کامپایلر محدوده سورسکد را ارائه میدهد که توسط گره مربوطه در AST
8 | نشان داده میشود. این میتواند برای اهداف مختلفی استفاده شود از جمله ابزارهای آنالیز استاتیک که خطاها را
9 | بر اساس AST گزارش میکنند و ابزارهای اشکال زدایی که متغیرهای محلی و کاربردهای آنها را برجسته میکنند.
10 |
11 |
12 |
13 | علاوه بر این، کامپایلر همچنین میتواند یک mapping از بایتکد به محدوده سورس کدی که دستور را ایجاد
14 | کرده است، ایجاد کند. این دوباره برای ابزارهای آنالیز استاتیک که در سطح بایتکد کار میکنند و برای نمایش
15 | موقعیت فعلی در سورسکد در داخل یک دیباگر یا برای رسیدگی به نقطه شکست مهم است. این mapping
16 | همچنین حاوی اطلاعات دیگری مانند تایپ jump و عمق اصلاح کننده (modifier) است (به قسمت زیر
17 | مراجعه کنید).
18 |
19 |
20 |
21 | هر دو تایپ mappingهای سورس از مشخص کنندههای اینتیجر برای ارجاع به سورس فایل استفاده میکنند.
22 | مشخص کننده یک سورس فایل در ``output['sources'][sourceName]['id']`` ذخیره میشود، جایی
23 | که ``output`` خروجی اینترفیس کامپایلر استاندارد-json است که بهعنوان JSON تجزیه میشود. برای برخی از
24 | روتینهای کاربردی، کامپایلر سورس فایلهای «داخلی(internal)» را تولید میکند که بخشی از ورودی اصلی
25 | نیستند، اما از mappingهای سورس ارجاع داده میشوند. این سورس فایلهای همراه با مشخص کنندهایشان
26 | را میتوان از طریق خروجی
27 | ``output['contracts'][sourceName][contractName]['evm']['bytecode']['generatedSources']`` به دست
28 | آورد.
29 |
30 |
31 |
32 | .. note ::
33 |
34 | در مورد دستورالعملهایی که با هیچ سورس فایل خاصی مرتبط نیستند، سورس mapping یک مشخص
35 | کننده عدد اینتیجر ``1-`` را اختصاص میدهد. این ممکن است برای بخشهای بایتکد ناشی از دستورات
36 | اسمبلی درون خطی تولید شده توسط کامپایلر اتفاق بیفتد.
37 |
38 | سورس mapping در داخل AST از نشانه گذاری زیر استفاده میکند:
39 |
40 |
41 | ``s:l:f``
42 |
43 | در جایی که ``s`` مقدار بایت آفست شروع محدوده در سورس فایل است، ``l`` طول محدوده سورس بر حسب بایت
44 | و ``f`` ایندکس سورس ذکر شده در بالا است.
45 |
46 |
47 | رمزگذاری در سورس mapping برای بایتکد پیچیدهتر است: این لیستی از ``s:l:f:j:m`` است که با ``;`` از
48 | هم جدا شدهاست. هر یک از این اِلمان مربوط به یک دستورالعمل است، یعنی شما نمیتوانید از آفست بایت
49 | استفاده کنید اما باید از آفست دستورالعمل استفاده کنید (دستورالعملهای push طولانیتر از یک بایت هستند).
50 | فیلدهای ``s`` ، ``l`` و ``f`` مانند بالا هستند. ``j`` میتواند ``i`` ، ``o`` یا ``-`` باشد که نشان میدهد آیا دستور push
51 | به یک تابع میرود، از یک تابع برمیگردد یا یک push منظم به عنوان بخشی از، برای مثال یک حلقه باشد.
52 | آخرین فیلد، ``m`` ، یک اینتیجر است که "عمق modifier " را نشان میدهد. هر زمان که (``_``) placeholder
53 | statement در یک modifier وارد شود، این عمق افزایش مییابد و با رها کردن مجدد آن کاهش
54 | مییابد. این به دیباگرها اجازه میدهد موارد پیچیده را ردیابی کنند، مانند modifierای که دو بار استفاده
55 | میشود یا چندین placeholder statements در یک modifier واحد استفاده میشود.
56 |
57 |
58 | برای فشرده سازی این سورس mappingهای بخصوص برای بایتکد، از قوانین زیر استفاده میشود:
59 |
60 |
61 |
62 | - اگر یک فیلد خالی باشد، از value اِلمان قبلی استفاده میشود.
63 | - اگر یک ``:`` وجود نداشته باشد، تمام فیلدهای بعدی خالی در نظر گرفته میشوند.
64 |
65 |
66 | این بدان معنی است که سورس mapping زیر همان اطلاعات را نشان میدهد:
67 |
68 |
69 | ``2:1:2;2:1:2;2:1:2;1:9:1;1:2:1``
70 |
71 | ``;;2:1:2;9:;1:2:1``
72 |
73 | نکته مهم این است که وقتی از :ref:`verbatim ` builtin استفاده شود، mapping سورس نامعتبر خواهد بود:
74 | builtin به جای چندتایی یک دستور واحد در نظر گرفته میشود.
75 |
--------------------------------------------------------------------------------
/docs/contracts/errors.rst:
--------------------------------------------------------------------------------
1 | .. index:: ! error, revert
2 |
3 | .. _errors:
4 |
5 | *******************************
6 | خطاها و عبارت واکشی
7 | *******************************
8 |
9 | خطاهای سالیدیتی یک روش مناسب و کارآمد برای ارائه توضیحات در مورد عدم موفقیت یک
10 | عملیات به کار بر ارائه می دهد. آنها می توانند در داخل و خارج از قرارداد( از جمله رابط ها و کتابخانه ها) تعریف شوند.
11 |
12 | آنها باید به همارت :ref:`عبارت revert ` استفاده شوند که باعث می شود همه تغییرات در فراخوانی
13 | فعلی برگردانده شود داده های خطا به فراخوانی کننده منتقل می شود.
14 |
15 | .. code-block:: solidity
16 |
17 | // SPDX-License-Identifier: GPL-3.0
18 | pragma solidity ^0.8.4;
19 |
20 | /// Insufficient balance for transfer. Needed `required` but only
21 | /// `available` available.
22 | /// @param available balance available.
23 | /// @param required requested amount to transfer.
24 | error InsufficientBalance(uint256 available, uint256 required);
25 |
26 | contract TestToken {
27 | mapping(address => uint) balance;
28 | function transfer(address to, uint256 amount) public {
29 | if (amount > balance[msg.sender])
30 | revert InsufficientBalance({
31 | available: balance[msg.sender],
32 | required: amount
33 | });
34 | balance[msg.sender] -= amount;
35 | balance[to] += amount;
36 | }
37 | // ...
38 | }
39 |
40 | خطاها غیر قابل بارگزاری یا بازنویسی هستنتد اما قابل وراثت هستند.
41 | همان خطا می تواند در چند مکان مختلف تعریف شود تا زمانی که در محدوده دید همپوشانی نداشته باشد. نمونه خطاها
42 | فقط می توانند توسط عبارت ``revert`` تولید شوند.
43 |
44 | خطا داده را تولید می کند و آن را به همراه عملیات revert به فراخوانی کننده خارج از زنجیره
45 | یا به گیرنده عبارت :ref:`try/catch statement ` بر می گرداند. نکته اینکه یک خطا تنها زمانی گرفته می شود که
46 | توسط یک فراخوانی خارجی انجام شده باشد، واکشی ها در فراخوانی داخلی اتفاق می افتد و
47 | داخل همان تابع غیر قابل گرفتن است.
48 |
49 | اگر هیچ ورودی فراهم نشود، شما فقط به 4 بایت داده خطا نیاز دارید و شما می توانید از
50 | :ref:`NatSpec ` در بالا برای توضیح بیشتر دلایل این خطا، که در زنجیره ذخیره نشده است، استفاده
51 | کنید.
52 | This makes this a very cheap and convenient error-reporting feature at the same time.
53 |
54 | دقیقتر اینکه، یک نمونه خطا به همان صورت ABI کدکذاری می شود که فراخوانی به یک نابع با
55 | همان نام و نوع های آن است و سپس به عنوان داده بازگشت ``revert`` در کد باز گردانده می شود. به
56 | این معناست که داده ها از یک انتخابگر 4 بایتی و سپس داده های کد شده توسط :ref:`ABI-encoded` تشکیل
57 | شده اند. انتخابگر شامل 4 بایت اول هش keccak256-hash از نوع خطا است.
58 |
59 | .. note::
60 | این امکان وجود دارد که یک قرارداد با خطاهای مختلف به همین نام یا حتی با خطاهایی که
61 | در مکان هایی یکسان هستند تعریف شده باشند و توسط فراخوانی کننده قابل تشخیص نباشند،
62 | بازگردد. برای خارج ، یعنی ABI ، فقط با نام خطا ارتباط دارد، نه قرارداد و نه فایلی که در آن
63 | تعریف شده است.
64 |
65 | عبارت ``;require(condition, "description")`` معادل خواهد بود
66 | با ``if (!condition) revert Error("description")`` اگر شما بتوانید تعریف کنید
67 | ``error Error(string)``.
68 | آن ``Error`` یک نوع داخلی است و در کد فراهم شده توسط کاربر قابل تعریف نیست.
69 |
70 | مشابها، یک خطای ``assert`` یا شرایط مشابه به همراه یک خطایی از نوع داخلی
71 | ``Panic(uint256)`` خواهد بود.
72 |
73 | .. note::
74 | داده های خطا فقط باید برای نشان دادن خطا مورد استفاده قرار گیرند، نه برای کنترل
75 | جریان. دلیل آن این است که داده های بازگشتی از فراخوانی داخلی به صورت پیش فرض از
76 | طریق زنجیره فراخوانی های خارجی پخش می شوند. این بدان معناست که یک فراخوانی
77 | داخلی می تواند "جعل" کند، داده هایی را که به نظر می رسد از آن قرارداد فراخانی شده است.
78 |
--------------------------------------------------------------------------------
/docs/bugs.rst:
--------------------------------------------------------------------------------
1 | .. index:: Bugs
2 |
3 | .. _known_bugs:
4 |
5 | #######################
6 | لیست باگهای شناخته شده
7 | #######################
8 |
9 | در زیر ، می توانید لیستی از برخی اشکالات شناخته شده مربوط به امنیت در کامپایلر سالیدیتی
10 | را در قالب جیسون پیدا کنید. خود فایل در `مخزن گیت هاب `_ . میزبانی می شود.
11 | این لیست تا نسخه 0.3.0 امتداد دارد، اشکالات قبلی حاضر هستند و اشکالاتی که بعد از ارائه شدن نسخه
12 | نبودند در این لیست وجود دارد.
13 |
14 | فایل دیگری بنام `bugs_by_version.json `_ وجود دارد ، که می تواند برای بررسی اشکالات
15 | موجود بر نسخه خاصی از کامپایلر مورد استفاده قرار گیرد.
16 |
17 | ابزار های تصدیق منبع قرارداد و همچنین سایر ابزار های تعاملی با قرارداد ها طبق این لیست
18 | معیارها باید شرایط ذیل را داشته باشند:
19 |
20 | - اگر قراردادی بجای نسخه کامپایلر منتشر شده با نسخه کامپایلرشبانه، کامپایل شود ،
21 | کمی مشکوک است. این لیست نسخه های منتشر نشده با شبانه را دنبال نمی کند.
22 | - همچنین اگر قراردادی با آخرین نسخه منتشر شده کامپایلر ، کامپایل نشده باشد، کمی
23 | مشکوک است. برای قراردادهایی که با استفاده از سایر قراردادها ایجاد شده اند، شما
24 | باید زنجیره ایجاد یک تراکنش را دنبال کنید و از تاریخ آن تراکنش به عنوان تاریخ ایجاد
25 | قرارداد استفاده کنید.
26 | - اگر قراردادی با کامپایلری که حاوی اشکال شناخته شده است ، کامپایل شده باشد و
27 | زمان ایجاد قرارداد بعد از تاریخ انتشار نسخه جدید کامپایلر با رفع اشکال مذکور باشد.
28 | آن قرارداد بسیار مشکوک است.
29 |
30 | فایل json اشکالات شناخته شده زیر ، یک آرایه ای از شی ها برای هر اشکال(bug) است ، به
31 | همراه کلید های زیر:
32 |
33 | uid
34 | Unique identifier given to the bug in the form of ``SOL--``.
35 | It is possible that multiple entries exists with the same uid. This means
36 | multiple version ranges are affected by the same bug.
37 | نام
38 | نام اختصاری داده شده به اشکال(bug)
39 | خلاصه
40 | توضیح کوتاه در مورد اشکال
41 | شرح
42 | شرح کامل از اشکال
43 | پیوند(link)
44 | URL وب سایت به همراه اطلاعات دقیقتر ، اختیاری
45 | معرفی شده
46 | اولین نسخه کامپایلر منتشر شده که دارای اشکال است، اختیاری
47 | تعمیر شده
48 | اولین نسخه کامپایلر منتشر شده که دیگر دارای آن اشکال نیست
49 | انتشار
50 | تاریخی که اشکال برای عموم شناخته شده است ، اختیاری
51 | شدت
52 | شدت(سختی) اشکال : خیلی کم ، کم ، متوسط ، زیاد. میزان قابل کشف بودن در تست
53 | های قرار داد در نظر گرفته می شود. احتمال افتادن اتفاق ، خسارت و سوء استفاده توسط
54 | exploit ها (exploit: تکه کد، برنامه نرم افزاری ، ترتیب انجام چند رفتار با قرارداد و ... که از
55 | اشکال موجود در قرارداد برای انجام اهداف مخرب بهره می برد).
56 | شرایط
57 | شرایطی که اشکال را تحریک می کنند . نام کلیدی ذیل قابل استفاده است :
58 | ``optimizer`` ، مقداری بولی(true/false) که مشخص می کند اگر ``optimizer`` فعال شود
59 | احتمال وقوع اشکال است. ``evmVersion`` ، رشته ای که مشخص می کند کدام تنظیمات
60 | کامپایلر نسخه EVM اشکال را تحریک می کنند. این رشته می تواند شامل عملگر های مقایسه
61 | ای نیز باشد. برای مثال ، ``">=constantinople"`` به این معنی است که اگر از EVM خود
62 | نسخه ``constantinople`` و یا به بعد استفاده شود، اشکال رخ می دهد . در صورت عدم ارائه
63 | شرایط ، فرض بر این است که اشکال در تمامی شرایط رخ می دهد.
64 | بررسی
65 | این بخش شامل چک-لیست هایی است که مشخص می کند قراداد های هوشمند
66 | اشکال دارند یا نه. اولین نوع بررسی عبارات منظم جاوا اسکریپت است که در صورت وجود
67 | اشکال باید کد منبع با ("source-regex") مطابقت داشته باشد. اگر مطابقتی وجود نداشته باشد،
68 | پس به اختمال زیاد اشکال وجود ندارد. اگر مطابقت وجود داشته باشد، احتمال وجود اشکال
69 | است. برای دقت بیشتر ، بررسی ها باید پس از حذف حاشیه نویسی ها(comments) در کد
70 | منبع (source code) انجام شود. دومین نوع بررسی الگوهایی است که باید بر روی AST
71 | فشرده برنامه سالیدتی اعمال کرد.(“ast-compact-json-path”). عبارت مشخص شده
72 | جستجو عبارتی از نوع `JsonPath `_ است. اگر حداقل یک مسیر از AST سالیدتی با عبارت
73 | جستجو شده تطابق کند، اشکال به احتمال زیاد وجود دارد.
74 |
75 | .. literalinclude:: bugs.json
76 | :language: js
77 |
--------------------------------------------------------------------------------
/docs/contracts/using-for.rst:
--------------------------------------------------------------------------------
1 | .. index:: ! using for, library
2 |
3 | .. _using-for:
4 |
5 | *********
6 | Using For
7 | *********
8 |
9 | The directive ``using A for B;`` can be used to attach library
10 | functions (from the library ``A``) to any type (``B``)
11 | in the context of a contract.
12 | These functions will receive the object they are called on
13 | as their first parameter (like the ``self`` variable in Python).
14 |
15 | The effect of ``using A for *;`` is that the functions from
16 | the library ``A`` are attached to *any* type.
17 |
18 | In both situations, *all* functions in the library are attached,
19 | even those where the type of the first parameter does not
20 | match the type of the object. The type is checked at the
21 | point the function is called and function overload
22 | resolution is performed.
23 |
24 | The ``using A for B;`` directive is active only within the current
25 | contract, including within all of its functions, and has no effect
26 | outside of the contract in which it is used. The directive
27 | may only be used inside a contract, not inside any of its functions.
28 |
29 | Let us rewrite the set example from the
30 | :ref:`libraries` in this way:
31 |
32 | .. code-block:: solidity
33 |
34 | // SPDX-License-Identifier: GPL-3.0
35 | pragma solidity >=0.6.0 <0.9.0;
36 |
37 |
38 | // This is the same code as before, just without comments
39 | struct Data { mapping(uint => bool) flags; }
40 |
41 | library Set {
42 | function insert(Data storage self, uint value)
43 | public
44 | returns (bool)
45 | {
46 | if (self.flags[value])
47 | return false; // already there
48 | self.flags[value] = true;
49 | return true;
50 | }
51 |
52 | function remove(Data storage self, uint value)
53 | public
54 | returns (bool)
55 | {
56 | if (!self.flags[value])
57 | return false; // not there
58 | self.flags[value] = false;
59 | return true;
60 | }
61 |
62 | function contains(Data storage self, uint value)
63 | public
64 | view
65 | returns (bool)
66 | {
67 | return self.flags[value];
68 | }
69 | }
70 |
71 |
72 | contract C {
73 | using Set for Data; // this is the crucial change
74 | Data knownValues;
75 |
76 | function register(uint value) public {
77 | // Here, all variables of type Data have
78 | // corresponding member functions.
79 | // The following function call is identical to
80 | // `Set.insert(knownValues, value)`
81 | require(knownValues.insert(value));
82 | }
83 | }
84 |
85 | It is also possible to extend elementary types in that way:
86 |
87 | .. code-block:: solidity
88 |
89 | // SPDX-License-Identifier: GPL-3.0
90 | pragma solidity >=0.6.8 <0.9.0;
91 |
92 | library Search {
93 | function indexOf(uint[] storage self, uint value)
94 | public
95 | view
96 | returns (uint)
97 | {
98 | for (uint i = 0; i < self.length; i++)
99 | if (self[i] == value) return i;
100 | return type(uint).max;
101 | }
102 | }
103 |
104 | contract C {
105 | using Search for uint[];
106 | uint[] data;
107 |
108 | function append(uint value) public {
109 | data.push(value);
110 | }
111 |
112 | function replace(uint _old, uint _new) public {
113 | // This performs the library function call
114 | uint index = data.indexOf(_old);
115 | if (index == type(uint).max)
116 | data.push(_new);
117 | else
118 | data[index] = _new;
119 | }
120 | }
121 |
122 | Note that all external library calls are actual EVM function calls. This means that
123 | if you pass memory or value types, a copy will be performed, even of the
124 | ``self`` variable. The only situation where no copy will be performed
125 | is when storage reference variables are used or when internal library
126 | functions are called.
127 |
--------------------------------------------------------------------------------
/docs/contracts/constant-state-variables.rst:
--------------------------------------------------------------------------------
1 | .. index:: ! constant
2 |
3 | .. _constants:
4 |
5 | **************************************
6 | متغیر های وضعیت ثابت و تغییر ناپذیر
7 | **************************************
8 |
9 |
10 | متغیر های وضعیت می توانند به عنوان ثابت ``constant`` یا تغییرناپذیر ``immutable`` تعریف شوند. در هر دو حالت ، متغیر
11 | ها بعد از ساخته شدن قرارداد غیر قابل دستکاری هستند. برای متغیر های ثابت ``constant`` ، مقدار دهی
12 | باید زمان کامپایل انجام شده باشد ، در صورتی که برای متغیر های تغییر ناپذیر ``immutable`` حین ساخته
13 | شدن قرارداد می توان مقدار دهی کرد.
14 |
15 | همچنین ممکن است متغیر های ثابت ``constant`` در سطح فایل تعریف شوند.
16 |
17 | کامپایلر برای این نوع متغیر ها، شکاف(slot) ذخیره سازی رزرو نمی کند و هر مورد با مقدار
18 | مربوطه خود جایگزین می شود.
19 |
20 | در مقایسه با متغیر های وضعیت معمولی ، هزینه های گاز(gas) متغیر های ثابت و تغییرناپذیر
21 | خیلی خیلی پایینتر است. برای یک متغیر ثابت عبارتی که به آن اختصاص داده شده است(مقدار
22 | دهی شده است) در همه جاهایی که به آن دسترسی وجود دارد کپی شده و همچنین در هر بار
23 | بازبینی می شود. این بهینه سازی محلی را ممکن می کند. متغیر های تغییر ناپذیر یک بار هنگام
24 | ساخت بررسی می شوند و مقدار آنها در هر جایی که دسترسی به آن وجود دارد کپی می شود.
25 | برای این نوع مقادیر، 32 بایت رزرو شده است حتی اگر این مقادیر در بایت کمتری هم جا
26 | شوند. بنابراین ، مقادیر ثابت گاها ارزانتر از مقادیر تغییرناپذیر هستند.
27 |
28 | تمامی نوع های متغیر فعلا برای ثابت و تغییر ناپذیر پیاشده سازی نشده اند . فقط نوع :ref:`strings `
29 | (فقط برای ثابت) و نوعهای مقداری :ref:`value types `.
30 |
31 | .. code-block:: solidity
32 |
33 | // SPDX-License-Identifier: GPL-3.0
34 | pragma solidity >=0.7.4;
35 |
36 | uint constant X = 32**22 + 8;
37 |
38 | contract C {
39 | string constant TEXT = "abc";
40 | bytes32 constant MY_HASH = keccak256("abc");
41 | uint immutable decimals;
42 | uint immutable maxBalance;
43 | address immutable owner = msg.sender;
44 |
45 | constructor(uint _decimals, address _reference) {
46 | decimals = _decimals;
47 | // Assignments to immutables can even access the environment.
48 | maxBalance = _reference.balance;
49 | }
50 |
51 | function isBalanceTooHigh(address _other) public view returns (bool) {
52 | return _other.balance > maxBalance;
53 | }
54 | }
55 |
56 |
57 | ثابت
58 | ========
59 |
60 | برای متغیر های ثابت ``constant`` ، در زمان کامپایل مقدار باید ثابت باشد و در جایی که متغیر تعریف می
61 | شود مقدار دهی می شود. هر عبارتی که به ذخیره سازی، داده های بلاکچین(مثل زمان بلوک ``block.timestamp`` ،
62 | آدرس(این[بلوک] ``address(this).balance`` ) میزان حساب ``address(this).balance`` یا شماره بوک ``block.number`` ) یا اجراییه های داده ای( ``msg.value`` یا
63 | ``()gasleft``) یا فراخوانی قراردادهای خارجی ممنوع است. عباراتی که ممکن است در تخصیص
64 | حافظه اثر جانبی داشته باشند مجاز هستند، اما آنهایی که ممکن است بر سایر اجزای حافظه
65 | تاثیر جانبی داشته باشند، مجاز نیستند. توابع داخلی ``keccak256`` ، ``sha256`` ، ``ripemd160`` ،
66 | ``ecrecover`` ، ``addmod`` و ``mulmod`` مجاز هستند ( حتی به همراه عبارت ``keccak256`` ، می
67 | توان قراردادهای خارجی نیز فراخوانی کرد).
68 |
69 | دلیل اجازه به تخصیص عوارض جانبی بر روی حافظه برای امکانسازی ساخت اشایه پیچیده مثل
70 | جدول-جستجو است. این ویژگی هنوز به طور کامل قابل استفاده نیست.
71 |
72 | تغییر ناپذیر
73 | =============
74 |
75 | متغیر های تعریف شده به عنوان تغییرناپذیر ``immutable`` محدودیت کمتری نسبت به متغیر های ثابت ``constant`` دارند :
76 | به متغیر های تغییر ناپذیر می توان یک مقدار دلخواه در سازنده قرارداد یا در زمان تعریف آنها
77 | اختصاص داد. انها نمی توانند در زمان ساخت خوانده شوند و فقط یک بار مقدار دهی می شوند.
78 |
79 | کد ساخت قرارداد که توسط کامپایلر تولید می شود قبل از بازگشت کد حین اجرایی قرارداد
80 | تمامی مراجعی که به متغیر تغییر ناپذیر اشاره می کند را مقداردهی خواهد کرد. این زمانی
81 | اهمیت دارد که می خواهید کد تولید شده توسط کامپایلر را با کد در حال حاضر ذخیره شده در
82 | بلاکچین مقایسه کنید.
83 |
84 | .. note::
85 | Immutables that are assigned at their declaration are only considered
86 | initialized once the constructor of the contract is executing.
87 | This means you cannot initialize immutables inline with a value
88 | that depends on another immutable. You can do this, however,
89 | inside the constructor of the contract.
90 |
91 | This is a safeguard against different interpretations about the order
92 | of state variable initialization and constructor execution, especially
93 | with regards to inheritance.
--------------------------------------------------------------------------------
/CMakeLists.txt:
--------------------------------------------------------------------------------
1 | cmake_minimum_required(VERSION 3.13.0)
2 |
3 | set(ETH_CMAKE_DIR "${CMAKE_CURRENT_LIST_DIR}/cmake" CACHE PATH "The the path to the cmake directory")
4 | list(APPEND CMAKE_MODULE_PATH ${ETH_CMAKE_DIR})
5 |
6 | # Set the build type, if none was specified.
7 | if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
8 | if(EXISTS "${CMAKE_SOURCE_DIR}/.git")
9 | set(DEFAULT_BUILD_TYPE "RelWithDebInfo")
10 | else()
11 | set(DEFAULT_BUILD_TYPE "Release")
12 | endif()
13 | set(CMAKE_BUILD_TYPE "${DEFAULT_BUILD_TYPE}" CACHE STRING "Choose the type of build, options are: Debug Release RelWithDebInfo MinSizeRel" FORCE)
14 | set_property(CACHE CMAKE_BUILD_TYPE PROPERTY STRINGS "Debug" "Release" "RelWithDebInfo" "MinSizeRel")
15 | endif()
16 |
17 | include(EthToolchains)
18 |
19 | # Set cmake_policies
20 | include(EthPolicy)
21 | eth_policy()
22 |
23 | # project name and version should be set after cmake_policy CMP0048
24 | set(PROJECT_VERSION "0.8.10")
25 | # OSX target needed in order to support std::visit
26 | set(CMAKE_OSX_DEPLOYMENT_TARGET "10.14")
27 | project(solidity VERSION ${PROJECT_VERSION} LANGUAGES C CXX)
28 |
29 | include(TestBigEndian)
30 | TEST_BIG_ENDIAN(IS_BIG_ENDIAN)
31 | if (IS_BIG_ENDIAN)
32 | message(FATAL_ERROR "${PROJECT_NAME} currently does not support big endian systems.")
33 | endif()
34 |
35 | option(SOLC_LINK_STATIC "Link solc executable statically on supported platforms" OFF)
36 | option(SOLC_STATIC_STDLIBS "Link solc against static versions of libgcc and libstdc++ on supported platforms" OFF)
37 | option(STRICT_Z3_VERSION "Use the latest version of Z3" ON)
38 |
39 | # Setup cccache.
40 | include(EthCcache)
41 |
42 | # Let's find our dependencies
43 | include(EthDependencies)
44 | include(fmtlib)
45 | include(jsoncpp)
46 | include(range-v3)
47 | include_directories(SYSTEM ${JSONCPP_INCLUDE_DIR})
48 |
49 | find_package(Threads)
50 |
51 | # Figure out what compiler and system are we using
52 | include(EthCompilerSettings)
53 |
54 | # Include utils
55 | include(EthUtils)
56 |
57 | # Create license.h from LICENSE.txt and template
58 | # Converting to char array is required due to MSVC's string size limit.
59 | file(READ ${CMAKE_SOURCE_DIR}/LICENSE.txt LICENSE_TEXT HEX)
60 | string(REGEX MATCHALL ".." LICENSE_TEXT "${LICENSE_TEXT}")
61 | string(REGEX REPLACE ";" ",\n\t0x" LICENSE_TEXT "${LICENSE_TEXT}")
62 | set(LICENSE_TEXT "0x${LICENSE_TEXT}")
63 |
64 | configure_file("${CMAKE_SOURCE_DIR}/cmake/templates/license.h.in" include/license.h)
65 |
66 | include(EthOptions)
67 | configure_project(TESTS)
68 | set(LATEST_Z3_VERSION "4.8.12")
69 | set(MINIMUM_Z3_VERSION "4.8.0")
70 | find_package(Z3)
71 | if (${Z3_FOUND})
72 | if (${STRICT_Z3_VERSION})
73 | if (NOT ("${Z3_VERSION_STRING}" VERSION_EQUAL ${LATEST_Z3_VERSION}))
74 | message(
75 | FATAL_ERROR
76 | "SMTChecker tests require Z3 ${LATEST_Z3_VERSION} for all tests to pass.\n\
77 | Build with -DSTRICT_Z3_VERSION=OFF if you want to use a different version. \
78 | You can also use -DUSE_Z3=OFF to build without Z3. In both cases use --no-smt when running tests."
79 | )
80 | endif()
81 | else()
82 | if ("${Z3_VERSION_STRING}" VERSION_LESS ${MINIMUM_Z3_VERSION})
83 | message(
84 | FATAL_ERROR
85 | "Solidity requires Z3 ${MINIMUM_Z3_VERSION} or newer. You can also use -DUSE_Z3=OFF to build without Z3."
86 | )
87 | endif()
88 | endif()
89 | endif()
90 |
91 | if(${USE_Z3_DLOPEN})
92 | add_definitions(-DHAVE_Z3)
93 | add_definitions(-DHAVE_Z3_DLOPEN)
94 | find_package(Python3 COMPONENTS Interpreter)
95 | if(${Z3_FOUND})
96 | get_target_property(Z3_HEADER_HINTS z3::libz3 INTERFACE_INCLUDE_DIRECTORIES)
97 | endif()
98 | find_path(Z3_HEADER_PATH z3.h HINTS ${Z3_HEADER_HINTS})
99 | if(Z3_HEADER_PATH)
100 | set(Z3_FOUND TRUE)
101 | else()
102 | message(SEND_ERROR "Dynamic loading of Z3 requires Z3 headers to be present at build time.")
103 | endif()
104 | if(NOT ${Python3_FOUND})
105 | message(SEND_ERROR "Dynamic loading of Z3 requires Python 3 to be present at build time.")
106 | endif()
107 | if(${SOLC_LINK_STATIC})
108 | message(SEND_ERROR "solc cannot be linked statically when dynamically loading Z3.")
109 | endif()
110 | elseif (${Z3_FOUND})
111 | add_definitions(-DHAVE_Z3)
112 | message("Z3 SMT solver found. This enables optional SMT checking with Z3.")
113 | endif()
114 |
115 | find_package(CVC4 QUIET)
116 | if (${CVC4_FOUND})
117 | add_definitions(-DHAVE_CVC4)
118 | message("CVC4 SMT solver found. This enables optional SMT checking with CVC4.")
119 | endif()
120 |
121 | if (NOT (${Z3_FOUND} OR ${CVC4_FOUND}))
122 | message("No SMT solver found (or it has been forcefully disabled). Optional SMT checking will not be available.\
123 | \nPlease install Z3 or CVC4 or remove the option disabling them (USE_Z3, USE_CVC4).")
124 | endif()
125 |
126 | add_subdirectory(libsolutil)
127 | add_subdirectory(liblangutil)
128 | add_subdirectory(libsmtutil)
129 | add_subdirectory(libevmasm)
130 | add_subdirectory(libyul)
131 | add_subdirectory(libsolidity)
132 | add_subdirectory(libsolc)
133 | add_subdirectory(tools)
134 |
135 | if (NOT EMSCRIPTEN)
136 | add_subdirectory(solc)
137 | endif()
138 |
139 | if (TESTS AND NOT EMSCRIPTEN)
140 | add_subdirectory(test)
141 | endif()
--------------------------------------------------------------------------------
/docs/contracts/creating-contracts.rst:
--------------------------------------------------------------------------------
1 | .. index:: ! contract;creation, constructor
2 |
3 | ******************
4 | ایجاد قراردادها
5 | ******************
6 | قراردادها را میتوان "از خارج" از طریق تراکنشهای اتریوم یا از طریق قراردادهای سالیدیتی ایجاد کرد.
7 |
8 |
9 | IDE هایی، مانند `Remix `_ ، فرآیند ایجاد را با استفاده از المانهای UI انجام میدهند.
10 |
11 |
12 | یکی از راههای ایجاد قراردادها به صورت برنامهای در اتریوم، استفاده از API جاوا اسکریپت `web3.js `_ است.
13 | یک تابع به نام `web3.eth.Contract `_ برای تسهیل ایجاد قرارداد را دارد.
14 |
15 |
16 | هنگامی که یک قرارداد ایجاد میشود، :ref:`constructor ` آن (تابع اعلام شده با کلمه کلیدی ``constructor`` )
17 | یک بار اجرا میشود.
18 |
19 |
20 | کانستراکتور اختیاری است. فقط یک کانستراکتور مجاز است، به این معنی که overloading پشتیبانی نمیشود.
21 |
22 |
23 |
24 | پس از اجرای کانستراکتور، کد نهایی قرارداد بر روی بلاکچین ذخیره میشود. این کد شامل تمام توابع عمومی و
25 | خارجی و همه توابعی است که از طریق فراخوانی تابع از آنجا قابل دسترسی است. کد به کار رفته شامل کد
26 | کانستراکتور یا توابع داخلی نیست که فقط از سازنده فراخوانی میشوند.
27 |
28 |
29 | .. index:: constructor;arguments
30 |
31 | در داخل، آرگومانهای کانستراکتور :ref:`ABI encoded ` پس از کد خود قرارداد ارسال میشوند، اما اگر از
32 | ``web3.js`` استفاده میکنید لازم نیست به این موضوع اهمیت دهید.
33 |
34 | اگر یک قرارداد میخواهد قرارداد دیگری ایجاد کند، سورسکد (و باینری) قرارداد ایجاد شده باید برای کانستراکتور
35 | شناخته شود. این بدان معنی است که وابستگی ایجاد چرخهای غیرممکن است.
36 |
37 |
38 | .. code-block:: solidity
39 |
40 | // SPDX-License-Identifier: GPL-3.0
41 | pragma solidity >=0.4.22 <0.9.0;
42 |
43 |
44 | contract OwnedToken {
45 | // `TokenCreator` is a contract type that is defined below.
46 | // It is fine to reference it as long as it is not used
47 | // to create a new contract.
48 | TokenCreator creator;
49 | address owner;
50 | bytes32 name;
51 |
52 | // This is the constructor which registers the
53 | // creator and the assigned name.
54 | constructor(bytes32 _name) {
55 | // State variables are accessed via their name
56 | // and not via e.g. `this.owner`. Functions can
57 | // be accessed directly or through `this.f`,
58 | // but the latter provides an external view
59 | // to the function. Especially in the constructor,
60 | // you should not access functions externally,
61 | // because the function does not exist yet.
62 | // See the next section for details.
63 | owner = msg.sender;
64 |
65 | // We perform an explicit type conversion from `address`
66 | // to `TokenCreator` and assume that the type of
67 | // the calling contract is `TokenCreator`, there is
68 | // no real way to verify that.
69 | // This does not create a new contract.
70 | creator = TokenCreator(msg.sender);
71 | name = _name;
72 | }
73 |
74 | function changeName(bytes32 newName) public {
75 | // Only the creator can alter the name.
76 | // We compare the contract based on its
77 | // address which can be retrieved by
78 | // explicit conversion to address.
79 | if (msg.sender == address(creator))
80 | name = newName;
81 | }
82 |
83 | function transfer(address newOwner) public {
84 | // Only the current owner can transfer the token.
85 | if (msg.sender != owner) return;
86 |
87 | // We ask the creator contract if the transfer
88 | // should proceed by using a function of the
89 | // `TokenCreator` contract defined below. If
90 | // the call fails (e.g. due to out-of-gas),
91 | // the execution also fails here.
92 | if (creator.isTokenTransferOK(owner, newOwner))
93 | owner = newOwner;
94 | }
95 | }
96 |
97 |
98 | contract TokenCreator {
99 | function createToken(bytes32 name)
100 | public
101 | returns (OwnedToken tokenAddress)
102 | {
103 | // Create a new `Token` contract and return its address.
104 | // From the JavaScript side, the return type
105 | // of this function is `address`, as this is
106 | // the closest type available in the ABI.
107 | return new OwnedToken(name);
108 | }
109 |
110 | function changeName(OwnedToken tokenAddress, bytes32 name) public {
111 | // Again, the external type of `tokenAddress` is
112 | // simply `address`.
113 | tokenAddress.changeName(name);
114 | }
115 |
116 | // Perform checks to determine if transferring a token to the
117 | // `OwnedToken` contract should proceed
118 | function isTokenTransferOK(address currentOwner, address newOwner)
119 | public
120 | pure
121 | returns (bool ok)
122 | {
123 | // Check an arbitrary condition to see if transfer should proceed
124 | return keccak256(abi.encodePacked(currentOwner, newOwner))[0] == 0x7f;
125 | }
126 | }
127 |
--------------------------------------------------------------------------------
/docs/contracts/function-modifiers.rst:
--------------------------------------------------------------------------------
1 | .. index:: ! function;modifier
2 |
3 | .. _modifiers:
4 |
5 | ********************
6 | اصلاح کننده های تابع
7 | ********************
8 |
9 | اصلاح کننده ها جهت تغییر رفتار توابع به روش تعریف وار استفاده می شوند. برای مثال، شما
10 | می توانید از یک اصلاح کننده جهت اعمال پیش شرط به صورت اتوماتیک برای اجرای آن تابع
11 | استفاده کنید.
12 |
13 | اصلاح کننده ها ویژگی های وراثتی قرارداد ها هستند و ممکن است توسط قرارداد هایی که
14 | نشات گرفته شده اند باز نویسی شوند. اما فقط زمانی که بصورت ``virtual`` نشانه گذاری شده
15 | باشند. برای جزئیات، لطفا از بخش :ref:`Modifier Overriding ` دیدن کنید.
16 |
17 | .. code-block:: solidity
18 |
19 | // SPDX-License-Identifier: GPL-3.0
20 | pragma solidity >=0.7.1 <0.9.0;
21 |
22 | contract owned {
23 | constructor() { owner = payable(msg.sender); }
24 | address payable owner;
25 |
26 | // This contract only defines a modifier but does not use
27 | // it: it will be used in derived contracts.
28 | // The function body is inserted where the special symbol
29 | // `_;` in the definition of a modifier appears.
30 | // This means that if the owner calls this function, the
31 | // function is executed and otherwise, an exception is
32 | // thrown.
33 | modifier onlyOwner {
34 | require(
35 | msg.sender == owner,
36 | "Only owner can call this function."
37 | );
38 | _;
39 | }
40 | }
41 |
42 | contract destructible is owned {
43 | // This contract inherits the `onlyOwner` modifier from
44 | // `owned` and applies it to the `destroy` function, which
45 | // causes that calls to `destroy` only have an effect if
46 | // they are made by the stored owner.
47 | function destroy() public onlyOwner {
48 | selfdestruct(owner);
49 | }
50 | }
51 |
52 | contract priced {
53 | // Modifiers can receive arguments:
54 | modifier costs(uint price) {
55 | if (msg.value >= price) {
56 | _;
57 | }
58 | }
59 | }
60 |
61 | contract Register is priced, destructible {
62 | mapping (address => bool) registeredAddresses;
63 | uint price;
64 |
65 | constructor(uint initialPrice) { price = initialPrice; }
66 |
67 | // It is important to also provide the
68 | // `payable` keyword here, otherwise the function will
69 | // automatically reject all Ether sent to it.
70 | function register() public payable costs(price) {
71 | registeredAddresses[msg.sender] = true;
72 | }
73 |
74 | function changePrice(uint _price) public onlyOwner {
75 | price = _price;
76 | }
77 | }
78 |
79 | contract Mutex {
80 | bool locked;
81 | modifier noReentrancy() {
82 | require(
83 | !locked,
84 | "Reentrant call."
85 | );
86 | locked = true;
87 | _;
88 | locked = false;
89 | }
90 |
91 | /// This function is protected by a mutex, which means that
92 | /// reentrant calls from within `msg.sender.call` cannot call `f` again.
93 | /// The `return 7` statement assigns 7 to the return value but still
94 | /// executes the statement `locked = false` in the modifier.
95 | function f() public noReentrancy returns (uint) {
96 | (bool success,) = msg.sender.call("");
97 | require(success);
98 | return 7;
99 | }
100 | }
101 |
102 | اگر می خواهید به یک اصلاح کننده ی ``m`` تعریف شده در یک قرارداد ``C`` دسترسی پیدا کنید، می
103 | توانید از ``C.m`` برای ارجاع دادن آن بدون بازپرسی مجازی استفاده کنید. این فقط در اصلاح
104 | کننده های تعریف شده در قرارداد جاری یا قراردادهای اصلی(base) قابل استفاده است. اصلاح
105 | کننده ها را می توان در کتابخانه ها نیز تعریف کرد اما محدود به توابع داخل همان کتابخانه می
106 | ماند.
107 |
108 | اصلاح کننده های متعدد بر روی یک تابع با مشخص کردن آنها در یک فضای خالی-جدا شده
109 | اعمال می شوند و به ترتیب نماش داده شده ارزیابی می شوند.
110 |
111 | اصلاح کننده ها نمی توانند به طور ضمنی به ورودی های تابع دسترسی داشته یا آنها را تغییر
112 | داده و یا مقادیر بازگشتی را برگردانند. مقادیر آنها فقط به صراحت هنگام فراخوانی به آنها
113 | منتقل می شود.
114 |
115 | بازگشت واضح(Explicit) از یک اصلاح کننده یا بدنه تابع فقط از اصلاح کننده جاری و یا بنده تابع
116 | خارج می شود. متغیر های اختصاص داده شده باز می گردند و کنترل جریان ``_`` از اصلاح کننده
117 | قبلی ادامه می یابد.
118 |
119 | .. warning::
120 | در نسخه قدیمی سالیدیتی، دستورات ``return`` در توابع اصلاح کننده ها با رفتار متفاوت
121 | عمل می کنند.
122 |
123 | یک بازگشت واضح از یک اصلاح کننده با ``;return`` روی مقادیر بازگشتی توسط تابع تاثیر نمی
124 | گذارد. با این حال، اصلاح کننده می تواند بدنه تابع را به طور کلی اجرا نکند و در این صورت
125 | متغیر های باز گشتی بر روی :ref:`مقادیر پیش فرض` خود تنظیم می شوند درست مانند اینکه تابع
126 | دارای یک بدن خالی باشد.
127 |
128 | نماد ``_`` می تواند چندین بار در اصلاح کننده ظاهر شود. هر رخداد با بدنه تابع جایگزین می شود.
129 |
130 | عبارت های دلخواه برای ورودی (آرگومان) های اصلاح کننده مجاز هستند و در این مورد ، همه
131 | نماد های قابل مشاهده در تابع در اصلاح کننده نیز قابل مشاهده هستند.
132 | نماد های معرفی شده در اصلاح کننده در تابع قابل مشاهده نیستند(زیرا ممکن است توسط
133 | بازنویسی(overriding) در آن تغییر کنند)
134 |
--------------------------------------------------------------------------------
/docs/examples/safe-remote.rst:
--------------------------------------------------------------------------------
1 | .. index:: purchase, remote purchase, escrow
2 |
3 | ********************
4 | خرید امن از راه دور
5 | ********************
6 |
7 | خرید کالا از راه دور در حال حاضر نیاز به چندین طرف دارد که باید به یکدیگر اعتماد کنند. ساده ترین پیکربندی شامل یک فروشنده و یک خریدار است. خریدار مایل است کالایی را از فروشنده دریافت کند و فروشنده مایل است در ازای آن پول (یا معادل آن) دریافت کند. قسمت مشکل ساز محموله در اینجا است: هیچ راهی برای تعیین اطمینان از رسیدن کالا به خریدار وجود ندارد.
8 |
9 | روشهای مختلفی برای حل این مشکل وجود دارد، اما همه آنها در مقابل یک یا بقیه راهها کم میآورند. در مثال زیر، هر دو طرف باید مقدار دو برابر یک قلم کالا را به عنوان ضمانت در قرارداد قرار دهند. به محض اینکه این اتفاق افتاد، پول در قرارداد قفل شده خواهد ماند تا زمانی که خریدار تأیید کند که کالا را دریافت کردهاست. پس از آن، مقدار (نیمی از سپرده خود) به خریدار بازگردانده میشود و فروشنده سه برابر مقدار (سپرده خود به علاوه مقدار) دریافت میکند. ایده پشت این امر این است که هر دو طرف انگیزهای برای حل اوضاع دارند یا در غیر این صورت پول آنها برای همیشه قفل شده خواهد ماند.
10 |
11 | البته این قرارداد مشکلی را حل نمیکند، اما یک نمای کلی از چگونگی استفاده از ساختار ماشین حالت مانند در داخل قرارداد ارائه میدهد.
12 |
13 | .. code-block:: solidity
14 |
15 | // SPDX-License-Identifier: GPL-3.0
16 | pragma solidity ^0.8.4;
17 | contract Purchase {
18 | uint public value;
19 | address payable public seller;
20 | address payable public buyer;
21 |
22 | enum State { Created, Locked, Release, Inactive }
23 | // The state variable has a default value of the first member, `State.created`
24 | State public state;
25 |
26 | modifier condition(bool condition_) {
27 | require(condition_);
28 | _;
29 | }
30 |
31 | /// Only the buyer can call this function.
32 | error OnlyBuyer();
33 | /// Only the seller can call this function.
34 | error OnlySeller();
35 | /// The function cannot be called at the current state.
36 | error InvalidState();
37 | /// The provided value has to be even.
38 | error ValueNotEven();
39 |
40 | modifier onlyBuyer() {
41 | if (msg.sender != buyer)
42 | revert OnlyBuyer();
43 | _;
44 | }
45 |
46 | modifier onlySeller() {
47 | if (msg.sender != seller)
48 | revert OnlySeller();
49 | _;
50 | }
51 |
52 | modifier inState(State state_) {
53 | if (state != state_)
54 | revert InvalidState();
55 | _;
56 | }
57 |
58 | event Aborted();
59 | event PurchaseConfirmed();
60 | event ItemReceived();
61 | event SellerRefunded();
62 |
63 | // Ensure that `msg.value` is an even number.
64 | // Division will truncate if it is an odd number.
65 | // Check via multiplication that it wasn't an odd number.
66 | constructor() payable {
67 | seller = payable(msg.sender);
68 | value = msg.value / 2;
69 | if ((2 * value) != msg.value)
70 | revert ValueNotEven();
71 | }
72 |
73 | /// Abort the purchase and reclaim the ether.
74 | /// Can only be called by the seller before
75 | /// the contract is locked.
76 | function abort()
77 | external
78 | onlySeller
79 | inState(State.Created)
80 | {
81 | emit Aborted();
82 | state = State.Inactive;
83 | // We use transfer here directly. It is
84 | // reentrancy-safe, because it is the
85 | // last call in this function and we
86 | // already changed the state.
87 | seller.transfer(address(this).balance);
88 | }
89 |
90 | /// Confirm the purchase as buyer.
91 | /// Transaction has to include `2 * value` ether.
92 | /// The ether will be locked until confirmReceived
93 | /// is called.
94 | function confirmPurchase()
95 | external
96 | inState(State.Created)
97 | condition(msg.value == (2 * value))
98 | payable
99 | {
100 | emit PurchaseConfirmed();
101 | buyer = payable(msg.sender);
102 | state = State.Locked;
103 | }
104 |
105 | /// Confirm that you (the buyer) received the item.
106 | /// This will release the locked ether.
107 | function confirmReceived()
108 | external
109 | onlyBuyer
110 | inState(State.Locked)
111 | {
112 | emit ItemReceived();
113 | // It is important to change the state first because
114 | // otherwise, the contracts called using `send` below
115 | // can call in again here.
116 | state = State.Release;
117 |
118 | buyer.transfer(value);
119 | }
120 |
121 | /// This function refunds the seller, i.e.
122 | /// pays back the locked funds of the seller.
123 | function refundSeller()
124 | external
125 | onlySeller
126 | inState(State.Release)
127 | {
128 | emit SellerRefunded();
129 | // It is important to change the state first because
130 | // otherwise, the contracts called using `send` below
131 | // can call in again here.
132 | state = State.Inactive;
133 |
134 | seller.transfer(3 * value);
135 | }
136 | }
137 |
--------------------------------------------------------------------------------
/docs/contracts/events.rst:
--------------------------------------------------------------------------------
1 | .. index:: ! event
2 |
3 | .. _events:
4 |
5 | *********
6 | رویدادها
7 | *********
8 |
9 | رویداد های سالیدیتی یک خلاصه ای از عملکرد گزارش گیری EVM ارائه می دهند. برنامه ها می
10 | توانند ار طریق رابط RPC به این رویداد ها ثبت نام کنند و به رویداد ها گوش دهند.
11 |
12 | رویدادها اعضای وراثتی قرارداد ها هستند. وقتی آنها را فراخوانی می کنید، آنها باعث می شوند
13 | که ورودی هایی که در تراکنش ها ذخیره شده اند گزارش شوند – یک ساختار داده ویژه در
14 | بلاکچین. این گزارش ها با آدرس قرارد داد ها مرتبط هستند، تا زمانی که یک بلوک قابل
15 | دسترس است ، در بلاکچین گنجانده شده اند(از حالا تا بی نهایت، ممکن است با آرامش نیز
16 | تغییر کند)،. گزارش و رویدادهای آن از داخل قرارداد ها (حتی از قراردادهایی که آنها را ایجاد
17 | کرده اند) قابل دسترس نیست .
18 |
19 | یک در خواست Merkle proof برای گزارش ها امکانپذیر است انجام شود، بنابراین اگر یک
20 | موجودیت خارجی قراردادی به همراه چنین اثباتی ارائه دهد، می تواند بررسی کند که گزارش
21 | واقعا در داخل بلاکچین وجود دارد یا نه. شما باید هدر های بلاک را تهیه کنید زیرا فقط آخرین
22 | 256 بلوک هش قابل مشاهده است.
23 |
24 | شما می توانید خصیصه ``indexed`` تا حداکثر 3 ورودی اضافه کنید که آن را در یک سختار داده
25 | خاصی بنام "عناوین" :ref:`"topics" ` بجای بخش داده ای گزارش قرار می دهد. اگر شما از آرایه های :ref:`reference type
26 | `
27 | استفاده کنید(شامل رشته ای و بایتی) بعنوان ورودی شاخص دار شده، از هش Keccak-256
28 | به عنوان "عناوین" استفاده و ذخیره می شود، زیرا بخش عناوین تنها می تواند یک کلمه در خود
29 | جای دهد(32 بایت).
30 |
31 | تمامی پارامترها/ورودی ها بدون خصیصه ``indexed`` در بخش داده گزارش به روش
32 | :ref:`ABI-encoded ` کد گذاری می شوند.
33 |
34 | عناوین شما را قادر می شازند تا بین رویداد ها جستجو کنید، برای مثال زمانی که می خواهید
35 | یک ترتیب بلوک از رویدادهای خاص را فیلتر کنید. شما همچنین می توانید رویدادها را بر اساس
36 | آدرس قراردادی که رویداد را منتشر کرده است ، فیلتر کنید.
37 |
38 | برای مثال ، کد زیر در web3.js از `method `_ ``subscribe("logs")`` جهت فیلتر گزارش هایی که
39 | با عنوانی با مقدار آدرس مشخص دارند، استفاده می کند:
40 |
41 | .. code-block:: javascript
42 |
43 | var options = {
44 | fromBlock: 0,
45 | address: web3.eth.defaultAccount,
46 | topics: ["0x0000000000000000000000000000000000000000000000000000000000000000", null, null]
47 | };
48 | web3.eth.subscribe('logs', options, function (error, result) {
49 | if (!error)
50 | console.log(result);
51 | })
52 | .on("data", function (log) {
53 | console.log(log);
54 | })
55 | .on("changed", function (log) {
56 | });
57 |
58 |
59 | یکی از عناوین امضای هش رویداد است، مگر شما رویداد را به صورت ``ناشناس`` تعریف کرده
60 | باشید. این بدان معناست که امکان فیلتر رویدادهایی با نام ناشناس وجود ندارد، شما تنها می
61 | توانید رویداد ها را توسط آدرس قرارداد فیلتر کنید. مزیت رویداد های نا شناس این است که
62 | استقرار و فراخوانی آنها ارزان است.
63 |
64 | .. note::
65 | Since the transaction log only stores the event data and not the type,
66 | you have to know the type of the event, including which parameter is
67 | indexed and if the event is anonymous in order to correctly interpret
68 | the data.
69 | In particular, it is possible to "fake" the signature of another event
70 | using an anonymous event.
71 |
72 | .. code-block:: solidity
73 |
74 | // SPDX-License-Identifier: GPL-3.0
75 | pragma solidity >=0.4.21 <0.9.0;
76 |
77 | contract ClientReceipt {
78 | event Deposit(
79 | address indexed _from,
80 | bytes32 indexed _id,
81 | uint _value
82 | );
83 |
84 | function deposit(bytes32 _id) public payable {
85 | // Events are emitted using `emit`, followed by
86 | // the name of the event and the arguments
87 | // (if any) in parentheses. Any such invocation
88 | // (even deeply nested) can be detected from
89 | // the JavaScript API by filtering for `Deposit`.
90 | emit Deposit(msg.sender, _id, msg.value);
91 | }
92 | }
93 |
94 | استفاده در جاوا اسکریپ API به شکل زیر است:
95 |
96 | .. code-block:: javascript
97 |
98 | var abi = /* abi as generated by the compiler */;
99 | var ClientReceipt = web3.eth.contract(abi);
100 | var clientReceipt = ClientReceipt.at("0x1234...ab67" /* address */);
101 |
102 | var depositEvent = clientReceipt.Deposit();
103 |
104 | // watch for changes
105 | depositEvent.watch(function(error, result){
106 | // result contains non-indexed arguments and topics
107 | // given to the `Deposit` call.
108 | if (!error)
109 | console.log(result);
110 | });
111 |
112 |
113 | // Or pass a callback to start watching immediately
114 | var depositEvent = clientReceipt.Deposit(function(error, result) {
115 | if (!error)
116 | console.log(result);
117 | });
118 |
119 | خروجی بالا شبیه زیر است (کوتاه شده است):
120 |
121 | .. code-block:: json
122 |
123 | {
124 | "returnValues": {
125 | "_from": "0x1111…FFFFCCCC",
126 | "_id": "0x50…sd5adb20",
127 | "_value": "0x420042"
128 | },
129 | "raw": {
130 | "data": "0x7f…91385",
131 | "topics": ["0xfd4…b4ead7", "0x7f…1a91385"]
132 | }
133 | }
134 |
135 | منابع اضافی برای درک رویداد ها
136 | ==============================================
137 |
138 | - `اسناد جاوا اسکریپت `_
139 | - `نمونه های استفاده از رویدادها `_
140 | - `چگونگی دسترسی به آنها در جاوا اسکریپت `_
141 |
--------------------------------------------------------------------------------
/docs/070-breaking-changes.rst:
--------------------------------------------------------------------------------
1 | ********************************
2 | Solidity v0.7.0 Breaking Changes
3 | ********************************
4 |
5 | This section highlights the main breaking changes introduced in Solidity
6 | version 0.7.0, along with the reasoning behind the changes and how to update
7 | affected code.
8 | For the full list check
9 | `the release changelog `_.
10 |
11 |
12 | Silent Changes of the Semantics
13 | ===============================
14 |
15 | * Exponentiation and shifts of literals by non-literals (e.g. ``1 << x`` or ``2 ** x``)
16 | will always use either the type ``uint256`` (for non-negative literals) or
17 | ``int256`` (for negative literals) to perform the operation.
18 | Previously, the operation was performed in the type of the shift amount / the
19 | exponent which can be misleading.
20 |
21 |
22 | Changes to the Syntax
23 | =====================
24 |
25 | * In external function and contract creation calls, Ether and gas is now specified using a new syntax:
26 | ``x.f{gas: 10000, value: 2 ether}(arg1, arg2)``.
27 | The old syntax -- ``x.f.gas(10000).value(2 ether)(arg1, arg2)`` -- will cause an error.
28 |
29 | * The global variable ``now`` is deprecated, ``block.timestamp`` should be used instead.
30 | The single identifier ``now`` is too generic for a global variable and could give the impression
31 | that it changes during transaction processing, whereas ``block.timestamp`` correctly
32 | reflects the fact that it is just a property of the block.
33 |
34 | * NatSpec comments on variables are only allowed for public state variables and not
35 | for local or internal variables.
36 |
37 | * The token ``gwei`` is a keyword now (used to specify, e.g. ``2 gwei`` as a number)
38 | and cannot be used as an identifier.
39 |
40 | * String literals now can only contain printable ASCII characters and this also includes a variety of
41 | escape sequences, such as hexadecimal (``\xff``) and unicode escapes (``\u20ac``).
42 |
43 | * Unicode string literals are supported now to accommodate valid UTF-8 sequences. They are identified
44 | with the ``unicode`` prefix: ``unicode"Hello 😃"``.
45 |
46 | * State Mutability: The state mutability of functions can now be restricted during inheritance:
47 | Functions with default state mutability can be overridden by ``pure`` and ``view`` functions
48 | while ``view`` functions can be overridden by ``pure`` functions.
49 | At the same time, public state variables are considered ``view`` and even ``pure``
50 | if they are constants.
51 |
52 |
53 |
54 | Inline Assembly
55 | ---------------
56 |
57 | * Disallow ``.`` in user-defined function and variable names in inline assembly.
58 | It is still valid if you use Solidity in Yul-only mode.
59 |
60 | * Slot and offset of storage pointer variable ``x`` are accessed via ``x.slot``
61 | and ``x.offset`` instead of ``x_slot`` and ``x_offset``.
62 |
63 | Removal of Unused or Unsafe Features
64 | ====================================
65 |
66 | Mappings outside Storage
67 | ------------------------
68 |
69 | * If a struct or array contains a mapping, it can only be used in storage.
70 | Previously, mapping members were silently skipped in memory, which
71 | is confusing and error-prone.
72 |
73 | * Assignments to structs or arrays in storage does not work if they contain
74 | mappings.
75 | Previously, mappings were silently skipped during the copy operation, which
76 | is misleading and error-prone.
77 |
78 | Functions and Events
79 | --------------------
80 |
81 | * Visibility (``public`` / ``internal``) is not needed for constructors anymore:
82 | To prevent a contract from being created, it can be marked ``abstract``.
83 | This makes the visibility concept for constructors obsolete.
84 |
85 | * Type Checker: Disallow ``virtual`` for library functions:
86 | Since libraries cannot be inherited from, library functions should not be virtual.
87 |
88 | * Multiple events with the same name and parameter types in the same
89 | inheritance hierarchy are disallowed.
90 |
91 | * ``using A for B`` only affects the contract it is mentioned in.
92 | Previously, the effect was inherited. Now, you have to repeat the ``using``
93 | statement in all derived contracts that make use of the feature.
94 |
95 | Expressions
96 | -----------
97 |
98 | * Shifts by signed types are disallowed.
99 | Previously, shifts by negative amounts were allowed, but reverted at runtime.
100 |
101 | * The ``finney`` and ``szabo`` denominations are removed.
102 | They are rarely used and do not make the actual amount readily visible. Instead, explicit
103 | values like ``1e20`` or the very common ``gwei`` can be used.
104 |
105 | Declarations
106 | ------------
107 |
108 | * The keyword ``var`` cannot be used anymore.
109 | Previously, this keyword would parse but result in a type error and
110 | a suggestion about which type to use. Now, it results in a parser error.
111 |
112 | Interface Changes
113 | =================
114 |
115 | * JSON AST: Mark hex string literals with ``kind: "hexString"``.
116 | * JSON AST: Members with value ``null`` are removed from JSON output.
117 | * NatSpec: Constructors and functions have consistent userdoc output.
118 |
119 |
120 | How to update your code
121 | =======================
122 |
123 | This section gives detailed instructions on how to update prior code for every breaking change.
124 |
125 | * Change ``x.f.value(...)()`` to ``x.f{value: ...}()``. Similarly ``(new C).value(...)()`` to
126 | ``new C{value: ...}()`` and ``x.f.gas(...).value(...)()`` to ``x.f{gas: ..., value: ...}()``.
127 | * Change ``now`` to ``block.timestamp``.
128 | * Change types of right operand in shift operators to unsigned types. For example change ``x >> (256 - y)`` to
129 | ``x >> uint(256 - y)``.
130 | * Repeat the ``using A for B`` statements in all derived contracts if needed.
131 | * Remove the ``public`` keyword from every constructor.
132 | * Remove the ``internal`` keyword from every constructor and add ``abstract`` to the contract (if not already present).
133 | * Change ``_slot`` and ``_offset`` suffixes in inline assembly to ``.slot`` and ``.offset``, respectively.
134 |
--------------------------------------------------------------------------------
/docs/index.rst:
--------------------------------------------------------------------------------
1 | سالیدیتی
2 | ========
3 | سالیدیتی یک زبان شیء گرا و سطح بالا برای پیاده سازی قراردادهای هوشمند میباشد. قراردادهای هوشمند، برنامههایی هستند که رفتار حسابها در داخل حالت اتریوم را کنترل میکنند.
4 |
5 |
6 | سالیدیتی یک `زبان آکلادی `_ میباشد که از زبانهایی مانند سی پلاس پلاس ، پایتون و جاوا اسکریپت تأثیر گرفته و برای هدف قراردادن EVM یا ماشینِ مجازیِ اتریوم طراحی شدهاست.
7 |
8 |
9 | سالیدیتی از نوع استاتیک میباشد. از ویژگیهای ارث بری ، کتابخانهها و انواع نوعهای پیچیده تعریف شده توسط کاربر پشتیبانی میکند.
10 |
11 | با سالیدیتی میتوانید قراردادهایی را برای کاربردهایی از قبیل رأیگیری ، سرمایه گذاری جمعی ، مزایده کور و کیف پول با امضای چندگانه استفاده کنید.
12 |
13 | هنگام استقرار قراردادها، باید از آخرین نسخه سالیدیتی منتشر شده استفاده کنید. به این دلیل که تغییرات جدید ، ویژگیهای جدید و رفع باگها به طور منظم معرفی میشوند. ما در حال حاضر از نسخه 0.X برای `نشان دادن این تغییرات سریع `_ استفاده میکنیم.
14 |
15 |
16 | .. warning::
17 |
18 | سالیدیتی به تازگی نسخه 0.8.X را منتشر کرده که تغییرات جدید را معرفی میکند. حتماً :doc:`لیست کامل <080-breaking-changes>` را مطالعه کنید.
19 |
20 | ایدههای بهبود سالیدیتی یا این مستند همیشه مورد استقبال قرار میگیرد، برای جزئیات بیشتر :doc:`راهنمای همکاری ` را مطالعه کنید.
21 |
22 |
23 | شروع
24 | ---------------
25 |
26 | **1. درک مبانی قراردادهای هوشمند**
27 |
28 | اگر با مفهوم قراردادهای هوشمند آشنا هستید، به شما توصیه میکنیم که با جستجوی بخش "معرفی قراردادهای هوشمند" شروع به کار کنید، که شامل موارد زیر است:
29 |
30 | * :ref:`یک مثال ساده از قرارداد هوشمند ` که با سالیدیتی نوشته شدهاست.
31 | * :ref:`مبانی بلاکچین `.
32 | * :ref:`ماشین مجازی اتریوم `.
33 |
34 | **2. آشنایی با سالیدیتی**
35 |
36 | هنگامی که با مبانی اولیه آشنا شدید، توصیه میکنیم برای درک مفاهیم اصلی زبان، بخشهای :doc:`"سالیدیتی با مثال" `
37 | و "شرح زبان" را بخوانید.
38 |
39 | **3. نصب کامپایلر سالیدیتی**
40 |
41 | روش های مختلفی برای نصب کامپایلر سالیدیتی وجود دارد، به سادگی گزینه مورد نظر خود را انتخاب کنید و مراحل ذکر شده در :ref:`صفحه نصب ` را دنبال کنید.
42 |
43 |
44 |
45 | .. hint::
46 |
47 | میتوانید نمونههای کد را مستقیماً در مرورگر خود با `ویرایشگر متن ریمیکس `_ امتحان کنید. ریمیکس یک ویرایشگر متن مبتنی بر مرورگر وب است که به شما امکان میدهد، بدون نیاز به نصب سالیدیتی به صورت محلی، قراردادهای هوشمند سالیدیتی را بنویسید، دیپلوی و مدیریت کنید.
48 |
49 | .. warning::
50 |
51 | نرم افزار به عنوان نوشتهی انسان، میتواند باگ داشته باشد. هنگام نوشتن قراردادهای هوشمند خود، باید بهترین شیوههای توسعه نرم افزار را دنبال کنید. شیوههای توسعه نرم افزار شامل بازبینی ، آزمایش ، حسابرسی و اثبات صحتِ کد میباشد. کاربران قرارداد هوشمند گاهی اوقات به خودِ کد نسبت به نویسندگان آنها اطمینان بیشتری دارند. بلاکچینها و قراردادهای هوشمند مسائل منحصر به فرد خود را دارند، که باید مراقب آنها باشید. بنابراین قبل از کار بر روی تولید کد، حتماً قسمت :ref:`ملاحظات امنیتی ` را مطالعه کنید.
52 |
53 |
54 | **4. یادگیری بیشتر**
55 |
56 | اگر میخواهید در مورد ساخت برنامههای غیرمتمرکز در اتریوم اطلاعات بیشتری کسب کنید، `منابع توسعه دهنده اتریوم `_ میتوانند به شما در تهیه مستندِ عمومیِ بیشتر در مورد اتریوم و انتخاب گستردهای از آموزشها، ابزارها و چارچوبهای توسعه کمک کنند.
57 |
58 | اگر سؤالی دارید، میتوانید جوابها را جستجو کنید یا از طریق `Ethereum StackExchange `_, یا `کانال Gitter `_ ما بپرسید.
59 |
60 | .. _translations:
61 |
62 | ترجمهها
63 | ------------
64 |
65 | داوطلبان جامعه سالیدیتی به ترجمه این مستندات به چندین زبان کمک میکنند. این مستندات سطوح مختلفی از کامل و بروز بودن را دارند. نسخه انگلیسی به عنوان مرجع میباشد.
66 |
67 | .. note::
68 |
69 |
70 | We recently set up a new GitHub organization and translation workflow to help streamline the
71 | community efforts. Please refer to the `translation guide `_
72 | for information on how to contribute to the community translations moving forward.
73 |
74 | * `فرانسوی `_ (در حال انجام)
75 | * `ایتالیایی `_ (در حال انجام)
76 | * `ژاپنی `_
77 | * `کرهای `_ (در حال انجام)
78 | * `روسی `_ (نسبتاً قدیمی)
79 | * `چینی `_ (در حال انجام)
80 | * `اسپانیایی `_
81 | * `ترکی `_ (جزئی)
82 |
83 | فهرست
84 | ========
85 |
86 | :ref:`فهرست کلمات `, :ref:`صفحه جستجو `
87 |
88 | .. toctree::
89 | :maxdepth: 2
90 | :caption: مبانی
91 |
92 | introduction-to-smart-contracts.rst
93 | installing-solidity.rst
94 | solidity-by-example.rst
95 |
96 | .. toctree::
97 | :maxdepth: 2
98 | :caption: توضیحات زبان
99 |
100 | layout-of-source-files.rst
101 | structure-of-a-contract.rst
102 | types.rst
103 | units-and-global-variables.rst
104 | control-structures.rst
105 | contracts.rst
106 | assembly.rst
107 | cheatsheet.rst
108 | grammar.rst
109 |
110 | .. toctree::
111 | :maxdepth: 2
112 | :caption: کامپایلر
113 |
114 | using-the-compiler.rst
115 | analysing-compilation-output.rst
116 |
117 | .. toctree::
118 | :maxdepth: 2
119 | :caption: Internals
120 |
121 | internals/layout_in_storage.rst
122 | internals/layout_in_memory.rst
123 | internals/layout_in_calldata.rst
124 | internals/variable_cleanup.rst
125 | internals/source_mappings.rst
126 | internals/optimizer.rst
127 | metadata.rst
128 | abi-spec.rst
129 |
130 | .. toctree::
131 | :maxdepth: 2
132 | :caption: Additional Material
133 |
134 | 050-breaking-changes.rst
135 | 060-breaking-changes.rst
136 | 070-breaking-changes.rst
137 | 080-breaking-changes.rst
138 | natspec-format.rst
139 | security-considerations.rst
140 | smtchecker.rst
141 | resources.rst
142 | path-resolution.rst
143 | yul.rst
144 | style-guide.rst
145 | common-patterns.rst
146 | bugs.rst
147 | contributing.rst
148 | brand-guide.rst
149 | language-influences.rst
150 |
--------------------------------------------------------------------------------
/docs/analysing-compilation-output.rst:
--------------------------------------------------------------------------------
1 | .. index:: analyse, asm
2 |
3 | #############################
4 | Analysing the Compiler Output
5 | #############################
6 |
7 | It is often useful to look at the assembly code generated by the compiler. The generated binary,
8 | i.e., the output of ``solc --bin contract.sol``, is generally difficult to read. It is recommended
9 | to use the flag ``--asm`` to analyse the assembly output. Even for large contracts, looking at a
10 | visual diff of the assembly before and after a change is often very enlightening.
11 |
12 | Consider the following contract (named, say ``contract.sol``):
13 |
14 | .. code-block:: Solidity
15 |
16 | // SPDX-License-Identifier: GPL-3.0
17 | pragma solidity >=0.5.0 <0.9.0;
18 | contract C {
19 | function one() public pure returns (uint) {
20 | return 1;
21 | }
22 | }
23 |
24 | The following would be the output of ``solc --asm contract.sol``
25 |
26 | .. code-block:: none
27 |
28 | ======= contract.sol:C =======
29 | EVM assembly:
30 | /* "contract.sol":0:86 contract C {... */
31 | mstore(0x40, 0x80)
32 | callvalue
33 | dup1
34 | iszero
35 | tag_1
36 | jumpi
37 | 0x00
38 | dup1
39 | revert
40 | tag_1:
41 | pop
42 | dataSize(sub_0)
43 | dup1
44 | dataOffset(sub_0)
45 | 0x00
46 | codecopy
47 | 0x00
48 | return
49 | stop
50 |
51 | sub_0: assembly {
52 | /* "contract.sol":0:86 contract C {... */
53 | mstore(0x40, 0x80)
54 | callvalue
55 | dup1
56 | iszero
57 | tag_1
58 | jumpi
59 | 0x00
60 | dup1
61 | revert
62 | tag_1:
63 | pop
64 | jumpi(tag_2, lt(calldatasize, 0x04))
65 | shr(0xe0, calldataload(0x00))
66 | dup1
67 | 0x901717d1
68 | eq
69 | tag_3
70 | jumpi
71 | tag_2:
72 | 0x00
73 | dup1
74 | revert
75 | /* "contract.sol":17:84 function one() public pure returns (uint) {... */
76 | tag_3:
77 | tag_4
78 | tag_5
79 | jump // in
80 | tag_4:
81 | mload(0x40)
82 | tag_6
83 | swap2
84 | swap1
85 | tag_7
86 | jump // in
87 | tag_6:
88 | mload(0x40)
89 | dup1
90 | swap2
91 | sub
92 | swap1
93 | return
94 | tag_5:
95 | /* "contract.sol":53:57 uint */
96 | 0x00
97 | /* "contract.sol":76:77 1 */
98 | 0x01
99 | /* "contract.sol":69:77 return 1 */
100 | swap1
101 | pop
102 | /* "contract.sol":17:84 function one() public pure returns (uint) {... */
103 | swap1
104 | jump // out
105 | /* "#utility.yul":7:125 */
106 | tag_10:
107 | /* "#utility.yul":94:118 */
108 | tag_12
109 | /* "#utility.yul":112:117 */
110 | dup2
111 | /* "#utility.yul":94:118 */
112 | tag_13
113 | jump // in
114 | tag_12:
115 | /* "#utility.yul":89:92 */
116 | dup3
117 | /* "#utility.yul":82:119 */
118 | mstore
119 | /* "#utility.yul":72:125 */
120 | pop
121 | pop
122 | jump // out
123 | /* "#utility.yul":131:353 */
124 | tag_7:
125 | 0x00
126 | /* "#utility.yul":262:264 */
127 | 0x20
128 | /* "#utility.yul":251:260 */
129 | dup3
130 | /* "#utility.yul":247:265 */
131 | add
132 | /* "#utility.yul":239:265 */
133 | swap1
134 | pop
135 | /* "#utility.yul":275:346 */
136 | tag_15
137 | /* "#utility.yul":343:344 */
138 | 0x00
139 | /* "#utility.yul":332:341 */
140 | dup4
141 | /* "#utility.yul":328:345 */
142 | add
143 | /* "#utility.yul":319:325 */
144 | dup5
145 | /* "#utility.yul":275:346 */
146 | tag_10
147 | jump // in
148 | tag_15:
149 | /* "#utility.yul":229:353 */
150 | swap3
151 | swap2
152 | pop
153 | pop
154 | jump // out
155 | /* "#utility.yul":359:436 */
156 | tag_13:
157 | 0x00
158 | /* "#utility.yul":425:430 */
159 | dup2
160 | /* "#utility.yul":414:430 */
161 | swap1
162 | pop
163 | /* "#utility.yul":404:436 */
164 | swap2
165 | swap1
166 | pop
167 | jump // out
168 |
169 | auxdata: 0xa2646970667358221220a5874f19737ddd4c5d77ace1619e5160c67b3d4bedac75fce908fed32d98899864736f6c637827302e382e342d646576656c6f702e323032312e332e33302b636f6d6d69742e65613065363933380058
170 | }
171 |
172 | Alternatively, the above output can also be obtained from `Remix `_,
173 | under the option "Compilation Details" after compiling a contract.
174 |
175 | Notice that the ``asm`` output starts with the creation / constructor code. The deploy code is
176 | provided as part of the sub object (in the above example, it is part of the sub-object ``sub_0``).
177 | The ``auxdata`` field corresponds to the contract :ref:`metadata
178 | `. The comments in the assembly output point to the
179 | source location. Note that ``#utility.yul`` is an internally generated file of utility functions
180 | that can be obtained using the flags ``--combined-json
181 | generated-sources,generated-sources-runtime``.
182 |
183 | Similarly, the optimized assembly can be obtained with the command: ``solc --optimize --asm
184 | contract.sol``. Often times, it is interesting to see if two different sources in Solidity result in
185 | the same optimized code. For example, to see if the expressions ``(a * b) / c``, ``a * b / c``
186 | generates the same bytecode. This can be easily done by taking a ``diff`` of the corresponding
187 | assembly output, after potentially stripping comments that reference the source locations.
188 |
189 | .. note::
190 |
191 | The ``--asm`` output is not designed to be machine readable. Therefore, there may be breaking
192 | changes on the output between minor versions of solc.
193 |
--------------------------------------------------------------------------------
/docs/structure-of-a-contract.rst:
--------------------------------------------------------------------------------
1 | .. index:: contract, state variable, function, event, struct, enum, function;modifier
2 |
3 | .. _contract_structure:
4 |
5 | ***********************
6 | ساختار قرارداد
7 | ***********************
8 |
9 | قراردادهای سالیدیتی مانند کلاسهای زبانهای شیگرا هستند. هر قرارداد میتواند شامل دستورات :ref:`structure-state-variables` ، :ref:`structure-functions` ، :ref:`structure-function-modifiers` ، :ref:`structure-events` ، :ref:`structure-errors` ، :ref:`structure-struct-types` و :ref:`structure-enum-types` باشد. علاوه بر این، قراردادها میتوانند از سایر قراردادها ارث ببرند.
10 |
11 |
12 | قراردادهای دیگری نیز وجود دارد که :ref:`کتابخانهها` و :ref:`رابطها` نامیده میشوند.
13 |
14 |
15 |
16 | بخش مربوط به :ref:`قراردادها` شامل جزئیات بیشتری نسبت به این بخش است که یک مرور سریع رو ارائه میدهد.
17 |
18 | .. _structure-state-variables:
19 |
20 | متغیرهای حالت
21 | ===============
22 |
23 | متغیرهای حالت متغیرهایی هستند که مقادیر آنها به طور دائمی در storage قرارداد ذخیره میشود.
24 |
25 |
26 | .. code-block:: solidity
27 |
28 | // SPDX-License-Identifier: GPL-3.0
29 | pragma solidity >=0.4.0 <0.9.0;
30 |
31 | contract SimpleStorage {
32 | uint storedData; // State variable
33 | // ...
34 | }
35 |
36 |
37 | برای دیدن انواع متغیرهای حالت معتبر و :ref:`قابلیت مشاهده آنها و گیرندهها` برای انتخابهای احتمالی برای مشاهده انواع متغیرها، به بخش :ref:`types` مراجعه کنید.
38 |
39 |
40 | .. _structure-functions:
41 |
42 | توابع
43 | =========
44 |
45 | توابع، واحد اجرایی کد هستند. توابع معمولاً در داخل قرارداد تعریف میشوند، اما در خارج از قراردادها نیز میتوانند تعریف شوند.
46 |
47 | .. code-block:: solidity
48 |
49 | // SPDX-License-Identifier: GPL-3.0
50 | pragma solidity >=0.7.1 <0.9.0;
51 |
52 | contract SimpleAuction {
53 | function bid() public payable { // Function
54 | // ...
55 | }
56 | }
57 |
58 | // Helper function defined outside of a contract
59 | function helper(uint x) pure returns (uint) {
60 | return x * 2;
61 | }
62 |
63 |
64 | :ref:`فراخوانی توابع` میتوانند به صورت داخلی یا خارجی اتفاق بیفتند و دارای :ref:`قابلیت مشاهده` مختلفی نسبت به سایر قراردادها هستند. :ref:`توابع` پارامترها را میپذیرند و :ref:`متغیرها را برمیگردانند` تا پارامترها و مقادیر بین آنها منتقل شود.
65 |
66 | .. _structure-function-modifiers:
67 |
68 | توابع اصلاح کننده
69 | ==================
70 |
71 |
72 | از تابع اصلاح کنندهها میتوان برای اصلاح سمنتیک توابع به روشی اعلانی استفاده کرد (به :ref:`توابع اصلاح کننده ` در بخش قراردادها مراجعه کنید).
73 |
74 |
75 | اضافه بار ، به این معنا که داشتن نام اصلاح کننده یکسان با پارامترهای مختلف، امکان پذیر نیست. مانند توابع، اصلاح کنندهها را میتوان لغو کرد.
76 |
77 | مانند توابع، اصلاح کنندهها نیز میتوانند :ref:`نادیده` گرفته شوند.
78 |
79 | .. code-block:: solidity
80 |
81 | // SPDX-License-Identifier: GPL-3.0
82 | pragma solidity >=0.4.22 <0.9.0;
83 |
84 | contract Purchase {
85 | address public seller;
86 |
87 | modifier onlySeller() { // Modifier
88 | require(
89 | msg.sender == seller,
90 | "Only seller can call this."
91 | );
92 | _;
93 | }
94 |
95 | function abort() public view onlySeller { // Modifier usage
96 | // ...
97 | }
98 | }
99 |
100 | .. _structure-events:
101 |
102 | رویدادها
103 | ======
104 |
105 |
106 | رویدادها رابطهای راحتی برای ورود به امکانات EVM هستند.
107 |
108 |
109 | .. code-block:: solidity
110 |
111 | // SPDX-License-Identifier: GPL-3.0
112 | pragma solidity >=0.4.21 <0.9.0;
113 |
114 | contract SimpleAuction {
115 | event HighestBidIncreased(address bidder, uint amount); // Event
116 |
117 | function bid() public payable {
118 | // ...
119 | emit HighestBidIncreased(msg.sender, msg.value); // Triggering event
120 | }
121 | }
122 |
123 | برای اطلاع از چگونگی اعلام رویدادها و استفاده از آنها از طریق dapp، به بخش :ref:`رویدادها` در بخش قراردادها مراجعه کنید.
124 |
125 |
126 | .. _structure-errors:
127 |
128 | خطاها
129 | ======
130 |
131 | خطاها به شما امکان میدهند نامها و دادههای توصیفی را برای شرایط شکست تعریف کنید. از خطاها میتوان در :ref:`دستورات revert ` استفاده کرد. در مقایسه با توضیحات رشته ، خطاها بسیار ارزانتر هستند و به شما امکان میدهند دادههای اضافی را رمزگذاری کنید. برای توصیف خطا برای کاربر میتوانید از NatSpec استفاده کنید.
132 |
133 |
134 | .. code-block:: solidity
135 |
136 | // SPDX-License-Identifier: GPL-3.0
137 | pragma solidity ^0.8.4;
138 |
139 | /// Not enough funds for transfer. Requested `requested`,
140 | /// but only `available` available.
141 | error NotEnoughFunds(uint requested, uint available);
142 |
143 | contract Token {
144 | mapping(address => uint) balances;
145 | function transfer(address to, uint amount) public {
146 | uint balance = balances[msg.sender];
147 | if (balance < amount)
148 | revert NotEnoughFunds(amount, balance);
149 | balances[msg.sender] -= amount;
150 | balances[to] += amount;
151 | // ...
152 | }
153 | }
154 |
155 |
156 | برای اطلاعات بیشتر به :ref:`خطاها` و دستورات Revert در قسمت قراردادها مراجعه کنید.
157 |
158 | .. _structure-struct-types:
159 |
160 | انواع Struct
161 | =============
162 |
163 | :ref:`structs` انواع تعریف شده سفارشی هستند که میتوانند متغیرهای مختلفی را گروه بندی کنند (به بخش Structها در بخش انواع مراجعه کنید).
164 |
165 |
166 |
167 | .. code-block:: solidity
168 |
169 | // SPDX-License-Identifier: GPL-3.0
170 | pragma solidity >=0.4.0 <0.9.0;
171 |
172 | contract Ballot {
173 | struct Voter { // Struct
174 | uint weight;
175 | bool voted;
176 | address delegate;
177 | uint vote;
178 | }
179 | }
180 |
181 | .. _structure-enum-types:
182 |
183 | انواع Enum
184 | ==========
185 |
186 | از Enums میتوان برای ایجاد انواع سفارشی با مجموعه محدودی از "مقادیر ثابت " استفاده کرد (به قسمت :ref:`enums` در بخش انواع مراجعه کنید).
187 |
188 |
189 | .. code-block:: solidity
190 |
191 | // SPDX-License-Identifier: GPL-3.0
192 | pragma solidity >=0.4.0 <0.9.0;
193 |
194 | contract Purchase {
195 | enum State { Created, Locked, Inactive } // Enum
196 | }
197 |
--------------------------------------------------------------------------------
/docs/resources.rst:
--------------------------------------------------------------------------------
1 | #########
2 | Resources
3 | #########
4 |
5 | General Resources
6 | =================
7 |
8 | * `Ethereum.org Developer Portal `_
9 | * `Ethereum StackExchange `_
10 | * `Solidity Portal `_
11 | * `Solidity Changelog `_
12 | * `Solidity Source Code on GitHub `_
13 | * `Solidity Language Users Chat `_
14 | * `Solidity Compiler Developers Chat `_
15 | * `Awesome Solidity `_
16 | * `Solidity by Example `_
17 |
18 |
19 | Integrated (Ethereum) Development Environments
20 | ==============================================
21 |
22 | * `Brownie `_
23 | Python-based development and testing framework for smart contracts targeting the Ethereum Virtual Machine.
24 |
25 | * `Dapp `_
26 | Tool for building, testing and deploying smart contracts from the command line.
27 |
28 | * `Embark `_
29 | Developer platform for building and deploying decentralized applications.
30 |
31 | * `Hardhat `_
32 | Ethereum development environment with local Ethereum network, debugging features and plugin ecosystem.
33 |
34 | * `Remix `_
35 | Browser-based IDE with integrated compiler and Solidity runtime environment without server-side components.
36 |
37 | * `Scaffold-ETH `_
38 | Ethereum development stack focused on fast product iterations.
39 |
40 | * `Truffle `_
41 | Ethereum development framework.
42 |
43 | Editor Integrations
44 | ===================
45 |
46 | * Atom
47 |
48 | * `Etheratom `_
49 | Plugin for the Atom editor that features syntax highlighting, compilation and a runtime environment (Backend node & VM compatible).
50 |
51 | * `Atom Solidity Linter `_
52 | Plugin for the Atom editor that provides Solidity linting.
53 |
54 | * `Atom Solium Linter `_
55 | Configurable Solidity linter for Atom using Solium (now Ethlint) as a base.
56 |
57 | * Emacs
58 |
59 | * `Emacs Solidity `_
60 | Plugin for the Emacs editor providing syntax highlighting and compilation error reporting.
61 |
62 | * IntelliJ
63 |
64 | * `IntelliJ IDEA plugin `_
65 | Solidity plugin for IntelliJ IDEA (and all other JetBrains IDEs)
66 |
67 | * Sublime
68 |
69 | * `Package for SublimeText - Solidity language syntax `_
70 | Solidity syntax highlighting for SublimeText editor.
71 |
72 | * Vim
73 |
74 | * `Vim Solidity `_
75 | Plugin for the Vim editor providing syntax highlighting.
76 |
77 | * `Vim Syntastic `_
78 | Plugin for the Vim editor providing compile checking.
79 |
80 | * Visual Studio Code
81 |
82 | * `Visual Studio Code extension `_
83 | Solidity plugin for Microsoft Visual Studio Code that includes syntax highlighting and the Solidity compiler.
84 |
85 | Solidity Tools
86 | ==============
87 |
88 | * `ABI to Solidity interface converter `_
89 | A script for generating contract interfaces from the ABI of a smart contract.
90 |
91 | * `abi-to-sol `_
92 | Tool to generate Solidity interface source from a given ABI JSON.
93 |
94 | * `Doxity `_
95 | Documentation Generator for Solidity.
96 |
97 | * `Ethlint `_
98 | Linter to identify and fix style and security issues in Solidity.
99 |
100 | * `evmdis `_
101 | EVM Disassembler that performs static analysis on the bytecode to provide a higher level of abstraction than raw EVM operations.
102 |
103 | * `EVM Lab `_
104 | Rich tool package to interact with the EVM. Includes a VM, Etherchain API, and a trace-viewer with gas cost display.
105 |
106 | * `hevm `_
107 | EVM debugger and symbolic execution engine.
108 |
109 | * `leafleth `_
110 | A documentation generator for Solidity smart-contracts.
111 |
112 | * `PIET `_
113 | A tool to develop, audit and use Solidity smart contracts through a simple graphical interface.
114 |
115 | * `sol2uml `_
116 | Unified Modeling Language (UML) class diagram generator for Solidity contracts.
117 |
118 | * `solc-select `_
119 | A script to quickly switch between Solidity compiler versions.
120 |
121 | * `Solidity prettier plugin `_
122 | A Prettier Plugin for Solidity.
123 |
124 | * `Solidity REPL `_
125 | Try Solidity instantly with a command-line Solidity console.
126 |
127 | * `solgraph `_
128 | Visualize Solidity control flow and highlight potential security vulnerabilities.
129 |
130 | * `Solhint `_
131 | Solidity linter that provides security, style guide and best practice rules for smart contract validation.
132 |
133 | * `Sūrya `_
134 | Utility tool for smart contract systems, offering a number of visual outputs and information about the contracts' structure. Also supports querying the function call graph.
135 |
136 | * `Universal Mutator `_
137 | A tool for mutation generation, with configurable rules and support for Solidity and Vyper.
138 |
139 | Third-Party Solidity Parsers and Grammars
140 | =========================================
141 |
142 | * `Solidity Parser for JavaScript `_
143 | A Solidity parser for JS built on top of a robust ANTLR4 grammar.
144 |
--------------------------------------------------------------------------------
/docs/contracts/visibility-and-getters.rst:
--------------------------------------------------------------------------------
1 | .. index:: ! visibility, external, public, private, internal
2 |
3 | .. _visibility-and-getters:
4 |
5 | **********************
6 | Visibility and Getters
7 | **********************
8 |
9 | Solidity knows two kinds of function calls: internal
10 | ones that do not create an actual EVM call (also called
11 | a "message call") and external
12 | ones that do. Because of that, there are four types of visibility for
13 | functions and state variables.
14 |
15 | Functions have to be specified as being ``external``,
16 | ``public``, ``internal`` or ``private``.
17 | For state variables, ``external`` is not possible.
18 |
19 | ``external``
20 | External functions are part of the contract interface,
21 | which means they can be called from other contracts and
22 | via transactions. An external function ``f`` cannot be called
23 | internally (i.e. ``f()`` does not work, but ``this.f()`` works).
24 |
25 | ``public``
26 | Public functions are part of the contract interface
27 | and can be either called internally or via
28 | messages. For public state variables, an automatic getter
29 | function (see below) is generated.
30 |
31 | ``internal``
32 | Those functions and state variables can only be
33 | accessed internally (i.e. from within the current contract
34 | or contracts deriving from it), without using ``this``.
35 | This is the default visibility level for state variables.
36 |
37 | ``private``
38 | Private functions and state variables are only
39 | visible for the contract they are defined in and not in
40 | derived contracts.
41 |
42 | .. note::
43 | Everything that is inside a contract is visible to
44 | all observers external to the blockchain. Making something ``private``
45 | only prevents other contracts from reading or modifying
46 | the information, but it will still be visible to the
47 | whole world outside of the blockchain.
48 |
49 | مشخص کننده میدان دید پس از نوع متغیر وضعیت و در توابع بین لیست پارامتر ها و لیست
50 | پارامتر های بازگشتی می آید.
51 |
52 | .. code-block:: solidity
53 |
54 | // SPDX-License-Identifier: GPL-3.0
55 | pragma solidity >=0.4.16 <0.9.0;
56 |
57 | contract C {
58 | function f(uint a) private pure returns (uint b) { return a + 1; }
59 | function setData(uint a) internal { data = a; }
60 | uint public data;
61 | }
62 |
63 | در مثال زیر، ``D`` ، می تواند ``()c.getData`` برای گرفتن مقدار ``data`` در وضعیت ذخیره سازی
64 | فراخوانی کند، اما نمی تواند ``f`` را فراخوانی کند. قرارداد ``E`` از ``C`` گرفته شده است پس می تواند
65 | ``compute`` را فراخوانی کند.
66 |
67 | .. code-block:: solidity
68 |
69 | // SPDX-License-Identifier: GPL-3.0
70 | pragma solidity >=0.4.16 <0.9.0;
71 |
72 | contract C {
73 | uint private data;
74 |
75 | function f(uint a) private pure returns(uint b) { return a + 1; }
76 | function setData(uint a) public { data = a; }
77 | function getData() public view returns(uint) { return data; }
78 | function compute(uint a, uint b) internal pure returns (uint) { return a + b; }
79 | }
80 |
81 | // This will not compile
82 | contract D {
83 | function readData() public {
84 | C c = new C();
85 | uint local = c.f(7); // error: member `f` is not visible
86 | c.setData(3);
87 | local = c.getData();
88 | local = c.compute(3, 5); // error: member `compute` is not visible
89 | }
90 | }
91 |
92 | contract E is C {
93 | function g() public {
94 | C c = new C();
95 | uint val = compute(3, 5); // access to internal member (from derived to parent contract)
96 | }
97 | }
98 |
99 | .. index:: ! getter;function, ! function;getter
100 | .. _getter-functions:
101 |
102 | توابع گیرنده
103 | =============
104 |
105 | کامپایلر بصورت اتوماتیک توابع گیرنده برای تمامی متغیر های وضعیت **عمومی** می سازد. در
106 | قرارداد ارائه شده زیر، کامپایلر یک تابعی بنام ``data`` تولید خواهد کرد که پارامتر ورودی نخواهد
107 | داشت و یک ``uint`` ، مقدار متغیر وضعیت ``data`` را بر خواهد گردانید. متغیر های وضعیت می
108 | توانند هنگام تعریف مقدار دهی اولیه نیز شوند.
109 |
110 | .. code-block:: solidity
111 |
112 | // SPDX-License-Identifier: GPL-3.0
113 | pragma solidity >=0.4.16 <0.9.0;
114 |
115 | contract C {
116 | uint public data = 42;
117 | }
118 |
119 | contract Caller {
120 | C c = new C();
121 | function f() public view returns (uint) {
122 | return c.data();
123 | }
124 | }
125 |
126 | توابع گیرنده دید خارجی دارند. اگر به نماد(symbol) به طور داخلی دسترسی پیدا شود( مثل :
127 | بدون استفاده از ``.this`` ) آن را به عنوان یک متغیر وضعیت می پندارد. اگر به طور خارجی
128 | دسترسی پیدا شود آن را به عنوان یک تابع می پندارد.
129 |
130 | .. code-block:: solidity
131 |
132 | // SPDX-License-Identifier: GPL-3.0
133 | pragma solidity >=0.4.0 <0.9.0;
134 |
135 | contract C {
136 | uint public data;
137 | function x() public returns (uint) {
138 | data = 3; // internal access
139 | return this.data(); // external access
140 | }
141 | }
142 |
143 | اگر شما آرایه ای از متغیر های وضعیت از نوع ``public`` دارید، شما قادر خواهید بود که فقط یک
144 | عنصر از آرایه را توسط تابع گیرنده تولید شده بر گردانید. این مکانیزم(سازوکار) بوجود آمده تا
145 | از هزینه بالای گاز هنگام برگرداندن کل آرایه جلوگیری کند. شما می توانید با مشخص کردن
146 | ورودی عنصر مورد نیاز خود از آرایه بازگردانید، برای مثال ``myArray(0)`` . اگر شما می خواهید کل
147 | آرایه را در یک فراخوانی بازگردانید نیاز مند نوشتن یک تابع هستید به عنوان مثال:
148 |
149 | .. code-block:: solidity
150 |
151 | // SPDX-License-Identifier: GPL-3.0
152 | pragma solidity >=0.4.16 <0.9.0;
153 |
154 | contract arrayExample {
155 | // public state variable
156 | uint[] public myArray;
157 |
158 | // Getter function generated by the compiler
159 | /*
160 | function myArray(uint i) public view returns (uint) {
161 | return myArray[i];
162 | }
163 | */
164 |
165 | // function that returns entire array
166 | function getArray() public view returns (uint[] memory) {
167 | return myArray;
168 | }
169 | }
170 |
171 | حالا شما می توانید از ``()getArray`` جهت گرفتن کل آرایه، بجای استفاده از ``myArray(i)`` که یک
172 | عنصر به ازای هر فراخوانی باز می گرداند ، استفاده کنید.
173 |
174 | مثال بعدی پیچیدگی بیشتری دارد:
175 |
176 | .. code-block:: solidity
177 |
178 | // SPDX-License-Identifier: GPL-3.0
179 | pragma solidity >=0.4.0 <0.9.0;
180 |
181 | contract Complex {
182 | struct Data {
183 | uint a;
184 | bytes3 b;
185 | mapping (uint => uint) map;
186 | uint[3] c;
187 | uint[] d;
188 | bytes e;
189 | }
190 | mapping (uint => mapping(bool => Data[])) public data;
191 | }
192 |
193 | این تابعی به شکل زیر ایجاد می کند. نگاشت در ساختار حذف شده است زیرا راه خوبی جهت
194 | فراهم کردن کلید نگاشت وجود ندارد:
195 |
196 | .. code-block:: solidity
197 |
198 | function data(uint arg1, bool arg2, uint arg3)
199 | public
200 | returns (uint a, bytes3 b, bytes memory e)
201 | {
202 | a = data[arg1][arg2][arg3].a;
203 | b = data[arg1][arg2][arg3].b;
204 | e = data[arg1][arg2][arg3].e;
205 | }
206 |
--------------------------------------------------------------------------------
/docs/Makefile:
--------------------------------------------------------------------------------
1 | # Makefile for Sphinx documentation
2 | #
3 |
4 | # You can set these variables from the command line.
5 | SPHINXOPTS =
6 | SPHINXBUILD = sphinx-build
7 | PAPER =
8 | BUILDDIR = _build
9 |
10 | # User-friendly check for sphinx-build
11 | ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
12 | $(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
13 | endif
14 |
15 | # Internal variables.
16 | PAPEROPT_a4 = -D latex_paper_size=a4
17 | PAPEROPT_letter = -D latex_paper_size=letter
18 | ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
19 | # the i18n builder cannot share the environment and doctrees with the others
20 | I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
21 |
22 | .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
23 |
24 | help:
25 | @echo "Please use \`make ' where is one of"
26 | @echo " html to make standalone HTML files"
27 | @echo " dirhtml to make HTML files named index.html in directories"
28 | @echo " singlehtml to make a single large HTML file"
29 | @echo " pickle to make pickle files"
30 | @echo " json to make JSON files"
31 | @echo " htmlhelp to make HTML files and a HTML help project"
32 | @echo " qthelp to make HTML files and a qthelp project"
33 | @echo " devhelp to make HTML files and a Devhelp project"
34 | @echo " epub to make an epub"
35 | @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
36 | @echo " latexpdf to make LaTeX files and run them through pdflatex"
37 | @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
38 | @echo " text to make text files"
39 | @echo " man to make manual pages"
40 | @echo " texinfo to make Texinfo files"
41 | @echo " info to make Texinfo files and run them through makeinfo"
42 | @echo " gettext to make PO message catalogs"
43 | @echo " changes to make an overview of all changed/added/deprecated items"
44 | @echo " xml to make Docutils-native XML files"
45 | @echo " pseudoxml to make pseudoxml-XML files for display purposes"
46 | @echo " linkcheck to check all external links for integrity"
47 | @echo " doctest to run all doctests embedded in the documentation (if enabled)"
48 |
49 | clean:
50 | rm -rf $(BUILDDIR)/*
51 |
52 | html:
53 | $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
54 | @echo
55 | @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
56 |
57 | dirhtml:
58 | $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
59 | @echo
60 | @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
61 |
62 | singlehtml:
63 | $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
64 | @echo
65 | @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
66 |
67 | pickle:
68 | $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
69 | @echo
70 | @echo "Build finished; now you can process the pickle files."
71 |
72 | json:
73 | $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
74 | @echo
75 | @echo "Build finished; now you can process the JSON files."
76 |
77 | htmlhelp:
78 | $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
79 | @echo
80 | @echo "Build finished; now you can run HTML Help Workshop with the" \
81 | ".hhp project file in $(BUILDDIR)/htmlhelp."
82 |
83 | qthelp:
84 | $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
85 | @echo
86 | @echo "Build finished; now you can run "qcollectiongenerator" with the" \
87 | ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
88 | @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Solidity.qhcp"
89 | @echo "To view the help file:"
90 | @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Solidity.qhc"
91 |
92 | devhelp:
93 | $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
94 | @echo
95 | @echo "Build finished."
96 | @echo "To view the help file:"
97 | @echo "# mkdir -p $$HOME/.local/share/devhelp/Solidity"
98 | @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Solidity"
99 | @echo "# devhelp"
100 |
101 | epub:
102 | $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
103 | @echo
104 | @echo "Build finished. The epub file is in $(BUILDDIR)/epub."
105 |
106 | latex:
107 | $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
108 | @echo
109 | @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
110 | @echo "Run \`make' in that directory to run these through (pdf)latex" \
111 | "(use \`make latexpdf' here to do that automatically)."
112 |
113 | latexpdf:
114 | $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
115 | @echo "Running LaTeX files through pdflatex..."
116 | $(MAKE) -C $(BUILDDIR)/latex all-pdf
117 | @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
118 |
119 | latexpdfja:
120 | $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
121 | @echo "Running LaTeX files through platex and dvipdfmx..."
122 | $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
123 | @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
124 |
125 | text:
126 | $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
127 | @echo
128 | @echo "Build finished. The text files are in $(BUILDDIR)/text."
129 |
130 | man:
131 | $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
132 | @echo
133 | @echo "Build finished. The manual pages are in $(BUILDDIR)/man."
134 |
135 | texinfo:
136 | $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
137 | @echo
138 | @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
139 | @echo "Run \`make' in that directory to run these through makeinfo" \
140 | "(use \`make info' here to do that automatically)."
141 |
142 | info:
143 | $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
144 | @echo "Running Texinfo files through makeinfo..."
145 | make -C $(BUILDDIR)/texinfo info
146 | @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
147 |
148 | gettext:
149 | $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
150 | @echo
151 | @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
152 |
153 | changes:
154 | $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
155 | @echo
156 | @echo "The overview file is in $(BUILDDIR)/changes."
157 |
158 | linkcheck:
159 | $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
160 | @echo
161 | @echo "Link check complete; look for any errors in the above output " \
162 | "or in $(BUILDDIR)/linkcheck/output.txt."
163 |
164 | doctest:
165 | $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
166 | @echo "Testing of doctests in the sources finished, look at the " \
167 | "results in $(BUILDDIR)/doctest/output.txt."
168 |
169 | xml:
170 | $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
171 | @echo
172 | @echo "Build finished. The XML files are in $(BUILDDIR)/xml."
173 |
174 | pseudoxml:
175 | $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
176 | @echo
177 | @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
178 |
--------------------------------------------------------------------------------
/docs/make.bat:
--------------------------------------------------------------------------------
1 | @ECHO OFF
2 |
3 | REM Command file for Sphinx documentation
4 |
5 | if "%SPHINXBUILD%" == "" (
6 | set SPHINXBUILD=sphinx-build
7 | )
8 | set BUILDDIR=_build
9 | set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
10 | set I18NSPHINXOPTS=%SPHINXOPTS% .
11 | if NOT "%PAPER%" == "" (
12 | set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
13 | set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
14 | )
15 |
16 | if "%1" == "" goto help
17 |
18 | if "%1" == "help" (
19 | :help
20 | echo.Please use `make ^` where ^ is one of
21 | echo. html to make standalone HTML files
22 | echo. dirhtml to make HTML files named index.html in directories
23 | echo. singlehtml to make a single large HTML file
24 | echo. pickle to make pickle files
25 | echo. json to make JSON files
26 | echo. htmlhelp to make HTML files and a HTML help project
27 | echo. qthelp to make HTML files and a qthelp project
28 | echo. devhelp to make HTML files and a Devhelp project
29 | echo. epub to make an epub
30 | echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter
31 | echo. text to make text files
32 | echo. man to make manual pages
33 | echo. texinfo to make Texinfo files
34 | echo. gettext to make PO message catalogs
35 | echo. changes to make an overview over all changed/added/deprecated items
36 | echo. xml to make Docutils-native XML files
37 | echo. pseudoxml to make pseudoxml-XML files for display purposes
38 | echo. linkcheck to check all external links for integrity
39 | echo. doctest to run all doctests embedded in the documentation if enabled
40 | goto end
41 | )
42 |
43 | if "%1" == "clean" (
44 | for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
45 | del /q /s %BUILDDIR%\*
46 | goto end
47 | )
48 |
49 |
50 | %SPHINXBUILD% 2> nul
51 | if errorlevel 9009 (
52 | echo.
53 | echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
54 | echo.installed, then set the SPHINXBUILD environment variable to point
55 | echo.to the full path of the 'sphinx-build' executable. Alternatively you
56 | echo.may add the Sphinx directory to PATH.
57 | echo.
58 | echo.If you don't have Sphinx installed, grab it from
59 | echo.http://sphinx-doc.org/
60 | exit /b 1
61 | )
62 |
63 | if "%1" == "html" (
64 | %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
65 | if errorlevel 1 exit /b 1
66 | echo.
67 | echo.Build finished. The HTML pages are in %BUILDDIR%/html.
68 | goto end
69 | )
70 |
71 | if "%1" == "dirhtml" (
72 | %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
73 | if errorlevel 1 exit /b 1
74 | echo.
75 | echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
76 | goto end
77 | )
78 |
79 | if "%1" == "singlehtml" (
80 | %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
81 | if errorlevel 1 exit /b 1
82 | echo.
83 | echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
84 | goto end
85 | )
86 |
87 | if "%1" == "pickle" (
88 | %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
89 | if errorlevel 1 exit /b 1
90 | echo.
91 | echo.Build finished; now you can process the pickle files.
92 | goto end
93 | )
94 |
95 | if "%1" == "json" (
96 | %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
97 | if errorlevel 1 exit /b 1
98 | echo.
99 | echo.Build finished; now you can process the JSON files.
100 | goto end
101 | )
102 |
103 | if "%1" == "htmlhelp" (
104 | %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
105 | if errorlevel 1 exit /b 1
106 | echo.
107 | echo.Build finished; now you can run HTML Help Workshop with the ^
108 | .hhp project file in %BUILDDIR%/htmlhelp.
109 | goto end
110 | )
111 |
112 | if "%1" == "qthelp" (
113 | %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
114 | if errorlevel 1 exit /b 1
115 | echo.
116 | echo.Build finished; now you can run "qcollectiongenerator" with the ^
117 | .qhcp project file in %BUILDDIR%/qthelp, like this:
118 | echo.^> qcollectiongenerator %BUILDDIR%\qthelp\Solidity.qhcp
119 | echo.To view the help file:
120 | echo.^> assistant -collectionFile %BUILDDIR%\qthelp\Solidity.ghc
121 | goto end
122 | )
123 |
124 | if "%1" == "devhelp" (
125 | %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
126 | if errorlevel 1 exit /b 1
127 | echo.
128 | echo.Build finished.
129 | goto end
130 | )
131 |
132 | if "%1" == "epub" (
133 | %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
134 | if errorlevel 1 exit /b 1
135 | echo.
136 | echo.Build finished. The epub file is in %BUILDDIR%/epub.
137 | goto end
138 | )
139 |
140 | if "%1" == "latex" (
141 | %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
142 | if errorlevel 1 exit /b 1
143 | echo.
144 | echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
145 | goto end
146 | )
147 |
148 | if "%1" == "latexpdf" (
149 | %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
150 | cd %BUILDDIR%/latex
151 | make all-pdf
152 | cd %BUILDDIR%/..
153 | echo.
154 | echo.Build finished; the PDF files are in %BUILDDIR%/latex.
155 | goto end
156 | )
157 |
158 | if "%1" == "latexpdfja" (
159 | %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
160 | cd %BUILDDIR%/latex
161 | make all-pdf-ja
162 | cd %BUILDDIR%/..
163 | echo.
164 | echo.Build finished; the PDF files are in %BUILDDIR%/latex.
165 | goto end
166 | )
167 |
168 | if "%1" == "text" (
169 | %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
170 | if errorlevel 1 exit /b 1
171 | echo.
172 | echo.Build finished. The text files are in %BUILDDIR%/text.
173 | goto end
174 | )
175 |
176 | if "%1" == "man" (
177 | %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
178 | if errorlevel 1 exit /b 1
179 | echo.
180 | echo.Build finished. The manual pages are in %BUILDDIR%/man.
181 | goto end
182 | )
183 |
184 | if "%1" == "texinfo" (
185 | %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo
186 | if errorlevel 1 exit /b 1
187 | echo.
188 | echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo.
189 | goto end
190 | )
191 |
192 | if "%1" == "gettext" (
193 | %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
194 | if errorlevel 1 exit /b 1
195 | echo.
196 | echo.Build finished. The message catalogs are in %BUILDDIR%/locale.
197 | goto end
198 | )
199 |
200 | if "%1" == "changes" (
201 | %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
202 | if errorlevel 1 exit /b 1
203 | echo.
204 | echo.The overview file is in %BUILDDIR%/changes.
205 | goto end
206 | )
207 |
208 | if "%1" == "linkcheck" (
209 | %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
210 | if errorlevel 1 exit /b 1
211 | echo.
212 | echo.Link check complete; look for any errors in the above output ^
213 | or in %BUILDDIR%/linkcheck/output.txt.
214 | goto end
215 | )
216 |
217 | if "%1" == "doctest" (
218 | %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
219 | if errorlevel 1 exit /b 1
220 | echo.
221 | echo.Testing of doctests in the sources finished, look at the ^
222 | results in %BUILDDIR%/doctest/output.txt.
223 | goto end
224 | )
225 |
226 | if "%1" == "xml" (
227 | %SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml
228 | if errorlevel 1 exit /b 1
229 | echo.
230 | echo.Build finished. The XML files are in %BUILDDIR%/xml.
231 | goto end
232 | )
233 |
234 | if "%1" == "pseudoxml" (
235 | %SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml
236 | if errorlevel 1 exit /b 1
237 | echo.
238 | echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml.
239 | goto end
240 | )
241 |
242 | :end
243 |
--------------------------------------------------------------------------------
/docs/examples/voting.rst:
--------------------------------------------------------------------------------
1 | .. index:: voting, ballot
2 |
3 | .. _voting:
4 |
5 | ******
6 | رای گیری
7 | ******
8 |
9 |
10 | قرارداد زیر کاملاً پیچیده است، اما بسیاری از ویژگیهای سالیدیتی را به نمایش میگذارد. قرارداد رای گیری را اجرا میکند. البته، مشکلات اصلی رای گیری الکترونیکی نحوه واگذاری حق رای به افراد صحیح و نحوه جلوگیری از دستکاری است. ما همه مشکلات را در اینجا حل نخواهیم کرد، اما حداقل نشان خواهیم داد که چگونه میتوان رای گیریِ نمایندگان را انجام داد تا شمارش آراء در همان زمان **به صورت خودکار و کاملاً شفاف** انجام شود..
11 |
12 | ایده این است که یک قرارداد برای هر رأی ایجاد شود و نام کوتاهی برای هر گزینه ارائه شود. سپس خالق قرارداد که به عنوان رئیس فعالیت میکند به هر آدرس به طور جداگانه حق رای میدهد.
13 |
14 | افراد پشت آدرسها میتوانند انتخاب کنند که یا خود رأی دهند یا رای خود را به شخصی که به او اعتماد دارند واگذار کنند.
15 |
16 | در پایان زمان رای گیری، ``()winningProposal`` پیشنهاد را با بیشترین تعداد رای برمیگرداند.
17 |
18 |
19 | .. code-block:: solidity
20 |
21 | // SPDX-License-Identifier: GPL-3.0
22 | pragma solidity >=0.7.0 <0.9.0;
23 | /// @title Voting with delegation.
24 | contract Ballot {
25 | // This declares a new complex type which will
26 | // be used for variables later.
27 | // It will represent a single voter.
28 | struct Voter {
29 | uint weight; // weight is accumulated by delegation
30 | bool voted; // if true, that person already voted
31 | address delegate; // person delegated to
32 | uint vote; // index of the voted proposal
33 | }
34 |
35 | // This is a type for a single proposal.
36 | struct Proposal {
37 | bytes32 name; // short name (up to 32 bytes)
38 | uint voteCount; // number of accumulated votes
39 | }
40 |
41 | address public chairperson;
42 |
43 | // This declares a state variable that
44 | // stores a `Voter` struct for each possible address.
45 | mapping(address => Voter) public voters;
46 |
47 | // A dynamically-sized array of `Proposal` structs.
48 | Proposal[] public proposals;
49 |
50 | /// Create a new ballot to choose one of `proposalNames`.
51 | constructor(bytes32[] memory proposalNames) {
52 | chairperson = msg.sender;
53 | voters[chairperson].weight = 1;
54 |
55 | // For each of the provided proposal names,
56 | // create a new proposal object and add it
57 | // to the end of the array.
58 | for (uint i = 0; i < proposalNames.length; i++) {
59 | // `Proposal({...})` creates a temporary
60 | // Proposal object and `proposals.push(...)`
61 | // appends it to the end of `proposals`.
62 | proposals.push(Proposal({
63 | name: proposalNames[i],
64 | voteCount: 0
65 | }));
66 | }
67 | }
68 |
69 | // Give `voter` the right to vote on this ballot.
70 | // May only be called by `chairperson`.
71 | function giveRightToVote(address voter) external {
72 | // If the first argument of `require` evaluates
73 | // to `false`, execution terminates and all
74 | // changes to the state and to Ether balances
75 | // are reverted.
76 | // This used to consume all gas in old EVM versions, but
77 | // not anymore.
78 | // It is often a good idea to use `require` to check if
79 | // functions are called correctly.
80 | // As a second argument, you can also provide an
81 | // explanation about what went wrong.
82 | require(
83 | msg.sender == chairperson,
84 | "Only chairperson can give right to vote."
85 | );
86 | require(
87 | !voters[voter].voted,
88 | "The voter already voted."
89 | );
90 | require(voters[voter].weight == 0);
91 | voters[voter].weight = 1;
92 | }
93 |
94 | /// Delegate your vote to the voter `to`.
95 | function delegate(address to) external {
96 | // assigns reference
97 | Voter storage sender = voters[msg.sender];
98 | require(!sender.voted, "You already voted.");
99 |
100 | require(to != msg.sender, "Self-delegation is disallowed.");
101 |
102 | // Forward the delegation as long as
103 | // `to` also delegated.
104 | // In general, such loops are very dangerous,
105 | // because if they run too long, they might
106 | // need more gas than is available in a block.
107 | // In this case, the delegation will not be executed,
108 | // but in other situations, such loops might
109 | // cause a contract to get "stuck" completely.
110 | while (voters[to].delegate != address(0)) {
111 | to = voters[to].delegate;
112 |
113 | // We found a loop in the delegation, not allowed.
114 | require(to != msg.sender, "Found loop in delegation.");
115 | }
116 |
117 | // Since `sender` is a reference, this
118 | // modifies `voters[msg.sender].voted`
119 | sender.voted = true;
120 | sender.delegate = to;
121 | Voter storage delegate_ = voters[to];
122 | if (delegate_.voted) {
123 | // If the delegate already voted,
124 | // directly add to the number of votes
125 | proposals[delegate_.vote].voteCount += sender.weight;
126 | } else {
127 | // If the delegate did not vote yet,
128 | // add to her weight.
129 | delegate_.weight += sender.weight;
130 | }
131 | }
132 |
133 | /// Give your vote (including votes delegated to you)
134 | /// to proposal `proposals[proposal].name`.
135 | function vote(uint proposal) external {
136 | Voter storage sender = voters[msg.sender];
137 | require(sender.weight != 0, "Has no right to vote");
138 | require(!sender.voted, "Already voted.");
139 | sender.voted = true;
140 | sender.vote = proposal;
141 |
142 | // If `proposal` is out of the range of the array,
143 | // this will throw automatically and revert all
144 | // changes.
145 | proposals[proposal].voteCount += sender.weight;
146 | }
147 |
148 | /// @dev Computes the winning proposal taking all
149 | /// previous votes into account.
150 | function winningProposal() public view
151 | returns (uint winningProposal_)
152 | {
153 | uint winningVoteCount = 0;
154 | for (uint p = 0; p < proposals.length; p++) {
155 | if (proposals[p].voteCount > winningVoteCount) {
156 | winningVoteCount = proposals[p].voteCount;
157 | winningProposal_ = p;
158 | }
159 | }
160 | }
161 |
162 | // Calls winningProposal() function to get the index
163 | // of the winner contained in the proposals array and then
164 | // returns the name of the winner
165 | function winnerName() external view
166 | returns (bytes32 winnerName_)
167 | {
168 | winnerName_ = proposals[winningProposal()].name;
169 | }
170 | }
171 |
172 |
173 | بهبودهای احتمالی
174 | =====================
175 |
176 | در حال حاضر، تراکنشها زیادی برای واگذاری حق رأی به همه شرکت کنندگان مورد نیاز است. آیا میتوانید به راه بهتری فکر کنید؟
177 |
--------------------------------------------------------------------------------
/docs/types/conversion.rst:
--------------------------------------------------------------------------------
1 | .. index:: ! type;conversion, ! cast
2 |
3 | .. _types-conversion-elementary-types:
4 |
5 | تبدیل بین نوعهای اصلی (Conversions between Elementary Types)
6 | ====================================
7 |
8 | تبدیلهای ضمنی (Implicit Conversions)
9 | --------------------
10 |
11 | در برخی موارد هنگام انتسابها، هنگام انتقال آرگومانها به توابع و هنگام اعمال عملگرها، کامپایلر به طور خودکار
12 | یک نوع تبدیل ضمنی اعمال میکند. به طور کلی، اگر به صورت سمنتیک معنا پیدا کند و هیچ اطلاعاتی از بین
13 | نرود، تبدیل ضمنی بین مقدار_نوعهای مختلف امکان پذیر است.
14 |
15 |
16 | به عنوان مثال، ``uint8`` به ``uint16`` و ``int128`` به ``int256`` قابل تبدیل است،
17 | اما ``int8`` به ``uint256`` قابل تبدیل نیست، زیرا ``uint256`` نمیتواند مقادیری مانند ``1-`` را نگه دارد.
18 |
19 | For example, ``uint8`` is convertible to
20 | ``uint16`` and ``int128`` to ``int256``, but ``int8`` is not convertible to ``uint256``,
21 | because ``uint256`` cannot hold values such as ``-1``.
22 |
23 | اگر یک عملگر بر روی نوعهای مختلف اعمال شود، کامپایلر سعی میکند به طور ضمنی یکی از عملوندها را به
24 | نوع دیگری تبدیل کند (این امر برای انتسابها نیز صادق است). این بدان معناست که عملیات همیشه در نوع یکی از عملوندها انجام میشود.
25 |
26 |
27 | برای جزئیات بیشتر در مورد اینکه کدام یک از تغییرات ضمنی امکان پذیر است، لطفاً با بخشهایی هر نوع مراجعه کنید.
28 |
29 |
30 |
31 | در مثال زیر، ``y`` و ``z`` ، عملوندهای جمع، یک نوع ندارند، اما ``uint8`` را میتوان به طور ضمنی
32 | به ``uint16`` تبدیل کرد و نه بالعکس. به همین دلیل، ``y`` قبل از اینکه جمع در نوع ``uint16`` انجام شود،
33 | به نوع ``z`` تبدیل میشود. ``uint16`` نوع حاصل از عبارت ``y + z`` است. از آنجا که به یک متغیر از نوع
34 | ``uint32`` اختصاص داده شده است، تبدیل ضمنی دیگر پس از جمع انجام میشود.
35 |
36 |
37 |
38 | .. code-block:: solidity
39 |
40 | uint8 y;
41 | uint16 z;
42 | uint32 x = y + z;
43 |
44 |
45 | تبدیلهای صریح (Explicit Conversions)
46 | --------------------
47 | اگر کامپایلر اجازه تبدیل ضمنی را ندهد اما اطمینان دارید که یک تبدیل کار میکند، تبدیل صریح نوع گاهی
48 | اوقات امکان پذیر است. این ممکن است منجر به یک رفتار غیر منتظره شود و به شما امکان میدهد برخی از
49 | ویژگیهای امنیتی کامپایلر را دور بزنید، بنابراین مطمئن شوید که نتیجه همان چیزی است که شما میخواهید
50 | و انتظار دارید!
51 |
52 | مثال زیر را در نظر بگیرید که ``int`` منفی را به ``uint`` تبدیل میکند:
53 |
54 | .. code-block:: solidity
55 |
56 | int y = -3;
57 | uint x = uint(y);
58 |
59 | در انتهای این قطعه کد، ``x`` دارای مقدار ``0xfffff..fd`` (64 نویسه hex) است که در نمایش مکمل 256 بیت 3- (منفی سه) است.
60 |
61 |
62 |
63 | اگر یک عدد صحیح صریح به یک نوع کوچکتر تبدیل شود، بیتهای مرتبه بالاتر بریده میشوند:
64 |
65 |
66 |
67 | .. code-block:: solidity
68 |
69 | uint32 a = 0x12345678;
70 | uint16 b = uint16(a); // b will be 0x5678 now
71 |
72 | اگر یک عدد صحیح صریح به یک نوع بزرگتر تبدیل شود، در سمت چپ (یعنی در انتهای مرتبه بالاتر) قرار
73 | میگیرد. نتیجه تبدیل برابر با عدد صحیح اصلی خواهد بود:
74 |
75 | .. code-block:: solidity
76 |
77 | uint16 a = 0x1234;
78 | uint32 b = uint32(a); // b will be 0x00001234 now
79 | assert(a == b);
80 |
81 | نوعهای بایتهای با اندازه ثابت در هنگام تبدیل متفاوت عمل میکنند. میتوان آنها را به عنوان توالی بایتهای
82 | فردی در نظر گرفت و تبدیل به نوع کوچکتر، توالی را قطع میکند:
83 |
84 |
85 | .. code-block:: solidity
86 |
87 | bytes2 a = 0x1234;
88 | bytes1 b = bytes1(a); // b will be 0x12
89 |
90 | اگر یک نوع بایت با اندازه ثابت صریحاً به یک نوع بزرگتر تبدیل شود، در سمت راست پر میشود. دستیابی به
91 | بایت در یک شاخص ثابت منجر به همان مقدار قبل و بعد از تبدیل خواهد شد (اگر شاخص هنوز در محدوده
92 | باشد):
93 |
94 | .. code-block:: solidity
95 |
96 | bytes2 a = 0x1234;
97 | bytes4 b = bytes4(a); // b will be 0x12340000
98 | assert(a[0] == b[0]);
99 | assert(a[1] == b[1]);
100 |
101 | ازآنجایی که آرایههای بایت با اندازه ثابت در هنگام کوتاه کردن یا پر کردن رفتار متفاوتی دارند، درصورتی که هر
102 | دو از اندازه یکسانی برخوردار باشند، تبدیل صریح بین اعداد صحیح و آرایههای بایت با اندازه ثابت مجاز است. اگر
103 | میخواهید بین اعداد صحیح و آرایههای بایت با اندازه ثابت با اندازههای مختلف تبدیل کنید، باید از تبدیلات
104 | میانی استفاده کنید که قوانین کوتاه کردن و پر کردن مورد نظر را صریح میکند:
105 |
106 |
107 |
108 | .. code-block:: solidity
109 |
110 | bytes2 a = 0x1234;
111 | uint32 b = uint16(a); // b will be 0x00001234
112 | uint32 c = uint32(bytes4(a)); // c will be 0x12340000
113 | uint8 d = uint8(uint16(a)); // d will be 0x34
114 | uint8 e = uint8(bytes1(a)); // e will be 0x12
115 |
116 | آرایههای ``bytes`` و برشهای ``bytes`` کالدیتا را میتوان به طور صریح به انواع بایتهای ثابت (``bytes1``/…/``bytes32``)
117 | تبدیل کرد. در صورتی که آرایه طولانی تر از نوع بایتهای ثابت هدف باشد، برش در انتها اتفاق میافتد. اگر آرایه کوتاهتر از نوع
118 | هدف باشد، در انتها با صفر پر میشود.
119 |
120 |
121 | .. code-block:: solidity
122 |
123 | // SPDX-License-Identifier: GPL-3.0
124 | pragma solidity ^0.8.5;
125 |
126 | contract C {
127 | bytes s = "abcdefgh";
128 | function f(bytes calldata c, bytes memory m) public view returns (bytes16, bytes3) {
129 | require(c.length == 16, "");
130 | bytes16 b = bytes16(m); // if length of m is greater than 16, truncation will happen
131 | b = bytes16(s); // padded on the right, so result is "abcdefgh\0\0\0\0\0\0\0\0"
132 | bytes3 b1 = bytes3(s); // truncated, b1 equals to "abc"
133 | b = bytes16(c[:8]); // also padded with zeros
134 | return (b, b1);
135 | }
136 | }
137 |
138 | .. _types-conversion-literals:
139 |
140 | تبدیل بین لیترالها و نوعهای اصلی
141 | =================================================
142 |
143 | انواع عدد صحیح (Integer Types)
144 | -------------
145 | لیترالهای عدد دسیمال و هگزادسیمال را میتوان به طور ضمنی به هر نوع عددی صحیح که به اندازه کافی بزرگ
146 | باشد و بتوان آن را بدون کوتاه سازی نشان داد، تبدیل کرد:
147 |
148 |
149 | .. code-block:: solidity
150 |
151 | uint8 a = 12; // fine
152 | uint32 b = 1234; // fine
153 | uint16 c = 0x123456; // fails, since it would have to truncate to 0x3456
154 |
155 | .. note::
156 |
157 | قبل از نسخه 0.8.0، هر عدد تحت اعشاری یا هگزا دسیمال میتواند به ضمنی به یک نوع صحیح تبدیل
158 | شود. از 0.8.0، چنین تبدیلهای صریح به اندازه تبدیلهای ضمنی سختگیرانه هستند، یعنی تنها در صورتی
159 | مجاز هستند که کلمه تحت اللفظی در محدوده حاصله مطابقت داشته باشد.
160 |
161 | آرایههای بایت با اندازه ثابت
162 | ----------------------
163 |
164 | اعداد اعشاری لیترال را نمیتوان به صورت ضمنی به آرایههای بایت با اندازه ثابت تبدیل کرد. میتواند لیترالهای
165 | عددی هگزادسیمال باشد، اما فقط در صورتی که تعداد ارقام هگز دقیقاً متناسب با اندازه نوع بایت باشد. به عنوان
166 | ک استثنا، هر دو لیترالهای دسیمال و هگزادسیمال که مقدار آنها صفر است، میتوانند به هر تایپ بایت با اندازه
167 | با اندازه ثابت تبدیل شوند:
168 |
169 |
170 |
171 | .. code-block:: solidity
172 |
173 | bytes2 a = 54321; // not allowed
174 | bytes2 b = 0x12; // not allowed
175 | bytes2 c = 0x123; // not allowed
176 | bytes2 d = 0x1234; // fine
177 | bytes2 e = 0x0012; // fine
178 | bytes4 f = 0; // fine
179 | bytes4 g = 0x0; // fine
180 |
181 | اگر تعداد کاراکترهای آنها با اندازه نوع بایتها مطابقت داشته باشد، میتوان لیترالهای رشتهای و لیترالهای
182 | رشتهای هگزی را به طور ضمنی به آرایههای بایت با اندازه ثابت تبدیل کرد:
183 |
184 | .. code-block:: solidity
185 |
186 | bytes2 a = hex"1234"; // fine
187 | bytes2 b = "xy"; // fine
188 | bytes2 c = hex"12"; // not allowed
189 | bytes2 d = hex"123"; // not allowed
190 | bytes2 e = "x"; // not allowed
191 | bytes2 f = "xyz"; // not allowed
192 |
193 | آدرسها
194 | ---------
195 |
196 | همانطور که در :ref:`آدرس لیترالها` توضیح داده شد، لیترالهای هگز با اندازه صحیح که از آزمون چکسام عبور
197 | میکنند از نوع ``address`` هستند. هیچ لیترال دیگری را نمیتوان به طور ضمنی به
198 | نوع ``address`` تبدیل کرد.
199 |
200 |
201 | تبدیل صریح از ``bytes20`` یا هر نوع عدد صحیح به ``address`` منجر به ``address payable`` میشود.
202 |
203 |
204 | ``address a`` را میتوان به ``address payable`` از طریق ``payable(a)`` تبدیل کرد.
205 |
206 |
--------------------------------------------------------------------------------
/docs/types/mapping-types.rst:
--------------------------------------------------------------------------------
1 | .. index:: !mapping
2 | .. _mapping-types:
3 |
4 | انواع نگاشتها (Mapping Types)
5 | =============
6 |
7 | نوعهای نگاشت از سینتکس ``mapping(_KeyType => _ValueType)`` استفاده میکنند و
8 | متغیرهای نوع نگاشت با استفاده از سینتکس
9 | ``mapping(_KeyType => _ValueType) _VariableName`` مشخص میشوند. ``KeyType_`` میتواند هر نوع مقدار داخلی، ``bytes`` ، ``string`` یا هر نوع قرارداد یا enum
10 | باشد. سایر نوعهای پیچیده یا تعریف شده توسط کاربر، مانند نگاشت یا (mapping)، structها یا انواع آرایه مجاز نیستند. ``ValueType_`` میتواند هر نوعی باشد، از جمله نگاشتها، آرایهها و structها.
11 |
12 |
13 | میتوانید نگاشتها را به صورت `جداول هش `_ در نظر بگیرید که عملاً مقداردهی اولیه میشوند به گونه ای که هر
14 | کلید ممکن وجود دارد و به مقداری نگاشت میشود که پیش نمایش بایت همهی آن صفر میباشند، یک نوع :ref:`مقدار پیش فرض` . شباهت در اینجا پایان مییابد، دادههای کلیدی در نگاشت ذخیره نمیشوند، فقط از هش ``keccak256`` برای جستجوی مقدار استفاده میشود.
15 |
16 |
17 |
18 | به همین دلیل، نگاشتها طول یا مفهومی از کلید یا مقدار تنظیم شده ندارند و بنابراین بدون اطلاعات اضافی در مورد کلیدهای اختصاص داده شده پاک نمیشوند (به قسمت :ref:`clearing-mappings` مراجعه کنید).
19 |
20 |
21 |
22 | نگاشتها فقط میتوانند یک مکان داده از ``storage`` را داشته باشند و بنابراین برای متغیرهای حالت، به
23 | عنوان نوعهای مرجع storage در توابع، یا به عنوان پارامترهای توابع کتابخانه مجاز هستند. آنها نمیتوانند به
24 | عنوان پارامترها یا پارامترهای بازگشتی توابع قرارداد که در معرض دید عموم قرار دارند، مورد استفاده قرار گیرند.
25 | این محدودیتها برای آرایهها و structهای حاوی نگاشت نیز صادق است.
26 |
27 |
28 | شما میتوانید متغیرهای حالت از نوع نگاشت را به صورت ``public`` علامت گذاری کنید و سالیدیتی یک
29 | گیرنده (:ref:`getter `) برای شما ایجاد میکند. ``KeyType_`` به یک پارامتر برای getter تبدیل میشود.
30 | اگر ``ValueType_`` یک مقدار نوع یا یک struct باشد، گیتر ``ValueType_`` را برمیگرداند.
31 | اگر ``ValueType_`` یک آرایه یا نگاشت باشد، getter به صورت بازگشتی برای هر ``KeyType_`` یک
32 | پارامتر دارد.
33 |
34 |
35 | در مثال زیر، قرارداد ``MappingExample`` یک نگاشت از ``balances`` عمومی را تعریف میکند، با نوع
36 | کلید یک ``address`` و یک نوع مقدار یک ``uint`` ، و یک آدرس اتریوم را به یک مقدار صحیح بدون علامت
37 | نگاشت میکند. از آنجا که ``uint`` یک نوع مقدار است، گیرنده مقداری را متناسب با نوع آن برمیگرداند که
38 | میتوانید آن را در قرارداد ``MappingUser`` مشاهده کنید که مقدار را در آدرس مشخص شده برمیگرداند.
39 |
40 |
41 | .. code-block:: solidity
42 |
43 | // SPDX-License-Identifier: GPL-3.0
44 | pragma solidity >=0.4.0 <0.9.0;
45 |
46 | contract MappingExample {
47 | mapping(address => uint) public balances;
48 |
49 | function update(uint newBalance) public {
50 | balances[msg.sender] = newBalance;
51 | }
52 | }
53 |
54 | contract MappingUser {
55 | function f() public returns (uint) {
56 | MappingExample m = new MappingExample();
57 | m.update(100);
58 | return m.balances(address(this));
59 | }
60 | }
61 |
62 |
63 | مثال زیر یک نسخه ساده از توکن `ERC20 token `_ است. ``_allowances`` نمونهای از نوع نگاشت در داخل نوع
64 | نگاشت دیگر است. مثال زیر از ``_allowances`` برای ثبت مبلغی که شخص دیگری مجاز به برداشت از
65 | حساب شما است استفاده میکند.
66 |
67 |
68 | .. code-block:: solidity
69 |
70 | // SPDX-License-Identifier: GPL-3.0
71 | pragma solidity >=0.4.22 <0.9.0;
72 |
73 | contract MappingExample {
74 |
75 | mapping (address => uint256) private _balances;
76 | mapping (address => mapping (address => uint256)) private _allowances;
77 |
78 | event Transfer(address indexed from, address indexed to, uint256 value);
79 | event Approval(address indexed owner, address indexed spender, uint256 value);
80 |
81 | function allowance(address owner, address spender) public view returns (uint256) {
82 | return _allowances[owner][spender];
83 | }
84 |
85 | function transferFrom(address sender, address recipient, uint256 amount) public returns (bool) {
86 | _transfer(sender, recipient, amount);
87 | approve(sender, msg.sender, amount);
88 | return true;
89 | }
90 |
91 | function approve(address owner, address spender, uint256 amount) public returns (bool) {
92 | require(owner != address(0), "ERC20: approve from the zero address");
93 | require(spender != address(0), "ERC20: approve to the zero address");
94 |
95 | _allowances[owner][spender] = amount;
96 | emit Approval(owner, spender, amount);
97 | return true;
98 | }
99 |
100 | function _transfer(address sender, address recipient, uint256 amount) internal {
101 | require(sender != address(0), "ERC20: transfer from the zero address");
102 | require(recipient != address(0), "ERC20: transfer to the zero address");
103 |
104 | _balances[sender] -= amount;
105 | _balances[recipient] += amount;
106 | emit Transfer(sender, recipient, amount);
107 | }
108 | }
109 |
110 |
111 | .. index:: !iterable mappings
112 | .. _iterable-mappings:
113 |
114 | نگاشت های تکرارپذیر
115 | -----------------
116 |
117 | نمیتوانید بر روی نگاشتها تکرار کنید، یعنی نمیتوانید کلیدهای آنها را بشمارید.گرچند امکان اجرای یک
118 | ساختار داده در بالای آنها و تکرار آن وجود دارد. به عنوان مثال، کد زیر یک
119 | کتابخانه ``IterableMapping`` را پیاده سازی میکند که قرارداد ``User`` سپس دادهها را نیز اضافه
120 | میکند و تابع ``sum`` تکرار میشود تا تمام مقادیر را جمع کند.
121 |
122 |
123 | .. code-block:: solidity
124 | :force:
125 |
126 | // SPDX-License-Identifier: GPL-3.0
127 | pragma solidity >=0.6.8 <0.9.0;
128 |
129 | struct IndexValue { uint keyIndex; uint value; }
130 | struct KeyFlag { uint key; bool deleted; }
131 |
132 | struct itmap {
133 | mapping(uint => IndexValue) data;
134 | KeyFlag[] keys;
135 | uint size;
136 | }
137 |
138 | library IterableMapping {
139 | function insert(itmap storage self, uint key, uint value) internal returns (bool replaced) {
140 | uint keyIndex = self.data[key].keyIndex;
141 | self.data[key].value = value;
142 | if (keyIndex > 0)
143 | return true;
144 | else {
145 | keyIndex = self.keys.length;
146 | self.keys.push();
147 | self.data[key].keyIndex = keyIndex + 1;
148 | self.keys[keyIndex].key = key;
149 | self.size++;
150 | return false;
151 | }
152 | }
153 |
154 | function remove(itmap storage self, uint key) internal returns (bool success) {
155 | uint keyIndex = self.data[key].keyIndex;
156 | if (keyIndex == 0)
157 | return false;
158 | delete self.data[key];
159 | self.keys[keyIndex - 1].deleted = true;
160 | self.size --;
161 | }
162 |
163 | function contains(itmap storage self, uint key) internal view returns (bool) {
164 | return self.data[key].keyIndex > 0;
165 | }
166 |
167 | function iterate_start(itmap storage self) internal view returns (uint keyIndex) {
168 | return iterate_next(self, type(uint).max);
169 | }
170 |
171 | function iterate_valid(itmap storage self, uint keyIndex) internal view returns (bool) {
172 | return keyIndex < self.keys.length;
173 | }
174 |
175 | function iterate_next(itmap storage self, uint keyIndex) internal view returns (uint r_keyIndex) {
176 | keyIndex++;
177 | while (keyIndex < self.keys.length && self.keys[keyIndex].deleted)
178 | keyIndex++;
179 | return keyIndex;
180 | }
181 |
182 | function iterate_get(itmap storage self, uint keyIndex) internal view returns (uint key, uint value) {
183 | key = self.keys[keyIndex].key;
184 | value = self.data[key].value;
185 | }
186 | }
187 |
188 | // How to use it
189 | contract User {
190 | // Just a struct holding our data.
191 | itmap data;
192 | // Apply library functions to the data type.
193 | using IterableMapping for itmap;
194 |
195 | // Insert something
196 | function insert(uint k, uint v) public returns (uint size) {
197 | // This calls IterableMapping.insert(data, k, v)
198 | data.insert(k, v);
199 | // We can still access members of the struct,
200 | // but we should take care not to mess with them.
201 | return data.size;
202 | }
203 |
204 | // Computes the sum of all stored data.
205 | function sum() public view returns (uint s) {
206 | for (
207 | uint i = data.iterate_start();
208 | data.iterate_valid(i);
209 | i = data.iterate_next(i)
210 | ) {
211 | (, uint value) = data.iterate_get(i);
212 | s += value;
213 | }
214 | }
215 | }
216 |
--------------------------------------------------------------------------------
/docs/metadata.rst:
--------------------------------------------------------------------------------
1 | .. _metadata:
2 |
3 | #################
4 | فراداده قرارداد (Contract Metadata)
5 | #################
6 |
7 | .. index:: metadata, contract verification
8 |
9 | کامپایلر سالیدیتی به طور خودکار یک فایل JSON، فراداده قرارداد، که حاوی اطلاعاتی درباره قرارداد کامپایل
10 | شده است، تولید می کند. می توانید از این فایل برای query یا جستجو از نسخه کامپایلر، منابع استفاده
11 | شده، اسناد ABI و NatSpec برای تعامل ایمن تر با قرارداد و تأیید کد منبع آن استفاده کنید.
12 |
13 | کامپایلر به طور پیشفرض هش IPFS فایل فراداده را به انتهای بایت کد (برای جزئیات، در زیر ببینید) هر
14 | قرارداد اضافه میکند، به طوری که میتوانید فایل را به روشی احراز هویت شده و بدون نیاز به اتصال به یک
15 | ارائهدهنده داده متمرکز بازیابی کنید. گزینه های دیگر موجود عبارتند از هش Swarm و عدم الحاق هش
16 | ابرداده به بایت کد. این میتواند با :ref:`Standard JSON Interface` پیکربندی شود.
17 |
18 |
19 | شما باید فایل فراداده را در IPFS، سوارم(Swarm) یا سرویس دیگری منتشر کنید تا دیگران بتوانند به آن
20 | دسترسی داشته باشند. شما فایل را با استفاده از دستور ``solc --metadata`` ایجاد می کنید که فایلی به نام
21 | ``ContractName_meta.json`` تولید می کند. این شامل IPFS و ارجاعات Swarm به کد منبع است،
22 | بنابراین شما باید تمام فایل های منبع و فایل فراداده را آپلود کنید.
23 |
24 |
25 |
26 | فایل فراداده دارای فرمت زیر است. مثال زیر به روشی قابل خواندن برای انسان ارائه شده است. فراداده هایی
27 | که به درستی قالب بندی شده اند باید از نقل قول ها به درستی استفاده کنند، فضای خالی را به حداقل
28 | برسانند و کلیدهای همه اشیاء را مرتب کنند تا به یک قالب بندی منحصر به فرد برسند. نظرات در اینجا فقط
29 | برای اهداف توضیحی مجاز نیست و استفاده می شود.
30 |
31 |
32 | .. code-block:: javascript
33 |
34 | {
35 | // Required: The version of the metadata format
36 | "version": "1",
37 | // Required: Source code language, basically selects a "sub-version"
38 | // of the specification
39 | "language": "Solidity",
40 | // Required: Details about the compiler, contents are specific
41 | // to the language.
42 | "compiler": {
43 | // Required for Solidity: Version of the compiler
44 | "version": "0.4.6+commit.2dabbdf0.Emscripten.clang",
45 | // Optional: Hash of the compiler binary which produced this output
46 | "keccak256": "0x123..."
47 | },
48 | // Required: Compilation source files/source units, keys are file names
49 | "sources":
50 | {
51 | "myFile.sol": {
52 | // Required: keccak256 hash of the source file
53 | "keccak256": "0x123...",
54 | // Required (unless "content" is used, see below): Sorted URL(s)
55 | // to the source file, protocol is more or less arbitrary, but a
56 | // Swarm URL is recommended
57 | "urls": [ "bzzr://56ab..." ],
58 | // Optional: SPDX license identifier as given in the source file
59 | "license": "MIT"
60 | },
61 | "destructible": {
62 | // Required: keccak256 hash of the source file
63 | "keccak256": "0x234...",
64 | // Required (unless "url" is used): literal contents of the source file
65 | "content": "contract destructible is owned { function destroy() { if (msg.sender == owner) selfdestruct(owner); } }"
66 | }
67 | },
68 | // Required: Compiler settings
69 | "settings":
70 | {
71 | // Required for Solidity: Sorted list of remappings
72 | "remappings": [ ":g=/dir" ],
73 | // Optional: Optimizer settings. The fields "enabled" and "runs" are deprecated
74 | // and are only given for backwards-compatibility.
75 | "optimizer": {
76 | "enabled": true,
77 | "runs": 500,
78 | "details": {
79 | // peephole defaults to "true"
80 | "peephole": true,
81 | // inliner defaults to "true"
82 | "inliner": true,
83 | // jumpdestRemover defaults to "true"
84 | "jumpdestRemover": true,
85 | "orderLiterals": false,
86 | "deduplicate": false,
87 | "cse": false,
88 | "constantOptimizer": false,
89 | "yul": true,
90 | // Optional: Only present if "yul" is "true"
91 | "yulDetails": {
92 | "stackAllocation": false,
93 | "optimizerSteps": "dhfoDgvulfnTUtnIf..."
94 | }
95 | }
96 | },
97 | "metadata": {
98 | // Reflects the setting used in the input json, defaults to false
99 | "useLiteralContent": true,
100 | // Reflects the setting used in the input json, defaults to "ipfs"
101 | "bytecodeHash": "ipfs"
102 | },
103 | // Required for Solidity: File and name of the contract or library this
104 | // metadata is created for.
105 | "compilationTarget": {
106 | "myFile.sol": "MyContract"
107 | },
108 | // Required for Solidity: Addresses for libraries used
109 | "libraries": {
110 | "MyLib": "0x123123..."
111 | }
112 | },
113 | // Required: Generated information about the contract.
114 | "output":
115 | {
116 | // Required: ABI definition of the contract
117 | "abi": [/* ... */],
118 | // Required: NatSpec user documentation of the contract
119 | "userdoc": [/* ... */],
120 | // Required: NatSpec developer documentation of the contract
121 | "devdoc": [/* ... */]
122 | }
123 | }
124 |
125 | .. warning::
126 |
127 | از آنجایی که بایت کد قرارداد حاصل به طور پیشفرض حاوی هش ابرداده است، هر تغییری در ابرداده ممکن
128 | است منجر به تغییر بایت کد شود که شامل تغییرات در نام فایل یا مسیر است و از آنجایی که فراداده شامل
129 | هش از تمام منابع استفاده شده است، یک تغییر فضای خالی منجر به ابرداده های مختلف و کد بایت متفاوت
130 | می شود.
131 |
132 |
133 | .. note::
134 |
135 | تعریف ABI در بالا ترتیب ثابتی ندارد. می تواند با نسخه های کامپایلر تغییر کند. با شروع از سالیدیتی نسخه 0.5.12، هر چند، آرایه نظم خاصی را حفظ می کند.
136 |
137 |
138 |
139 | .. _encoding-of-the-metadata-hash-in-the-bytecode:
140 |
141 | رمزگذاری هش فراداده در بایت کد
142 | =============================================
143 | از آنجایی که ممکن است در آینده از روشهای دیگری برای بازیابی فایل فراداده پشتیبانی کنیم، مپینگ
144 | ``{"ipfs": , "solc": }`` بهصورت کدگذاری `CBOR `_ ذخیره میشود.
145 | از آنجایی که مپینگ ممکن است حاوی کلیدهای بیشتری باشد (به زیر مراجعه کنید) و پیدا کردن ابتدای آن
146 | رمزگذاری آسان نیست، طول آن در یک رمزگذاری دو بایتی بیگ اندیان(big-endian) اضافه می شود.
147 | نسخه فعلی کامپایلر سالیدیتی معمولا موارد زیر را به انتهای بایت کد مستقر شده اضافه می کند، بنابراین
148 | برای بازیابی داده ها، می توان انتهای بایت کد مستقر شده را بررسی کرد تا با آن الگو مطابقت داشته باشد و
149 | از هش IPFS برای بازیابی فایل استفاده کرد.
150 |
151 |
152 |
153 | .. code-block:: text
154 |
155 | 0xa2
156 | 0x64 'i' 'p' 'f' 's' 0x58 0x22 <34 bytes IPFS hash>
157 | 0x64 's' 'o' 'l' 'c' 0x43 <3 byte version encoding>
158 | 0x00 0x33
159 |
160 | در حالی که بیلدهای انتشار solc از کدگذاری 3 بایتی نسخه همانطور که در بالا نشان داده شده است (هر
161 | کدام یک بایت برای شماره نسخه اصلی، فرعی و وصله) استفاده می کنند، نسخه های پیش از انتشار از یک
162 | رشته نسخه کامل شامل هش commit و تاریخ ساخت استفاده می کنند.
163 |
164 |
165 | .. note::
166 |
167 | مپینگ CBOR میتواند حاوی کلیدهای دیگری نیز باشد، بنابراین بهتر است به جای اینکه با ``0xa264``
168 | شروع کنید، دادهها را به طور کامل رمزگشایی کنید. به عنوان مثال، اگر از هر ویژگی آزمایشی که بر تولید
169 | کد تأثیر می گذارد استفاده شود، مپینگ نیز حاوی ``"experimental": true`` . می باشد.
170 |
171 |
172 | .. note::
173 |
174 | توجه: کامپایلر در حال حاضر از هش IPFS فراداده استفاده می کند، اما ممکن است در آینده از هش bzzr1 یا هش دیگری نیز استفاده کند، بنابراین برای شروع با ``0xa2 0x64 'i' 'p' 'f' 's'`` به این دنباله اعتماد نکنید . ما همچنین ممکن است داده های اضافی را به این ساختار CBOR اضافه کنیم، بنابراین بهترین گزینه استفادهاز تجزیه کننده CBOR مناسب است.
175 |
176 |
177 | استفاده برای تولید رابط خودکار و NatSpec
178 | ====================================================
179 |
180 | فراداده به روش زیر استفاده می شود: مؤلفه ای که می خواهد با یک قرارداد تعامل داشته باشد (مثلاً Mist
181 | یا هر کیف پول) کد قرارداد را بازیابی می کند، از آن هش IPFS/Swarm یک فایل که سپس بازیابی می
182 | شود. آن فایل با JSON در ساختاری مانند بالا رمزگشایی می شود.
183 |
184 |
185 | سپس این مؤلفه می تواند از ABI برای ایجاد خودکار یک رابط کاربری ابتدایی برای قرارداد استفاده کند.
186 |
187 | علاوه بر این، کیف پول میتواند از اسناد کاربر theNatSpec برای نمایش یک پیام تأیید برای کاربر در زمان
188 | تعامل با قرارداد، همراه با درخواست مجوز برای امضای تراکنش استفاده کند. برای اطلاعات بیشتر، فرمت
189 | مشخصات :doc:`Ethereum Natural Language Specification (NatSpec) format ` را بخوانید.
190 |
191 |
192 |
193 | استفاده برای تأیید کد منبع
194 | ==================================
195 | به منظور تأیید کامپایل، منابع را می توان از IPFS/Swarm از طریق پیوند موجود در فایل فراداده بازیابی
196 | کرد. کامپایلر نسخه صحیح (که به عنوان بخشی از کامپایلرهای "رسمی" بررسی شده است) با تنظیمات
197 | مشخص شده روی آن ورودی فراخوانی می شود. بایت کد به دست آمده با داده های تراکنش ایجاد یا داده
198 | های آپکد ``CREATE`` مقایسه می شود که به طور خودکار ابرداده را تأیید می کند زیرا هش آن بخشی از بایت
199 | کد است. داده های اضافی مربوط به داده های ورودی سازنده است که باید با توجه به رابط رمزگشایی شده و
200 | به کاربر ارائه شود. در مخزن `sourcify `_
201 | (`npm package `_) می توانید کد نمونه ای را مشاهده کنید که نحوه
202 | استفاده از این ویژگی را نشان می دهد.
203 |
204 |
205 |
--------------------------------------------------------------------------------
/docs/060-breaking-changes.rst:
--------------------------------------------------------------------------------
1 | ********************************
2 | سالیدیتی v0.6.0 و تغییرات
3 | ********************************
4 |
5 | این بخش، تغییرات اصلی را که در سالیدیتی نسخه 0.6.0 معرفی شده است، به همراه استدلال پشت این
6 | تغییرات و نحوه بهروزرسانی کدهای تحت تأثیر، برجسته میکند. برای لیست کامل، `تغییرات انتشار `_ را بررسی
7 | کنید.
8 |
9 |
10 | تغییراتی که کامپایلر ممکن است در مورد آن هشدار ندهد
11 | ====================================================
12 |
13 | این بخش تغییراتی را لیست می کند که در آن رفتار کد شما ممکن است تغییر کند بدون اینکه کامپایلر در مورد
14 | آن به شما بگوید.
15 |
16 | * نوع حاصل از یک توان، نوع پایه است. قبلاً کوچکترین نوع بود که می تواند هم نوع پایه و هم نوع توان را
17 | مانند عملیات متقارن نگه دارد. علاوه بر این، انواع علامتدار برای پایه قدرت مجاز هستند.
18 |
19 | الزامات صراحت
20 | ==============
21 |
22 | این بخش تغییراتی را لیست میکند که کد اکنون باید واضحتر باشد، اما معنایی تغییر نمیکند. برای بیشتر
23 | موضوعات، کامپایلر پیشنهاداتی را ارائه می دهد.
24 |
25 | * اکنون فقط زمانی می توان توابع را لغو کرد که با کلمه کلیدی ``virtual`` علامت گذاری شده باشند یا در یک
26 | رابط تعریف شده باشند. توابع بدون پیاده سازی خارج از رابط باید ``virtual`` علامت گذاری شوند. هنگام نادیده
27 | گرفتن یک تابع یا اصلاح کننده، باید از کلمه کلیدی ``override`` استفاده شود. هنگام لغو یک تابع یا modifier
28 | تعریف شده در چندین پایه موازی، همه پایه ها باید در داخل پرانتز پس از کلمه کلیدی مانند این لیست شوند: ``override(Base1, Base2)``.
29 |
30 | * دسترسی اعضا به طول ``length`` آرایه ها اکنون همیشه فقط خواندنی است، حتی برای آرایه های ذخیره سازی. دیگر
31 | امکان تغییر اندازه آرایه های ذخیره سازی با اختصاص یک مقدار جدید به طول آنها وجود ندارد. به جای آن از
32 | ``push()``، ``push(value)`` یا ``pop()`` استفاده کنید یا یک آرایه کامل را اختصاص دهید که البته محتوای موجود را
33 | بازنویسی می کند. دلیل این امر جلوگیری از برخورد آرایه های ذخیره سازی بزرگ است.
34 |
35 | * برای علامت گذاری قراردادها به عنوان ``abstract`` می توان از کلمه کلیدی جدید abstract استفاده کرد. اگر
36 | قراردادی تمام وظایف خود را اجرا نکند، باید از آن استفاده شود. قراردادهای انتزاعی را نمی توان با استفاده
37 | از عملگر جدید ``new`` ایجاد کرد و امکان تولید بایت کد برای آنها در حین کامپایل وجود ندارد.
38 |
39 | * کتابخانه ها باید تمام وظایف خود را اجرا کنند، نه فقط کارهای داخلی.
40 |
41 | * نام متغیرهای اعلام شده در اسمبلی درون خطی ممکن است دیگر به ``_slot`` یا ``_offset`` ختم نشود.
42 |
43 | * اعلامیه های متغیر در assembly درون خطی ممکن است دیگر هیچ اعلان خارج از بلوک assembly درون
44 | خطی را تحت الشعاع قرار ندهند.
45 | اگر نام حاوی یک نقطه باشد، پیشوند آن تا نقطه ممکن است با هیچ اعلان
46 | خارج از بلوک اسمبلی درون خطی مغایرت نداشته باشد.
47 |
48 | * یک قرارداد مشتق شده فقط می تواند یک متغیر حالت ``x`` را اعلام کند، در صورتی که متغیر حالت قابل
49 | مشاهده با همان نام در هیچ یک از پایه های آن وجود نداشته باشد.
50 |
51 |
52 | تغییرات معنایی و نحوی
53 | ==============================
54 |
55 | این بخش تغییراتی را لیست می کند که در آن باید کد خود را تغییر دهید و پس از آن کار دیگری انجام می دهد.
56 |
57 | * تبدیل از انواع تابع خارجی به ``address`` اکنون مجاز نیست. در عوض انواع تابع خارجی دارای عضوی به نام ``address`` هستند که مشابه عضو انتخابگر ``selector`` موجود، است.
58 |
59 | * تابع ``push(value)`` برای آرایه های ذخیره سازی پویا دیگر طول جدید را بر نمی گرداند (هیچ چیز را برمی گرداند).
60 |
61 | * تابع بدون نام که معمولاً به عنوان "تابع فالبک" شناخته می شود به یک تابع بازگشتی جدید که با استفاده از کلمه کلیدی فالبک ``fallback`` و یک تابع دریافت اتر با استفاده از کلمه کلیدی دریافت ``receive`` تعریف می شود، تقسیم شد.
62 |
63 | * در صورت وجود، تابع دریافت اتر هر زمان که داده تماس(call) خالی باشد (چه اتر دریافت شود یا نه) فراخوانی می شود. این تابع به طور ضمنی قابل پرداخت ``payable`` است.
64 |
65 | * تابع فالبک یا همان فالبک فانکشن جدید زمانی فراخوانی می شود که هیچ تابع دیگری مطابقت نداشته باشد (اگر تابع دریافت اتر وجود نداشته باشد، این شامل تماس هایی با داده تماس خالی می شود). شما می توانید این تابع را قابل پرداخت یا همان ``payable`` کنید یا خیر. اگر ``payable`` نباشد، تراکنش هایی که با هیچ تابع دیگری که ارزشی ارسال نمی کند مطابقت ندارد، برگردانده می شود. اگر از الگوی ارتقا یا پروکسی پیروی می کنید، فقط باید تابع جدید بازگشتی یا همان فالبک را پیاده سازی کنید.
66 |
67 | ویژگیهای جدید
68 | ============
69 |
70 | این بخش مواردی را لیست می کند که قبل از سالیدیتی0.6.0 امکان پذیر نبودند یا دستیابی به آنها دشوارتر بود.
71 |
72 | * عبارت :ref:`try/catch ` به شما امکان می دهد در تماس های خارجی ناموفق واکنش نشان دهید.
73 |
74 | * ``struct`` and ``enum`` types can be declared at file level.
75 |
76 | * انواع ``struct`` و ``enum`` را می توان در سطح فایل اعلام کرد.
77 |
78 | * برش های آرایه را می توان برای آرایه های داده فراخوانی استفاده کرد، برای مثال ``abi.decode(msg.data[4:], (uint, uint))`` یک روش سطح پایین برای رمزگشایی بار فراخوانی تابع است.
79 |
80 | * Natspec از پارامترهای بازگشتی متعدد در اسناد توسعه دهنده پشتیبانی می کند و همان بررسی نامگذاری را به عنوان ``@param`` اعمال می کند.
81 |
82 | * Yul و Inline Assembly یک عبارت جدید به نام ترک ``leave`` دارند که از تابع فعلی خارج می شود.
83 |
84 | * تبدیل از ``address`` به ``address payable`` اکنون از طریق ``payable(x)`` امکان پذیر است، جایی که ``x`` باید از نوع ``address`` باشد.
85 |
86 |
87 | تغییرات رابط یا همان اینترفیس
88 | =================
89 |
90 | این بخش تغییراتی را لیست میکند که به خود زبان ارتباطی ندارند، اما روی رابطهای کامپایلر تأثیر دارند. اینها ممکن است نحوه استفاده از کامپایلر را
91 | در خط فرمان یا همان کامند لاین، نحوه استفاده از رابط قابل برنامه ریزی آن، یا نحوه تجزیه و تحلیل خروجی تولید شده توسط آن را تغییر دهند.
92 |
93 |
94 | گزارشگر خطای جدید
95 | ~~~~~~~~~~~~~~~~~~
96 |
97 | گزارشگر خطای جدیدی معرفی شد که هدف آن تولید پیام های خطا در دسترس تر در خط فرمان است. به طور پیش فرض فعال است، اما ارسال ``--old-reporter`` به گزارشگر خطای قدیمی منسوخ برمی گردد.
98 |
99 | گزینه های هش متادیتا
100 | ~~~~~~~~~~~~~~~~~~~~~
101 |
102 | کامپایلر اکنون هش `IPFS `_ فایل فراداده را بهطور پیشفرض به انتهای بایت کد اضافه میکند (برای جزئیات، مستندات مربوط به :doc:`contract metadata ` را ببینید). قبل از ورژن 0.6.0، کامپایلر هش سوارم `Swarm `_ را به طور پیشفرض اضافه میکرد و برای اینکه همچنان از این رفتار پشتیبانی
103 | کند، گزینه جدید خط فرمان ``--metadata-hash`` معرفی شد که به شما اجازه می دهد تا با ارسال ``ipfs`` یا ``swarm`` به عنوان مقدار به گزینه خط
104 | فرمان ``--metadata-hash`` هش مورد نظر برای تولید و الحاق را انتخاب کنید.
105 | ارسال مقدار ``none`` به طور کامل هش را حذف می کند.
106 |
107 |
108 | این تغییرات همچنین می تواند از طریق رابط :ref:`Standard JSON Interface` مورد استفاده قرار گیرد و فراداده JSON تولید شده توسط کامپایلر را تحت تأثیر قرار
109 | دهد.
110 |
111 |
112 |
113 | روش توصیه شده برای خواندن ابرداده خواندن دو بایت آخر برای تعیین طول رمزگذاری CBOR و انجام رمزگشایی مناسب روی آن بلوک داده همانطور که در بخش :ref:`metadata section` توضیح داده شده است.
114 |
115 |
116 | Yul Optimizer
117 | ~~~~~~~~~~~~~
118 |
119 | همراه با بهینه ساز بایت کد قدیمی، زمانی که کامپایلر را با ``--optimize`` فراخوانی می کنید، بهینه ساز :doc:`Yul ` به طور پیش فرض فعال می شود. با
120 | فراخوانی کامپایلر با ``--no-optimize-yul`` می توان آن را غیرفعال کرد. این حرکت بیشتر روی کدهایی که از کد ABI v2 استفاده می کنند تأثیر می
121 | گذارد.
122 |
123 |
124 | C API تغییرات
125 | ~~~~~~~~~~~~~
126 |
127 | کد کلاینت که از C API ``libsolc`` استفاده می کند، اکنون کنترل حافظه مورد استفاده توسط کامپایلر را در دست دارد. برای تطبیق این تغییر،
128 | ``solidity_free`` به solidity_reset تغییر نام داد، توابع ``solidity_alloc`` و ``solidity_free`` اضافه شدند و ``solidity_compile`` اکنون رشته یا
129 | استرینگی را برمیگرداند که باید صریحاً از طریق ``solidity_free()`` آزاد شود.
130 |
131 | The client code that uses the C API of ``libsolc`` is now in control of the memory used by the compiler. To make
132 | this change consistent, ``solidity_free`` was renamed to ``solidity_reset``, the functions ``solidity_alloc`` and
133 | ``solidity_free`` were added and ``solidity_compile`` now returns a string that must be explicitly freed via
134 | ``solidity_free()``.
135 |
136 |
137 | چگونه کد خود را به روز کنیم
138 | =======================
139 |
140 | این بخش دستورالعمل های دقیقی در مورد نحوه به روز رسانی کد قبلی برای هر تغییر شکسته ارائه می دهد.
141 |
142 | * ``address(f)`` را به ``f.address`` تغییر دهید زیرا ``f`` از نوع تابع خارجی است.
143 |
144 | * ``function () external [payable] { ... }`` را با ``receive() external payable { ... }`` ، ``fallback() external [payable] { ... }`` یا هر دو جایگزین کنید. در صورت امکان، فقط از یک تابع دریافت استفاده کنید.
145 |
146 | * تغییر ``uint length = array.push(value)`` به ``;array.push(value)`` . طول جدید از طریق ``array.length`` قابل دسترسی است.
147 |
148 | * برای افزایش ``array.length++`` به ``array.push()`` و برای کاهش طول آرایه ذخیره سازی از ``pop()`` استفاده کنید.
149 |
150 | * برای هر پارامتر بازگشتی نامگذاری شده در اسناد ``@dev`` یک تابع، یک ورودی ``@return`` تعریف کنید که حاوی نام پارامتر به عنوان اولین کلمه است. به عنوان مثال. اگر تابع ``f()`` تعریف شده است مانند ``function f() public returns (uint value)`` و یک ``@dev`` که آن را حاشیه نویسی می کند، پارامترهای بازگشتی آن را به این صورت مستند کنید: ``@return value The return value.`` . می توانید پارامترهای بازگشتی نامدار و نامگذاری نشده را ترکیب کنید. مستندات تا زمانی که اعلامیه ها به ترتیبی باشند که در نوع بازگشتی تاپلی ظاهر می شوند.
151 |
152 | * شناسههای منحصربهفرد را برای اعلانهای متغیر در مجموعه درون خطی انتخاب کنید که با اعلانهای خارج از بلوک اسمبلی درون خطی تضاد ندارند.
153 |
154 | * مجازی ``virtual`` را به هر تابع غیر رابطی که قصد لغو آن را دارید اضافه کنید. ``virtual`` را به همه توابع بدون اجرای رابط های خارجی اضافه کنید. برای وراثت تکی، به هر تابع نادیده ``override`` اضافه کنید. برای وراثت چندگانه، ``override(A, B, ..)`` را اضافه کنید، جایی که تمام قراردادهایی را که تابع لغو را در پرانتز تعریف می کنند، لیست می کنید. هنگامی که چندین پایه یک تابع را تعریف می کنند، قرارداد ارثی باید همه عملکردهای متضاد را لغو کند.
155 |
--------------------------------------------------------------------------------
/docs/_static/css/dark.css:
--------------------------------------------------------------------------------
1 | /* links */
2 |
3 | .rst-content a:not(:visited) {
4 | color: #aaddff !important;
5 | }
6 |
7 | /* code directives */
8 |
9 | .method dt,
10 | .class dt,
11 | .data dt,
12 | .attribute dt,
13 | .function dt,
14 | .classmethod dt,
15 | .exception dt,
16 | .descclassname,
17 | .descname {
18 | background-color: #2d2d2d !important;
19 | }
20 |
21 | .rst-content dl:not(.docutils) dt {
22 | color: #aaddff;
23 | background-color: #2d2d2d;
24 | border-top: solid 3px #525252;
25 | border-left: solid 3px #525252;
26 | }
27 |
28 | em.property {
29 | color: #888888;
30 | }
31 |
32 |
33 | /* tables */
34 |
35 | .rst-content table.docutils thead {
36 | color: #ddd;
37 | }
38 |
39 | .rst-content table.docutils td {
40 | border: 0px;
41 | }
42 |
43 | .rst-content table.docutils:not(.field-list) tr:nth-child(2n-1) td {
44 | background-color: #5a5a5a;
45 | }
46 |
47 | .rst-content pre {
48 | background: none;
49 | }
50 |
51 | /* inlined code highlights */
52 |
53 | .xref,
54 | .py-meth,
55 | .rst-content a code {
56 | color: #aaddff !important;
57 | font-weight: normal !important;
58 | }
59 |
60 | .rst-content code {
61 | color: #eee !important;
62 | font-weight: normal !important;
63 | }
64 |
65 | code.literal {
66 | background-color: #2d2d2d !important;
67 | border: 1px solid #6d6d6d !important;
68 | }
69 |
70 | code.docutils.literal.notranslate {
71 | color: #ddd;
72 | }
73 |
74 | /* highlight color search text */
75 |
76 | .rst-content .highlighted {
77 | background: #ff5722;
78 | box-shadow: 0 0 0 2px #f0978b;
79 | }
80 |
81 | /* notes, warnings, hints */
82 |
83 | .hint .admonition-title {
84 | background: #2aa87c !important;
85 | }
86 |
87 | .warning .admonition-title {
88 | background: #cc4444 !important;
89 | }
90 |
91 | .admonition-title {
92 | background: #3a7ca8 !important;
93 | }
94 |
95 | .admonition,
96 | .note {
97 | background-color: #2d2d2d !important;
98 | }
99 |
100 |
101 | /* table of contents */
102 |
103 | .wy-nav-content-wrap {
104 | background-color: rgba(0, 0, 0, 0.6) !important;
105 | }
106 |
107 | .sidebar {
108 | background-color: #191919 !important;
109 | }
110 |
111 | .sidebar-title {
112 | background-color: #2b2b2b !important;
113 | }
114 |
115 | .wy-menu-vertical a {
116 | color: #ddd;
117 | }
118 |
119 | .wy-menu-vertical code.docutils.literal.notranslate {
120 | color: #404040;
121 | background: none !important;
122 | border: none !important;
123 | }
124 |
125 | .wy-nav-content {
126 | background: #3c3c3c;
127 | color: #dddddd;
128 | }
129 |
130 | .wy-menu-vertical li.on a,
131 | .wy-menu-vertical li.current>a {
132 | background: #a3a3a3;
133 | border-bottom: 0px !important;
134 | border-top: 0px !important;
135 | }
136 |
137 | .wy-menu-vertical li.current {
138 | background: #b3b3b3;
139 | }
140 |
141 | .toc-backref {
142 | color: grey !important;
143 | }
144 |
145 | .highlight .hll {
146 | background-color: #49483e
147 | }
148 |
149 | .highlight {
150 | background: #222;
151 | color: #f8f8f2
152 | }
153 |
154 | .highlight .c {
155 | color: #888
156 | }
157 |
158 |
159 | /* Comment */
160 |
161 | .highlight .err {
162 | color: #960050;
163 | background-color: #1e0010
164 | }
165 |
166 |
167 | /* Error */
168 |
169 | .highlight .k {
170 | color: #66d9ef
171 | }
172 |
173 |
174 | /* Keyword */
175 |
176 | .highlight .l {
177 | color: #ae81ff
178 | }
179 |
180 |
181 | /* Literal */
182 |
183 | .highlight .n {
184 | color: #f8f8f2
185 | }
186 |
187 |
188 | /* Name */
189 |
190 | .highlight .o {
191 | color: #f92672
192 | }
193 |
194 |
195 | /* Operator */
196 |
197 | .highlight .p {
198 | color: #f8f8f2
199 | }
200 |
201 |
202 | /* Punctuation */
203 |
204 | .highlight .ch {
205 | color: #888
206 | }
207 |
208 |
209 | /* Comment.Hashbang */
210 |
211 | .highlight .cm {
212 | color: #888
213 | }
214 |
215 |
216 | /* Comment.Multiline */
217 |
218 | .highlight .cp {
219 | color: #888
220 | }
221 |
222 |
223 | /* Comment.Preproc */
224 |
225 | .highlight .cpf {
226 | color: #888
227 | }
228 |
229 |
230 | /* Comment.PreprocFile */
231 |
232 | .highlight .c1 {
233 | color: #888
234 | }
235 |
236 |
237 | /* Comment.Single */
238 |
239 | .highlight .cs {
240 | color: #888
241 | }
242 |
243 |
244 | /* Comment.Special */
245 |
246 | .highlight .gd {
247 | color: #f92672
248 | }
249 |
250 |
251 | /* Generic.Deleted */
252 |
253 | .highlight .ge {
254 | font-style: italic
255 | }
256 |
257 |
258 | /* Generic.Emph */
259 |
260 | .highlight .gi {
261 | color: #a6e22e
262 | }
263 |
264 |
265 | /* Generic.Inserted */
266 |
267 | .highlight .gs {
268 | font-weight: bold
269 | }
270 |
271 |
272 | /* Generic.Strong */
273 |
274 | .highlight .gu {
275 | color: #888
276 | }
277 |
278 |
279 | /* Generic.Subheading */
280 |
281 | .highlight .kc {
282 | color: #66d9ef
283 | }
284 |
285 |
286 | /* Keyword.Constant */
287 |
288 | .highlight .kd {
289 | color: #66d9ef
290 | }
291 |
292 |
293 | /* Keyword.Declaration */
294 |
295 | .highlight .kn {
296 | color: #f92672
297 | }
298 |
299 |
300 | /* Keyword.Namespace */
301 |
302 | .highlight .kp {
303 | color: #66d9ef
304 | }
305 |
306 |
307 | /* Keyword.Pseudo */
308 |
309 | .highlight .kr {
310 | color: #66d9ef
311 | }
312 |
313 |
314 | /* Keyword.Reserved */
315 |
316 | .highlight .kt {
317 | color: #66d9ef
318 | }
319 |
320 |
321 | /* Keyword.Type */
322 |
323 | .highlight .ld {
324 | color: #e6db74
325 | }
326 |
327 |
328 | /* Literal.Date */
329 |
330 | .highlight .m {
331 | color: #ae81ff
332 | }
333 |
334 |
335 | /* Literal.Number */
336 |
337 | .highlight .s {
338 | color: #e6db74
339 | }
340 |
341 |
342 | /* Literal.String */
343 |
344 | .highlight .na {
345 | color: #a6e22e
346 | }
347 |
348 |
349 | /* Name.Attribute */
350 |
351 | .highlight .nb {
352 | color: #f8f8f2
353 | }
354 |
355 |
356 | /* Name.Builtin */
357 |
358 | .highlight .nc {
359 | color: #a6e22e
360 | }
361 |
362 |
363 | /* Name.Class */
364 |
365 | .highlight .no {
366 | color: #66d9ef
367 | }
368 |
369 |
370 | /* Name.Constant */
371 |
372 | .highlight .nd {
373 | color: #a6e22e
374 | }
375 |
376 |
377 | /* Name.Decorator */
378 |
379 | .highlight .ni {
380 | color: #f8f8f2
381 | }
382 |
383 |
384 | /* Name.Entity */
385 |
386 | .highlight .ne {
387 | color: #a6e22e
388 | }
389 |
390 |
391 | /* Name.Exception */
392 |
393 | .highlight .nf {
394 | color: #a6e22e
395 | }
396 |
397 |
398 | /* Name.Function */
399 |
400 | .highlight .nl {
401 | color: #f8f8f2
402 | }
403 |
404 |
405 | /* Name.Label */
406 |
407 | .highlight .nn {
408 | color: #f8f8f2
409 | }
410 |
411 |
412 | /* Name.Namespace */
413 |
414 | .highlight .nx {
415 | color: #a6e22e
416 | }
417 |
418 |
419 | /* Name.Other */
420 |
421 | .highlight .py {
422 | color: #f8f8f2
423 | }
424 |
425 |
426 | /* Name.Property */
427 |
428 | .highlight .nt {
429 | color: #f92672
430 | }
431 |
432 |
433 | /* Name.Tag */
434 |
435 | .highlight .nv {
436 | color: #f8f8f2
437 | }
438 |
439 |
440 | /* Name.Variable */
441 |
442 | .highlight .ow {
443 | color: #f92672
444 | }
445 |
446 |
447 | /* Operator.Word */
448 |
449 | .highlight .w {
450 | color: #f8f8f2
451 | }
452 |
453 |
454 | /* Text.Whitespace */
455 |
456 | .highlight .mb {
457 | color: #ae81ff
458 | }
459 |
460 |
461 | /* Literal.Number.Bin */
462 |
463 | .highlight .mf {
464 | color: #ae81ff
465 | }
466 |
467 |
468 | /* Literal.Number.Float */
469 |
470 | .highlight .mh {
471 | color: #ae81ff
472 | }
473 |
474 |
475 | /* Literal.Number.Hex */
476 |
477 | .highlight .mi {
478 | color: #ae81ff
479 | }
480 |
481 |
482 | /* Literal.Number.Integer */
483 |
484 | .highlight .mo {
485 | color: #ae81ff
486 | }
487 |
488 |
489 | /* Literal.Number.Oct */
490 |
491 | .highlight .sa {
492 | color: #e6db74
493 | }
494 |
495 |
496 | /* Literal.String.Affix */
497 |
498 | .highlight .sb {
499 | color: #e6db74
500 | }
501 |
502 |
503 | /* Literal.String.Backtick */
504 |
505 | .highlight .sc {
506 | color: #e6db74
507 | }
508 |
509 |
510 | /* Literal.String.Char */
511 |
512 | .highlight .dl {
513 | color: #e6db74
514 | }
515 |
516 |
517 | /* Literal.String.Delimiter */
518 |
519 | .highlight .sd {
520 | color: #e6db74
521 | }
522 |
523 |
524 | /* Literal.String.Doc */
525 |
526 | .highlight .s2 {
527 | color: #e6db74
528 | }
529 |
530 |
531 | /* Literal.String.Double */
532 |
533 | .highlight .se {
534 | color: #ae81ff
535 | }
536 |
537 |
538 | /* Literal.String.Escape */
539 |
540 | .highlight .sh {
541 | color: #e6db74
542 | }
543 |
544 |
545 | /* Literal.String.Heredoc */
546 |
547 | .highlight .si {
548 | color: #e6db74
549 | }
550 |
551 |
552 | /* Literal.String.Interpol */
553 |
554 | .highlight .sx {
555 | color: #e6db74
556 | }
557 |
558 |
559 | /* Literal.String.Other */
560 |
561 | .highlight .sr {
562 | color: #e6db74
563 | }
564 |
565 |
566 | /* Literal.String.Regex */
567 |
568 | .highlight .s1 {
569 | color: #e6db74
570 | }
571 |
572 |
573 | /* Literal.String.Single */
574 |
575 | .highlight .ss {
576 | color: #e6db74
577 | }
578 |
579 |
580 | /* Literal.String.Symbol */
581 |
582 | .highlight .bp {
583 | color: #f8f8f2
584 | }
585 |
586 |
587 | /* Name.Builtin.Pseudo */
588 |
589 | .highlight .fm {
590 | color: #a6e22e
591 | }
592 |
593 |
594 | /* Name.Function.Magic */
595 |
596 | .highlight .vc {
597 | color: #f8f8f2
598 | }
599 |
600 |
601 | /* Name.Variable.Class */
602 |
603 | .highlight .vg {
604 | color: #f8f8f2
605 | }
606 |
607 |
608 | /* Name.Variable.Global */
609 |
610 | .highlight .vi {
611 | color: #f8f8f2
612 | }
613 |
614 |
615 | /* Name.Variable.Instance */
616 |
617 | .highlight .vm {
618 | color: #f8f8f2
619 | }
620 |
621 |
622 | /* Name.Variable.Magic */
623 |
624 | .highlight .il {
625 | color: #ae81ff
626 | }
627 |
628 |
629 | /* Literal.Number.Integer.Long */
630 |
631 |
632 | /* Link to Remix IDE shown over code snippets */
633 | a.remix-link {
634 | filter: invert(1); /* The icon is black. In dark mode we want it white. */
635 | }
636 |
--------------------------------------------------------------------------------
/docs/natspec-format.rst:
--------------------------------------------------------------------------------
1 | .. _natspec:
2 |
3 | ##############
4 | NatSpec Format
5 | ##############
6 |
7 | Solidity contracts can use a special form of comments to provide rich
8 | documentation for functions, return variables and more. This special form is
9 | named the Ethereum Natural Language Specification Format (NatSpec).
10 |
11 | .. note::
12 |
13 | NatSpec was inspired by `Doxygen `_.
14 | While it uses Doxygen-style comments and tags, there is no intention to keep
15 | strict compatibility with Doxygen. Please carefully examine the supported tags
16 | listed below.
17 |
18 | This documentation is segmented into developer-focused messages and end-user-facing
19 | messages. These messages may be shown to the end user (the human) at the
20 | time that they will interact with the contract (i.e. sign a transaction).
21 |
22 | It is recommended that Solidity contracts are fully annotated using NatSpec for
23 | all public interfaces (everything in the ABI).
24 |
25 | NatSpec includes the formatting for comments that the smart contract author will
26 | use, and which are understood by the Solidity compiler. Also detailed below is
27 | output of the Solidity compiler, which extracts these comments into a machine-readable
28 | format.
29 |
30 | NatSpec may also include annotations used by third-party tools. These are most likely
31 | accomplished via the ``@custom:`` tag, and a good use case is analysis and verification
32 | tools.
33 |
34 | .. _header-doc-example:
35 |
36 | Documentation Example
37 | =====================
38 |
39 | Documentation is inserted above each ``contract``, ``interface``,
40 | ``function``, and ``event`` using the Doxygen notation format.
41 | A ``public`` state variable is equivalent to a ``function``
42 | for the purposes of NatSpec.
43 |
44 | - For Solidity you may choose ``///`` for single or multi-line
45 | comments, or ``/**`` and ending with ``*/``.
46 |
47 | - For Vyper, use ``"""`` indented to the inner contents with bare
48 | comments. See the `Vyper
49 | documentation `__.
50 |
51 | The following example shows a contract and a function using all available tags.
52 |
53 | .. note::
54 |
55 | The Solidity compiler only interprets tags if they are external or
56 | public. You are welcome to use similar comments for your internal and
57 | private functions, but those will not be parsed.
58 |
59 | This may change in the future.
60 |
61 | .. code-block:: Solidity
62 |
63 | // SPDX-License-Identifier: GPL-3.0
64 | pragma solidity >=0.8.2 < 0.9.0;
65 |
66 | /// @title A simulator for trees
67 | /// @author Larry A. Gardner
68 | /// @notice You can use this contract for only the most basic simulation
69 | /// @dev All function calls are currently implemented without side effects
70 | /// @custom:experimental This is an experimental contract.
71 | contract Tree {
72 | /// @notice Calculate tree age in years, rounded up, for live trees
73 | /// @dev The Alexandr N. Tetearing algorithm could increase precision
74 | /// @param rings The number of rings from dendrochronological sample
75 | /// @return Age in years, rounded up for partial years
76 | function age(uint256 rings) external virtual pure returns (uint256) {
77 | return rings + 1;
78 | }
79 |
80 | /// @notice Returns the amount of leaves the tree has.
81 | /// @dev Returns only a fixed number.
82 | function leaves() external virtual pure returns(uint256) {
83 | return 2;
84 | }
85 | }
86 |
87 | contract Plant {
88 | function leaves() external virtual pure returns(uint256) {
89 | return 3;
90 | }
91 | }
92 |
93 | contract KumquatTree is Tree, Plant {
94 | function age(uint256 rings) external override pure returns (uint256) {
95 | return rings + 2;
96 | }
97 |
98 | /// Return the amount of leaves that this specific kind of tree has
99 | /// @inheritdoc Tree
100 | function leaves() external override(Tree, Plant) pure returns(uint256) {
101 | return 3;
102 | }
103 | }
104 |
105 | .. _header-tags:
106 |
107 | Tags
108 | ====
109 |
110 | All tags are optional. The following table explains the purpose of each
111 | NatSpec tag and where it may be used. As a special case, if no tags are
112 | used then the Solidity compiler will interpret a ``///`` or ``/**`` comment
113 | in the same way as if it were tagged with ``@notice``.
114 |
115 | =============== ====================================================================================== =============================
116 | Tag Context
117 | =============== ====================================================================================== =============================
118 | ``@title`` A title that should describe the contract/interface contract, library, interface
119 | ``@author`` The name of the author contract, library, interface
120 | ``@notice`` Explain to an end user what this does contract, library, interface, function, public state variable, event
121 | ``@dev`` Explain to a developer any extra details contract, library, interface, function, state variable, event
122 | ``@param`` Documents a parameter just like in Doxygen (must be followed by parameter name) function, event
123 | ``@return`` Documents the return variables of a contract's function function, public state variable
124 | ``@inheritdoc`` Copies all missing tags from the base function (must be followed by the contract name) function, public state variable
125 | ``@custom:...`` Custom tag, semantics is application-defined everywhere
126 | =============== ====================================================================================== =============================
127 |
128 | If your function returns multiple values, like ``(int quotient, int remainder)``
129 | then use multiple ``@return`` statements in the same format as the ``@param`` statements.
130 |
131 | Custom tags start with ``@custom:`` and must be followed by one or more lowercase letters or hyphens.
132 | It cannot start with a hyphen however. They can be used everywhere and are part of the developer documentation.
133 |
134 | .. _header-dynamic:
135 |
136 | Dynamic expressions
137 | -------------------
138 |
139 | The Solidity compiler will pass through NatSpec documentation from your Solidity
140 | source code to the JSON output as described in this guide. The consumer of this
141 | JSON output, for example the end-user client software, may present this to the end-user directly or it may apply some pre-processing.
142 |
143 | For example, some client software will render:
144 |
145 | .. code:: Solidity
146 |
147 | /// @notice This function will multiply `a` by 7
148 |
149 | to the end-user as:
150 |
151 | .. code:: text
152 |
153 | This function will multiply 10 by 7
154 |
155 | if a function is being called and the input ``a`` is assigned a value of 10.
156 |
157 | Specifying these dynamic expressions is outside the scope of the Solidity
158 | documentation and you may read more at
159 | `the radspec project `__.
160 |
161 | .. _header-inheritance:
162 |
163 | Inheritance Notes
164 | -----------------
165 |
166 | Functions without NatSpec will automatically inherit the documentation of their
167 | base function. Exceptions to this are:
168 |
169 | * When the parameter names are different.
170 | * When there is more than one base function.
171 | * When there is an explicit ``@inheritdoc`` tag which specifies which contract should be used to inherit.
172 |
173 | .. _header-output:
174 |
175 | Documentation Output
176 | ====================
177 |
178 | When parsed by the compiler, documentation such as the one from the
179 | above example will produce two different JSON files. One is meant to be
180 | consumed by the end user as a notice when a function is executed and the
181 | other to be used by the developer.
182 |
183 | If the above contract is saved as ``ex1.sol`` then you can generate the
184 | documentation using:
185 |
186 | .. code::
187 |
188 | solc --userdoc --devdoc ex1.sol
189 |
190 | And the output is below.
191 |
192 | .. note::
193 | Starting Solidity version 0.6.11 the NatSpec output also contains a ``version`` and a ``kind`` field.
194 | Currently the ``version`` is set to ``1`` and ``kind`` must be one of ``user`` or ``dev``.
195 | In the future it is possible that new versions will be introduced, deprecating older ones.
196 |
197 | .. _header-user-doc:
198 |
199 | User Documentation
200 | ------------------
201 |
202 | The above documentation will produce the following user documentation
203 | JSON file as output:
204 |
205 | .. code::
206 |
207 | {
208 | "version" : 1,
209 | "kind" : "user",
210 | "methods" :
211 | {
212 | "age(uint256)" :
213 | {
214 | "notice" : "Calculate tree age in years, rounded up, for live trees"
215 | }
216 | },
217 | "notice" : "You can use this contract for only the most basic simulation"
218 | }
219 |
220 | Note that the key by which to find the methods is the function's
221 | canonical signature as defined in the :ref:`Contract
222 | ABI ` and not simply the function's
223 | name.
224 |
225 | .. _header-developer-doc:
226 |
227 | Developer Documentation
228 | -----------------------
229 |
230 | Apart from the user documentation file, a developer documentation JSON
231 | file should also be produced and should look like this:
232 |
233 | .. code::
234 |
235 | {
236 | "version" : 1,
237 | "kind" : "dev",
238 | "author" : "Larry A. Gardner",
239 | "details" : "All function calls are currently implemented without side effects",
240 | "custom:experimental" : "This is an experimental contract.",
241 | "methods" :
242 | {
243 | "age(uint256)" :
244 | {
245 | "details" : "The Alexandr N. Tetearing algorithm could increase precision",
246 | "params" :
247 | {
248 | "rings" : "The number of rings from dendrochronological sample"
249 | },
250 | "return" : "age in years, rounded up for partial years"
251 | }
252 | },
253 | "title" : "A simulator for trees"
254 | }
255 |
--------------------------------------------------------------------------------
/docs/080-breaking-changes.rst:
--------------------------------------------------------------------------------
1 | ********************************
2 | Solidity v0.8.0 Breaking Changes
3 | ********************************
4 |
5 | This section highlights the main breaking changes introduced in Solidity
6 | version 0.8.0.
7 | For the full list check
8 | `the release changelog `_.
9 |
10 | Silent Changes of the Semantics
11 | ===============================
12 |
13 | This section lists changes where existing code changes its behaviour without
14 | the compiler notifying you about it.
15 |
16 | * Arithmetic operations revert on underflow and overflow. You can use ``unchecked { ... }`` to use
17 | the previous wrapping behaviour.
18 |
19 | Checks for overflow are very common, so we made them the default to increase readability of code,
20 | even if it comes at a slight increase of gas costs.
21 |
22 | * ABI coder v2 is activated by default.
23 |
24 | You can choose to use the old behaviour using ``pragma abicoder v1;``.
25 | The pragma ``pragma experimental ABIEncoderV2;`` is still valid, but it is deprecated and has no effect.
26 | If you want to be explicit, please use ``pragma abicoder v2;`` instead.
27 |
28 | Note that ABI coder v2 supports more types than v1 and performs more sanity checks on the inputs.
29 | ABI coder v2 makes some function calls more expensive and it can also make contract calls
30 | revert that did not revert with ABI coder v1 when they contain data that does not conform to the
31 | parameter types.
32 |
33 | * Exponentiation is right associative, i.e., the expression ``a**b**c`` is parsed as ``a**(b**c)``.
34 | Before 0.8.0, it was parsed as ``(a**b)**c``.
35 |
36 | This is the common way to parse the exponentiation operator.
37 |
38 | * Failing assertions and other internal checks like division by zero or arithmetic overflow do
39 | not use the invalid opcode but instead the revert opcode.
40 | More specifically, they will use error data equal to a function call to ``Panic(uint256)`` with an error code specific
41 | to the circumstances.
42 |
43 | This will save gas on errors while it still allows static analysis tools to distinguish
44 | these situations from a revert on invalid input, like a failing ``require``.
45 |
46 | * If a byte array in storage is accessed whose length is encoded incorrectly, a panic is caused.
47 | A contract cannot get into this situation unless inline assembly is used to modify the raw representation of storage byte arrays.
48 |
49 | * If constants are used in array length expressions, previous versions of Solidity would use arbitrary precision
50 | in all branches of the evaluation tree. Now, if constant variables are used as intermediate expressions,
51 | their values will be properly rounded in the same way as when they are used in run-time expressions.
52 |
53 | * The type ``byte`` has been removed. It was an alias of ``bytes1``.
54 |
55 | New Restrictions
56 | ================
57 |
58 | This section lists changes that might cause existing contracts to not compile anymore.
59 |
60 | * There are new restrictions related to explicit conversions of literals. The previous behaviour in
61 | the following cases was likely ambiguous:
62 |
63 | 1. Explicit conversions from negative literals and literals larger than ``type(uint160).max`` to
64 | ``address`` are disallowed.
65 | 2. Explicit conversions between literals and an integer type ``T`` are only allowed if the literal
66 | lies between ``type(T).min`` and ``type(T).max``. In particular, replace usages of ``uint(-1)``
67 | with ``type(uint).max``.
68 | 3. Explicit conversions between literals and enums are only allowed if the literal can
69 | represent a value in the enum.
70 | 4. Explicit conversions between literals and ``address`` type (e.g. ``address(literal)``) have the
71 | type ``address`` instead of ``address payable``. One can get a payable address type by using an
72 | explicit conversion, i.e., ``payable(literal)``.
73 |
74 | * :ref:`Address literals` have the type ``address`` instead of ``address
75 | payable``. They can be converted to ``address payable`` by using an explicit conversion, e.g.
76 | ``payable(0xdCad3a6d3569DF655070DEd06cb7A1b2Ccd1D3AF)``.
77 |
78 | * There are new restrictions on explicit type conversions. The conversion is only allowed when there
79 | is at most one change in sign, width or type-category (``int``, ``address``, ``bytesNN``, etc.).
80 | To perform multiple changes, use multiple conversions.
81 |
82 | Let us use the notation ``T(S)`` to denote the explicit conversion ``T(x)``, where, ``T`` and
83 | ``S`` are types, and ``x`` is any arbitrary variable of type ``S``. An example of such a
84 | disallowed conversion would be ``uint16(int8)`` since it changes both width (8 bits to 16 bits)
85 | and sign (signed integer to unsigned integer). In order to do the conversion, one has to go
86 | through an intermediate type. In the previous example, this would be ``uint16(uint8(int8))`` or
87 | ``uint16(int16(int8))``. Note that the two ways to convert will produce different results e.g.,
88 | for ``-1``. The following are some examples of conversions that are disallowed by this rule.
89 |
90 | - ``address(uint)`` and ``uint(address)``: converting both type-category and width. Replace this by
91 | ``address(uint160(uint))`` and ``uint(uint160(address))`` respectively.
92 | - ``payable(uint160)``, ``payable(bytes20)`` and ``payable(integer-literal)``: converting both
93 | type-category and state-mutability. Replace this by ``payable(address(uint160))``,
94 | ``payable(address(bytes20))`` and ``payable(address(integer-literal))`` respectively. Note that
95 | ``payable(0)`` is valid and is an exception to the rule.
96 | - ``int80(bytes10)`` and ``bytes10(int80)``: converting both type-category and sign. Replace this by
97 | ``int80(uint80(bytes10))`` and ``bytes10(uint80(int80)`` respectively.
98 | - ``Contract(uint)``: converting both type-category and width. Replace this by
99 | ``Contract(address(uint160(uint)))``.
100 |
101 | These conversions were disallowed to avoid ambiguity. For example, in the expression ``uint16 x =
102 | uint16(int8(-1))``, the value of ``x`` would depend on whether the sign or the width conversion
103 | was applied first.
104 |
105 | * Function call options can only be given once, i.e. ``c.f{gas: 10000}{value: 1}()`` is invalid and has to be changed to ``c.f{gas: 10000, value: 1}()``.
106 |
107 | * The global functions ``log0``, ``log1``, ``log2``, ``log3`` and ``log4`` have been removed.
108 |
109 | These are low-level functions that were largely unused. Their behaviour can be accessed from inline assembly.
110 |
111 | * ``enum`` definitions cannot contain more than 256 members.
112 |
113 | This will make it safe to assume that the underlying type in the ABI is always ``uint8``.
114 |
115 | * Declarations with the name ``this``, ``super`` and ``_`` are disallowed, with the exception of
116 | public functions and events. The exception is to make it possible to declare interfaces of contracts
117 | implemented in languages other than Solidity that do permit such function names.
118 |
119 | * Remove support for the ``\b``, ``\f``, and ``\v`` escape sequences in code.
120 | They can still be inserted via hexadecimal escapes, e.g. ``\x08``, ``\x0c``, and ``\x0b``, respectively.
121 |
122 | * The global variables ``tx.origin`` and ``msg.sender`` have the type ``address`` instead of
123 | ``address payable``. One can convert them into ``address payable`` by using an explicit
124 | conversion, i.e., ``payable(tx.origin)`` or ``payable(msg.sender)``.
125 |
126 | This change was done since the compiler cannot determine whether or not these addresses
127 | are payable or not, so it now requires an explicit conversion to make this requirement visible.
128 |
129 | * Explicit conversion into ``address`` type always returns a non-payable ``address`` type. In
130 | particular, the following explicit conversions have the type ``address`` instead of ``address
131 | payable``:
132 |
133 | - ``address(u)`` where ``u`` is a variable of type ``uint160``. One can convert ``u``
134 | into the type ``address payable`` by using two explicit conversions, i.e.,
135 | ``payable(address(u))``.
136 | - ``address(b)`` where ``b`` is a variable of type ``bytes20``. One can convert ``b``
137 | into the type ``address payable`` by using two explicit conversions, i.e.,
138 | ``payable(address(b))``.
139 | - ``address(c)`` where ``c`` is a contract. Previously, the return type of this
140 | conversion depended on whether the contract can receive Ether (either by having a receive
141 | function or a payable fallback function). The conversion ``payable(c)`` has the type ``address
142 | payable`` and is only allowed when the contract ``c`` can receive Ether. In general, one can
143 | always convert ``c`` into the type ``address payable`` by using the following explicit
144 | conversion: ``payable(address(c))``. Note that ``address(this)`` falls under the same category
145 | as ``address(c)`` and the same rules apply for it.
146 |
147 | * The ``chainid`` builtin in inline assembly is now considered ``view`` instead of ``pure``.
148 |
149 | * Unary negation cannot be used on unsigned integers anymore, only on signed integers.
150 |
151 | Interface Changes
152 | =================
153 |
154 | * The output of ``--combined-json`` has changed: JSON fields ``abi``, ``devdoc``, ``userdoc`` and
155 | ``storage-layout`` are sub-objects now. Before 0.8.0 they used to be serialised as strings.
156 |
157 | * The "legacy AST" has been removed (``--ast-json`` on the commandline interface and ``legacyAST`` for standard JSON).
158 | Use the "compact AST" (``--ast-compact--json`` resp. ``AST``) as replacement.
159 |
160 | * The old error reporter (``--old-reporter``) has been removed.
161 |
162 |
163 | How to update your code
164 | =======================
165 |
166 | - If you rely on wrapping arithmetic, surround each operation with ``unchecked { ... }``.
167 | - Optional: If you use SafeMath or a similar library, change ``x.add(y)`` to ``x + y``, ``x.mul(y)`` to ``x * y`` etc.
168 | - Add ``pragma abicoder v1;`` if you want to stay with the old ABI coder.
169 | - Optionally remove ``pragma experimental ABIEncoderV2`` or ``pragma abicoder v2`` since it is redundant.
170 | - Change ``byte`` to ``bytes1``.
171 | - Add intermediate explicit type conversions if required.
172 | - Combine ``c.f{gas: 10000}{value: 1}()`` to ``c.f{gas: 10000, value: 1}()``.
173 | - Change ``msg.sender.transfer(x)`` to ``payable(msg.sender).transfer(x)`` or use a stored variable of ``address payable`` type.
174 | - Change ``x**y**z`` to ``(x**y)**z``.
175 | - Use inline assembly as a replacement for ``log0``, ..., ``log4``.
176 | - Negate unsigned integers by subtracting them from the maximum value of the type and adding 1 (e.g. ``type(uint256).max - x + 1``, while ensuring that `x` is not zero)
177 |
--------------------------------------------------------------------------------