├── .github └── workflows │ ├── markdown-links.config.json │ └── markdown-links.yml ├── .gitignore ├── 0000-template.md ├── CODE_OF_CONDUCT.md ├── LICENSE ├── README.md ├── assets ├── 0001-state-diagram.puml ├── 0001-state-diagram.svg └── 0004 │ ├── 0004-api-call-direct.puml │ ├── 0004-api-call-direct.svg │ ├── 0004-api-call.puml │ ├── 0004-api-call.svg │ ├── 0004-dh-init.puml │ ├── 0004-dh-init.svg │ ├── 0004-open-wallet-direct.puml │ ├── 0004-open-wallet-direct.svg │ ├── 0004-open-wallet.puml │ └── 0004-open-wallet.svg └── text ├── 0001-rfc-process.md ├── 0002-grin-governance.md ├── 0003-security-process.md ├── 0004-full-wallet-lifecycle.md ├── 0005-variable-size-kernels.md ├── 0006-payment-proofs.md ├── 0007-node-api-v2.md ├── 0008-wallet-state-management.md ├── 0009-enable-faster-sync.md ├── 0010-online-transacting-via-tor.md ├── 0011-security-team.md ├── 0012-compact-slates.md ├── 0013-nrd-kernels.md ├── 0014-general-fund-guidelines.md ├── 0015-slatepack.md ├── 0016-simplify-governance.md ├── 0017-fix-fees.md ├── 0018-fix-daa.md ├── 0019-deprecate-http-tx.md ├── 0020-pibd-messages.md ├── 0021-fix-prior-fees.md └── 0022-pibd-deployment.md /.github/workflows/markdown-links.config.json: -------------------------------------------------------------------------------- 1 | { 2 | "timeout": "20s", 3 | "retryOn429": true, 4 | "retryCount": 5, 5 | "fallbackRetryDelay": "30s", 6 | "aliveStatusCodes": [200, 206], 7 | "ignorePatterns": [ 8 | { 9 | "pattern": "https://github.com/mimblewimble/grin-rfcs/pull/0000" 10 | } 11 | ] 12 | } 13 | -------------------------------------------------------------------------------- /.github/workflows/markdown-links.yml: -------------------------------------------------------------------------------- 1 | name: Check Markdown links 2 | 3 | on: 4 | push: 5 | branches: 6 | - master 7 | pull_request: 8 | branches: 9 | - '*' 10 | 11 | jobs: 12 | markdown-link-check: 13 | runs-on: ubuntu-latest 14 | steps: 15 | - uses: actions/checkout@master 16 | - uses: gaurav-nelson/github-action-markdown-link-check@v1 17 | with: 18 | use-quiet-mode: 'yes' 19 | use-verbose-mode: 'yes' 20 | config-file: '.github/workflows/markdown-links.config.json' 21 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | *.swp 2 | -------------------------------------------------------------------------------- /0000-template.md: -------------------------------------------------------------------------------- 1 | 2 | - Title: [edit and replace with a unique name like so: `my-awesome-proposal`] 3 | - Authors: [Your Name](mailto:your@email.com) 4 | - Start date: [edit and replace the day work begun, i.e. `Jan 15, 2019`] 5 | - RFC PR: Edit if merged: [mimblewimble/grin-rfcs#0000](https://github.com/mimblewimble/grin-rfcs/pull/0000) 6 | - Tracking issue: [Edit if merged with link to tracking github issue] 7 | 8 | --- 9 | 10 | ## Summary 11 | [summary]: #summary 12 | 13 | One paragraph explanation of the improvement. 14 | 15 | ## Motivation 16 | [motivation]: #motivation 17 | 18 | Why are we doing this? What use cases does it support? What is the expected outcome? 19 | 20 | ## Community-level explanation 21 | [community-level-explanation]: #community-level-explanation 22 | 23 | Explain the proposal as if it were already introduced into the Grin ecosystem and you were teaching it to another community member. That generally means: 24 | 25 | - Introducing new named concepts. 26 | - Explaining the feature largely in terms of examples. 27 | - Explaining how Grin community members should *think* about the improvement, and how it should impact the way they interact with Grin. It should explain the impact as concretely as possible. 28 | - If applicable, provide sample error messages, deprecation warnings, or migration guidance. 29 | - If applicable, describe the differences between teaching this to existing Grin community members and new Grin community members. 30 | 31 | For implementation-oriented RFCs (e.g. for wallet), this section should focus on how wallet contributors should think about the change, and give examples of its concrete impact. For policy RFCs, this section should provide an example-driven introduction to the policy, and explain its impact in concrete terms. 32 | 33 | ## Reference-level explanation 34 | [reference-level-explanation]: #reference-level-explanation 35 | 36 | This is the technical portion of the RFC. Explain the design in sufficient detail that: 37 | 38 | - Its interaction with other features is clear. 39 | - It is reasonably clear how the feature would be implemented. 40 | - Corner cases are dissected by example. 41 | 42 | The section should return to the examples given in the previous section, and explain more fully how the detailed proposal makes those examples work. 43 | 44 | ## Drawbacks 45 | [drawbacks]: #drawbacks 46 | 47 | Why should we *not* do this? 48 | 49 | ## Rationale and alternatives 50 | [rationale-and-alternatives]: #rationale-and-alternatives 51 | 52 | - Why is this design the best in the space of possible designs? 53 | - What other designs have been considered and what is the rationale for not choosing them? 54 | - What is the impact of not doing this? 55 | 56 | ## Prior art 57 | [prior-art]: #prior-art 58 | 59 | Discuss prior art, both the good and the bad, in relation to this proposal. 60 | A few examples of what this can include are: 61 | 62 | - For core, node, wallet and infrastructure proposals: Does this feature exist in other projects and what experience have their community had? 63 | - For community, ecosystem and moderation proposals: Is this done by some other community and what were their experiences with it? 64 | - For other teams: What lessons can we learn from what other communities have done here? 65 | - Papers: Are there any published papers or great posts that discuss this? If you have some relevant papers to refer to, this can serve as a more detailed theoretical background. 66 | 67 | This section is intended to encourage you as an author to think about the lessons from other languages, provide readers of your RFC with a fuller picture. If there is no prior art, that is fine - your ideas are interesting to us whether they are brand new or if it is an adaptation from other projects. 68 | 69 | Note that while precedent set by other projects is some motivation, it does not on its own motivate an RFC. 70 | Please also take into consideration that Grin sometimes intentionally diverges from common project features. 71 | 72 | ## Unresolved questions 73 | [unresolved-questions]: #unresolved-questions 74 | 75 | - What parts of the design do you expect to resolve through the RFC process before this gets merged? 76 | - What parts of the design do you expect to resolve through the implementation of this feature before stabilization? 77 | - What related issues do you consider out of scope for this RFC that could be addressed in the future independently of the solution that comes out of this RFC? 78 | 79 | ## Future possibilities 80 | [future-possibilities]: #future-possibilities 81 | 82 | Think about what the natural extension and evolution of your proposal would be and how it would affect the project and ecosystem as a whole in a holistic way. Try to use this section as a tool to more fully consider all possible interactions with the project and language in your proposal. Also consider how it fits into the road-map of the project and of the relevant sub-team. 83 | 84 | This is also a good place to "dump ideas", if they are out of scope for the RFC you are writing but otherwise related. 85 | 86 | If you have tried and cannot think of any future possibilities, you may simply state that you cannot think of anything. 87 | 88 | Note that having something written down in the future-possibilities section is not a reason to accept the current or a future RFC; such notes should be in the section on motivation or rationale in this or subsequent RFCs. The section merely provides additional information. 89 | 90 | ## References 91 | [references]: #references 92 | 93 | Include any references such as links to other documents or reference implementations. 94 | 95 | - [reference 1](#references) 96 | - [reference 2](#references) 97 | -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Code of Conduct 2 | 3 | The Code of Conduct for this repository [can be found online](https://grin.mw/policies/code_of_conduct). -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | 2 | Apache License 3 | Version 2.0, January 2004 4 | http://www.apache.org/licenses/ 5 | 6 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 7 | 8 | 1. Definitions. 9 | 10 | "License" shall mean the terms and conditions for use, reproduction, 11 | and distribution as defined by Sections 1 through 9 of this document. 12 | 13 | "Licensor" shall mean the copyright owner or entity authorized by 14 | the copyright owner that is granting the License. 15 | 16 | "Legal Entity" shall mean the union of the acting entity and all 17 | other entities that control, are controlled by, or are under common 18 | control with that entity. For the purposes of this definition, 19 | "control" means (i) the power, direct or indirect, to cause the 20 | direction or management of such entity, whether by contract or 21 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 22 | outstanding shares, or (iii) beneficial ownership of such entity. 23 | 24 | "You" (or "Your") shall mean an individual or Legal Entity 25 | exercising permissions granted by this License. 26 | 27 | "Source" form shall mean the preferred form for making modifications, 28 | including but not limited to software source code, documentation 29 | source, and configuration files. 30 | 31 | "Object" form shall mean any form resulting from mechanical 32 | transformation or translation of a Source form, including but 33 | not limited to compiled object code, generated documentation, 34 | and conversions to other media types. 35 | 36 | "Work" shall mean the work of authorship, whether in Source or 37 | Object form, made available under the License, as indicated by a 38 | copyright notice that is included in or attached to the work 39 | (an example is provided in the Appendix below). 40 | 41 | "Derivative Works" shall mean any work, whether in Source or Object 42 | form, that is based on (or derived from) the Work and for which the 43 | editorial revisions, annotations, elaborations, or other modifications 44 | represent, as a whole, an original work of authorship. For the purposes 45 | of this License, Derivative Works shall not include works that remain 46 | separable from, or merely link (or bind by name) to the interfaces of, 47 | the Work and Derivative Works thereof. 48 | 49 | "Contribution" shall mean any work of authorship, including 50 | the original version of the Work and any modifications or additions 51 | to that Work or Derivative Works thereof, that is intentionally 52 | submitted to Licensor for inclusion in the Work by the copyright owner 53 | or by an individual or Legal Entity authorized to submit on behalf of 54 | the copyright owner. For the purposes of this definition, "submitted" 55 | means any form of electronic, verbal, or written communication sent 56 | to the Licensor or its representatives, including but not limited to 57 | communication on electronic mailing lists, source code control systems, 58 | and issue tracking systems that are managed by, or on behalf of, the 59 | Licensor for the purpose of discussing and improving the Work, but 60 | excluding communication that is conspicuously marked or otherwise 61 | designated in writing by the copyright owner as "Not a Contribution." 62 | 63 | "Contributor" shall mean Licensor and any individual or Legal Entity 64 | on behalf of whom a Contribution has been received by Licensor and 65 | subsequently incorporated within the Work. 66 | 67 | 2. Grant of Copyright License. Subject to the terms and conditions of 68 | this License, each Contributor hereby grants to You a perpetual, 69 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 70 | copyright license to reproduce, prepare Derivative Works of, 71 | publicly display, publicly perform, sublicense, and distribute the 72 | Work and such Derivative Works in Source or Object form. 73 | 74 | 3. Grant of Patent License. Subject to the terms and conditions of 75 | this License, each Contributor hereby grants to You a perpetual, 76 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 77 | (except as stated in this section) patent license to make, have made, 78 | use, offer to sell, sell, import, and otherwise transfer the Work, 79 | where such license applies only to those patent claims licensable 80 | by such Contributor that are necessarily infringed by their 81 | Contribution(s) alone or by combination of their Contribution(s) 82 | with the Work to which such Contribution(s) was submitted. If You 83 | institute patent litigation against any entity (including a 84 | cross-claim or counterclaim in a lawsuit) alleging that the Work 85 | or a Contribution incorporated within the Work constitutes direct 86 | or contributory patent infringement, then any patent licenses 87 | granted to You under this License for that Work shall terminate 88 | as of the date such litigation is filed. 89 | 90 | 4. Redistribution. You may reproduce and distribute copies of the 91 | Work or Derivative Works thereof in any medium, with or without 92 | modifications, and in Source or Object form, provided that You 93 | meet the following conditions: 94 | 95 | (a) You must give any other recipients of the Work or 96 | Derivative Works a copy of this License; and 97 | 98 | (b) You must cause any modified files to carry prominent notices 99 | stating that You changed the files; and 100 | 101 | (c) You must retain, in the Source form of any Derivative Works 102 | that You distribute, all copyright, patent, trademark, and 103 | attribution notices from the Source form of the Work, 104 | excluding those notices that do not pertain to any part of 105 | the Derivative Works; and 106 | 107 | (d) If the Work includes a "NOTICE" text file as part of its 108 | distribution, then any Derivative Works that You distribute must 109 | include a readable copy of the attribution notices contained 110 | within such NOTICE file, excluding those notices that do not 111 | pertain to any part of the Derivative Works, in at least one 112 | of the following places: within a NOTICE text file distributed 113 | as part of the Derivative Works; within the Source form or 114 | documentation, if provided along with the Derivative Works; or, 115 | within a display generated by the Derivative Works, if and 116 | wherever such third-party notices normally appear. The contents 117 | of the NOTICE file are for informational purposes only and 118 | do not modify the License. You may add Your own attribution 119 | notices within Derivative Works that You distribute, alongside 120 | or as an addendum to the NOTICE text from the Work, provided 121 | that such additional attribution notices cannot be construed 122 | as modifying the License. 123 | 124 | You may add Your own copyright statement to Your modifications and 125 | may provide additional or different license terms and conditions 126 | for use, reproduction, or distribution of Your modifications, or 127 | for any such Derivative Works as a whole, provided Your use, 128 | reproduction, and distribution of the Work otherwise complies with 129 | the conditions stated in this License. 130 | 131 | 5. Submission of Contributions. Unless You explicitly state otherwise, 132 | any Contribution intentionally submitted for inclusion in the Work 133 | by You to the Licensor shall be under the terms and conditions of 134 | this License, without any additional terms or conditions. 135 | Notwithstanding the above, nothing herein shall supersede or modify 136 | the terms of any separate license agreement you may have executed 137 | with Licensor regarding such Contributions. 138 | 139 | 6. Trademarks. This License does not grant permission to use the trade 140 | names, trademarks, service marks, or product names of the Licensor, 141 | except as required for reasonable and customary use in describing the 142 | origin of the Work and reproducing the content of the NOTICE file. 143 | 144 | 7. Disclaimer of Warranty. Unless required by applicable law or 145 | agreed to in writing, Licensor provides the Work (and each 146 | Contributor provides its Contributions) on an "AS IS" BASIS, 147 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 148 | implied, including, without limitation, any warranties or conditions 149 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 150 | PARTICULAR PURPOSE. You are solely responsible for determining the 151 | appropriateness of using or redistributing the Work and assume any 152 | risks associated with Your exercise of permissions under this License. 153 | 154 | 8. Limitation of Liability. In no event and under no legal theory, 155 | whether in tort (including negligence), contract, or otherwise, 156 | unless required by applicable law (such as deliberate and grossly 157 | negligent acts) or agreed to in writing, shall any Contributor be 158 | liable to You for damages, including any direct, indirect, special, 159 | incidental, or consequential damages of any character arising as a 160 | result of this License or out of the use or inability to use the 161 | Work (including but not limited to damages for loss of goodwill, 162 | work stoppage, computer failure or malfunction, or any and all 163 | other commercial damages or losses), even if such Contributor 164 | has been advised of the possibility of such damages. 165 | 166 | 9. Accepting Warranty or Additional Liability. While redistributing 167 | the Work or Derivative Works thereof, You may choose to offer, 168 | and charge a fee for, acceptance of support, warranty, indemnity, 169 | or other liability obligations and/or rights consistent with this 170 | License. However, in accepting such obligations, You may act only 171 | on Your own behalf and on Your sole responsibility, not on behalf 172 | of any other Contributor, and only if You agree to indemnify, 173 | defend, and hold each Contributor harmless for any liability 174 | incurred by, or claims asserted against, such Contributor by reason 175 | of your accepting any such warranty or additional liability. 176 | 177 | END OF TERMS AND CONDITIONS 178 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Grin RFCs 2 | 3 | This repository contains all [Grin Project](https://grin.mw) RFCs that have been proposed and accepted by the Grin community for further consideration. 4 | 5 | Grin RFCs may cover (but are not limited to) technical enhancements, changes to the governance structure or changes to project processes. 6 | 7 | ## Getting started 8 | 9 | To begin writing your own RFC or to find out more about the process and the general RFC guidelines, refer to [the RFC that established this process](text/0001-rfc-process.md). 10 | 11 | ## List of accepted RFCs 12 | 13 | |Title|Status|Tl;dr| 14 | |:---|---|:---| 15 | | [0001-rfc-process](text/0001-rfc-process.md) | ACTIVE | Introduce RFC process | 16 | | [0002-grin-governance](text/0002-grin-governance.md) | RETIRED | ~~Articulate community values, define core and sub-teams~~ Replaced by RFC#6. | 17 | | [0003-security-process](text/0003-security-process.md) | ACTIVE | Define community standards for ethical disclosure behaviour | 18 | | [0004-full-wallet-lifecycle](text/0004-full-wallet-lifecycle.md) | ACTIVE | Define API standard for sensitive wallet operations | 19 | | [0005-variable-size-kernels](text/0005-variable-size-kernels.md) | ACTIVE | Introduce kernel variants that can be of different sizes | 20 | | [0006-payment-proofs](text/0006-payment-proofs.md) | ACTIVE | Support generating and validating payment proofs for sender-initiated (i.e. non-invoice) transactions | 21 | | [0007-node-api-v2](text/0007-node-api-v2.md) | ACTIVE | Create a v2 JSON-RPC API for the Node API | 22 | | [0008-wallet-state-management](text/0008-wallet-state-management.md) | ACTIVE | Improve wallet state management | 23 | | [0009-enable-faster-sync](text/0009-enable-faster-sync.md) | ACTIVE | Enable faster txhashset sync by changing output MMR commitment | 24 | | [0010-online-transacting-via-tor](text/0010-online-transacting-via-tor.md) | RETIRED | ~~Define standard for transacting via Tor~~ Replaced by RFC#0015. | 25 | | [0011-security-team](text/0011-security-team.md) | ACTIVE | Establish Grin Security team | 26 | | [0012-compact-slates](text/0012-compact-slates.md)| ACTIVE | Introduce new compact slate format (Slate V4) | 27 | | [0013-nrd-kernels](text/0013-nrd-kernels.md) | ACTIVE | Introduce relative timelocks through "No Recent Duplicate" transaction kernels | 28 | | [0014-general-fund-guidelines](text/0014-general-fund-guidelines.md) | ACTIVE | Define general fund spending guidelines | 29 | | [0015-slatepack](text/0015-slatepack.md) | ACTIVE | Universal transaction standard for Grin. Replaces RFC#0010. | 30 | | [0016-simplify-governance](text/0016-simplify-governance.md) | ACTIVE | Simplify Grin governance model. Replaces RFC#0002. | 31 | | [0017-fix-fees](text/0017-fix-fees.md) | ACTIVE | Change minimum relay fees to be weight proportional, make output creation cost 0.01 Grin. | 32 | | [0018-fix-daa](text/0018-fix-daa.md) | ACTIVE | Change DAA (Difficulty Adjustment Algorithm) from damped simple moving average (dsma) to a weighted-target exponential moving average (wtema). Restrict the future-time-limit (FTL) window to 5 minutes. | 33 | | [0019-deprecate-http-tx](text/0019-deprecate-http-tx.md) | ACTIVE | Deprecating HTTP(S) as a transaction method in grin-wallet. | 34 | | [0020-pibd-messages](text/0020-pibd-messages.md) | ACTIVE | Define new peer-to-peer messages to enable a novel sync method, using packets of self-contained partial state that can be downloaded and verified independently from each other. | 35 | | [0021-fix-prior-fees](text/0021-fix-prior-fees.md) | ACTIVE | Carry the restriction of fees, to 40 bits since HF4, back to all history. | 36 | | [0022-pibd-deployment](text/0022-pibd-deployment.md) | ACTIVE | Rollout of Parallel Independent Block Download (PIBD) functionality. | 37 | 38 | ## License 39 | 40 | Apache License 2.0 41 | 42 | ### Contributions 43 | 44 | Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, shall be licensed as above, without any additional terms or conditions. 45 | -------------------------------------------------------------------------------- /assets/0001-state-diagram.puml: -------------------------------------------------------------------------------- 1 | @startuml 2 | hide empty description 3 | skinparam shadowing false 4 | 5 | [*] -down-> long1 : [author]\nSubmit a PR to /grin-rfcs 6 | 7 | state "PR is Open" as long1 { 8 | draft : * tag sub-team 9 | draft : * assign shepherd 10 | draft : * feedback from community 11 | draft : * iterate on proposal 12 | draft -right-> FCP : [shepherd]\nEnter Final Comment Period 13 | FCP: * include disposition to merge/close/postpone 14 | FCP: * final feedback from community 15 | FCP: * final touches on proposal 16 | FCP -left-> draft : [shepherd]\nCancel FCP 17 | } 18 | 19 | state close_join <> 20 | draft --> close_join 21 | FCP --> close_join 22 | 23 | state post_join <> 24 | draft --> post_join 25 | FCP --> post_join 26 | 27 | state "PR is Closed" as long2 { 28 | close_join -down-> closed : Close RFC 29 | post_join -down-> postponed : Postpone RFC 30 | } 31 | 32 | state "PR is Merged" as long3 { 33 | FCP -right-> active : [shepherd]\nMerge RFC 34 | active --> active : Minor changes\nthrough new PR 35 | active: * assign RFC number 36 | active: * create tracking issue in relevant repo 37 | active: * make note if superseded by a new RFC 38 | } 39 | 40 | postponed --> draft : Re-open PR 41 | postponed --> [*] 42 | closed --> [*] 43 | active --> [*] 44 | @enduml -------------------------------------------------------------------------------- /assets/0001-state-diagram.svg: -------------------------------------------------------------------------------- 1 | PR is OpenPR is ClosedPR is Mergeddrafttag sub-teamassign shepherdfeedback from communityiterate on proposalFCPinclude disposition to merge/close/postponefinal feedback from communityfinal touches on proposalclosedpostponedactiveassign RFC numbercreate tracking issue in relevant repomake note if superseded by a new RFC[author]Submit a PR to /grin-rfcs[shepherd]Enter Final Comment Period[shepherd]Cancel FCPClose RFCPostpone RFC[shepherd]Merge RFCMinor changesthrough new PRRe-open PR -------------------------------------------------------------------------------- /assets/0004/0004-api-call-direct.puml: -------------------------------------------------------------------------------- 1 | @startuml 2 | actor "Client" as client 3 | participant "Internal Rust API" as rustapi 4 | participant "Wallet Backend" as backend 5 | 6 | title Wallet API Call (Directly Linked) 7 | 8 | == API Call == 9 | client -> client: Stored token **t** 10 | client -> rustapi: call_api_function(**t**, **other_params**) 11 | rustapi -> backend: retrieve_seed(**t**) 12 | backend -> backend: calc(**t** ^ **seedT**) -> **seed** 13 | rustapi -> backend: Internal Wallet Calls 14 | backend -> backend: Drop **seed** 15 | rustapi -> client: Return (**return_data**) 16 | @enduml -------------------------------------------------------------------------------- /assets/0004/0004-api-call-direct.svg: -------------------------------------------------------------------------------- 1 | Wallet API Call (Directly Linked)ClientClientInternal Rust APIInternal Rust APIWallet BackendWallet BackendAPI CallStored tokentcall_api_function(t,other_params)retrieve_seed(t)calc(t^seedT) ->seedInternal Wallet CallsDropseedReturn (return_data) -------------------------------------------------------------------------------- /assets/0004/0004-api-call.puml: -------------------------------------------------------------------------------- 1 | @startuml 2 | actor "Client" as client 3 | participant "JSON-RPC API (if used)" as jsonrpc 4 | participant "Internal Rust API" as rustapi 5 | participant "Wallet Backend" as backend 6 | 7 | title Wallet API Call via JSON-RPC 8 | 9 | 10 | == API Call == 11 | client -> client: Supply stored token **t** in **req** as **req.t** 12 | client -> client: enc(**req**, **s**) -> **reqEnc** 13 | client -> jsonrpc: call_api_function(**reqEnc**) 14 | jsonrpc -> jsonrpc: dec(**reqEnc**, **s**) -> **req** 15 | jsonrpc -> rustapi: call_api_function(**req**) 16 | rustapi -> backend: retrieve_seed(**req.t** as **t**) 17 | backend -> backend: calc(**t** ^ **seedT**) -> **seed** 18 | rustapi -> backend: Internal Wallet Calls 19 | backend -> backend: Drop **seed** 20 | rustapi -> jsonrpc: Return (**resp**) 21 | jsonrpc -> jsonrpc: enc(**resp**, **s**) -> (**respEnc**) 22 | jsonrpc -> client: Return (**respEnc**) 23 | client -> client: dec(**s**, **respEnc**) -> **resp** 24 | @enduml -------------------------------------------------------------------------------- /assets/0004/0004-dh-init.puml: -------------------------------------------------------------------------------- 1 | @startuml 2 | actor "Client" as client 3 | participant "JSON-RPC API" as jsonrpc 4 | participant "Internal Rust API" as rustapi 5 | participant "Wallet Backend" as backend 6 | 7 | title Wallet JSON-RPC API ECDH Initialization 8 | 9 | == Initialization (ECDH/secp256k1)== 10 | client -> client: Calc Pub ECDH Key (**cP**) 11 | client -> jsonrpc: init_api_secure (**cP**) 12 | jsonrpc -> jsonrpc: Calc Pub ECDH Key (**sP**) 13 | jsonrpc -> jsonrpc: Calc + store shared secret (**s**) 14 | jsonrpc -> client: **sP** 15 | client -> client: Calc + store shared secret (**s**) 16 | @enduml -------------------------------------------------------------------------------- /assets/0004/0004-dh-init.svg: -------------------------------------------------------------------------------- 1 | Wallet JSON-RPC API ECDH InitializationClientClientJSON-RPC APIJSON-RPC APIInternal Rust APIInternal Rust APIWallet BackendWallet BackendInitialization (ECDH/secp256k1)Calc Pub ECDH Key (cP)init_api_secure (cP)Calc Pub ECDH Key (sP)Calc + store shared secret (s)sPCalc + store shared secret (s) -------------------------------------------------------------------------------- /assets/0004/0004-open-wallet-direct.puml: -------------------------------------------------------------------------------- 1 | @startuml 2 | actor "Client" as client 3 | participant "Internal Rust API" as rustapi 4 | participant "Wallet Backend" as backend 5 | 6 | title Opening a Wallet (Directly Linked) 7 | 8 | == Open Wallet == 9 | client -> client: Supply password **pw** 10 | client -> rustapi: open_wallet(**pw**, **other_params**) 11 | rustapi -> rustapi: Generate Random Token (**t**) 12 | rustapi -> backend: open_Wallet(**t**, **pw**) 13 | backend -> backend: Decrypt seed(**req.pw**) -> **seed** 14 | backend -> backend: Store **seed**^**t** -> (**seedT**) 15 | rustapi -> rustapi: Include **t** in **return_data** 16 | rustapi -> client: Return (**return_data**) 17 | client -> client: Store **return_data.t** as **t** 18 | client -> client: Supply **t** as parameter to all other API calls 19 | @enduml -------------------------------------------------------------------------------- /assets/0004/0004-open-wallet-direct.svg: -------------------------------------------------------------------------------- 1 | Opening a Wallet (Directly Linked)ClientClientInternal Rust APIInternal Rust APIWallet BackendWallet BackendOpen WalletSupply passwordpwopen_wallet(pw,other_params)Generate Random Token (t)open_Wallet(t,pw)Decrypt seed(req.pw) ->seedStoreseed^t-> (seedT)Includetinreturn_dataReturn (return_data)Storereturn_data.tastSupplytas parameter to all other API calls -------------------------------------------------------------------------------- /assets/0004/0004-open-wallet.puml: -------------------------------------------------------------------------------- 1 | @startuml 2 | actor "Client" as client 3 | participant "JSON-RPC API" as jsonrpc 4 | participant "Internal Rust API" as rustapi 5 | participant "Wallet Backend" as backend 6 | 7 | title Opening a Wallet in Secure Mode via JSON-RPC API 8 | 9 | == Open Wallet == 10 | client -> client: Supply password field **pw** in **req** as **req.pw** 11 | client -> client: enc(**req**, **s**) -> **reqEnc** 12 | client -> jsonrpc: open_wallet(**reqEnc**) 13 | jsonrpc -> jsonrpc: dec(**reqEnc**, **s**) -> **req** 14 | jsonrpc -> rustapi: open_wallet(**req**) 15 | rustapi -> rustapi: Generate Random Token (**t**) 16 | rustapi -> backend: Open Wallet(**t**, **req.pw**) 17 | backend -> backend: Decrypt seed(**req.pw**) -> **seed** 18 | backend -> backend: Store **seed**^**t** -> (**seedT**) 19 | rustapi -> rustapi: Include **t** in **resp** as **resp.t** 20 | rustapi -> jsonrpc: Return (**resp**) 21 | jsonrpc -> jsonrpc: enc(**resp**, **s**) -> (**respEnc**) 22 | jsonrpc -> client: Return (**respEnc**) 23 | client -> client: dec(**s**, **respEnc**) -> **resp** 24 | client -> client: Store **resp.t** as **t** 25 | client -> client: All further API requests contain **t** 26 | @enduml -------------------------------------------------------------------------------- /text/0001-rfc-process.md: -------------------------------------------------------------------------------- 1 | 2 | - Title: rfc-process 3 | - Authors: [joltz](mailto:joltz@protonmail.com), [yeastplume](mailto:yeastplume@protonmail.com), [lehnberg](mailto:daniel.lehnberg@protonmail.com) 4 | - Start date: June 21st, 2019 5 | 6 | --- 7 | 8 | ## Summary 9 | [summary]: #summary 10 | 11 | The "RFC" (request for comments) process is intended to provide a consistent and controlled path for improvements to be made to Grin. 12 | 13 | ## Motivation 14 | [motivation]: #motivation 15 | 16 | Many changes, including bug fixes and documentation improvements can be implemented and reviewed via the normal GitHub pull request workflow. 17 | 18 | Some changes though are "substantial", and could benefit from being put through a more formal design process in order to produce a consensus among Grin community participants and stakeholders. 19 | 20 | ## When this process should be followed 21 | [when-this-process-should-be-followed]: #when-this-process-should-be-followed 22 | 23 | You need to follow this process if you intend to make "substantial" changes to the Grin codebase or governance process. What constitutes a "substantial" change may evolve based on community norms and individual definitions of sub-teams, but may include the following. 24 | 25 | - Any semantic or syntactic change to the wallet, node, miner, or underlying crypto libraries that is not a bugfix. 26 | - Major changes in ecosystem content such as the docs, site or explorer. 27 | - Removing Grin features, including those that are feature-gated. 28 | 29 | Some changes do not require an RFC: 30 | 31 | - Rephrasing, reorganizing, refactoring, or changes that are not visible to Grin's users. 32 | - Additions that strictly improve objective, numerical quality criteria (warning removal, speedup, better platform coverage, more parallelism, trap more errors, etc.) 33 | - Additions only likely to be _noticed by_ other developers-of-grin, invisible to users-of-grin. 34 | 35 | If you submit a pull request to implement a new feature without going through the RFC process, it may be closed with a polite request to submit an RFC first. 36 | 37 | ### Team specific guidelines 38 | 39 | _To be added here once available._ 40 | 41 | ## Before creating an RFC 42 | [Before creating an RFC]: #before-creating-an-rfc 43 | 44 | A hastily-proposed RFC can hurt its chances of acceptance. Low quality proposals, proposals for previously-rejected features, or those that don't fit into the near-term roadmap, may be quickly rejected, which can be demotivating for the unprepared contributor. Laying some groundwork ahead of the RFC can make the process smoother. 45 | 46 | Although there is no single way to prepare for submitting an RFC, it is generally a good idea to pursue feedback from other project contributors 47 | beforehand, to ascertain that the RFC may be desirable; having a consistent impact on the project requires concerted effort toward consensus-building. 48 | 49 | Ways to prepare and pave the way for writing and submitting an RFC include discussing the topic or posting "pre-RFCs" to our [forum](https://forum.grin.mw) for feedback. 50 | 51 | As a rule of thumb, receiving encouraging feedback from long-standing project contributors, and particularly members of the relevant team (if applicable) is a good indication that the RFC is worth pursuing. 52 | 53 | ## Process description 54 | [process-description]: #process-description 55 | 56 | In order to make a "substantial" change to Grin, one must first get an RFC merged into the RFC repo as a markdown file. At that point the RFC is "active" and may be implemented with the goal of eventual inclusion into Grin. 57 | 58 | ![process state diagram](../assets/0001-state-diagram.svg) 59 | 60 | ### Stages in detail 61 | 62 | #### Submission 63 | * Fork the RFC repo https://github.com/mimblewimble/grin-rfcs 64 | * Copy `0000-template.md` to `text/0000-my-feature.md` (where 65 | "my-feature" is descriptive. don't assign an RFC number yet). 66 | * If you include any assets, do so as `/assets/0000-asset-description.xxx` 67 | * Write the RFC according to the template instructions. 68 | * Submit a pull request. As a pull request the RFC will receive design feedback from the larger community, and the author should be prepared to revise it in response. 69 | 70 | #### Draft 71 | 72 | * Each pull request will be labeled with the most relevant team, which will lead to it being triaged by that team and is assigned a shepherd from this team. The shepherd ensures the RFC progresses through the process and that a decision is reached, but they themselves do not make this decision. 73 | * As the author, you build consensus and integrate feedback. RFCs that have broad support are much more likely to make progress than those that don't receive any comments. They are encouraged to reach out to the RFC shepherd in particular to get help identifying stakeholders and obstacles. 74 | * The relevant team discuss the RFC pull request, as much as possible in the comment thread of the pull request itself. Offline discussion will be summarized on the pull request comment thread. 75 | * RFCs rarely go through this process unchanged, especially as alternatives and drawbacks are shown. As an author you can make edits, big and small, to the RFC to clarify or change the design,but make changes as new commits to the pull request, and leave a comment on the pull request explaining your changes. Specifically, do not squash or rebase commits after they are visible on the pull request. 76 | 77 | #### Final Comment Period (FCP) 78 | 79 | * At some point, a member of the assigned team will propose a "motion for final comment period" (FCP), along with a *disposition* for the RFC (merge, close, or postpone). 80 | * This step is taken when enough of the tradeoffs have been discussed that the team is in a position to make a decision. That does not require consensus amongst all participants in the RFC thread (which is usually impossible). However, the argument supporting the disposition on the RFC needs to have already been clearly articulated, and there should not be a strong consensus *against* that position outside of the team. Team members use their best judgment in taking this step, and the FCP itself ensures there is ample time and notification for stakeholders to push back if it is made prematurely. 81 | * For RFCs with lengthy discussion, the motion to FCP is usually preceded by a *summary comment* trying to lay out the current state of the discussion and major tradeoffs/points of disagreement. 82 | * The FCP lasts ten calendar days, so that it is open for at least 5 business days. It is also advertised widely (i.e. in [Grin News](https://grinnews.substack.com)). This way all stakeholders have a chance to lodge any final objections before a decision is reached. 83 | * In most cases, the FCP period is quiet, and the RFC is either merged or closed. However, sometimes substantial new arguments or ideas are raised, the FCP is canceled, and the RFC goes back into draft mode. 84 | 85 | #### Active 86 | 87 | * As FCP concludes and there are no objections to accepting the RFC, it gets merged into `/grin-rfcs` and becomes "active". 88 | * Before merging, the shepherd: 89 | * updates the RFC to give it an RFC number (which is the same as the number of the initial Pull Request). 90 | * Renames the markdown file accordingly and any accompanied assets. 91 | * If a tracking issue on the repo affected by the RFC has created, it is linked to in the header. 92 | * Once active, the authors may then implement it and submit the feature as a pull request to the relevant repo. 93 | * Being "active" is not a rubber stamp, and in particular still does not mean the feature will ultimately be merged; it does mean that in principle all the major stakeholders have agreed to the feature and are amenable to merging it. 94 | * Furthermore, the fact that a given RFC has been accepted and is "active" implies nothing about what priority is assigned to its implementation, nor does it imply anything about whether a developer has been assigned the task of implementing the feature. 95 | * While it is not necessary that the author of the RFC also write the implementation, it is by far the most effective way to see an RFC through to completion: authors should not expect that other project contributors will take on responsibility for implementing their accepted feature. 96 | * Modifications to "active" RFCs can be done in follow-up pull requests. We strive to write each RFC in a manner that it will reflect the final design of the feature; but the nature of software development means that we cannot expect every merged RFC to actually reflect what the end result will be at the time of implementation. 97 | * In general, once accepted, RFCs should not be substantially changed. Only very minor changes should be submitted as amendments. More substantial changes should be new RFCs, with a note added to the original RFC. Exactly what counts as a "very minor change" is up to the team to decide; check team specific guidelines for more details. 98 | 99 | #### Postponed 100 | 101 | * Some RFC pull requests are tagged with the "postponed" label when they are closed (as part of the rejection process). 102 | * An RFC closed with "postponed" is marked as such because we want neither to think about evaluating the proposal nor about implementing the described feature until some time in the future, and we believe that we can afford to wait until then to do so. 103 | * Postponed pull requests may be re-opened when the time is right. We don't have any formal process for that, you should ask members of the relevant team. 104 | * Usually an RFC pull request marked as "postponed" has already passed an informal first round of evaluation, namely the round of "do we think we would ever possibly consider making this change, as outlined in the RFC pull request, or some semi-obvious variation of it." (When the answer to the latter question is "no", then the appropriate response is to close the RFC, not postpone it.) 105 | 106 | #### Closed 107 | 108 | * A proposed RFC can be closed at any time before reaching "active" state. This is done by closing the pull request itself. This would happen for example if there is no support in the community for the proposal or if there are other underlying reasons why this is not a change the community wants to make. 109 | 110 | ### Changes to the RFC process 111 | 112 | In the spirit of the proposed process itself, a future "substantial" overhaul to the RFC process should be opened as a new RFC rather than making edits to this RFC. Minor changes can be made by opening pull requests against this document. 113 | 114 | As the RFC process is something that should be consistent across all teams and the project as a whole, changes to the process fall under Core's remit. As they evaluate proposals to modify the process, they are expected to consult with teams, and other stakeholders using or being affected by the process. 115 | 116 | ## Drawbacks 117 | [drawbacks]: #drawbacks 118 | 119 | * May not encourage sufficient community engagement 120 | * May slow down needed features 121 | * May allow some features to be included too quickly 122 | 123 | ## Rationale and alternatives 124 | [rationale-and-alternatives]: #rationale-and-alternatives 125 | 126 | Alternatively, retain the current informal RFC process. The proposed RFC process is designed to improve over the informal process in the following ways: 127 | 128 | * Discourage unactionable or vague RFCs 129 | * Ensure that all serious RFCs are considered equally 130 | * Improve transparency for how new features are added to Grin 131 | * Give confidence to those with a stake in Grin's development that they 132 | understand why new features are being merged 133 | * Assist the Grin community with feature and release planning. 134 | 135 | As an alternative, we could adopt an even stricter RFC process than the one proposed here. We could for example look to Bitcoin's BIP or Python's PEP process for inspiration. 136 | 137 | ## Prior art 138 | [prior-art]: #prior-art 139 | 140 | This process draws inspiration _extensively_ from Rust's RFC process, where much credit for the process is due. 141 | 142 | Most decentralized cryptocurrency projects have adopted an RFC-like process to manage adding new features. 143 | 144 | Bitcoin uses BIPs which are an adaptation of Python's PEPs. These processes are similar to the Rust RFC process which has had success in the Rust community as well as in other cryptocurrency projects like Peercoin. 145 | 146 | ## Unresolved questions 147 | [unresolved-questions]: #unresolved-questions 148 | 149 | 1. Does this RFC strike a favorable balance between formality and agility? 150 | 2. Does this RFC address the issues with the current informal process adequately? 151 | 152 | ## Future possibilities 153 | [future-possibilities]: #future-possibilities 154 | 155 | This proposal was initially based on an RFC process for codebase development. As the process evolves it will have a larger impact in the governance of Grin. This is a relatively new area of exploration as governance processes can have 156 | wide ranging impacts on the ecosystem as a whole. 157 | 158 | Just as it is important to hone the language to support the development process and life-cycle, it is also important to sharpen the language to support governance processes and life-cycles for the Grin ecosystem. 159 | 160 | ## References 161 | [references]: #references 162 | 163 | - [https://github.com/rust-lang/rfcs](https://github.com/rust-lang/rfcs) 164 | - [https://github.com/bitcoin/bips/blob/master/bip-0001.mediawiki](https://github.com/bitcoin/bips/blob/master/bip-0001.mediawiki) 165 | - [https://www.python.org/dev/peps/pep-0001/](https://www.python.org/dev/peps/pep-0001/) 166 | -------------------------------------------------------------------------------- /text/0002-grin-governance.md: -------------------------------------------------------------------------------- 1 | 2 | - Title: grin-governance 3 | - Authors: [lehnberg](mailto:daniel.lehnberg@protonmail.com), [yeastplume](mailto:yeastplume@protonmail.com) 4 | - Start date: June 24th, 2019 5 | - Tracking issue: [mimblewimble/grin-pm/#167](https://github.com/mimblewimble/grin-pm/issues/167) 6 | 7 | --- 8 | 9 | ## RETIRED 10 | This RFC has been retired and has been superseded by [RFC#0016: simplify-governance](0016-simplify-governance.md). 11 | 12 | --- 13 | 14 | ## Summary 15 | [summary]: #summary 16 | 17 | Evolve Grin's governance: 18 | - Define general community principles; 19 | - Convert council into core team and define its responsibilities and processes; 20 | - Introduce RFC process; 21 | - Introduce self-governing teams that steward and guide work in each of their focus areas. 22 | 23 | ## Motivation 24 | [motivation]: #motivation 25 | 26 | ### Background 27 | 28 | Grin's governance today consists of the Grin Technocratic Council, and the rest of the community. The council came to be as there was a need for some sub-set of community members to manage the multi-sig keys of the Grin General Fund, and it became a modest first pass at a governance structure. Over time, it has come to be that a lot of responsibilities and day to day tasks are handled by Grin council members. This puts a heavy workload on council members, but it also inhibits other members of the community from becoming more engaged, contributing more, and becoming recognized for it. Naturally this implies that either the council would have to grow large in order to be able to fit all the members of the community that deserve recognition for their contributions, or that we end up not rewarding active contributors properly. 29 | 30 | In addition, as most decisions up to this point have been taken in the bi-weekly meetings, it's come to be that decisions take time to materialize: It can take up to 14 days just to have the initial conversation and sometimes multiples of that to reach an agreement. In these meetings the entire active community ends up participating in every discussion in a synchronous fashion that often does not end up being productive. 31 | 32 | We have also struggled to answer more fundamental questions about Grin's governance, as in how decisions are made, who has authority to make these, and what the path is for a community member who would like to take on greater responsibilities. 33 | 34 | This is a proposal to evolve our governance process. 35 | 36 | ### Objectives 37 | 38 | - **Reward and recognize contributions better.** Offer different ways to become more engaged and give better recognition for work 39 | - **Empower more to contribute.** Encourage more community members to participate, facilitate more initiative. 40 | - **Make Grin less centralized.** Rather than relying on a small group of people, share responsibilities and make the project more resilient against shocks. 41 | - **Create a more transparent process.** 42 | 43 | ### Not objectives 44 | 45 | - **Do not create fiefdoms.** Do not create emperors. Nobody is the boss of anybody else. 46 | - **Do not create bureaucracy for the sake of bureaucracy.** Do not impose death by a thousand papercuts or let forms and administration get in the way of making progress. 47 | - **Do not discourage contributions.** Nobody can prevent someone else from doing work. Anyone can contribute in which ever way they find meaningful. You do not need to ask for permission. 48 | 49 | ## Community-level explanation 50 | [community-level-explanation]: #community-level-explanation 51 | 52 | This proposal outlines a set of loose principles to guide the work we do. While some of these may already be in use, they might not have been articulated before. It converts the council into a core team, and outlines its responsibilities for the first time. In addition, it's proposed that additional teams are introduced alongside it, as well as an RFC process. An initial teams breakdown is suggested, and the proposal concludes with a path to adoption. 53 | 54 | ### General principles 55 | 56 | - **Lead by example.** "Cypherpunks write code." We don't tell others what to do. We do what we can, and if we need to we ask for help. We suggest, but never command. We act as we want others to act. 57 | - **Not a democracy.** We are evaluated based on the work we do. It's not a popularity contest, and the majority is not always right. Community members are here by their free will, participation is optional. 58 | - **Influence is measured by recent and not historical work.** We are grateful for and respect historical contributions, but they do not lead to lifelong positions of authority. Influence is earned by making contributions consistently over time, allowing new contributors to join the ranks of the old. 59 | - **Transparency.** Where possible, discussions and decisions are made in the open. We have nothing to hide, and we do not try to limit oversight unless there's a defensible reason to do so. 60 | - **Keep things lightweight.** We strive to only put in place the minimal structure and organization that's needed, neither more nor less. 61 | - **Groups organize themselves.** Structures do not need to be imposed tops down, and we recognise that what works for one group will not necessarily work for the other. Teams self-organize and define their own workflows and processes as they see fit. 62 | - **Consensus-seeking decision making.** Voting creates winners and losers, and is polarizing. We recognize there are trade offs with everything and rarely any single right answer. This does not mean design by committee. We seek consensus through dialogue and discussion, but where there is a lack of consensus, we do not let it block us indefinitely. We're ready to make judgment calls to the best of our abilities. 63 | - **We speak for ourselves.** We can only speak in the name of ourselves, as contributors to the project. We do not write blog posts, articles, tweets, or give interviews speaking on behalf of the project as a whole. Grin itself has no single voice. 64 | - **There's no need to ask for permission.** We are not afraid to take decisions. We ask for feedback and opinions from others, but we do not need to ask for somebody's permission. If we believe it's in the best interest of Grin, we act, and are accountable for our actions. 65 | - **Mistakes are tolerated.** As with any organization structure, mistakes happen. This is understood, and mistakes are accepted. We try to learn from them and improve. We assume we all act in good faith, until proven otherwise. 66 | 67 | ### Core team 68 | 69 | The existing grin council is proposed to be renamed to core team. 70 | 71 | Over time, it's intended to be a broad representation of the wider community with diverse stakeholders. 72 | 73 | #### Responsibilities 74 | 75 | The core team leads the wider Grin project as a whole. In particular: 76 | 77 | * **Sets overall direction and vision.** Values and philosophies. Steering towards use cases and targets. 78 | * **Sets priorities and plans releases.** Maintains high level planning, roadmaps, focus areas, decides on pace and the release schedule. 79 | * **Work on broader, cross-sectional issues.** What falls in-between teams, taking a global view. 80 | * **Adds and removes teams.** While proposals for new teams can come from anywhere, the core team is responsible to ensure structures are productive and make sense. 81 | * **Appoints initial team leadership.** Once a new team is established, core appoints a leader that has the responsibility to grow the team. 82 | * **Responsible for security.** Handles disclosures, vulnerabilities, audits, processes. 83 | * **Handles multi-sig keys and takes high level spending decisions.** Spending proposals can be made by anyone, and teams can have their own own budgets to deal with as they please. 84 | 85 | #### Organization & Processes 86 | 87 | - There's no defined maximum size of the team. 88 | - New members are added through a core decision; A core member can nominate a new member for inclusion, there’s discussion, and the process is consensus seeking. 89 | - The general decision making process is consensus seeking - no majority rule based voting, but also not blocked by lack of explicit consensus. 90 | - Core members have no explicit veto, but strong objections are considered. 91 | - Nominations and discussions are kept private. 92 | - The term of core members is currently undefined but may change in the future. 93 | - A core member can resign by notifying the rest of the team. 94 | - If unreachable for 30 days without any news, a core member can be removed through a core decision. 95 | - The core team *does not* make rulings on RFCs of other teams, although individual team members might also participate in the discussions of sub teams or be members of those teams. 96 | - Meeting notes should be published and made transparent to the community on a regular basis. 97 | 98 | ### RFC process 99 | 100 | An RFC is a Request For Comments document, outlining a proposed improvement or design change to an area of Grin. The exact specifics for the template is TBD. They are kept in their own dedicated repo and need to be accepted before a pull request is merged. Their purpose is to outline a standardized way of making proposals and allow the community to discuss and evaluate whether something is worth doing. Having an RFC accepted means that there's support "in theory" for the suggestion. It does not mean that a change becomes implemented automatically or in the exact way it is proposed, it is high-level design. The work still needs to be carried out. Accepted RFCs guide the broader planning work. 101 | 102 | ### Teams 103 | 104 | #### Overview 105 | 106 | Teams are groups organized around specific areas or knowledge fields. They are responsible for these areas, but do not do all the work. Anyone can contribute anywhere, and do not need to hold a particular title to do so. 107 | 108 | Rather, teams work on policies, processes, and workflows for their specific areas, as required. They are in charge of the RFC process in their specific field: They determine what requires an RFC in their area, they assign RFC shepherds that guide an RFC through its various stages and ensures the right stakeholders become aware of it and solicit their feedback. Ultimately, teams decide whether an RFC in their area should be accepted or rejected. They are responsible to ensure that each RFC in their area has a tracked status, and that they progress towards an outcome. 109 | 110 | Teams self-organize, but should be inclusive and adhere to community values. They should have a leader, often this leader may be part of the core team. They determine how members get added to the team. They should include area experts, and stakeholders. The decision making process should be consensus-seeking where possible. 111 | 112 | Teams can be broken down into smaller working groups or teams, permanent or temporary, as required and is seen necessary for them to be productive. 113 | 114 | Each team has a dedicated section on the forum, they should meet regularly, and keep some notes on what was covered and decided. Decisions do not need to happen in meetings, and could for example be handled asynchronously or in the RFC process. 115 | 116 | Meeting notes should be published and made transparent to the community on a regular basis. 117 | 118 | ### The teams 119 | 120 | In addition to Core team, the following teams are proposed to be created initially. 121 | 122 | * **Node development.** Core Grin technology, changes and optimizations to the node and anything consensus related, research and discussion of new technologies, proof of work. 123 | 124 | * **Wallet development.** wallet technology, wallet API, wallet-related research. 125 | 126 | * **Infrastructure.** Technical documentation, non-technical documentation, QA, testing, toolchain, developer productivity, guides, how-tos. 127 | 128 | * **Ecosystem.** 3rd party developers interaction (wallets, pools, exchanges and others), integration and technical assistance, growing the grin ecosystem, stakeholder collaboration. 129 | 130 | * **Community.** Onboarding of new community members, website, chat channels, conferences, events, meetups. 131 | 132 | * **Fundraising.** Sponsorships, donations, activities to increase project funds. 133 | 134 | * **Moderation.** Code of conduct, handles violations, across all areas of the project. To avoid biases and conflicts of interest, this team _does not_ contain any member of the core team. 135 | 136 | ### In case of conflicts, disagreement, or dissent 137 | 138 | Teams are created and appointed by the core, and core can decide to re-organize team structures and shut down dysfunctional teams. This is a "nuclear" option, such decisions should not be taken lightly. The repercussions of such actions can be worse than the initial situation. 139 | 140 | In practice, core team members might be engaging with teams as individual contributors. It is however not expected that "the core team" will become involved in the responsibilities of individual teams. Core sets the overall direction for the project, but should not micro manage teams as this defeats the entire purpose of having these teams in the first place. 141 | 142 | If there are conflicts within teams, these should ideally be resolved within the teams themselves. If this is not possible and there's contentious disagreements that need outside arbitration, teams can invite core or another team to become involved. 143 | 144 | ## Drawbacks 145 | [drawbacks]: #drawbacks 146 | 147 | - Adds a lot more structure. This might create overhead. 148 | - Could lead to infighting and conflict between teams. 149 | - Could lead to situations where one team does work that conflicts with other teams, "left hand not talking to the right". 150 | 151 | 152 | ## Rationale and alternatives 153 | [rationale-and-alternatives]: #rationale-and-alternatives 154 | 155 | * Keep the process as is. 156 | * Change the process to something else. 157 | 158 | ## Prior art 159 | [prior-art]: #prior-art 160 | 161 | Python conducted a comprehensive survey of the governance structures of various open source projects in 2018 through [PEP-8002](https://www.python.org/dev/peps/pep-8002/). This document is highly recommended reading for various alternative structures. 162 | 163 | ## Unresolved questions 164 | [unresolved-questions]: #unresolved-questions 165 | 166 | Far too many to all be listed here, but here are some: 167 | 168 | - Is this too much structure for the amount of active contributors we have? 169 | - Does this approach really address the problems as highlighted in the motivation? 170 | - Does this legitimize the core team enough in the community? 171 | 172 | ## Future possibilities 173 | [future-possibilities]: #future-possibilities 174 | 175 | - Introduce more teams 176 | - Introduce an electorate 177 | - Introduce terms 178 | - Define firmer structures and organizational rules 179 | 180 | ## References 181 | [references]: #references 182 | 183 | **Rust's governance process** 184 | 185 | - [https://rust-lang.github.io/rfcs/1068-rust-governance.html](https://rust-lang.github.io/rfcs/1068-rust-governance.html) 186 | - [https://web.archive.org/web/2019*/https://predictablynoisy.com/rust-governance](https://web.archive.org/web/2019*/https://predictablynoisy.com/rust-governance) 187 | - [http://mgattozzi.com/oss-governance-and-sustainablility-i/](http://mgattozzi.com/oss-governance-and-sustainablility-i/) 188 | 189 | **Node.js governance** 190 | 191 | - [https://medium.com/the-node-js-collection/healthy-open-source-967fa8be7951](https://medium.com/the-node-js-collection/healthy-open-source-967fa8be7951) 192 | 193 | **Swarmwise, by Rick Falkvinge** 194 | 195 | - [https://falkvinge.net/files/2013/04/Swarmwise-2013-by-Rick-Falkvinge-v1.1-2013Sep01.pdf](https://falkvinge.net/files/2013/04/Swarmwise-2013-by-Rick-Falkvinge-v1.1-2013Sep01.pdf) 196 | -------------------------------------------------------------------------------- /text/0004-full-wallet-lifecycle.md: -------------------------------------------------------------------------------- 1 | 2 | - Title: full-wallet-lifecycle 3 | - Authors: [Michael Cordner](mailto:yeastplume@protonmail.com) 4 | - Start date : June 26th, 2019 5 | - RFC PR: [mimblewimble/grin-rfcs#18](https://github.com/mimblewimble/grin-rfcs/pull/18) 6 | - Tracking issue: [mimblewimble/grin-wallet#212](https://github.com/mimblewimble/grin-wallet/issues/212) 7 | 8 | --- 9 | 10 | ## Summary 11 | [summary]: #summary 12 | 13 | Increase the scope of the Grin Wallet's Owner API to support full wallet lifecycle functions. 14 | 15 | ## Motivation 16 | [motivation]: #motivation 17 | 18 | Grin Wallet's APIs currently provides functions for transacting and querying the contents of the wallet. However, several pieces of functionality 19 | around wallet creation and seed/password management are not included within the API. This means that any consumers of the API will either expect their users 20 | to initialize the wallet manually before the APIs can be used, or provide custom management for wallet lifecycle functions. 21 | 22 | The Wallet APIs are intended to be the foundation upon which community-created wallets should be built, and the job of a wallet creator is made far 23 | more difficult by the absence of wallet creation and seed management functions within the API. Ideally, it should be the case that a wallet can 24 | be instantiated and managed solely via the Owner API. 25 | 26 | ## Community-level explanation 27 | [community-level-explanation]: #community-level-explanation 28 | 29 | From an end-user perspective, (i.e. end-users of community wallets that use the wallet API,) this change should be transparent. 30 | 31 | ## Reference-level explanation 32 | [reference-level-explanation]: #reference-level-explanation 33 | 34 | ### Wallet Initialization 35 | 36 | Currently, wallet data does not exist until the user runs `grin-wallet init`. The `init` command creates `grin-wallet.toml`, 37 | in the `~/.grin/main` directory (or `~/.grin/floonet`, or the current directory via the `-h` flag), prompts the user for a password, 38 | creates a seed file, stores the resulting data files in the directory specified in `grin-wallet.toml` (`~/.grin/main/wallet_data` by default) 39 | and initialises the lmdb database. 40 | 41 | It should be possible to run `grin-wallet owner_api` or invoke the API directly from a linked binary without having instantiated a wallet. 42 | 43 | ### Security Model 44 | 45 | Given that the Wallet's Owner API needs to deal with sensitive data such as passwords and seed phrases, the API will be enhanced with a new ECDH and Token-based security model, the primary goals of which are to: 46 | 47 | * Ensure sensitive data such as passwords or seed phrases are always end-to-end encrypted between the client and the Owner API server, regardless of what higher-level protocols are used during the exchange. 48 | * Minimize the potential for damage that can be done by a third party listening on the exchange between a wallet client and its corresponding server. 49 | * Ensure that sensitive data such as passwords or seed phrases are not resident in server-side memory any longer than they absolutely need to be. 50 | 51 | Note that this mode of operation is primarily intended for use over the JSON-RPC API, which supports many different architectural possiblities. Clients that link libraries directly and keep all sensitive data in the same process would see less benefit from this scheme, and an alternative model which doesn't encrypt any sensitive data is provided. Further, authors of existing wallets will need time to consider and/or implement the added complexity needed on the client-side to support ECDH and encryption. It's therefore proposed that the Owner API initially provide the new "SecureAPI" mode as an optional feature, with wallet authors strongly encouraged to make use of it. Support for the "InsecureAPI" model can be maintained indefinitely for directly-linked wallets, and for the JSON-RPC API until a cut-off release at some point in the future. 52 | 53 | Note that the "SecureAPI" mode and all lifecycle functions will be implemented in a V3 API, with the V2 API maintained for a time for backwards compatibility. The V3 API requires all JSON-RPC communication to be encrypted, with the exception of the `init_secure_api` function. 54 | 55 | #### SecureAPI Mode 56 | 57 | SecureAPI Mode consists of an ECDH key agreement followed by the establishment of an API Token that's used to XOR encrypt the wallet seed on the server side. The negotiated ECDH shared key is used to encrypt all requests and responses between the client and the JSON-RPC layer, while the token must be included in all API requests to allow the wallet backend to decrypt the seed. 'Open' wallets store their in-memory seeds XORed against the token, which is temporarily XORed against the supplied token during each request to reproduce the master seed. 58 | 59 | ECDH will use secp256k1 for key agreement. 60 | 61 | Encryption of JSON-RPC requests and responses will be performed using AEAD in GCM mode with 128-bit tags, 96 bit nonces, a 16 byte suffix length and an empty vector for the additional data. A 12 byte nonce will be applied in the encryption and included in each request/response to use on the decrypting side. 62 | 63 | Encrypted requests and responses will be exchanged in valid JSON-RPC calls with the method "encrypted_request_v3" (with 'v3' here denoting the version of the API). They will have the following form: 64 | 65 | ``` 66 | { 67 | "jsonrpc": "2.0", 68 | "method: "encrypted_request_v3", 69 | "id": "1", 70 | "params": { 71 | "nonce": "ef32...", 72 | "body_enc": "e0bcd..." 73 | } 74 | } 75 | ``` 76 | 77 | ##### Security Mode Initialization 78 | 79 | To initialize the Secure API, clients will generate an EC keypair using the secp256k1 curve, and provide the public key to the Owner API server via a new `init_secure_api` method. Both client and server will calculate the shared key, and store this key for the remainder of the session. The sequence of operations is outlined below: 80 | 81 | ![init_secure_api](../assets/0004/0004-dh-init.svg) 82 | 83 | The Secure API assumes that all requests (other than the actual call to `init_secure_api` itself) will be encrypted with the shared secret and presented in the above JSON-RPC format. All API calls other than `open_wallet` will be accompanied with a valid encrypted token derived during the call to the `open_wallet` function. This assumption will remain until the server process exits or a call to a corresponding `close_api_secure` function is called. 84 | 85 | The shared secret can be refreshed by the client at any time with another call to `init_secure_api` (either encrypted or unencrypted). Closing a wallet via the `close_wallet` function does not regenerate the shared secret but does invalidate the token and drops the XORed seed from memory. 86 | 87 | ##### Legacy support 88 | 89 | The V2 API will remain active for a time the mode of operation for its JSON-RPC API will be assumed to work as currently, i.e. requests and responses are unencrypted, the wallet stores its full seed in-memory between requests and the providing of a token with each request is not requred. However, the new lifecycle functions described in this RFC, which deal with highly sensitive data such as passwords and master keys, will not be available in the V2 API. This setup should allow existing wallets to continue working as-is until a cutoff release for legacy mode is determined. 90 | 91 | ##### Opening a Wallet in SecureAPI Mode 92 | 93 | Opening a wallet in SecureAPI mode consists of encrypting a request to `open_wallet` (which contains the wallet password) with the shared secret `s`. The request is decrypted in the JSON-RPC layer and the password is used in the wallet backend to unlock the wallet master seed. The master seed is stored XORed against a randomly-generated token T, which is returned to the client in an encrypted response for inclusion in all further API calls. T is valid for the lifetime of the process, or until a corresponding call to `close_wallet`. 94 | 95 | ![open_wallet](../assets/0004/0004-open-wallet.svg) 96 | 97 | ##### Calling API functions in SecureAPI Mode 98 | 99 | Calls to each API function proceed as per a call to `open_wallet`, however each encrypted request must contain the token provided by the `open_wallet` call. The token is XORed against the stored XORed seed to recover the original seed by the backend for the duration of each call, and the seed value is dropped and zeroed from memory when each call returns. 100 | 101 | ![api_call](../assets/0004/0004-api-call.svg) 102 | 103 | #### Directly Linked Wallets 104 | 105 | Wallets that link the wallet API directly will not be required to encrypt parameters, as there would be little benefit to doing so within a single process. However, for consistency, they will be expected to store and supply a token to each API call. The modified workflow for a linked wallet is outlined below: 106 | 107 | ![open-wallet-direct](../assets/0004/0004-open-wallet-direct.svg) 108 | ![api-call-direct](../assets/0004/0004-api-call-direct.svg) 109 | 110 | 'Legacy' support will not be provided for directly-linked wallets on release of the features described in this RFC. It is expected that wallet authors will need to update their code to store and supply the token with each request. 111 | 112 | ### New Lifecycle API Functions 113 | 114 | The functions as shown here are for illustrative purposes, and their signatures will change during implementation. 115 | 116 | * `OwnerAPI::init_secure_api(pubkey: Secp256k1Point) -> Result` 117 | - Initializes secure API mode, returning the server-side public key to be used for key agreement 118 | - All further calls to the JSON-RPC API must be encrypted with the shared secret 119 | * `OwnerAPI::set_wallet_directory(dir: String) -> Result<(), libwallet::Error>` 120 | - On API startup, it's assumed the top-level wallet data directory is `~/.grin/main/wallet_data` (or floonet equivalent) 121 | - Set the top-level system wallet directory from which named wallets are read. Further calls to lifecycle functions will use this wallet directory 122 | * `OwnerAPI::create_config(chain_type: &global::ChainTypes, config_overrides: Option) -> Result<(), libwallet::Error>` 123 | - Outputs a `grin-wallet.toml` file into current top-level system wallet directory 124 | - Optionally takes wallet configuration structure to override defaults in the grin-wallet.toml file 125 | * `OwnerAPI::create_wallet(name: Option, mnemonic: Option, mnemonic_length: usize, password: ZeroingString) -> Result<(), libwallet::Error>` 126 | - Creates and initializes a new wallet 127 | - Initializes seed from given mnemonic if given, random seed otherwise 128 | - Should error appropriately if the wallet already exists 129 | - The 'name' parameter is included for future use as in `open_wallet` above. 130 | * `OwnerAPI::open_wallet(name: Option, password: String) -> Result` 131 | - Opens a wallet and sets it as the 'active' wallet. All further API commands will be performed against this wallet. 132 | - 'Opens' the wallet seed in memory, stored XORed against a new token. The token is to be returned to the client for use in all further API calls. 133 | - The 'name' argument is included for future use, anticipating the inclusion of multiple wallets and seeds within a single top-level wallet directory. 134 | * `OwnerAPI::close_wallet(&mut self) -> Result<(), libwallet::Error>` 135 | - Closes the currently open wallet (i.e. drops the XORed seed from memory) 136 | * `OwnerAPI::get_mnemonic(t:Token) -> Result` 137 | - Returns the mnemonic from the active, (open) wallet 138 | * `OwnerAPI::change_password(old: ZeroingString, new: ZeroingString) -> Result<(), libwallet::Error>` 139 | - Changes the password for the open wallet. This will essentially: 140 | - Close the wallet instance 141 | - Confirm the existing seed can be opened with the given password 142 | - Regenerate the `wallet.seed` file with the new password 143 | - Re-open the wallet instance 144 | - (Should this just operate on closed wallets instead?) 145 | * `OwnerAPI::delete_wallet(name: Option, password: ZeroingString) -> Result<(), libwallet::Error>` 146 | - Dangerous function that removes all wallet data 147 | - name argument reserved for future use 148 | 149 | #### API only 150 | 151 | Note that this RFC does not propose making user-facing changes to the existing CLI wallet to invoke these functions. It's expected that the existing cli functionality will be modified to invoke the new API functions. 152 | 153 | ### Implementation notes 154 | 155 | Although this document doesn't attempt to outline implementation, a few notes to consider for the implementor: 156 | 157 | * Currently, the code that deals with wallet initialization and seed management sits outside the wallet APIs, in the `impls` crate, (denoting they're implementation specific). The implementation should attempt to refactor traits from these hard implementations into a new interface, similar to the existing WalletBackend and NodeClient interfaces (WalletLifecycleManager, for instance). The implementation within `impls` will then become an implementation of that trait and can be substituted by wallet authors with their own implementations. 158 | * The implementation period of this RFC may be a good time to remove the BIP32 specific code out from Grin core into the wallet or into a separate rust crate (probably more desirable). 159 | * New API functions should be implemented as additions, with the new features optional to ensure complete backwards compatibility 160 | 161 | ## Drawbacks 162 | [drawbacks]: #drawbacks 163 | 164 | * Security-critical information such as passwords and mnemonics are covered via the encryption in the above scheme, but sending slate information via the OwnerAPI has privacy concerns. 165 | 166 | ## Unresolved questions 167 | [unresolved-questions]: #unresolved-questions 168 | 169 | * Due to how this is likely to be implemented, the Foreign API will also have to provide a token for all wallet access. The Foreign API will need to store this token in-process, therefore negating much of the benefit of the scheme. Is there a cleverer way to deal with this? 170 | 171 | ## Future possibilities 172 | [future-possibilities]: #future-possibilities 173 | 174 | The changes in this RFC lead the way for: 175 | 176 | * Support for multiple wallets in a single top-level data directory 177 | * An alternate method of command-line invocation whereby the wallet presents its own prompt instead of using single-use commands. 178 | -------------------------------------------------------------------------------- /text/0005-variable-size-kernels.md: -------------------------------------------------------------------------------- 1 | 2 | - Title: variable-size-kernels 3 | - Authors: [Antioch Peverell](mailto:apeverell@protonmail.com) 4 | - Start date: Aug 13, 2019 5 | - RFC PR: [mimblewimble/grin-rfcs#21](https://github.com/mimblewimble/grin-rfcs/pull/21) 6 | - Tracking issue: [mimblewimble/grin#3038](https://github.com/mimblewimble/grin/issues/3038) 7 | 8 | --- 9 | 10 | ## Summary 11 | [summary]: #summary 12 | 13 | We minimize the size of binary serialized transaction kernels by including only the data applicable for each kernel variant. Height locked kernels include a fee and a lock height. Plain kernels include only a fee. Coinbase kernels include neither a fee nor a lock height. Each kernel feature variant will serialize to a fixed size in bytes but this size will differ across the kernel variants. 14 | 15 | ## Motivation 16 | [motivation]: #motivation 17 | 18 | We were originally including both fee and lock_height on _every_ kernel in the binary serialization format. We were storing a fee of 0 on coinbase kernels and a lock_height of 0 on both plain and coinbase kernels. Kernels are never pruned and must be maintained forever so this overhead is relatively expensive. By only serializing data strictly necessary for each kernel variant we minimize storage and transmission costs. This also provides the flexibility necessary to introduce new kernel variants in the future, for example the proposed [relative kernels][0]. 19 | 20 | ## Community-level explanation 21 | [community-level-explanation]: #community-level-explanation 22 | 23 | Each transaction kernel variant may have associated data. For example, height locked kernels include an associated lock height and non-coinbase kernels have an associated fee. Each kernel variant serializes to a fixed size in bytes but this size may be different for each kernel variants. This allows kernels to be serialized efficiently and provides flexibility to introduce new kernel variants that have additional associated data in the future. 24 | 25 | A plain kernel is 106 bytes compared to 114 bytes for a height locked kernel. Omitting the lock height from plain kernels saves approximately 7% in kernel storage costs. 26 | 27 | These changes affect serialization/deserialization of transaction kernels. Kernels are included in p2p messages for transactions and full blocks. Older nodes will serialize transaction kernels differently so nodes on the network need to be able to handle old and new serialization formats. The kernel MMR is also included in the txhashset state file during fast sync so nodes need to be able to support old and new formats of the state file. 28 | 29 | ## Reference-level explanation 30 | [reference-level-explanation]: #reference-level-explanation 31 | 32 | ### Protocol Version 1 (Previous Version) 33 | 34 | In protocol version 1 all transaction kernels are serialized using the same structure, regardless of kernel variant. All kernels include 8 bytes for the fee and 8 bytes for the lock_height, even if unused. 35 | 36 | ``` 37 | features (1 byte) | fee (8 bytes) | lock_height (8 bytes) | excess (33 bytes) | signature (64 bytes) 38 | 39 | 00 | 00 00 00 00 01 f7 8a 40 | 00 00 00 00 00 00 00 00 | 08 b1 ... 22 d8 | 33 11 ... b9 69 40 | ``` 41 | 42 | All kernels contain a feature byte to determine the variant. Kernels always include an excess commitment and signature, 33 bytes and 64 bytes respectively. The proposal is to have variant specific data follow the feature byte. 43 | 44 | The initial feature byte would determine the number of subsequent bytes to read for variant specific data. 45 | 46 | ``` 47 | 00 (plain): following 8 bytes for the fee. 48 | 01 (coinbase): no additional bytes. 49 | 02 (height locked): following 8 bytes for the fee and additional 8 bytes for the lock height. 50 | ``` 51 | 52 | This would always be followed by a fixed 33 bytes for the excess commitment and 64 bytes for the kernel signature. 53 | 54 | ### Protocol Version 2 (Current Version) 55 | 56 | Plain kernel, includes fee. 57 | 58 | ``` 59 | features (1 byte) | fee (8 bytes) | excess (33 bytes) | signature (64 bytes) 60 | 61 | 00 | 00 00 00 00 01 f7 8a 40 | 08 b1 ... 22 d8 | 33 11 ... b9 69 62 | ``` 63 | 64 | Coinbase kernel, no fee, no lock height. 65 | 66 | ``` 67 | features (1 byte) | excess (33 bytes) | signature (64 bytes) 68 | 69 | 01 | 08 b2 ... 15 36 | 08 14 ... 98 96 70 | ``` 71 | 72 | Height locked kernel, include fee and lock height. 73 | 74 | ``` 75 | features (1 byte) | fee (8 bytes) | lock_height (8 bytes) | excess (33 bytes) | signature (64 bytes) 76 | 77 | 02 | 00 00 00 00 00 6a cf c0 | 00 00 00 00 00 00 04 14 | 09 4d ... bb 9a | 09 c7 ... bd 54 78 | ``` 79 | 80 | ### Backward Compatibility (Protocol Version Support) 81 | 82 | #### Network p2p messages 83 | 84 | The following p2p messages include serialized transaction kernels - 85 | 86 | * transaction 87 | * full block 88 | * compact block (incl. coinbase kernel) 89 | 90 | Each node has a "local" protocol version. Nodes exchange protocol versions during the initial handshake when setting up a connection. 91 | 92 | If both nodes are running protocol version 2 then no translation is required and transaction kernels can be serialized using protocol version 2. 93 | 94 | If both nodes are running protocol version 1 then again no translation is required. 95 | 96 | The complexity arises when one node is running protocol version 2 and the other node is running protocol version 1. 97 | 98 | * Node A: protocol version 2 99 | * Node B: protocol version 1 100 | 101 | If node A and node B are communicating they must both send and receive using a protocol version compatible with both nodes. In this case protocol version 1. 102 | 103 | __Receiving messages using previous protocol version__ 104 | 105 | Node B will broadcast transactions and blocks using protocol version 1. Node A will need to use the previous protocol version and not the local version when deserializing these messages. 106 | 107 | __Sending messages using previous protocol version__ 108 | 109 | Node A will need to ensure anything broadcast to Node B is compatible with protocol version 1. In both cases node A is responsible for translating to and from the previous protocol version. 110 | 111 | #### Local db storage 112 | 113 | Each node has a "db" protocol version. All entries in the db serialize/deserialize using that protocol version. Nodes support a process for local migration of data. On startup, the db is inspected and if necessary a migration is performed upgrading all entries in the db to the latest protocol version. This process can be disabled locally to allow nodes to run against old databases without upgrading the protocol version. This is useful in cases where nodes do not wish to immediately upgrade the db, allowing for previous versions of code to run without problems. 114 | 115 | #### Kernel MMR storage 116 | 117 | Each node maintains a kernel MMR as part of the txhashset data structure. Each node has an MMR protocol version. The node will serialize/deserialize kernel entries in the kernel MMR data file according to the MMR protocol version. 118 | 119 | ##### Fast sync (txhashset.zip state file) 120 | 121 | Internally nodes are free to use any protocol version but the kernel MMR is also provided to other nodes during initial fast sync. A node joining the network requests a txhashset state file and this includes the kernel MMR. It is important that nodes send and receive the txhashset file using a compatible protocol version. This is a special case of "p2p messages" above with the txhashset state file provided as an attachment to the txhashset message. 122 | 123 | If node A (protocol version 2) requests a txhashset from node B (protocol version 1) then it must read the file using protocol version 1. Similarly, if node B requests txhashset from node A then node A must provide the file such that it is compatible with protocol version 1. 124 | 125 | The simplest way to achieve this is for all nodes to continue to use protocol version 1 internally for MMR storage, even if they use protocol version 2 externally for p2p messages. A transition period will be in place until a majority of nodes support protocol version 2 at which time nodes can migrate their MMR storage to protocol version 2. 126 | 127 | ### Wallet Compatibility 128 | 129 | Interactive transaction building involves a transaction "slate" passed between parties. This includes a json serialized representation of the transaction. 130 | 131 | To minimize compatibility issues between wallets we have maintained this existing json format. Transaction kernels are represented in a single consistent json format, with fee and lock_height both included, regardless of kernel variant. Plain kernels have an associated lock_height of 0 and coinbase kernels include a 0 fee. This is consistent with the current "v2" slate. 132 | 133 | ``` 134 | "kernels": [ 135 | { 136 | "features": "Plain", 137 | "fee": "7000000", 138 | "lock_height": "0", 139 | "excess": "08b1...22d8", 140 | "excess_sig": "3311...b969" 141 | }, 142 | ... 143 | ] 144 | ``` 145 | 146 | ## Future possibilities 147 | [future-possibilities]: #future-possibilities 148 | 149 | Support for variable size kernels allows new kernel variants to be introduced in the future. One proposed kernel variant is [No Recent Duplicate (NRD) kernels][0]. Kernels with relative lock heights will have an associated reference to a prior kernel in addition to a lock height based on that prior kernel. 150 | 151 | ## References 152 | [references]: #references 153 | 154 | * [PR #2734 Support for variable size MMRs](https://github.com/mimblewimble/grin/pull/2734) 155 | * [PR #2824 Protocol version support](https://github.com/mimblewimble/grin/pull/2824) 156 | * [PR #2859 Kernel feature variants](https://github.com/mimblewimble/grin/pull/2859) 157 | -------------------------------------------------------------------------------- /text/0006-payment-proofs.md: -------------------------------------------------------------------------------- 1 | 2 | - Title: payment-proofs 3 | - Authors: [David Burkett](mailto:davidburkett38@gmail.com) 4 | - Start date: Nov 05, 2019 5 | - RFC PR: [mimblewimble/grin-rfcs#31](https://github.com/mimblewimble/grin-rfcs/pull/31) 6 | - Tracking issue: [mimblewimble/grin-wallet#230](https://github.com/mimblewimble/grin-wallet/issues/230) 7 | 8 | ## Summary 9 | [summary]: #summary 10 | 11 | Support generating and validating payment proofs for sender-initiated (i.e. non-invoice) transactions. 12 | 13 | ## Motivation 14 | [motivation]: #motivation 15 | 16 | Bitcoin and other cryptocurrencies with transparent protocol-level addressing and immutable, unprunable blockchains can prove sender, receiver, and amounts of payments simply by pointing to the transaction in the blockchain. 17 | Grin's privacy and scalability means users no longer have this ability. This prevents some merchants from accepting Grin due to the high possibility of payment disputes that are unresolvable in the same way they are for transparent coins. 18 | 19 | This RFC changes the transaction building process where payers can require payees to create a "proof" they've received a payment before the payer finalizes and broadcasts the transaction. 20 | 21 | ## Community-level explanation 22 | [community-level-explanation]: #community-level-explanation 23 | 24 | From an end-user perspective, payers can require payees to prove receipt of funds as part of the transacting process. 25 | Payers can then use these "proofs" to resolve payment disputes and prove they sent funds to the correct payee. 26 | 27 | ## Reference-level explanation 28 | [reference-level-explanation]: #reference-level-explanation 29 | 30 | ### Slate changes 31 | 32 | A new (optional) structure (`payment_info`) will be added to transaction slates, along with a version increase. The `payment_info` structure will contain: 33 | 34 | * `sender_address` - An ed25519 public key generated by the sender. 35 | * `receiver_address` - An ed25519 public key for the receiver, typically the public key of the user's v3 onion address. 36 | * `receiver_signature` - A signature of the sender_address, received amount, and kernel commitment that validates against the `receiver_address`. 37 | 38 | ### Generating proofs 39 | 40 | Receipt confirmations (`receiver_signature`) will be generated by the payee by providing an ED25519 signature of: `(amount || kernel_commitment || sender_address)`, using the private key of the `receiver_address`. 41 | 42 | The `sender_signature` can be generated for `(amount || kernel_commitment || sender_address)` using the private key of the `sender_address`. 43 | 44 | Sender will then create and store the following info, which can be considered the complete `payment_proof`: 45 | 46 | * `receiver_address` 47 | * `receiver_signature` 48 | * `amount` 49 | * `kernel_commitment` 50 | * `sender_address` 51 | * `sender_signature` 52 | 53 | ### Verifying Proofs 54 | 55 | This `payment_proof` can be provided by the sender at any time to convince a payee that a payment was made to them. The proof can be verified as follows: 56 | 57 | 1. Ensure the `kernel_commitment` is confirmed on-chain. 58 | 2. Verify that the `receiver_address` belongs to the payee. 59 | 3. Verify that the `receiver_signature` is valid. 60 | 4. Verify that the `sender_signature` is valid. 61 | 62 | ### Wallet actions 63 | 64 | #### init-send 65 | 66 | As part of the first step of the tx-building process, the sender/payer generates the `sender_address` using their keychain. 67 | 68 | The `receiver_address` and keychain path of the `sender_address` must be stored locally, along with the `slate_id`. 69 | 70 | The `sender_address` and `receiver_address` will then be added to the `payment_proof` structure of the slate. 71 | 72 | #### receive 73 | 74 | If the `payment_proof` structure exists on the slate, it is mandatory that the `receiver_signature` is generated and added to the slate as part of the receive tx-building step. 75 | 76 | #### finalize 77 | 78 | Using the `slate_id`, the sender can retrieve the original `sender_address` and `receiver_address` that were included in the slate, and verify that those fields remain unchanged. The sender must then validate the `receiver_signature`. If any of the original `payment_proof` slate fields were modified, or if the `receiver_signature` is invalid, the transaction must be rejected by the sender. 79 | 80 | Once the `payment_info` details have been validated, the sender can generate and store the `payment_proof` (See `Generating Proofs` above), and then finalize the transaction as normal. 81 | 82 | ## Drawbacks 83 | 84 | * Increases the size of tx slates. 85 | * Possibility of privacy leakage through address reuse. 86 | 87 | ## Rationale and alternatives 88 | 89 | * This design works well with TOR tx building, yet is generic enough to work with all known transacting mechanisms. 90 | 91 | ## Prior art 92 | 93 | * Wallet713 implements payment proofs for grinbox transactions, which our design adapts and builds on to work more seemlessly with onion addresses and with transaction building methods that don't inherently rely on addresses. 94 | 95 | ## Unresolved questions 96 | 97 | * Can this be adapted to work for invoices? 98 | 99 | ## Future possibilities 100 | 101 | * Payment proofs could potentially be added to invoice payments in the future, but at the cost of an additional round of communication. 102 | 103 | ## References 104 | 105 | - [Tx slate structure](https://github.com/mimblewimble/grin-wallet/blob/master/libwallet/src/slate.rs) 106 | - [Beam's payment proof model](https://github.com/BeamMW/beam/blob/c9beb0eae55fa6b7fb3084ebe9b5db2850cf83b9/wallet/wallet_db.cpp#L3231-L3236) 107 | -------------------------------------------------------------------------------- /text/0009-enable-faster-sync.md: -------------------------------------------------------------------------------- 1 | 2 | - Title: enable-faster-sync 3 | - Authors: [Antioch Peverell](mailto:apeverell@protonmail.com), [John Tromp](mailto:john.tromp@gmail.com) 4 | - Start date: Oct 25, 2019 5 | - RFC PR: [mimblewimble/grin-rfcs#29](https://github.com/mimblewimble/grin-rfcs/pull/29) 6 | - Tracking issue: [mimblewimble/grin#3173](https://github.com/mimblewimble/grin/issues/3173) 7 | 8 | --- 9 | 10 | ## Summary 11 | [summary]: #summary 12 | 13 | This RFC introduces changes that reduce the time it takes for a node joining the Grin network to fully sync. Data can be downloaded in batches and partially verified without the bottleneck of waiting to receive all data. These batches can be requested from multiple peers in parallel and verified as they are received. This improves the performance and the robustness of the "fast sync" process and allows for futher improvements to be explored in the future. A consensus change is required to facilitate this, with a change to what we commit to in each block header. We propose making this consensus change as part of the upcoming scheduled hardfork (HF2 scheduled for Jan 2020). 14 | 15 | ## Motivation 16 | [motivation]: #motivation 17 | 18 | The initial sync process involves downloading all kernels, all unspent outputs and their corresponding rangeproofs. The unspent outputs are maintained in a "Prunable Merkle Mountain Range" (PMMR). Briefly, this consists of unpruned output data, a set of intermediate hashes representing pruned subtrees and a "leafset" bitmap representing the position of unpruned, unspent outputs in the PMMR. 19 | 20 | The previous implementation packaged all of the above data into a single zip file, requested and received from a single peer. This was both a performance bottleneck and a single point of failure. To increase reliability and performance we split this data up into smaller chunks and request from multiple peers. 21 | 22 | It was previously only possible to validate the _full_ set of unspent outputs. We were unable to validate a partial set of outputs as we compared the total output sum to the total kernel sum plus the total kernel offset. By design, there is no partial kernel sum to compare against a partial output sum. 23 | 24 | This RFC describes how we split the output PMMR into subtrees, requesting these subtrees along with the corresponding bitmap fragment and the necessary Merkle proofs. Each output subtree can be verified with its corresponding bitmap fragment. By committing to the leafset bitmap in addition to the output PMMR we can verify the output subtrees. 25 | 26 | The final "sum to zero" validation remains unchanged but the partial verification of the individual output subtrees allows for more granular, and earlier verification of the data as it is received. 27 | 28 | ## Community-level explanation 29 | [community-level-explanation]: #community-level-explanation 30 | 31 | Validation of full transaction history is not necessary when joining the Grin network and access to full block history is not required. The initial sync process involves downloading all block headers, all kernels, all unspent outputs and their corresponding rangeproofs. Historical spent outputs are not necessary for validation. Nodes prune historical spent outputs, with a few days of recent history retained. Kernels are not pruned and must be retained indefinitely. 32 | 33 | The unspent outputs are maintained in a "Prunable Merkle Mountain Range" (PMMR). Briefly, this consists of unpruned output data, a set of intermediate hashes representing pruned subtrees and a "leafset" bitmap representing the position of unpruned, unspent outputs in the PMMR. Subtrees of the output PMMR are requested from peers and these subtrees are verified together with the corresponding fragment of the leafset bitmap. Merkle proofs are provided to prove inclusion of both the output subtree and bitmap fragments beneath the root committed to in the block header. Once all subtrees are received and verified, the unspent outputs are summed together and checked against the sum of all kernels plus the kernel offset from the block header. 34 | 35 | This allows us to download outputs from multiple peers, in parallel and verify them as they are received. 36 | The node does not need to wait for the full output PMMR to be received before validation can begin. 37 | 38 | ## Reference-level explanation 39 | [reference-level-explanation]: #reference-level-explanation 40 | 41 | The leafset bitmap is committed to by splitting the bitmap into smaller fragments, adding these fragments to an MMR and committing to the root of the bitmap MMR. 42 | 43 | The leafset bitmap represents leaf positions, in insertion order, of the underlying output PMMR. The output PMMR is append-only and the order of these outputs does not change. The first (leftmost) bit in the bitmap maps directly to the first output inserted into the output PMMR. The next bit in the bitmap maps to the second output inserted into the output PMMR etc. The bitmap `11100010` represents outputs `[0, 1, 2, 6]` in the PMMR. The bitmap is then split into smaller fragments of 1024 bits, representing contiguous sequences of bits of the bitmap. The two fragments `0000...0001, 1000...0000` represent outputs `[1023, 1024]` in the output PMMR. Every fragment is exactly 1024 bits in length with the final fragment padded with `0` values to fill the full 1024 bits. 44 | 45 | The bitmap MMR itself is not append-only as fragments of the bitmap will be updated over time as outputs are spent. Recent outputs are more likely to be spent than old output, resulting in updates clustering around the most recent (rightmost) fragments in the MMR. This has the nice property of minimizing the amount of updating and rehashing necessary to keep the bitmap MMR updated over time as older fragments will change only rarely. 46 | 47 | Merkle proofs can be provided for both a subtree of the output PMMR and a fragment in the bitmap MMR. These are used during validation to locate the output subtree in the overall output PMMR and to verify the bitmap fragment corresponds to the same output positions. 48 | 49 | To commit to the root of both the output PMMR and the root of the bitmap MMR we hash the roots together 50 | and commit to this single composite root `H(output_root|bitmap_root)` in the the block header. 51 | This allows us to reuse the existing `output_root` field on the header to commit to both MMR roots. 52 | 53 | 54 | ## Drawbacks 55 | [drawbacks]: #drawbacks 56 | 57 | These changes necessitate a change to the data committed to in the block header. This is a consensus breaking change and comes with all risks and complexity inherent to any consensus breaking change. As block headers are retained indefinitely the implementation will need to maintain compatibility for headers pre and post hardfork indefinitely. 58 | 59 | ## Rationale and alternatives 60 | [rationale-and-alternatives]: #rationale-and-alternatives 61 | 62 | We believe we cannot make the desired changes to fast sync without committing to the leafset bitmap. 63 | The previous approach of implicitly validating this as part of the overall "sum to zero" kernel validation does not allow for a batched approach. The previous approach was by design "all or nothing" with validation only possible once we have downloaded the full set of kernels and unspent outputs. 64 | 65 | The details are around precisely how to commit to this bitmap and there are various alternatives possible here. 66 | The leafset bitmap is implemented as a "roaring bitmap" internally but we want to commit to a canonical representation of this data. The obvious choice here is the uncompressed bitmap data itself. We could simply hash the full bitmap but this is not efficient as we would need to rehash all the data for every block header. The other extreme would be to treat each individual bit in the bitmap as a leaf of a Merkle tree. This would also be inefficent as we would require a 32 byte hash for every individual bit. The proposed solution is to break the bitmap up into smaller chunks and add these chunks as leaves of an MMR. Recent outputs are more likely to be spent than older outputs and bitmap chunks to the right of the MMR 67 | are more likely to change over time. These rightmost chunks have shorter paths to the associated peak in the MMR with correspondingly shorter Merkle proofs. The cost of updating more recent fragments is also minimized as the number of rehashing operations up to the peak is small. 68 | 69 | The proposal is to break the bitmap up into 1024 bit (128 byte) chunks and use these as leaves in the bitmap MMR. 70 | 71 | The other question is what data to add to the header itself. We propose combining the bitmap root and the output MMR root into a single `output_root` hash on the block header. This changes the semantics of the existing `output_root` field. This solutiuon has the advantage of maintaining the existing header serialization. No new header field would be necessary. 72 | An alternative solution would be to keep the two MMR roots separate and to introduce the new bitmap root as a new header field. The would affect serialization at both the p2p layer and the local database and would add significant complexity to the implementation. 73 | 74 | The two roots are closely related and we propose committing to them together as a single combined hash. 75 | 76 | ## References 77 | [references]: #references 78 | 79 | * [Merkle Mountain Range (OpenTimestamps)](https://github.com/opentimestamps/opentimestamps-server/blob/532033b465c3b09c9db2a9064de03230c7e2e28e/doc/merkle-mountain-range.md) 80 | * [Prunable Merkle Mountain Ranges (Grin)](https://github.com/mimblewimble/grin/blob/67057ab36d606072c543b2741e33496c6affd6ab/doc/mmr.md) 81 | -------------------------------------------------------------------------------- /text/0010-online-transacting-via-tor.md: -------------------------------------------------------------------------------- 1 | 2 | - Title: online-transacting-via-tor 3 | - Authors: [David Burkett](mailto:davidburkett38@gmail.com) 4 | - Start date: September 1, 2019 5 | - RFC PR: [mimblewimble/grin-rfcs#24](https://github.com/mimblewimble/grin-rfcs/pull/24) 6 | - Tracking issue: [mimblewimble/grin-wallet#280](https://github.com/mimblewimble/grin-wallet/issues/280) 7 | 8 | --- 9 | 10 | ## RETIRED 11 | This RFC has been retired and has been superseded by [RFC#0015: slatepack](0015-slatepack.md). 12 | 13 | --- 14 | 15 | ## Summary 16 | [summary]: #summary 17 | 18 | Describes a standardized addressing and communication protocol for building Grin transactions. 19 | 20 | Wallets will attempt to connect to the recipient directly to build transactions over a TOR hidden service similar to how http(s) transaction building works today. 21 | 22 | This RFC does not cover the offline transacting problem. 23 | 24 | ## Motivation 25 | [motivation]: #motivation 26 | 27 | Grin is unique in that it requires the sender and receiver to interact in order to transact. This presents a lot of unique challenges that most coins don’t have to deal with. There are a number of different incompatible standards for sending and receiving, resulting in confusion and headaches for many users. The hope is that the addressing mechanism described here will become the new default method for sending and receiving, deprecating several less secure and less private methods in the process. 28 | 29 | ## Community-level explanation 30 | [community-level-explanation]: #community-level-explanation 31 | 32 | From an end-user perspective, there should no longer be a need to configure routers and firewalls to receive grins. Sending and receiving should feel like any other cryptocurrency, where a simple encoded address is all you need to share before receiving. No firewall or router configuration should be necessary. 33 | 34 | ## Reference-level explanation 35 | [reference-level-explanation]: #reference-level-explanation 36 | 37 | ### Addressing 38 | 39 | Onion addresses for TOR hidden services are generated from an ed25519 public key (32 bytes), and include a checksum and a version[1]. This provides an equivalent level of security as bitcoin addresses, and can be ephemeral or permanent, depending on the user’s needs. Grin addresses should be generated and base32 encoded in the same way as TOR v3 addresses. 40 | 41 | Although ed25519 is a different curve than used by the grin protocol, we can still use our HD wallets to generate deterministic ed25519 public keys (and therefore Grin addresses). For account `m/0`, addresses will be generated using keychain paths `m/0/1/x`, for account `m/1`, addresses will be generated using `m/1/1/x`, etc. To generate addresses for a keychain path, we derive the private key in the usual way, but then blake2b hash the derived key to get the ed25519 secret key, which can then be used to calculate the public key and address. 42 | 43 | ### TOR Hidden Services 44 | 45 | TOR hidden services can be used to directly serve the existing foreign APIs. When configuring TOR (whether bundled with grin, or installed separately), you would just publish a hidden service and configure TOR to forward all traffic to port 3420. This means we can continue supporting http(s) sending/receiving with no disruption, though it’s advisable to avoid sending directly over http(s) asap.In future versions of Grin, we can stop allowing non-local connections to the foreign wallet APIs. 46 | 47 | ## Drawbacks 48 | [drawbacks]: #drawbacks 49 | 50 | Requires users to setup TOR, or bundle it with Grin, which could be non-trivial, and could conflict with locally installed/running versions. 51 | 52 | ## Unresolved questions 53 | [unresolved-questions]: #unresolved-questions 54 | 55 | * How often should addresses change? Should users manually request a new address, or should they auto expire? Should we support multiple? 56 | 57 | ## Future possibilities 58 | [future-possibilities]: #future-possibilities 59 | 60 | The changes in this RFC lead the way for: 61 | * Payment proofs 62 | * Offline transacting via SBBS/Grinbox-style relay system. See 0000-asynchronous-transacting-via-relays RFC 63 | 64 | ## References 65 | [references]: #references 66 | 67 | - [1] [https://github.com/torproject/torspec/blob/87698dc1c0fa4cf2186f180a636fc7ad1c5fb5fd/rend-spec-v3.txt#L2059-L2081](https://github.com/torproject/torspec/blob/87698dc1c0fa4cf2186f180a636fc7ad1c5fb5fd/rend-spec-v3.txt#L2059-L2081) 68 | - [2] [https://github.com/mimblewimble/grin/blob/d918c5fe84e859290c9d09f5cfc167ed41d27bff/keychain/src/extkey_bip32.rs#L122](https://github.com/mimblewimble/grin/blob/d918c5fe84e859290c9d09f5cfc167ed41d27bff/keychain/src/extkey_bip32.rs#L122) 69 | -------------------------------------------------------------------------------- /text/0011-security-team.md: -------------------------------------------------------------------------------- 1 | 2 | - Title: security-team 3 | - Authors: [joltz](mailto:joltz@protonmail.com) 4 | - Start date: Jan 22, 2020 5 | - RFC PR: [mimblewimble/grin-rfcs#39](https://github.com/mimblewimble/grin-rfcs/pull/39) 6 | - Tracking issue: [mimblewimble/grin-pm/#258](https://github.com/mimblewimble/grin-pm/issues/258) 7 | 8 | --- 9 | 10 | ## Summary 11 | [summary]: #summary 12 | 13 | The security team for Grin carries out the security priorities of the Grin community and core team, which are to be defined prior to formation of the team. The security team streamlines the security decision making process for the core team while maintaining a careful balance of security and transparency for the community. 14 | 15 | ## Motivation 16 | [motivation]: #motivation 17 | 18 | * Improve transparency, efficiency, decisiveness and scalability around security-related decision making 19 | * Dedicated support for security-related initiatives such as bilateral disclosure agreements, bug bounty programs and audit work 20 | * Increase confidence in the ecosystem for future contributions 21 | 22 | A clear and structured decision making process is needed to fully support the current security process as well as community initiatives such as bilateral disclosure agreements, bug bounty programs and future audit work. This process was previously maintained by the core team who had many areas of focus, leading to a lack of clarity, timeliness and ability to decisively execute on community security initiatives. 23 | 24 | The security team frees up core resources to focus on other important areas while expanding dedicated resources to security work, allowing the Grin ecosystem to continue to scale. A clear decision making structure around the security process instills confidence in the greater ecosystem and encourages projects, developers and users to continue to increase contributions of time and resources into Grin. 25 | 26 | ## Community-level explanation 27 | [community-level-explanation]: #community-level-explanation 28 | 29 | Grin's security team is responsible for making predefined security related decisions for the Grin project. This includes, but is not limited to, decisions about the specification and implementation of Grin's security processes. As much as possible Grin's security team carries out the security priorities of the community and core team in a transparent manner. 30 | 31 | There may be some unique security-related cases that require the security team to make some decisions in private to protect the security of Grin users. In these cases, once it is safe to do so, the security team is responsible for sharing as many details as possible with the community for transparency and accountability purposes. 32 | 33 | The primary day-to-day impact this will have on the community is making available structured support around security-related initiatives such as bilateral disclosure agreements, bug bounty programs and audit work. The community and other teams will have regular opportunity to interact with, provide input to and receive input from the security team. 34 | 35 | ### Example 36 | 37 | Here we will walk through an example case that highlights how Grin's security team would operate, contrasting with the current process. 38 | 39 | _In the example case, a vulnerability is disclosed to the disclosure contacts listed in Grin's security policy. It is shown that the community gains greater transparency into the decision making process and related outcomes with the proposed security team. Additionally the disclosure map is more tightly contained in the proposed process, resulting in less risk of vulnerability exploitation to the community._ 40 | 41 | #### Previous Process 42 | 43 | * Grin's security contacts make initial assessment of the validity of the vulnerability disclosure 44 | * If disclosure determined to be valid, all details of the disclosure are shared with the entire core team 45 | * With a conversation between the entire core team, a plan of action is determined and executed, following Grin's responsible disclosure policy 46 | * Once the vulnerability is mitigated the core team may optionally share some of the details with the community 47 | 48 | #### Security Team Process 49 | 50 | * Grin's security contacts, all members of the security team, make initial assessment of the validity of the vulnerability disclosure 51 | * If disclosure determined to be valid, a conversation and plan of action is determined and executed by the security team, following Grin's responsible disclosure policy 52 | * Once the vulnerability is mitigated the security team must disclose all information that is not still security-critical with the community 53 | 54 | ## Reference-level explanation 55 | [reference-level-explanation]: #reference-level-explanation 56 | 57 | Grin's security team will be implemented as stated below. 58 | 59 | ### Membership 60 | 61 | * Bootstrapped by existing security contacts (@lehnberg, @hashmap, @joltz) 62 | * Minimum three, maximum five members 63 | * Membership is recommended by the security team and approved by the core team 64 | * All members must have relevant domain expertise in security, cryptography, the Grin codebase or Grin community 65 | * All members must have high competency in maintaining personal operational security (keeping private keys secure, maintaining secure communications channels etc.) 66 | * Membership is revoked by failure to update the canary, unanimous decision by team or decision from the core team 67 | * Note if the core team engages in removing members from the security team without reasonable justification, the security team loses purpose, becomes ineffective and is relegated to useless security theater 68 | 69 | ### Decision Making 70 | 71 | * Distinction between _security-team decisions_ and _security-related decisions_: 72 | * The security team is responsible for making predefined security-team decisions, not all possible ambiguous security-related decisions 73 | * Decisions are made primarily with consideration to the security priorities outlined prior to the team's formation 74 | * Unanimous approval of security team members is needed to make all impactful decisions 75 | * Some decisions made must also be approved by the core team to be carried out: 76 | * Adding/removing parties from disclosure agreements 77 | * Adding members to the security team 78 | * Updating the security policy 79 | * In the event that the core team does not follow a security team recommendation, a reasonable explanation must be provided as to why the security recommendation was not followed 80 | * Some decisions must be made without fully informing the core team of all details: 81 | * When fixing a vulnerability requires a [deviation from the standard](https://github.com/mimblewimble/grin/blob/master/SECURITY.md#deviations-from-the-standard) 82 | * In these cases not all information will be shared with core team, such as specific details to carry out an exploit, full impact and other relevant information that will create unnecessary risk if disclosed 83 | * The core team must be notified of all cases of these decisions within a reasonable time frame that does not pose a security risk (e.g. after a fix is implemented) and provided with a reasonable explanation by the security team 84 | 85 | #### Vetoes 86 | 87 | * Any member of the security team may veto an impactful security team decision 88 | 89 | The ability to veto an impactful security team decision is important to preserve the ability for members of the security team to make honest recommendations. Important and controversial decisions will be made and members of the security team need the ability to not sign their names to a decision they are not comfortable with that could have serious ramifications. These cases will be handled according to the Deadlocks section below. 90 | 91 | The security team should always strive to reach its own decisions. Constant vetoes and inability to reach unanimous decisions will dampen the advantages of the existence of the team and may render it obsolete. It is important to strike the right balance of different perspectives, expertise and reasonability in members to take advantage of the benefits that come with a diverse and functional security-related decision making process. 92 | 93 | #### Deadlocks 94 | 95 | * Impactful security team decisions that can't be made unanimously by the security team will be made by the core team according to their decision making process 96 | * If the core team is deadlocked, the decision made will be whichever decision, if any, will provide the end user with the greatest measure of security 97 | 98 | Deadlocks should be avoided at all costs. The inability of the security team to reach a unanimous decision based on the security priorities of Grin's community and core team should be a red flag to the community and core team for the health of the team. All members should be able to clearly discuss the factual merits of the options and reach a decision that is in the clear best possible interest for the security of Grin's ecosystem and users. 99 | 100 | ### Example 101 | 102 | _By following the previous example in more detail, critical differences can be further explored between the current process and the proposed security team process in the handling of a unique case._ 103 | 104 | _In cases where fixing a vulnerability is so critical that it requires a [deviation from the standard](https://github.com/mimblewimble/grin/blob/master/SECURITY.md#deviations-from-the-standard), the proposed process reduces the likelihood of the vulnerability being exploited with a focused decision making process and by restricting the details to essential persons only._ 105 | 106 | #### Previous Process 107 | 108 | * Grin's security contacts make initial assessment of the validity of the vulnerability disclosure 109 | * It is determined that the disclosed vulnerability is a critical inflation bug 110 | * _All details of the disclosure, including the steps to carry out the exploit, are shared with the entire core team_ 111 | * With a conversation between the entire core team, a plan of action is determined and executed, following Grin's responsible disclosure policy 112 | * _This conversation may take days or weeks as there is no particular decision making process for security-related issues_ 113 | * _Once the vulnerability is mitigated the core team may optionally share some of the details with the community_ 114 | 115 | #### Security Team Process 116 | 117 | * Grin's security contacts, all members of the security team, make initial assessment of the validity of the vulnerability disclosure 118 | * It is determined that the disclosed vulnerability is a critical inflation bug 119 | * _A conversation and plan of action is quickly and unanimously determined and executed on by the security team, following Grin's responsible disclosure policy_ 120 | * _Once the vulnerability is mitigated, the security team must disclose all information that is not still security-critical with the community_ 121 | 122 | ## Drawbacks 123 | [drawbacks]: #drawbacks 124 | 125 | * The core team is already busy and the formation and management of a security team may distract from other pressing and immediate issues 126 | * Even though it decentralizes the core team, it potentially creates another point of centralization 127 | * Adds resource overhead to the project that _must_ be upheld (it is not acceptable to fail to follow through in security processes once established!) 128 | * Possibly distracts from other important work- we don't want to spread attention too wide too early 129 | * Adds bulk to Grin's governance structure 130 | * The community may trust core more than a team to make critical security decisions 131 | 132 | ## Rationale and alternatives 133 | [rationale-and-alternatives]: #rationale-and-alternatives 134 | 135 | * One alternative, currently in use, is adding the input of a security expert to the existing core decision making process 136 | * This is better than nothing but we lose a few benefits without a dedicated security team: 137 | * Strengthened security process: reduced likelihood of exploit leaks 138 | * Improved transparency: there is currently little transparency around core's security decision making process 139 | * Improved reaction times: informed, thoughtful, decisive actions with input from relevant experts only 140 | * Possibility for security initiatives: clear decision making process for bilateral disclosure agreements, bug bounty programs, audit work 141 | * Stronger commitments to the community, ecosystem and other projects: viable with a dedicated, clear decision making process 142 | * Long-term scalability: extend capacity for security work to grow beyond the core team's attention capacity 143 | * Another alternative is to rely on an open community to handle all incidents as they come in 144 | * This is less desirable than both the previous process and security team process: 145 | * Vulnerabilities would essentially be public before they can by mitigated 146 | * There is no decision making team so mitigation actions may be slow and contentious 147 | * There is no accountability to ensure that the responsible disclosure process is followed 148 | * This model is much more transparent than other alternatives but comes with the unacceptable associated costs above 149 | 150 | ## Prior art 151 | [prior-art]: #prior-art 152 | 153 | grin-governance[0] and security-process[1] RFCs lay groundwork for the security-team RFC. 154 | 155 | ## Unresolved questions 156 | [unresolved-questions]: #unresolved-questions 157 | 158 | - What are the security priorities of the Grin community and core team? (e.g. is privacy a higher priority than undetectable inflation?) 159 | - Is this the most minimal model that can have long-term success for Grin's security-related decision making process? 160 | - Is the single-veto model sufficient for a consistent, timely decision making process? 161 | 162 | ## Future possibilities 163 | [future-possibilities]: #future-possibilities 164 | 165 | * Budget allocation and management 166 | * Manage an allocated budget for possible initiatives 167 | * Bug bounty programs 168 | * Audits 169 | * Full time contributors 170 | * Development of security tooling 171 | 172 | * Security team working groups 173 | * Red team 174 | * Blue team 175 | * Audit team 176 | * Bug bounty team 177 | * Community outreach team 178 | 179 | * Expanding security-team decisions 180 | * Currently security-team decisions are restricted to predefined decisions around the security processes 181 | * In the future security-team decisions can be expanded to include more security-related decisions 182 | 183 | ## References 184 | [references]: #references 185 | 186 | - [0] [0002 grin-governance RFC (#teams)](https://github.com/mimblewimble/grin-rfcs/blob/master/text/0002-grin-governance.md#teams) 187 | - [1] [0003 security-process RFC](https://github.com/mimblewimble/grin-rfcs/blob/master/text/0003-security-process.md) 188 | -------------------------------------------------------------------------------- /text/0014-general-fund-guidelines.md: -------------------------------------------------------------------------------- 1 | 2 | - Title: general-fund-guidelines 3 | - Authors: [Michael Cordner](mailto:yeastplume@protonmail.org) 4 | - Start date: Feb 07, 2020 5 | - RFC PR: Edit if merged: [mimblewimble/grin-rfcs#41](https://github.com/mimblewimble/grin-rfcs/pull/41) 6 | - Tracking issue: `N/A` 7 | 8 | --- 9 | 10 | ## Summary 11 | [summary]: #summary 12 | 13 | This RFC establishes a set of guidelines for spending the Grin Development Fund, the procedure via which funding requests can be made, and a set of procedures for managing and reporting on the fund. 14 | 15 | ## Motivation 16 | [motivation]: #motivation 17 | 18 | Previously there were no clear guidelines on how the Grin Development Fund could be spent and what types of activities could and could not be financed from the fund. This RFC presents a set of non-exhaustive guidelines intended to ensure that: 19 | 20 | * Donators have a clear understanding of how their donations are likely to be spent. 21 | * Those with funding ideas have a clear reference point to understand what types of proposals are likely to be considered for funding. 22 | * Those with funding ideas have a specific process through which they can apply for funding. 23 | * The team making spending decisions has clear, community-established guidelines against which to consider new funding requests. 24 | * The decision-making process through which funding requests are granted is as fair, consistent and transparent as it can reasonably be. 25 | * The wider community understands how the fund is managed and that transparency is evident. 26 | 27 | Note that this document does not establish hard-and-fast rules for how the fund's contents can be spent. It is meant to be an indicative focal point for the community, and is intended to evolve with the needs of the project. 28 | 29 | ## Community-level explanation 30 | [community-level-explanation]: #community-level-explanation 31 | 32 | ### Appropriate and inappropriate uses of the Grin Development Fund 33 | 34 | Although spending decisions will always be made on a case-by-case basis, it is understood that the Grin Development Fund is to be used mainly to finance the development needs of the Grin project and the advancement of Grin/Mimblewimble as a whole. 35 | 36 | There is scope for interpretation as to what this actually means, but the following presents (non-exhaustive) guidelines as to the types of activities that would be considered appropriate to finance from the fund. 37 | 38 | * Activities related to the continuing development needs of the Grin code-base and related projects under the GitHub [mimblewimble](https://github.com/mimblewimble) organization. This can include: 39 | * Fixed-term development or project-management contracts 40 | * Infrastructure and other incidental costs 41 | * Security audit costs 42 | * Costs incurred for any legal matters that may arise for either the project or individual contributors arising directly from their work in good faith on the Grin project 43 | * Running budgets for Grin teams (with funds spent at their own discretion) 44 | * Technological research in areas that may be relevant to Grin in the future 45 | * Cryptographic research related to Grin or Mimblewimble in general 46 | * Fully open-sourced community-based projects that enhance the Grin ecosystem 47 | * Supporting non-profit, community-driven and inclusive promotional efforts for the Grin Project (e.g. Grincon) 48 | * Charitable donations toward important causes relevant to the Grin or cryptocurrency communities as a whole 49 | 50 | While the guidelines above give plenty of flexibility in how funds can be employed toward the advancement of the Grin project, certain types of funding requests will not be considered: 51 | 52 | * Marketing or promotional 'offers' where a party is taking a profit or gains some financial benefit to promote Grin (regardless of how the 'opportunity' is presented) 53 | * Cryptocurrency speculation or any kind of investment 54 | 55 | ### Request for Funding Process 56 | 57 | All requests for funding should be made in the [Governance Section](https://forum.grin.mw/c/governance) of the Grin forum. Topics should be clearly titled "Request for Funding: " followed by a short description of the request. 58 | 59 | There is no set template for what the contents of the funding request should include, however a better reception can be attained by including: 60 | 61 | * The exact amount requested, what the funding covers and for what time period (if applicable) 62 | * A clear description of what will be provided to the Grin project in return, including: 63 | * Details of any work or research that will be performed during the period 64 | * The expected deliverable, if applicable (for a research project, for instance) 65 | * Background information on the person making the request 66 | 67 | Amounts should be stated using fiat currency equivalents with the exact Cryptocurrency amount determined by the rate at the time of transfer. To assist others with conceptualizing the amounts, fiat currencies used should be reasonably global, e.g. USD, EUR, CNY, GBP. 68 | 69 | All community discussion on the funding request should be made within the forum thread itself, and the final decision on the request will be made by members of the core team at a [public governance meeting](https://github.com/mimblewimble/grin-pm/issues?q=is%3Aissue+label%3Agovernance+label%3Ameetings+), to take place at least one week after the request is made. The community is encouraged to display their support (or lack thereof) of a funding request at these Governance meetings, however the decision rests with the core team. 70 | 71 | It should also be noted that decisions should never be considered final. Those making funding requests are encouraged to revise or refine proposals based on whatever feedback is given during the request process and submit them for consideration again. 72 | 73 | ### Decision Process 74 | 75 | While everyone and anyone is encouraged to create a funding request, those making requests should understand that not all funding decisions will be approved simply on the basis of them conforming to the guidelines above. Many other factors will be considered for each request, including (but not limited to): 76 | 77 | * How well known in the community is the person making the funding request? 78 | * Have too many similar requests been funded recently? 79 | * How tangible is the value proposition to Grin? 80 | * How much risk is involved relative to the size of the ask and the potential return. 81 | * Does a prioritization call need to be made due to a limited balance in the General Fund? 82 | 83 | Everyone is welcome to weigh in on the merits of a funding request in the forum thread and during the public governance meeting where the funding request is finalized. The core team will strive to ensure there's a community consensus for each request, however the final decision rests with the core team. Other Grin teams who have been allocated budgets can spend funds at their own discretion, but are strongly encouraged to consider the guidelines in this RFC during their decision making process. 84 | 85 | ### Tips on effective proposals 86 | 87 | * You proposal is likely to be better received if you're already known to the Grin community or the wider cryptocurrency community. Even more so if you've already contributed to Grin in some meaningful way. 88 | * It might be better to keep your initial funding request small and focused, particularly if your idea is something new and radical, or if you're unknown to the Grin community. 89 | * Be specific, professional and thorough with your proposal. 90 | * Be respectful and professional in your response to any feedback and criticism on the proposal thread 91 | 92 | ### Payout Process 93 | 94 | * At the time of payout, the approved funding amount is converted to the equivalent in cryptocurrency and paid out to an address provided by the funding requestor only. 95 | * The payout address should be provided to the core team by the requestor via a secure, verifiable channel (with cryptographic proof of identity if deemed necessary). 96 | * Any conversion rate between the currency of the funding request and the currency that is paid out from the general fund is determined by the prevailing exchange rate at the time of the funding transaction, without exception. 97 | * To minimize the effects of currency fluctuations on accounting transparency, all payments should be performed at pre-arranged "signing parties" in which mu-sig holders sample the current exchange rate. The transaction should be created, signed and broadcast as quickly as possible, with the transaction and rate reported back to the core team for tracking. 98 | * Mu-sig holders will verify the address provided by the funding requestor several times during transaction creation and broadcasting. However, the core team is not responsible for errors or incorrect addresses provided by the requestor. 99 | 100 | ### Reporting 101 | 102 | The result of all funding decisions will be published in the meeting notes found in the [Grin Project Management](https://github.com/mimblewimble/grin-pm) repository. 103 | 104 | The core team is obliged to publish a detailed spending log of all transactions made in and out of the fund, as well as quarterly transparency reports summarizing all income and spending. This and other financial reporting can be found in the [/grin-pm](https://github.com/mimblewimble/grin-pm) repository. 105 | 106 | ## Unresolved questions 107 | 108 | * This RFC is put together on the understanding that the fundamental question of 'who appoints the core team' is still outstanding. This point should be discussed separately and this RFC assumes there is an acceptable answer in place. 109 | 110 | ## Future possibilities 111 | 112 | Ideas to further improve the funding process include creating a community funding website, where proposals can be made and vetted by the community, and support for particular ideas can be shown. Contributions towards funding could be made by community individuals and be matched with contributions from the general fund. 113 | 114 | ## References 115 | 116 | * [https://grin.mw/fund](https://grin.mw/fund) 117 | * [https://github.com/mimblewimble/grin-pm/](https://github.com/mimblewimble/grin-pm/) 118 | -------------------------------------------------------------------------------- /text/0016-simplify-governance.md: -------------------------------------------------------------------------------- 1 | 2 | - Title: `simplify-governance` 3 | - Authors: [@paouky](mailto:ar.gis@protonmail.com), [@lehnberg](mailto:daniel.lehnberg@protonmail.com) 4 | - Start date: `Sep 11, 2020` 5 | - RFC PR: [mimblewimble/grin-rfcs#67](https://github.com/mimblewimble/grin-rfcs/pull/67) 6 | 7 | --- 8 | 9 | ## Summary 10 | [summary]: #summary 11 | 12 | This governance iteration replaces the previous process that was set out in [RFC#0002](https://github.com/mimblewimble/grin-rfcs/blob/master/text/0002-grin-governance.md) with a simplified and better-defined version. Specifically, it: 13 | 14 | - defines its remit to be around the repos, projects, and communities that are centered around the [/mimblewimble](https://github.com/mimblewimble) GitHub organization; 15 | - reverts the core team to the original technocratic council structure, whose sole responsibility is managing the general fund; and 16 | - explicitly enables individual contributors and teams to self-organize for other aspects of decision making. 17 | 18 | ## Motivation 19 | [motivation]: #motivation 20 | 21 | RFC#0002 was an iteration on governance in response to the sudden disappearance of Ignotus Peverell, the founder of Grin. Introduced together with the RFC process as defined in [RFC#0001](https://github.com/mimblewimble/grin-rfcs/blob/master/text/0001-rfc-process.md), it served its purpose to formalize a structure for how the project would organize and make decisions. Over time however, it became clear that while the structure had its benefits, it came with its own drawbacks. 22 | 23 | ### Flaws of the previous structure 24 | 25 | 1. **All critical decision making became centralized around the core team.** 26 | - Consensus changes 27 | - Releases 28 | - Spending decisions 29 | - RFC approvals 30 | - Project leadership 31 | 1. **It established a negative feedback loop for contributors:** 32 | 1. It created an “us” and “them” in the community; Those on the inside (part of the core team), and those on the outside (not part of the core team). 33 | 2. This in turn led to the assumption that the core team were “responsible” for the project’s direction and success, which fostered complacency by non-core members. 34 | 3. This in turn led to more work for the core team, which made it more tolling to be a member of it, reinforcing the notion of "us" and "them" in point 1 above. 35 | 1. **The core team structure would either suck up or turn away contributors.** Either: there were no new core team members added, which would be bad for contributor morale, and bad for the legitimacy of the structure; 36 | Or: those that contributed the most in the community would be added, which would lead to only core team members being the strong contributors. Which in turn would reinforce the “us” and “them” situation described above. 37 | 1. **Despite all the authority vested in the core team, there were no real checks and balances.** 38 | - Core team members had the right to stay for an indefinite time, there were no terms. 39 | - Only core members could add new core members or remove existing ones. 40 | - Community members could protest and object in case of conflict, but nothing technically would prevent the core team from going against the will of the community. 41 | 1. **Sub-teams had few non-core team members active.** Because of the general lack of non-core engagement, it ended up being core team members filling up most of the spots in the sub-teams, defeating their purpose. 42 | 1. **The remit and scope of governance was left undefined.** Was the process supposed to govern Grin the wider network? Or Grin the implementation under the [/mimblewimble](http://github.com/mimblewimble/) github organization? How does the grin forum and grin.mw website fit into this? There were a lot of ambiguities as to what exactly was being governed. 43 | 44 | ### Objectives of the new structure 45 | 46 | 1. **Establish a clear scope.** Make it explicitly defined what the new structure applies to. 47 | 1. **Keep things simple.** Less is more. One of Grin's design objectives is minimalism. This should be applied to its governance model, as much as anywhere else. 48 | 1. **Empower contributors.** Make it easy for new contributors to get involved, pick up tasks, and feel responsible for some part of the project. 49 | 1. **Reduce centralization and single point of failure risk.** Avoid having all key decisions go through a single structure. 50 | 51 | ## Community-level explanation 52 | [community-level-explanation]: #community-level-explanation 53 | 54 | The new structure can be broken down into three areas: Scope, Teams, and Participation. 55 | 56 | ### Scope 57 | 58 | The explicit remit of this governance structure is defined as all the repos that are organized under the GitHub organization [/mimblewimble](https://github.com/mimblewimble) along with its existing and future communities and websites. This will be referred to as "the Project" below for clarity purposes, which include among other: 59 | 60 | - [/grin](https://github.com/mimblewimble/grin), [/grin-wallet](https://github.com/mimblewimble/grin-wallet), and [/grin-miner](https://github.com/mimblewimble/grin-miner) 61 | - [/grin-pm](https://github.com/mimblewimble/grin-pm), [/grin-rfcs](https://github.com/mimblewimble/grin-rfcs), and [/grin-security](https://github.com/mimblewimble/grin-security) 62 | - https://grin.mw 63 | - https://docs.grin.mw 64 | - https://forum.grin.mw 65 | - keybase [@grincoin](https://keybase.io/team/grincoin) team 66 | - [Mimblewimble mailing list](https://lists.launchpad.net/mimblewimble/) 67 | - [Grin General Fund](https://grin.mw/fund) 68 | 69 | ### Teams 70 | 71 | There is no hierarchical organization, and there is no "official" representative or group of representatives of the Project. Teams form and self-organize based on need. Teams are any group that carry out specific tasks or have specific responsibilities or have privileged access to tools or services related to the Project. They are responsible for their own processes and policies. 72 | 73 | #### Technocratic Council 74 | 75 | The Core Team as per RFC#0002 is removed. The existing members form the team that was known as the Technocratic Council prior to RFC#0002. The main purpose of the council is to manage the keys to the Grin General Fund and have final say in spending decisions. The technocratic council does not have a say in the matters of other teams. 76 | 77 | #### Other teams 78 | 79 | Examples of existing teams with various degree of organization that are seamlessly transitioned into their own autonomous structures include: 80 | 81 | - node development team 82 | - wallet dev team 83 | - security team 84 | - forum, keybase, and mailing list admins and moderators 85 | 86 | ### Participation 87 | 88 | - Each team is responsible for how to add or remove team members. Where practical, open and unrestricted participation is encouraged. 89 | - As much as possible of discussion and team organization should be made in public. Note-keeping is encouraged to make it easier for newcomers to get up to speed. 90 | - As with any other aspect of the Project, contributors are required to adhere to the [Code of Conduct](https://grin.mw/policies/code_of_conduct). 91 | 92 | ## Reference-level explanation 93 | [reference-level-explanation]: #reference-level-explanation 94 | 95 | This section covers some of the more technical details of the process. 96 | 97 | ### Naming 98 | 99 | Where there needs to be clarification between Grin (the implementation in [/mimblewimble/grin](https://github.com/mimblewimble/grin)), and Grin (the wider network consensus running any number of different implementations), it is suggested that [existing conventions](https://grinnode.live/stats) are followed and the former is referred to by the user agent name `MW/Grin` or `mw/grin`. 100 | 101 | ### RFC process 102 | 103 | The RFC process as defined in RFC#0001 remains unchanged, and is how "significant changes" are proposed. Teams can assign RFCs to themselves if RFCs relate to their areas. Other community members are free to opine on proposals. 104 | 105 | ### Funding 106 | 107 | The funding process remains as described in [RFC#0014: General Fund Guidelines](https://github.com/mimblewimble/grin-rfcs/blob/master/text/0014-general-fund-guidelines.md), with the difference that it is the Technocratic Council who now has final say on spending decisions. 108 | 109 | ### Consensus-breaking changes 110 | 111 | Network wide consensus rules are out of scope of this process. Significant changes to mw/grin are introduced via the existing RFC process. 112 | 113 | ### Disagreements / Dissent 114 | 115 | - Teams are expected to resolve their internal disputes to the best of their abilities. 116 | - Dysfunctional teams are replaced by forming new teams and contributors are encouraged to migrate over. 117 | - Where there is disagreement between teams, other teams and community members can be asked to mediate. 118 | 119 | ## Drawbacks 120 | [drawbacks]: #drawbacks 121 | 122 | - **Lack of final decision-making authority.** With no clear decision-making process to fall back on in case of major disagreements, a community split, and therefore a network fork, becomes more likely. 123 | - **Hierarchy is still present, but no longer as visible.** There are still some contributors with decision making authority, and some without. Before, this was codified explicitly. Now this is subtle and fluid. 124 | - **Tasks may fall in between cracks easier.** Without a team with ultimate responsibility picking up slack, some things might simply not get done and progress may slow. 125 | - **Lack of contributors may lead to the same people in charge everywhere.** Similar to the previous structure, if there are not enough new contributors joining, it ends up being the same people occupying all the different positions. 126 | 127 | ## Rationale and alternatives 128 | [rationale-and-alternatives]: #rationale-and-alternatives 129 | 130 | [A forum post](https://forum.grin.mw/t/dismantling-the-core-team-and-governance-structure/) on forum.grin.mw solicited ideas for alternatives to the previous structure. Some of those included: 131 | 132 | - Establishing different teams being responsible for funds, code repos, and direction; 133 | - Separating consensus protocol decisions from repository decisions; 134 | - Spending the General Fund more aggressively in order to try out new directions and ideas; 135 | - Simplifying or removing the RFC process altogether; and 136 | - Creating a "House of Representatives" to balance out the powers of the Core team. 137 | 138 | Additional options include: 139 | 140 | - Doing nothing; and 141 | - Attempting to establish a governance process that involves the entire network, current (and future?) implementations. 142 | 143 | The rationale for pursuing the specific approach that is outlined in this RFC is because it: 144 | 145 | - Establishes a scope for the process, which is contained and well defined; 146 | - Simplifies the structure significantly compared to what was before; 147 | - Has been tried in the past in the project, with some success; 148 | - Can be implemented easily, and does not carry much migration risk; 149 | - Can easily be evolved further by introducing new structures and processes if and when those are mandated; and 150 | - Is not likely to leave the project significantly worse off than before. 151 | 152 | ## Prior art 153 | [prior-art]: #prior-art 154 | 155 | This replaces RFC#0002 with something closer to the governance process that was in place earlier in the project's life cycle. 156 | 157 | ## Unresolved questions 158 | [unresolved-questions]: #unresolved-questions 159 | 160 | - What is the governance process between different implementations? 161 | - How can the funds and the spending decisions of the General Fund become more decentralized, removing the function of the Technocratic Council? 162 | - How can commit rights to the Project repos be formalized better? 163 | 164 | ## Future possibilities 165 | [future-possibilities]: #future-possibilities 166 | 167 | - Should we stop accepting donations to addresses controlled by a single entity? 168 | 169 | ## References 170 | [references]: #references 171 | 172 | - [RFC#0002: grin-governance](https://github.com/mimblewimble/grin-rfcs/blob/master/text/0002-grin-governance.md) 173 | - [RFC#0001: rfc-process](https://github.com/mimblewimble/grin-rfcs/blob/master/text/0001-rfc-process.md) 174 | - /mimblewimble GitHub organization: [https://github.com/mimblewimble](https://github.com/mimblewimble) 175 | - [https://forum.grin.mw/t/dismantling-the-core-team-and-governance-structure/](https://forum.grin.mw/t/dismantling-the-core-team-and-governance-structure/) 176 | -------------------------------------------------------------------------------- /text/0017-fix-fees.md: -------------------------------------------------------------------------------- 1 | - Title: fix-fees 2 | - Authors: [John Tromp](mailto:john.tromp@gmail.com) 3 | - Start date: August 23, 2020 4 | - RFC PR: [mimblewimble/grin-rfcs#63](https://github.com/mimblewimble/grin-rfcs/pull/63) 5 | - Tracking issue: [mimblewimble/grin/issues/3459](https://github.com/mimblewimble/grin/issues/3459) 6 | 7 | --- 8 | 9 | ## Summary 10 | [summary]: #summary 11 | 12 | Change Grin's minimum relay fees to be weight proportional and make output creation cost about a Grin-cent. 13 | Restrict fees to 40 bits, using 4 of the freed up 24 bits to specify the desired tx priority, 14 | and leaving the remaining 20 bits for future use. 15 | NOTE: this is a hard-forking change. 16 | 17 | ## Motivation 18 | [motivation]: #motivation 19 | 20 | The former fee requirements suffer from being somewhat arbitrary, and not miner incentive compatible. 21 | They are not even linear; to avoid a negative minimum fee, they are rounded up to `BASE_FEE`. 22 | As a consequence, the minimum fees for the aggregate of two 23 | transactions was not necessarily equal to the sum of the individual ones. 24 | Worse, a miner had no incentive to include a transaction that pays 0 fees, while they take resources to relay. 25 | The current (and foreseeable) low price of Grin makes spamming the UTXO set rather cheaper than desired. 26 | Fee overpaying, for higher priority to be included in full blocks, fails when aggregated with minimal fee transactions. 27 | 28 | ## Community-level explanation 29 | [community-level-explanation]: #community-level-explanation 30 | 31 | For clarity, let's adopt the following definitions. Let the feerate of 32 | a transaction be the fees paid by the transaction divided by the transaction 33 | weight with regards to block inclusion (`Transaction::weight_as_block`). 34 | Let the `minfee` of a transaction be the amount of fees required for relay and mempool inclusion. 35 | A transaction paying at least `minfee` in fees is said to be relayable. 36 | 37 | Grin constrains the size of blocks by a maximum block weight, which is a linear 38 | combination of the number of inputs, outputs, and kernels. When blocks fill 39 | up, miners are incentivized to pick transactions in decreasing order of feerate. 40 | Ideally then, higher feerate transactions are more relayable than lower feerate ones. 41 | Having a lower feerate transaction be relayable while a higher feerate transaction is not 42 | is very much undesirable and a recipe for problems in a congested network. 43 | 44 | The only way to avoid this mismatch between relay and block inclusion incentives 45 | is to make the minimum relay fee be proportional to the block weight of the 46 | transaction. This leaves only the constant of proportionality to be decided. 47 | We can calibrate the fee system by stipulating that creating one output should 48 | cost at least one Grin-cent (formerly 0.4 Grin-cent). 49 | 50 | We want minfee to be linear to make splitting and combining of fees well-behaved. 51 | For instance, two parties in a payjoin may each want pay their own input and output fees, 52 | while splitting the kernel fee, without overpaying for the whole transaction. 53 | 54 | Only the least significant 40 bits will be used to specify a fee, while 55 | some of the remaining bits will specify a minimum fee overpayment factor as a power-of-2, 56 | preventing aggregation with lesser overpaying transactions, and earlier inclusion into full blocks. 57 | 58 | The largest possible 40-bit fee is 2^40 - 1 nanogrin, or approximately 1099.5 grin, 59 | which should be more than enough to guarantee inclusion in the next available block. 60 | Technically speaking, transactions can pay higher fees by having multiple kernels, 61 | but we still want to avoid that kind of friction. 62 | As a side effect, this limits the damage of fat fingering a manually entered fee amount. 63 | 64 | ## Reference-level explanation 65 | [reference-level-explanation]: #reference-level-explanation 66 | 67 | The minimum relay fee of a transaction shall be proportional to `Transaction::weight_as_block`, 68 | which uses weights of `BLOCK_INPUT_WEIGHT` = 1, `BLOCK_OUTPUT_WEIGHT` = 21, and `BLOCK_KERNEL_WEIGHT` = 3, 69 | which correspond to the nearest multiple of 32 bytes that it takes to serialize. 70 | Formerly, we used `Transaction::weight`, 71 | which uses arbitrary weights of -1, 4, and 1 respectively, but also non-linearly rounds negative results up to 1 72 | (as happens when the number of inputs exceeds the number of kernels plus 4 times the number of outputs). 73 | 74 | The `Transaction::weight_as_block` shall be multiplied by a base fee. 75 | This will not be hardcoded, but configurable in grin-server.toml, 76 | using the already present `accept_fee_base` parameter. 77 | There is no reason to use different fees for relay and mempool acceptance. 78 | Its value shall default to `GRIN_BASE` / 100 / 20 = 500000, which makes each output 79 | incur just over 1 Grin-cent in fees. 80 | 81 | The 64-bit fee field in kernel types `Plain` and `HeightLocked` shall be renamed to `fee_bits` and be composed of bitfields 82 | { `future_use`: 20, `fee_shift`: 4, fee: 40 }. All former uses of the fee will use `fee_bits` & `FEE_MASK`, 83 | where `FEE_MASK = 0xffffffffff`. 84 | 85 | A nonzero fee shift places an additional restriction on transaction relay and mempool inclusion. 86 | Namely, a transaction containining a kernel with `fee_shift = s` must pay a total fee 87 | of at least 2^s times the minfee (the minfee shifted left by `fee_shift`). 88 | 89 | Aggregation of two relayable transactions should only happen when the result remains relayable. 90 | By linearity, this is always the case for two transactions with identical fee shift. 91 | Transactions with differing fee shift can be aggregated only if either one pays more 92 | than required by their fee shift. 93 | 94 | For instance, suppose two transactions have the same minfee. If one pays 3 times the minfee with a fee shift of 1, 95 | while the other pays exactly minfee with a zero fee shift, 96 | then both can be aggregated into one that pays twice the joint minfee (which is double the old one). 97 | 98 | While a transaction can choose an arbitrarily high feerate to incentivize early inclusion into full blocks, 99 | the fee shift provides for 16 different levels of protection against feerate dilution (through transaction aggregation). 100 | 101 | The new tx relay rules and new fee computation in wallets shall take effect at 102 | the HF4 block height of 1048320 (but see below about alternatives for 3rd party wallets). 103 | 104 | The 20 bits of `future_use bits` provide a possible soft-forking mechanism. 105 | We can imagine a future soft-fork further constraining the validity of kernels, 106 | or the relayability of transactions containing them, depending on the value of some of these bits. 107 | 108 | ## Drawbacks 109 | [drawbacks]: #drawbacks 110 | 111 | Leaving 20 bits of `future_use` increases the amount of zero cost zero friction 112 | spam that can be added to the chain. However, we already have a similar amount 113 | of spammable bits in the lock height of HeightLocked kernels, where any lock 114 | height under the current height of around a million has no effect. 115 | So this appears to be an acceptable increase. 116 | 117 | At the time of writing, only one other perceived drawback could be identified, which is what motivated the former fee rules. 118 | A negative weight on inputs was supposed to encourage spending many outputs, and lead to a reduction in UTXO size. 119 | But this aligned poorly with miner incentives, as for instance they have no economic reason to include zero fee transactions. 120 | A positive weight on inputs is no serious drawback, as long as creation of outputs is more strongly discouraged. 121 | Most wallets, especially those relying on payjoins, do about equal amounts of output creation and spending, 122 | the difference being just the wallet's UTXO set. 123 | Mining pools are the major exception. While they obviously don't incur any fees in coinbase creation, they need not 124 | spend fees on spending them either, as they can mine these payout transactions directly. 125 | 126 | ## Rationale and alternatives 127 | [rationale-and-alternatives]: #rationale-and-alternatives 128 | 129 | There are no good alternative to economically significant fees. Any blockchain lacking them is an open invitation to abuse. 130 | For chains with a maximum blocksize, fees are also necessary to allow prioritization of transactions. 131 | 132 | There is a small window prior to HF4 where transactions constructed using the former lower won't be finalized before HF4 and will thus fail to be relayed. Third party wallets are free to switch fee computation some arbitrary time before HF4 to minimize this risk. 133 | 134 | Instead of a fee shift, one could specify a fee factor. 135 | So then a transaction containing a kernel with the `fee_factor` bitfield having value f would require total fees 136 | of at least f+1 times minfee (preserving old behaviour for a 0 bitfield). 137 | A reasonable overpayment range would then require 8 bits instead of the 4 used for fee 138 | shift, and would create 256 levels of priority. It does seem 139 | wasteful though, to allow a distinction between, say, overpaying by 128 times, 140 | or by 129 times. 141 | Worse still, that many priority levels will severely reduce the potential for aggregation when blocks fill up. 142 | To maximize aggregation opportunities then, forcing priority levels to be a factor of 2 apart seems quite reasonable. 143 | 144 | We can avoid a consensus change by keeping the fee at the full 64 bits, 145 | instead using its least significant 4 bits to specify a fee shift. 146 | This only makes sense if we never plan to make any use of the top 24 bits, which would always be forced to 0 147 | unless someone pays a monstrous fee, most likely by accident. 148 | It would also lead to balances that are no longer a multiple of a milligrin, making for slightly worse UX. 149 | 150 | ## Prior art 151 | Several chains have suffered spam attacks. In early days, bitcoin was swamped with feeless wagers on Satoshi Dice [1]. 152 | At least those served some purpose. 153 | 154 | Nano was under a deluge of meaningless 0-value back and forth transfers for weeks, 155 | that added dozens of GB of redundant bloat to its chain data [2]. Although nano requires client PoW as a substitute for fees, 156 | these attacks showed that the PoW was poorly calibrated and not an effective deterrant. 157 | 158 | 159 | ## Unresolved questions 160 | [unresolved-questions]: #unresolved-questions 161 | 162 | ## Future possibilities 163 | [future-possibilities]: #future-possibilities 164 | 165 | While the input and kernel weights are pretty fixed, the output weight is subject to improvements in range proof technology. 166 | If Grin implements BP+, the weight should go down from 21 to 18. That would make outputs incur slightly less than a Grin-cent in fees, 167 | which is not worth bothering with. If range proofs were to halve in size though, then we might want to double the base fee to compensate. 168 | 169 | If Grin ever becomes worth many dollars, then a lowering of fees is desirable. 170 | This can then be achieved by getting the majority of running nodes to reconfigure their base fee to a lower value, 171 | after which wallets can have their fee computation adjusted. 172 | In the converse case, where Grin becomes worth only a few cents, then an increase in fees might be needed to avoid spam. 173 | Both cases will be much easier to deal with if they coincide with a hard fork, but those may not be on the horizon. 174 | 175 | ## References 176 | [references]: #references 177 | 178 | [1] [Satoshi Dice](https://en.bitcoin.it/wiki/Satoshi_Dice) 179 | 180 | [2] [Nano github](https://github.com/nanocurrency/nano-node/issues/1883) 181 | -------------------------------------------------------------------------------- /text/0018-fix-daa.md: -------------------------------------------------------------------------------- 1 | - Title: fix-daa 2 | - Authors: [John Tromp](mailto:john.tromp@gmail.com) 3 | - Start date: July 23, 2020 4 | - RFC PR: [mimblewimble/grin-rfcs#61](https://github.com/mimblewimble/grin-rfcs/pull/61) 5 | - Tracking issue: [mimblewimble/grin#3473](https://github.com/mimblewimble/grin/issues/3473) 6 | 7 | --- 8 | 9 | ## Summary 10 | [summary]: #summary 11 | 12 | Change Grin's DAA (Difficulty Adjustment Algorithm) from the current damped simple moving average (dsma) to a weighted-target exponential moving average (wtema). Also, restrict the future-time-limit (FTL) window to 5 minutes. 13 | 14 | ## Motivation 15 | [motivation]: #motivation 16 | 17 | The current DAA suffers from oscillatory behaviour, and also requires keeping the last 60 block on hand. 18 | wtema is simpler to state, requires only the last 2 blocks, and fixes the oscillatory behaviour. 19 | The current FTL window of 12 minutes appears rather arbitrary. It matches the 2-hour window used in bitcoin 20 | when expressed in their respective blocktimes, but we prefer a more natural amount in terms of clock time. 21 | 22 | 23 | ## Community-level explanation 24 | [community-level-explanation]: #community-level-explanation 25 | 26 | Grin aims for a 1 minute average block time. 27 | Thus, if the last block took exactly 1 minute to solve, then network difficulty 28 | remains the same in Grin's DAA. If it took 2 minutes to solve, then network 29 | difficulty should be decreased. 30 | But only by a small percentage. Halving network difficulty would make it way 31 | too erratic. Similarly, if the last block took less than a minute to solve, 32 | then network difficulty should be increased a little. 33 | Grin's DAA uses a simple formula to express the factor by which to change 34 | network difficulty, in terms of the ratio of last block time to ideal block 35 | time. 36 | 37 | A future-time-limit of 5 minutes naturally corresponds to the hour markers on a clock. 38 | The trade-off for FTL is between impact of timestamp manipulation and risk of divergence between local 39 | and actual clock time. For properly configured systems (e.g. correct time-zone and daylight-savings-time settings) 40 | we expect drifts of several minutes to be quite noticeable, and likely to be corrected by operators. 41 | 42 | ## Reference-level explanation 43 | [reference-level-explanation]: #reference-level-explanation 44 | 45 | In wtema-M, the factor by which to lower network difficulty after every block 46 | is 1 + (t/T - 1) / M, where T is the ideal block time of 60 seconds, t is the 47 | last block time in seconds, and M is a mean life time. Grin requires strictly 48 | increasing timestamps in consecutive blocks, so t > 0. 49 | In M blocks, the difficulty can thus be increased by at most (1-1/M)^-M ~ e. 50 | 51 | The maximum allowed clock drift (FTL parameter) is to be 5 minutes; blocks whose timestamp exceeds 52 | the local time by more than 5 minutes are ignored and not relayed. 53 | This parameter is not hardcoded but to be specified in grin-server.toml 54 | 55 | ## Drawbacks 56 | [drawbacks]: #drawbacks 57 | 58 | At the time of writing, the only apparent drawback is that using the difference of consecutive 59 | timestamps makes the DAA more susceptible to timestamp manipulation. To quantify 60 | the effect of this, let's say that miners maximally misrepresent m typical 61 | consecutive block times as one m-minute block + m-1 instant blocks. Instead of 62 | keeping network difficulty constant, this would divide it by (1+(m-1)/M) * (1-1/M)^m. 63 | For m much smaller than M, and M > 100, this is only a tiny increase in difficulty. 64 | If m is as large as k\*M+1 then this is (approximately) dividing by (1+k)/e^k, i.e. multiplying by e^k/(1+k). 65 | This is not something that miners should be interested in doing, 66 | as they generally want to maximize rewards by minimizing difficulty, 67 | so this kind of timestamp manipulation seems unlikely. 68 | On the other hand, they have a small incentive to misrepresent block times as 69 | being more regular (closer to T) than they really are, since for m blocks 70 | taking a total time of m\*T, setting timestamps exactly 1 minute apart minimizes the new difficulty. 71 | For instance, reporting a 30-second block and a 90-second block as two 1-minute blocks, changes the adjustment factor 72 | from (1-1/2M)(1+1/2M) = 1-1/4M^2 to 1, which for M > 100 is pretty negligible, indistinguishable from noise 73 | among realistic graphrate fluctuations. 74 | 75 | The risk of NTP (Network Time Protocol) based local clocks diverging by more than 5 minutes is somewhat 76 | larger than with a 12 minute threshold. 77 | 78 | ## Rationale and alternatives 79 | [rationale-and-alternatives]: #rationale-and-alternatives 80 | 81 | The simplest fix to the current DAA to reduce the problem of oscillations is to increase the damping factor. 82 | The reason Grin went with a small damping factor was to make the DAA very responsive to changes in graphrate. 83 | This responsiveness will suffer from increasing the damping factor. It makes sense to consider changing not just 84 | a parameter in the current DAA, but the DAA altogether, as alternatives may offer better trade-offs between stability 85 | and responsiveness. They may also achieve greater overall simplicity, both conceptually and in implementation. 86 | 87 | An FTL window of 1 minute, matching the blocktime, was considered as being the least arbitrary, 88 | and also leaving little room for timestamp manipulation. However, some worries remained that NTP is not robust enough to 89 | practically guarantee sub-minute drift even for properly configured systems. 90 | 91 | 92 | ## Prior art 93 | [prior-art]: #prior-art 94 | 95 | The current DAA in Bitcoin Cash suffers from the same oscillatory behaviour that Grin's DAA does. 96 | Which is what led various BCH developers to do extensive research on possible alternatives [1] [2]. 97 | They identified two DAAs as being superior to others. These two, wtema, and asert, also happen to behave nearly identically. 98 | While wtema is simpler in that it doesn't need exponentiation, it would need special safeguards to robustly deal with 99 | the possibility of very negative solvetimes. Since Grin requires strictly increasing timestamps, it doesn't need any such 100 | safeguards, making wtema the preferred choice for Grin. 101 | 102 | Before adding a dependence on number of parent uncles, Ethereum uses a DAA that can be seen as a close approximation of wtema: 103 | After every block, increase network difficulty by a factor of 1 - (t/T - 1) / M. 104 | Comparing with wtema above, we see that instead of dividing by (1+x), they multiply by (1-x). 105 | Even though Ethereum, like Grin, enforces positive solvetimes, they still need to guard against division by 0 in this form. 106 | 107 | ## Unresolved questions 108 | [unresolved-questions]: #unresolved-questions 109 | 110 | While this RFC argues for adopting wtema as a new DAA, it doesn't want to argue for a specific value of the half life M. 111 | In Grin tradition, an integral number of hours is preferable, to limit 112 | arbitrariness. Either 2 hours, 3 hours, or 4 hours, all offer a resonable 113 | balance of responsiveness and stability. 114 | These 3 choices as well as Grin's current DAA with various damping factor choices are implemented at [3], 115 | which allows for easy comparison across many scenarios. 116 | 117 | ## Future possibilities 118 | [future-possibilities]: #future-possibilities 119 | 120 | Although Grin graphrate has been relatively stable throughout its short 121 | history, as a GPU mineable coin available at nicehash, it's always at risk of 122 | sudden temporary surges in graphrate, to which it should be able to respond 123 | quickly. The current DAA does that, but at a cost (of oscillatory behaviour). 124 | In a future where Grin mining is dominated by Cuckatoo32 ASICs and where Grin 125 | is the C32 coin with the largest daily issuance, 126 | the graphrate should be naturally stable, with the need for responsiveness lessened. 127 | We should however account for the possibility of other coins adopting Cuckatoo32 as well. 128 | If, like most coins, they opt for a finite supply, then in initial years they 129 | may well have a daily issuance exceeding that of Grin. That would put us in the 130 | same situation as Bitcoin Cash competing with Bitcoin for ASIC hashrate. 131 | Having such a well vetted DAA will be a reassurance for years to come. 132 | 133 | Future improvements in network clock synchronization might make a reduction of FTL down to one minute viable. 134 | 135 | ## References 136 | [references]: #references 137 | 138 | [1] [archive.org](https://web.archive.org/web/20181120082228if_/https://www.yours.org/content/the-wtema-difficulty-adjustment-algorithm-855a3405606a/) 139 | 140 | [2] [read.cash](https://web.archive.org/web/20210117193410/https://read.cash/@jtoomim/bch-upgrade-proposal-use-asert-as-the-new-daa-1d875696) 141 | 142 | [3] (tromp github)https://github.com/tromp/difficulty 143 | -------------------------------------------------------------------------------- /text/0019-deprecate-http-tx.md: -------------------------------------------------------------------------------- 1 | - Title: Deprecate HTTP(S) Transactions 2 | - Authors: [joltz](mailto:joltz@protonmail.com) 3 | - Start date: April 28 2020 4 | - RFC PR: [mimblewimble/grin-rfcs#54](https://github.com/mimblewimble/grin-rfcs/pull/54) 5 | - Tracking issue: [mimblewimble/grin-wallet#523](https://github.com/mimblewimble/grin-wallet/issues/523) 6 | 7 | --- 8 | 9 | ## Summary 10 | [summary]: #summary 11 | 12 | Deprecating HTTP(S) as a transaction method helps preserve privacy for Grin users during the slate exchange process while building transactions. By only allowing the http listener in `grin-wallet` to listen on localhost by default, users and services will be encouraged to use more privacy-friendly transaction methods like Tor or directly exchanging armored slates via the [Slatepack](https://github.com/mimblewimble/grin-rfcs/blob/master/text/0015-slatepack.md) standard. This improves privacy for the Grin ecosystem by ensuring that services do not force Grin users into transaction methods that can easily violate their privacy like HTTP(S). 13 | 14 | ## Motivation 15 | [motivation]: #motivation 16 | 17 | Previously, Grin slates could be exchanged over HTTP(S) as a convenient method to take the required steps to exchange slate data between wallets to build a transaction. This method was commonly adopted by exchanges and services who already had infrastructure in place to configure wallets to listen for incoming HTTPS requests. 18 | 19 | Unfortunately, while convenient, this method of exchange requires the sender and receiver to reveal their IP addresses to route the network packets. This is bad for user privacy because without taking extra obfuscating steps, an IP address can often be traced to an individual. 20 | 21 | While steps can be taken to obfuscate a users true IP (like using a VPN), it is undesirable for a privacy-preserving technology like Grin to rely on this method for conventional use. It does not seem natural for users that are concerned about their privacy enough to use a technology like Grin to at the same time accept that their IP address is revealed when exchanging Grin with many services. 22 | 23 | Deprecating HTTP(S) provides a few benefits: 24 | - User experience is improved by not having to manage firewall settings like port forwarding to accept Grin transactions from most users 25 | - Wallet developer experience is improved with the need to support fewer transaction methods 26 | - Users will no longer be encouraged to engage in transaction methods that potentially violate privacy during the transaction building process 27 | - The ecosystem can converge around a universally accepted transaction flow that is privacy preserving 28 | 29 | The overall expected outcome is a privacy improvement for users that may otherwise have to reveal their IP address to send or receive Grin. 30 | 31 | ## Community-level explanation 32 | [community-level-explanation]: #community-level-explanation 33 | 34 | Deprecating HTTP(S) means that the old method of sending and listening for transactions over traditional HTTP(S) is no longer supported to help preserve privacy for Grin users who may not be aware of the risk to privacy using HTTP(S) poses. 35 | 36 | This reduces the overall number of transaction transport methods that need to be supported but requires that all services and wallets that previously only accepted/sent HTTP(S) transactions to upgrade at least to the version this RFC is implemented in to support their users. 37 | 38 | For the average user this means that to send or receive Grin they can use the [Slatepack](https://github.com/mimblewimble/grin-rfcs/blob/master/text/0015-slatepack.md) method. It is no longer possible to send and receive Grin via the HTTP(S) method without custom configuration. 39 | 40 | For wallet developers, it is no longer necessary to be concerned about managing HTTP(S) endpoints. All transactions will be conducted via Tor or asynchronous exchange of armored slate strings with the Slatepack standard. It can no longer be assumed that the counterparty in the transaction supports HTTP(S). 41 | 42 | Previously, some services like exchanges _only_ supported HTTP(S) Grin transactions. This change impacts these services significantly. 43 | 44 | Slatepack with Tor is the closest replacement to HTTP(S), but for some services the use of Tor is unacceptable, not possible or not allowed. These services will will need to refactor the user flow to allow supporting manual copying and pasting of [Slatepack armored transaction messages](https://github.com/mimblewimble/grin-rfcs/blob/master/text/0015-slatepack.md#slatepackmessage) instead, as the HTTP(S) method is no longer supported for `grin-wallet`. 45 | 46 | ## Reference-level explanation 47 | [reference-level-explanation]: #reference-level-explanation 48 | 49 | The technical and implementation details for this RFC are simple: no new features are added and some existing features are restricted: 50 | 51 | - `grin-wallet` http listener only accepts connections from localhost 52 | 53 | - `grin-wallet listen` no longer accepts `-e` argument 54 | 55 | - `grin-wallet send -d` requires a valid Slatepack address 56 | 57 | ### Deprecation Timeline 58 | 59 | - With v4.0.0 a public announcement will be made to notify the Grin ecosystem that HTTP(S) will be fully deprecated in v5.0.0 60 | 61 | - With v4.0.0 wallets will warn users that their privacy may be at risk when sending or listening via HTTP(S) and that the method will be deprecated in next major release 62 | 63 | - With v5.0.0 wallets will no longer support sending transactions via HTTP(S) 64 | 65 | - With v5.0.0 wallets will only accept connections from localhost by default. 66 | 67 | ## Drawbacks 68 | [drawbacks]: #drawbacks 69 | 70 | - Forces changes to existing transaction building workflows that use HTTP(S) 71 | 72 | - Remaining transaction options (Slatepack via Tor and armored message) may not be appealing for services already exclusively using HTTP(S) 73 | 74 | - Forces "always on" wallet listeners to use Tor or to build out logic to support handling armored slates in the UX flow 75 | 76 | - Potentially makes a technology that is already challenging for services to adopt even more challenging to adopt 77 | 78 | - Those that do not value privacy as a first-order objective may see this as an unnecessary inconvenience 79 | 80 | - Friction could cause some services to avoid Grin completely rather than adding support for a new transaction method 81 | 82 | ## Rationale and alternatives 83 | [rationale-and-alternatives]: #rationale-and-alternatives 84 | 85 | By not deprecating HTTP(S) an opportunity is lost to provide an additional layer of privacy to present and future Grin supporters. 86 | 87 | Deprecating HTTP only while continuing to support HTTPS would not likely be viable. As currently implemented, removing HTTP support would also mean removing HTTPS support. Allowing HTTPS while blocking HTTP may beyond the scope of `grin-wallet` configuration. 88 | 89 | ## Prior art 90 | [prior-art]: #prior-art 91 | 92 | A [general comparison of transaction methods for Grin](https://github.com/mimblewimble/grin-pm/issues/283) is available and provides many considerations when weighing possible transaction methods, including HTTP(S). 93 | 94 | Bitcoin previously used a similar transaction method (send to IP) which was deprecated as well for many valid reasons. While the arguments presented in this RFC are primarily derived from the objective of delivering privacy, there are other good reasons previously discussed in the context of Bitcoin. These discussions can be found partially in the [bitcointalk post](https://bitcointalk.org/index.php?topic=9334.0) accompanying the [PR](https://github.com/bitcoin/bitcoin/pull/253) that removed this feature for Bitcoin. 95 | 96 | Note that Grin is not quite in the same position as Bitcoin was when they deprecated this method as an alternative method existed that did not require interaction was available (P2PKH). Grin will still require interaction for the foreseeable future, either directly via Tor or asynchronously via Slatepack armored messages. 97 | 98 | ## Unresolved questions 99 | [unresolved-questions]: #unresolved-questions 100 | 101 | - Is it acceptable to the ecosystem to remove a commonly used transaction method? 102 | 103 | - Will the adoption of this RFC cause an unacceptable loss of support from existing adopting services? 104 | 105 | - Will deprecating HTTP(S) grow or reduce adoption in the next 6-12 months? 1-3 years? 5-10 years? 106 | 107 | ## Future possibilities 108 | [future-possibilities]: #future-possibilities 109 | 110 | This RFC along with others can eventually support ecosystem convergence around a single acceptable transaction building workflow supported by all wallets and services. 111 | 112 | ## References 113 | [references]: #references 114 | 115 | https://bitcointalk.org/index.php?topic=9334.0 116 | 117 | https://github.com/bitcoin/bitcoin/pull/253 118 | 119 | https://github.com/mimblewimble/grin-pm/issues/283 120 | 121 | https://github.com/mimblewimble/grin-rfcs/blob/master/text/0015-slatepack.md 122 | -------------------------------------------------------------------------------- /text/0021-fix-prior-fees.md: -------------------------------------------------------------------------------- 1 | - Title: fix-prior-fees 2 | - Authors: [John Tromp](mailto:john.tromp@gmail.com) 3 | - Start date: January 21, 2021 4 | - RFC PR: [mimblewimble/grin-rfcs#0021](https://github.com/mimblewimble/grin-rfcs/pull/77) 5 | - Tracking issue: https://github.com/mimblewimble/grin/issues/3635 6 | 7 | --- 8 | 9 | ## Summary 10 | [summary]: #summary 11 | 12 | Carry the restriction of fees, to 40 bits since HF4, back to all history. 13 | Do not change `headerversion` despite the hard-forking nature. 14 | 15 | ## Motivation 16 | [motivation]: #motivation 17 | 18 | This makes the `FeeFields` methods `fee()` and `fee_shift()` height independent, 19 | as well as several other functions which end up calling them. 20 | This results in nontrivial code and consensus model simplification, 21 | with no downside, which is always a good thing. 22 | 23 | ## Community-level explanation 24 | [community-level-explanation]: #community-level-explanation 25 | 26 | The largest fee to appear on mainnet prior to Hark Fork 4 is 2.404 Grin. This 27 | means that extending the current 40-bit fee restriction to the pre-HF4 history 28 | preserves validity. While this is technically a hard-forking change, we could 29 | treat it as an optional update. 30 | An attacker could in theory split the network by creating an ultra-deep reorg 31 | that includes a pre-HF4 fee exceeding 40 bits. However, the split damage would 32 | utterly pale in comparison to having a many months deep reorg in the first 33 | place. So in practice this change does not justify a header version bump and 34 | mandatory upgrade. 35 | 36 | ## Reference-level explanation 37 | [reference-level-explanation]: #reference-level-explanation 38 | 39 | When computing the fee paid by a transaction, take all the fee fields in transaction kernels, and mask out all but the least significant 40 bits. 40 | This masking used to be conditional on the header version of a argument height being at least 5 [1]. 41 | 42 | ## Drawbacks 43 | [drawbacks]: #drawbacks 44 | 45 | None! 46 | 47 | ## Rationale and alternatives 48 | [rationale-and-alternatives]: #rationale-and-alternatives 49 | 50 | There is no compelling reason for leaving a height dependency in the fee method. 51 | 52 | ## Unresolved questions 53 | [unresolved-questions]: #unresolved-questions 54 | 55 | How many months should we wait after HF4 before rolling out this code simplification? 56 | I propose that 3 months is more than enough, making this RFC acceptable from mid April 2021 onwards. 57 | 58 | ## Future possibilities 59 | [future-possibilities]: #future-possibilities 60 | 61 | ## References 62 | [references]: #references 63 | 64 | [1] [transaction.rs](https://github.com/mimblewimble/grin/blob/acba73bf40242f963d8ea1e7128dfdfde6fb8853/core/src/core/transaction.rs#L181-L188) 65 | --------------------------------------------------------------------------------