├── CMakeLists.txt ├── README.md └── docs ├── 050-breaking-changes.rst ├── 060-breaking-changes.rst ├── 070-breaking-changes.rst ├── 080-breaking-changes.rst ├── Makefile ├── _build └── doctrees │ ├── 050-breaking-changes.doctree │ └── 060-breaking-changes.doctree ├── _static ├── css │ ├── custom.css │ ├── dark.css │ └── toggle.css ├── img │ └── solid-share-arrow.svg └── js │ └── toggle.js ├── _templates ├── footer.html ├── layout.html └── versions.html ├── abi-spec.rst ├── analysing-compilation-output.rst ├── assembly.rst ├── brand-guide.rst ├── bugs.json ├── bugs.rst ├── bugs_by_version.json ├── cheatsheet.rst ├── common-patterns.rst ├── conf.py ├── contracts.rst ├── contracts ├── abstract-contracts.rst ├── constant-state-variables.rst ├── creating-contracts.rst ├── errors.rst ├── events.rst ├── function-modifiers.rst ├── functions.rst ├── inheritance.rst ├── interfaces.rst ├── libraries.rst ├── using-for.rst └── visibility-and-getters.rst ├── contributing.rst ├── control-structures.rst ├── credits-and-attribution.rst ├── examples ├── blind-auction.rst ├── micropayment.rst ├── modular.rst ├── safe-remote.rst └── voting.rst ├── ext ├── html_extra_template_renderer.py └── remix_code_links.py ├── grammar.rst ├── grammar ├── SolidityLexer.g4 └── SolidityParser.g4 ├── index.rst ├── installing-solidity.rst ├── internals ├── layout_in_calldata.rst ├── layout_in_memory.rst ├── layout_in_storage.rst ├── optimizer.rst ├── source_mappings.rst └── variable_cleanup.rst ├── introduction-to-smart-contracts.rst ├── ir └── ir-breaking-changes.rst ├── language-influences.rst ├── layout-of-source-files.rst ├── logo.svg ├── make.bat ├── metadata.rst ├── natspec-format.rst ├── path-resolution.rst ├── requirements.txt ├── resources.rst ├── robots.txt.template ├── security-considerations.rst ├── smtchecker.rst ├── solidity-by-example.rst ├── structure-of-a-contract.rst ├── style-guide.rst ├── types.rst ├── types ├── conversion.rst ├── mapping-types.rst ├── operators.rst ├── reference-types.rst └── value-types.rst ├── units-and-global-variables.rst ├── using-the-compiler.rst └── yul.rst /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/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/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/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 | -------------------------------------------------------------------------------- /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/_build/doctrees/050-breaking-changes.doctree: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/solidity-docs/fa-persian/aedc0907fd45ab940f4f1201ef825d37bf7278dc/docs/_build/doctrees/050-breaking-changes.doctree -------------------------------------------------------------------------------- /docs/_build/doctrees/060-breaking-changes.doctree: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/solidity-docs/fa-persian/aedc0907fd45ab940f4f1201ef825d37bf7278dc/docs/_build/doctrees/060-breaking-changes.doctree -------------------------------------------------------------------------------- /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/_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/_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/_static/img/solid-share-arrow.svg: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /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/footer.html: -------------------------------------------------------------------------------- 1 | {% extends "!footer.html" %} 2 | 3 | {% block extrafooter %} 4 |

5 | Credits and attribution. 6 |

7 | {% endblock %} 8 | -------------------------------------------------------------------------------- /docs/_templates/layout.html: -------------------------------------------------------------------------------- 1 | {% extends "!layout.html" %} 2 | 3 | {% block menu %} 4 | {{ super() }} 5 | 10 | {% endblock %} 11 | -------------------------------------------------------------------------------- /docs/_templates/versions.html: -------------------------------------------------------------------------------- 1 | {# Add rst-badge after rst-versions for small badge style. #} 2 |
3 | 4 | RTD 5 | 6 | 7 | 8 | 9 | 10 | 11 | v: {{ current_version }} 12 | 13 | 14 |
15 |
16 |
{{ _('Versions') }}
{% for slug, url in versions %} 17 |
{{ slug }}
18 | {% endfor %} 19 |
20 |
21 |
{{ _('Downloads') }}
{% for type, url in downloads %} 22 |
{{ type }}
23 | {% endfor %} 24 |
25 |
26 | {# Translators: The phrase "Read the Docs" is not translated #} 27 |
{{ _('On Read the Docs') }}
28 |
29 | {{ _('Project Home') }} 30 |
31 |
32 | {{ _('Builds') }} 33 |
34 |
35 |
36 |
-------------------------------------------------------------------------------- /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/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/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.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/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/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. -------------------------------------------------------------------------------- /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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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 | 7 | Vector 1 8 | Created with Sketch. 9 | 10 | 11 | 12 | 14 | 16 | 18 | 20 | 22 | 24 | 25 | 26 | 27 | 28 | -------------------------------------------------------------------------------- /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/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/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/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/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/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/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/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/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/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/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 | --------------------------------------------------------------------------------