├── .github ├── pull_request_template.md └── workflows │ └── main.yml ├── .prettierrc.json ├── CONTRIBUTING.md ├── LICENSE ├── README.md └── current ├── advanced ├── block-import.md ├── codec.md ├── consensus.md ├── cryptography.md ├── executor.md ├── ss58-address-format.md └── storage.md ├── assets ├── 16b213f-Screenshot_from_2019-01-11_16-29-09.png ├── consensus-ghost.png ├── consensus-longest-chain.png ├── file-hash.png ├── forks.png ├── frame-arch.png ├── front-end-template-balance-transfer.png ├── front-end-template.png ├── off-chain-workers-v1.png ├── off-chain-workers-v2.png ├── poe-claimed.png ├── poe-component.png ├── private-network-apps-insert-key.png ├── private-network-apps-keygen.png ├── private-network-no-blocks.png ├── runtime.png ├── substrate-listener.png └── technical-freedom.png ├── config.json ├── contribute └── help-translate.md ├── getting-started ├── glossary.md ├── index.md └── windows-users.md ├── integrate ├── chain-spec.md ├── libraries.md ├── polkadot-js.md └── subkey.md ├── learn-substrate ├── account-abstractions.md ├── extrinsics.md ├── index.md ├── off-chain-workers.md ├── session-keys.md ├── tx-pool.md └── weight.md ├── runtime ├── debugging.md ├── events.md ├── execution.md ├── fees.md ├── frame.md ├── index.md ├── macros.md ├── metadata.md ├── off-chain-workers.md ├── origin.md ├── pallets.md ├── primitives.md ├── storage.md └── tests.md └── smart-contracts ├── contracts-pallet.md ├── env-types.md ├── evm-pallet.md ├── faq.md ├── index.md ├── ink-development.md ├── ink-fundamentals.md └── overview.md /.github/pull_request_template.md: -------------------------------------------------------------------------------- 1 | Thank you for making a PR to the knowledge base. Please make sure it follows these short guidelines: 2 | 3 | - [ ] Are the audience and objective of the document clear? 4 | - [ ] Is the writing: 5 | - **Clear**: All jargon defined, explained, or linked to. Best to avoid it. 6 | - **Precise**: No ambiguous meanings 7 | - **Concise**: Free of superfluous detail 8 | - [ ] Does it follow our [style guide](/CONTRIBUTING.md#documentation-style)? 9 | - [ ] If this is a new page, does the PR include the appropriate infrastructure, e.g. adding the 10 | page to a sidebar? 11 | - [ ] Build the page. Does it render properly? E.g. no funny lists or formatting. 12 | - [ ] Links should go to rustdocs or devhub articles, not source code. 13 | - [ ] If this PR addresses an issue in the queue, have you referenced it in the description? 14 | -------------------------------------------------------------------------------- /.github/workflows/main.yml: -------------------------------------------------------------------------------- 1 | name: Build App 2 | 3 | on: 4 | push: 5 | branches: 6 | - master 7 | 8 | jobs: 9 | build: 10 | runs-on: ubuntu-latest 11 | 12 | steps: 13 | - name: Run a one-line script 14 | uses: peter-evans/repository-dispatch@v1 15 | with: 16 | token: ${{ secrets.ACCESS_TOKEN }} 17 | repository: paritytech/substrate.io 18 | event-type: content-update 19 | client-payload: '{"ref": "${{ github.ref }}", "sha": "${{ github.sha }}"}' 20 | -------------------------------------------------------------------------------- /.prettierrc.json: -------------------------------------------------------------------------------- 1 | { 2 | "printWidth": 100, 3 | "proseWrap": "always" 4 | } 5 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contribution Guidelines 2 | 3 | If you are interested in contributing to Substrate Documentation, please follow these contribution 4 | guidelines. 5 | 6 | - [PR Checklist](#pr-checklist) 7 | - [Documentation Standards](#documentation-standards) 8 | - [Documentation Style](#documentation-style) 9 | 10 | ## PR Checklist 11 | 12 | - [ ] Are the audience and objective of the document clear? E.g. a document for developers that 13 | should teach them about transaction fees. 14 | - [ ] Is the writing: 15 | - **Clear**: All jargon defined, explained, or linked to. Best to avoid it. 16 | - **Precise**: No ambiguous meanings 17 | - **Concise**: Free of superfluous detail 18 | - [ ] Does it follow our [style guide](#documentation-style)? 19 | - [ ] If this is a new page, does the PR include the appropriate infrastructure, e.g. adding the 20 | page to a sidebar? 21 | - [ ] Did you run Prettier by executing `npx prettier --write .` in the project root? 22 | - [ ] Build the page. Does it render properly? E.g. no funny lists or formatting. 23 | - [ ] Links should go to rustdocs or devhub articles, not source code. 24 | - [ ] If this PR addresses an issue in the queue, have you referenced it in the description? 25 | 26 | ## Documentation Standards 27 | 28 | A document about what to document and how to document it for people who create things that need 29 | documentation. 30 | 31 | ### Why document? 32 | 33 | Substrate is a new framework for building blockchains. Effective documentation allows new people to 34 | join and grow the project by having all necessary information. 35 | 36 | ### Who is the audience? 37 | 38 | The documentation described here is intended to address a technical audience, i.e. those who expect 39 | to implement or exercise APIs or understand the internal dynamics of the blockchain system. These 40 | standards are not intended for end-user product documentation. 41 | 42 | The knowledge base houses instructions, conceptual overviews, and procedural documentation for 43 | developers who are working on Substrate. This directory includes documentation on how to get 44 | started, build, run, and test Substrate. You should organize the content that you create by specific 45 | activities, such as testing, getting started, or by workflow topic. 46 | 47 | ### What should I document? 48 | 49 | Document protocols, introduce essential concepts, and explain how everything fits together. 50 | 51 | - Conventions: e.g. this document about documentation, code style 52 | - System Design: e.g. subsystems, consensus, runtime, block format, assumptions 53 | - APIs: e.g. JSON-RPC, runtime functions 54 | - Protocols: e.g. schemas, encodings, configuration files 55 | - Tools: e.g. `subkey`, `build-spec`, `purge-chain` 56 | - Workflows: e.g. environment set up, test methodologies, where to find various parts, how to get 57 | work done 58 | 59 | ### What documentation style guidelines should I follow? 60 | 61 | It is important to follow documentation style guidelines to ensure that the documentation created by 62 | a large number of contributors can flow together. See 63 | [Documentation Style Guide](#documentation-style). 64 | 65 | ### How can I link to other docs in my documentation? 66 | 67 | Use absolute paths starting with `/` and ending with `.md`, like `/overview/getting-started.md`. 68 | 69 | ### How can I link to source code in my documentation? 70 | 71 | Use the rust-docs to link to specific parts of the Substrate source code, for example a module's 72 | `trait`. When referencing specific lines of code, copy those lines into the documentation. 73 | 74 | DO NOT link to specific lines of code -- Substrate changes often and links that reference specific 75 | locations in the code become inaccurate fast and are not easily maintainable. 76 | 77 | **Showing code can make an abstract idea concrete. It is not, however, a shortcut to writing a clear 78 | explanation about how something works.** 79 | 80 | ## Documentation Style 81 | 82 | It is important to create documentation that follows similar guidelines. This allows documentation 83 | to be clear and concise while allowing users to easily find necessary information. 84 | 85 | ### Substrate-Specific Style 86 | 87 | This section is for terminology specifically related to Substrate. 88 | 89 | - **WebAssembly:** It's "WebAssembly" or "Wasm". 90 | 91 | - **FRAME, Pallets, and Modules:** A module is a generic term for a piece of software that expresses 92 | domain-specific logic. A pallet is a special type of module that is meant to operate in the 93 | context of FRAME. FRAME is a system that provides the abstractions necessary for building a 94 | runtime on the Substrate client. If you don't know if you should call something a module or a 95 | pallet, check its `Cargo.toml` file for its name; pallets have a `pallet-*` prefix. 96 | 97 | - **Capitalization:** 98 | - Substrate is always capitalized. 99 | - Pallet names are capitalized, e.g. the Balances pallet. 100 | 101 | ### General Style 102 | 103 | These are style guidelines that can help create clearer documentation. For anything not addessed 104 | here, use 105 | [The Economist](https://bordeure.files.wordpress.com/2008/11/the-economist-style-guide.pdf). 106 | 107 | - **Write in plain U.S. English.** You should write in plain U.S. English and try to avoid 108 | complicated words when you describe something. 109 | 110 | - **Except for quotation marks.** Follow The Economist's guidance. 111 | 112 | - Use single ones only for quotations within quotations. 113 | - If the quotation does not include any punctuation, the closing quotation marks should precede 114 | any punctuation that the sentence requires. 115 | - If a quoted section would naturally end with a period or comma, put the punctuation mark inside 116 | the quotation mark. 117 | 118 | - **Avoid using pronouns such as "I" or "we".** These can be quite ambiguous when someone reads the 119 | documentation. It is OK to use "you" as this allows the documentation to speak to a user. 120 | 121 | - **Know your relative pronouns.** 122 | 123 | - "That" introduces a restrictive clause. It isn't preceded by a comma. 124 | - "Which" introduces a nonrestrictive clause and is preceded by a comma. 125 | - Quick tip that works 90% of the time: Every time you write "which", put a comma in front of it 126 | and see if it makes sense. If it does, then leave the comma. If it doesn't, change it to "that". 127 | - See: https://www.quickanddirtytips.com/education/grammar/which-versus-that 128 | 129 | - **If you plan on using acronyms, you should define them the first time you write about them.** For 130 | example, looks good to me (LGTM). Don't assume that everyone will understand all acronyms. You do 131 | not need to define acronyms that might be considered industry standards such as TCP/IP. 132 | 133 | - **In most cases, avoid future tense.** Words such as "will" are very ambiguous. For example "you 134 | will see" can lead to questions such as "when will I see this?". In 1 minute or in 20 minutes? In 135 | most cases, assume that when someone reads the documentation you are sitting next to them and 136 | reading the instructions to them. 137 | 138 | - **Use active voice.** You should always try to write in the active voice since passive voice can 139 | make sentences very ambiguous and hard to understand. There are very few cases where you should 140 | use the passive voice for technical documentation. 141 | 142 | - Active voice - the subject performs the action denoted by the verb. 143 | 144 | - "The operating system runs a process." This sentence answers the question on what is happening 145 | and who/what is performing the action. 146 | 147 | - Passive voice - the subject is no longer _active_, but is, instead, being acted upon by the 148 | verb - or passive. 149 | 150 | - "A process is being run." This sentence is unclear about who or what is running the process. 151 | You might consider "a process is run by the operating system", but the object of the action is 152 | still made into the subject of the sentence, which indicates passive voice. Passive voice 153 | tends to be wordier than active voice, which can make your sentence unclear. 154 | 155 | - **Do not list future plans for a product/feature.** "In the future, the product will have no 156 | bugs." This leads to the question as to when this would happen, but most importantly this is not 157 | something that anyone can guarantee will actually happen. 158 | 159 | - **Do not talk about how certain features work behind the covers unless it is absolutely 160 | necessary.** Always ask yourself, "Is this text necessary to understand this concept or to get 161 | through these instructions?" This also leads to shorter (less maintenance) and more concise 162 | (happier readers) documentation. 163 | 164 | - **Avoid using uncommon words, highly technical words, or jargon that users might not understand.** 165 | Also, avoid using idioms such as "that's the way the cookie crumbles". While it might make sense 166 | to you, it may not translate well into another language. Keep in mind that a lot of users are 167 | non-native English speakers. 168 | 169 | - **Use compound words correctly.** Use the compound words that give the correct meaning. For 170 | example, "set up" (verb) and "setup" (noun) have different meanings. 171 | 172 | - **Avoid using words such as "best" or "great" since these are all relative terms.** How can you 173 | prove that "this operating system is the best?" 174 | 175 | - **Avoid referencing proprietary information.** This can refer to any potential terminology or 176 | product names that may be trademarked or any internal information (API keys, machine names, etc…). 177 | 178 | - **Avoid starting a sentence with "this" since it is unclear what "this" references.** 179 | 180 | - For example: "The operating system is fast and efficient. This is what makes it well designed." 181 | Does "this" refer to fast, efficient, or operating system? Consider using: "The operating system 182 | is well designed because it is fast and efficient." 183 | 184 | - **Avoid ambiguous pronouns.** Pronouns are generally evil and not to be trusted. When you use 185 | "it", "they", "them", etc., make sure it is 100% clear what the pronoun refers to. Always err on 186 | the side of re-writing the noun. Example: "The cat crept down the stairs towards the mouse, and it 187 | shrieked." The cat or the mouse? 188 | 189 | - **Keep sentences short and concrete.** Using punctuation allows your reader to follow instructions 190 | or concepts. If by the time you read the last word of your sentence, you can't remember how the 191 | sentence started, it is probably too long. Also, short sentences are much easier to translate 192 | correctly. 193 | 194 | - **Know your audience.** It is good practice to know your audience before you write documentation. 195 | Your audience can be, for example, developers, end-users, integrators, etc. and they can have 196 | varying degrees of expertise and knowledge about a specific topic. Knowing your audience allows 197 | you to understand what information your audience should be familiar with. When a document is meant 198 | for a more advanced audience, it is best practice to state it up front and let the user know 199 | prerequisites before reading your document. 200 | 201 | - **Adverbs are evil.** Using an adverb is almost always a sign that you haven't done enough work to 202 | set the correct context. You should try using a different verb or setting more context. 203 | 204 | - **Do not use exclamation marks.** Some newspaper editors only let their writers use one 205 | exclamation mark _per year._ Just remove it, and you will see that the sentence is better. 206 | 207 | - **Use markdown.** You must create documentation in markdown (.md). 208 | 209 | - **Use Prettier.** [Prettier](https://prettier.io/) is a tool that can be used to ensure consistent 210 | formatting of markdown files. This repository includes 211 | [a Prettier config file](./.prettierrc.json) and you should run Prettier on the entire repo before 212 | submitting any changes. Prettier is distributed as an [NPM](https://www.npmjs.com/) package, so 213 | you can either install it globally or run it on-the-fly using `npx`. Here is an example that 214 | demonstrates the latter option: 215 | 216 | ``` 217 | npx prettier --write . 218 | ``` 219 | 220 | - **Be respectful** 221 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity authorized by 13 | the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works 101 | that You distribute, all copyright, patent, trademark, and 102 | attribution notices from the Source form of the Work, 103 | excluding those notices that do not pertain to any part of 104 | the Derivative Works; and 105 | 106 | (d) If the Work includes a "NOTICE" text file as part of its 107 | distribution, then any Derivative Works that You distribute must 108 | include a readable copy of the attribution notices contained 109 | within such NOTICE file, excluding those notices that do not 110 | pertain to any part of the Derivative Works, in at least one 111 | of the following places: within a NOTICE text file distributed 112 | as part of the Derivative Works; within the Source form or 113 | documentation, if provided along with the Derivative Works; or, 114 | within a display generated by the Derivative Works, if and 115 | wherever such third-party notices normally appear. The contents 116 | of the NOTICE file are for informational purposes only and 117 | do not modify the License. You may add Your own attribution 118 | notices within Derivative Works that You distribute, alongside 119 | or as an addendum to the NOTICE text from the Work, provided 120 | that such additional attribution notices cannot be construed 121 | as modifying the License. 122 | 123 | You may add Your own copyright statement to Your modifications and 124 | may provide additional or different license terms and conditions 125 | for use, reproduction, or distribution of Your modifications, or 126 | for any such Derivative Works as a whole, provided Your use, 127 | reproduction, and distribution of the Work otherwise complies with 128 | the conditions stated in this License. 129 | 130 | 5. Submission of Contributions. Unless You explicitly state otherwise, 131 | any Contribution intentionally submitted for inclusion in the Work 132 | by You to the Licensor shall be under the terms and conditions of 133 | this License, without any additional terms or conditions. 134 | Notwithstanding the above, nothing herein shall supersede or modify 135 | the terms of any separate license agreement you may have executed 136 | with Licensor regarding such Contributions. 137 | 138 | 6. Trademarks. This License does not grant permission to use the trade 139 | names, trademarks, service marks, or product names of the Licensor, 140 | except as required for reasonable and customary use in describing the 141 | origin of the Work and reproducing the content of the NOTICE file. 142 | 143 | 7. Disclaimer of Warranty. Unless required by applicable law or 144 | agreed to in writing, Licensor provides the Work (and each 145 | Contributor provides its Contributions) on an "AS IS" BASIS, 146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 147 | implied, including, without limitation, any warranties or conditions 148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 149 | PARTICULAR PURPOSE. You are solely responsible for determining the 150 | appropriateness of using or redistributing the Work and assume any 151 | risks associated with Your exercise of permissions under this License. 152 | 153 | 8. Limitation of Liability. In no event and under no legal theory, 154 | whether in tort (including negligence), contract, or otherwise, 155 | unless required by applicable law (such as deliberate and grossly 156 | negligent acts) or agreed to in writing, shall any Contributor be 157 | liable to You for damages, including any direct, indirect, special, 158 | incidental, or consequential damages of any character arising as a 159 | result of this License or out of the use or inability to use the 160 | Work (including but not limited to damages for loss of goodwill, 161 | work stoppage, computer failure or malfunction, or any and all 162 | other commercial damages or losses), even if such Contributor 163 | has been advised of the possibility of such damages. 164 | 165 | 9. Accepting Warranty or Additional Liability. While redistributing 166 | the Work or Derivative Works thereof, You may choose to offer, 167 | and charge a fee for, acceptance of support, warranty, indemnity, 168 | or other liability obligations and/or rights consistent with this 169 | License. However, in accepting such obligations, You may act only 170 | on Your own behalf and on Your sole responsibility, not on behalf 171 | of any other Contributor, and only if You agree to indemnify, 172 | defend, and hold each Contributor harmless for any liability 173 | incurred by, or claims asserted against, such Contributor by reason 174 | of your accepting any such warranty or additional liability. 175 | 176 | END OF TERMS AND CONDITIONS 177 | 178 | APPENDIX: How to apply the Apache License to your work. 179 | 180 | To apply the Apache License to your work, attach the following 181 | boilerplate notice, with the fields enclosed by brackets "[]" 182 | replaced with your own identifying information. (Don't include 183 | the brackets!) The text should be enclosed in the appropriate 184 | comment syntax for the file format. We also recommend that a 185 | file or class name and description of purpose be included on the 186 | same "printed page" as the copyright notice for easier 187 | identification within third-party archives. 188 | 189 | Copyright [yyyy] [name of copyright owner] 190 | 191 | Licensed under the Apache License, Version 2.0 (the "License"); 192 | you may not use this file except in compliance with the License. 193 | You may obtain a copy of the License at 194 | 195 | http://www.apache.org/licenses/LICENSE-2.0 196 | 197 | Unless required by applicable law or agreed to in writing, software 198 | distributed under the License is distributed on an "AS IS" BASIS, 199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 200 | See the License for the specific language governing permissions and 201 | limitations under the License. 202 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Substrate Knowledge Base 2 | 3 | The Knowledge Base is live on [substrate.io](https://www.substrate.io/). The Knowledge Base empowers developers to make informed design decisions so they can make the most of Substrate and its robust vast set of flexible, powerful capabilities. 4 | 5 | This repository holds documentation that goes in the Substrate Knowledge Base. The main website is 6 | hosted in [substrate-cms](https://github.com/substrate-developer-hub/substrate-cms). 7 | 8 | If you have feedback or suggestions for improvement, please don't keep quiet about it. You can contact us [via our Riot channels](https://riot.im/app/#/room/#watercooler:matrix.parity.io) or drop a pull request. 9 | 10 | ## Structure 11 | 12 | All docs are written in markdown format. The most up-to-date docs are in the `current` folder, while 13 | supporting figures and images go in the `assets` folder. 14 | 15 | ## Contributing 16 | 17 | Feel free to add an issue if there is documentation that you'd like to see. See the 18 | [contributing guide](https://github.com/substrate-developer-hub/knowledge-base/blob/master/CONTRIBUTING.md) 19 | for guidance on making PRs. 20 | 21 | ## Directory Structure 22 | 23 | The knowledge base has six main categories. These are not meant to be a table of contents or imposed 24 | order in which to read documentation, but rather groups of articles within the same context and for 25 | similar audiences. 26 | 27 | 1. **Getting Started:** Entry-level documentation. For example dependencies, installation, key 28 | terms. 29 | 1. **Learn Substrate:** Conceptual documentation. Articles about assumptions, key concepts, and 30 | design decisions in Substrate that will help you make educated decisions about developing your 31 | chain. 32 | 1. **Runtime:** Documentation that goes more in-depth and covers topics specific to runtime 33 | development like macros, storage, fees, and pallet architecture. 34 | 1. **Smart Contracts:** A section dedicated to smart contracts on Substrate. 35 | 1. **Integrate:** Documentation about integrating and interacting with your chain for node 36 | operation, key management, and front-end development. 37 | 1. **Advanced:** Sometimes you need more details than just the abstraction. The Advanced section 38 | contains information about encoding/decoding, consensus, cryptography, etc. 39 | 40 | ## License 41 | 42 | All documentation is under the 43 | [Apache 2 License](https://github.com/substrate-developer-hub/knowledge-base/blob/master/LICENSE). 44 | -------------------------------------------------------------------------------- /current/advanced/block-import.md: -------------------------------------------------------------------------------- 1 | --- 2 | slug: block-import 3 | lang: en 4 | title: The Block Import Pipeline 5 | --- 6 | 7 | ## The Import Queue 8 | 9 | The import queue is an abstract worker queue present in every Substrate node. It is not part of the 10 | runtime. The import queue is responsible for processing pieces of incoming information, verifying 11 | them, and if valid, importing the information into the node's state. The most fundamental piece of 12 | information that the import queue processes is blocks themselves. It is also responsible for 13 | importing consensus-related messages such as justifications or in light clients finality proofs. 14 | 15 | The import queue collects incoming elements from the network and stores them in a pool. The elements 16 | are later checked for validity and discarded if they are not valid. Elements that are valid are then 17 | imported into the node's local state. 18 | 19 | The import queue is codified abstractly in Substrate by means of the 20 | [`ImportQueue` trait](https://crates.parity.io/sp_consensus/import_queue/trait.ImportQueue.html). 21 | The use of a trait allows each consensus engine to provide its own specialized implementation of the 22 | import queue, which may take advantage of optimization opportunities such as verifying multiple 23 | blocks in parallel as they come in across the network. 24 | 25 | The import queue also provides some hooks via the 26 | [`Link` trait](https://crates.parity.io/sp_consensus/import_queue/trait.Link.html) that can be used 27 | to follow its progress. 28 | 29 | ## The Basic Queue 30 | 31 | Substrate provides a default in-memory implementation of the `ImportQueue` known as the 32 | [`BasicQueue`](https://crates.parity.io/sp_consensus/import_queue/struct.BasicQueue.html). The 33 | `BasicQueue` does not do any kind of optimization, rather it performs the verification and import 34 | steps sequentially. It does, however, abstract the notion of verification through the use of the 35 | [`Verifier`](https://crates.parity.io/sp_consensus/import_queue/trait.Verifier.html) trait. 36 | 37 | Any consensus engine that relies on the `BasicQueue` must implement the `Verifier` trait. The 38 | `Verifier` is typically responsible for tasks such as checking 39 | [inherent data](https://www.substrate.io/kb/learn-substrate/extrinsics#inherents), and ensuring that 40 | the block is signed by the appropriate authority. 41 | 42 | ## The Block Import Trait 43 | 44 | When the import queue is ready to import a block, it passes the block in question to a method 45 | provided by the 46 | [`BlockImport` trait](https://crates.parity.io/sp_consensus/block_import/trait.BlockImport.html). 47 | This `BlockImport` trait provides the behavior of importing a block into the node's local state 48 | database. 49 | 50 | One implementer of the `BlockImport` trait that is used in every Substrate node is the 51 | [`Client`](https://crates.parity.io/sc_service/client/index.html), which contains the node's entire 52 | block database. When a block is imported into the client, it is added to the main database of blocks 53 | that the node knows about. 54 | 55 | ## The Block Import Pipeline 56 | 57 | In the simplest cases, blocks are imported directly into the client. But most consensus engines will 58 | need to perform additional verification on incoming blocks, update their own local auxiliary 59 | databases, or perform both. To allow consensus engines to execute this, it is common to wrap the client in 60 | another struct that also implements `BlockImport`. This nesting leads to the term "block import 61 | pipeline". 62 | 63 | An example of this wrapping is the 64 | [`PowBlockImport`](https://crates.parity.io/sc_consensus_pow/struct.PowBlockImport.html), which 65 | holds a reference to another type that also implements `BlockImport`. This allows the PoW consensus 66 | engine to do its own import-related bookkeeping and then pass the block to the nested `BlockImport`, 67 | probably the client. This pattern is also demonstrated in 68 | [`AuraBlockImport`](https://crates.parity.io/sc_consensus_aura/struct.AuraBlockImport.html), 69 | [`BabeBlockImport`](https://crates.parity.io/sc_consensus_babe/struct.BabeBlockImport.html), and 70 | [`GrandpaBlockImport`](https://crates.parity.io/sc_finality_grandpa/struct.GrandpaBlockImport.html). 71 | 72 | `BlockImport` nesting need not be limited to one level. In fact, it is common for nodes that use 73 | both an authoring engine and a finality gadget to layer the nesting even more deeply. For example, 74 | Polkadot's block import pipeline consists of a `BabeBlockImport`, which wraps a 75 | `GrandpaBlockImport`, which wraps the `Client`. 76 | 77 | ## Learn More 78 | 79 | Several of the Recipes' nodes demonstrate the block import pipeline: 80 | 81 | - [Manual Seal](https://substrate.dev/recipes/3-entrees/manual-seal.html) - all blocks are valid so 82 |   the block import pipeline is just the client 83 | - [Basic PoW](https://substrate.dev/recipes/3-entrees/basic-pow.html) - the import pipeline includes 84 |   PoW and the client 85 | - [Hybrid Consensus](https://substrate.dev/recipes/3-entrees/hybrid-consensus.html) - the import 86 |   pipeline is PoW, then Grandpa, then the client 87 | -------------------------------------------------------------------------------- /current/advanced/codec.md: -------------------------------------------------------------------------------- 1 | --- 2 | slug: codec 3 | lang: en 4 | title: SCALE Codec 5 | --- 6 | 7 | The SCALE (Simple Concatenated Aggregate Little-Endian) is a lightweight, efficient, binary 8 | serialization and deserialization codec. SCALE allows encoding and decoding of data. It is highly suitable for resource-constrained execution environments like blockchain runtimes and resource-constrained execution contexts, like the [Substrate runtime](/current/runtime/index.md). It is not 9 | self-describing in any way and assumes the decoding context has all type knowledge about the encoded data. 10 | 11 | ## SCALE for Substrate 12 | 13 | Substrate uses the [`parity-scale-codec`](https://github.com/paritytech/parity-scale-codec), a Rust 14 | implementation of the SCALE Codec. This library and the SCALE codec are advantageous for Substrate 15 | and blockchain systems because: 16 | 17 | - It is lightweight relative to generic serialization frameworks like [serde](https://serde.rs/), 18 | which adds a significant boilerplate that can bloat the size of the binary. 19 | - It does not use Rust STD, and thus can compile to Wasm for the Substrate runtime. 20 | - It is built to have great support in Rust for deriving codec logic for new types: 21 | ``` 22 | #[derive(Encode, Decode)] 23 | ``` 24 | 25 | It is important to define the encoding scheme used on Substrate rather than reuse an existing Rust 26 | codec library because this codec needs to be re-implemented on other platforms and languages that 27 | want to support interoperability. 28 | 29 | ## Codec Definition 30 | 31 | Here you will find how the SCALE codec encodes different types. 32 | 33 | ### Fixed-width Integers 34 | 35 | Basic integers are encoded using a fixed-width little-endian (LE) format. 36 | 37 | #### Example 38 | 39 | - `signed 8-bit integer 69`: `0x45` 40 | - `unsigned 16-bit integer 42`: `0x2a00` 41 | - `unsigned 32-bit integer 16777215`: `0xffffff00` 42 | 43 | ### Compact/General Integers 44 | 45 | A "compact" or general integer encoding is sufficient for encoding large integers (up to 2\*\*536) 46 | and is more efficient at encoding most values than the fixed-width version. (Though for single-byte 47 | values, the fixed-width integer is never worse.) 48 | 49 | It is encoded with the two least significant bits denoting the mode: 50 | 51 | - `0b00`: single-byte mode; upper six bits are the LE encoding of the value (valid only for values 52 | of 0-63). 53 | - `0b01`: two-byte mode: upper six bits and the following byte is the LE encoding of the value 54 | (valid only for values `64-(2**14-1)`). 55 | - `0b10`: four-byte mode: upper six bits and the following three bytes are the LE encoding of the 56 | value (valid only for values `(2**14-1)-(2**30-1)`). 57 | - `0b11`: Big-integer mode: The upper six bits are the number of bytes following, less four. The 58 | value is contained, LE encoded, in the bytes following. The final (most significant) byte must be 59 | non-zero. Valid only for values `(2**30-1)-(2**536-1)`. 60 | 61 | #### Example 62 | 63 | - `unsigned integer 0`: `0x00` 64 | - `unsigned integer 1`: `0x04` 65 | - `unsigned integer 42`: `0xa8` 66 | - `unsigned integer 69`: `0x1501` 67 | 68 | Error: 69 | 70 | - ~~`0x0100`: Zero encoded in mode 1~~ 71 | 72 | ### Boolean 73 | 74 | Boolean values are encoded using the least significant bit of a single byte. 75 | 76 | #### Example 77 | 78 | - `boolean false`: `0x00` 79 | - `boolean true`: `0x01` 80 | 81 | ### Options 82 | 83 | One or zero values of a particular type. Encoded as: 84 | 85 | - `0x00` if it is `None` ("empty" or "null"). 86 | - `0x01` followed by the encoded value if it is `Some`. 87 | 88 | As an exception, in the case that the type is a boolean, then it is always one byte: 89 | 90 | - `0x00` if it is `None` ("empty" or "null"). 91 | - `0x01` if it is the `false` value. 92 | - `0x02` if it is the `true` value. 93 | 94 | ### Results 95 | 96 | Results are commonly used enumerations which indicate whether certain operations were successful or unsuccessful. Encoded as: 97 | 98 | - `0x00` if the operation was successful, followed by the encoded value. 99 | - `0x01` if the operation was unsuccessful, followed by the encoded error. 100 | 101 | #### Example 102 | 103 | ```rust 104 | // A custom result type used in a crate. 105 | let Result = std::result::Result; 106 | ``` 107 | 108 | - `Ok(42)`: `0x002a` 109 | - `Err(false)`: `0x0100` 110 | 111 | ### Vectors (lists, series, sets) 112 | 113 | A collection of same-typed values is encoded, prefixed with a _compact_ encoding of the number of 114 | items, followed by each item's encoding concatenated in turn. 115 | 116 | #### Example 117 | 118 | Vector of unsigned 16-bit integers: 119 | 120 | ``` 121 | [4, 8, 15, 16, 23, 42] 122 | ``` 123 | 124 | SCALE Bytes: 125 | 126 | ``` 127 | 0x18040008000f00100017002a00 128 | ``` 129 | 130 | ### Strings 131 | 132 | Strings are Vectors containing a valid UTF8 sequence. 133 | 134 | ### Tuples 135 | 136 | A fixed-size series of values, each with a possibly different but predetermined and fixed type. This 137 | is simply the concatenation of each encoded value. 138 | 139 | #### Example 140 | 141 | Tuple of compact unsigned integer and boolean: 142 | 143 | `(3, false)`: `0x0c00` 144 | 145 | ### Data Structures 146 | 147 | For structures, the values are named, but that is irrelevant for the encoding (names are ignored - 148 | only order matters). **All containers store elements consecutively. The order of the elements is not 149 | fixed, depends on the container, and cannot be relied on at decoding.** 150 | 151 | This implicitly means that decoding some byte-array into a specified structure that enforces an 152 | order and then re-encoding it could result in a different byte array than the original that was 153 | decoded. 154 | 155 | #### Example 156 | 157 | Imagine a `SortedVecAsc` structure that always has byte-elements in ascending order and you have 158 | `[3, 5, 2, 8]`, where the first element is the number of bytes following (i.e. `[3, 5, 2]` would be 159 | invalid). 160 | 161 | `SortedVecAsc::from([3, 5, 2, 8])` would decode to `[3, 2, 5, 8]`, which does not match the original 162 | encoding. 163 | 164 | ### Enumerations (tagged-unions) 165 | 166 | A fixed number of variants, each mutually exclusive and potentially implying a further value or 167 | series of values. 168 | 169 | Encoded as the first byte identifying the index of the variant that the value is. Any further bytes 170 | are used to encode any data that the variant implies. Thus, no more than 256 variants are supported. 171 | 172 | #### Example 173 | 174 | ```rust 175 | enum IntOrBool { 176 | Int(u8), 177 | Bool(bool), 178 | } 179 | ``` 180 | 181 | - `Int(42)`: `0x002a` 182 | - `Bool(true)`: `0x0101` 183 | 184 | ## Implementations 185 | 186 | The Parity SCALE Codec is currently implemented for: 187 | 188 | - Rust: [`paritytech/parity-scale-codec`](https://github.com/paritytech/parity-scale-codec) 189 | - Python: [`polkascan/py-scale-codec`](https://github.com/polkascan/py-scale-codec) 190 | - Golang: [`ChainSafe/gossamer`](https://github.com/ChainSafe/gossamer) 191 | - C++: [`soramitsu/scale`](https://github.com/soramitsu/kagome/tree/master/core/scale) 192 | - JavaScript: [`polkadot-js/api`](https://github.com/polkadot-js/api) 193 | 194 | 195 | ### References 196 | 197 | - Visit the reference docs for the 198 | [`parity-scale-codec`](https://crates.parity.io/parity_scale_codec/index.html). 199 | 200 | - Visit the auxiliary encoding section of the 201 | [Polkadot runtime environment specification](https://github.com/w3f/polkadot-spec/blob/master/runtime-environment-spec/polkadot_re_spec.pdf). 202 | -------------------------------------------------------------------------------- /current/advanced/consensus.md: -------------------------------------------------------------------------------- 1 | --- 2 | slug: consensus 3 | lang: en 4 | title: Consensus 5 | --- 6 | 7 | Blockchain nodes use consensus engines to agree on the blockchain's state. This article covers the 8 | fundamentals of consensus in blockchain systems, how consensus interacts with the runtime in the 9 | Substrate framework, and the consensus engines available with the framework. 10 | 11 | ## State Machines and Conflicts 12 | 13 | A blockchain runtime is a [state machine](https://en.wikipedia.org/wiki/Finite-state_machine). It 14 | has some internal state, and state transition function that allows it to transition from its current 15 | state to a future state. In most runtimes there are states that have valid transitions to multiple 16 | future states, but a single transition must be selected. 17 | 18 | Blockchains must agree on: 19 | 20 | - Some initial state, called "genesis", 21 | - A series of state transitions, each called a "block", and 22 | - A final (current) state. 23 | 24 | In order to agree on the resulting state after a transition, all operations within a blockchain's 25 | [state transition function](../runtime/index) must be deterministic. 26 | 27 | ## Conflict Exclusion 28 | 29 | In centralized systems, the central authority defines mutually exclusive alternatives by 30 | recording state transitions in the order it sees them, and choosing the first of the competing 31 | alternatives when a conflict arises. In decentralized systems, the nodes will see transactions in 32 | different orders, and thus they must use a more elaborate method to exclude transactions. As a 33 | further complication, blockchain networks strive to be fault tolerant, which means that they should 34 | continue to provide consistent data even if some participants are not following the rules. 35 | 36 | Blockchains batch transactions into blocks and have defined methodologies to select which participants have the 37 | right to submit a block. For example, in a proof-of-work chain, the node that finds a valid proof of 38 | work first has the right to submit a block to the chain. 39 | 40 | Substrate provides several block construction algorithms and also allows you to create your own: 41 | 42 | - Aura (round robin) 43 | - BABE (slot-based) 44 | - Proof of Work 45 | 46 | ## Fork Choice Rules 47 | 48 | As a primitive, a block contains a header and a batch of 49 | [extrinsics](../learn-substrate/extrinsics). The header must contain a reference to its parent block 50 | such that one can trace the chain to its genesis. Forks occur when two blocks reference the same 51 | parent. Forks must be resolved such that only one, canonical chain exists. 52 | 53 | A fork choice rule is an algorithm that takes a blockchain and selects the "best" chain, and thus 54 | the one that should be extended. Substrate exposes this concept through the 55 | [`SelectChain` Trait](https://crates.parity.io/sp_consensus/trait.SelectChain.html). 56 | 57 | Substrate allows you to write a custom fork choice rule, or use one that comes out of the box. For 58 | example: 59 | 60 | ### Longest Chain Rule 61 | 62 | The longest chain rule simply says that the best chain is the longest chain. Substrate provides this 63 | chain selection rule with the 64 | [`LongestChain` struct](https://crates.parity.io/sc_consensus/struct.LongestChain.html). 65 | GRANDPA uses the longest chain rule for voting. 66 | 67 | ![longest chain rule](../assets/consensus-longest-chain.png) 68 | 69 | ### GHOST Rule 70 | 71 | The Greedy Heaviest Observed SubTree rule says that, starting at the genesis block, each fork is 72 | resolved by choosing the branch that has the most blocks built on it recursively. 73 | 74 | ![GHOST rule](../assets/consensus-ghost.png) 75 | 76 | ## Block Production 77 | 78 | Some nodes in a blockchain network are able to produce new blocks, a process known as authoring. 79 | Exactly which nodes may author blocks depends on which consensus engine you're using. In a 80 | centralized network, a single node might author all the blocks, whereas in a completely 81 | permissionless network, an algorithm must select the block author at each height. 82 | 83 | ### Proof of Work 84 | 85 | In proof-of-work systems like Bitcoin, any node may produce a block at any time, so long as it has 86 | solved a computationally-intensive problem. Solving the problem takes CPU time, and thus miners can 87 | only produce blocks in proportion with their computing resources. Substrate provides a proof-of-work 88 | block production engine. 89 | 90 | ### Slots 91 | 92 | Slot-based consensus algorithms must have a known set of validators who are permitted to produce 93 | blocks. Time is divided up into discrete slots, and during each slot only some of the validators may 94 | produce a block. The specifics of which validators can author blocks during each slot vary from 95 | engine to engine. Substrate provides Aura and Babe, both of which are slot-based block authoring 96 | engines. 97 | 98 | ## Finality 99 | 100 | Users in any system want to know when their transactions are finalized, and blockchain is no 101 | different. In some traditional systems, finality happens when a receipt is handed over, or papers 102 | are signed. 103 | 104 | Using the block authoring schemes and fork choice rules described so far, transactions are never 105 | entirely finalized. There is always a chance that a longer (or heavier) chain will come along and 106 | revert your transaction. However, the more blocks are built on top of a particular block, the less 107 | likely it is to ever be reverted. In this way, block authoring along with a proper fork choice rule 108 | provides probabilistic finality. 109 | 110 | When deterministic finality is desired, a finality gadget can be added to the blockchain's logic. 111 | Members of a fixed authority set cast finality votes, and when enough votes have been cast for a 112 | certain block, the block is deemed final. In most systems, this threshold is 2/3. Blocks that have 113 | been finalized by such a gadget cannot be reverted without external coordination such as a hard 114 | fork. 115 | 116 | > Some consensus systems couple block production and finality, as in, finalization is part of the 117 | > block production process and a new block `N+1` cannot be authored until block `N` is finalize. 118 | > Substrate, however, isolates the two processes and allows you to use any block production engine 119 | > on its own with probabilistic finality or couple it with a finality gadget to have deterministic 120 | > finality. 121 | 122 | In systems that use a finality gadget, the fork choice rule must be modified to consider the results 123 | of the finality game. For example, instead of taking the longest chain period, a node would take the 124 | longest chain that contains the most recently finalized block. 125 | 126 | ## Consensus in Substrate 127 | 128 | The Substrate framework ships with several consensus engines that provide block authoring, or 129 | finality. This article provides a brief overview of the offerings included with Substrate itself. 130 | Developers are always welcome to provide their own custom consensus algorithms. 131 | 132 | ### Aura 133 | 134 | [Aura](https://crates.parity.io/sc_consensus_aura/index.html) provides a slot-based 135 | block authoring mechanism. In Aura a known set of authorities take turns producing blocks. 136 | 137 | ### BABE 138 | 139 | [BABE](https://crates.parity.io/sc_consensus_babe/index.html) also provides slot-based 140 | block authoring with a known set of validators. In these ways it is similar to Aura. Unlike Aura, 141 | slot assignment is based on the evaluation of a Verifiable Random Function (VRF). Each validator is 142 | assigned a weight for an _epoch._ This epoch is broken up into slots and the validator evaluates its 143 | VRF at each slot. For each slot that the validator's VRF output is below its weight, it is allowed 144 | to author a block. 145 | 146 | Because multiple validators may be able to produce a block during the same slot, forks are more 147 | common in BABE than they are in Aura, and are common even in good network conditions. 148 | 149 | Substrate's implementation of BABE also has a fallback mechanism for when no authorities are chosen 150 | in a given slot. These "secondary" slot assignments allow BABE to achieve a constant block time. 151 | 152 | ### Proof of Work 153 | 154 | [Proof-of-work](https://crates.parity.io/sc_consensus_pow/index.html) block authoring 155 | is not slot-based and does not require a known authority set. In proof of work, anyone can produce a 156 | block at any time, so long as they can solve a computationally challenging problem (typically a hash 157 | preimage search). The difficulty of this problem can be tuned to provide a statistical target block 158 | time. 159 | 160 | ### GRANDPA 161 | 162 | [GRANDPA](https://crates.parity.io/sc_finality_grandpa/index.html) provides block 163 | finalization. It has a known weighted authority set like BABE. However, GRANDPA does not author 164 | blocks; it just listens to gossip about blocks that have been produced by some authoring engine like 165 | the three discussed above. GRANDPA validators vote on _chains,_ not _blocks,_ i.e. they vote on a 166 | block that they consider "best" and their votes are applied transitively to all previous blocks. 167 | Once more than 2/3 of the GRANDPA authorities have voted for a particular block, it is considered 168 | final. 169 | 170 | ### Coordination with the Runtime 171 | 172 | The simplest static consensus algorithms work entirely outside of the runtime as we've described so 173 | far. However many consensus games are made much more powerful by adding features that require 174 | coordination with the runtime. Examples include adjustable difficulty in proof of work, authority 175 | rotation in proof of authority, and stake-based weighting in proof-of-stake networks. 176 | 177 | To accommodate these consensus features, Substrate has the concept of a 178 | [`DigestItem`](https://crates.parity.io/sp_runtime/enum.DigestItem.html), a message 179 | passed from the outer part of the node, where consensus lives, to the runtime, or vice versa. 180 | 181 | ## Learn More 182 | 183 | Because both BABE and GRANDPA will be used in the Polkadot network, Web3 Foundation provides 184 | research-level presentations of the algorithms. 185 | 186 | - [BABE Research](https://research.web3.foundation/en/latest/polkadot/BABE/Babe.html) 187 | - [GRANDPA Research](https://research.web3.foundation/en/latest/polkadot/GRANDPA.html) 188 | 189 | All deterministic finality algorithms, including GRANDPA, require at least `2f + 1` non-faulty 190 | nodes, where `f` is the number of faulty or malicious nodes. Learn more about where this threshold 191 | comes from and why it is ideal in the seminal paper 192 | [Reaching Agreement in the Presence of Faults](https://lamport.azurewebsites.net/pubs/reaching.pdf) 193 | or on [Wikipedia: Byzantine Fault](https://en.wikipedia.org/wiki/Byzantine_fault). 194 | 195 | Not all consensus protocols define a single, canonical chain. Some protocols validate 196 | [directed acyclic graphs](https://en.wikipedia.org/wiki/Directed_acyclic_graph) (DAG) when two 197 | blocks with the same parent do not have conflicting state changes. 198 | -------------------------------------------------------------------------------- /current/advanced/cryptography.md: -------------------------------------------------------------------------------- 1 | --- 2 | slug: cryptography 3 | lang: en 4 | title: Cryptography 5 | --- 6 | 7 | This document offers a conceptual overview of the cryptography used in Substrate. 8 | 9 | ## Hashing Algorithms 10 | 11 | Hash functions are used in Substrate to map arbitrary sized data to fixed-sized values. 12 | 13 | Substrate provides two hash algorithms out of the box, but can support any hash algorithm which 14 | implements the [`Hasher` trait](https://crates.parity.io/sp_core/trait.Hasher.html). 15 | 16 | ### xxHash 17 | 18 | xxHash is a fast [non-cryptographic hash function](https://en.wikipedia.org/wiki/Hash_function), 19 | working at speeds close to RAM limits. Because xxHash is not cryptographically secure, it is 20 | possible that the output of the hash algorithm can be reasonably controlled by modifying the input. 21 | This can allow a user to attack the algorithm by creating key collisions, hash collisions, and 22 | imbalanced storage tries. 23 | 24 | xxHash is used in places where outside parties cannot manipulate the input of the hash function. For 25 | example, it is used to generate the key for runtime storage values, whose inputs are controlled by 26 | the runtime developer. 27 | 28 | Substrate uses the [`twox-hash`](https://github.com/shepmaster/twox-hash) implementation in Rust. 29 | 30 | ### Blake2 31 | 32 | [Blake2]() is a cryptographic hash 33 | function. It is considered to be optimized and is also used in 34 | [Zcash](https://en.wikipedia.org/wiki/Zcash). 35 | 36 | Substrate uses the [`blake2`](https://docs.rs/blake2/) implementation in Rust. 37 | 38 | ## Public-Key Cryptography 39 | 40 | Public-key cryptography is used in Substrate to provide a robust authentication system. 41 | 42 | Substrate provides multiple different cryptographic schemes and is generic such that it can support 43 | anything which implements the 44 | [`Pair` trait](https://crates.parity.io/sp_core/crypto/trait.Pair.html). 45 | 46 | ### ECDSA 47 | 48 | Substrate provides an 49 | [ECDSA](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm) signature scheme 50 | using the [secp256k1](https://en.bitcoin.it/wiki/Secp256k1) curve. This is the same cryptographic 51 | algorithm used to secure [Bitcoin](https://en.wikipedia.org/wiki/Bitcoin) and 52 | [Ethereum](https://en.wikipedia.org/wiki/Ethereum). 53 | 54 | ### Ed25519 55 | 56 | [Ed25519](https://en.wikipedia.org/wiki/EdDSA#Ed25519) is an EdDSA signature scheme using 57 | [Curve25519](https://en.wikipedia.org/wiki/Curve25519). It is carefully engineered at several levels 58 | of design and implementation to achieve very high speeds without compromising security. 59 | 60 | ### SR25519 61 | 62 | [SR25519](https://research.web3.foundation/en/latest/polkadot/keys/1-accounts-more/) is based on the 63 | same underlying curve as [Ed25519](#ed25519). However, it uses Schnorr signatures instead of the 64 | EdDSA scheme. 65 | 66 | Schnorr signatures bring some noticeable features over the [ECDSA](#ecdsa)/EdDSA schemes: 67 | 68 | - It is better for hierarchical deterministic key derivations. 69 | - It allows for native multi-signature through 70 | [signature aggregation](https://bitcoincore.org/en/2017/03/23/schnorr-signature-aggregation/). 71 | - It is generally more resistant to misuse. 72 | 73 | One sacrifice that is made when using Schnorr signatures over ECDSA is that both require 64 bytes, 74 | but only ECDSA signatures communicate their public key. 75 | 76 | ## Next Steps 77 | 78 | ### Learn More 79 | 80 | - Learn about the [Substrate account abstractions](../learn-substrate/account-abstractions). 81 | - For more detailed descriptions, please see the more advanced 82 | [research wiki](https://research.web3.foundation). 83 | 84 | ### Examples 85 | 86 | - Look at the Polkadot claims module to see how you can 87 | [verify Ethereum signatures in the Substrate runtime](https://github.com/paritytech/polkadot/blob/master/runtime/common/src/claims.rs). 88 | 89 | ### References 90 | 91 | - Take a look at the 92 | [`Hash`](https://crates.parity.io/sp_runtime/traits/trait.Hash.html) trait needed for 93 | implementing new hashing algorithms. 94 | - Take a look at the [`Pair`](https://crates.parity.io/sp_core/crypto/trait.Pair.html) 95 | trait needed for implementing new cryptographic schemes. 96 | -------------------------------------------------------------------------------- /current/advanced/executor.md: -------------------------------------------------------------------------------- 1 | --- 2 | slug: executor 3 | lang: en 4 | title: Executor 5 | --- 6 | 7 | The executor is responsible for dispatching and executing calls into the Substrate runtime. 8 | 9 | ## Runtime Execution 10 | 11 | The Substrate runtime is compiled into a native executable and a WebAssembly (Wasm) binary. 12 | 13 | The native runtime is included as part of the node executable, while the Wasm binary is stored on 14 | the blockchain under a well known storage key. 15 | 16 | These two representations of the runtime may not be the same. For example: when the runtime is 17 | upgraded. The executor determines which version of the runtime to use when dispatching calls. 18 | 19 | ### Execution Strategy 20 | 21 | Before runtime execution begins, the Substrate client proposes which runtime execution environment 22 | should be used. This is controlled by the execution strategy, which can be configured for the 23 | different parts of the blockchain execution process. The strategies are: 24 | 25 | - `Native`: Execute with native build (if available, WebAssembly otherwise); if it fails, do not 26 | fallback to Wasm. 27 | - `Wasm`: Only execute with the WebAssembly build. 28 | - `Both`: Execute with both native (where available) and WebAssembly builds. 29 | - `NativeElseWasm`: Execute with the native build if possible; if it fails, then execute with 30 | WebAssembly. 31 | 32 | The default execution strategies for the different parts of the blockchain execution process are: 33 | 34 | - Syncing: `NativeElseWasm` 35 | - Block Import: `NativeElseWasm` 36 | - Block Construction: `Wasm` 37 | - Off-Chain Worker: `Native` 38 | - Other: `Native` 39 | 40 | ### Wasm Execution 41 | 42 | The Wasm representation of the Substrate runtime is considered the canonical runtime. Because this 43 | Wasm runtime is placed in the blockchain storage, the network must come to consensus about this 44 | binary. Thus it can be verified to be consistent across all syncing nodes. 45 | 46 | The Wasm execution environment can be more restrictive than the native execution environment. For 47 | example, the Wasm runtime always executes in a 32-bit environment with a configurable memory limit 48 | (up to 4 GB). 49 | 50 | For these reasons, the blockchain prefers to do block construction with the Wasm runtime even though 51 | Wasm execution is measurably slower than native execution. Some logic executed in Wasm will always 52 | work in the native execution environment, but the same cannot be said the other way around. Wasm 53 | execution can help to ensure that block producers create valid blocks. 54 | 55 | ### Native Execution 56 | 57 | The native runtime will only be used by the executor when it is chosen as the execution strategy and 58 | it is compatible with the requested runtime version. For all other execution processes other than 59 | block construction, the native runtime is preferred since it is more performant. In any situation 60 | where the native executable should not be run, the canonical Wasm runtime is executed instead. 61 | 62 | ## Runtime Upgrades 63 | 64 | The Substrate runtime is designed to be upgraded so that you can continue to iterate on your state 65 | transition function even after your blockchain goes live. 66 | 67 | ### Runtime Versioning 68 | 69 | In order for the executor to be able to select the appropriate runtime execution environment, it 70 | needs to know the `spec_name`, `spec_version` and `authoring_version` of both the native and Wasm 71 | runtime. 72 | 73 | The runtime provides the following 74 | [versioning properties](https://crates.parity.io/sp_version/struct.RuntimeVersion.html): 75 | 76 | - `spec_name`: The identifier for the different Substrate runtimes. 77 | 78 | - `impl_name`: The name of the implementation of the spec. This is of little consequence for the 79 | node and serves only to differentiate code of different implementation teams. 80 | 81 | - `authoring_version`: The version of the authorship interface. An authoring node will not attempt 82 | to author blocks unless this is equal to its native runtime. 83 | 84 | - `spec_version`: The version of the runtime specification. A full-node will not attempt to use its 85 | native runtime in substitute for the on-chain Wasm runtime unless all of `spec_name`, 86 | `spec_version`, and `authoring_version` are the same between Wasm and native. 87 | 88 | - `impl_version`: The version of the implementation of the specification. Nodes are free to ignore 89 | this; it serves only as an indication that the code is different; as long as the other two 90 | versions are the same then while the actual code may be different, it is nonetheless required to 91 | do the same thing. Non-consensus-breaking optimizations are about the only changes that could be 92 | made which would result in only the `impl_version` changing. 93 | 94 | As mentioned above, the executor always verifies that the native runtime has the same 95 | consensus-driven logic before it chooses to execute it, independent of whether the version is higher 96 | or lower. 97 | 98 | > **Note:** The runtime versioning is manually set. Thus the executor can still make inappropriate 99 | > decisions if the runtime version is misrepresented. 100 | 101 | ### Forkless Runtime Upgrades 102 | 103 | Traditional blockchains require a [hard fork]() 104 | when upgrading the state transition function of their chain. This requires node operators to stop 105 | their nodes and manually upgrade to the latest executable. For distributed production networks, 106 | coordination of a hard fork upgrades can be a complex process. 107 | 108 | The culmination of the properties listed on this page allows for Substrate-based blockchains to 109 | perform "forkless runtime upgrades". This means that the upgrade of the runtime logic can happen in 110 | real time without causing a fork in the network. 111 | 112 | To perform a forkless runtime upgrade, Substrate uses existing runtime logic to update the Wasm 113 | runtime stored on the blockchain to a new consensus-breaking version with new logic. This upgrade 114 | gets pushed out to all syncing nodes on the network as a part of the consensus process. Once the 115 | Wasm runtime is upgraded, the executor will see that the native runtime `spec_name`, `spec_version`, 116 | or `authoring_version` no longer matches this new Wasm runtime. As a result, it will fall back to 117 | execute the canonical Wasm runtime instead of using the native runtime in any of the execution 118 | processes. 119 | 120 | ## Next Steps 121 | 122 | ### Learn More 123 | 124 | - Learn more about 125 | 126 | ### Examples 127 | 128 | TODO 129 | 130 | ### References 131 | 132 | - Check out the different 133 | [Execution Strategies](https://crates.parity.io/sc_client_api/execution_extensions/struct.ExecutionStrategies.html). 134 | 135 | - Take a look at the different 136 | [Execution Strategy Options](https://crates.parity.io/sp_state_machine/enum.ExecutionStrategy.html) 137 | 138 | - Review the 139 | [Runtime Version definition](https://crates.parity.io/sp_version/struct.RuntimeVersion.html). 140 | -------------------------------------------------------------------------------- /current/advanced/ss58-address-format.md: -------------------------------------------------------------------------------- 1 | --- 2 | slug: ss58-address-format 3 | lang: en 4 | title: SS58 Address Format 5 | --- 6 | 7 | SS58 is a simple address format designed for Substrate based chains. There's no problem with using 8 | other address formats for a chain, but this serves as a robust default. It is heavily based on 9 | Bitcoin's Base-58-check format with a few alterations. 10 | 11 | The basic idea is a base-58 encoded value that can identify a specific account on the Substrate 12 | chain. Different chains have different means of identifying accounts. SS58 is designed to be 13 | extensible for this reason. 14 | 15 | The living specification for the SS-58 address format can be found on the Substrate GitHub wiki: 16 | 17 | https://github.com/paritytech/substrate/wiki/External-Address-Format-(SS58) 18 | -------------------------------------------------------------------------------- /current/advanced/storage.md: -------------------------------------------------------------------------------- 1 | --- 2 | slug: storage 3 | lang: en 4 | title: Storage 5 | --- 6 | 7 | Substrate uses a simple key-value data store implemented as a database-backed, modified Merkle tree. 8 | All of Substrate's [higher-lever storage abstractions](../runtime/storage) are built on top of this 9 | simple key-value store. 10 | 11 | ## Key-Value Database 12 | 13 | Substrate implements its storage database with [RocksDB](https://rocksdb.org/), a persistent 14 | key-value store for fast storage environments. It also supports an experimental 15 | [Parity DB](https://github.com/paritytech/parity-db). 16 | 17 | The DB is used for all the components of Substrate that require persistent storage, such as: 18 | 19 | - Substrate clients 20 | - Substrate light-clients 21 | - Off-chain workers 22 | 23 | ## Trie Abstraction 24 | 25 | One advantage of using a simple key-value store is that you are able to easily abstract storage 26 | structures on top of it. 27 | 28 | Substrate uses a Base-16 Modified Merkle Patricia tree ("trie") from 29 | [`paritytech/trie`](https://github.com/paritytech/trie) to provide a trie structure whose contents 30 | can be modified and whose root hash is recalculated efficiently. 31 | 32 | Tries allow efficient storing and sharing of the historical block state. The trie root is a 33 | representation of the data within the trie; that is, two tries with different data will always have 34 | different roots. Thus, two blockchain nodes can easily verify that they have the same state by 35 | simply comparing their trie roots. 36 | 37 | Accessing trie data is costly. Each read operation takes O(log N) time, where N is the number of 38 | elements stored in the trie. To mitigate this, we use a key-value cache. 39 | 40 | All trie nodes are stored in the DB and part of the trie state can get pruned, i.e. a key-value pair 41 | can be deleted from storage when it is out of pruning range for non-archive nodes. We do not use 42 | [reference counting](http://en.wikipedia.org/wiki/Reference_counting) for performance reasons. 43 | 44 | ### State Trie 45 | 46 | Substrate-based chains have a single main trie, called the state trie, whose root hash is placed in 47 | each block header. This is used to easily verify the state of the blockchain and provide a basis for 48 | light clients to verify proofs. 49 | 50 | This trie only stores content for the canonical chain, not forks. There is a separate 51 | [`state_db` layer](https://crates.parity.io/sc_state_db/index.html) that maintains the 52 | trie state with references counted in memory for all that is non-canonical. 53 | 54 | ### Child Trie 55 | 56 | Substrate also provides an API to generate new child tries with their own root hashes that can be 57 | used in the runtime. 58 | 59 | Child tries are identical to the main state trie, except that a child trie's root is stored and 60 | updated as a node in the main trie instead of the block header. Since their headers are a part of 61 | the main state trie, it is still easy to verify the complete node state when it includes child 62 | tries. 63 | 64 | Child tries are useful when you want your own independent trie with a separate root hash that you 65 | can use to verify the specific content in that trie. Subsections of a trie do not have a 66 | root-hash-like representation that satisfies these needs automatically; thus a child trie is used 67 | instead. 68 | 69 | ## Querying Storage 70 | 71 | Blockchains that are built with Substrate expose a remote procedure called (RPC) server that can be 72 | used to query runtime storage. When you use the Substrate RPC to access a storage item, you only 73 | need to provide [the key](#Key-Value-Database) associated with that item. 74 | [Substrate's runtime storage APIs](../runtime/storage) expose a number of storage item types. Additional information on how to calculate storage keys for the different types of storage items will be explained below. 75 | 76 | ### Storage Value Keys 77 | 78 | To calculate the key for a simple [Storage Value](../runtime/storage#Storage-Value), take the 79 | [TwoX 128 hash](https://github.com/Cyan4973/xxHash) of the name of the module that contains the 80 | Storage Value and append to it the TwoX 128 hash of the name of the Storage Value itself. For 81 | example, the [Sudo](https://crates.parity.io/pallet_sudo/index.html) pallet exposes a 82 | Storage Value item named 83 | [`Key`](https://crates.parity.io/pallet_sudo/struct.Module.html#method.key): 84 | 85 | ``` 86 | twox_128("Sudo")                   = "0x5c0d1176a568c1f92944340dbfed9e9c" 87 | twox_128("Key)                     = "0x530ebca703c85910e7164cb7d1c9e47b" 88 | twox_128("Sudo") + twox_128("Key") = "0x5c0d1176a568c1f92944340dbfed9e9c530ebca703c85910e7164cb7d1c9e47b" 89 | ``` 90 | 91 | If the `Alice` account is the sudo user, an RPC request and responds to read the Sudo 92 | module's `Key` Storage Value, this could be represented as: 93 | 94 | ``` 95 | state_getStorage("0x5c0d1176a568c1f92944340dbfed9e9c530ebca703c85910e7164cb7d1c9e47b") = "0xd43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d" 96 | ``` 97 | 98 | In this case, the value that is returned 99 | (`"0xd43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d"`) is Alice's 100 | [SCALE](./codec)-encoded account ID (`5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY`). 101 | 102 | You may have noticed that the 103 | [non-cryptographic](../runtime/storage#Cryptographic-Hashing-Algorithms) TwoX 128 hash algorithm is 104 | used to generate Storage Value keys. This is because it is not necessary to migrate the performance 105 | costs associated with a cryptographic hash function. The input to the hash function (the names 106 | of the module and storage item) are thus determined by the runtime developer vs a potentially 107 | malicious users of your blockchain. 108 | 109 | ### Storage Map Keys 110 | 111 | Like Storage Values, the keys for [Storage Maps](../runtime/storage#StorageMaps) are equal to the 112 | TwoX 128 hash of the name of the module that contains the map prepended to the TwoX 128 hash of the 113 | name of the Storage Map itself. To retrieve an element from a map, simply append the hash of the 114 | desired map key to the storage key of the Storage Map. For maps with two keys (Storage Double Maps), 115 | append the hash of the first map key followed by the hash of the second map key to the Storage 116 | Double Map's storage key. Like Storage Values, Substrate will use the TwoX 128 hashing algorithm for 117 | the module and Storage Map names, but you will need to make sure to use the correct 118 | [hashing algorithm](../runtime/storage#Hashing-Algorithms) (the one that was declared in 119 | [the `decl_storage` macro](../runtime/storage#Declaring-Storage-Items)) when determining the hashed 120 | keys for the elements in a map. 121 | 122 | Here is an example that illustrates querying a Storage Map named `FreeBalance` from a module named 123 | "Balances" for the balance of the familiar `Alice` account. In this example, the `FreeBalance` map 124 | is using 125 | [the transparent Blake2 128 Concat hashing algorithm](../runtime/storage#Transparent-Hashing-Algorithms): 126 | 127 | ``` 128 | twox_128("Balances)                                              = "0xc2261276cc9d1f8598ea4b6a74b15c2f" 129 | twox_128("FreeBalance")                                          = "0x6482b9ade7bc6657aaca787ba1add3b4" 130 | scale_encode("5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY") = "0xd43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d" 131 | 132 | blake2_128_concat("0xd43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d") = "0xde1e86a9a8c739864cf3cc5ec2bea59fd43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d" 133 | 134 | state_getStorage("0xc2261276cc9d1f8598ea4b6a74b15c2f6482b9ade7bc6657aaca787ba1add3b4de1e86a9a8c739864cf3cc5ec2bea59fd43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d") = "0x0000a0dec5adc9353600000000000000" 135 | ``` 136 | 137 | The value that is returned from the storage query (`"0x0000a0dec5adc9353600000000000000"` in the 138 | example above) is the [SCALE](./codec)-encoded value of Alice's account balance 139 | (`"1000000000000000000000"` in this example). Notice that before hashing Alice's account ID it has 140 | to be SCALE-encoded. Also notice that the output of the `blake2_128_concat` function consists of 32 141 | hexadecimal characters followed by the function's input. This is because the Blake2 128 Concat is 142 | [a transparent hashing algorithm](../runtime/storage#Transparent-Hashing-Algorithms). Its goal is to iterate over the keys in a map (as opposed to retrieving the value associated with a 143 | single key). Thus, the ability to iterate over the keys in a map is a common requirement in order to allow 144 | _people_ to use the map in a way that seems natural (such as UIs). First, a user is presented with a 145 | list of elements in the map, then, that user can select the element that they are interested in. The user can then 146 | query the map for more details about that particular element. Here is another example that uses the 147 | same example Storage Map (a map named `FreeBalances` that uses a Blake2 128 Concat hashing algorithm 148 | in a module named "Balances") that will demonstrate using the Substrate RPC to query a Storage Map 149 | for its list of keys via the `state_getKeys` RPC endpoint: 150 | 151 | ``` 152 | twox_128("Balances)                                       = "0xc2261276cc9d1f8598ea4b6a74b15c2f" 153 | twox_128("FreeBalance")                                   = "0x6482b9ade7bc6657aaca787ba1add3b4" 154 | 155 | state_getKeys("0xc2261276cc9d1f8598ea4b6a74b15c2f6482b9ade7bc6657aaca787ba1add3b4") = [ 156 | "0xc2261276cc9d1f8598ea4b6a74b15c2f6482b9ade7bc6657aaca787ba1add3b4de1e86a9a8c739864cf3cc5ec2bea59fd43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d", 157 | "0xc2261276cc9d1f8598ea4b6a74b15c2f6482b9ade7bc6657aaca787ba1add3b432a5935f6edc617ae178fef9eb1e211fbe5ddb1579b72e84524fc29e78609e3caf42e85aa118ebfe0b0ad404b5bdd25f", 158 | ... 159 | ] 160 | ``` 161 | 162 | Each element in the list that is returned by the Substrate RPC's `state_getKeys` endpoint can be 163 | directly used as input for the RPC's `state_getStorage` endpoint. In fact, the first element in 164 | the example list above is equal to the input used for the `state_getStorage` query in the previous 165 | example (the one used to find the balance for `Alice`). Because the map that these keys belong to 166 | uses a transparent hashing algorithm to generate its keys, it is possible to determine the account 167 | associated with the second element in the list. Notice that each element in the list is a 168 | hexadecimal value that begins with the same 64 characters; this is because each list element 169 | represents a key in the same map, and that map is identified by concatenating two TwoX 128 hashes, 170 | each of which are 128-bits or 32 hexadecimal characters. After discarding this portion of the second 171 | element in the list, you are left with 172 | `0x32a5935f6edc617ae178fef9eb1e211fbe5ddb1579b72e84524fc29e78609e3caf42e85aa118ebfe0b0ad404b5bdd25f`. 173 | 174 | In the previous example this represents the Blake2 128 Concat hash of some 175 | [SCALE](./codec)-encoded account ID. The Blake 128 Concat hashing algorithm consists of appending 176 | (concatenating) the hashing algorithm's input to its Blake 128 hash. Thus the first 128 177 | bits (or 32 hexadecimal characters) of a Blake2 128 Concat hash represents a Blake2 128 hash, and 178 | the remainder represents the value that was passed to the Blake 2 128 hashing algorithm. By removing the first 32 hexadecimal characters that represent the Blake2 128 hash 179 | (i.e. `0x32a5935f6edc617ae178fef9eb1e211f`) the hexadecimal value 180 | `0xbe5ddb1579b72e84524fc29e78609e3caf42e85aa118ebfe0b0ad404b5bdd25f`remains which is a 181 | [SCALE](./codec)-encoded account ID. Decoding this value yields the result 182 | `5GNJqTPyNqANBkUVMN1LPPrxXnFouWXoe2wNSmmEoLctxiZY`, which is the account ID for the 183 | `Alice_Stash` account. 184 | 185 | ## Runtime Storage API 186 | 187 | Substrate's [FRAME Support crate](https://crates.parity.io/frame_support/index.html) 188 | provides utilities for generating unique, deterministic keys for your runtime's storage items. These 189 | storage items are placed in the [state trie](#Trie-Abstraction) and can be accessed by 190 | [querying the trie by key](#Querying-Storage). 191 | 192 | ## Next Steps 193 | 194 | ### Learn More 195 | 196 | - Learn how to add [storage items](../runtime/storage) into your Substrate runtime modules. 197 | 198 | ### Examples 199 | 200 | - View an example of creating 201 |   [child tries](https://substrate.dev/recipes/3-entrees/storage-api/childtries.html) in your 202 |   Substrate runtime module. 203 | 204 | ### References 205 | 206 | - Visit the reference docs for 207 |   [`paritytech/trie`](https://crates.parity.io/trie_db/trait.Trie.html). 208 | -------------------------------------------------------------------------------- /current/assets/16b213f-Screenshot_from_2019-01-11_16-29-09.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/polkadot-developers/knowledgebase/1f009a4cdad54a49b0a742030168593b712c1dd9/current/assets/16b213f-Screenshot_from_2019-01-11_16-29-09.png -------------------------------------------------------------------------------- /current/assets/consensus-ghost.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/polkadot-developers/knowledgebase/1f009a4cdad54a49b0a742030168593b712c1dd9/current/assets/consensus-ghost.png -------------------------------------------------------------------------------- /current/assets/consensus-longest-chain.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/polkadot-developers/knowledgebase/1f009a4cdad54a49b0a742030168593b712c1dd9/current/assets/consensus-longest-chain.png -------------------------------------------------------------------------------- /current/assets/file-hash.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/polkadot-developers/knowledgebase/1f009a4cdad54a49b0a742030168593b712c1dd9/current/assets/file-hash.png -------------------------------------------------------------------------------- /current/assets/forks.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/polkadot-developers/knowledgebase/1f009a4cdad54a49b0a742030168593b712c1dd9/current/assets/forks.png -------------------------------------------------------------------------------- /current/assets/frame-arch.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/polkadot-developers/knowledgebase/1f009a4cdad54a49b0a742030168593b712c1dd9/current/assets/frame-arch.png -------------------------------------------------------------------------------- /current/assets/front-end-template-balance-transfer.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/polkadot-developers/knowledgebase/1f009a4cdad54a49b0a742030168593b712c1dd9/current/assets/front-end-template-balance-transfer.png -------------------------------------------------------------------------------- /current/assets/front-end-template.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/polkadot-developers/knowledgebase/1f009a4cdad54a49b0a742030168593b712c1dd9/current/assets/front-end-template.png -------------------------------------------------------------------------------- /current/assets/off-chain-workers-v1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/polkadot-developers/knowledgebase/1f009a4cdad54a49b0a742030168593b712c1dd9/current/assets/off-chain-workers-v1.png -------------------------------------------------------------------------------- /current/assets/off-chain-workers-v2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/polkadot-developers/knowledgebase/1f009a4cdad54a49b0a742030168593b712c1dd9/current/assets/off-chain-workers-v2.png -------------------------------------------------------------------------------- /current/assets/poe-claimed.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/polkadot-developers/knowledgebase/1f009a4cdad54a49b0a742030168593b712c1dd9/current/assets/poe-claimed.png -------------------------------------------------------------------------------- /current/assets/poe-component.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/polkadot-developers/knowledgebase/1f009a4cdad54a49b0a742030168593b712c1dd9/current/assets/poe-component.png -------------------------------------------------------------------------------- /current/assets/private-network-apps-insert-key.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/polkadot-developers/knowledgebase/1f009a4cdad54a49b0a742030168593b712c1dd9/current/assets/private-network-apps-insert-key.png -------------------------------------------------------------------------------- /current/assets/private-network-apps-keygen.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/polkadot-developers/knowledgebase/1f009a4cdad54a49b0a742030168593b712c1dd9/current/assets/private-network-apps-keygen.png -------------------------------------------------------------------------------- /current/assets/private-network-no-blocks.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/polkadot-developers/knowledgebase/1f009a4cdad54a49b0a742030168593b712c1dd9/current/assets/private-network-no-blocks.png -------------------------------------------------------------------------------- /current/assets/runtime.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/polkadot-developers/knowledgebase/1f009a4cdad54a49b0a742030168593b712c1dd9/current/assets/runtime.png -------------------------------------------------------------------------------- /current/assets/substrate-listener.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/polkadot-developers/knowledgebase/1f009a4cdad54a49b0a742030168593b712c1dd9/current/assets/substrate-listener.png -------------------------------------------------------------------------------- /current/assets/technical-freedom.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/polkadot-developers/knowledgebase/1f009a4cdad54a49b0a742030168593b712c1dd9/current/assets/technical-freedom.png -------------------------------------------------------------------------------- /current/config.json: -------------------------------------------------------------------------------- 1 | { 2 | "lang": "en", 3 | "slug": "config", 4 | "release_url": "https://github.com/paritytech/substrate/", 5 | "menu": [ 6 | { 7 | "title": "Getting Started", 8 | "slug": "getting-started", 9 | "menu_items": [ 10 | { "title": "Installation", "slug": "index" }, 11 | { "title": "Windows Users", "slug": "windows-users" }, 12 | { "title": "Glossary", "slug": "glossary" } 13 | ] 14 | }, 15 | { 16 | "title": "Learn Substrate", 17 | "slug": "learn-substrate", 18 | "menu_items": [ 19 | { "title": "Overview", "slug": "index" }, 20 | { "title": "Extrinsics", "slug": "extrinsics" }, 21 | { "title": "Transaction Queue", "slug": "tx-pool" }, 22 | { "title": "Account Abstractions", "slug": "account-abstractions" }, 23 | { "title": "Session Keys", "slug": "session-keys" }, 24 | { "title": "Weight", "slug": "weight" }, 25 | { "title": "Off Chain Workers", "slug": "off-chain-workers" } 26 | ] 27 | }, 28 | { 29 | "title": "Runtime", 30 | "slug": "runtime", 31 | "menu_items": [ 32 | { "title": "Overview", "slug": "index" }, 33 | { "title": "Primitives", "slug": "primitives" }, 34 | { "title": "FRAME", "slug": "frame" }, 35 | { "title": "Pallets", "slug": "pallets" }, 36 | { "title": "Macros", "slug": "macros" }, 37 | { "title": "Runtime Metadata", "slug": "metadata" }, 38 | { "title": "Storage", "slug": "storage" }, 39 | { "title": "Origin", "slug": "origin" }, 40 | { "title": "Execution", "slug": "execution" }, 41 | { "title": "Events", "slug": "events" }, 42 | { "title": "Fees", "slug": "fees" }, 43 | { "title": "Off Chain Workers", "slug": "off-chain-workers" }, 44 | { "title": "Debugging", "slug": "debugging" }, 45 | { "title": "Tests", "slug": "tests" } 46 | ] 47 | }, 48 | { 49 | "title": "Smart Contracts", 50 | "slug": "smart-contracts", 51 | "menu_items": [ 52 | { "title": "Ink! Smart Contracts", "slug": "index" }, 53 | { "title": "Overview", "slug": "overview" }, 54 | { "title": "Ink! Fundamentals", "slug": "ink-fundamentals" }, 55 | { "title": "Environment Types", "slug": "env-types" }, 56 | { "title": "Ink! Development", "slug": "ink-development" }, 57 | { "title": "Contracts Pallet", "slug": "contracts-pallet" }, 58 | { "title": "EVM Pallet", "slug": "evm-pallet" }, 59 | { "title": "FAQ", "slug": "faq" } 60 | ] 61 | }, 62 | { 63 | "title": "Integrate", 64 | "slug": "integrate", 65 | "menu_items": [ 66 | { "title": "Front End", "slug": "polkadot-js" }, 67 | { "title": "Client Libraries", "slug": "libraries" }, 68 | { "title": "Chain Specs", "slug": "chain-spec" }, 69 | { "title": "Subkey", "slug": "subkey" } 70 | ] 71 | }, 72 | { 73 | "title": "Advanced", 74 | "slug": "advanced", 75 | "menu_items": [ 76 | { "title": "SCALE Codec", "slug": "codec" }, 77 | { "title": "Consensus", "slug": "consensus" }, 78 | { "title": "Block Import Pipeline", "slug": "block-import" }, 79 | { "title": "Executor", "slug": "executor" }, 80 | { "title": "Cryptography", "slug": "cryptography" }, 81 | { "title": "Storage", "slug": "storage" }, 82 | { "title": "SS58 Address Format", "slug": "ss58-address-format" } 83 | ] 84 | } 85 | ] 86 | } 87 | -------------------------------------------------------------------------------- /current/contribute/help-translate.md: -------------------------------------------------------------------------------- 1 | --- 2 | slug: help-translate 3 | lang: en 4 | title: Help Translate 5 | --- 6 | 7 | Substrate is an open source Blockchain framework used by developers around the 8 | world. We need **your** help to make this website accessible for developers of all languages. 9 | 10 | If you can help translate the documentation here into another language, please go to 11 | [Crowdin](https://crowdin.com/project/substrate-developer-hub) and pick a language to get started. 12 | 13 | Once your translation gets approved, it will appear on the website! 14 | 15 | If you are interested in approving translations from others, please send an email to 16 | . 17 | -------------------------------------------------------------------------------- /current/getting-started/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | slug: index 3 | lang: en 4 | title: Installation 5 | --- 6 | 7 | ## Fast Installation 8 | 9 | Install all the required dependencies with a single command. (Be patient, this can take up to 30 10 | minutes) 11 | 12 | ```bash 13 | curl https://getsubstrate.io -sSf | bash -s -- --fast 14 | ``` 15 | 16 | ## Manual Installation 17 | 18 | ### Debian 19 | 20 | Run: 21 | 22 | ```bash 23 | sudo apt install -y cmake pkg-config libssl-dev git gcc build-essential clang libclang-dev 24 | ``` 25 | 26 | ### MacOS 27 | 28 | Install the [Homebrew package manager](https://brew.sh/), then run: 29 | 30 | ```bash 31 | brew install openssl cmake llvm 32 | ``` 33 | 34 | ## Rust Developer Environment 35 | 36 | Substrate uses the Rust programming language. You should 37 | [install Rust](https://www.rust-lang.org/tools/install) using `rustup`: 38 | 39 | ``` 40 | curl https://sh.rustup.rs -sSf | sh 41 | ``` 42 | 43 | Then make sure that you are using the latest Rust stable by default: 44 | 45 | ``` 46 | rustup default stable 47 | ``` 48 | 49 | ### Wasm Compilation 50 | 51 | Substrate uses WebAssembly (Wasm), and you will need to configure your Rust compiler to use 52 | `nightly` to support this build target. 53 | 54 | Run the following: 55 | 56 | ```bash 57 | rustup update nightly 58 | rustup target add wasm32-unknown-unknown --toolchain nightly 59 | ``` 60 | 61 | ### Rustup Update 62 | 63 | Substrate always uses the latest version of Rust stable and nightly for compilation. To ensure your 64 | Rust compiler is always up to date, you should run: 65 | 66 | ``` 67 | rustup update 68 | ``` 69 | 70 | This may even solve compilation issues you face when working with Substrate. 71 | -------------------------------------------------------------------------------- /current/getting-started/windows-users.md: -------------------------------------------------------------------------------- 1 | --- 2 | slug: windows-users 3 | lang: en 4 | title: Getting Started on Windows 5 | --- 6 | 7 | If you are trying to set up a Windows computer to build Substrate, do the following: 8 | 9 | 1. Download and install "Build Tools for Visual Studio:" 10 | 11 | - You can get it at this link: https://aka.ms/buildtools. 12 | - Run the installation file: `vs_buildtools.exe`. 13 | - Ensure the "Windows 10 SDK" component is included when installing the Visual C++ Build Tools. 14 | - Restart your computer. 15 | 16 | 2. Install Rust: 17 | 18 | - Detailed instructions are provided by the 19 | [Rust Book](https://doc.rust-lang.org/book/ch01-01-installation.html#installing-rustup-on-windows). 20 | 21 | - Download from: https://www.rust-lang.org/tools/install. 22 | - Run the installation file: `rustup-init.exe`. 23 | 24 | > Note that it should **not** prompt you to install `vs_buildtools` since you did it in 25 | > step 1. 26 | 27 | - Choose "Default Installation." 28 | - To get started, you need Cargo's bin directory (`%USERPROFILE%\.cargo\bin`) in your PATH 29 | environment variable. Future applications will automatically have the correct environment, 30 | but you may need to restart your current shell. 31 | 32 | 3. Run these commands in Command Prompt (`CMD`) to set up your Wasm Build Environment: 33 | 34 | ```bash 35 | rustup update nightly 36 | rustup update stable 37 | rustup target add wasm32-unknown-unknown --toolchain nightly 38 | ``` 39 | 40 | 4. Install LLVM: https://releases.llvm.org/download.html 41 | 42 | 5. Install OpenSSL with `vcpkg`: 43 | 44 | ```bash 45 | mkdir C:\Tools 46 | cd C:\Tools 47 | git clone https://github.com/Microsoft/vcpkg.git 48 | cd vcpkg 49 | .\bootstrap-vcpkg.bat 50 | .\vcpkg.exe install openssl:x64-windows-static 51 | ``` 52 | 53 | 6. Add OpenSSL to your System Variables using PowerShell: 54 | 55 | ```powershell 56 | $env:OPENSSL_DIR = 'C:\Tools\vcpkg\installed\x64-windows-static' 57 | $env:OPENSSL_STATIC = 'Yes' 58 | [System.Environment]::SetEnvironmentVariable('OPENSSL_DIR', $env:OPENSSL_DIR, [System.EnvironmentVariableTarget]::User) 59 | [System.Environment]::SetEnvironmentVariable('OPENSSL_STATIC', $env:OPENSSL_STATIC, [System.EnvironmentVariableTarget]::User) 60 | ``` 61 | 62 | 7. Finally, install `cmake`: https://cmake.org/download/ 63 | 64 | You can now jump back to [Get the Source](#get-the-source) to learn how to download and compile 65 | Substrate! 66 | -------------------------------------------------------------------------------- /current/integrate/chain-spec.md: -------------------------------------------------------------------------------- 1 | --- 2 | slug: chain-spec 3 | lang: en 4 | title: Chain Specification 5 | --- 6 | 7 | A chain specification, or "chain spec", is a collection of configuration information that dictates 8 | which network a blockchain node will connect to, which entities it will initially communicate with, 9 | and what consensus-critical state it must have at genesis. 10 | 11 | ## Structure of a Chain Spec 12 | 13 | The [`ChainSpec` struct](https://crates.parity.io/sc_service/struct.GenericChainSpec.html) 14 | separates the information contained in a chain spec into two parts. A node can use a `ChainSpec` 15 | instance to create a genesis block. 16 | 17 | ### The Client Spec 18 | 19 | The first part of the chain spec, is the `ClientSpec`. The `ClientSpec` contains configuration 20 | information used by the Substrate client, the part of the node outside of the runtime. Much of this 21 | information is used to communicate with other parties in the network such as a set of bootnodes, a 22 | set of telemetry endpoints to which the node will send data, and human- and machine-readable names 23 | for the network to which the node will connect. Many of these items can be overridden by 24 | command-line flags, and the values can be changed after the blockchain has been launched. 25 | 26 | > Caution: While all properties in this section can be changed after genesis, nodes will only add 27 | > peers who use the same `protocolId`. 28 | 29 | ### Extension 30 | 31 | Because the Substrate framework is extensible, it provides a way to customize the client spec with 32 | additional data to configure customized parts of the client. One example use case is telling the 33 | node about well-known blocks at specific heights, to prevent long range attacks when syncing a new 34 | node from genesis. 35 | 36 | ### The Genesis State 37 | 38 | The second part of the chain spec is the consensus-critical genesis configuration. All nodes in the 39 | network must agree on this initial state before they can agree on any subsequent blocks. Therefore, 40 | this information must be established at the outset of the chain and cannot be changed thereafter 41 | without starting an entirely new blockchain. There are no command-line flags to override values in 42 | the genesis portion of a chain spec. 43 | 44 | Examples of what information might be included in the genesis portion of a chain spec include 45 | initial token balances, the accounts that are initially part of a governance council, or the holder 46 | of the sudo key. Substrate nodes also place the compiled Wasm runtime logic on chain, so the initial 47 | runtime must also be supplied in the chain spec. 48 | 49 | It is this second part of the chain spec that is used when creating a genesis block. 50 | 51 | ## Storing Chain Spec Information 52 | 53 | The information that comprises a chain spec can be stored in either of two ways. Being a Rust 54 | struct, the first way to store this information is as Rust code. Indeed, Substrate nodes typically 55 | include at least one, and often many, chain specs hard-coded into the client. Including this 56 | information directly in the client ensures that the node will know how to connect to at least one 57 | chain without any additional information supplied by the node operator. In protocols that have a 58 | notion of "main net" this spec is usually hard-coded in the client. 59 | 60 | Another common way to store chain spec information is in JSON format. The chain spec struct has a 61 | method for serializing its data into JSON as well as a function for de-serializing JSON data into an 62 | instance of a chain spec. When launching testnets or private chains, it is common to distribute a 63 | JSON-encoded chain spec along with the node binary. 64 | 65 | ## Using Chain Specs 66 | 67 | Node operators and runtime developers will encounter chain specifications when performing common 68 | tasks. 69 | 70 | ### Launching a Chain 71 | 72 | Each time a node operator starts a node, they provide a chain specification that the node should 73 | use. In the simplest case, the chain spec is provided implicitly and the node uses a default chain 74 | spec that is hard-coded into the node binary. 75 | 76 | A common task is to start a testnet or private network that behaves similarly to an existing 77 | protocol, but is not connected to the mainnet. To achieve this, the operator may choose an 78 | alternative hard-coded chain spec by using a command-line flag such as `--chain local` that 79 | instructs the node to use the spec associated with the string "local". A third option available to 80 | node operators is to provide a chain spec as a JSON file with a command-line flag such as 81 | `--chain=someCustomSpec.json`, in which case the node will attempt to de-serialize the provided JSON 82 | chain spec, and then use it. 83 | 84 | ### Developing a Runtime 85 | 86 | Nearly every Substrate runtime will have storage items that need to be configured at genesis. When 87 | developing with [FRAME](../runtime/frame), any storage item that is declared with the `config()` 88 | option requires configuration at genesis. It is the job of the chain spec, specifically the genesis 89 | portion, to configure such storage values. 90 | 91 | ### Customizing a Chain Spec 92 | 93 | When creating a one-off network for development, testing, or demonstration purposes, a truly 94 | customized chain spec may be desired. Node operators may export the default chain spec for the 95 | protocol to JSON format and then make edits. Substrate-based nodes are equipped with a `build-spec` 96 | sub-command that does this exporting. 97 | 98 | ```bash 99 | substrate build-spec > myCustomSpec.json 100 | ``` 101 | 102 | Once the chain spec has been exported, the node operator is free to modify any of its fields. It is 103 | common to modify the network's name and bootnodes as well as any genesis storage items, such as 104 | token balances, that the operator wishes. Once the edits are made, the operator may launch their 105 | customized chain by supplying the customized JSON. 106 | 107 | ```bash 108 | substrate --chain=myCustomSpec.json 109 | ``` 110 | 111 | ## Raw Chain Specs 112 | 113 | Substrate nodes support runtime upgrades, which means a blockchain's runtime may be different than 114 | when the chain began. Chain specs, as discussed so far, contain information structured in a way that 115 | can be understood by the node's runtime. For example, consider this excerpt from the default 116 | Substrate node's chainspec json. 117 | 118 | ```json 119 | "sudo": { 120 | "key": "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY" 121 | } 122 | ``` 123 | 124 | Before this spec can be used to initialize a node's genesis storage, the human-readable keys must be 125 | transformed into actual storage keys for the [storage trie](/current/advanced/storage). This 126 | transformation is straight-forward, but it requires that the node's runtime be able to understand 127 | the chain spec. 128 | 129 | If a node with an upgraded runtime attempts to synchronize a chain from genesis, it will not 130 | understand the information in this human-readable chain spec. For this reason, there is a second 131 | encoding of the chain spec known as the "raw" chain spec. 132 | 133 | When distributing chain specs in JSON format, they should be distributed in this raw format to 134 | ensure that all nodes can sync the chain even after runtime upgrades. Substrate-based nodes support 135 | the `--raw` flag to produce such raw chain specs. 136 | 137 | ```bash 138 | substrate build-spec --chain=myCustomSpec.json --raw > customSpecRaw.json 139 | ``` 140 | 141 | After the conversion process, the above snippet looks like this: 142 | 143 | ```json 144 | "0x50a63a871aced22e88ee6466fe5aa5d9": "0xd43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d", 145 | ``` 146 | 147 | ## Next Steps 148 | 149 | ### Learn More 150 | 151 | - Rustdocs for the 152 | [`ChainSpec` struct](https://crates.parity.io/sc_service/struct.GenericChainSpec.html) 153 | - Rustdocs for the 154 | [`ProtocolId` struct](https://crates.parity.io/sc_network/config/struct.ProtocolId.html) 155 | 156 | ### Examples 157 | 158 | - Gain hands-on experience with chain specs by 159 | [starting a private network](https://substrate.dev/docs/en/next/tutorials/start-a-private-network/). 160 | - The 161 | [Node Template's Chainspec](https://github.com/substrate-developer-hub/substrate-node-template/blob/master/src/chain_spec.rs) 162 | stored as rust code. 163 | -------------------------------------------------------------------------------- /current/integrate/libraries.md: -------------------------------------------------------------------------------- 1 | --- 2 | slug: libraries 3 | lang: en 4 | title: Client Libraries 5 | --- 6 | 7 | There are a number of language-specific client libraries that can be used to interact with 8 | Substrate-based blockchains. In general, the capabilities that these libraries expose are 9 | implemented on top of the Substrate remote procedure call (RPC) API. 10 | 11 | ## Javascript 12 | 13 | The Polkadot JS team maintains a rich set of tools for interacting with Substrate-based blockchains. 14 | Refer to [the main Polkadot JS page](./polkadot-js) to learn more about that suite of tools. 15 | 16 | Parity also maintains [`txwrapper`](https://github.com/paritytech/txwrapper), which is a Javascript 17 | library for offline generation of Substrate transactions. 18 | 19 | ## Go 20 | 21 | [The Go Substrate RPC Client](https://github.com/centrifuge/go-substrate-rpc-client/), AKA GSRPC, is 22 | maintained by [Centrifuge](https://centrifuge.io/). 23 | 24 | ## C 25 | 26 | [Polkadot API DotNet](https://github.com/usetech-llc/polkadot_api_dotnet) is a Substrate RPC client 27 | library for .Net programmers. It is maintained by [Usetech](https://usetech.com/blockchain/). 28 | 29 | ## C++ 30 | 31 | [Usetech](https://usetech.com/blockchain/) also maintains Polkadot API CPP, which is a C++ library 32 | for interacting with the Substrate RPC. 33 | 34 | ## Rust 35 | 36 | Parity maintains [`substrate-subxt`](https://github.com/paritytech/substrate-subxt), which is a Rust 37 | library specifically designed for submitting extrinsics to Substrate blockchains. The 38 | [the Substrate API Client](https://github.com/scs/substrate-api-client) is another Substrate client 39 | library for Rust that is maintained by Supercomputing Systems; its API is more general-purpose than 40 | `substrate-subxt`. 41 | -------------------------------------------------------------------------------- /current/integrate/polkadot-js.md: -------------------------------------------------------------------------------- 1 | --- 2 | slug: polkadot-js 3 | lang: en 4 | title: Polkadot-JS 5 | --- 6 | 7 | The Polkadot-JS project is a collection of tools, interfaces, and libraries around Polkadot and 8 | Substrate. 9 | 10 | > **Note:** While the project is named after "Polkadot", know that these tools, interfaces, and 11 | > libraries are fully compatible with any Substrate based chain. 12 | 13 | ## Polkadot-JS API 14 | 15 | The Polkadot-JS API is a library of interfaces for communicating with Polkadot and Substrate nodes. 16 | 17 | The API provides application developers the ability to query a node and interact with the Polkadot 18 | or Substrate chains using Javascript. 19 | 20 | Documentation 21 | GitHub 22 | 23 | ### Getting Started 24 | 25 | Developer documentation for the Polkadot-JS API can be found on their site. Follow the 26 | [Getting Started](https://polkadot.js.org/api/start/) guide to learn how to install and start using 27 | the Polkadot-JS API right away. 28 | 29 | ## Polkadot-JS Apps 30 | 31 | The Polkadot-JS Apps is a flexible UI for interacting with a Polkadot or Substrate based node. 32 | 33 | This is pre-built user-facing application, allowing access to all features available on Substrate 34 | chains. 35 | 36 | Open 37 | Apps 38 | GitHub 39 | 40 | TODO: Image 41 | 42 | ### Connecting to Local Node 43 | 44 | To connect the Polkadot-JS Apps to your local node, you must go into `Settings` and change the 45 | "endpoint to connect to" to `Local Node (127.0.0.1:9944)`. 46 | 47 | > **Note:** If you are connected to the Polkadot-JS Apps over a secure HTTPS connection, you will 48 | > need to use a browser which also supports bridging to an insecure WebSocket endpoint. For example, 49 | > Google Chrome supports this, but Mozilla Firefox does not. 50 | 51 | ## Polkadot-JS Extension 52 | 53 | The Polkadot-JS Extension is a simple proof-of-concept for managing accounts in a browser extension 54 | and allowing the signing of extrinsics using these accounts. It also provides simple interface for 55 | interacting with extension-compliant dApps. 56 | 57 | Install 58 | for Chrome 59 | Install 60 | for Firefox 61 | GitHub 62 | 63 | ## Next Steps 64 | 65 | 70 | 71 | ### Examples 72 | 73 | - Clone the 74 | [Substrate Front End Template](https://github.com/substrate-developer-hub/substrate-front-end-template) 75 | to start building a custom ReactJS app for your blockchain using Polkadot-JS API. 76 | 77 | ### References 78 | 79 | - Visit the reference docs for the [Polkadot-JS API](https://polkadot.js.org/api/) 80 | 81 | - Visit the reference docs for the [Polkadot-JS Common Utilities](https://polkadot.js.org/common/) 82 | -------------------------------------------------------------------------------- /current/learn-substrate/account-abstractions.md: -------------------------------------------------------------------------------- 1 | --- 2 | slug: account-abstractions 3 | lang: en 4 | title: Account Abstractions 5 | --- 6 | 7 | Substrate uses multiple sets of public/private key pairs to represent participants of the network. 8 | 9 | ## Overview 10 | 11 | Blockchain systems have participants in varying roles, for example from validators to normal users. 12 | 13 | As an example, the Substrate node uses a Nominated Proof-of-Stake (NPoS) algorithm to select 14 | validators. Validators and nominators may hold significant amounts of funds, so Substrate's Staking 15 | module introduces account abstractions that help keep funds as secure as possible. 16 | 17 | These abstractions are: 18 | 19 | - Accounts 20 | - Stash Key: The Stash account is meant to hold large amounts of funds. Its private key should be 21 | as secure as possible in a cold wallet. 22 | - Controller Key: The Controller account signals choices on behalf of the Stash account, like 23 | payout preferences, but should only hold a minimal amount of funds to pay transaction fees. Its 24 | private key should be secure as it can affect validator settings, but will be used somewhat 25 | regularly for validator maintenance. 26 | - Session Keys: Session keys are "hot" keys kept in the validator client and used for signing 27 | certain validator operations. They should never hold funds. 28 | 29 | > **Note:** Learn more about validators and nominators in the context of the Substrate's NPoS 30 | > [Staking module](https://crates.parity.io/pallet_staking/index.html). 31 | 32 | ## Account Keys 33 | 34 | A key pair can represent an account and control funds, like normal accounts that you would expect 35 | from other blockchains. In the context of Substrate 36 | [Balances module](https://crates.parity.io/pallet_balances/index.html), these accounts 37 | must have a minimum amount (an "existential deposit") to exist in storage. 38 | 39 | Account keys are defined generically and made concrete in the runtime. 40 | 41 | To continue with our example of Stash and Controller accounts, the keys to these accounts are 42 | distinguished by their intended use, not by any underlying cryptographic difference. When creating 43 | Stash or Controller keys, all cryptography supported for normal account keys are also supported. 44 | 45 | ### Stash Keys 46 | 47 | The Stash keys are the public/private key pair that defines a Stash account. This account is like a 48 | "savings account" in that you should not make frequent transactions from it. Therefore, its private 49 | key should be treated with the utmost security, for example protected in a safe or layers of 50 | hardware security. 51 | 52 | Since the Stash key is kept offline, it designates a Controller account to make non-spending 53 | decisions with the weight of the Stash account's funds. It can also designate a Proxy account to 54 | vote in governance on its behalf. 55 | 56 | ### Controller Keys 57 | 58 | The Controller keys are the public/private key pair that defines a Controller account. In the 59 | context of Substrate's NPoS model, the Controller key will signal one's intent to validate or 60 | nominate. 61 | 62 | The Controller key is used to set preferences like the rewards destination and, in the case of 63 | validators, to set their Session keys. The Controller account only needs to pay transaction fees, so 64 | it only needs a minimal amount of funds. 65 | 66 | The Controller key can never be used to spend funds from its Stash account. However, actions taken 67 | by the Controller can result in slashing, so it should still be well secured. 68 | 69 | ## Session Keys 70 | 71 | Session keys are "hot keys" that are used by validators to sign consensus-related messages. They are 72 | not meant to be used as account keys that control funds and should only be used for their intended 73 | purpose. They can be changed regularly; your Controller only needs to create a certificate by 74 | signing a session public key and broadcast this certificate via an extrinsic. Session keys are also 75 | defined generically and made concrete in the runtime. 76 | 77 | To create a Session key, validator operators must attest that a key acts on behalf of their Stash 78 | account (stake) and nominators. To do so, they create a certificate by signing the key with their 79 | Controller key. Then, they inform the chain that this key represents their Controller key by 80 | publishing the Session certificate in a transaction on the chain. 81 | 82 | Substrate provides the 83 | [Session module](https://crates.parity.io/pallet_session/index.html), which allows 84 | validators to manage their session keys. 85 | 86 | ### Strongly Typed Wrappers 87 | 88 | You can declare any number of Session keys. For example, the default Substrate node uses three for 89 | BABE, GRANDPA, and "I'm Online". Other chains could have more or fewer depending on what operations 90 | the chain expects its validators to perform. 91 | 92 | These different Session keys could use the same cryptography, but serve very different purposes 93 | throughout your runtime logic. To prevent the wrong key being used for the wrong operation, strong 94 | Rust types wrap these keys, keeping them incompatible with one another and ensuring they are only 95 | used for their intended purpose. 96 | 97 | ### Generation 98 | 99 | If a Session key is compromised, attackers could commit slashable behavior. Session keys should be 100 | changed regularly (e.g. every session) via 101 | [the `rotate_keys` RPC](https://crates.parity.io/sc_rpc/author/trait.AuthorApi.html#tymethod.rotate_keys) 102 | for increased security. 103 | 104 | ## Next Steps 105 | 106 | ### Learn More 107 | 108 | - Learn about the [cryptography used within Substrate](../advanced/cryptography). 109 | 110 | ### Examples 111 | 112 | - Follow our 113 | [tutorial to create a local network and generate keys](https://substrate.dev/docs/en/next/tutorials/start-a-private-network/). 114 | 115 | ### References 116 | 117 | - Visit the reference docs for the 118 | [session keys runtime API](https://crates.parity.io/sp_session/trait.SessionKeys.html). 119 | 120 | - Take a look at the default 121 | [session keys in the Substrate node runtime](https://crates.parity.io/node_runtime/struct.SessionKeys.html). 122 | 123 | - Take a look at 124 | [`substrate_application_crypto`](https://crates.parity.io/sp_application_crypto/index.html), 125 | used for constructing application specific strongly typed crypto wrappers. 126 | 127 | 128 | -------------------------------------------------------------------------------- /current/learn-substrate/extrinsics.md: -------------------------------------------------------------------------------- 1 | --- 2 | slug: extrinsics 3 | lang: en 4 | title: Extrinsics 5 | --- 6 | 7 | An extrinsic is a piece of information that comes from outside the chain and is included in a block. 8 | Extrinsics fall into three categories: inherents, signed transactions, and unsigned transactions. 9 | 10 | Note that [events](../runtime/events) are not extrinsics. The chain emits events for pieces of 11 | information that are intrinsic to the chain itself. For example, staking rewards are events, not 12 | extrinsics, because the reward is triggered by circumstances intrinsic to the chain's logic. 13 | 14 | ## Block Structure 15 | 16 | A block in Substrate is composed of a header and an array of extrinsics. The header contains a 17 | block height, parent hash, extrinsics root, state root, and digest. This section will only focus on 18 | the extrinsics root. 19 | 20 | Extrinsics are bundled together into a block as a series to be executed as each is defined in the 21 | runtime. The extrinsics root is a cryptographic digest of this series. This serves two purposes. 22 | First, it prevents any alterations to the series of extrinsics after the header has been built and 23 | distributed. Second, it provides a means of allowing light clients to succinctly verify that any 24 | given extrinsic did indeed exist in a block given only knowledge of the header. 25 | 26 | - [Block Reference](https://crates.parity.io/sp_runtime/traits/trait.Block.html) 27 | 28 | ## Inherents 29 | 30 | Inherents are pieces of information that are not signed and only inserted into a block by the block 31 | author. They are not gossiped on the network or stored in the transaction queue. There is nothing 32 | technically preventing a Substrate chain that gossips inherents, but there would be no fee-based 33 | spam prevention mechanism. 34 | 35 | Inherents represent data that, in an opinionated fashion, describes one of a number of valid pieces 36 | of information. They are assumed to be "true" simply because a sufficiently large number of 37 | validators have agreed on them being reasonable. 38 | 39 | For example, the author of the block may insert a timestamp inherent into the block. There is no way 40 | to prove that a timestamp is true the way the desire to send funds is proved with a signature. 41 | Rather, validators accept or reject the block based on how reasonable the other validators find the 42 | timestamp, which may mean it is within some acceptable range of their own system clocks. 43 | 44 | - [Inherents Reference](https://crates.parity.io/sp_inherents/index.html) 45 | 46 | ## Signed Transactions 47 | 48 | Signed transactions contain a signature of the account that issued the transaction and stands to pay 49 | a fee to have the transaction included on chain. Because the value of including signed transactions 50 | on-chain can be recognized prior to execution, they can be gossiped on the network between nodes 51 | with a low risk of spam. 52 | 53 | Signed transactions fit the concept of a transaction in Ethereum or Bitcoin. 54 | 55 | ## Unsigned Transactions 56 | 57 | Some cases call for unsigned transactions. Use unsigned transactions with care, as their validation 58 | logic can be difficult. 59 | 60 | Since the transaction is not signed, there is nobody to pay a fee. Because of this, the transaction 61 | queue lacks economic logic to prevent spam. Unsigned transactions also lack a nonce, making replay 62 | protection difficult. A few transactions warrant using the unsigned variant, but they will require 63 | some form of spam prevention based on a custom implementation of 64 | [signed extension](#signed-extension), which can exist on unsigned transactions. 65 | 66 | An example of unsigned transactions in Substrate is the [I'm Online](../runtime/frame#im-online) 67 | heartbeat transaction sent by authorities. The transaction includes a signature from a Session key, 68 | which does not control funds and therefore cannot pay a fee. The transaction pool controls spam by 69 | checking if a heartbeat has already been submitted in the session. 70 | 71 | ## Signed Extension 72 | 73 | `SignedExtension` is a trait by which a transaction can be extended with additional data or logic. 74 | Signed extensions are used anywhere you want some information about a transaction prior to 75 | execution. This is heavily used in the transaction queue. 76 | 77 | The runtime can use some of this data, for example the `Call` that will be dispatched, to calculate 78 | transaction fees. Signed extensions also include an `AdditionalSigned` type that can hold any 79 | encodable data, and therefore allow you to perform any custom logic prior to including or 80 | dispatching a transaction. The transaction queue regularly calls functions from `SignedExtension` to 81 | validate transactions prior to block construction to avoid including transactions that will fail in 82 | blocks. 83 | 84 | Despite the name, `SignedExtension` can also be used to verify unsigned transactions. The 85 | `*_unsigned` set of methods can be implemented to encapsulate validation, spam, and replay 86 | protection logic that is needed by the transaction pool. 87 | 88 | - [Signed Extension Reference](https://crates.parity.io/sp_runtime/traits/trait.SignedExtension.html) 89 | 90 | ## Further Reading 91 | 92 | - [Reference Documentation](https://crates.parity.io/sp_runtime/traits/trait.Extrinsic.html) 93 | - [Runtime Execution](../runtime/execution) 94 | - [Transaction Fees](../runtime/fees) 95 | - [Transaction Pool](../learn-substrate/tx-pool) 96 | -------------------------------------------------------------------------------- /current/learn-substrate/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | slug: index 3 | lang: en 4 | title: Overview 5 | --- 6 | 7 | This page is the top level entry point into the Substrate documentation. 8 | 9 | Substrate is a blockchain development framework with a completely generic State Transition Function 10 | (STF) and composable components for consensus, networking, and configuration. 11 | 12 | Despite being "completely generic", it comes with both standards and conventions - particularly with 13 | the Substrate runtime module library (a.k.a [FRAME](./runtime/frame)) - regarding the underlying 14 | data-structures that power the STF, thereby making rapid blockchain development a reality. 15 | 16 | ## Usage 17 | 18 | Substrate is designed to be used in one of three ways: 19 | 20 | 1. **With the Substrate Node**: You can run the pre-designed Substrate Node and configure it with a 21 | genesis block that includes the default node runtime. In this case, you just need to configure a 22 | JSON file and launch your own blockchain. This affords you the least amount of customization, 23 | only allowing you to change the genesis parameters of the included runtime modules such as: 24 | balances, staking, block-period, fees, governance, etc... For a tutorial on doing this, see 25 | [Start a Private Network with Substrate](https://substrate.dev/docs/en/next/tutorials/start-a-private-network/). 26 | 27 | 2. **With the Substrate FRAME**: You can easily create your own custom blockchain using the FRAME. 28 | This affords you a very large amount of freedom over your own blockchain's logic, letting you 29 | change datatypes, compose the library of modules, and add your own custom modules. Almost any 30 | blockchain can be made within FRAME, and the true power of Substrate lies here. If you want to 31 | dive right in, see the tutorial for 32 | [creating your first Substrate chain](https://substrate.dev/docs/en/next/tutorials/creating-your-first-substrate-chain/). 33 | 34 | 3. **With the Substrate Core**: The entire FRAME can be ignored, and the entire runtime can be 35 | designed and implemented from scratch. This could be done in _any language_ that can target 36 | WebAssembly. If the runtime can be made to be compatible with the abstract block authoring logic 37 | of the Substrate node, then you can simply construct a new genesis block from your Wasm blob and 38 | launch your chain with the existing Rust-based Substrate client. If not, then you will need to 39 | alter the client's block authoring logic, and potentially even alter the header and block 40 | serialization formats. In terms of development effort, this is by far the most difficult way to 41 | use Substrate, but also gives you the most freedom to innovate. 42 | 43 | ## Next Steps 44 | 45 | ### Learn More 46 | 47 | - View our developer documentation for 48 | [using the FRAME for module development](../runtime/frame). 49 | 50 | ### Examples 51 | 52 | - Follow our 53 | [tutorial to create your first custom blockchain with Substrate](https://substrate.dev/docs/en/next/tutorials/creating-your-first-substrate-chain/). 54 | 55 | - Follow our 56 | [tutorial to start a private network with Substrate](https://substrate.dev/docs/en/next/tutorials/start-a-private-network/). 57 | 58 | - Follow our 59 | [tutorial to build your first Substrate app](https://substrate.dev/docs/en/next/tutorials/build-a-dapp). 60 | 61 | ### References 62 | 63 | - Check out [Rust reference documentation](https://crates.parity.io). 64 | -------------------------------------------------------------------------------- /current/learn-substrate/off-chain-workers.md: -------------------------------------------------------------------------------- 1 | --- 2 | slug: off-chain-workers 3 | lang: en 4 | title: Off-Chain Workers 5 | --- 6 | 7 | ## Overview 8 | 9 | There is often a need to query and/or process off-chain data before it can be included in the 10 | on-chain state. The conventional way of doing this is through oracles. Oracles are external services 11 | that typically listen to blockchain events and trigger tasks accordingly. When these tasks complete, 12 | their results are submitted back to the blockchain using transactions. While this approach works, it 13 | still has several flaws with respect to security, scalability, and infrastructure efficiency. 14 | 15 | To make the off-chain data integration secure and more efficient, Substrate provides off-chain 16 | workers. The off-chain worker subsystem allows execution of long-running and possibly non- 17 | deterministic tasks (e.g. web requests, encryption/decryption and signing of data, random number 18 | generation, CPU-intensive computations, enumeration/aggregation of on-chain data, etc.) that could 19 | otherwise require longer than the block execution time. 20 | 21 | Off-chain workers have their own Wasm execution environment outside of the Substrate runtime. This 22 | separation of concerns is to make sure that the block production is not impacted by the long-running 23 | tasks. However, as the off-chain workers are declared in the same code as the runtime, they can 24 | easily access on-chain state for their computations. 25 | 26 | ![Off-chain Workers](../assets/off-chain-workers-v2.png) 27 | 28 | ## APIs 29 | 30 | Off-chain workers have access to extended APIs for communicating with the external world: 31 | 32 | - Ability to submit transactions (either signed or unsigned) to the chain to publish computation 33 | results. 34 | - A fully-featured HTTP client allowing the worker to access and fetch data from external services. 35 | - Access to the local keystore to sign and verify statements or transactions. 36 | - An additional, local key-value database shared between all off-chain workers. 37 | - A secure, local entropy source for random number generation. 38 | - Access to the node's precise local time and the ability to sleep and resume work. 39 | 40 | Off-chain workers can be initiated from within a special function in your runtime implementation, 41 | `fn offchain_worker(block: T::BlockNumber)`. The function is executed after each block import. To 42 | communicate results back to the chain, off-chain workers can submit signed or unsigned transactions 43 | to be included in subsequent blocks. 44 | 45 | Note that the results from off-chain workers are not subject to regular transaction verification. A 46 | verification mechanism (e.g. voting, averaging, checking sender signatures, or simply "trusting") 47 | should be implemented to determine what information gets into the chain. 48 | 49 | For more information on how to use off-chain workers in your next runtime development project, 50 | please refer to our [Development Guide](../runtime/off-chain-workers). 51 | 52 | 53 | -------------------------------------------------------------------------------- /current/learn-substrate/session-keys.md: -------------------------------------------------------------------------------- 1 | --- 2 | slug: session-keys 3 | lang: en 4 | title: Session Keys 5 | --- 6 | 7 | Session keys are used by validators to sign consensus-related messages. `SessionKeys` is a generic, 8 | indexable type that is made concrete in the runtime. 9 | 10 | You can declare any number Session keys. For example, the default Substrate node uses four. Other 11 | chains could have more or fewer depending on what operations the chain expects its validators to 12 | perform. 13 | 14 | In practice, validators amalgamate all of the session public keys into a single object, sign the set 15 | of public keys with a "Controller" account, and submit a transaction to register the keys on chain. 16 | This on-chain registration links a validator _node_ with an _account_ that holds funds. As such, 17 | that account can be credited with rewards or slashed based on the node's behavior. 18 | 19 | The runtime declares what session keys will be included (`runtime/src/lib.rs`): 20 | 21 | ```rust 22 | impl_opaque_keys! { 23 | pub struct SessionKeys { 24 | pub grandpa: Grandpa, 25 | pub babe: Babe, 26 | pub im_online: ImOnline, 27 | pub authority_discovery: AuthorityDiscovery, 28 | } 29 | } 30 | ``` 31 | 32 | The actual cryptographic curve that each key uses gets defined in `primitives`. For example, BABE's 33 | key uses sr25519: 34 | 35 | ```rust 36 | mod app { 37 | use sp_application_crypto::{app_crypto, key_types::BABE, sr25519}; 38 | app_crypto!(sr25519, BABE); 39 | } 40 | ``` 41 | 42 | > This code is just an example of the Substrate node at the 43 | > [time of writing](https://github.com/paritytech/substrate/tree/9fa8589d9b8cfe8716e9e4c48f9e3f238c1e502f). 44 | > Refer to the runtime for the most up-to-date implementation. 45 | 46 | The default Substrate node implements Session keys in the 47 | [Session pallet](https://crates.parity.io/pallet_session/index.html). 48 | 49 | ## Generation and Use 50 | 51 | Session keys are hot keys that must be kept online. The individual keys should **not** be used to 52 | control funds. All the logic for handling session keys is in the Substrate client, primitives, and 53 | Session pallet. If one of the Session keys is compromised, the attacker could commit slashable 54 | behavior. 55 | 56 | Session keys may be changed regularly (e.g. every session) for increased security. Node operators 57 | can generate them via the RPC call 58 | [`author_rotateKeys`](https://crates.parity.io/sc_rpc/author/trait.AuthorApi.html#tymethod.rotate_keys). 59 | You will then need to register the new keys on chain with a `session.setKeys` transaction. 60 | -------------------------------------------------------------------------------- /current/learn-substrate/tx-pool.md: -------------------------------------------------------------------------------- 1 | --- 2 | slug: tx-pool 3 | lang: en 4 | title: Transaction Pool 5 | --- 6 | 7 | The transaction pool contains all transactions (signed and unsigned) broadcasted to the network that 8 | have been received and validated by the local node. 9 | 10 | **Validity** 11 | 12 | The transaction pool checks for transaction validity. Note that `validity` of the transaction is not 13 | hard-wired to the transaction pool, but is defined by the runtime. Example validity checks are: 14 | 15 | - Checking if the Transaction Index (nonce) is correct. 16 | - Checking if the account has enough funds to pay for the associated fees. 17 | - Checking if the signature is valid. 18 | 19 | The transaction pool also regularly checks validity of existing transactions within the pool. A 20 | transaction will be dropped from the pool if an invalid or expired mortal transaction is found. 21 | 22 | **Sorting** 23 | 24 | If the transaction is valid, the transaction queue sorts transactions into two groups: 25 | 26 | - _Ready Queue_ - Contains transactions that can be included in a new pending block. For runtimes 27 | built with FRAME, the transactions must follow the exact order in the ready queue. 28 | - _Future Queue_ - Contains transactions that may become valid in the future. For example, a 29 | transaction may have a `nonce` that is too high for its account. This transaction will wait in the 30 | future queue until the preceding transactions are included in the chain. 31 | 32 | Note: It's possible to design a custom runtime to remove the strict transaction ordering 33 | requirement. This would allow full nodes to implement different strategies on transaction 34 | propagation and block inclusion. 35 | 36 | ## Transaction Dependencies 37 | 38 | The `ValidTransaction` 39 | [struct](https://crates.parity.io/sp_runtime/transaction_validity/struct.ValidTransaction.html) 40 | defines the `requires` and `provides` parameters to build a dependency graph of transactions. 41 | Together with `priority` (discussed below), this dependency graph allows the pool to produce a valid 42 | linear ordering of transactions. 43 | 44 | For runtimes built with FRAME, the nodes order transactions with an account-based system. Every 45 | signed transaction needs to contain a nonce, which is incremented by 1 every time a new transaction 46 | is made. For example, the first transaction from a new account will have `nonce = 0` and the second 47 | transaction will have `nonce = 1`. 48 | 49 | At minimum, FRAME transactions have a `provides` tag of `encode(sender ++ nonce)` and a `requires` 50 | tag of `encode(sender ++ (nonce -1)) if nonce > 1`. Transactions do not require anything if 51 | `nonce=0`. As a result, all transactions coming from a single sender will form a sequence in which 52 | they should be included. 53 | 54 | Substrate supports multiple `provides` and `requires` tags, so custom runtimes can create alternate 55 | dependency (ordering) schemes. 56 | 57 | ## Transaction Priority 58 | 59 | Transaction `priority` in the `ValidTransaction` 60 | [struct](https://crates.parity.io/sp_runtime/transaction_validity/struct.ValidTransaction.html) 61 | determines the ordering of transactions that are in the ready queue. If a node is the next block 62 | author, it will order transactions from high to low priority in the next block until it reaches the 63 | weight or length limit of the block. 64 | 65 | `priority` defines the linear ordering of a graph in the case of one transaction unlocking multiple 66 | dependent transactions. For example, if we have two (or more) transactions that have their 67 | dependencies satisfied, then we use `priority` to choose the order for them. 68 | 69 | For runtimes built with FRAME, `priority` is defined as the `fee` that the transaction is going to 70 | pay. For example: 71 | 72 | - If we receive 2 transactions from _different_ senders (with `nonce=0`), we use `priority` to 73 | determine which transaction is more important and included in the block first. 74 | - If we receive 2 transactions from the _same_ sender with an identical `nonce`, only one 75 | transaction can be included on-chain. We use `priority` to choose the transaction with a higher 76 | `fee` to store in the transaction pool. 77 | 78 | Note that the pool does not know about fees, accounts, or signatures - it only deals with the 79 | validity of the transaction and the abstract notion of the `priority`, `requires`, and `provides` 80 | parameters. All other details are defined by the runtime via the `validate_transaction` function. 81 | 82 | ## Transaction Lifecycle 83 | 84 | A transaction can follow two paths: 85 | 86 | ### Block Produced by our Node 87 | 88 | 1. Our node listens for transactions on the network. 89 | 2. Each transaction is verified and valid transactions are placed in the transaction pool. 90 | 3. The pool is responsible for ordering the transactions and returning ones that are ready to be 91 | included in the block. Transactions in the ready queue are used to construct a block. 92 | 4. Transactions are executed and state changes are stored in local memory. Transactions from the 93 | `ready` queue are also propagated (gossiped) to peers over the network. We use the exact ordering 94 | as the pending block since transactions in the front of the queue have a higher priority and are 95 | more likely to be successfully executed in the next block. 96 | 5. The constructed block is published to the network. All other nodes on the network receive and 97 | execute the block. 98 | 99 | Note that transactions are not removed from the ready queue when blocks are authored, but removed 100 | _only_ on block import. This is due to the possibility that a recently-authored block may not make 101 | it into the canonical chain. 102 | 103 | ### Block Received from Network 104 | 105 | The block is executed and the entire block either succeeds or fails. 106 | 107 | ## Transaction Validity 108 | 109 | `validate_transaction` is called from the runtime, checks for a valid signature and nonce (or output 110 | for a UTXO chain) and returns a `Result`. `validate_transaction` checks transactions in isolation, 111 | so it will not catch errors like the same output being spent twice. 112 | 113 | Although it is possible, `validate_transaction` does not check whether calls to pallets will 114 | succeed. It is a potential DoS vector since all transactions in the network will be passed into 115 | `validate_transaction`. 116 | 117 | The `validate_transaction` function should focus on providing the necessary information for the pool 118 | to order and prioritize transactions, and quickly reject all transactions that are invalid or 119 | outdated. The function will be called frequently, potentially multiple times for the same 120 | transaction. It is also possible for `validate_transaction` to fail a dependent transaction that 121 | would pass `execute_block` if it were executed in the correct order. 122 | 123 | ## Further Reading 124 | 125 | - [Extrinsics](extrinsics) 126 | - [Transaction Fees](../runtime/fees) 127 | -------------------------------------------------------------------------------- /current/learn-substrate/weight.md: -------------------------------------------------------------------------------- 1 | --- 2 | slug: weight 3 | lang: en 4 | title: Transaction Weight 5 | --- 6 | 7 | Resources available to chains are limited. The resources include memory usage, storage I/O, 8 | computation, transaction/block size and state database size. There are several mechanisms to manage 9 | access to resources and to prevent individual components of the chain from consuming too much of any 10 | resource. Weights are the mechanism used to manage the _time is takes to validate_ a block. 11 | Generally speaking, this comes from limiting the storage I/O and computation. 12 | 13 | NOTE: Weights are not used to restrict access to other resources, such as storage itself or memory 14 | footprint. Other mechanisms must be used for this. 15 | 16 | The amount of weight a block may contain is limited, and optional weight consumption (i.e. weight 17 | that is not required to be deployed as part of the block's initialization or finalization phases nor 18 | used in mandatory inherent extrinsics) will generally be limited through economic measures --- or in 19 | simple terms, through transaction fees. The fee implications of the weight system are covered in the 20 | [Transaction Fees document](../runtime/fees). 21 | 22 | Substrate defines one unit of weight as one picosecond of execution time on fixed reference hardware 23 | (Intel Core i7-7700K CPU with 64GB of RAM and an NVMe SSD). Benchmarking on reference hardware makes 24 | weights comparable across runtimes, which allows composability of software components from different 25 | sources. In order to tune a runtime for different validator hardware assumptions, you can set a 26 | different maximum block weight. For example, in order to allow validators to participate that are 27 | only half as fast as the reference machine, the maximum block weight should be half of the default, 28 | keeping the default block time. 29 | 30 | The maximum block weight should be equivalent to one-third of the target block time, allocating one 31 | third for block construction, one third for network propagation, and one third for import and 32 | verification. Doubling the block time would allow a doubling of the maximum block weight. These 33 | tuning options give runtime developers a way to make the optimal transaction per second vs. hardware 34 | requirement trade-offs for their use case. These trade-offs can be tuned with runtime updates to 35 | keep up with hardware and software improvements. 36 | 37 | ## Weight Fundamentals 38 | 39 | Weights represent the _limited_ time that your blockchain has to validate a block. This includes 40 | computational cycles, and storage I/O. A custom implementation may use complex structures to express 41 | this. Substrate weights are simply a 42 | [numeric value](https://crates.parity.io/frame_support/weights/type.Weight.html). 43 | 44 | A weight calculation should always: 45 | 46 | - Be computable **ahead of dispatch**. A block producer should be able to examine the weight of a 47 | dispatchable before actually deciding to accept it or not. 48 | - Consume few resources itself. It does not make sense to consume similar resources computing a 49 | transaction's weight as would be spent to execute it. Thus, weight computation should be much 50 | lighter than dispatch. 51 | - Be able to determine resources used without consulting on-chain state. Weights are good at 52 | representing _fixed_ measurements or measurements based solely on the parameters of the 53 | dispatchable function where no expensive I/O is necessary. Weights are not so useful when the cost 54 | is dependent on the chain-state. 55 | 56 | In the case that the weight of a dispatchable is heavily dependent on chain-state case, two options 57 | are available: 58 | 59 | - Determine or introduce a forced upper limit to the amount of weight a dispatchable could possibly 60 | take. If the difference between the enforced upper limit and the least possible amount of weight a 61 | dispatchable could take is small, then it can just be assumed to always be at the upper limit of 62 | the weight without consulting the state. If the difference is too great, however, then the 63 | economic cost of making lesser transactions might be too great which will warp the incentives and 64 | create inefficiencies in throughput. 65 | - Require the effective weight (or precursors that can be used to efficiently compute it) be passed 66 | in as parameters to the dispatch. The weight charged should be based on these parameters but also 67 | cover the amount of time it takes to verify them during dispatch. Verification must take place to 68 | ensure the weighing parameters correspond accurately to on-chain state and if they don't then the 69 | operation should gracefully error. 70 | 71 | ### Weight Factors 72 | 73 | Several factors impact execution time, and therefore weight calculation. One large contributor is 74 | the number of database accesses that are performed by a dispatchable. Because the cost of a database 75 | access is greatly dependent on the database backend and storage hardware, the weight calculations 76 | are parameterized over the weight costs of database reads and writes. These costs are determined by 77 | benchmarking each available database backend on some reference hardware. This allows switching 78 | database backends without changing all weight calculations. 79 | 80 | In addition to only using constants for the pre-dispatch weight calculation, the developer has the 81 | ability to factor in the input parameters of the given dispatchable. This can be useful when the 82 | execution time depends on, for example, the length of one parameter. It is important that these 83 | calculations do not entail any meaningful work themselves. The pre-dispatch maximum weight should be 84 | trivially computable from the input arguments with some basic arithmetic. 85 | 86 | The [System pallet](https://crates.parity.io/frame_system/struct.Module.html) is 87 | responsible for accumulating the weight of each block as it gets executed and making sure that it 88 | does not exceed the limit. The 89 | [Transaction Payment pallet](https://crates.parity.io/pallet_transaction_payment/index.html) 90 | is responsible for interpreting these weights and deducting fees based upon them. The weighing 91 | function is part of the runtime so it can be upgraded if needed. 92 | 93 | ## Post Dispatch Weight Correction 94 | 95 | There are cases where the actual weight of a dispatchable is not trivially computable from its 96 | inputs. For example, the weight could depend on the logic path of the dispatchable. Without any 97 | means of correcting the weight after dispatch, we would constantly overestimate and subsequently 98 | overcharge for those dispatchables as we must assume the worst case ahead of dispatch for the chain 99 | to be safe. 100 | 101 | The post-dispatch weight correction allows any dispatchable to return its _actual weight_ after it 102 | was executed. This weight must be less than or equal to the pre-dispatch worst case weight. For a 103 | user to be allowed to include an extrinsic, they still must be able to pay for the maximum weight, 104 | even though the final payment will be based on the actual weight. 105 | 106 | ## Block Weight and Length Limit 107 | 108 | Aside from affecting fees, the main purpose of the weight system is to prevent a block from being 109 | filled with transactions that would take too long to execute. While processing transactions within a 110 | block, the System pallet accumulates both the total length of the block (sum of encoded transactions 111 | in bytes) and the total weight of the block. If either of these numbers surpass the limits, no 112 | further transactions are accepted in that block. These limits are defined in 113 | [`MaximumBlockLength`](https://crates.parity.io/frame_system/trait.Trait.html#associatedtype.MaximumBlockLength) 114 | and 115 | [`MaximumBlockWeight`](https://crates.parity.io/frame_system/trait.Trait.html#associatedtype.MaximumBlockWeight). 116 | 117 | One important note about these limits is that a portion of them are reserved for the `Operational` 118 | dispatch class. This rule applies to both of the limits and the ratio can be found in 119 | [`AvailableBlockRatio`](https://crates.parity.io/frame_system/trait.Trait.html#associatedtype.AvailableBlockRatio). 120 | 121 | For example, if the block length limit is 1 megabyte and the ratio is set to 80%, all transactions 122 | can fill the first 800 kilobytes of the block while the last 200 can only be filled by the 123 | operational class. 124 | 125 | There is also a `Mandatory` dispatch class that can be used to ensure an extrinsic is always 126 | included in a block regardless of its impact on block weight. Please refer to the 127 | [Transaction Fees document](../runtime/fees) to learn more about the different dispatch classes and 128 | when to use them. 129 | 130 | ## Next Steps 131 | 132 | ### Learn More 133 | 134 | - Substrate Recipes contains examples of both 135 | [custom weights](https://github.com/substrate-developer-hub/recipes/tree/master/pallets/weights) 136 | and custom 137 | [WeightToFee](https://github.com/substrate-developer-hub/recipes/tree/master/runtimes/weight-fee-runtime). 138 | - The [Example](https://github.com/paritytech/substrate/blob/master/frame/example/src/lib.rs) 139 | pallet. 140 | 141 | ### Examples 142 | 143 | - See an example of 144 | [adding a transaction weight](https://substrate.dev/recipes/3-entrees/weights.html) to a custom 145 | runtime function. 146 | 147 | ### References 148 | 149 | - [Transaction Payment pallet](https://github.com/paritytech/substrate/blob/master/frame/transaction-payment/src/lib.rs) 150 | - [Weights](https://github.com/paritytech/substrate/blob/master/frame/support/src/weights.rs) 151 | -------------------------------------------------------------------------------- /current/runtime/debugging.md: -------------------------------------------------------------------------------- 1 | --- 2 | slug: debugging 3 | lang: en 4 | title: Debugging 5 | --- 6 | 7 | Debugging is a necessity in all walks of software development, and blockchain is no exception. Most 8 | of the same tools used for general purpose Rust debugging also apply to Substrate. However, there 9 | are some restrictions when operating inside of a `no_std` environment like the Substrate runtime. 10 | 11 | ## Substrate's Own `print` Function 12 | 13 | To facilitate the debugging of the runtime, Substrate provides extra tools for `Print` debugging (or 14 | tracing). You can use the 15 | [`print` function](https://crates.parity.io/sp_runtime/fn.print.html) to log the status 16 | of the runtime execution. 17 | 18 | ```rust 19 | use sp_runtime::print; 20 | 21 | // --snip-- 22 | pub fn do_something(origin) -> DispatchResult { 23 | print("Execute do_something"); 24 | 25 | let who = ensure_signed(origin)?; 26 | let my_val: u32 = 777; 27 | 28 | Something::put(my_val); 29 | 30 | print("After storing my_val"); 31 | 32 | Self::deposit_event(RawEvent::SomethingStored(my_val, who)); 33 | Ok(()) 34 | } 35 | // --snip-- 36 | ``` 37 | 38 | Start the chain using the `RUST_LOG` environment variable to see the print logs. 39 | 40 | ```sh 41 | RUST_LOG=runtime=debug ./target/release/node-template --dev 42 | ``` 43 | 44 | The values are printed in the terminal or the standard output if the Error gets triggered. 45 | 46 | ```sh 47 | 2020-01-01 00:00:00 tokio-blocking-driver DEBUG runtime Execute do_something 48 | 2020-01-01 00:00:00 tokio-blocking-driver DEBUG runtime After storing my_val 49 | ``` 50 | 51 | ## Printable Trait 52 | 53 | The Printable trait is meant to be a way to print from the runtime in `no_std` and in `std`. The 54 | `print` function works with any type that implements the 55 | [`Printable` trait](https://crates.parity.io/sp_runtime/traits/trait.Printable.html). 56 | Substrate implements this trait for some types (`u8`, `u32`, `u64`, `usize`, `&[u8]`, `&str`) by 57 | default. You can also implement it for your own custom types. Here is an example of implementing it 58 | for a pallet's `Error` type using the node-template as the example codebase. 59 | 60 | ```rust 61 | use sp_runtime::traits::Printable; 62 | use sp_runtime::print; 63 | ``` 64 | 65 | ```rust 66 | // The pallet's errors 67 | decl_error! { 68 | pub enum Error for Module { 69 | /// Value was None 70 | NoneValue, 71 | /// Value reached maximum and cannot be incremented further 72 | StorageOverflow, 73 | } 74 | } 75 | 76 | impl Printable for Error { 77 | fn print(&self) { 78 | match self { 79 | Error::NoneValue => "Invalid Value".print(), 80 | Error::StorageOverflow => "Value Exceeded and Overflowed".print(), 81 | _ => "Invalid Error Case".print(), 82 | } 83 | } 84 | } 85 | ``` 86 | 87 | ```rust 88 | /// takes no parameters, attempts to increment storage value, and possibly throws an error 89 | pub fn cause_error(origin) -> dispatch::DispatchResult { 90 | // Check it was signed and get the signer. See also: ensure_root and ensure_none 91 | let _who = ensure_signed(origin)?; 92 | 93 | print("My Test Message"); 94 | 95 | match Something::get() { 96 | None => { 97 | print(Error::::NoneValue); 98 | Err(Error::::NoneValue)? 99 | } 100 | Some(old) => { 101 | let new = old.checked_add(1).ok_or( 102 | { 103 | print(Error::::StorageOverflow); 104 | Error::::StorageOverflow 105 | })?; 106 | Something::put(new); 107 | Ok(()) 108 | }, 109 | } 110 | } 111 | ``` 112 | 113 | Run the node binary with the RUST_LOG environment variable to print the values. 114 | 115 | ```sh 116 | RUST_LOG=runtime=debug ./target/release/node-template --dev 117 | ``` 118 | 119 | The values are printed in the terminal or the standard output every time that the runtime function 120 | gets called. 121 | 122 | ```rust 123 | 2020-01-01 tokio-blocking-driver DEBUG runtime My Test Message <-- str implements Printable by default 124 | 2020-01-01 tokio-blocking-driver DEBUG runtime Invalid Value <-- the custom string from NoneValue 125 | 2020-01-01 tokio-blocking-driver DEBUG runtime DispatchError 126 | 2020-01-01 tokio-blocking-driver DEBUG runtime 8 127 | 2020-01-01 tokio-blocking-driver DEBUG runtime 0 <-- index value from the Error enum definition 128 | 2020-01-01 tokio-blocking-driver DEBUG runtime NoneValue <-- str which holds the name of the ident of the error 129 | ``` 130 | 131 | > IMPORTANT: Adding many print functions to the runtime will produce a bigger binary and wasm blob 132 | > with debug code not needed in production. 133 | 134 | ## If Std 135 | 136 | The `print` function works well when you just want to print and you have an implementation of the 137 | `Printable` trait. In some cases you may want to do more than print, or not bother with 138 | Substrate-specific traits just for debugging purposes. The 139 | [`if_std!` macro](https://crates.parity.io/sp_std/macro.if_std.html) is for exactly 140 | this situation. 141 | 142 | One caveat of using this macro is that the code inside will only execute when you are actually 143 | running the native version of the runtime. 144 | 145 | ```rust 146 | use sp_std::if_std; // Import into scope the if_std! macro. 147 | ``` 148 | 149 | The `println!` statement should be inside of the `if_std` macro. 150 | 151 | ```rust 152 | decl_module! { 153 | 154 | // --snip-- 155 | pub fn do_something(origin) -> DispatchResult { 156 | 157 | let who = ensure_signed(origin)?; 158 | let my_val: u32 = 777; 159 | 160 | Something::put(my_val); 161 | 162 | if_std! { 163 | // This code is only being compiled and executed when the `std` feature is enabled. 164 | println!("Hello native world!"); 165 | println!("My value is: {:#?}", my_val); 166 | println!("The caller account is: {:#?}", who); 167 | } 168 | 169 | Self::deposit_event(RawEvent::SomethingStored(my_val, who)); 170 | Ok(()) 171 | } 172 | // --snip-- 173 | } 174 | ``` 175 | 176 | The values are printed in the terminal or the standard output every time that the runtime function 177 | gets called. 178 | 179 | ```sh 180 | $ 2020-01-01 00:00:00 Substrate Node 181 | 2020-01-01 00:00:00 version x.y.z-x86_64-linux-gnu 182 | 2020-01-01 00:00:00 by Anonymous, 2017, 2020 183 | 2020-01-01 00:00:00 Chain specification: Development 184 | 2020-01-01 00:00:00 Node name: my-node-007 185 | 2020-01-01 00:00:00 Roles: AUTHORITY 186 | 2020-01-01 00:00:00 Imported 999 (0x3d7a…ab6e) 187 | # --snip-- 188 | -> Hello native world! 189 | -> My value is: 777 190 | -> The caller account is: d43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d (5GrwvaEF...) 191 | # --snip-- 192 | 2020-01-01 00:00:00 Imported 1000 (0x3d7a…ab6e) 193 | 194 | ``` 195 | -------------------------------------------------------------------------------- /current/runtime/events.md: -------------------------------------------------------------------------------- 1 | --- 2 | slug: events 3 | lang: en 4 | title: Runtime Events 5 | --- 6 | 7 | A Substrate runtime module can emit events when it wants to notify external entities about changes 8 | or conditions in the runtime to external entities like users, chain explorers, or dApps. 9 | 10 | You can define what events your module emits, what information is contained within those events, and 11 | when those events are emitted. 12 | 13 | ## Declaring an Event 14 | 15 | Runtime events are created with the `decl_event!` macro. 16 | 17 | ```rust 18 | decl_event!( 19 | pub enum Event where AccountId = ::AccountId { 20 | /// Set a value. 21 | ValueSet(u32, AccountId), 22 | } 23 | ); 24 | ``` 25 | 26 | The `Event` enum needs to be declared in your runtime's configuration trait. 27 | 28 | ```rust 29 | pub trait Trait: system::Trait { 30 | type Event: From> + Into<::Event>; 31 | } 32 | ``` 33 | 34 | ## Exposing Events to Your Runtime 35 | 36 | The events for your module need to be exposed to your Substrate's runtime (`/runtime/src/lib.rs`). 37 | 38 | First you need to implement the Event type in your module's configuration trait: 39 | 40 | ```rust 41 | // runtime/src/lib.rs 42 | impl template::Trait for Runtime { 43 | type Event = Event; 44 | } 45 | ``` 46 | 47 | Then you need to add the `Event` type to your `construct_runtime!` macro: 48 | 49 | ```rust 50 | // runtime/src/lib.rs 51 | construct_runtime!( 52 | pub enum Runtime where 53 | Block = Block, 54 | NodeBlock = opaque::Block, 55 | UncheckedExtrinsic = UncheckedExtrinsic 56 | { 57 | // --snip-- 58 | TemplateModule: template::{Module, Call, Storage, Event}, 59 | //--add-this------------------------------------->^^^^^^^^ 60 | } 61 | ); 62 | ``` 63 | 64 | > **Note:** You may or may not need the `` parameter depending on whether your events use generic 65 | > types. In our example it does, and is included above. 66 | 67 | ## Depositing an Event 68 | 69 | Substrate provides a default implementation of how to deposit an event that is defined in the 70 | `decl_module!` macro. 71 | 72 | ```rust 73 | decl_module! { 74 | pub struct Module for enum Call where origin: T::Origin { 75 | // Default implementation of `deposit_event` 76 | fn deposit_event() = default; 77 | 78 | fn set_value(origin, value: u64) { 79 | let sender = ensure_signed(origin)?; 80 | // --snip-- 81 | Self::deposit_event(RawEvent::ValueSet(value, sender)); 82 | } 83 | } 84 | } 85 | ``` 86 | 87 | The default behavior of this function is to call 88 | [`deposit_event`](https://crates.parity.io/frame_system/struct.Module.html#method.deposit_event) 89 | from the FRAME system, which writes the event to storage. 90 | 91 | This function places the event in the System module's runtime storage for that block. At the 92 | beginning of a new block, the System module automatically removes all events that were stored from 93 | the previous block. 94 | 95 | Events deposited using the default implementation will be directly supported by downstream libraries 96 | like the [Polkadot-JS api](../integrate/polkadot-js), however you can implement your own 97 | `deposit_event` function if you want to handle events differently. 98 | 99 | ## Supported Types 100 | 101 | Events can emit any type which supports the [Parity SCALE codec](../advanced/codec). 102 | 103 | In the case where you want to use Runtime generic types like `AccountId` or `Balances`, you need to 104 | include a [`where` clause](https://doc.rust-lang.org/rust-by-example/generics/where.html) to define 105 | those types as shown in the example above. 106 | 107 | ## Listening To Events 108 | 109 | The Substrate RPC does not directly expose an endpoint for querying events. If you used the default 110 | implementation, you can see the list of events for the current block by querying the storage of the 111 | System module. Otherwise, the [Polkadot-JS api](../integrate/polkadot-js) supports a WebSocket 112 | subscription on runtime events. 113 | 114 | ## Next Steps 115 | 116 | ### Learn More 117 | 118 | - Learn more about the [macros](macros) used in Substrate runtime development. 119 | - Learn more about using the [Polkadot JS api](../integrate/polkadot-js). 120 | 121 | ### Examples 122 | 123 | These [Substrate Recipes](https://github.com/substrate-developer-hub/recipes) offer examples of how 124 | runtime events are used: 125 | 126 | - [A pallet that implements standard events](https://github.com/substrate-developer-hub/recipes/blob/master/pallets/last-caller/src/lib.rs) 127 | - [A pallet that does not emit events with generic types](https://github.com/substrate-developer-hub/recipes/blob/master/pallets/adding-machine/src/lib.rs) 128 | 129 | ### References 130 | 131 | - [`decl_event!` macro](https://crates.parity.io/frame_support/macro.decl_event.html) 132 | - [`decl_module!` macro](https://crates.parity.io/frame_support/macro.decl_module.html) 133 | - [`construct_runtime!` macro](https://crates.parity.io/frame_support/macro.construct_runtime.html) 134 | -------------------------------------------------------------------------------- /current/runtime/execution.md: -------------------------------------------------------------------------------- 1 | --- 2 | slug: execution 3 | lang: en 4 | title: Runtime Execution 5 | --- 6 | 7 | The execution of the Substrate runtime is orchestrated by the Executive module. 8 | 9 | Unlike the other modules within FRAME, this is not a _runtime_ module, but just a normal Rust module 10 | that calls into the various runtime modules included in your blockchain. 11 | 12 | The Executive module exposes the `execute_block` function that: 13 | 14 | - [Initializes the block](#initializing-a-block) 15 | - [Executes extrinsics](#executing-extrinsics) 16 | - [Finalizes the block](#finalizing-a-block) 17 | 18 | ## Validating Transactions 19 | 20 | Before block execution begins, signed transaction are checked for validity. This doesn't execute any 21 | side-effects; it merely checks whether the transaction would panic if it were included or not. Thus, 22 | changes made to storage are discarded. 23 | 24 | ## Executing a Block 25 | 26 | Once there is a queue of valid transactions, the Executive module begins to execute the block. 27 | 28 | ### Initializing a Block 29 | 30 | To initialize a block, the System module and all other included runtime modules have their 31 | `on_initialize` function called which executes any business logic defined by those modules to take 32 | place before transactions are executed. The modules are executed in the order which they are defined 33 | in the `construct_runtime!` macro, but with the System module always executing first. 34 | 35 | Then, initial checks take place where the parent hash in the block header is verified to be correct 36 | and the extrinsics trie root actually represents the extrinsics. 37 | 38 | ### Executing Extrinsics 39 | 40 | After the block has been initialized, each valid extrinsic is executed in order of transaction 41 | priority. Extrinsics must not cause a panic in the runtime logic or else the system becomes 42 | vulnerable to attacks where users can trigger computational execution without any punishment. 43 | 44 | When an extrinsic executes, the state is not cached prior to execution and storage mutations operate 45 | directly on storage. Therefore, runtime developers should perform all necessary checks that an 46 | extrinsic will succeed before mutating storage. If an extrinsic fails mid-execution, previous 47 | storage mutations will not be reverted. 48 | 49 | [Events](events) that are emitted from an extrinsic are also written to storage. Therefore, you 50 | should not emit an event before performing the complementary actions. If an extrinsic fails after an 51 | event is emitted, the event will not be reverted. 52 | 53 | ### Finalizing a Block 54 | 55 | After all queued extrinsics have been executed, the Executive module calls into each module's 56 | `on_finalize` function to perform any final business logic which should take place at the end of the 57 | block. The modules are again executed in the order which they are defined in the 58 | `construct_runtime!` macro, but in this case, the System module finalizes last. 59 | 60 | Then, final checks take place where the digest and storage root in the block header match what was 61 | calculated. 62 | 63 | ## Next Steps 64 | 65 | ### Learn More 66 | 67 | - Learn how how you can simulate the orchestration of the Executive module in your 68 | [runtime tests](/current/runtime/tests.md). 69 | 70 | ### References 71 | 72 | - [FRAME executive](https://crates.parity.io/frame_executive/index.html) 73 | - [`decl_event!` macro](https://crates.parity.io/frame_support/macro.decl_event.html) 74 | - [`decl_storage!` macro](https://crates.parity.io/frame_support/macro.decl_storage.html) 75 | - [`construct_runtime!` macro](https://crates.parity.io/frame_support/macro.construct_runtime.html) 76 | -------------------------------------------------------------------------------- /current/runtime/frame.md: -------------------------------------------------------------------------------- 1 | --- 2 | slug: frame 3 | lang: en 4 | title: FRAME 5 | --- 6 | 7 | The **Framework for Runtime Aggregation of Modularized Entities (FRAME)** is a set of modules 8 | (called pallets) and support libraries that simplify runtime development. Pallets are individual 9 | modules within FRAME that host domain-specific logic. 10 | 11 | FRAME provides some helper modules to interact with Substrate Primitives, which provide the 12 | interface to the core client. 13 | 14 | ## Overview 15 | 16 | The following diagram shows the architectural overview of FRAME and its support libraries: 17 | 18 | ![frame-arch](../assets/frame-arch.png) 19 | 20 | ### Pallets 21 | 22 | When building with FRAME, the Substrate runtime is composed of several smaller components called 23 | pallets. A pallet contains a set of types, storage items, and functions that define a set of 24 | features and functionality for a runtime. 25 | 26 | ### System Library 27 | 28 | The [System library](https://crates.parity.io/frame_system/index.html) provides 29 | low-level types, storage, and functions for your blockchain. All other pallets depend on the System 30 | library as the basis of your Substrate runtime. 31 | 32 | The System library defines all the core types for the Substrate runtime, such as: 33 | 34 | - Origin 35 | - Block Number 36 | - Account Id 37 | - Hash 38 | - Header 39 | - Version 40 | - etc... 41 | 42 | It also has a number of system-critical storage items, such as: 43 | 44 | - Account Nonce 45 | - Block Hash 46 | - Block Number 47 | - Events 48 | - etc... 49 | 50 | Finally, it defines a number of low level functions which can access your blockchain storage, verify 51 | the origin of an extrinsic, and more. 52 | 53 | ### Executive Pallet 54 | 55 | The [Executive pallet](https://crates.parity.io/frame_executive/index.html) acts as the 56 | orchestration layer for the runtime. It dispatches incoming extrinsic calls to the respective 57 | pallets in the runtime. 58 | 59 | ### Support Library 60 | 61 | The [FRAME support library](https://crates.parity.io/frame_support/index.html) is a 62 | collection of Rust macros, types, traits, and functions that simplify the development of Substrate 63 | pallets. 64 | 65 | The support macros expand at compile time to generate code that is used by the runtime and reduce 66 | boilerplate code for the most common components of a pallet. 67 | 68 | ### Runtime 69 | 70 | The runtime library brings together all these components and pallets. It defines which pallets are 71 | included with your runtime and configures them to work together to compose your final runtime. When 72 | calls are made to your runtime, it uses the Executive pallet to dispatch those calls to the 73 | individual pallets. 74 | 75 | ## Prebuilt Pallets 76 | 77 | Some pallets will be sufficiently general-purpose to be reused in many blockchains. Anyone is free 78 | to write and share useful pallets. There is a collection of popular pallets provided with Substrate. 79 | Let's explore them. 80 | 81 | ### Assets 82 | 83 | The Assets pallet is a simple, secure module for dealing with fungible assets. 84 | 85 | - [Docs](https://crates.parity.io/pallet_assets/index.html) 86 | - [Source](https://github.com/paritytech/substrate/blob/master/frame/assets/src/lib.rs) 87 | 88 | ### Aura 89 | 90 | The Aura pallet extends Aura consensus by managing offline reporting. 91 | 92 | - [Docs](https://crates.parity.io/pallet_aura/index.html) 93 | - [Source](https://github.com/paritytech/substrate/blob/master/frame/aura/src/lib.rs) 94 | 95 | ### Authority Discovery 96 | 97 | The Authority Discovery pallet is used by `core/authority-discovery` to retrieve the current set of 98 | authorities, learn its own authority ID, as well as to sign and verify messages to and from other 99 | authorities. 100 | 101 | - [Docs](https://crates.parity.io/pallet_authority_discovery/index.html) 102 | - [Source](https://github.com/paritytech/substrate/blob/master/frame/authority-discovery/src/lib.rs) 103 | 104 | ### Authorship 105 | 106 | The Authorship pallet tracks the current author of the block and recent uncles. 107 | 108 | - [Docs](https://crates.parity.io/pallet_authorship/index.html) 109 | - [Source](https://github.com/paritytech/substrate/blob/master/frame/authorship/src/lib.rs) 110 | 111 | ### BABE 112 | 113 | The BABE pallet extends BABE consensus by collecting on-chain randomness from VRF outputs and 114 | managing epoch transitions. 115 | 116 | - [Docs](https://crates.parity.io/pallet_babe/index.html) 117 | - [Source](https://github.com/paritytech/substrate/blob/master/frame/babe/src/lib.rs) 118 | 119 | ### Balances 120 | 121 | The Balances pallet provides functionality for handling accounts and balances. 122 | 123 | - [Docs](https://crates.parity.io/pallet_balances/index.html) 124 | - [Source](https://github.com/paritytech/substrate/blob/master/frame/balances/src/lib.rs) 125 | 126 | ### Collective 127 | 128 | The Collective pallet allows a set of account IDs to make their collective feelings known through 129 | dispatched calls from specialized origins. 130 | 131 | - [Docs](https://crates.parity.io/pallet_collective/index.html) 132 | - [Source](https://github.com/paritytech/substrate/blob/master/frame/collective/src/lib.rs) 133 | 134 | ### Contracts 135 | 136 | The Contracts pallet provides functionality for the runtime to deploy and execute WebAssembly 137 | smart-contracts. 138 | 139 | - [Docs](https://crates.parity.io/pallet_contracts/index.html) 140 | - [Source](https://github.com/paritytech/substrate/blob/master/frame/contracts/src/lib.rs) 141 | 142 | ### Democracy 143 | 144 | The Democracy pallet provides a democratic system that handles administration of general stakeholder 145 | voting. 146 | 147 | - [Docs](https://crates.parity.io/pallet_democracy/index.html) 148 | - [Source](https://github.com/paritytech/substrate/blob/master/frame/democracy/src/lib.rs) 149 | 150 | ### Elections Phragmen 151 | 152 | The Phragmen Elections pallet is an election module based on 153 | [sequential phragmen](https://research.web3.foundation/en/latest/polkadot/NPoS/4.%20Sequential%20Phragm%C3%A9n%E2%80%99s%20method/). 154 | 155 | - [Docs](https://crates.parity.io/pallet_elections_phragmen/index.html) 156 | - [Source](https://github.com/paritytech/substrate/blob/master/frame/elections-phragmen/src/lib.rs) 157 | 158 | ### Elections 159 | 160 | The Elections pallet is an election module for stake-weighted membership selection of a collective. 161 | 162 | - [Docs](https://crates.parity.io/pallet_elections/index.html) 163 | - [Source](https://github.com/paritytech/substrate/blob/master/frame/elections/src/lib.rs) 164 | 165 | ### EVM 166 | 167 | The EVM pallet is an [Ethereum](https://en.wikipedia.org/wiki/Ethereum) virtual machine (EVM) 168 | execution module for Substrate. 169 | 170 | - [Docs](https://crates.parity.io/pallet_evm/index.html) 171 | - [Source](https://github.com/paritytech/substrate/blob/master/frame/evm/src/lib.rs) 172 | 173 | ### Example 174 | 175 | The Example pallet is a simple example of a pallet demonstrating concepts, APIs, and structures 176 | common to most pallets. 177 | 178 | - [Docs](https://crates.parity.io/pallet_example/index.html) 179 | - [Source](https://github.com/paritytech/substrate/blob/master/frame/example/src/lib.rs) 180 | 181 | ### Finality Tracker 182 | 183 | The Finality Tracker pallet tracks the last finalized block, as perceived by block authors. 184 | 185 | - [Docs](https://crates.parity.io/pallet_finality_tracker/index.html) 186 | - [Source](https://github.com/paritytech/substrate/blob/master/frame/finality-tracker/src/lib.rs) 187 | 188 | ### Generic Asset 189 | 190 | The Generic Asset pallet provides functionality for handling accounts and asset balances. 191 | 192 | - [Docs](https://crates.parity.io/pallet_generic_asset/index.html) 193 | - [Source](https://github.com/paritytech/substrate/blob/master/frame/generic-asset/src/lib.rs) 194 | 195 | ### GRANDPA 196 | 197 | The GRANDPA pallet extends GRANDPA consensus by managing the GRANDPA authority set ready for the 198 | native code. 199 | 200 | - [Docs](https://crates.parity.io/pallet_grandpa/index.html) 201 | - [Source](https://github.com/paritytech/substrate/blob/master/frame/grandpa/src/lib.rs) 202 | 203 | ### I'm Online 204 | 205 | The I'm Online pallet allows validators to gossip a heartbeat transaction with each new session to 206 | signal that the node is online. 207 | 208 | - [Docs](https://crates.parity.io/pallet_im_online/index.html) 209 | - [Source](https://github.com/paritytech/substrate/blob/master/frame/im-online/src/lib.rs) 210 | 211 | ### Indices 212 | 213 | The Indices pallet allocates indices for newly created accounts. An index is a short form of an 214 | address. 215 | 216 | - [Docs](https://crates.parity.io/pallet_indices/index.html) 217 | - [Source](https://github.com/paritytech/substrate/blob/master/frame/indices/src/lib.rs) 218 | 219 | ### Membership 220 | 221 | The Membership pallet allows control of membership of a set of `AccountId`s, useful for managing 222 | membership of a collective. 223 | 224 | - [Docs](https://crates.parity.io/pallet_membership/index.html) 225 | - [Source](https://github.com/paritytech/substrate/blob/master/frame/membership/src/lib.rs) 226 | 227 | ### Offences 228 | 229 | The Offences pallet tracks reported offences. 230 | 231 | - [Docs](https://crates.parity.io/pallet_offences/index.html) 232 | - [Source](https://github.com/paritytech/substrate/blob/master/frame/offences/src/lib.rs) 233 | 234 | ### Randomness Collective Flip 235 | 236 | The Randomness Collective Flip pallet provides a `random` function that generates low-influence 237 | random values based on the block hashes from the previous `81` blocks. 238 | 239 | - [Docs](https://crates.parity.io/pallet_randomness_collective_flip/index.html) 240 | - [Source](https://github.com/paritytech/substrate/blob/master/frame/randomness-collective-flip/src/lib.rs) 241 | 242 | ### Scored Pool 243 | 244 | The Scored Pool pallet maintains a scored membership pool where the highest scoring entities are 245 | made members. 246 | 247 | - [Docs](https://crates.parity.io/pallet_scored_pool/index.html) 248 | - [Source](https://github.com/paritytech/substrate/blob/master/frame/scored-pool/src/lib.rs) 249 | 250 | ### Session 251 | 252 | The Session pallet allows validators to manage their session keys, provides a function for changing 253 | the session length, and handles session rotation. 254 | 255 | - [Docs](https://crates.parity.io/pallet_session/index.html) 256 | - [Source](https://github.com/paritytech/substrate/blob/master/frame/session/src/lib.rs) 257 | 258 | ### Staking 259 | 260 | The Staking pallet is used to manage funds at stake by network maintainers. 261 | 262 | - [Docs](https://crates.parity.io/pallet_staking/index.html) 263 | - [Source](https://github.com/paritytech/substrate/blob/master/frame/staking/src/lib.rs) 264 | 265 | ### Sudo 266 | 267 | The Sudo pallet allows for a single account (called the "sudo key") to execute dispatchable 268 | functions that require a `Root` origin or designate a new account to replace them as the sudo key. 269 | 270 | - [Docs](https://crates.parity.io/pallet_sudo/index.html) 271 | - [Source](https://github.com/paritytech/substrate/blob/master/frame/sudo/src/lib.rs) 272 | 273 | ### Timestamp 274 | 275 | The Timestamp pallet provides functionality to get and set the on-chain time. 276 | 277 | - [Docs](https://crates.parity.io/pallet_timestamp/index.html) 278 | - [Source](https://github.com/paritytech/substrate/blob/master/frame/timestamp/src/lib.rs) 279 | 280 | ### Transaction Payment 281 | 282 | The Transaction Payment pallet provides the basic logic to compute pre-dispatch transaction fees. 283 | 284 | - [Docs](https://crates.parity.io/pallet_transaction_payment/index.html) 285 | - [Source](https://github.com/paritytech/substrate/blob/master/frame/transaction-payment/src/lib.rs) 286 | 287 | ### Treasury 288 | 289 | The Treasury pallet provides a "pot" of funds that can be managed by stakeholders in the system and 290 | a structure for making spending proposals from this pot. 291 | 292 | - [Docs](https://crates.parity.io/pallet_treasury/index.html) 293 | - [Source](https://github.com/paritytech/substrate/blob/master/frame/treasury/src/lib.rs) 294 | 295 | ## Next Steps 296 | 297 | ### Learn More 298 | 299 | - Learn how to [develop custom Substrate pallets](pallet). 300 | 301 | ### Examples 302 | 303 | - Follow a 304 | [tutorial to add a pallet to your Substrate runtime](https://substrate.dev/docs/en/tutorials/adding-a-module-to-your-runtime/). 305 | 306 | ### References 307 | 308 | - Visit the reference docs for the 309 | [System library](https://crates.parity.io/frame_system/index.html). 310 | 311 | - Visit the reference docs for the 312 | [Executive pallet](https://crates.parity.io/frame_executive/index.html). 313 | 314 | - Visit the reference docs for the 315 | [FRAME support library](https://crates.parity.io/frame_support/index.html). 316 | -------------------------------------------------------------------------------- /current/runtime/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | slug: index 3 | lang: en 4 | title: Overview 5 | --- 6 | 7 | ## Substrate Runtime 8 | 9 | The runtime contains the business logic that will define your blockchain's behavior, a.k.a. its 10 | state transition function. The runtime will define the storage items and functions that users can 11 | dispatch. 12 | 13 | Substrate provides a set of modules, called pallets, that can be composed and configured. Substrate 14 | also provides the support libraries necessary to let these pallets interact with the client. Each 15 | pallet contains domain-specific logic and storage items. At the runtime level, you can add your own 16 | pallets by using the standard pallet interfaces and access the public methods and traits of other 17 | pallets. 18 | 19 | The entire set of pallets and support libraries is called _FRAME._ FRAME interacts with the client 20 | by implementing the traits in _primitives._ 21 | 22 | ![Runtime Composition](../assets/runtime.png) 23 | 24 | For example, if you want to add smart contract functionality to your blockchain, you simply need to 25 | include the [Contracts](https://crates.parity.io/pallet_contracts/index.html) pallet. 26 | Adding this pallet will expose the smart contract interface so that users can deploy smart contracts 27 | that execute in Wasm. 28 | 29 | Because Substrate can execute a runtime in both native and Wasm, anything that you write in FRAME 30 | can be upgraded without a hard fork. 31 | 32 | ### Learn More 33 | 34 | - Follow a 35 | [tutorial to develop your first Substrate chain](https://substrate.dev/docs/en/next/tutorials/creating-your-first-substrate-chain/). 36 | - Follow a 37 | [tutorial to add a pallet to your Substrate runtime](https://substrate.dev/docs/en/tutorials/adding-a-module-to-your-runtime/). 38 | -------------------------------------------------------------------------------- /current/runtime/macros.md: -------------------------------------------------------------------------------- 1 | --- 2 | slug: macros 3 | lang: en 4 | title: Runtime Macros 5 | --- 6 | 7 | The Substrate runtime macros are a set of utilities which make the development of runtime modules 8 | simpler for you. 9 | 10 | ## What are Rust macros? 11 | 12 | In short, Rust macros are a way to write code that writes more code. Macros work by matching against 13 | the specific patterns defined in the macro rule, capturing part of the match as variables, and then 14 | expand to produce even more code. 15 | 16 | You can learn more about 17 | [macros in the Rust book](https://doc.rust-lang.org/book/ch19-06-macros.html). 18 | 19 | ## Runtime Macros 20 | 21 | Substrate provides a set of runtime macros that generate boilerplate code that would otherwise be 22 | cumbersome for you to write. 23 | 24 | The main macros you will interact with are: 25 | 26 | - `decl_module!` - Used for defining the callable functions your runtime module exposes and 27 | orchestrates actions our module takes through block execution. 28 | - `decl_storage!` - Used to define the storage items managed by your runtime module. 29 | - `decl_event!` - Used to define the events that can be emitted by your runtime module. 30 | 31 | In addition, you will interact with the `construct_runtime!` macro when finally choosing the modules 32 | which will be included into your runtime. 33 | 34 | Each of these macros have their own page which describes how to use them. 35 | 36 | ## Expanding the Macros 37 | 38 | The runtime macros do a lot of work for you, and as a result, may sometimes feel like magic. In 39 | general, we suggest that you treat them like magic. 40 | 41 | However, if you are interested in learning more details about what exactly the macros do, you can 42 | expand them with [`cargo expand`](https://github.com/dtolnay/cargo-expand), resulting in pure Rust 43 | code. 44 | 45 | ## Next Steps 46 | 47 | ### Learn More 48 | 49 | - Learn how to use the [`decl_storage` macro](storage). 50 | - Learn how to use the [`decl_event` macro](events). 51 | 52 | ### Examples 53 | 54 | View our most [simple Substrate runtime](index) to see all these macros interact with one another. 55 | 56 | ### References 57 | 58 | - [`decl_module!` macro](https://crates.parity.io/frame_support/macro.decl_module.html) 59 | - [`decl_event!` macro](https://crates.parity.io/frame_support/macro.decl_event.html) 60 | - [`decl_storage!` macro](https://crates.parity.io/frame_support/macro.decl_storage.html) 61 | - [`construct_runtime!` macro](https://crates.parity.io/frame_support/macro.construct_runtime.html) 62 | -------------------------------------------------------------------------------- /current/runtime/origin.md: -------------------------------------------------------------------------------- 1 | --- 2 | slug: origin 3 | lang: en 4 | title: Runtime Origin 5 | --- 6 | 7 | The runtime origin is used by dispatchable functions to check where the call came from. 8 | 9 | ## Raw Origins 10 | 11 | Substrate defines three raw origins which can be used in your runtime module: 12 | 13 | ```rust 14 | pub enum RawOrigin { 15 | Root, 16 | Signed(AccountId), 17 | None, 18 | } 19 | ``` 20 | 21 | - Root: A system level origin. This is the highest privilege level. 22 | 23 | - Signed: A transaction origin. This is signed by some public key and includes the account 24 | identifier of the signer. 25 | 26 | - None: A lack of origin. This needs to be agreed upon by the validators or validated by a module to 27 | be included. 28 | 29 | ## Custom Origins 30 | 31 | You are also able to define custom origins that can be used for authorization checks in your runtime 32 | functions. 33 | 34 | More details TODO 35 | 36 | ## Custom Origin Call 37 | 38 | You can construct calls within your runtime with any origin. For example: 39 | 40 | ```rust 41 | // Root 42 | proposal.dispatch(system::RawOrigin::Root.into()) 43 | 44 | // Signed 45 | proposal.dispatch(system::RawOrigin::Signed(who).into()) 46 | 47 | // None 48 | proposal.dispatch(system::RawOrigin::None.into()) 49 | ``` 50 | 51 | You can look at the source code of the 52 | [Sudo module](https://crates.parity.io/pallet_sudo/index.html) for a practical 53 | implementation of this. 54 | 55 | ## Next Steps 56 | 57 | ### Learn More 58 | 59 | - Learn origin is used in the `decl_module` macro. 60 | 61 | - Learn 62 | 63 | ### Examples 64 | 65 | - View the Sudo module to see how it allows a user to call with `Root` and `Signed` origin. 66 | 67 | - View the Timestamp module to see how it validates an a call with `None` origin. 68 | 69 | - View the Collective module to see how it constructs a custom `Member` origin. 70 | 71 | - View our recipe for creating and using a custom origin. 72 | 73 | ### References 74 | 75 | - Visit the reference docs for the 76 | [`RawOrigin` enum](https://crates.parity.io/frame_system/enum.RawOrigin.html). 77 | -------------------------------------------------------------------------------- /current/runtime/pallets.md: -------------------------------------------------------------------------------- 1 | --- 2 | slug: pallets 3 | lang: en 4 | title: Pallets 5 | --- 6 | 7 | This document is a top-level entry point to documentation related to developing runtime modules for 8 | Substrate. 9 | 10 | These documents are written for a technical audience, who is familiar with the Rust programming 11 | language. 12 | 13 | If you are getting started with Substrate runtime development for the first time, we suggest you try 14 | our introductory tutorial for 15 | [creating your first Substrate chain](/tutorials/create-your-first-substrate-chain). 16 | 17 | ## What is a Pallet? 18 | 19 | Pallets are a special kind of Rust module from which Substrate runtimes can be composed. Each pallet 20 | has its own discrete logic which can modify the features and functionality of your blockchain's 21 | state transition function. 22 | 23 | For example, the Balances pallet, which is included in the Framework for Runtime Aggregation of 24 | Modularised Entities (FRAME), defines a cryptocurrency for your blockchain. More specifically, it 25 | defines storage items which tracks the tokens a user has, functions that users can call to transfer 26 | and manage those tokens, APIs which allow other modules to burn or mint those tokens, and hooks 27 | which allow other modules to trigger functions when a user's balance changes. 28 | 29 | You are able to write your own pallets which define logic and functionality you want to introduce to 30 | your blockchain, and the following documentation will show you how. 31 | 32 | ## Skeleton of a Pallet 33 | 34 | A Substrate pallet is composed of 5 main sections: 35 | 36 | ```rust 37 | // 1. Imports and Dependencies 38 | // The pallet supports the use of any Rust library which compiles 39 | // with the `no_std` flag. 40 | use support::{decl_module, decl_event, decl_storage, ...} 41 | 42 | // 2. Runtime Configuration Trait 43 | // All of the runtime types and consts go in here. If the pallet 44 | // is dependent on specific other pallets, then their configuration traits 45 | // should be added to the inherited traits list. 46 | pub trait Trait: system::Trait { ... } 47 | 48 | // 3. Runtime Events 49 | // Events are a simple means of reporting specific conditions and circumstances 50 | // that have happened that users, Dapps and/or chain explorers would find 51 | // interesting and otherwise difficult to detect. 52 | decl_event!{ ... } 53 | 54 | // 4. Runtime Storage 55 | // This allows for type-safe usage of the Substrate storage database, so you can 56 | // keep things around between blocks. 57 | decl_storage! { ... } 58 | 59 | // 5. The Pallet Declaration 60 | // This defines the `Module` struct that is ultimately exported from this pallet. 61 | // It defines the callable functions that this pallet exposes and orchestrates 62 | // actions this pallet takes throughout block execution. 63 | decl_module! { ... } 64 | ``` 65 | 66 | ## Example Module 67 | 68 | Here is a minimal, working pallet which simply allows a user to put a `u64` value into storage. 69 | 70 | Parts of this example will be used to help teach concepts throughout the rest of the pallet 71 | documentation. 72 | 73 | It is written in full here for clarity: 74 | 75 | ```rust 76 | use support::{decl_module, decl_event, decl_storage, StorageValue, StorageMap}; 77 | use system::ensure_signed; 78 | 79 | pub trait Trait: system::Trait { 80 | // The traits the `Event` type used in this pallet has. 81 | type Event: From> + Into<::Event>; 82 | } 83 | 84 | decl_event!{ 85 | pub enum Event where 86 | AccountId = ::AccountId, 87 | { 88 | // An event which is emitted when `set_value` is called. 89 | // Contains information about the user who called the function 90 | // and the value they called with. 91 | ValueSet(AccountId, u64), 92 | } 93 | } 94 | 95 | decl_storage! { 96 | trait Store for Module as Example { 97 | // The last value passed to `set_value`. 98 | // Used as an example of a `StorageValue`. 99 | pub LastValue get(last_value): u64; 100 | // The value each user has put into `set_value`. 101 | // Used as an example of a `StorageMap`. 102 | pub UserValue get(user_value): map T::AccountId => u64; 103 | } 104 | } 105 | 106 | decl_module! { 107 | pub struct Module for enum Call where origin: T::Origin { 108 | // A default function for depositing events in our runtime 109 | fn deposit_event() = default; 110 | 111 | // The only callable function of our runtime module. 112 | // Allows a user to set a `u64` value into the runtime storage. 113 | pub fn set_value(origin, value: u64) { 114 | let sender = ensure_signed(origin)?; 115 | LastValue::put(value); 116 | UserValue::::insert(&sender, value); 117 | Self::deposit_event(RawEvent::ValueSet(sender, value)); 118 | } 119 | } 120 | } 121 | ``` 122 | -------------------------------------------------------------------------------- /current/runtime/primitives.md: -------------------------------------------------------------------------------- 1 | --- 2 | slug: primitives 3 | lang: en 4 | title: Runtime Primitives 5 | --- 6 | 7 | The Substrate runtime is composed with a set of primitive types that are expected by the rest of the 8 | Substrate framework. 9 | 10 | ## Core Primitives 11 | 12 | The Substrate framework makes minimal assumptions about what your runtime must provide to the other 13 | layers of Substrate. They are mandatory to define and must fulfill a particular interface in order 14 | to work within the Substrate framework. 15 | 16 | They are: 17 | 18 | - `Hash`: A type which encodes a cryptographic digest of some data. Typically just a 256-bit 19 | quantity. 20 | 21 | - `DigestItem`: A type which must be able to encode one of a number of "hard-wired" alternatives 22 | relevant to consensus and change-tracking as well as any number of "soft-coded" variants, relevant 23 | to specific modules within the runtime. 24 | 25 | - `Digest`: A series of DigestItems. This encodes all information that is relevant for a 26 | light-client to have on hand within the block. 27 | 28 | - `Extrinsic`: A type to represent a single piece of data external to the blockchain that is 29 | recognized by the blockchain. This typically involves one or more signatures, and some sort of 30 | encoded instruction (e.g. for transferring ownership of funds or calling into a smart contract). 31 | 32 | - `Header`: A type which is representative (cryptographically or otherwise) of all information 33 | relevant to a block. It includes the parent hash, the storage root and the extrinsics trie root, 34 | the digest and a block number. 35 | 36 | - `Block`: Essentially just a combination of `Header` and a series of `Extrinsic`s, together with a 37 | specification of the hashing algorithm to be used. 38 | 39 | - `BlockNumber`: A type which encodes the total number of ancestors any valid block has. Typically a 40 | 32-bit quantity. 41 | 42 | ## FRAME Primitives 43 | 44 | There are an additional set of primitives that are assumed about a runtime built with the Substrate 45 | FRAME: 46 | 47 | - `Call`: The dispatch type that can be called via an extrinsic. 48 | 49 | - `Origin`: Represents where a call came from. For example, a signed message (a transaction), an 50 | unsigned message (an inherent extrinsic), and a call from the runtime itself (a root call). 51 | 52 | - `Index`: An account index (aka nonce) type. This stores the number of previous transactions 53 | associated with a sender account. 54 | 55 | - `Hashing`: The hashing system (algorithm) being used in the runtime (e.g. Blake2). 56 | 57 | - `AccountId`: The type used to identify user accounts in the runtime. 58 | 59 | - `Event`: The type used for events emitted by the runtime. 60 | 61 | - `Version`: A type which represents the version of the runtime. 62 | 63 | ## Next Steps 64 | 65 | ### Learn More 66 | 67 | - Learn about the [Substrate FRAME](frame). 68 | 69 | ### Examples 70 | 71 | - See how these generic types are implemented 72 | [in the Substrate node](https://github.com/paritytech/substrate/blob/master/bin/node/runtime/src/lib.rs). 73 | 74 | ### References 75 | 76 | - View the 77 | [primitive types defined in `node-primitives`](https://crates.parity.io/node_primitives/index.html). 78 | 79 | - View the 80 | [`traits` defined in `sp-runtime`](https://crates.parity.io/sp_runtime/traits/index.html) 81 | -------------------------------------------------------------------------------- /current/runtime/tests.md: -------------------------------------------------------------------------------- 1 | --- 2 | slug: tests 3 | lang: en 4 | title: Runtime Tests 5 | --- 6 | 7 | Runtime tests allow you to verify the logic in your runtime module by mocking a Substrate runtime 8 | environment. 9 | 10 | ## Unit Testing 11 | 12 | Substrate uses the existing 13 | [unit testing](https://doc.rust-lang.org/rust-by-example/testing/unit_testing.html) framework 14 | provided by Rust. To run tests, the command is 15 | 16 | ```bash 17 | cargo test 18 | ``` 19 | 20 | ## Mock Runtime Environment 21 | 22 | To test a Substrate runtime, construct a mock runtime environment. The configuration type `Test` is 23 | defined as a unit struct with implementations for each of the configuration traits that need to be 24 | used in the mock runtime. 25 | 26 | ```rust 27 | #[derive(Clone, PartialEq, Eq, Debug)] 28 | pub struct Test; 29 | ``` 30 | 31 | If `Test` implements `balances::Trait`, the assignment might use `u64` for the `Balance` type. 32 | 33 | ```rust 34 | impl balances::Trait for TestRuntime { 35 | type Balance = u64; 36 | //.. 37 | } 38 | ``` 39 | 40 | By assigning `balances::Balance` and `system::AccountId` to `u64`, mock runtimes ease the mental 41 | overhead of comprehensive, conscientious testers. Reasoning about accounts and balances only 42 | requires tracking a `(AccountId: u64, Balance: u64)` mapping. 43 | 44 | ### Mock Runtime Storage 45 | 46 | The [`runtime-io`](https://crates.parity.io/sp_io/index.html) crate exposes a 47 | [`TestExternalities`](https://crates.parity.io/sp_io/type.TestExternalities.html) 48 | implementation frequently used for mocking storage in tests. It is the type alias for an in-memory, 49 | hashmap-based externalities implementation in 50 | [`substrate_state_machine`](https://crates.parity.io/sp_state_machine/index.html)] 51 | referred to as 52 | [`TestExternalities`](https://crates.parity.io/sp_state_machine/struct.TestExternalities.html). 53 | 54 | In the [basic mock runtime's recipe](https://substrate.dev/recipes/3-entrees/testing/mock.html), an 55 | `ExtBuilder` object is defined to build an instance of 56 | [`TestExternalities`](https://crates.parity.io/sp_io/type.TestExternalities.html). 57 | 58 | ```rust 59 | pub struct ExtBuilder; 60 | 61 | impl ExtBuilder { 62 | pub fn build() -> runtime_io::TestExternalities { 63 | let mut storage = system::GenesisConfig::default().build_storage::().unwrap(); 64 | runtime_io::TestExternalities::from(storage) 65 | } 66 | } 67 | ``` 68 | 69 | To create the test environment in unit tests, the build method is called to generate a 70 | `TestExternalities` using the default genesis configuration. Then, 71 | [`with_externalities`](https://crates.parity.io/sp_externalities/fn.with_externalities.html) 72 | provides the runtime environment in which we may call the pallet's methods to test that storage, 73 | events, and errors behave as expected. 74 | 75 | ```rust 76 | #[test] 77 | fn fake_test_example() { 78 | ExtBuilder::build().execute_with(|| { 79 | // ...test conditions... 80 | }) 81 | } 82 | ``` 83 | 84 | Custom implementations of 85 | [Externalities](https://crates.parity.io/sp_externalities/index.html) allow developers 86 | to construct runtime environments that provide access to features of the outer node. Another example 87 | of this can be found in 88 | [`offchain`](https://crates.parity.io/sp_core/offchain/index.html), which maintains its 89 | own 90 | [Externalities](https://substrate.dev/rustdocs/pre-v2.0-3e65111/sp_core/offchain/trait.Externalities.html) 91 | implementation. 92 | [Implementing configurable externalities](https://substrate.dev/recipes/3-entrees/testing/externalities.html) 93 | is covered in more depth in the recipes. 94 | 95 | #### Genesis Config 96 | 97 | The previously shown `ExtBuilder::build()` method used the default genesis configuration for 98 | building the mock runtime environment. In many cases, it is convenient to set storage before 99 | testing. 100 | 101 | An example might involve pre-seeding account balances before testing. 102 | 103 | In the implementation of `system::Trait`, `AccountId` is set to `u64` just like `Balance` shown 104 | above. Place `(u64, u64)` pairs in the `balances` vec to seed `(AccountId, Balance)` pairs as the 105 | account balances. 106 | 107 | ```rust 108 | pub fn build(self) -> runtime_io::TestExternalities { 109 | GenesisConfig { 110 | balances: Some(balances::GenesisConfig::{ 111 | balances: vec![ 112 | (1, 10), 113 | (2, 20), 114 | (3, 30), 115 | (4, 40), 116 | (5, 50), 117 | (6, 60) 118 | ], 119 | vesting: vec![], 120 | }), 121 | }.build_storage().unwrap().into() 122 | } 123 | ``` 124 | 125 | Account 1 has balance 10, account 2 has balance 20, and so on. 126 | 127 | ### Block Production 128 | 129 | It will be useful to simulate block production to verify that expected behavior holds during block 130 | time dependent changes. 131 | 132 | A simple way of doing this increments the System module's block number between `on_initialize` and 133 | `on_finalize` calls from all modules with `System::block_number()` as the sole input. While it is 134 | important for runtime code to 135 | [cache calls](https://substrate.dev/recipes/3-entrees/storage-api/cache.html) to storage or the 136 | system module, the test environment scaffolding should prioritize readability to facilitate future 137 | maintenance. 138 | 139 | ```rust 140 | fn run_to_block(n: u64) { 141 | while System::block_number() < n { 142 | ExampleModule::on_finalize(System::block_number()); 143 | System::on_finalize(System::block_number()); 144 | System::set_block_number(System::block_number() + 1); 145 | System::on_initialize(System::block_number()); 146 | ExampleModule::on_initialize(System::block_number()); 147 | } 148 | } 149 | ``` 150 | 151 | `on_finalize` and `on_initialize` are only called from `ExampleModule` if the pallet's trait 152 | implements the `sr_primitives::traits::{OnInitialize, OnFinalize}` traits to execute the logic 153 | encoded in the runtime methods before and after each block respectively. 154 | 155 | To use this function in unit tests, 156 | 157 | ```rust 158 | #[test] 159 | fn my_runtime_test() { 160 | with_externalities(&mut new_test_ext(), || { 161 | assert_ok!(ExampleModule::start_auction()); 162 | run_to_block(10); 163 | assert_ok!(ExampleModule::end_auction()); 164 | }); 165 | } 166 | ``` 167 | 168 | ## Next Steps 169 | 170 | The [testing chapter](https://substrate.dev/recipes/3-entrees/testing/index.html) of the Substrate 171 | Recipes compliments the samples shown above, and provides an environment to run the tests, change 172 | the logic, and tinker with the code. 173 | -------------------------------------------------------------------------------- /current/smart-contracts/contracts-pallet.md: -------------------------------------------------------------------------------- 1 | --- 2 | slug: contracts-pallet 3 | lang: en 4 | title: Contracts Pallet 5 | --- 6 | 7 | The [Contracts pallet](https://crates.parity.io/pallet_contracts/index.html) provides 8 | the ability for the runtime to deploy and execute [WebAssembly (Wasm)](https://webassembly.org/) 9 | smart contracts. 10 | 11 | ## Wasm Engine 12 | 13 | The Contracts pallet depends on a Wasm sandboxing interface defining the Wasm execution engine 14 | available within the runtime. This is currently implemented with 15 | [`wasmi`](https://github.com/paritytech/wasmi), a Wasm interpreter. 16 | 17 | ## Features 18 | 19 | The Contracts module has a number of familiar and new features for the deployment and execution of 20 | smart contracts. 21 | 22 | ### Account Based 23 | 24 | The Contracts module uses an account-based system similar to many existing smart contract platforms. 25 | To the Substrate runtime, contract accounts are just like normal user accounts; however, in addition 26 | to an `AccountID` and `Balance` that normal accounts have, a contract account also has associated 27 | contract code and some persistent contract storage. 28 | 29 | ### Two Step Deployment 30 | 31 | Deploying a contract with the Contracts module takes two steps: 32 | 33 | 1. Store the Wasm contract on the blockchain. 34 | 2. Instantiate a new account, with new storage, associated with that Wasm contract. 35 | 36 | This means that multiple contract instances, with different constructor arguments, can be 37 | initialized using the same Wasm code, reducing the amount of storage space needed by the Contracts 38 | module on your blockchain. 39 | 40 | ### Runtime Environment Types 41 | 42 | For writing contracts and interacting with the runtime, a set of types are available (e.g. 43 | `AccountId`, `Balance`, `Hash`, `Moment`). These types can be user defined for custom runtimes, or 44 | the supplied defaults can be used. 45 | 46 | ### Contract Calls 47 | 48 | Calls to contracts can alter the storage of the contract, create new contracts, and call other 49 | contracts. Because Substrate provides you with the ability to write custom runtime modules, the 50 | Contracts module also enables you to make asynchronous calls directly to those runtime functions on 51 | behalf of the contract's account. 52 | 53 | ### Sandboxed 54 | 55 | The Contracts module is intended to be used by any user on a public network. This means that 56 | contracts only have the ability to directly modify their own storage. To provide safety to the 57 | underlying blockchain state, the Contracts module enables revertible transactions, which roll back 58 | any changes to the storage by contract calls that do not complete successfully. 59 | 60 | ### Gas 61 | 62 | Contract calls are charged a gas fee to limit the amount of computational resources a transaction 63 | can use. When forming a contract transaction, a gas limit is specified. As the contract executes, 64 | gas is incrementally used up depending on the complexity of the computation. If the gas limit is 65 | reached before the contract execution completes, the transaction fails, contract storage is 66 | reverted, and the gas fee is **not** returned to the user. If the contract execution completes with 67 | remaining gas, it is returned to the user at the end of the transaction. 68 | 69 | The Contracts module determines the gas price, which is a conversion between the Substrate 70 | `Currency` and a single unit of gas. Thus, to execute a transaction, a user must have a free balance 71 | of at least `gas price` \* `gas limit` which can be spent. 72 | 73 | ### Storage Rent 74 | 75 | Similar to how gas limits the amount of computational resources that can be used during a 76 | transaction, storage rent limits the footprint that a contract can have on the blockchain's storage. 77 | A contract account is charged proportionally to the amount of storage its account uses. When a 78 | contract's balance goes below a defined limit, the contract's account is turned into a "tombstone" 79 | and its storage is cleaned up. A tombstone contract can be restored by providing the data that was 80 | cleaned up when it became a tombstone as well as any additional funds needed to keep the contract 81 | alive. 82 | 83 | ## Contracts Module vs EVM 84 | 85 | The Contracts module iterates on existing ideas in the smart contract ecosystem, particularly 86 | Ethereum and the EVM. 87 | 88 | The most obvious difference between the Contracts module and the EVM is the underlying execution 89 | engine used to run smart contracts. The EVM is a good theoretical execution environment, but it is 90 | not very practical to use with modern hardware. For example, manipulation of 256 bit integers on 91 | modern architectures is significantly more complex than standard types. Even the Ethereum team has 92 | investigated the use of [Wasm](https://github.com/ewasm/design) for the next generation of the 93 | network. 94 | 95 | The EVM charges for storage fees only at the time of storage. This one-time cost results in some 96 | permanent amount of storage being used on the blockchain, _forever_, which is economically unsound. 97 | The Contracts module attempts to repair this through [storage rent](#storage-rent) which ensures 98 | that any data that persists on the blockchain is appropriately charged for those resources. 99 | 100 | The Contracts module chooses to approach contract creation using a 101 | [two-step process](#two-step-deployment), which fundamentally changes how contracts are stored on 102 | chain. Contract addresses, their storage, and balances are now separated from the underlying 103 | contract logic. This could enable behavior like what 104 | [`create2`](https://eips.ethereum.org/EIPS/eip-1014) provided to Ethereum or even enable repairable 105 | or upgradeable contracts on a Substrate based blockchain. 106 | 107 | ## Next Steps 108 | 109 | ### Learn More 110 | 111 | - Learn about 112 | [ink!, a Rust based embedded domain specific language](/current/smart-contracts/index.md) for 113 | developing smart contracts for the SEAL pallet. 114 | 115 | ### Examples 116 | 117 | - Follow a 118 | [tutorial to add this Contracts pallet to your Substrate runtime](https://substrate.dev/docs/en/tutorials/adding-a-module-to-your-runtime/). 119 | 120 | ### References 121 | 122 | - Visit the reference docs for the 123 | [Contracts module](https://crates.parity.io/pallet_contracts/index.html). 124 | - Take a look at the [repository for `wasmi`](https://github.com/paritytech/wasmi). 125 | - Take a look at the [repository for ink!](https://github.com/paritytech/ink). 126 | -------------------------------------------------------------------------------- /current/smart-contracts/env-types.md: -------------------------------------------------------------------------------- 1 | --- 2 | slug: env-types 3 | lang: en 4 | title: Smart Contract Runtime Environment Types 5 | --- 6 | 7 | `ink!` provides a set of types for interacting with the runtime environment (currently:`AccountId`, 8 | `Balance`, `Hash`, `Timestamp`). 9 | 10 | Previously these types were fixed, requiring that the target substrate runtime had compatible types. 11 | 12 | Now smart contract authors can specify their own definitions of these types, in order to be 13 | compatible with their custom runtime. e.g. 14 | 15 | ``` 16 | // 1. Define type and derive the implementations. 17 | #[cfg_attr(feature = "ink-generate-abi", derive(Metadata))] 18 | #[derive(Clone, Debug, PartialEq, Eq)] 19 | pub enum CustomRuntimeTypes {} 20 | 21 | // 2. Implement `EnvTypes` trait, specifying custom types 22 | impl ink_core::env::EnvTypes for CustomRuntimeTypes { 23 | type AccountId = AccountId; 24 | type Balance = u128; 25 | type Hash = Hash; 26 | type Timestamp = u64; 27 | type BlockNumber = BlockNumber; 28 | type Call = calls::Call; 29 | } 30 | 31 | 32 | // 3. Add contract attribute specifying custom types 33 | #[ink::contract(version = "0.1.0", env = CustomRuntimeTypes)] 34 | ... 35 | ``` 36 | 37 | A full example of implementing this as a library can be found 38 | [here](https://github.com/paritytech/ink-types-node-runtime). 39 | 40 | ### Testing 41 | 42 | For accessing the state of the contract test environment, some helper methods will now require the 43 | concrete implementation of the `EnvTypes`, matching the type specified in the contract `env` 44 | attribute. 45 | -------------------------------------------------------------------------------- /current/smart-contracts/evm-pallet.md: -------------------------------------------------------------------------------- 1 | --- 2 | slug: evm-pallet 3 | lang: en 4 | title: EVM Pallet 5 | --- 6 | 7 | FRAME provides an EVM execution module that allows unmodified EVM code to be executed in a 8 | Substrate-based blockchain. 9 | 10 | ## EVM Engine 11 | 12 | The EVM module uses [SputnikVM](https://github.com/sorpaas/rust-evm) as the underlying EVM engine. 13 | The engine is overhauled so that it's [modular](https://github.com/corepaper/evm). In the future, we 14 | will want to allow users to swap out components like gasometer, and inject their own customized 15 | ones. 16 | 17 | ## Execution Lifecycle 18 | 19 | There are a separate set of accounts managed by the EVM module. Substrate based accounts can call 20 | the EVM Module to deposit or withdraw balance from the Substrate base-currency into a different 21 | balance managed and used by the EVM module. Once a user has populated their balance, they can create 22 | and call smart contracts using this module. 23 | 24 | There's one-to-one mapping from Substrate accounts and EVM external accounts that is defined by a 25 | conversion function. 26 | 27 | ## EVM Module vs Ethereum Network 28 | 29 | The EVM module should be able to produce nearly identical results compared to the Ethereum mainnet, 30 | including gas cost and balance changes. 31 | 32 | Observable differences include: 33 | 34 | - The available length of block hashes may not be 256 depending on the configuration of the System 35 | module in the Substrate runtime. 36 | - Difficulty and coinbase, which do not make sense in this module and is currently hard coded to 37 | zero. 38 | 39 | We currently do not aim to make unobservable behaviors, such as state root, to be the same. We also 40 | don't aim to follow the exact same transaction / receipt format. However, given one Ethereum 41 | transaction and one Substrate account's private key, one should be able to convert any Ethereum 42 | transaction into a transaction compatible with this module. 43 | 44 | The gas configurations are currently hard-coded to the Istanbul hard fork. It can later be expanded 45 | to support earlier hard fork configurations. 46 | 47 | ## Next Steps 48 | 49 | ### Learn More 50 | 51 | - Learn about our [Contracts pallet](https://docs.rs/pallet-contracts/), which supports deployment 52 | and execution of Wasm smart contracts. 53 | 54 | ### Examples 55 | 56 | - Follow a 57 | [tutorial to add a runtime module to your Substrate runtime](https://substrate.dev/docs/en/tutorials/adding-a-module-to-your-runtime/). 58 | 59 | ### References 60 | 61 | - Visit the reference docs for the [EVM module](https://docs.rs/pallet_evm/). 62 | 63 | - Visit the reference docs for [SputnikVM's `evm` crate](https://docs.rs/evm/). 64 | -------------------------------------------------------------------------------- /current/smart-contracts/faq.md: -------------------------------------------------------------------------------- 1 | --- 2 | slug: faq 3 | lang: en 4 | title: ink! F.A.Q. 5 | --- 6 | 7 | This page will answer a number of common questions you may have when starting to build smart 8 | contracts for Substrate. 9 | 10 | ## ink! F.A.Q. 11 | 12 | ### What is the difference between memory and storage? 13 | 14 | In ink! we refer `memory` to being the computer memory that is commonly known to programmers while 15 | with `storage` we refer to the contract instance's memory. The `storage` is backed up by the runtime 16 | in a data base. Accesses to it are considered to be slow. 17 | 18 | #### Example 19 | 20 | While a `storage::Vec` stores every of its elements in a different cell in the contract storage, 21 | a `storage::Value>` would store all elements (and a length info) in a single cell. 22 | Smart contract writers can use this to optimize for certain use cases. Using a 23 | `storage::Value>` could probably be more efficient for a small amount of elements in 24 | the `memory::Vec`. We advise to use the more general `storage::Vec` for storing information on 25 | the contract instance. 26 | 27 | ### What is the test environment? 28 | 29 | ink provides a test environment 30 | ([test_env](https://github.com/paritytech/ink/blob/master/core/src/env/test_env.rs)) which is used 31 | to emulate contract execution off-chain. This can be enabled by the crate feature `test-env` and is 32 | mainly useful for running tests off-chain. 33 | 34 | See [running off-chain tests](#running-off-chain-tests) for more information. 35 | 36 | ### How do I run off-chain tests? 37 | 38 | When building a smart contract with ink, you can define a set of tests that can be run using the 39 | off-chain test environment. 40 | 41 | For example, in the minimal 42 | [flipper contract](https://github.com/paritytech/ink/blob/master/examples/lang/flipper/src/lib.rs), 43 | you can find a small off-chain test at the bottom of the contract. 44 | 45 | To run this test, type the following command: 46 | 47 | ```bash 48 | cargo +nightly test 49 | ``` 50 | 51 | ## Contracts Module 52 | 53 | ### How do I add the Contracts module to my custom chain? 54 | 55 | You can follow 56 | [our guide here](https://substrate.dev/docs/en/tutorials/adding-a-module-to-your-runtime/) for 57 | instructions to add the Contracts pallet and other FRAME pallets to your blockchain runtime. 58 | -------------------------------------------------------------------------------- /current/smart-contracts/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | slug: index 3 | lang: en 4 | title: ink! Smart Contracts 5 | --- 6 | 7 | Welcome to the smart contracts section of the Developer Hub! 8 | 9 | Because Substrate supports Wasm smart contracts, it means that any language that can compile to Wasm 10 | could be used to write these contracts. ink! is Parity's answer for writing smart contracts using 11 | the Rust programming language. 12 | 13 | ## Contracts Pallet 14 | 15 | The Contracts pallet provides the ability for the runtime to deploy and execute WebAssembly smart 16 | contracts. Here we will provide a short overview of the major features of the contracts pallet. To 17 | really learn all of the fine details, you can take a look at the 18 | [reference documentation for `pallet-contracts`](https://docs.rs/pallet-contracts). 19 | 20 | ### Account Based 21 | 22 | The Contracts pallet uses an account-based system similar to many existing smart contract platforms. 23 | To the Substrate runtime, contract accounts are just like normal user accounts; however, in addition 24 | to an `AccountID` and `Balance` that normal accounts have, a contract account also has associated 25 | contract code and some persistent contract storage. 26 | 27 | ### Two Step Deployment 28 | 29 | Deploying a contract with the Contracts pallet takes two steps: 30 | 31 | 1. Store the Wasm contract on the blockchain. 32 | 2. Instantiate a new account, with new storage, associated with that Wasm contract. 33 | 34 | This means that multiple contract instances, with different constructor arguments, can be 35 | initialized using the same Wasm code, reducing the amount of storage space needed by the Contracts 36 | pallet on your blockchain. 37 | 38 | ### Runtime Environment Types 39 | 40 | For writing contracts and interacting with the runtime, a set of types are available (e.g. 41 | `AccountId`, `Balance`, `Hash`, `Timestamp`). These types can be user defined for custom runtimes, 42 | or the supplied defaults can be used. See: [EnvTypes](env-types) 43 | 44 | ### Contract Calls 45 | 46 | Calls to contracts can alter the storage of the contract, create new contracts, and call other 47 | contracts. Because Substrate provides you with the ability to write custom runtime pallets, the 48 | Contracts pallet also enables you to make asynchronous calls directly to those runtime functions on 49 | behalf of the contract's account. 50 | 51 | ### Sandboxed 52 | 53 | The Contracts pallet is intended to be used by any user on a public network. This means that 54 | contracts only have the ability to directly modify their own storage. To provide safety to the 55 | underlying blockchain state, the Contracts pallet enables revertible transactions, which roll back 56 | any changes to the storage by contract calls that do not complete successfully. 57 | 58 | ### Gas 59 | 60 | Contract calls are charged a gas fee to limit the amount of computational resources a transaction 61 | can use. When forming a contract transaction, a gas limit is specified. As the contract executes, 62 | gas is incrementally used up depending on the complexity of the computation. If the gas limit is 63 | reached before the contract execution completes, the transaction fails, contract storage is 64 | reverted, and the gas fee is **not** returned to the user. If the contract execution completes with 65 | remaining gas, it is returned to the user at the end of the transaction. 66 | 67 | The Contracts pallet determines the gas price, which is a conversion between the Substrate 68 | `Currency` and a single unit of gas. Thus, to execute a transaction, a user must have a free balance 69 | of at least `gas price` \* `gas limit` which can be spent. 70 | 71 | ### Storage Rent 72 | 73 | Similar to how gas limits the amount of computational resources that can be used during a 74 | transaction, storage rent limits the footprint that a contract can have on the blockchain's storage. 75 | A contract account is charged proportionally to the amount of storage its account uses. When a 76 | contract's balance goes below a defined limit, the contract's account is turned into a "tombstone" 77 | and its storage is cleaned up. A tombstone contract can be restored by providing the data that was 78 | cleaned up when it became a tombstone as well as any additional funds needed to keep the contract 79 | alive. 80 | 81 | ## ink! 82 | 83 | ink! is a Rust-based embedded domain specific language 84 | ([eDSL](https://wiki.haskell.org/Embedded_domain_specific_language)) for writing Wasm smart 85 | contracts specifically for the Contracts pallet. The main goals of ink! are user friendliness, 86 | conciseness, and efficiency. 87 | 88 | ### Abstraction Layers 89 | 90 | The ink! language is composed of three different layers of abstractions with which you can write 91 | smart contracts: 92 | 93 | - [Lang](https://github.com/paritytech/ink/tree/master/lang): The actual eDSL to provide a 94 | user-friendly interface to writing smart contract code. 95 | - [Core](https://github.com/paritytech/ink/tree/master/core): The core utilities and APIs used to 96 | interact with the Contracts pallet. 97 | 98 | We expect that most users will develop using the language layer, but thanks to the other 99 | abstractions, it is possible for developers to create their own Rust eDSL for their specific needs. 100 | 101 | ### Contract Components 102 | 103 | ink! should feel familiar to developers who have programmed using other modern smart contract 104 | languages. The skeleton of a contract has all of the same components that you might expect: 105 | 106 | - Events 107 | - Storage 108 | - Deployment (Constructor) Function 109 | - Public Functions 110 | - Internal functions 111 | 112 | In ink!, mutability and visibility are explicitly defined per contract function. In these functions, 113 | you gain access to a number of common Substrate types like `AccountId`, `Balances`, `Hash`, etc. 114 | Additionally, you gain access to commonly used environment variables like the `caller`, `balance`, 115 | `gas_left`, and more! 116 | 117 | ### Overflow Safety 118 | 119 | Being written in Rust, ink! can provide compile-time overflow/underflow safety. Using a Rust 120 | compiler configuration, you can specify whether you want to support overflowing math, or if you want 121 | contract execution to panic when overflows occur. No need to continually import "Safe Math" 122 | libraries, although Rust also provides 123 | [integrated checked, wrapped, and saturated math functions](https://doc.rust-lang.org/std/primitive.u32.html). 124 | 125 | ### Test Environment 126 | 127 | ink! provides a built in test environment that can be used to perform off-chain unit testing with 128 | the Rust framework. This makes it simple and easy to ensure that your contract code functions as 129 | expected, without the need for third party testing platforms. 130 | -------------------------------------------------------------------------------- /current/smart-contracts/ink-development.md: -------------------------------------------------------------------------------- 1 | --- 2 | slug: ink-development 3 | lang: en 4 | title: ink! Development 5 | --- 6 | 7 | ink! is a [Rust](https://www.rust-lang.org/)-based embedded domain specific language 8 | ([eDSL](https://wiki.haskell.org/Embedded_domain_specific_language)) for writing 9 | [WebAssembly](https://webassembly.org/) smart contracts specifically for the 10 | [FRAME Contracts pallet](/current/smart-contracts/contracts-pallet.md). 11 | 12 | ink! is still under development, so the documentation for using it is sparse. However, on this page 13 | you will find the best resources to get you started building ink! contracts right away. 14 | 15 | ## Tutorials 16 | 17 | The ink! project maintains an up-to-date tutorial teaching all the basics of developing on ink!. 18 | 19 | **This is the best way to get start learning the language today.** 20 | 21 | Start the ink! tutorial! 23 | 24 | You will learn how to: 25 | 26 | - Set up your computer to build and deploy ink! smart contracts. 27 | - Learn the basics of ink! by creating an incrementer contract. 28 | - Learn more advance tricks by developing an ERC20 contract. 29 | 30 | ## Example Contracts 31 | 32 | ink! provides a 33 | [set of example smart contracts](https://github.com/paritytech/ink/tree/master/examples) that can 34 | help you understand how it is similar and different to other smart contract languages. 35 | 36 | This includes: 37 | 38 | - [A Flipper Contract](https://github.com/paritytech/ink/tree/master/examples/flipper/) 39 | - [An ERC20 Contract](https://github.com/paritytech/ink/tree/master/examples/erc20/) 40 | - [An ERC721 Contract](https://github.com/paritytech/ink/tree/master/examples/erc721/) 41 | - [A Delegator Contract](https://github.com/paritytech/ink/tree/master/examples/delegator/) 42 | 43 | ## FAQ 44 | 45 | Here are some answers to frequently asked questions developers have while building on ink!. 46 | 47 | ### What is the difference between memory and storage? 48 | 49 | In ink!, `memory` refers to computer memory, while `storage` refers to the on-chain storage used by 50 | a contract instance. `memory` is temporary and only lasts until the contract execution is done, 51 | while `storage` is persistent and lasts over many contract executions. The contract `storage` is 52 | built on top of the runtime storage, and access is considered to be slow. 53 | 54 | #### Example 55 | 56 | While a `storage::Vec` stores all of its elements in different cells in the contract storage, a 57 | `storage::Value>` would store all elements (and a length info) in a single cell. 58 | Smart contract developers can use this to optimize for certain use cases. For example, using a 59 | `storage::Value>` would probably be more efficient for storing a small amount of 60 | elements in the `memory::Vec`. In general, we recommend using the more general `storage::Vec` for 61 | storing information on the contract instance. 62 | 63 | ### What is the test environment? 64 | 65 | ink! provides a test environment 66 | ([test_env](https://github.com/paritytech/ink/blob/master/core/src/env/test_env.rs)) which is used 67 | to emulate contract execution off-chain. This can be enabled by the crate feature `test-env` and is 68 | mainly used for running tests off-chain. 69 | 70 | ### How do I run off-chain tests? 71 | 72 | When building a smart contract with ink!, you can define a set of tests that can be run using the 73 | off-chain test environment. 74 | 75 | For example, in the minimal 76 | [flipper contract](https://github.com/paritytech/ink/blob/master/examples/flipper/src/lib.rs), you 77 | can find a small off-chain test at the bottom of the contract. 78 | 79 | You should run this test just like you would any other Rust test: 80 | 81 | ```bash 82 | cargo +nightly test 83 | ``` 84 | 85 | ## Get Help 86 | 87 | Join the growing community of ink! smart contract developers: 88 | 89 | - Ask development questions on [StackOverflow](https://stackoverflow.com/questions/tagged/ink) with 90 | the `ink` tag. 91 | - Join the live chat in the 92 | [Smart Contracts & Parity ink!](https://riot.im/app/#/room/!tYUCYdSvSYPMjWNDDD:matrix.parity.io) 93 | on Riot. 94 | - Report bugs, make feature requests, and ask technical questions on the 95 | [ink! GitHub](https://github.com/paritytech/ink). 96 | 97 | ## Next Steps 98 | 99 | ### Learn More 100 | 101 | - Learn more about the design philosophy of 102 | [ink! in our conceptual documentation](/current/smart-contracts/ink-fundamentals.md). 103 | - Learn more about the [Contracts pallet](https://docs.rs/pallet-contracts). 104 | 105 | ### Examples 106 | 107 | - Follow a 108 | [tutorial to add this Contracts pallet to your Substrate runtime](https://substrate.dev/docs/en/tutorials/adding-a-module-to-your-runtime/). 109 | 110 | ### References 111 | 112 | - Visit the 113 | [ink! repository for additional docs and to look at the source](https://github.com/paritytech/ink). 114 | - Visit the reference docs for the [ink! abi](https://paritytech.github.io/ink/ink_abi/). 115 | - Visit the reference docs for the [ink! core](https://paritytech.github.io/ink/ink_core/). 116 | -------------------------------------------------------------------------------- /current/smart-contracts/ink-fundamentals.md: -------------------------------------------------------------------------------- 1 | --- 2 | slug: ink-fundamentals 3 | lang: en 4 | title: ink! Concepts 5 | --- 6 | 7 | ink! is a [Rust](https://www.rust-lang.org/)-based embedded domain specific language 8 | ([eDSL](https://wiki.haskell.org/Embedded_domain_specific_language)) for writing 9 | [Wasm](https://webassembly.org/) smart contracts specifically for the 10 | [FRAME Contracts pallet](/current/smart-contracts/contracts-pallet.md). 11 | 12 | ## Design 13 | 14 | The main goals of ink! are correctness, conciseness, and efficiency. 15 | 16 | ink! is designed to be as close to the Rust programming language as possible. The language uses 17 | [attribute macros](https://doc.rust-lang.org/reference/procedural-macros.html#attribute-macros) to 18 | tag standard Rust structures into understandable contract components. 19 | 20 | ```rust 21 | #[ink(...)] 22 | ``` 23 | 24 | Because ink! follows Rust standards, tools like `rustfmt` and `rust-analyzer` already work out of 25 | the box. 26 | 27 | ### Contract Components 28 | 29 | ink! should still feel familiar to developers who have programmed using other modern smart contract 30 | languages. The skeleton of a contract has all of the same components that you might expect: 31 | 32 | - Events 33 | - Event Topics 34 | - Storage 35 | - Constructor Functions 36 | - Message Functions 37 | 38 | ### Custom Types 39 | 40 | ink! supports custom type definitions needed to interact with the Substrate runtime. By default, 41 | ink! has access to all the [primitive Substrate types](../runtime/primitives) like `AccountId`, 42 | `Balance`, `Hash`, etc... 43 | 44 | You can specify and interact with additional types which may be specific to your Substrate runtime 45 | environment. 46 | 47 | ### Overflow Safety 48 | 49 | Being written in Rust, ink! can provide compile-time overflow/underflow safety. Using a Rust 50 | compiler configuration, you can specify whether you want to support overflowing math, or if you want 51 | contract execution to panic when overflows occur. No need to continually import "Safe Math" 52 | libraries, although Rust also provides 53 | [integrated checked, wrapped, and saturated math functions](https://doc.rust-lang.org/std/primitive.u32.html). 54 | 55 | > Note: There are some known issues regarding functionality of compiler level overflow checks and 56 | > the resulting size of the Wasm blob. This feature may change or be iterated on in the future. 57 | 58 | ### Test Environment 59 | 60 | ink! provides a built in test environment that can be used to perform off-chain unit testing with 61 | the Rust framework. This makes it simple and easy to ensure that your contract code functions as 62 | expected, without the need for third party testing platforms. 63 | 64 | ## ink! vs Solidity 65 | 66 | Rust is an ideal smart contract language. It is type safe, memory safe, and free of undefined 67 | behaviors. It generates small binaries because it doesn’t include extra bloat, like a garbage 68 | collector, and advanced optimizations and tree shaking remove dead code. Through compiler flags, 69 | Rust can automatically protect against integer overflow. 70 | 71 | ink! chooses not to invent a new programming language, but rather adapt a subset of Rust to serve 72 | this purpose. As a result, you gain from all of the tooling and support available to the Rust 73 | ecosystem for free. In addition, as the language develops, ink! will automatically gain access to 74 | new features and functionality, improving how you can write smart contracts in the future. 75 | 76 | Here is a brief comparison of features between ink! and Solidity: 77 | 78 | | | ink! | Solidity | 79 | | --------------------- | --------------------------- | ------------------------------------------------------------ | 80 | | Virtual Machine | Any Wasm VM | EVM | 81 | | Encoding | Wasm | EVM Byte Code | 82 | | Language | Rust | Standalone | 83 | | Overflow Protection | Enabled by default | None | 84 | | Constructor Functions | Multiple | Single | 85 | | Tooling | Anything that supports Rust | Custom | 86 | | Versioning | Semantic | Semantic | 87 | | Has Metadata? | Yes | Yes | 88 | | Multi-File Project | Planned | Yes | 89 | | Storage Entries | Variable | 256 bits | 90 | | Supported Types | [Docs](../advanced/codec) | [Docs](https://solidity.readthedocs.io/en/latest/types.html) | 91 | | Has Interfaces? | Planned (Rust Traits) | Yes | 92 | 93 | ## Next Steps 94 | 95 | ### Learn More 96 | 97 | - Learn about the [FREAME Contracts Pallet](https://docs.rs/pallet-contracts) which is used to 98 | deploy and execute ink! contracts. 99 | 100 | ### Examples 101 | 102 | - Follow our 103 | [tutorial to create your first ink! smart contract](https://substrate.dev/substrate-contracts-workshop/). 104 | 105 | ### References 106 | 107 | - Visit the 108 | [ink! repository for additional docs and to look at the source](https://github.com/paritytech/ink). 109 | 110 | - Visit the reference docs for the [ink! abi](https://paritytech.github.io/ink/ink_abi/). 111 | 112 | - Visit the reference docs for the [ink! core](https://paritytech.github.io/ink/ink_core/). 113 | -------------------------------------------------------------------------------- /current/smart-contracts/overview.md: -------------------------------------------------------------------------------- 1 | --- 2 | slug: overview 3 | lang: en 4 | title: Overview 5 | --- 6 | 7 | This page is an overview on the state of smart contracts in Substrate. 8 | 9 | ## Virtual Machines 10 | 11 | FRAME provides two smart contract virtual machines which can be added to your Substrate runtime. 12 | 13 | ### Contracts Module 14 | 15 | The **FRAME Contracts pallet** (SEAL) provides functionality for the runtime to deploy and execute 16 | WebAssembly smart-contracts. It is designed to iterate on the design of modern smart contract 17 | platforms. 18 | 19 | ### EVM Module 20 | 21 | The [FRAME EVM pallet](evm-pallet) provides an EVM execution environment that allows unmodified EVM 22 | code to be executed in a Substrate-based blockchain. It is designed to most closely emulate the 23 | functionality of executing contracts on the Ethereum mainnet within the Substrate runtime. 24 | 25 | ### Custom 26 | 27 | Substrate is not a platform where you are limited with what comes out of the box. 28 | 29 | We encourage further development of alternative smart contract platforms on top of the Substrate 30 | runtime. Use these pre-built modules to inform how you might design your own system or port over 31 | existing systems to work on a Substrate based chain. 32 | 33 | ## Smart Contract Languages 34 | 35 | ### ink! 36 | 37 | [ink!](ink-fundamentals) is a Rust-based eDSL for writing Wasm smart contracts specifically for the 38 | [Contracts module](#contracts-module). It is designed for correctness, conciseness and efficiency. 39 | 40 | ## Smart Contracts vs Runtime Modules 41 | 42 | Substrate runtime modules and Substrate smart contracts are two different approaches to building 43 | "decentralized applications" using the Substrate framework. 44 | 45 | ### Smart Contracts 46 | 47 | A traditional smart contract platform allows users to publish additional logic on top of some core 48 | blockchain logic. Since smart contract logic can be published by anyone, including malicious actors 49 | and inexperienced developers, there are a number of intentional safe guards built around these 50 | public smart contract platform. 51 | 52 | Some examples are: 53 | 54 | - **Fees**: Ensuring that contract developers are charged for the computation and storage they force 55 | on the computers running their contract, and not allowed to abuse the block creators. 56 | - **Sandbox**: A contract is not able to modify core blockchain storage or the storage of other 57 | contracts directly. It's power is limited to only modifying it's own state, and the ability to 58 | make outside calls to other contracts or runtime functions. 59 | - **State Rent**: A contract takes up space on the blockchain, and thus should be charged for simply 60 | existing. This ensures that people don't take advantage of "free, unlimited storage". 61 | - **Reversion**: A contract can be prone to have situations which lead to logical errors. The 62 | expectations of a contract developer are low, so extra overhead is added to support reverting 63 | transactions when they fail so no state is updated when things go wrong. 64 | 65 | These different overheads makes running contracts slower and more costly, but again, the "target 66 | audience" for contract development is different than runtime developers. 67 | 68 | Contracts can allow your community to extend and develop on top of your runtime logic without 69 | needing to go through all the craziness of proposals, runtime upgrades, etc... It may even be used 70 | as a testing grounds for future runtime changes, but done in a way that isolates your network from 71 | any of the growing pains or errors which may occur. 72 | 73 | **In summary**, Substrate Smart Contracts: 74 | 75 | - Are inherently safer to the network. 76 | - Have built in economic incentives against abuse. 77 | - Have computational overhead to support graceful failures in logic. 78 | - Have a lower bar to entry for development. 79 | - Enable fast pace community interaction through a playground to write new logic. 80 | 81 | ### Runtime Modules 82 | 83 | Runtime modules on the other hand afford none of these protections or safe guards that Smart 84 | Contracts give you. As a runtime developer, the bar to entry on the code you produce jumps way up. 85 | 86 | You have full control of the underlying logic that each node on your network will run. You have full 87 | access to each and every storage item across all of your modules, which you can modify and control. 88 | You can even brick your chain with incorrect logic or poor error handling. 89 | 90 | Substrate runtime module development has the intention of producing lean, performant, and fast 91 | nodes. It provides none of the protections or overhead of transaction reverting, and does not 92 | implicitly introduce any fee system to the computation which nodes on your chain run. This mean 93 | while you are developing runtime functions, it is up to _you_ to correctly assess and apply fees to 94 | the different parts of your runtime logic such that it will not be abused by bad actors and hurt 95 | your network. 96 | 97 | **In summary**, Substrate Runtime Modules: 98 | 99 | - Provide low level access to your entire blockchain. 100 | - Have removed the overhead of built-in safety for performance. 101 | - Have a high bar to entry for developers. 102 | - Not necessarily to write working code, but to avoid writing broken code. 103 | - Has no inherent economic incentives to repel bad actors. 104 | 105 | ### The Right Tool For You 106 | 107 | Substrate runtime modules and Substrate smart contracts are tools made available to you to solve 108 | problems. 109 | 110 | There is likely some amount of overlap in the kinds of problems each one can solve, but there is 111 | also a clear set of problems suited for only one of the two. To give just one example in each 112 | category: 113 | 114 | - Runtime Module: Building a privacy layer on top of transactions in your blockchain. 115 | - Shared: Building a gaming dApp which may need to build up a community of users (leaning toward 116 | Smart Contract), or may need to scale to millions of transactions a day (leaning toward Runtime 117 | Module). 118 | - Smart Contract: Introducing multi-signature wallets over the currency of your blockchain. 119 | 120 | In addition to everything written above, you also need to take into account the costs to set up a 121 | DApp using a certain tool. Deploying a contract is a relatively simple and easy process since you 122 | take advantage of the existing network. The only costs to you are those fees which you pay to deploy 123 | and maintain your contract. 124 | 125 | Setting up your own blockchain on the other hand has the cost of building a community who find value 126 | in your service or establishing a private network with the overhead of cloud computing system and 127 | general network maintenance. 128 | 129 | It is hard to provide direct guidance on every possible scenario, but use the table below to help 130 | influence your decision on the kinds of situations you may want to use these different tools: 131 | 132 | 133 | 134 | 135 | 136 | 137 | 138 | 139 | 149 | 162 | 167 | 168 |
Runtime ModuleEitherSmart Contract
140 | 141 | - Privacy Layer 142 | - Feeless Token 143 | - Light-Client Bridge 144 | - Decentralized Exchange 145 | - Oracles 146 | - Stable Coin 147 | 148 | 150 | 151 | - Game dApp 152 | - Small scale (contract) 153 | - Large scale (runtime) 154 | - Decentralized Autonomous Organizations (DAO) 155 | - Community driven (contract) 156 | - Protocol driven (runtime) 157 | - Treasury 158 | - Community driven (contract) 159 | - Protocol driven (runtime) 160 | 161 | 163 | 164 | - Multi-signature Wallet 165 | 166 |
169 | 170 | ## Next Steps 171 | 172 | ### Learn More 173 | 174 | - See how Substrate is iterating on smart contract blockchains with the 175 | [Contracts pallet](contracts-pallet). 176 | - Investigate the [EVM pallet](evm-pallet) to see if it is what you need for your next project. 177 | - Read about the [ink! smart contract language](ink-fundamentals). 178 | 179 | ### Examples 180 | 181 | - Follow a 182 | [tutorial to add a runtime module to your Substrate runtime](tutorials/adding-a-module-to-your-runtime.md). 183 | - Learn how to 184 | [start developing with the Contracts pallet and ink!](/current/smart-contracts/ink-development.md). 185 | 186 | ### References 187 | 188 | - Visit the reference docs for the 189 | [Contracts pallet](https://crates.parity.io/pallet_contracts/index.html). 190 | - Visit the reference docs for the 191 | [EVM pallet](https://crates.parity.io/pallet_evm/index.html). 192 | - Take a look at the [repository for ink!](https://github.com/paritytech/ink). 193 | --------------------------------------------------------------------------------