From e103c249c298353d9adc656ed334240d977c1c44 Mon Sep 17 00:00:00 2001 From: Benjamin Bollen Date: Wed, 21 Aug 2024 11:46:04 +0200 Subject: [PATCH 01/46] (docs): setup MkDocs for Circles Protocol documentation --- .gitignore | 2 +- docs/README.md | 79 +++++++++++++++++++++++++++++++++++++++++++ docs/docs/about.md | 3 ++ docs/docs/index.md | 3 ++ docs/mkdocs.yml | 5 +++ docs/requirements.txt | 1 + 6 files changed, 92 insertions(+), 1 deletion(-) create mode 100644 docs/README.md create mode 100644 docs/docs/about.md create mode 100644 docs/docs/index.md create mode 100644 docs/mkdocs.yml create mode 100644 docs/requirements.txt diff --git a/.gitignore b/.gitignore index 852fb69..52add64 100644 --- a/.gitignore +++ b/.gitignore @@ -3,7 +3,7 @@ cache/ out/ # docs -docs/ + # gas snapshot files .gas-snapshot diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..128417f --- /dev/null +++ b/docs/README.md @@ -0,0 +1,79 @@ +# Protocol Documentation + +This directory contains the documentation for the protocol using MkDocs. + +## Prerequisites + +- Miniconda or Anaconda installed on your system. If you don't have it installed, you can download and install it from the [official website](https://docs.conda.io/en/latest/miniconda.html). + +## Setup + +1. Open a terminal or command prompt and navigate to the `docs/` directory. + +2. Create a new conda environment named "protocol-docs" with Python 3.9: + ```bash + conda create --name protocol-docs python=3.9 + conda activate protocol-docs + ``` + +3. Install MkDocs and its dependencies from the `conda-forge` channel: + ```bash + conda install -c conda-forge --file requirements.txt + ``` + +4. Verify the installation by running: + ```bash + mkdocs --version + ``` + +## Usage + +1. Ensure you have activated the "protocol-docs" environment: + ```bash + conda activate protocol-docs + ``` + +2. Preview the documentation locally: + ```bash + mkdocs serve + ``` + Open a web browser and navigate to `http://localhost:8000` to view the documentation. + +3. Build the documentation: + ```bash + mkdocs build + ``` + The static HTML files will be generated in the `site/` directory. + +4. Deploy the documentation: + - Copy the contents of the `site/` directory to your preferred hosting platform or server. + - Configure your hosting platform to serve the files from the `site/` directory. + +## Adding Documentation + +- Create new Markdown files in the `docs/` directory for each documentation page. +- Update the `mkdocs.yml` file to include the new pages in the navigation structure. + +## Updating Dependencies + +If you need to update the dependencies or install additional packages, follow these steps: + +1. Update the `requirements.txt` file with the desired dependencies. + +2. Activate the "protocol-docs" environment: + ```bash + conda activate protocol-docs + ``` + +3. Update the dependencies using conda and the `conda-forge` channel: + ```bash + conda install -c conda-forge --file requirements.txt + ``` + +## Deactivating the Environment + +When you're done working on the documentation, you can deactivate the "protocol-docs" environment: + +```bash +conda deactivate +``` \ No newline at end of file diff --git a/docs/docs/about.md b/docs/docs/about.md new file mode 100644 index 0000000..27f51b4 --- /dev/null +++ b/docs/docs/about.md @@ -0,0 +1,3 @@ +# About Circles Protocol + +This is the about page of Circles protocol documentation. \ No newline at end of file diff --git a/docs/docs/index.md b/docs/docs/index.md new file mode 100644 index 0000000..e62c782 --- /dev/null +++ b/docs/docs/index.md @@ -0,0 +1,3 @@ +# Welcome to Circles Protocol Documentation + +This is the home page of Circles protocol documentation. \ No newline at end of file diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml new file mode 100644 index 0000000..bdf3f1b --- /dev/null +++ b/docs/mkdocs.yml @@ -0,0 +1,5 @@ +site_name: Circles Protocol +nav: + - Home: index.md + - About: about.md +theme: readthedocs \ No newline at end of file diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..b854bca --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1 @@ +mkdocs \ No newline at end of file From 8ef945dabcee4c19a18962ac293ef8e3d8770347 Mon Sep 17 00:00:00 2001 From: Benjamin Bollen Date: Wed, 21 Aug 2024 12:22:41 +0200 Subject: [PATCH 02/46] (docs): about page --- docs/docs/about.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/docs/about.md b/docs/docs/about.md index 27f51b4..9a59bbc 100644 --- a/docs/docs/about.md +++ b/docs/docs/about.md @@ -1,3 +1,9 @@ # About Circles Protocol -This is the about page of Circles protocol documentation. \ No newline at end of file +Circles is a vision for a fair and social form of money. It is also the culmination of the efforts of multiple teams over several years, working to bring this vision to life through organizing and building concrete instantiations. + +Various teams have collaborated with varying degrees of coordination and autonomy, all in the spirit of open-source development, to continually advance Circles forward. This protocol improvement to Circles is presented in that same spirit by the "About Circles" team, acting as a "Circles Ambassador." + +We do not claim any authority over what Circles should be or become. Instead, we humbly propose this as a way to make Circles better, and invite people to vote with their feet by adopting it if they find value in it. Our aim is simply to contribute to the Circles ecosystem and vision in a positive way. + +Ultimately, the path forward for Circles will be shaped by the collective actions and decisions of the community. We are merely one voice and one effort among many in this collaborative, open-source endeavor to create a fair and socially-embedded form of digital money. We are excited to be part of this journey and to see how Circles evolves. \ No newline at end of file From 1d108c85ef7a07566c4e1392202e8dd23342b328 Mon Sep 17 00:00:00 2001 From: Benjamin Bollen Date: Wed, 21 Aug 2024 12:34:38 +0200 Subject: [PATCH 03/46] (docs): add license for docs --- docs/LICENSE | 429 +++++++++++++++++++++++++++++++++++++++++++++ docs/docs/about.md | 10 +- 2 files changed, 438 insertions(+), 1 deletion(-) create mode 100644 docs/LICENSE diff --git a/docs/LICENSE b/docs/LICENSE new file mode 100644 index 0000000..3654b55 --- /dev/null +++ b/docs/LICENSE @@ -0,0 +1,429 @@ +Attribution-ShareAlike 4.0 International + +======================================================================= + +Creative Commons Corporation ("Creative Commons") is not a law firm and +does not provide legal services or legal advice. Distribution of +Creative Commons public licenses does not create a lawyer-client or +other relationship. Creative Commons makes its licenses and related +information available on an "as-is" basis. Creative Commons gives no +warranties regarding its licenses, any material licensed under their +terms and conditions, or any related information. Creative Commons +disclaims all liability for damages resulting from their use to the +fullest extent possible. + +Using Creative Commons Public Licenses + +Creative Commons public licenses provide a standard set of terms and +conditions that creators and other rights holders may use to share +original works of authorship and other material subject to copyright +and certain other rights specified in the public license below. The +following considerations are for informational purposes only, are not +exhaustive, and do not form part of our licenses. + + Considerations for licensors: Our public licenses are + intended for use by those authorized to give the public + permission to use material in ways otherwise restricted by + copyright and certain other rights. Our licenses are + irrevocable. Licensors should read and understand the terms + and conditions of the license they choose before applying it. + Licensors should also secure all rights necessary before + applying our licenses so that the public can reuse the + material as expected. Licensors should clearly mark any + material not subject to the license. This includes other CC- + licensed material, or material used under an exception or + limitation to copyright. More considerations for licensors: + wiki.creativecommons.org/Considerations_for_licensors + + Considerations for the public: By using one of our public + licenses, a licensor grants the public permission to use the + licensed material under specified terms and conditions. If + the licensor's permission is not necessary for any reason--for + example, because of any applicable exception or limitation to + copyright--then that use is not regulated by the license. Our + licenses grant only permissions under copyright and certain + other rights that a licensor has authority to grant. Use of + the licensed material may still be restricted for other + reasons, including because others have copyright or other + rights in the material. A licensor may make special requests, + such as asking that all changes be marked or described. + Although not required by our licenses, you are encouraged to + respect those requests where reasonable. More considerations + for the public: + wiki.creativecommons.org/Considerations_for_licensees + +======================================================================= + +Creative Commons Attribution-ShareAlike 4.0 International Public +License + +By exercising the Licensed Rights (defined below), You accept and agree +to be bound by the terms and conditions of this Creative Commons +Attribution-ShareAlike 4.0 International Public License ("Public +License"). To the extent this Public License may be interpreted as a +contract, You are granted the Licensed Rights in consideration of Your +acceptance of these terms and conditions, and the Licensor grants You +such rights in consideration of benefits the Licensor receives from +making the Licensed Material available under these terms and +conditions. + + +Section 1 -- Definitions. + + a. Adapted Material means material subject to Copyright and Similar + Rights that is derived from or based upon the Licensed Material + and in which the Licensed Material is translated, altered, + arranged, transformed, or otherwise modified in a manner requiring + permission under the Copyright and Similar Rights held by the + Licensor. For purposes of this Public License, where the Licensed + Material is a musical work, performance, or sound recording, + Adapted Material is always produced where the Licensed Material is + synched in timed relation with a moving image. + + b. Adapter's License means the license You apply to Your Copyright + and Similar Rights in Your contributions to Adapted Material in + accordance with the terms and conditions of this Public License. + + c. BY-SA Compatible License means a license listed at + creativecommons.org/compatiblelicenses, approved by Creative + Commons as essentially the equivalent of this Public License. + + d. Copyright and Similar Rights means copyright and/or similar rights + closely related to copyright including, without limitation, + performance, broadcast, sound recording, and Sui Generis Database + Rights, without regard to how the rights are labeled or + categorized. For purposes of this Public License, the rights + specified in Section 2(b)(1)-(2) are not Copyright and Similar + Rights. + + e. Effective Technological Measures means those measures that, in the + absence of proper authority, may not be circumvented under laws + fulfilling obligations under Article 11 of the WIPO Copyright + Treaty adopted on December 20, 1996, and/or similar international + agreements. + + f. Exceptions and Limitations means fair use, fair dealing, and/or + any other exception or limitation to Copyright and Similar Rights + that applies to Your use of the Licensed Material. + + g. License Elements means the license attributes listed in the name + of a Creative Commons Public License. The License Elements of this + Public License are Attribution and ShareAlike. + + h. Licensed Material means the artistic or literary work, database, + or other material to which the Licensor applied this Public + License. + + i. Licensed Rights means the rights granted to You subject to the + terms and conditions of this Public License, which are limited to + all Copyright and Similar Rights that apply to Your use of the + Licensed Material and that the Licensor has authority to license. + + j. Licensor means the individual(s) or entity(ies) granting rights + under this Public License. + + k. Share means to provide material to the public by any means or + process that requires permission under the Licensed Rights, such + as reproduction, public display, public performance, distribution, + dissemination, communication, or importation, and to make material + available to the public including in ways that members of the + public may access the material from a place and at a time + individually chosen by them. + + l. Sui Generis Database Rights means rights other than copyright + resulting from Directive 96/9/EC of the European Parliament and of + the Council of 11 March 1996 on the legal protection of databases, + as amended and/or succeeded, as well as other essentially + equivalent rights anywhere in the world. + + m. You means the individual or entity exercising the Licensed Rights + under this Public License. Your has a corresponding meaning. + + +Section 2 -- Scope. + + a. License grant. + + 1. Subject to the terms and conditions of this Public License, + the Licensor hereby grants You a worldwide, royalty-free, + non-sublicensable, non-exclusive, irrevocable license to + exercise the Licensed Rights in the Licensed Material to: + + a. reproduce and Share the Licensed Material, in whole or + in part; and + + b. produce, reproduce, and Share Adapted Material. + + 2. Exceptions and Limitations. For the avoidance of doubt, where + Exceptions and Limitations apply to Your use, this Public + License does not apply, and You do not need to comply with + its terms and conditions. + + 3. Term. The term of this Public License is specified in Section + 6(a). + + 4. Media and formats; technical modifications allowed. The + Licensor authorizes You to exercise the Licensed Rights in + all media and formats whether now known or hereafter created, + and to make technical modifications necessary to do so. The + Licensor waives and/or agrees not to assert any right or + authority to forbid You from making technical modifications + necessary to exercise the Licensed Rights, including + technical modifications necessary to circumvent Effective + Technological Measures. For purposes of this Public License, + simply making modifications authorized by this Section 2(a) + (4) never produces Adapted Material. + + 5. Downstream recipients. + + a. Offer from the Licensor -- Licensed Material. Every + recipient of the Licensed Material automatically + receives an offer from the Licensor to exercise the + Licensed Rights under the terms and conditions of this + Public License. + + b. Additional offer from the Licensor -- Adapted Material. + Every recipient of Adapted Material from You + automatically receives an offer from the Licensor to + exercise the Licensed Rights in the Adapted Material + under the conditions of the Adapter's License You apply. + + c. No downstream restrictions. You may not offer or impose + any additional or different terms or conditions on, or + apply any Effective Technological Measures to, the + Licensed Material if doing so restricts exercise of the + Licensed Rights by any recipient of the Licensed + Material. + + 6. No endorsement. Nothing in this Public License constitutes or + may be construed as permission to assert or imply that You + are, or that Your use of the Licensed Material is, connected + with, or sponsored, endorsed, or granted official status by, + the Licensor or others designated to receive attribution as + provided in Section 3(a)(1)(A)(i). + + b. Other rights. + + 1. Moral rights, such as the right of integrity, are not + licensed under this Public License, nor are publicity, + privacy, and/or other similar personality rights; however, to + the extent possible, the Licensor waives and/or agrees not to + assert any such rights held by the Licensor to the limited + extent necessary to allow You to exercise the Licensed + Rights, but not otherwise. + + 2. Patent and trademark rights are not licensed under this + Public License. + + 3. To the extent possible, the Licensor waives any right to + collect royalties from You for the exercise of the Licensed + Rights, whether directly or through a collecting society + under any voluntary or waivable statutory or compulsory + licensing scheme. In all other cases the Licensor expressly + reserves any right to collect such royalties. + + +Section 3 -- License Conditions. + +Your exercise of the Licensed Rights is expressly made subject to the +following conditions. + + a. Attribution. + + 1. If You Share the Licensed Material (including in modified + form), You must: + + a. retain the following if it is supplied by the Licensor + with the Licensed Material: + + i. identification of the creator(s) of the Licensed + Material and any others designated to receive + attribution, in any reasonable manner requested by + the Licensor (including by pseudonym if + designated); + + ii. a copyright notice; + + iii. a notice that refers to this Public License; + + iv. a notice that refers to the disclaimer of + warranties; + + v. a URI or hyperlink to the Licensed Material to the + extent reasonably practicable; + + b. indicate if You modified the Licensed Material and + retain an indication of any previous modifications; and + + c. indicate the Licensed Material is licensed under this + Public License, and include the text of, or the URI or + hyperlink to, this Public License. + + 2. You may satisfy the conditions in Section 3(a)(1) in any + reasonable manner based on the medium, means, and context in + which You Share the Licensed Material. For example, it may be + reasonable to satisfy the conditions by providing a URI or + hyperlink to a resource that includes the required + information. + + 3. If requested by the Licensor, You must remove any of the + information required by Section 3(a)(1)(A) to the extent + reasonably practicable. + + b. ShareAlike. + + In addition to the conditions in Section 3(a), if You Share + Adapted Material You produce, the following conditions also apply. + + 1. The Adapter's License You apply must be a Creative Commons + license with the same License Elements, this version or + later, or a BY-SA Compatible License. + + 2. You must include the text of, or the URI or hyperlink to, the + Adapter's License You apply. You may satisfy this condition + in any reasonable manner based on the medium, means, and + context in which You Share Adapted Material. + + 3. You may not offer or impose any additional or different terms + or conditions on, or apply any Effective Technological + Measures to, Adapted Material that restrict exercise of the + rights granted under the Adapter's License You apply. + + +Section 4 -- Sui Generis Database Rights. + +Where the Licensed Rights include Sui Generis Database Rights that +apply to Your use of the Licensed Material: + + a. for the avoidance of doubt, Section 2(a)(1) grants You the right + to extract, reuse, reproduce, and Share all or a substantial + portion of the contents of the database; + + b. if You include all or a substantial portion of the database + contents in a database in which You have Sui Generis Database + Rights, then the database in which You have Sui Generis Database + Rights (but not its individual contents) is Adapted Material, + including for purposes of Section 3(b); and + + c. You must comply with the conditions in Section 3(a) if You Share + all or a substantial portion of the contents of the database. + +For the avoidance of doubt, this Section 4 supplements and does not +replace Your obligations under this Public License where the Licensed +Rights include other Copyright and Similar Rights. + + +Section 5 -- Disclaimer of Warranties and Limitation of Liability. + + a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE + EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS + AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF + ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, + IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, + WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR + PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, + ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT + KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT + ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. + + b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE + TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, + NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, + INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, + COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR + USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN + ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR + DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR + IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. + + c. The disclaimer of warranties and limitation of liability provided + above shall be interpreted in a manner that, to the extent + possible, most closely approximates an absolute disclaimer and + waiver of all liability. + + +Section 6 -- Term and Termination. + + a. This Public License applies for the term of the Copyright and + Similar Rights licensed here. However, if You fail to comply with + this Public License, then Your rights under this Public License + terminate automatically. + + b. Where Your right to use the Licensed Material has terminated under + Section 6(a), it reinstates: + + 1. automatically as of the date the violation is cured, provided + it is cured within 30 days of Your discovery of the + violation; or + + 2. upon express reinstatement by the Licensor. + + For the avoidance of doubt, this Section 6(b) does not affect any + right the Licensor may have to seek remedies for Your violations + of this Public License. + + c. For the avoidance of doubt, the Licensor may also offer the + Licensed Material under separate terms or conditions or stop + distributing the Licensed Material at any time; however, doing so + will not terminate this Public License. + + d. Sections 1, 5, 6, 7, and 8 survive termination of this Public + License. + + +Section 7 -- Other Terms and Conditions. + + a. The Licensor shall not be bound by any additional or different + terms or conditions communicated by You unless expressly agreed. + + b. Any arrangements, understandings, or agreements regarding the + Licensed Material not stated herein are separate from and + independent of the terms and conditions of this Public License. + + +Section 8 -- Interpretation. + + a. For the avoidance of doubt, this Public License does not, and + shall not be interpreted to, reduce, limit, restrict, or impose + conditions on any use of the Licensed Material that could lawfully + be made without permission under this Public License. + + b. To the extent possible, if any provision of this Public License is + deemed unenforceable, it shall be automatically reformed to the + minimum extent necessary to make it enforceable. If the provision + cannot be reformed, it shall be severed from this Public License + without affecting the enforceability of the remaining terms and + conditions. + + c. No term or condition of this Public License will be waived and no + failure to comply consented to unless expressly agreed to by the + Licensor. + + d. Nothing in this Public License constitutes or may be interpreted + as a limitation upon, or waiver of, any privileges and immunities + that apply to the Licensor or You, including from the legal + processes of any jurisdiction or authority. + + +======================================================================= + +Creative Commons is not a party to its public +licenses. Notwithstanding, Creative Commons may elect to apply one of +its public licenses to material it publishes and in those instances +will be considered the “Licensor.” The text of the Creative Commons +public licenses is dedicated to the public domain under the CC0 Public +Domain Dedication. Except for the limited purpose of indicating that +material is shared under a Creative Commons public license or as +otherwise permitted by the Creative Commons policies published at +creativecommons.org/policies, Creative Commons does not authorize the +use of the trademark "Creative Commons" or any other trademark or logo +of Creative Commons without its prior written consent including, +without limitation, in connection with any unauthorized modifications +to any of its public licenses or any other arrangements, +understandings, or agreements concerning use of licensed material. For +the avoidance of doubt, this paragraph does not form part of the +public licenses. + +Creative Commons may be contacted at creativecommons.org. + +https://creativecommons.org/licenses/by-sa/4.0/ \ No newline at end of file diff --git a/docs/docs/about.md b/docs/docs/about.md index 9a59bbc..8d3e14c 100644 --- a/docs/docs/about.md +++ b/docs/docs/about.md @@ -6,4 +6,12 @@ Various teams have collaborated with varying degrees of coordination and autonom We do not claim any authority over what Circles should be or become. Instead, we humbly propose this as a way to make Circles better, and invite people to vote with their feet by adopting it if they find value in it. Our aim is simply to contribute to the Circles ecosystem and vision in a positive way. -Ultimately, the path forward for Circles will be shaped by the collective actions and decisions of the community. We are merely one voice and one effort among many in this collaborative, open-source endeavor to create a fair and socially-embedded form of digital money. We are excited to be part of this journey and to see how Circles evolves. \ No newline at end of file +Ultimately, the path forward for Circles will be shaped by the collective actions and decisions of the community. We are merely one voice and one effort among many in this collaborative, open-source endeavor to create a fair and socially-embedded form of digital money. We are excited to be part of this journey and to see how Circles evolves. + +## Licensing +In alignment with our open-source ethos, Circles Protocol is developed and released under the following licenses: + +- All code is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0), a strong copyleft license. This ensures that any derivative works or modifications of the code are also released under the same license, maintaining the open and shared nature of the codebase. +- All documentation is released under the Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) license. This is a copyleft license that allows others to share and adapt the material, as long as they credit the original creation and license their new creations under identical terms. + +We believe in the power of open collaboration and sharing, and these licenses reflect our commitment to keeping Circles open and accessible to all. \ No newline at end of file From 064110a4268dac90d8c4498fe001b4ba8c0f8f03 Mon Sep 17 00:00:00 2001 From: Benjamin Bollen Date: Wed, 21 Aug 2024 12:43:49 +0200 Subject: [PATCH 04/46] (docs): disclaimer --- docs/docs/about.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/docs/about.md b/docs/docs/about.md index 8d3e14c..da1b360 100644 --- a/docs/docs/about.md +++ b/docs/docs/about.md @@ -8,6 +8,9 @@ We do not claim any authority over what Circles should be or become. Instead, we Ultimately, the path forward for Circles will be shaped by the collective actions and decisions of the community. We are merely one voice and one effort among many in this collaborative, open-source endeavor to create a fair and socially-embedded form of digital money. We are excited to be part of this journey and to see how Circles evolves. +## Disclaimer +Circles is not owned or controlled by any single entity, including the "About Circles" team. Instead, it is a collective vision and effort, intended to be cared for and shaped by the wider community. The "About Circles" team acts as an ambassador and contributor to this vision, but does not claim any special authority or ownership over Circles. + ## Licensing In alignment with our open-source ethos, Circles Protocol is developed and released under the following licenses: From 6a175b3d9fcbcf74294fff05d72adc8b0024737f Mon Sep 17 00:00:00 2001 From: Benjamin Bollen Date: Wed, 21 Aug 2024 12:48:33 +0200 Subject: [PATCH 05/46] (docs): improve the title of About page --- docs/docs/about.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/about.md b/docs/docs/about.md index da1b360..8f5e7a4 100644 --- a/docs/docs/about.md +++ b/docs/docs/about.md @@ -1,4 +1,4 @@ -# About Circles Protocol +# About the Circles Protocol Circles is a vision for a fair and social form of money. It is also the culmination of the efforts of multiple teams over several years, working to bring this vision to life through organizing and building concrete instantiations. From 8779a351a379e0ca7166af7f27784ef522d74326 Mon Sep 17 00:00:00 2001 From: Benjamin Bollen Date: Wed, 21 Aug 2024 19:33:52 +0200 Subject: [PATCH 06/46] (docs): documentation outline, a first proposal --- .../advanced-topics/group-mint-policies.md | 0 docs/docs/advanced-topics/index.md | 0 .../advanced-topics/inflation-demurrage.md | 0 .../path-based-transactions.md | 0 docs/docs/appendices/contract-addresses.md | 0 docs/docs/appendices/external-resources.md | 0 docs/docs/appendices/index.md | 0 docs/docs/architecture.md | 0 docs/docs/contract-interactions.md | 0 .../core-functionality/circles-contract.md | 0 docs/docs/core-functionality/hub-contract.md | 0 docs/docs/core-functionality/index.md | 0 .../developer-resources/best-practices.md | 0 .../docs/developer-resources/contract-abis.md | 0 docs/docs/developer-resources/index.md | 0 .../integration-guidelines.md | 0 docs/docs/glossary.md | 0 docs/docs/index.md | 66 ++++++++++++++++++- docs/docs/introduction.md | 3 + docs/docs/key-features.md | 0 docs/docs/user-guides/group-currencies.md | 0 docs/docs/user-guides/index.md | 0 docs/docs/user-guides/minting-transferring.md | 0 docs/docs/user-guides/registration.md | 0 docs/docs/user-guides/trust-management.md | 0 docs/mkdocs.yml | 33 +++++++++- 26 files changed, 99 insertions(+), 3 deletions(-) create mode 100644 docs/docs/advanced-topics/group-mint-policies.md create mode 100644 docs/docs/advanced-topics/index.md create mode 100644 docs/docs/advanced-topics/inflation-demurrage.md create mode 100644 docs/docs/advanced-topics/path-based-transactions.md create mode 100644 docs/docs/appendices/contract-addresses.md create mode 100644 docs/docs/appendices/external-resources.md create mode 100644 docs/docs/appendices/index.md create mode 100644 docs/docs/architecture.md create mode 100644 docs/docs/contract-interactions.md create mode 100644 docs/docs/core-functionality/circles-contract.md create mode 100644 docs/docs/core-functionality/hub-contract.md create mode 100644 docs/docs/core-functionality/index.md create mode 100644 docs/docs/developer-resources/best-practices.md create mode 100644 docs/docs/developer-resources/contract-abis.md create mode 100644 docs/docs/developer-resources/index.md create mode 100644 docs/docs/developer-resources/integration-guidelines.md create mode 100644 docs/docs/glossary.md create mode 100644 docs/docs/introduction.md create mode 100644 docs/docs/key-features.md create mode 100644 docs/docs/user-guides/group-currencies.md create mode 100644 docs/docs/user-guides/index.md create mode 100644 docs/docs/user-guides/minting-transferring.md create mode 100644 docs/docs/user-guides/registration.md create mode 100644 docs/docs/user-guides/trust-management.md diff --git a/docs/docs/advanced-topics/group-mint-policies.md b/docs/docs/advanced-topics/group-mint-policies.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/docs/advanced-topics/index.md b/docs/docs/advanced-topics/index.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/docs/advanced-topics/inflation-demurrage.md b/docs/docs/advanced-topics/inflation-demurrage.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/docs/advanced-topics/path-based-transactions.md b/docs/docs/advanced-topics/path-based-transactions.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/docs/appendices/contract-addresses.md b/docs/docs/appendices/contract-addresses.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/docs/appendices/external-resources.md b/docs/docs/appendices/external-resources.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/docs/appendices/index.md b/docs/docs/appendices/index.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/docs/architecture.md b/docs/docs/architecture.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/docs/contract-interactions.md b/docs/docs/contract-interactions.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/docs/core-functionality/circles-contract.md b/docs/docs/core-functionality/circles-contract.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/docs/core-functionality/hub-contract.md b/docs/docs/core-functionality/hub-contract.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/docs/core-functionality/index.md b/docs/docs/core-functionality/index.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/docs/developer-resources/best-practices.md b/docs/docs/developer-resources/best-practices.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/docs/developer-resources/contract-abis.md b/docs/docs/developer-resources/contract-abis.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/docs/developer-resources/index.md b/docs/docs/developer-resources/index.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/docs/developer-resources/integration-guidelines.md b/docs/docs/developer-resources/integration-guidelines.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/docs/glossary.md b/docs/docs/glossary.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/docs/index.md b/docs/docs/index.md index e62c782..d788b7c 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -1,3 +1,65 @@ -# Welcome to Circles Protocol Documentation +# Circles Documentation -This is the home page of Circles protocol documentation. \ No newline at end of file +Welcome to the Circles documentation. This guide will help you understand the Circles project, its architecture, and core functionalities. + +## Table of Contents + +1. [Introduction to Circles](introduction.md) + - Brief overview of the Circles project + - Purpose and goals of Circles + - Key concepts: personal currencies, trust networks, and demurrage + +2. [Architectural Overview](architecture.md) + - High-level system architecture + - Key components: + - Hub contract + - Circles contract + - ERC1155 implementation + - Relationship between components + +3. [Core Functionality](core-functionality/index.md) + 1. [Hub Contract (Hub.sol)](core-functionality/hub-contract.md) + - Avatar registration (humans, organizations, groups) + - Trust system + - Minting and issuance + - Token transfers and path-based transactions + - Migration from v1 + + 2. [Circles Contract (Circles.sol)](core-functionality/circles-contract.md) + - Issuance mechanism + - Demurrage implementation + - Personal minting + - Balance management + +4. [Key Features](key-features.md) + - Multi-token support (ERC1155) + - Demurraged balances + - Trust-based transfers + - Group currencies and mint policies + - Migration from v1 to v2 + +5. [Contract Interactions](contract-interactions.md) + - Inheritance structure and responsibilities + +6. [Advanced Topics](advanced-topics/index.md) + - [Inflation and demurrage calculations](advanced-topics/inflation-demurrage.md) + - [Path-based transactions and flow matrices](advanced-topics/path-based-transactions.md) + - [Group mint policies and treasuries](advanced-topics/group-mint-policies.md) + +7. [User Guides](user-guides/index.md) + - [How to register as a human, organization, or group](user-guides/registration.md) + - [Managing trust relationships](user-guides/trust-management.md) + - [Minting and transferring Circles](user-guides/minting-transferring.md) + - [Interacting with group currencies](user-guides/group-currencies.md) + +8. [Developer Resources](developer-resources/index.md) + - [Contract ABIs](developer-resources/contract-abis.md) + - [Integration guidelines](developer-resources/integration-guidelines.md) + - [Best practices for interacting with Circles contracts](developer-resources/best-practices.md) + +9. [Glossary of Terms](glossary.md) + - Definitions of key concepts and terminology used in Circles + +10. [Appendices](appendices/index.md) + - [Contract addresses](appendices/contract-addresses.md) + - [Relevant external resources and links](appendices/external-resources.md) \ No newline at end of file diff --git a/docs/docs/introduction.md b/docs/docs/introduction.md new file mode 100644 index 0000000..b8d20a5 --- /dev/null +++ b/docs/docs/introduction.md @@ -0,0 +1,3 @@ +# Introduction to Circles + +Introduction \ No newline at end of file diff --git a/docs/docs/key-features.md b/docs/docs/key-features.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/docs/user-guides/group-currencies.md b/docs/docs/user-guides/group-currencies.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/docs/user-guides/index.md b/docs/docs/user-guides/index.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/docs/user-guides/minting-transferring.md b/docs/docs/user-guides/minting-transferring.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/docs/user-guides/registration.md b/docs/docs/user-guides/registration.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/docs/user-guides/trust-management.md b/docs/docs/user-guides/trust-management.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index bdf3f1b..2120bf3 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -1,5 +1,36 @@ site_name: Circles Protocol +theme: readthedocs +site_name: Circles Protocol +theme: readthedocs nav: - Home: index.md - About: about.md -theme: readthedocs \ No newline at end of file + - Introduction: introduction.md + - Architectural Overview: architecture.md + - Core Functionality: + - Overview: core-functionality/index.md + - Hub Contract: core-functionality/hub-contract.md + - Circles Contract: core-functionality/circles-contract.md + - Key Features: key-features.md + - Contract Interactions: contract-interactions.md + - Advanced Topics: + - Overview: advanced-topics/index.md + - Inflation and Demurrage: advanced-topics/inflation-demurrage.md + - Path-based Transactions: advanced-topics/path-based-transactions.md + - Group Mint Policies: advanced-topics/group-mint-policies.md + - User Guides: + - Overview: user-guides/index.md + - Registration: user-guides/registration.md + - Trust Management: user-guides/trust-management.md + - Minting and Transferring: user-guides/minting-transferring.md + - Group Currencies: user-guides/group-currencies.md + - Developer Resources: + - Overview: developer-resources/index.md + - Contract ABIs: developer-resources/contract-abis.md + - Integration Guidelines: developer-resources/integration-guidelines.md + - Best Practices: developer-resources/best-practices.md + - Glossary: glossary.md + - Appendices: + - Overview: appendices/index.md + - Contract Addresses: appendices/contract-addresses.md + - External Resources: appendices/external-resources.md From ef33f6a79a10dfec0b59a3a0f937e5a97be4d679 Mon Sep 17 00:00:00 2001 From: Benjamin Bollen Date: Wed, 21 Aug 2024 19:37:40 +0200 Subject: [PATCH 07/46] (docs): correct indentation in overview --- docs/docs/index.md | 74 +++++++++++++++++++++++----------------------- 1 file changed, 37 insertions(+), 37 deletions(-) diff --git a/docs/docs/index.md b/docs/docs/index.md index d788b7c..2065066 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -5,60 +5,60 @@ Welcome to the Circles documentation. This guide will help you understand the Ci ## Table of Contents 1. [Introduction to Circles](introduction.md) - - Brief overview of the Circles project - - Purpose and goals of Circles - - Key concepts: personal currencies, trust networks, and demurrage + - Brief overview of the Circles project + - Purpose and goals of Circles + - Key concepts: personal currencies, trust networks, and demurrage 2. [Architectural Overview](architecture.md) - - High-level system architecture - - Key components: - - Hub contract - - Circles contract - - ERC1155 implementation - - Relationship between components + - High-level system architecture + - Key components: + - Hub contract + - Circles contract + - ERC1155 implementation + - Relationship between components 3. [Core Functionality](core-functionality/index.md) - 1. [Hub Contract (Hub.sol)](core-functionality/hub-contract.md) - - Avatar registration (humans, organizations, groups) - - Trust system - - Minting and issuance - - Token transfers and path-based transactions - - Migration from v1 + 1. [Hub Contract (Hub.sol)](core-functionality/hub-contract.md) + - Avatar registration (humans, organizations, groups) + - Trust system + - Minting and issuance + - Token transfers and path-based transactions + - Migration from v1 - 2. [Circles Contract (Circles.sol)](core-functionality/circles-contract.md) - - Issuance mechanism - - Demurrage implementation - - Personal minting - - Balance management + 2. [Circles Contract (Circles.sol)](core-functionality/circles-contract.md) + - Issuance mechanism + - Demurrage implementation + - Personal minting + - Balance management 4. [Key Features](key-features.md) - - Multi-token support (ERC1155) - - Demurraged balances - - Trust-based transfers - - Group currencies and mint policies - - Migration from v1 to v2 + - Multi-token support (ERC1155) + - Demurraged balances + - Trust-based transfers + - Group currencies and mint policies + - Migration from v1 to v2 5. [Contract Interactions](contract-interactions.md) - - Inheritance structure and responsibilities + - Inheritance structure and responsibilities 6. [Advanced Topics](advanced-topics/index.md) - - [Inflation and demurrage calculations](advanced-topics/inflation-demurrage.md) - - [Path-based transactions and flow matrices](advanced-topics/path-based-transactions.md) - - [Group mint policies and treasuries](advanced-topics/group-mint-policies.md) + - [Inflation and demurrage calculations](advanced-topics/inflation-demurrage.md) + - [Path-based transactions and flow matrices](advanced-topics/path-based-transactions.md) + - [Group mint policies and treasuries](advanced-topics/group-mint-policies.md) 7. [User Guides](user-guides/index.md) - - [How to register as a human, organization, or group](user-guides/registration.md) - - [Managing trust relationships](user-guides/trust-management.md) - - [Minting and transferring Circles](user-guides/minting-transferring.md) - - [Interacting with group currencies](user-guides/group-currencies.md) + - [How to register as a human, organization, or group](user-guides/registration.md) + - [Managing trust relationships](user-guides/trust-management.md) + - [Minting and transferring Circles](user-guides/minting-transferring.md) + - [Interacting with group currencies](user-guides/group-currencies.md) 8. [Developer Resources](developer-resources/index.md) - - [Contract ABIs](developer-resources/contract-abis.md) - - [Integration guidelines](developer-resources/integration-guidelines.md) - - [Best practices for interacting with Circles contracts](developer-resources/best-practices.md) + - [Contract ABIs](developer-resources/contract-abis.md) + - [Integration guidelines](developer-resources/integration-guidelines.md) + - [Best practices for interacting with Circles contracts](developer-resources/best-practices.md) 9. [Glossary of Terms](glossary.md) - - Definitions of key concepts and terminology used in Circles + - Definitions of key concepts and terminology used in Circles 10. [Appendices](appendices/index.md) - [Contract addresses](appendices/contract-addresses.md) From a52e7aac43e935bbfc5f690bf5362345ac115e41 Mon Sep 17 00:00:00 2001 From: Benjamin Bollen Date: Wed, 21 Aug 2024 20:40:25 +0200 Subject: [PATCH 08/46] (docs): first draft of introduction --- docs/docs/introduction.md | 54 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 53 insertions(+), 1 deletion(-) diff --git a/docs/docs/introduction.md b/docs/docs/introduction.md index b8d20a5..3abfa12 100644 --- a/docs/docs/introduction.md +++ b/docs/docs/introduction.md @@ -1,3 +1,55 @@ # Introduction to Circles -Introduction \ No newline at end of file +## Brief Overview + +Circles is an innovative blockchain-based protocol designed to create and distribute a basic income through personal currencies. It leverages the power of decentralized technology to implement a system of interconnected, individual economic units that together form a larger, more equitable economic network. + +The Circles protocol is built on top of the Ethereum blockchain, utilizing smart contracts to manage the creation, distribution, and transfer of personal currencies. At its core, Circles employs an ERC1155 multi-token standard, allowing for efficient handling of multiple token types within a single contract. + +## Purpose and Goals of Circles + +The primary purpose of Circles is to create a more inclusive and sustainable economic system by providing a basic income to all participants. By doing so, Circles aims to: + +1. Reduce economic inequality by ensuring a baseline level of economic participation for all. +2. Foster community connections and local economies through trust-based currency networks. +3. Encourage sustainable economic growth by implementing a demurrage system that discourages hoarding and promotes circulation. +4. Provide a flexible framework for various economic experiments and community-driven initiatives. + +## Key Concepts + +### Personal Currencies + +In the Circles ecosystem, each individual can mint their own personal currency. This is a unique feature of the protocol, allowing every participant to become an issuer of their own basic income. The Hub contract manages the registration of individuals (referred to as "humans" in the contract) and the issuance of their personal currencies. + +Key points about personal currencies: +- Each registered human can mint a fixed amount of their personal currency regularly (1 Circle per hour). +- Personal currencies are represented as unique tokens within the ERC1155 multi-token system. +- The minting process is managed by the `personalMint()` function in the Hub contract. + +### Trust Networks + +Trust is a fundamental concept in the Circles protocol. It allows personal currencies to become valuable and transferable within the network. The trust system is implemented in the Hub contract through the following mechanisms: + +- Users can establish trust relationships with other users using the `trust()` function. +- Trust relationships have expiration times, allowing for dynamic trust networks. +- The `isPermittedFlow()` function checks if a transfer is allowed based on the trust relationships between the sender, receiver, and the currency being transferred. + +Trust networks enable: +- Path-based transactions, where currencies can be exchanged through chains of trust. +- Community-building, as users create economic connections with those they trust. +- A decentralized approach to currency valuation and acceptance. + +### Demurrage + +Demurrage is an economic concept where the value of a currency decreases over time. In Circles, this is implemented to encourage circulation of the currency and discourage hoarding. The Circles contract includes a demurrage system with the following characteristics: + +- Balances are stored as "discounted balances" that automatically decrease in value over time. +- The `_calculateIssuance()` function in the Circles contract accounts for demurrage when determining how much new currency to mint for a user. +- Demurrage applies to both personal currencies and group currencies. + +This system ensures that: +- The currency remains active and circulating within the community. +- Long-term storage of wealth is discouraged, promoting a more dynamic economy. +- The basic income aspect of the system remains relevant, as users are incentivized to regularly engage with their personal currency. + +By combining these key concepts - personal currencies, trust networks, and demurrage - Circles creates a unique economic system that aims to provide a basic income while fostering community connections and encouraging active participation in the local economy. \ No newline at end of file From e485a6d9691125deab760bd2d8b935e0c39c38f9 Mon Sep 17 00:00:00 2001 From: Benjamin Bollen Date: Wed, 21 Aug 2024 22:21:05 +0200 Subject: [PATCH 09/46] (docs): first revision of intro/brief overview --- docs/docs/introduction.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/docs/introduction.md b/docs/docs/introduction.md index 3abfa12..31000ef 100644 --- a/docs/docs/introduction.md +++ b/docs/docs/introduction.md @@ -2,15 +2,15 @@ ## Brief Overview -Circles is an innovative blockchain-based protocol designed to create and distribute a basic income through personal currencies. It leverages the power of decentralized technology to implement a system of interconnected, individual economic units that together form a larger, more equitable economic network. +Circles is a digital protocol designed to create and distribute a a fair and social money through personal currencies. It leverages the power of decentralized technology to implement a system of interconnected, individual economic units that together form a larger, more equitable economic network. -The Circles protocol is built on top of the Ethereum blockchain, utilizing smart contracts to manage the creation, distribution, and transfer of personal currencies. At its core, Circles employs an ERC1155 multi-token standard, allowing for efficient handling of multiple token types within a single contract. +The Circles protocol is built on top of the Gnosis Chain blockchain, utilizing smart contracts to manage the creation, distribution, and transfer of personal currencies. At its core, Circles employs an ERC1155 multi-token standard, allowing for efficient handling of multiple token types (different personal and group Circles -- more on groups later) within a single contract. ## Purpose and Goals of Circles -The primary purpose of Circles is to create a more inclusive and sustainable economic system by providing a basic income to all participants. By doing so, Circles aims to: +The primary purpose of Circles is to create a more inclusive and sustainable economic system by providing equitable issuance of money to all participants. By doing so, Circles aims to: -1. Reduce economic inequality by ensuring a baseline level of economic participation for all. +1. Introduce community currencies with lower economic inequality by ensuring a baseline level of economic participation for all. 2. Foster community connections and local economies through trust-based currency networks. 3. Encourage sustainable economic growth by implementing a demurrage system that discourages hoarding and promotes circulation. 4. Provide a flexible framework for various economic experiments and community-driven initiatives. @@ -22,6 +22,7 @@ The primary purpose of Circles is to create a more inclusive and sustainable eco In the Circles ecosystem, each individual can mint their own personal currency. This is a unique feature of the protocol, allowing every participant to become an issuer of their own basic income. The Hub contract manages the registration of individuals (referred to as "humans" in the contract) and the issuance of their personal currencies. Key points about personal currencies: + - Each registered human can mint a fixed amount of their personal currency regularly (1 Circle per hour). - Personal currencies are represented as unique tokens within the ERC1155 multi-token system. - The minting process is managed by the `personalMint()` function in the Hub contract. From 5b2c82b3a9976d3d9a4284322f5bd2056a92cea8 Mon Sep 17 00:00:00 2001 From: Benjamin Bollen Date: Wed, 21 Aug 2024 22:29:03 +0200 Subject: [PATCH 10/46] (githubAction): quick add WIP hosting on fork --- .github/workflows/deploy-mkdocs.yml | 31 +++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) create mode 100644 .github/workflows/deploy-mkdocs.yml diff --git a/.github/workflows/deploy-mkdocs.yml b/.github/workflows/deploy-mkdocs.yml new file mode 100644 index 0000000..0116b00 --- /dev/null +++ b/.github/workflows/deploy-mkdocs.yml @@ -0,0 +1,31 @@ +name: Deploy MkDocs to GitHub Pages + +on: + push: + branches: + - 20240821-docs + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + + - name: Set up Python + uses: actions/setup-python@v2 + with: + python-version: '3.x' + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install mkdocs mkdocs-material + + - name: Build site + run: mkdocs build + + - name: Deploy to GitHub Pages + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./site \ No newline at end of file From d9e55fa506975bea77329ef49c1a71e553b8c0ec Mon Sep 17 00:00:00 2001 From: Benjamin Bollen Date: Wed, 21 Aug 2024 22:34:30 +0200 Subject: [PATCH 11/46] (docs): update github action for conda and folder docs/ --- .github/workflows/deploy-mkdocs.yml | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/.github/workflows/deploy-mkdocs.yml b/.github/workflows/deploy-mkdocs.yml index 0116b00..837cb85 100644 --- a/.github/workflows/deploy-mkdocs.yml +++ b/.github/workflows/deploy-mkdocs.yml @@ -11,21 +11,26 @@ jobs: steps: - uses: actions/checkout@v2 - - name: Set up Python - uses: actions/setup-python@v2 + - name: Set up Conda + uses: conda-incubator/setup-miniconda@v2 with: - python-version: '3.x' + auto-update-conda: true + python-version: 3.9 - name: Install dependencies + shell: bash -l {0} run: | - python -m pip install --upgrade pip - pip install mkdocs mkdocs-material + cd docs/ + conda install -c conda-forge --file requirements.txt - name: Build site - run: mkdocs build + shell: bash -l {0} + run: | + cd docs/ + mkdocs build - name: Deploy to GitHub Pages uses: peaceiris/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB_TOKEN }} - publish_dir: ./site \ No newline at end of file + publish_dir: ./docs/site \ No newline at end of file From 328cc211254ca63bad04f2f6f40aa7aed5bdc8f3 Mon Sep 17 00:00:00 2001 From: Benjamin Bollen Date: Thu, 22 Aug 2024 12:02:26 +0200 Subject: [PATCH 12/46] (docs): improvements to introduction overview, purpose and key concepts personal currencies --- docs/docs/introduction.md | 26 ++++++++++++++++---------- 1 file changed, 16 insertions(+), 10 deletions(-) diff --git a/docs/docs/introduction.md b/docs/docs/introduction.md index 31000ef..645f156 100644 --- a/docs/docs/introduction.md +++ b/docs/docs/introduction.md @@ -2,30 +2,36 @@ ## Brief Overview -Circles is a digital protocol designed to create and distribute a a fair and social money through personal currencies. It leverages the power of decentralized technology to implement a system of interconnected, individual economic units that together form a larger, more equitable economic network. +Circles is a digital protocol designed to create and distribute fair and social money through personal currencies. It harnesses the power of decentralized technology to implement a system of interconnected, individual economic units that collectively form a larger, more equitable economic network. -The Circles protocol is built on top of the Gnosis Chain blockchain, utilizing smart contracts to manage the creation, distribution, and transfer of personal currencies. At its core, Circles employs an ERC1155 multi-token standard, allowing for efficient handling of multiple token types (different personal and group Circles -- more on groups later) within a single contract. +The Circles protocol is built on the Gnosis Chain blockchain, utilizing smart contracts to manage the creation, distribution, and transfer of personal currencies. At its core, Circles employs an ERC1155 multi-token standard, enabling efficient handling of multiple token types (different personal and group Circles -- more on groups later) within a single contract. ## Purpose and Goals of Circles -The primary purpose of Circles is to create a more inclusive and sustainable economic system by providing equitable issuance of money to all participants. By doing so, Circles aims to: +The primary purpose of Circles is to create a more inclusive and sustainable economic system through the equitable issuance of money to all participants. In pursuing this vision, Circles aims to: -1. Introduce community currencies with lower economic inequality by ensuring a baseline level of economic participation for all. -2. Foster community connections and local economies through trust-based currency networks. -3. Encourage sustainable economic growth by implementing a demurrage system that discourages hoarding and promotes circulation. +1. Introduce community currencies that reduce economic inequality by ensuring a baseline level of economic participation for all. +2. Foster community connections and strengthen local economies through trust-based currency networks. +3. Promote sustainable economic growth by implementing a demurrage system that discourages hoarding and encourages circulation. 4. Provide a flexible framework for various economic experiments and community-driven initiatives. +5. Empower individuals and communities to have greater control over their economic interactions and monetary systems. ## Key Concepts ### Personal Currencies -In the Circles ecosystem, each individual can mint their own personal currency. This is a unique feature of the protocol, allowing every participant to become an issuer of their own basic income. The Hub contract manages the registration of individuals (referred to as "humans" in the contract) and the issuance of their personal currencies. +In the Circles ecosystem, each individual can mint their own personal currency. This unique feature of the protocol empowers every participant to become an issuer of their own personal Circles. The Hub contract manages both the registration of individuals (referred to as "humans" in the contract) and the issuance of their personal currencies. Key points about personal currencies: -- Each registered human can mint a fixed amount of their personal currency regularly (1 Circle per hour). -- Personal currencies are represented as unique tokens within the ERC1155 multi-token system. -- The minting process is managed by the `personalMint()` function in the Hub contract. +- Each registered human can mint a deterministic amount of their personal currency at a consistent rate of one Circle per hour. +- Minting is retroactive, allowing claims for up to 14 days of past elapsed time. +- The mintable amount is calculated based on the number of complete hours passed since the last issuance of Circles. +- Circles undergo daily demurrage at a rate equivalent to 7% per year. Issuance for past days accounts for this demurrage, ensuring fair distribution over time. (Further details on demurrage are discussed in a later section) +- Personal currencies are represented as unique tokens within the ERC1155 multi-token system, with each token ID derived from the address of the human's avatar. +- The `personalMint()` function in the Hub contract manages the minting process. + +This system ensures a fair, time-based issuance of personal currencies while implementing mechanisms to encourage active participation in the Circles economy. ### Trust Networks From b09fa8b28b7be90560fbc984c1931ea039cc2869 Mon Sep 17 00:00:00 2001 From: Benjamin Bollen Date: Thu, 22 Aug 2024 12:20:38 +0200 Subject: [PATCH 13/46] (docs): introduction:trust refinements --- docs/docs/introduction.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/docs/docs/introduction.md b/docs/docs/introduction.md index 645f156..22f902a 100644 --- a/docs/docs/introduction.md +++ b/docs/docs/introduction.md @@ -37,14 +37,17 @@ This system ensures a fair, time-based issuance of personal currencies while imp Trust is a fundamental concept in the Circles protocol. It allows personal currencies to become valuable and transferable within the network. The trust system is implemented in the Hub contract through the following mechanisms: -- Users can establish trust relationships with other users using the `trust()` function. -- Trust relationships have expiration times, allowing for dynamic trust networks. -- The `isPermittedFlow()` function checks if a transfer is allowed based on the trust relationships between the sender, receiver, and the currency being transferred. +- People can establish trust relationships with other entities (people, organizations, or groups) using the `trust()` function. +- Trust relationships can be set with expiration times, allowing for dynamic trust networks. Alternatively, trust can be established indefinitely by setting the expiration to the maximum possible future time. +- The trust network is leveraged to enable transitive transfers of Circles along paths of trust. The `isPermittedFlow()` function verifies if a transitive transfer is permissible based on the trust relationships between the involved parties and the specific currency being transferred. +- Trust relationships can be established not only between individuals but also between people, organizations, and groups, creating a diverse and interconnected economic ecosystem. Trust networks enable: -- Path-based transactions, where currencies can be exchanged through chains of trust. -- Community-building, as users create economic connections with those they trust. -- A decentralized approach to currency valuation and acceptance. + +- Path-based transactions, where currencies can be exchanged through chains of trust connections. +- Community-building, as users create economic connections with individuals and entities they trust. +- A decentralized approach to currency valuation and acceptance, based on social and organizational relationships rather than centralized authority. +- Flexible economic interactions between various types of actors within the Circles ecosystem. ### Demurrage From 2b13f157e113f0437b6e8434f17ffaacfb59acfc Mon Sep 17 00:00:00 2001 From: Benjamin Bollen Date: Fri, 23 Aug 2024 11:38:04 +0200 Subject: [PATCH 14/46] (docs): intro/ on demrruage second pass --- docs/docs/introduction.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/docs/introduction.md b/docs/docs/introduction.md index 22f902a..6fededf 100644 --- a/docs/docs/introduction.md +++ b/docs/docs/introduction.md @@ -51,13 +51,18 @@ Trust networks enable: ### Demurrage -Demurrage is an economic concept where the value of a currency decreases over time. In Circles, this is implemented to encourage circulation of the currency and discourage hoarding. The Circles contract includes a demurrage system with the following characteristics: +Demurrage is an economic concept where the value of a currency decreases over time. In Circles, this is implemented to encourage circulation of the currency and discourage hoarding. Demurrage further ensures that all times in the future one hour can be issued as one Circle. + +By default all balances and transfer amounts as arguments in functions in the Hub contract are understood as demurraged amounts for the present day. However, to interact with other smart contracts it is often important to be able to interact with a static (ie. not rebalancing) token representation. Therefore Circles also offers a static, inflationary representation of all balances and transfer functions - both at the ERC1155 representation and in the ERC20 representation. + +The Circles contract includes a demurrage system with the following characteristics: - Balances are stored as "discounted balances" that automatically decrease in value over time. -- The `_calculateIssuance()` function in the Circles contract accounts for demurrage when determining how much new currency to mint for a user. +- The `calculateIssuance()` function in the Circles contract accounts for demurrage when determining how much new currency to mint for a person. - Demurrage applies to both personal currencies and group currencies. This system ensures that: + - The currency remains active and circulating within the community. - Long-term storage of wealth is discouraged, promoting a more dynamic economy. - The basic income aspect of the system remains relevant, as users are incentivized to regularly engage with their personal currency. From 448cfc9100f236065abab474a3ec428e86395a45 Mon Sep 17 00:00:00 2001 From: Benjamin Bollen Date: Sat, 24 Aug 2024 15:14:22 +0200 Subject: [PATCH 15/46] (docs): re-polish demurrage section in introduction --- docs/docs/introduction.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/docs/docs/introduction.md b/docs/docs/introduction.md index 6fededf..8af3600 100644 --- a/docs/docs/introduction.md +++ b/docs/docs/introduction.md @@ -51,20 +51,21 @@ Trust networks enable: ### Demurrage -Demurrage is an economic concept where the value of a currency decreases over time. In Circles, this is implemented to encourage circulation of the currency and discourage hoarding. Demurrage further ensures that all times in the future one hour can be issued as one Circle. +Demurrage in currency systems is an economic concept where a cost is associated with holding a currency over time. In Circles, this mechanism is implemented to encourage circulation of the currency and mitigate extreme inequities. Demurrage ensures that at any future point, one hour can be issued as one Circle, while maintaining a maximum total supply of Circles. -By default all balances and transfer amounts as arguments in functions in the Hub contract are understood as demurraged amounts for the present day. However, to interact with other smart contracts it is often important to be able to interact with a static (ie. not rebalancing) token representation. Therefore Circles also offers a static, inflationary representation of all balances and transfer functions - both at the ERC1155 representation and in the ERC20 representation. +In the Hub contract, all balances and transfer amounts used as function arguments are, by default, understood as demurraged amounts for the present day. However, to facilitate interactions with other smart contracts, Circles also offers a static (non-rebalancing) token representation. This static, inflationary representation of all balances and transfer functions is available both in the ERC1155 and ERC20 representations. -The Circles contract includes a demurrage system with the following characteristics: +The Circles contract incorporates a demurrage system with the following key characteristics: - Balances are stored as "discounted balances" that automatically decrease in value over time. -- The `calculateIssuance()` function in the Circles contract accounts for demurrage when determining how much new currency to mint for a person. -- Demurrage applies to both personal currencies and group currencies. +- The `calculateIssuance()` function in the Circles contract factors in demurrage when determining the amount of new currency to mint for an individual. +- Demurrage applies uniformly to both personal currencies and group currencies. This system ensures that: - The currency remains active and circulating within the community. -- Long-term storage of wealth is discouraged, promoting a more dynamic economy. -- The basic income aspect of the system remains relevant, as users are incentivized to regularly engage with their personal currency. +- Circles are issued equitably across individuals and over time. +- A clear unit of account is established, with one Circle representing one hour of an individual's time. +- Circles serves as both a robust store of value and an effective means of exchange. -By combining these key concepts - personal currencies, trust networks, and demurrage - Circles creates a unique economic system that aims to provide a basic income while fostering community connections and encouraging active participation in the local economy. \ No newline at end of file +By integrating these key concepts - personal currencies, trust networks, and demurrage - Circles creates a unique economic system. This system aims to provide a fairly issued, socially-rooted monetary framework that fosters community connections and promotes active participation in the local economy. \ No newline at end of file From ffc0731360c7faa647bfd0a825ca26d66f857b85 Mon Sep 17 00:00:00 2001 From: Benjamin Bollen Date: Sat, 24 Aug 2024 15:27:20 +0200 Subject: [PATCH 16/46] (docs): add note on normal transfer behaviour --- docs/docs/introduction.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/docs/introduction.md b/docs/docs/introduction.md index 8af3600..853e711 100644 --- a/docs/docs/introduction.md +++ b/docs/docs/introduction.md @@ -40,6 +40,7 @@ Trust is a fundamental concept in the Circles protocol. It allows personal curre - People can establish trust relationships with other entities (people, organizations, or groups) using the `trust()` function. - Trust relationships can be set with expiration times, allowing for dynamic trust networks. Alternatively, trust can be established indefinitely by setting the expiration to the maximum possible future time. - The trust network is leveraged to enable transitive transfers of Circles along paths of trust. The `isPermittedFlow()` function verifies if a transitive transfer is permissible based on the trust relationships between the involved parties and the specific currency being transferred. +- Circles still function as a normal token, for explicit `ERC1155:safe(Batch)TransferFrom()` or `ERC20:transfer()` no constraints of the transitive transfer of the trust network apply. - Trust relationships can be established not only between individuals but also between people, organizations, and groups, creating a diverse and interconnected economic ecosystem. Trust networks enable: From 3e8256c01817fbf6664fcd23fe9054700b6b888e Mon Sep 17 00:00:00 2001 From: Benjamin Bollen Date: Fri, 30 Aug 2024 14:55:09 +0100 Subject: [PATCH 17/46] (docs): change preview branch name to v0.3.6-docs --- .github/workflows/deploy-mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/deploy-mkdocs.yml b/.github/workflows/deploy-mkdocs.yml index 837cb85..7604d9e 100644 --- a/.github/workflows/deploy-mkdocs.yml +++ b/.github/workflows/deploy-mkdocs.yml @@ -3,7 +3,7 @@ name: Deploy MkDocs to GitHub Pages on: push: branches: - - 20240821-docs + - v0.3.6-docs jobs: deploy: From 2ced93c51a0850d572538afb4a40fb0c9be19af2 Mon Sep 17 00:00:00 2001 From: Benjamin Bollen Date: Fri, 30 Aug 2024 15:44:03 +0100 Subject: [PATCH 18/46] (docs): total supply and equilibrium of Circles in introduction --- docs/docs/index.md | 1 + docs/docs/introduction.md | 35 ++++++++++++++++++++++++++++++++++- 2 files changed, 35 insertions(+), 1 deletion(-) diff --git a/docs/docs/index.md b/docs/docs/index.md index 2065066..49b72a7 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -8,6 +8,7 @@ Welcome to the Circles documentation. This guide will help you understand the Ci - Brief overview of the Circles project - Purpose and goals of Circles - Key concepts: personal currencies, trust networks, and demurrage + - Total Supply and Equilibrium 2. [Architectural Overview](architecture.md) - High-level system architecture diff --git a/docs/docs/introduction.md b/docs/docs/introduction.md index 853e711..fc4b655 100644 --- a/docs/docs/introduction.md +++ b/docs/docs/introduction.md @@ -58,6 +58,8 @@ In the Hub contract, all balances and transfer amounts used as function argument The Circles contract incorporates a demurrage system with the following key characteristics: +- Circles have a 7% p.a. demurrage cost applied to them in the contracts, rebalancing the amounts. +- Demurrage is applied on an equivalent daily basis, ensuring that during a period of a day balances are not continuously adjusted. - Balances are stored as "discounted balances" that automatically decrease in value over time. - The `calculateIssuance()` function in the Circles contract factors in demurrage when determining the amount of new currency to mint for an individual. - Demurrage applies uniformly to both personal currencies and group currencies. @@ -69,4 +71,35 @@ This system ensures that: - A clear unit of account is established, with one Circle representing one hour of an individual's time. - Circles serves as both a robust store of value and an effective means of exchange. -By integrating these key concepts - personal currencies, trust networks, and demurrage - Circles creates a unique economic system. This system aims to provide a fairly issued, socially-rooted monetary framework that fosters community connections and promotes active participation in the local economy. \ No newline at end of file +By integrating these key concepts - personal currencies, trust networks, and demurrage - Circles creates a unique economic system. This system aims to provide a fairly issued, socially-rooted monetary framework that fosters community connections and promotes active participation in the local economy. + +## Total Supply and Equilibrium + +The Circles protocol implements a unique economic model where the minting of new Circles and the demurrage mechanism work together to create an equilibrium in the total supply. This balance is crucial for maintaining the long-term stability and fairness of the system. + +Key aspects of the total supply mechanism: + +1. Issuance Rate: Each registered human can mint one Circle per hour, which translates to 24 Circles per day or 8760 Circles per year (not accounting for leap years). +2. Demurrage Rate: All Circles undergo a 7% annual demurrage, applied on a daily basis. +3. Equilibrium Point: The issuance and demurrage rates are carefully calibrated so that they balance each other out at a specific point, creating a maximum total supply for each personal currency. +4. Maximum Total Supply Calculation: + - Let x be the maximum total supply in Circles. + - Annual issuance: 8760 Circles + - Annual demurrage: 7% of x + - At equilibrium: 8760 = 0.07x + - Solving for x: x = 8760 / 0.07 = 125,142.86 Circles +5. Dynamic Balance: As new Circles are minted, they contribute to the total supply. However, the demurrage mechanism ensures that the total value of existing Circles decreases over time. This creates a dynamic where the total supply approaches but never exceeds the equilibrium point. +6. Practical Implications: + - For a new participant, it would take approximately 14.3 years of continuous minting to reach the maximum supply, assuming no spending. + - In practice, as people might not mint all their Circles, or they get burnt in usage the total supply of their personal Circles token will fluctuate below this theoretical maximum. + - Each person, organization, group or account can earn Circles from others though in an open economy so anyone's balance can well exceed 125k Circles by holding a variety of different Circles in their wallet. +7. System-wide Effects: While each personal currency has its own maximum supply, the trust network and transferability of Circles create a larger, interconnected economy. The total supply in effect can be thought of as a multiple of 125k CRC for every non-sybil human participating in the network. + +This equilibrium mechanism is crucial for several reasons: + +- It ensures long-term stability in the value of Circles. +- It maintains fairness by preventing early adopters from gaining disproportionate economic power. +- It creates a predictable and sustainable monetary policy for the Circles ecosystem. + +The total supply mechanism is implemented through the interaction of the `personalMint()` function and the demurrage calculations in the Circles contract. The `calculateIssuance()` function takes into account both the time elapsed since the last mint and the demurrage rate to determine the appropriate amount of new Circles to issue, ensuring that the system remains in balance. +By carefully managing the total supply through this issuance and demurrage equilibrium, Circles creates a fair, stable, and sustainable economic system that aligns with its goals of reducing inequality and fostering community connections. \ No newline at end of file From 572b19bb2ad755d24bc00d9d52bd89773bc62485 Mon Sep 17 00:00:00 2001 From: Benjamin Bollen Date: Fri, 30 Aug 2024 15:54:45 +0100 Subject: [PATCH 19/46] (docs): correct duration of mint in total supply --- docs/docs/introduction.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/introduction.md b/docs/docs/introduction.md index fc4b655..7c76d7a 100644 --- a/docs/docs/introduction.md +++ b/docs/docs/introduction.md @@ -90,8 +90,8 @@ Key aspects of the total supply mechanism: - Solving for x: x = 8760 / 0.07 = 125,142.86 Circles 5. Dynamic Balance: As new Circles are minted, they contribute to the total supply. However, the demurrage mechanism ensures that the total value of existing Circles decreases over time. This creates a dynamic where the total supply approaches but never exceeds the equilibrium point. 6. Practical Implications: - - For a new participant, it would take approximately 14.3 years of continuous minting to reach the maximum supply, assuming no spending. - - In practice, as people might not mint all their Circles, or they get burnt in usage the total supply of their personal Circles token will fluctuate below this theoretical maximum. + - For a new participant, after 14 years of continuous minting they would reach 62% of the maximum supply, assuming no spending. To reach 95% of the total supply, 42.79 years of minting is required. + - In practice, as people might not mint all their Circles, or Circles get burnt in usage the total supply of their personal Circles token will fluctuate below this theoretical maximum. - Each person, organization, group or account can earn Circles from others though in an open economy so anyone's balance can well exceed 125k Circles by holding a variety of different Circles in their wallet. 7. System-wide Effects: While each personal currency has its own maximum supply, the trust network and transferability of Circles create a larger, interconnected economy. The total supply in effect can be thought of as a multiple of 125k CRC for every non-sybil human participating in the network. From 1b787c6cec2d3007dbc89ed5a4317c78d827005b Mon Sep 17 00:00:00 2001 From: Benjamin Bollen Date: Fri, 30 Aug 2024 16:06:07 +0100 Subject: [PATCH 20/46] (docs): compactify the conclusion --- docs/docs/introduction.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/introduction.md b/docs/docs/introduction.md index 7c76d7a..fae3ee8 100644 --- a/docs/docs/introduction.md +++ b/docs/docs/introduction.md @@ -101,5 +101,5 @@ This equilibrium mechanism is crucial for several reasons: - It maintains fairness by preventing early adopters from gaining disproportionate economic power. - It creates a predictable and sustainable monetary policy for the Circles ecosystem. -The total supply mechanism is implemented through the interaction of the `personalMint()` function and the demurrage calculations in the Circles contract. The `calculateIssuance()` function takes into account both the time elapsed since the last mint and the demurrage rate to determine the appropriate amount of new Circles to issue, ensuring that the system remains in balance. -By carefully managing the total supply through this issuance and demurrage equilibrium, Circles creates a fair, stable, and sustainable economic system that aligns with its goals of reducing inequality and fostering community connections. \ No newline at end of file +The total supply mechanism is implemented through the interaction of the `personalMint()` function and the demurrage calculations in the Circles contract. +By dynamically managing the total supply through this issuance and demurrage equilibrium, Circles creates a fair, stable, and sustainable economic system that aligns with its goals of reducing inequality and fostering community connections. \ No newline at end of file From 39926392b37d7d67cb452832b50c882e86583a13 Mon Sep 17 00:00:00 2001 From: Benjamin Bollen Date: Fri, 30 Aug 2024 21:08:34 +0100 Subject: [PATCH 21/46] (docs): start of flow matrix in depth explanation up to example --- docs/docs/advanced-topics/consented-flow.md | 54 ++++++ .../path-based-transactions.md | 182 ++++++++++++++++++ docs/docs/advanced-topics/path2.md | 71 +++++++ .../advanced-flow-matrix-trust-graph.png | Bin 0 -> 15048 bytes src/hub/Hub.sol | 2 - 5 files changed, 307 insertions(+), 2 deletions(-) create mode 100644 docs/docs/advanced-topics/consented-flow.md create mode 100644 docs/docs/advanced-topics/path2.md create mode 100644 docs/docs/images/advanced-flow-matrix-trust-graph.png diff --git a/docs/docs/advanced-topics/consented-flow.md b/docs/docs/advanced-topics/consented-flow.md new file mode 100644 index 0000000..1bb5cc1 --- /dev/null +++ b/docs/docs/advanced-topics/consented-flow.md @@ -0,0 +1,54 @@ +# Consented Flow and isPermittedFlow + +## Consented Flow + +Consented flow is an advanced feature in the Circles ecosystem that provides additional control over token transfers. It's an opt-in mechanism that allows people to have more granular control over how their Circles tokens are used in path-based transactions. + +### Key Aspects: + +1. **Opt-in Feature**: By default, avatars don't have consented flow enabled. It can be activated by setting a specific flag in the `advancedUsageFlags` mapping. + +2. **Bilateral Trust**: When enabled, it requires bilateral trust for a transfer to be permitted. This means both the sender and receiver must trust each other. + +3. **Recursive Protection**: To maintain the integrity of the consented flow system, receivers must also have consented flow enabled for the transfer to be permitted. + +## isPermittedFlow Function + +The `isPermittedFlow` function is a crucial component in enforcing trust relationships and consented flow rules. It determines whether a transfer between two avatars is allowed. + +### Function Signature: +```solidity +function isPermittedFlow(address _from, address _to, address _circlesAvatar) public view returns (bool) +``` + +### Parameters: +- `_from`: The sender's address +- `_to`: The receiver's address +- `_circlesAvatar`: The address of the Circles avatar whose tokens are being transferred + +### Behavior: + +1. **Basic Trust Check**: + - Always checks if the receiver trusts the Circles being sent (`_to` trusts `_circlesAvatar`). + - If this basic trust doesn't exist, the flow is not permitted. + +2. **Consented Flow Check**: + - If the sender has consented flow enabled (checked via `advancedUsageFlags`), additional checks are performed: + a. The sender must trust the receiver (`_from` trusts `_to`). + b. The receiver must have consented flow enabled. + +3. **Return Value**: + - Returns `true` if the flow is permitted based on the above checks. + - Returns `false` otherwise. + +### Implications: + +- **Enhanced Control**: Allows people to have more control over how their tokens are used in complex transactions. +- **Increased Trust Requirements**: When enabled, it requires mutual trust between transaction participants. +- **Potential Complexity**: While offering more control, it may increase the complexity of finding valid transaction paths. + +## Use in the Circles Ecosystem + +The `isPermittedFlow` function is used in various parts of the Circles contract, particularly in path-based transactions and group mints. It ensures that all transfers, whether direct or as part of a complex path, adhere to the trust relationships and consented flow rules set by the participants. + +By providing this additional layer of control, Circles allows for a more nuanced and trust-centric economy, where people can have fine-grained control over their participation in the network's flow of value. \ No newline at end of file diff --git a/docs/docs/advanced-topics/path-based-transactions.md b/docs/docs/advanced-topics/path-based-transactions.md index e69de29..ea57654 100644 --- a/docs/docs/advanced-topics/path-based-transactions.md +++ b/docs/docs/advanced-topics/path-based-transactions.md @@ -0,0 +1,182 @@ +# Path-based Transactions and Flow Matrices + +In the Circles ecosystem, path-based transactions enable the transfer of Circles tokens between people who don't directly trust each other. This system uses flow matrices to represent and validate these multi-hop transactions. + +## Concept Overview + +Path-based transactions allow Circles to be transferred along a path of trust relationships. Instead of requiring direct trust between the sender and receiver, the system finds a path through the trust network where each step involves a trusted relationship. + +## Flow Matrices + +Flow matrices are the mathematical representation of these path-based transactions. They describe the movement of Circles tokens through the network for a given transaction (or a batch of transactions). + +### Structure of a Flow Matrix + +A flow matrix consists of the following components: + +1. **Flow Vertices**: An ordered list of avatar addresses that the transaction path touches. This includes any avatar that sends, receives or whose Circles are used in any of the flow edges. These can be humans, organizations or groups, but must be registered. +2. **Flow Edges**: A path consists of a set of flow edges. This is expressed as an array of `FlowEdges`, each representing a transfer of a specific (personal or group) Circles type and amount between two vertices. These flow edges are applied in the order given and the order of the coordinates must match that of the flow edges. A `FlowEdge` therefore is a structure that specifies: + - `amount`: The amount of tokens being transferred (uint192) in this edge. + - `streamSinkId`: To perform the `ERC1155:onERC1155Received()` call, the path needs to identify which edges are terminal flow edges. Therefore this references for all terminal edges a stream identifier (and is 0 for non-terminal edges; >0 for terminal edges). +3. **Coordinates**: Packed data representing triplets of indices within the flow vertices array: for each flow edge the coordinates must provide a triplet `(uint16, uint16, uint16)`, referencing the addresses of `(Circles-to-send, sender, receiver)` read from the flow vertices array. The coordinates are input as `bytes` packed explicitly per 16 bits to avoid zero-padding for 256bit word length. +4. **Streams**: A stream represents the actual intent of a sender to send an amount of Circles to a receiver - without specifying which Circles to send or over which path, simply that the receiver only ever receives Circles they trust. A stream specifies a `sourceCoordinate` as the index of the source (or sender) in the flow vertices array, an array of the `flowEdgeIds` to cross-reference with the flow edges the correct terminal edges of this stream; and `bytes data` that will be sent to the receiver of the stream in the acceptance call. A flow matrix can have: + - zero streams provided: All edges combined must form a closed path where no sender and no receiver nett-receives or nett-sends an amount of Circles. This can be used to reorganise the balances of Circles across the graph. + - one stream provided: The flow matrix represents the path of a single intended transfer between a sender and receiver. + - two or more streams: The flow matrix represents a batch of intents of multiple senders to send Circles to receivers as a single path settled (while still performing the acceptance checks for each stream's receiver). + +### An example of a flow matrix + +Let's illustrate a flow matrix and streams with an example. Let's assume we have the following avatars (only humans). +``` +Avatars (Flow Vertices): +A: Alice +B: Bob +C: Charlie +D: David +E: Eva +``` + +Let's assume Alice wants to send 3 CRC to David, and 5 CRC to Eva. Bob wants to send 4 CRC to David as well. Let's assume they have the following trust graph among them. + +![Docs directory image](/images/advanced-flow-matrix-trust-graph.png "Trust graph") + +We can assume that everyone already holds some balances of the tokens of the people they trust. A possible path could look like the following: + +```sh ++----------+-----+-----+-----+-----+-----+ +| | A | B | C | D | E | ++----------+-----+-----+-----+-----+-----+ +| A-B | -8A | 8A | | | | ++----------+-----+-----+-----+-----+-----+ +| B-D (T2) | | -4C | | 4C | | ++----------+-----+-----+-----+-----+-----+ +| B-C | | -5B | 5B | | | ++----------+-----+-----+-----+-----+-----+ +| B-D (T1) | | -3C | | 3C | | ++----------+-----+-----+-----+-----+-----+ +| C-E (T3) | | | -5D | | 5D | ++==========+=====+=====+=====+=====+=====+ +| Net Flow | -8 | -4 | 0 | 7 | 5 | ++==========+=====+=====+=====+=====+=====+ +| Stream 1 | -3 | | | 3 | | ++----------+-----+-----+-----+-----+-----+ +| Stream 2 | | -4 | | 4 | | ++----------+-----+-----+-----+-----+-----+ +| Stream 3 | -5 | | | | 5 | ++----------+-----+-----+-----+-----+-----+ +``` + +In this diagram, positive values represent incoming tokens and negative values represent outgoing tokens; the letters `(A, B, C, D)` represent the type of Circles tokens being transfered; and streams don't specify token types, only amounts. + +#### Flow edges Explanation + +Note: flow edge arrays and flow vertices arrays are indexed from 0. Streams are explicitly indexed from 1, because we reserve 0 for not-referencing a stream. (And Markdown will not enumerate from 0, so subtract 1 here): + +1. A-B: Alice sends 8 of her own Circles (A) to Bob. + - `(amount = 8, streamSinkId = 0)` + - coordinates `(A, A, B)` +2. B-D: Bob sends 4 of Charlie's Circles (C) to David. + - `(amount = 4, streamSinkId = 2)` + - coordinates `(C, B, D)` +3. B-C: Bob sends 5 of his own Circles (B) to Charlie. + - `(amount = 5, streamSinkId = 0)` + - coordinates `(B, B, C)` +4. B-D: Bob sends 3 of Charlie's Circles (C) to David. + - `(amount = 3, streamSinkId = 1)` + - coordinates `(C, D, D)` +5. C-E: Charlie sends 5 of David's Circles (D) to Eva. + - `(amount = 5, streamSinkId = 3)` + - coordinates `(D, C, E)` + +#### Stream Explanation + +- Stream 1: Alice intends to send 3 Circles from her to David. + - `sourceCoordinate = 0` (Alice) + - `flowEdgeIds = [3]` (fourth edge B-D is the single terminal edge for stream 1) + - `data` (some message Alice sends along to David) +- Stream 2: Bob intends to send 4 Circles to David. + - `sourceCoordinate = 1` (Bob) + - `flowEdgeIds = [1]` (second edge B-D is single terminal edge for stream 2) + - `data` +- Stream 3: Alice intends to send 5 Circles to Eva. + - `sourceCoorindate = 0` + - `flowEdgeIds = [4]` (fifth edge C-E terimates stream 3) + - `data` + +#### Net Flow and consistency check + +The net flow is not sent as input to the contracts, rather it is included in the diagram to illustrate the consistency check that the contract performs. +For an explicit path of flow edges to be a valid solution to the set of intents expressed in the streams, it must hold that +for every vertex the sum over all flow edges (modulo Circles Id) must equal the sum over all streams (ie. summing the columns). + +## Technical Implementation + +The `Hub` contract implements path-based transactions through the `operateFlowMatrix` function. Let's break down its key components: + +### Function Signature + +```solidity +function operateFlowMatrix( + address[] calldata _flowVertices, + FlowEdge[] calldata _flow, + Stream[] calldata _streams, + bytes calldata _packedCoordinates +) external nonReentrant(0) +``` + +### Key Steps in Processing + +1. **Unpacking Coordinates**: + The packed coordinates are unpacked into an array of `uint16` values. + +2. **Verification**: + - The flow matrix is verified for correctness using `_verifyFlowMatrix`. + - This checks that all vertices are valid avatars and that trust relationships are respected. + +3. **Effecting Transfers**: + - The actual transfers are processed using `_effectPathTransfers`. + - This function handles both regular transfers and group mints when applicable. + +4. **Acceptance Checks**: + - The `_callAcceptanceChecks` function performs necessary checks for each stream in the transaction. + +5. **Flow Matching**: + - The netted flows from the streams and the matrix are compared to ensure they match. + +## Key Functions + +### _verifyFlowMatrix + +This function performs crucial checks: +- Ensures all vertices are registered avatars. +- Verifies that receivers trust the Circles being sent. +- Calculates the netted flow for each vertex. + +### _effectPathTransfers + +This function: +- Processes each flow edge, either as a transfer or a group mint. +- Keeps track of stream definitions and ensures their correctness. + +### _callAcceptanceChecks + +This function: +- Calls acceptance checks for each stream. +- Emits `StreamCompleted` events for successful transfers. + +## Trust and Permissions + +The system uses two key functions to manage trust and permissions: + +1. `isTrusted(address _truster, address _trustee)`: Checks if the truster trusts the trustee. +2. `isPermittedFlow(address _to, address _circlesAvatar)`: Ensures both that the receiver trusts the Circles being sent and that the Circles avatar trusts the receiver. + +## Challenges and Considerations + +1. **Complexity**: Path-based transactions involve multiple checks and operations, making them computationally intensive. +2. **Gas Costs**: The complexity of these transactions can lead to higher gas costs, which needs to be balanced against the benefits of the system. +3. **Trust Dynamics**: The system relies on up-to-date trust relationships, which can change over time. + +## Conclusion + +Path-based transactions and flow matrices form the backbone of Circles' unique approach to creating a trust-based economy. By enabling multi-hop transfers through trust networks, Circles can facilitate transactions between individuals who don't directly trust each other, expanding the utility and reach of the system. \ No newline at end of file diff --git a/docs/docs/advanced-topics/path2.md b/docs/docs/advanced-topics/path2.md new file mode 100644 index 0000000..941e955 --- /dev/null +++ b/docs/docs/advanced-topics/path2.md @@ -0,0 +1,71 @@ +# Path-based Transactions and Flow Matrices + +In the Circles ecosystem, path-based transactions enable the transfer of Circles tokens between people who don't directly trust each other. This system utilizes flow matrices to represent and validate these complex transactions. + +## Flow Matrix Structure + +A flow matrix consists of the following components: + +1. **Flow Vertices**: An ordered list of avatar addresses that the transaction path touches. +2. **Flow Edges**: An array of structures, each representing a transfer of Circles tokens between two vertices. +3. **Streams**: Structures that define the terminal points of a transaction, including source, sink, and associated data. +4. **Coordinates**: Packed data representing the indices of Circles identifiers, senders, and receivers within the flow vertices array. + +## Transaction Process + +The `operateFlowMatrix` function in the Hub contract orchestrates path-based transactions: + +1. **Unpacking Coordinates**: The packed coordinates are expanded into an array of uint16 values. +2. **Operator Authorization**: Ensures the operator is approved for all source addresses in the streams. +3. **Flow Matrix Verification**: Checks the correctness of the flow matrix, including: + - Well-definedness of the matrix + - Registration of all entities + - Adherence to trust relationships + - Calculation of netted flows + +4. **Path Transfers**: Executes the individual transfers defined by the flow edges. +5. **Acceptance Checks**: Calls acceptance checks for the streams and calculates the netted flows. +6. **Flow Matching**: Ensures the netted flows from the matrix and streams match. + +## Key Functions + +### _verifyFlowMatrix + +This function performs crucial checks on the flow matrix: + +- Validates the length and order of flow vertices +- Ensures all vertices are registered avatars +- Verifies that each flow edge respects trust relationships +- Calculates the netted flow for each vertex + +### _effectPathTransfers + +Executes the actual transfers defined by the flow edges: + +- Handles both regular transfers and group mints +- Verifies the correct definition of streams +- Updates balances without triggering acceptance checks for intermediate transfers + +### _callAcceptanceChecks + +Processes the final streams of the transaction: + +- Calculates the total amounts for each stream +- Performs acceptance checks for the receiving addresses +- Emits `StreamCompleted` events for each successful stream + +## Optimizations and Constraints + +- Uses packed coordinates to reduce gas costs +- Implements checks to prevent common errors and vulnerabilities +- Utilizes a non-reentrant modifier to prevent reentrancy attacks + +## Implications for the Circles Ecosystem + +Path-based transactions allow for: + +- Increased liquidity within the Circles network +- Facilitation of trades between people without direct trust relationships +- Complex, multi-step transactions executed atomically + +This system forms the backbone of Circles' unique approach to creating a decentralized basic income, enabling fluid value transfer while respecting individual trust boundaries. \ No newline at end of file diff --git a/docs/docs/images/advanced-flow-matrix-trust-graph.png b/docs/docs/images/advanced-flow-matrix-trust-graph.png new file mode 100644 index 0000000000000000000000000000000000000000..3d0fc5aa3a6cfd3962585c7af9765e79f0297ffe GIT binary patch literal 15048 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 literal 0 HcmV?d00001 diff --git a/src/hub/Hub.sol b/src/hub/Hub.sol index 3f77bc3..843ddea 100644 --- a/src/hub/Hub.sol +++ b/src/hub/Hub.sol @@ -538,8 +538,6 @@ contract Hub is Circles, TypeDefinitions, IHubErrors { return erc20Wrapper; } - // todo: if we have space, possibly have a wrapBatch function - function operateFlowMatrix( address[] calldata _flowVertices, FlowEdge[] calldata _flow, From 0c0f33167787ff45dea2da3087c1011513a554de Mon Sep 17 00:00:00 2001 From: Benjamin Bollen Date: Fri, 30 Aug 2024 21:53:41 +0100 Subject: [PATCH 22/46] (docs): net flow and consistency check of flow matrix --- docs/docs/advanced-topics/path-based-transactions.md | 12 +++++++++++- src/hub/TypeDefinitions.sol | 2 +- 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/docs/advanced-topics/path-based-transactions.md b/docs/docs/advanced-topics/path-based-transactions.md index ea57654..1a11d73 100644 --- a/docs/docs/advanced-topics/path-based-transactions.md +++ b/docs/docs/advanced-topics/path-based-transactions.md @@ -103,12 +103,22 @@ Note: flow edge arrays and flow vertices arrays are indexed from 0. Streams are - `flowEdgeIds = [4]` (fifth edge C-E terimates stream 3) - `data` -#### Net Flow and consistency check +## Net Flow and Consistency Check The net flow is not sent as input to the contracts, rather it is included in the diagram to illustrate the consistency check that the contract performs. For an explicit path of flow edges to be a valid solution to the set of intents expressed in the streams, it must hold that for every vertex the sum over all flow edges (modulo Circles Id) must equal the sum over all streams (ie. summing the columns). +Streams themselves don't specify an amount though - both to compactify the representation but also to not over-determine the representation. Instead it is checked that for each stream: + +- all the terminal edges that reference this stream have the same receiver. +- that each stream lists their terminal flow edge ids in ascending order. +- and that the count of terminal edges that reference a stream, matches the length of the `flowEdgeIds` array of that stream. + +By cross-referencing, and checking consistency we ensure that we can use the sum of the terminal edges for a stream as the amount intended to send by that stream. + +In our example, all streams only had one terminal flow edge, but in general a flow matrix can have multiple terminal flow edges for a single stream. + ## Technical Implementation The `Hub` contract implements path-based transactions through the `operateFlowMatrix` function. Let's break down its key components: diff --git a/src/hub/TypeDefinitions.sol b/src/hub/TypeDefinitions.sol index ba5d4ce..79665bf 100644 --- a/src/hub/TypeDefinitions.sol +++ b/src/hub/TypeDefinitions.sol @@ -17,7 +17,7 @@ contract TypeDefinitions { struct FlowEdge { uint16 streamSinkId; - uint192 amount; // todo: set this to uint192 (align with demurrage), and leave it to compiler to pad + uint192 amount; } struct Stream { From 2af3678f872b6b3a773960012735e422e5f3d7f9 Mon Sep 17 00:00:00 2001 From: Benjamin Bollen Date: Fri, 30 Aug 2024 23:11:17 +0100 Subject: [PATCH 23/46] (docs): try local image for pushing img to server --- .../advanced-flow-matrix-trust-graph.png | Bin .../docs/advanced-topics/path-based-transactions.md | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) rename docs/docs/{images => advanced-topics}/advanced-flow-matrix-trust-graph.png (100%) diff --git a/docs/docs/images/advanced-flow-matrix-trust-graph.png b/docs/docs/advanced-topics/advanced-flow-matrix-trust-graph.png similarity index 100% rename from docs/docs/images/advanced-flow-matrix-trust-graph.png rename to docs/docs/advanced-topics/advanced-flow-matrix-trust-graph.png diff --git a/docs/docs/advanced-topics/path-based-transactions.md b/docs/docs/advanced-topics/path-based-transactions.md index 1a11d73..59c10e6 100644 --- a/docs/docs/advanced-topics/path-based-transactions.md +++ b/docs/docs/advanced-topics/path-based-transactions.md @@ -38,7 +38,7 @@ E: Eva Let's assume Alice wants to send 3 CRC to David, and 5 CRC to Eva. Bob wants to send 4 CRC to David as well. Let's assume they have the following trust graph among them. -![Docs directory image](/images/advanced-flow-matrix-trust-graph.png "Trust graph") +![Local image](./advanced-flow-matrix-trust-graph.png "Trust graph") We can assume that everyone already holds some balances of the tokens of the people they trust. A possible path could look like the following: From 68ebe964dace1e0f5768e55578858a65eabe7f0e Mon Sep 17 00:00:00 2001 From: Benjamin Bollen Date: Fri, 30 Aug 2024 23:53:32 +0100 Subject: [PATCH 24/46] (docs): change image for brand-themed svg --- .../advanced-flow-matrix-trust-graph.png | Bin 15048 -> 0 bytes .../advanced-topics/path-based-transactions.md | 8 ++++---- 2 files changed, 4 insertions(+), 4 deletions(-) delete mode 100644 docs/docs/advanced-topics/advanced-flow-matrix-trust-graph.png diff --git a/docs/docs/advanced-topics/advanced-flow-matrix-trust-graph.png b/docs/docs/advanced-topics/advanced-flow-matrix-trust-graph.png deleted file mode 100644 index 3d0fc5aa3a6cfd3962585c7af9765e79f0297ffe..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 15048 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 diff --git a/docs/docs/advanced-topics/path-based-transactions.md b/docs/docs/advanced-topics/path-based-transactions.md index 59c10e6..9a22392 100644 --- a/docs/docs/advanced-topics/path-based-transactions.md +++ b/docs/docs/advanced-topics/path-based-transactions.md @@ -8,7 +8,7 @@ Path-based transactions allow Circles to be transferred along a path of trust re ## Flow Matrices -Flow matrices are the mathematical representation of these path-based transactions. They describe the movement of Circles tokens through the network for a given transaction (or a batch of transactions). +Flow matrices are structured representations for these path-based transactions. They describe the movement of Circles tokens through the network for a given transaction (or a batch of transactions). ### Structure of a Flow Matrix @@ -22,7 +22,7 @@ A flow matrix consists of the following components: 4. **Streams**: A stream represents the actual intent of a sender to send an amount of Circles to a receiver - without specifying which Circles to send or over which path, simply that the receiver only ever receives Circles they trust. A stream specifies a `sourceCoordinate` as the index of the source (or sender) in the flow vertices array, an array of the `flowEdgeIds` to cross-reference with the flow edges the correct terminal edges of this stream; and `bytes data` that will be sent to the receiver of the stream in the acceptance call. A flow matrix can have: - zero streams provided: All edges combined must form a closed path where no sender and no receiver nett-receives or nett-sends an amount of Circles. This can be used to reorganise the balances of Circles across the graph. - one stream provided: The flow matrix represents the path of a single intended transfer between a sender and receiver. - - two or more streams: The flow matrix represents a batch of intents of multiple senders to send Circles to receivers as a single path settled (while still performing the acceptance checks for each stream's receiver). + - two or more streams: The flow matrix represents a batch of intents of multiple senders to send Circles to receivers, and they get settled on-chain as single path (while still performing the acceptance checks for each stream's receiver). ### An example of a flow matrix @@ -36,9 +36,9 @@ D: David E: Eva ``` -Let's assume Alice wants to send 3 CRC to David, and 5 CRC to Eva. Bob wants to send 4 CRC to David as well. Let's assume they have the following trust graph among them. +Let's assume Alice wants to send 3 CRC to David, and 5 CRC to Eva. Bob wants to send 4 CRC to David as well. Let's assume they have the following trust graph among them (where the arrow means "trusts"): -![Local image](./advanced-flow-matrix-trust-graph.png "Trust graph") +Circles Trust Graph We can assume that everyone already holds some balances of the tokens of the people they trust. A possible path could look like the following: From 8d825b9fec31299f799f64554916787d3a772931 Mon Sep 17 00:00:00 2001 From: Benjamin Bollen Date: Sat, 31 Aug 2024 00:31:47 +0100 Subject: [PATCH 25/46] (docs): path transfers, section on group mint along path --- .../path-based-transactions.md | 97 ++++++++++++++----- 1 file changed, 71 insertions(+), 26 deletions(-) diff --git a/docs/docs/advanced-topics/path-based-transactions.md b/docs/docs/advanced-topics/path-based-transactions.md index 9a22392..7a516fd 100644 --- a/docs/docs/advanced-topics/path-based-transactions.md +++ b/docs/docs/advanced-topics/path-based-transactions.md @@ -135,44 +135,89 @@ function operateFlowMatrix( ``` ### Key Steps in Processing +The function performs several crucial steps: -1. **Unpacking Coordinates**: - The packed coordinates are unpacked into an array of `uint16` values. +1. **Unpacking Coordinates**: The packed coordinates are unpacked into an array of uint16 values. +2. **Authorization Check**: Ensures all senders (as listed in the streams) have authorized the operator calling this function (with `ERC1155::setApprovalForAll()`). +3. **Flow Matrix Verification**: Checks the correctness of the flow matrix, including trust relationships and avatar registrations. +4. **Path Transfers**: Executes the individual transfers defined by the flow edges. +5. **Acceptance Checks**: Calls acceptance checks for the streams and calculates the netted flows. +6. **Flow Matching**: Ensures the netted flows from streams match the verified flow matrix. -2. **Verification**: - - The flow matrix is verified for correctness using `_verifyFlowMatrix`. - - This checks that all vertices are valid avatars and that trust relationships are respected. +The important internal functions that accomplish these above steps are the following: -3. **Effecting Transfers**: - - The actual transfers are processed using `_effectPathTransfers`. - - This function handles both regular transfers and group mints when applicable. +- **_verifyFlowMatrix** + - Ensures all vertices are registered avatars. + - Verifies that receivers trust the Circles being sent. + - Calculates the netted flow for each vertex. +- **_effectPathTransfers** + - Processes each flow edge, either as a transfer or a group mint. + - Keeps track of stream definitions and ensures their correctness. +- **_callAcceptanceChecks** + - Calls acceptance checks for each stream. + - Emits `StreamCompleted` events for successful "effective transfers" for each stream. -4. **Acceptance Checks**: - - The `_callAcceptanceChecks` function performs necessary checks for each stream in the transaction. +## Minting Group Circles along a Path -5. **Flow Matching**: - - The netted flows from the streams and the matrix are compared to ensure they match. +The Circles ecosystem allows for the minting of group Circles as part of path-based transactions. This feature enables dynamic creation of group tokens within complex transfer paths, enhancing the liquidity and utility of the system. -## Key Functions +### How Group Minting Works in Path Transactions -### _verifyFlowMatrix +1. **Flow Edge to Group Avatar**: When a flow edge in the path has a receiver that is a registered group avatar, the system treats this as a group minting operation instead of a regular transfer. -This function performs crucial checks: -- Ensures all vertices are registered avatars. -- Verifies that receivers trust the Circles being sent. -- Calculates the netted flow for each vertex. +2. **Collateral for Minting**: The tokens being sent to the group in this flow edge are used as collateral for minting new group Circles. -### _effectPathTransfers +3. **Automatic Minting**: The `_groupMint` function is called internally, creating new group Circles based on the collateral provided. -This function: -- Processes each flow edge, either as a transfer or a group mint. -- Keeps track of stream definitions and ensures their correctness. +4. **Mint Policies**: Each group has an associated mint policy contract that determines the rules for minting new group Circles. This policy is consulted during the minting process. -### _callAcceptanceChecks +### Implementation Details -This function: -- Calls acceptance checks for each stream. -- Emits `StreamCompleted` events for successful transfers. +The `_effectPathTransfers` function in the Hub contract handles the minting of group Circles within a path: + +```solidity +if (!isGroup(to)) { + // Regular transfer for non-group receivers + _update( + _flowVertices[_coordinates[index + 1]], // sender + to, + ids, + amounts + ); +} else { + // Group minting for group receivers + _groupMint( + _flowVertices[_coordinates[index + 1]], // sender + to, // receiver + to, // group + ids, // collateral + amounts, // amounts + "", // No additional data for path-based group mints + false // Indicate this is part of a path, not an explicit call + ); +} +``` + +### Key Aspects of Group Minting in Paths + +1. **Implicit Minting**: Group minting occurs automatically when a group is the receiver in a flow edge, without requiring explicit minting instructions. + +2. **Collateral Transfer**: The tokens sent to the group are transferred to the group's treasury contract as collateral. + +3. **Mint Policy Checks**: The group's mint policy is consulted to ensure the minting operation is valid according to the group's rules. + +4. **No Additional Data**: When minting occurs as part of a path, no additional data is passed to the mint policy (unlike in explicit group mint calls when the caller can pass data to the group mint policy). + +5. **Trust Relationships**: The system checks that the group trusts the collateral being provided (i.e., the actual tokens being sent, not the sender of the flow edge). + +### Implications and Benefits + +- **Dynamic Token Creation**: Allows for the creation of new group tokens as part of complex transfer paths. +- **Increased Liquidity**: Facilitates the conversion from personal (or group Circles) into (other) group Circles within a single flow edge. Group Circles are likely to be trusted by more and hence accepted by more, reducing the number of hops in the graph a path needs to include to reach far away recipients. +- **Flexible Economic Structures**: Enables more complex economic interactions and structures within the Circles ecosystem. +- **Seamless Integration**: Group minting is seamlessly integrated into the path-based transaction system, requiring no special handling from the transaction initiator. + +This feature significantly enhances the capabilities of path-based transactions in Circles, allowing for dynamic and flexible token interactions that can adapt to the needs of the network and its participants. ## Trust and Permissions From e5749ec701668c5db965fc9529e032729fc208d5 Mon Sep 17 00:00:00 2001 From: Benjamin Bollen Date: Sat, 31 Aug 2024 01:08:03 +0100 Subject: [PATCH 26/46] (docs): consented flow and conclusion for path based transfers --- .../path-based-transactions.md | 73 ++++++++++++++++--- src/hub/Hub.sol | 12 +-- 2 files changed, 69 insertions(+), 16 deletions(-) diff --git a/docs/docs/advanced-topics/path-based-transactions.md b/docs/docs/advanced-topics/path-based-transactions.md index 7a516fd..cb30790 100644 --- a/docs/docs/advanced-topics/path-based-transactions.md +++ b/docs/docs/advanced-topics/path-based-transactions.md @@ -213,25 +213,78 @@ if (!isGroup(to)) { ### Implications and Benefits - **Dynamic Token Creation**: Allows for the creation of new group tokens as part of complex transfer paths. -- **Increased Liquidity**: Facilitates the conversion from personal (or group Circles) into (other) group Circles within a single flow edge. Group Circles are likely to be trusted by more and hence accepted by more, reducing the number of hops in the graph a path needs to include to reach far away recipients. +- **Increased Liquidity**: Facilitates the conversion from personal (or group Circles) into (other) group Circles within a single flow edge. Group Circles are likely to be trusted by more and hence accepted by more, reducing the number of hops in the graph a path needs to traverse to reach far away recipients. - **Flexible Economic Structures**: Enables more complex economic interactions and structures within the Circles ecosystem. - **Seamless Integration**: Group minting is seamlessly integrated into the path-based transaction system, requiring no special handling from the transaction initiator. This feature significantly enhances the capabilities of path-based transactions in Circles, allowing for dynamic and flexible token interactions that can adapt to the needs of the network and its participants. +[Previous content remains unchanged] -## Trust and Permissions +## Trust and Consented Flow -The system uses two key functions to manage trust and permissions: +### Trust Implies a Flow Edge -1. `isTrusted(address _truster, address _trustee)`: Checks if the truster trusts the trustee. -2. `isPermittedFlow(address _to, address _circlesAvatar)`: Ensures both that the receiver trusts the Circles being sent and that the Circles avatar trusts the receiver. +The default behavior for Circles is such that if one avatar trusts another avatar, they attest that: -## Challenges and Considerations +1. **Token Acceptance**: They are willing to accept the trusted avatar's personal Circles tokens as payment. -1. **Complexity**: Path-based transactions involve multiple checks and operations, making them computationally intensive. -2. **Gas Costs**: The complexity of these transactions can lead to higher gas costs, which needs to be balanced against the benefits of the system. -3. **Trust Dynamics**: The system relies on up-to-date trust relationships, which can change over time. +2. **Implicit Flow Permission**: They allow their balance of the trusted avatar's tokens to be used in path-based transactions, potentially without their direct involvement in each transaction. + +3. **Network Facilitation**: They contribute to the overall liquidity and connectivity of the Circles network by creating a potential path for transactions. + +4. **Value Recognition**: They recognize some form of value or merit in the trusted avatar's economic activity or contribution to the community. + +5. **Transitive Trust**: While not directly trusting the entire network of the trusted avatar, they implicitly allow for multi-hop transactions that may involve avatars further down the trust chain. + +6. **Time-Bound Relationship**: Trust relationships have an expiry time, allowing for dynamic changes in the trust network over time. + +This default behavior enables the Circles system to create paths for transactions between avatars who may not directly trust each other, facilitating a more interconnected and fluid economy. + +### Consented Flow + +Consented flow is an advanced feature in the Circles ecosystem that provides additional control over path-based transfers. It's an opt-in mechanism that allows people (and groups or organizations) to have more granular control over how their Circles tokens are used in path-based transactions. + +#### Key Aspects of Consented Flow + +1. **Opt-In Feature**: Avatars must explicitly enable consented flow by setting an advanced usage flag. +2. **Bidirectional Trust Requirement**: When consented flow is enabled, a valid flow edge requires: + - The receiver trusts the Circles avatar of the tokens being sent (standard requirement). + - The sender trusts the receiver. + - The receiver must also have consented flow enabled. +3. **Recursive Protection**: The requirement for the receiver to also have consented flow enabled ensures that the protection extends through multiple hops in a transaction path, for those flow edges that enter a region of consented flow. +4. **Enhanced Control**: Provides more precise control over how an avatar's tokens can be used in the network, potentially reducing unexpected or undesired token movements. +5. **Impact on Liquidity**: While offering more security, consented flow may make some transactions more challenging to complete, as it requires more tightly-knit web of trust relationships. + +#### Behaviour Details + +The `isPermittedFlow` function in the Hub contract implements the logic for checking whether a flow edge is permitted (with or without consented flow enabled for the sender): + +1. **Basic Trust Check**: + - Always checks if the receiver trusts the Circles being sent. + - If this basic trust doesn't exist, the flow is never permitted. +2. **Consented Flow Check**: + - If the sender has consented flow enabled (checked via `advancedUsageFlags`), additional checks are performed: + 1. The sender must trust the receiver. + 2. The receiver must also have consented flow enabled. +3. **Return Value**: + - Returns `true` if the flow is permitted based on the above checks. + - Returns `false` otherwise. + +#### Implications of Consented Flow + +1. **Enhanced Security**: Provides an additional layer of control for avatars concerned about unauthorized use of their tokens. +2. **Potential Complexity**: May increase the complexity of finding valid paths for transactions, especially if a sender with consented flow is trying to send tokens to a receiver outside the consented flow perimeter (ie. a receiver without consented flow enabled). The sender may be required to sandwich their path-transfer between disabling and re-enabling consented flow for themselves, so that their path can start from outside the local consented flow perimeter. +3. **Network Dynamics**: Could influence the overall structure and behavior of the Circles trust network, potentially leading to more tightly-knit, high-trust sub-networks. +4. **Flexibility**: Allows for different trust models within the same network, catering to varying preferences for control and openness. + +Consented flow represents an advanced usage of the Circles system, allowing for a more nuanced approach to trust and token flow within the network. It balances the need for additional control with the system's goal of creating a fluid, interconnected economy. ## Conclusion -Path-based transactions and flow matrices form the backbone of Circles' unique approach to creating a trust-based economy. By enabling multi-hop transfers through trust networks, Circles can facilitate transactions between individuals who don't directly trust each other, expanding the utility and reach of the system. \ No newline at end of file +The Circles ecosystem implements path-based transactions using flow matrices to enable multi-hop transfers of personal and group tokens. This system allows for: + +1. Complex transfers between indirectly connected avatars +2. Automatic group token minting within transaction paths +3. Flexible trust models, including opt-in consented flow for enhanced control + +These mechanisms collectively form a decentralized currency network capable of supporting diverse economic interactions and trust relationships. The technical infrastructure provides a foundation for a social currency system that can adapt to various community needs and transaction complexities. \ No newline at end of file diff --git a/src/hub/Hub.sol b/src/hub/Hub.sol index 843ddea..b99a4a9 100644 --- a/src/hub/Hub.sol +++ b/src/hub/Hub.sol @@ -636,15 +636,15 @@ contract Hub is Circles, TypeDefinitions, IHubErrors { * @return permitted true if the flow is permitted, false otherwise */ function isPermittedFlow(address _from, address _to, address _circlesAvatar) public view returns (bool) { - // if receiver does not trust the Circles being sent, then the flow is not permitted regardless + // Check if receiver trusts the Circles being sent if (uint256(trustMarkers[_to][_circlesAvatar].expiry) < block.timestamp) return false; - // if the advanced usage flag does not enables consented flow, - // then the uni-directional trust is sufficient, ie. no consented flow applies for sender + + // Check if sender has enabled consented flow if (advancedUsageFlags[_from] & ADVANCED_FLAG_ENABLE_CONSENTEDFLOW == bytes32(0)) { - return true; + return true; // If not enabled, standard trust is sufficient } - // however, recursive consented flow also requires sender to trust the receiver - // and for that receiver themselves to have consented flow enabled + // For consented flow, check sender trusts receiver, + // and receiver has consented flow enabled too return ( uint256(trustMarkers[_from][_to].expiry) >= block.timestamp && advancedUsageFlags[_to] & ADVANCED_FLAG_ENABLE_CONSENTEDFLOW != bytes32(0) From 6cdab5dd6ec85839ccd57da45bfea491c9b65f89 Mon Sep 17 00:00:00 2001 From: Benjamin Bollen Date: Sat, 31 Aug 2024 20:23:47 +0100 Subject: [PATCH 27/46] (docs/demurrage): first draft for demurrage --- .../advanced-topics/inflation-demurrage.md | 91 +++++++++++++++++++ 1 file changed, 91 insertions(+) diff --git a/docs/docs/advanced-topics/inflation-demurrage.md b/docs/docs/advanced-topics/inflation-demurrage.md index e69de29..cc7a4c9 100644 --- a/docs/docs/advanced-topics/inflation-demurrage.md +++ b/docs/docs/advanced-topics/inflation-demurrage.md @@ -0,0 +1,91 @@ +# Demurrage Mechanism in Circles: Developer's Guide + +## Overview + +Circles implements demurrage as a systematic reduction of token balances over time, applied to all token balances in the system, affecting both personal and group currencies. The system extends the ERC1155 multi-token standard to incorporate this demurrage mechanism. + +Additionally, Circles allows wrapping ERC1155 tokens (in a demurrage representation) into an ERC20 contract. For each Circles identifier (personal or group), two ERC20 contracts can be created: one for demurrage representation and one for inflationary representation. + +### Key Features of Demurrage in Circles + +1. **Annual Rate**: 7% reduction in token balances per year +2. **Daily Application**: Calculated and applied on a per-day basis +3. **Universal**: Affects all Circles tokens equally + +## ERC1155 Interface and Demurrage + +Circles extends the standard ERC1155 interface to handle demurrage. Key functions include: + +### Balance Queries + +```solidity +function balanceOf(address account, uint256 id) public view returns (uint256) +``` +Returns the current demurraged balance of `account` for token `id`. This function internally calls `balanceOfOnDay` with the current day. + +```solidity +function balanceOfOnDay(address account, uint256 id, uint64 day) public view returns (uint256 balance, uint256 discountCost) +``` +Returns the demurraged balance for `account` and `id` as of the specified `day`, along with the `discountCost` (amount of tokens "burned" due to demurrage). + +### Transfers + +```solidity +function safeTransferFrom(address from, address to, uint256 id, uint256 value, bytes memory data) public +``` +Transfers `value` amount of token `id` from `from` to `to`, applying demurrage before transfer. + +### Token ID Convention + +Token IDs in Circles are derived from addresses: +```solidity +function toTokenId(address _address) public pure returns (uint256) +``` + +## Demurrage Calculation + +### Balance Reduction + +The system reduces token balances daily by a factor calculated as: +``` +Daily Factor = (1 - 0.07)^(1/365.25) ≈ 0.99980813 +``` +This results in a compound 7% reduction over a full year. + +### Practical Effects + +- A balance of 100 Circles reduces to approximately 99.98081 Circles after one day +- Over 365 days, 100 Circles reduces to about 93 Circles + +## Implementation Considerations + +1. **On-Demand Calculation**: Balance reductions are computed when balances are accessed or modified, not on a fixed schedule. +2. **Token Burning**: The reduction in balance effectively burns tokens, removing them from circulation. +3. **Gas Efficiency**: On-demand calculation avoids the need for daily update transactions. +4. **Precision**: Fixed-point arithmetic ensures high accuracy in calculations. + +## Development Guidelines + +1. Always use `balanceOf()` or `balanceOfOnDay()` to get current, demurraged balances. +2. On the hub contract, all amounts are to be understood as demurraged amounts on the current day. +3. Be aware that token balances decrease over time, even without explicit transfers or actions. + +## Helper Functions for Inflationary Conversion + +Circles provides two helper functions to convert between demurraged and inflationary representations: + +```solidity +function convertInflationaryToDemurrageValue(uint256 _amount, uint64 _currentDay) public view returns (uint256) +``` +Converts an inflationary amount to its demurraged equivalent as of the specified day. + +```solidity +function convertDemurrageToInflationaryValue(uint256 _amount, uint64 _currentDay) public view returns (uint256) +``` +Converts a demurraged amount to its inflationary equivalent as of the specified day. + +These functions are particularly useful when interacting with external systems or when a non-demurraged representation is needed for certain calculations or displays. + +## Conclusion + +Understanding the demurrage mechanism is crucial for developers working with Circles. Always consider the time-dependent nature of token balances and use the provided functions to ensure accurate balance calculations and transfers. \ No newline at end of file From 03eb8d500f46755640ef797b7b9c038494997ae3 Mon Sep 17 00:00:00 2001 From: Benjamin Bollen Date: Sat, 31 Aug 2024 20:24:24 +0100 Subject: [PATCH 28/46] (docs): path-based transfers, remove other sketches --- docs/docs/advanced-topics/consented-flow.md | 54 ---------------- docs/docs/advanced-topics/path2.md | 71 --------------------- 2 files changed, 125 deletions(-) delete mode 100644 docs/docs/advanced-topics/consented-flow.md delete mode 100644 docs/docs/advanced-topics/path2.md diff --git a/docs/docs/advanced-topics/consented-flow.md b/docs/docs/advanced-topics/consented-flow.md deleted file mode 100644 index 1bb5cc1..0000000 --- a/docs/docs/advanced-topics/consented-flow.md +++ /dev/null @@ -1,54 +0,0 @@ -# Consented Flow and isPermittedFlow - -## Consented Flow - -Consented flow is an advanced feature in the Circles ecosystem that provides additional control over token transfers. It's an opt-in mechanism that allows people to have more granular control over how their Circles tokens are used in path-based transactions. - -### Key Aspects: - -1. **Opt-in Feature**: By default, avatars don't have consented flow enabled. It can be activated by setting a specific flag in the `advancedUsageFlags` mapping. - -2. **Bilateral Trust**: When enabled, it requires bilateral trust for a transfer to be permitted. This means both the sender and receiver must trust each other. - -3. **Recursive Protection**: To maintain the integrity of the consented flow system, receivers must also have consented flow enabled for the transfer to be permitted. - -## isPermittedFlow Function - -The `isPermittedFlow` function is a crucial component in enforcing trust relationships and consented flow rules. It determines whether a transfer between two avatars is allowed. - -### Function Signature: -```solidity -function isPermittedFlow(address _from, address _to, address _circlesAvatar) public view returns (bool) -``` - -### Parameters: -- `_from`: The sender's address -- `_to`: The receiver's address -- `_circlesAvatar`: The address of the Circles avatar whose tokens are being transferred - -### Behavior: - -1. **Basic Trust Check**: - - Always checks if the receiver trusts the Circles being sent (`_to` trusts `_circlesAvatar`). - - If this basic trust doesn't exist, the flow is not permitted. - -2. **Consented Flow Check**: - - If the sender has consented flow enabled (checked via `advancedUsageFlags`), additional checks are performed: - a. The sender must trust the receiver (`_from` trusts `_to`). - b. The receiver must have consented flow enabled. - -3. **Return Value**: - - Returns `true` if the flow is permitted based on the above checks. - - Returns `false` otherwise. - -### Implications: - -- **Enhanced Control**: Allows people to have more control over how their tokens are used in complex transactions. -- **Increased Trust Requirements**: When enabled, it requires mutual trust between transaction participants. -- **Potential Complexity**: While offering more control, it may increase the complexity of finding valid transaction paths. - -## Use in the Circles Ecosystem - -The `isPermittedFlow` function is used in various parts of the Circles contract, particularly in path-based transactions and group mints. It ensures that all transfers, whether direct or as part of a complex path, adhere to the trust relationships and consented flow rules set by the participants. - -By providing this additional layer of control, Circles allows for a more nuanced and trust-centric economy, where people can have fine-grained control over their participation in the network's flow of value. \ No newline at end of file diff --git a/docs/docs/advanced-topics/path2.md b/docs/docs/advanced-topics/path2.md deleted file mode 100644 index 941e955..0000000 --- a/docs/docs/advanced-topics/path2.md +++ /dev/null @@ -1,71 +0,0 @@ -# Path-based Transactions and Flow Matrices - -In the Circles ecosystem, path-based transactions enable the transfer of Circles tokens between people who don't directly trust each other. This system utilizes flow matrices to represent and validate these complex transactions. - -## Flow Matrix Structure - -A flow matrix consists of the following components: - -1. **Flow Vertices**: An ordered list of avatar addresses that the transaction path touches. -2. **Flow Edges**: An array of structures, each representing a transfer of Circles tokens between two vertices. -3. **Streams**: Structures that define the terminal points of a transaction, including source, sink, and associated data. -4. **Coordinates**: Packed data representing the indices of Circles identifiers, senders, and receivers within the flow vertices array. - -## Transaction Process - -The `operateFlowMatrix` function in the Hub contract orchestrates path-based transactions: - -1. **Unpacking Coordinates**: The packed coordinates are expanded into an array of uint16 values. -2. **Operator Authorization**: Ensures the operator is approved for all source addresses in the streams. -3. **Flow Matrix Verification**: Checks the correctness of the flow matrix, including: - - Well-definedness of the matrix - - Registration of all entities - - Adherence to trust relationships - - Calculation of netted flows - -4. **Path Transfers**: Executes the individual transfers defined by the flow edges. -5. **Acceptance Checks**: Calls acceptance checks for the streams and calculates the netted flows. -6. **Flow Matching**: Ensures the netted flows from the matrix and streams match. - -## Key Functions - -### _verifyFlowMatrix - -This function performs crucial checks on the flow matrix: - -- Validates the length and order of flow vertices -- Ensures all vertices are registered avatars -- Verifies that each flow edge respects trust relationships -- Calculates the netted flow for each vertex - -### _effectPathTransfers - -Executes the actual transfers defined by the flow edges: - -- Handles both regular transfers and group mints -- Verifies the correct definition of streams -- Updates balances without triggering acceptance checks for intermediate transfers - -### _callAcceptanceChecks - -Processes the final streams of the transaction: - -- Calculates the total amounts for each stream -- Performs acceptance checks for the receiving addresses -- Emits `StreamCompleted` events for each successful stream - -## Optimizations and Constraints - -- Uses packed coordinates to reduce gas costs -- Implements checks to prevent common errors and vulnerabilities -- Utilizes a non-reentrant modifier to prevent reentrancy attacks - -## Implications for the Circles Ecosystem - -Path-based transactions allow for: - -- Increased liquidity within the Circles network -- Facilitation of trades between people without direct trust relationships -- Complex, multi-step transactions executed atomically - -This system forms the backbone of Circles' unique approach to creating a decentralized basic income, enabling fluid value transfer while respecting individual trust boundaries. \ No newline at end of file From 900cdb424939b2eb869a5f599625c645c0939cd0 Mon Sep 17 00:00:00 2001 From: Benjamin Bollen Date: Sat, 31 Aug 2024 20:46:32 +0100 Subject: [PATCH 29/46] (docs): demurrage, second pass --- .../advanced-topics/inflation-demurrage.md | 40 +++++++++++-------- 1 file changed, 24 insertions(+), 16 deletions(-) diff --git a/docs/docs/advanced-topics/inflation-demurrage.md b/docs/docs/advanced-topics/inflation-demurrage.md index cc7a4c9..d8c91be 100644 --- a/docs/docs/advanced-topics/inflation-demurrage.md +++ b/docs/docs/advanced-topics/inflation-demurrage.md @@ -18,28 +18,31 @@ Circles extends the standard ERC1155 interface to handle demurrage. Key function ### Balance Queries -```solidity +```js function balanceOf(address account, uint256 id) public view returns (uint256) ``` Returns the current demurraged balance of `account` for token `id`. This function internally calls `balanceOfOnDay` with the current day. -```solidity -function balanceOfOnDay(address account, uint256 id, uint64 day) public view returns (uint256 balance, uint256 discountCost) +```js +function balanceOfOnDay(address account, uint256 id, uint64 day) + public view returns (uint256 balance, uint256 discountCost) ``` Returns the demurraged balance for `account` and `id` as of the specified `day`, along with the `discountCost` (amount of tokens "burned" due to demurrage). ### Transfers -```solidity +```js function safeTransferFrom(address from, address to, uint256 id, uint256 value, bytes memory data) public ``` -Transfers `value` amount of token `id` from `from` to `to`, applying demurrage before transfer. +Transfers `value` amount of token `id` from `from` to `to`, applying demurrage before transfer to both sender and receiver if applicable. ### Token ID Convention Token IDs in Circles are derived from addresses: -```solidity -function toTokenId(address _address) public pure returns (uint256) +```js +function toTokenId(address _avatar) public pure returns (uint256) { + return uint256(uint160(_avatar)); +} ``` ## Demurrage Calculation @@ -47,7 +50,7 @@ function toTokenId(address _address) public pure returns (uint256) ### Balance Reduction The system reduces token balances daily by a factor calculated as: -``` +```sh Daily Factor = (1 - 0.07)^(1/365.25) ≈ 0.99980813 ``` This results in a compound 7% reduction over a full year. @@ -59,30 +62,35 @@ This results in a compound 7% reduction over a full year. ## Implementation Considerations -1. **On-Demand Calculation**: Balance reductions are computed when balances are accessed or modified, not on a fixed schedule. -2. **Token Burning**: The reduction in balance effectively burns tokens, removing them from circulation. +1. **On-Demand Calculation**: Balance reductions are computed when balances are accessed (through view functions) or computed and updated when modified (through transfers). +2. **Token Burning**: The reduction in balance burns the amount that gets demurraged, effectively removing these tokens from circulation. 3. **Gas Efficiency**: On-demand calculation avoids the need for daily update transactions. -4. **Precision**: Fixed-point arithmetic ensures high accuracy in calculations. +4. **Precision**: 128-bit fixed-point arithmetic ensures high accuracy in calculations, allowing for daily updates. ## Development Guidelines 1. Always use `balanceOf()` or `balanceOfOnDay()` to get current, demurraged balances. 2. On the hub contract, all amounts are to be understood as demurraged amounts on the current day. 3. Be aware that token balances decrease over time, even without explicit transfers or actions. +3. If your application expects static (ie. inflationary) balances or to interface with external systems: + - Use the provided `InflationaryOperator` contract to interact with ERC1155 Circles. + - Alternatively, wrap the (group) Circles you want to interact with in an inflationary ERC20 contract, where you can treat them as regular ERC20 tokens. ## Helper Functions for Inflationary Conversion Circles provides two helper functions to convert between demurraged and inflationary representations: -```solidity -function convertInflationaryToDemurrageValue(uint256 _amount, uint64 _currentDay) public view returns (uint256) +```js +function convertInflationaryToDemurrageValue(uint256 _amount, uint64 _day) + public view returns (uint256) ``` Converts an inflationary amount to its demurraged equivalent as of the specified day. -```solidity -function convertDemurrageToInflationaryValue(uint256 _amount, uint64 _currentDay) public view returns (uint256) +```js +function convertDemurrageToInflationaryValue(uint256 _amount, uint64 _dayUpdated) + public view returns (uint256) ``` -Converts a demurraged amount to its inflationary equivalent as of the specified day. +Converts a demurraged amount as on the day provided to its inflationary equivalent (day independent). These functions are particularly useful when interacting with external systems or when a non-demurraged representation is needed for certain calculations or displays. From b6e9261ae603d76c2981f7ed61ecb24ffb080246 Mon Sep 17 00:00:00 2001 From: Benjamin Bollen Date: Sat, 31 Aug 2024 20:58:59 +0100 Subject: [PATCH 30/46] (docs): demurrage, another pass; explain difference also demurrage vs inflationary --- .../advanced-topics/inflation-demurrage.md | 39 +++++++++++++++++-- 1 file changed, 36 insertions(+), 3 deletions(-) diff --git a/docs/docs/advanced-topics/inflation-demurrage.md b/docs/docs/advanced-topics/inflation-demurrage.md index d8c91be..ed4af32 100644 --- a/docs/docs/advanced-topics/inflation-demurrage.md +++ b/docs/docs/advanced-topics/inflation-demurrage.md @@ -76,6 +76,41 @@ This results in a compound 7% reduction over a full year. - Use the provided `InflationaryOperator` contract to interact with ERC1155 Circles. - Alternatively, wrap the (group) Circles you want to interact with in an inflationary ERC20 contract, where you can treat them as regular ERC20 tokens. +## Time and Day Calculation in Circles + +Understanding how Circles handles time is crucial for working with demurraged balances. The system uses a concept of "days" since a fixed starting point to calculate demurrage. + +### The `day` Function + +```js +function day(uint256 timestamp) internal view returns (uint64) { + return uint64((timestamp - inflationDayZero) / 1 days); +} +``` + +This function converts a Unix timestamp to a day number used in demurrage calculations. Key points: + +1. **Inflation Day Zero**: This is the starting point for all time calculations in Circles. It's set to October 15, 2020, at 00:00:00 UTC (Unix timestamp: 1602720000). + +2. **Day Calculation**: Days are calculated as the number of whole days passed since Inflation Day Zero. + +3. **Usage**: This day number is used in all demurrage calculations to determine how much a balance has decreased over time. + +### Demurrage vs Inflationary Balances + +- **Demurrage Balances**: These are time-dependent. The actual balance at any given moment is a function of the stored balance, the last update day, and the current day. +- **Inflationary Balances**: These are static in time. They represent an equivalent way of representing the 7% p.a. "inflation", but through an ever-increasing money supply. In the inflationary representation, Circles mints slightly more tokens per hour each day than the previous day, to offset the existing Circles already in circulation. + +Note that the ground-truth for Circles is the demurrage representation, where exactly one Circle is minted per person per hour, offset by the daily burning of Circles at a rate equivalent to 7% p.a. + +### Practical Implications + +1. When querying balances, the current day is always used to calculate the up-to-date demurraged balance. + +2. For future projections, you can specify a different day using `balanceOfOnDay()`. + +3. When converting between demurrage and inflationary representations, the day parameter determines the point in time for the conversion. + ## Helper Functions for Inflationary Conversion Circles provides two helper functions to convert between demurraged and inflationary representations: @@ -90,9 +125,7 @@ Converts an inflationary amount to its demurraged equivalent as of the specified function convertDemurrageToInflationaryValue(uint256 _amount, uint64 _dayUpdated) public view returns (uint256) ``` -Converts a demurraged amount as on the day provided to its inflationary equivalent (day independent). - -These functions are particularly useful when interacting with external systems or when a non-demurraged representation is needed for certain calculations or displays. +Converts a demurraged amount as on the day provided to its inflationary equivalent. ## Conclusion From c9e630afabbfa0e82a6c24edddff48bd47074f3c Mon Sep 17 00:00:00 2001 From: Benjamin Bollen Date: Mon, 2 Sep 2024 11:59:05 +0100 Subject: [PATCH 31/46] (docs): clean up nav --- docs/docs/index.md | 8 ++-- docs/mkdocs.yml | 46 +++++++++---------- .../appendices/contract-addresses.md | 0 .../appendices/external-resources.md | 0 .../appendices/index.md | 0 .../contract-interactions.md | 0 .../core-functionality/circles-contract.md | 0 .../core-functionality/hub-contract.md | 0 .../core-functionality/index.md | 0 .../developer-resources/best-practices.md | 0 .../developer-resources/contract-abis.md | 0 .../developer-resources/index.md | 0 .../integration-guidelines.md | 0 docs/{docs => unwritten-docs}/glossary.md | 0 docs/{docs => unwritten-docs}/key-features.md | 0 .../user-guides/group-currencies.md | 0 .../user-guides/index.md | 0 .../user-guides/minting-transferring.md | 0 .../user-guides/registration.md | 0 .../user-guides/trust-management.md | 0 20 files changed, 27 insertions(+), 27 deletions(-) rename docs/{docs => unwritten-docs}/appendices/contract-addresses.md (100%) rename docs/{docs => unwritten-docs}/appendices/external-resources.md (100%) rename docs/{docs => unwritten-docs}/appendices/index.md (100%) rename docs/{docs => unwritten-docs}/contract-interactions.md (100%) rename docs/{docs => unwritten-docs}/core-functionality/circles-contract.md (100%) rename docs/{docs => unwritten-docs}/core-functionality/hub-contract.md (100%) rename docs/{docs => unwritten-docs}/core-functionality/index.md (100%) rename docs/{docs => unwritten-docs}/developer-resources/best-practices.md (100%) rename docs/{docs => unwritten-docs}/developer-resources/contract-abis.md (100%) rename docs/{docs => unwritten-docs}/developer-resources/index.md (100%) rename docs/{docs => unwritten-docs}/developer-resources/integration-guidelines.md (100%) rename docs/{docs => unwritten-docs}/glossary.md (100%) rename docs/{docs => unwritten-docs}/key-features.md (100%) rename docs/{docs => unwritten-docs}/user-guides/group-currencies.md (100%) rename docs/{docs => unwritten-docs}/user-guides/index.md (100%) rename docs/{docs => unwritten-docs}/user-guides/minting-transferring.md (100%) rename docs/{docs => unwritten-docs}/user-guides/registration.md (100%) rename docs/{docs => unwritten-docs}/user-guides/trust-management.md (100%) diff --git a/docs/docs/index.md b/docs/docs/index.md index 49b72a7..af43ac5 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -9,7 +9,7 @@ Welcome to the Circles documentation. This guide will help you understand the Ci - Purpose and goals of Circles - Key concepts: personal currencies, trust networks, and demurrage - Total Supply and Equilibrium - + 6. [Advanced Topics](advanced-topics/index.md) - [Inflation and demurrage calculations](advanced-topics/inflation-demurrage.md) - [Path-based transactions and flow matrices](advanced-topics/path-based-transactions.md) - [Group mint policies and treasuries](advanced-topics/group-mint-policies.md) - + \ No newline at end of file diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 2120bf3..0b71496 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -7,30 +7,30 @@ nav: - About: about.md - Introduction: introduction.md - Architectural Overview: architecture.md - - Core Functionality: - - Overview: core-functionality/index.md - - Hub Contract: core-functionality/hub-contract.md - - Circles Contract: core-functionality/circles-contract.md - - Key Features: key-features.md - - Contract Interactions: contract-interactions.md + # - Core Functionality: + # - Overview: core-functionality/index.md + # - Hub Contract: core-functionality/hub-contract.md + # - Circles Contract: core-functionality/circles-contract.md + # - Key Features: key-features.md + # - Contract Interactions: contract-interactions.md - Advanced Topics: - - Overview: advanced-topics/index.md + # - Overview: advanced-topics/index.md - Inflation and Demurrage: advanced-topics/inflation-demurrage.md - Path-based Transactions: advanced-topics/path-based-transactions.md - Group Mint Policies: advanced-topics/group-mint-policies.md - - User Guides: - - Overview: user-guides/index.md - - Registration: user-guides/registration.md - - Trust Management: user-guides/trust-management.md - - Minting and Transferring: user-guides/minting-transferring.md - - Group Currencies: user-guides/group-currencies.md - - Developer Resources: - - Overview: developer-resources/index.md - - Contract ABIs: developer-resources/contract-abis.md - - Integration Guidelines: developer-resources/integration-guidelines.md - - Best Practices: developer-resources/best-practices.md - - Glossary: glossary.md - - Appendices: - - Overview: appendices/index.md - - Contract Addresses: appendices/contract-addresses.md - - External Resources: appendices/external-resources.md + # - User Guides: + # - Overview: user-guides/index.md + # - Registration: user-guides/registration.md + # - Trust Management: user-guides/trust-management.md + # - Minting and Transferring: user-guides/minting-transferring.md + # - Group Currencies: user-guides/group-currencies.md + # - Developer Resources: + # - Overview: developer-resources/index.md + # - Contract ABIs: developer-resources/contract-abis.md + # - Integration Guidelines: developer-resources/integration-guidelines.md + # - Best Practices: developer-resources/best-practices.md + # - Glossary: glossary.md + # - Appendices: + # - Overview: appendices/index.md + # - Contract Addresses: appendices/contract-addresses.md + # - External Resources: appendices/external-resources.md diff --git a/docs/docs/appendices/contract-addresses.md b/docs/unwritten-docs/appendices/contract-addresses.md similarity index 100% rename from docs/docs/appendices/contract-addresses.md rename to docs/unwritten-docs/appendices/contract-addresses.md diff --git a/docs/docs/appendices/external-resources.md b/docs/unwritten-docs/appendices/external-resources.md similarity index 100% rename from docs/docs/appendices/external-resources.md rename to docs/unwritten-docs/appendices/external-resources.md diff --git a/docs/docs/appendices/index.md b/docs/unwritten-docs/appendices/index.md similarity index 100% rename from docs/docs/appendices/index.md rename to docs/unwritten-docs/appendices/index.md diff --git a/docs/docs/contract-interactions.md b/docs/unwritten-docs/contract-interactions.md similarity index 100% rename from docs/docs/contract-interactions.md rename to docs/unwritten-docs/contract-interactions.md diff --git a/docs/docs/core-functionality/circles-contract.md b/docs/unwritten-docs/core-functionality/circles-contract.md similarity index 100% rename from docs/docs/core-functionality/circles-contract.md rename to docs/unwritten-docs/core-functionality/circles-contract.md diff --git a/docs/docs/core-functionality/hub-contract.md b/docs/unwritten-docs/core-functionality/hub-contract.md similarity index 100% rename from docs/docs/core-functionality/hub-contract.md rename to docs/unwritten-docs/core-functionality/hub-contract.md diff --git a/docs/docs/core-functionality/index.md b/docs/unwritten-docs/core-functionality/index.md similarity index 100% rename from docs/docs/core-functionality/index.md rename to docs/unwritten-docs/core-functionality/index.md diff --git a/docs/docs/developer-resources/best-practices.md b/docs/unwritten-docs/developer-resources/best-practices.md similarity index 100% rename from docs/docs/developer-resources/best-practices.md rename to docs/unwritten-docs/developer-resources/best-practices.md diff --git a/docs/docs/developer-resources/contract-abis.md b/docs/unwritten-docs/developer-resources/contract-abis.md similarity index 100% rename from docs/docs/developer-resources/contract-abis.md rename to docs/unwritten-docs/developer-resources/contract-abis.md diff --git a/docs/docs/developer-resources/index.md b/docs/unwritten-docs/developer-resources/index.md similarity index 100% rename from docs/docs/developer-resources/index.md rename to docs/unwritten-docs/developer-resources/index.md diff --git a/docs/docs/developer-resources/integration-guidelines.md b/docs/unwritten-docs/developer-resources/integration-guidelines.md similarity index 100% rename from docs/docs/developer-resources/integration-guidelines.md rename to docs/unwritten-docs/developer-resources/integration-guidelines.md diff --git a/docs/docs/glossary.md b/docs/unwritten-docs/glossary.md similarity index 100% rename from docs/docs/glossary.md rename to docs/unwritten-docs/glossary.md diff --git a/docs/docs/key-features.md b/docs/unwritten-docs/key-features.md similarity index 100% rename from docs/docs/key-features.md rename to docs/unwritten-docs/key-features.md diff --git a/docs/docs/user-guides/group-currencies.md b/docs/unwritten-docs/user-guides/group-currencies.md similarity index 100% rename from docs/docs/user-guides/group-currencies.md rename to docs/unwritten-docs/user-guides/group-currencies.md diff --git a/docs/docs/user-guides/index.md b/docs/unwritten-docs/user-guides/index.md similarity index 100% rename from docs/docs/user-guides/index.md rename to docs/unwritten-docs/user-guides/index.md diff --git a/docs/docs/user-guides/minting-transferring.md b/docs/unwritten-docs/user-guides/minting-transferring.md similarity index 100% rename from docs/docs/user-guides/minting-transferring.md rename to docs/unwritten-docs/user-guides/minting-transferring.md diff --git a/docs/docs/user-guides/registration.md b/docs/unwritten-docs/user-guides/registration.md similarity index 100% rename from docs/docs/user-guides/registration.md rename to docs/unwritten-docs/user-guides/registration.md diff --git a/docs/docs/user-guides/trust-management.md b/docs/unwritten-docs/user-guides/trust-management.md similarity index 100% rename from docs/docs/user-guides/trust-management.md rename to docs/unwritten-docs/user-guides/trust-management.md From 8f9a74974945cb312254c28e62e32a397caffa04 Mon Sep 17 00:00:00 2001 From: Benjamin Bollen Date: Mon, 2 Sep 2024 13:10:58 +0100 Subject: [PATCH 32/46] (root): update readme --- README.md | 105 ++++++++++++++++++++------------------------- docs/docs/index.md | 11 +++-- 2 files changed, 54 insertions(+), 62 deletions(-) diff --git a/README.md b/README.md index a066f4a..153a771 100644 --- a/README.md +++ b/README.md @@ -1,95 +1,84 @@ # Circles Protocol -## Introducing Circles Protocol v2 +Circles is a decentralized protocol for creating and distributing fair and social money through personal currencies. Built on the Gnosis Chain, it utilizes smart contracts to manage the creation, distribution, and transfer of personal currencies using the ERC1155 multi-token standard. -We're excited to be working on Circles Protocol v2, where we focus on making things better for everyone who uses and builds on Circles. Learning from our journey since Circles began, we've tackled the challenges we faced in the early days. +## Key Concepts -In Circles v2, we make it easier and more inviting for users and developers to engage with Circles. Our goal is to foster an ecosystem of products and experiences building on Circles. We've also been busy updating our technology, using the latest in cryptography to enhance performance, scalability, and to bring a new level of privacy to the Circles experience. +- **Personal Currencies**: Each individual can mint their own currency at a rate of one Circle per hour. +- **Trust Networks**: Currencies become valuable and transferable through trust relationships between participants. +- **Demurrage**: A 7% annual cost applied to held currencies, encouraging circulation and maintaining equity. -## Why build Circles ? +## Features -Our standard money system is based on debt, primarily from banks. Repaying this debt requires more than the initial amount due to interest, ensuring a consistent return of funds to these financial institutions. This system indirectly encourages anticipating future economic growth, which can increase our demand on the planet's resources. +- Retroactive minting for up to 14 days +- Path-based transactions through trust connections +- Flexible economic interactions between individuals, organizations, and groups +- Equilibrium mechanism balancing issuance and demurrage -In Circles UBI, we introduce "Time Circles" (TiC), a money system backed by the equal passage of time for all people. Every hour, each individual can seamlessly add one TiC to their account, unconditionally. To ensure TiC remains a meaningful measure of value, we implement a decay mechanism: tokens diminish in value over time. This equilibrium between token creation and decay ensures a stable balance for everyone, today and for future generations. +## Getting Started -Understanding "Time Circles" also means recognizing what they are not. While this brief overview may not capture the full depth of the discussion, let's set a clear foundation from the outset. +🐲 **Beta Status**: This repository is in beta and actively developed in the open. While initial reviews are on-going, we welcome community engagement for wider testing and integration. As AGPL-licensed software, it's provided as-is. We encourage thorough review and testing before any production use. -Time Circles is not a panacea for all economic challenges, but it is essential to understand its intended purpose. TiC isn't a promise of a universal standard of living across diverse regions. Instead, it's a commitment that no person should be completely without financial means. Think of TC as a baseline currency available to all. -Time Circles encourages circular spending. Its true worth will be determined by the quality and range of goods and services available for TiC. While other currencies may prioritize store-of-value, TiC complements this financial landscape, emphasizing circulation and utility. +### Prerequisites -Lastly, two crucial parameters underpin the TiC system. The first parameter straightforwardly defines the unit: one token for every human, every hour. The second parameter establishes the decay rate of TiC. With a vision for sustainability across generations, our approach is retrospective: taking an optimistic human lifespan of 80 years as a benchmark, a token minted today should, after those 80 years, carry negligible value. +- [Foundry](https://book.getfoundry.sh/getting-started/installation) -## Specifications +### Installation -🐉 **warning**: here be dragons. This repository is under construction and neither functionally complete or externally reviewed. It is shared publicly to enable early discussion, but should not be considered ready for use. - -For questions, contact maintainer: Ben - -## Setting up development environment - -This Solidity project uses Foundry as a toolkit. If you don't have Foundry installed yet, see instructions [below](#foundry-as-toolkit) - -### Using Foundry to build the contracts -1. First, you'll need to clone the repository to your local machine: +1. Clone the repository: ```bash - git clone https://github.com/CirclesUBI/circles-contracts-v2 + git clone https://github.com/aboutcircles/circles-contracts-v2 cd circles-contracts-v2 ``` - -### Compiling the contracts -1. To compile the contracts, use the following command: +2. Install dependencies: ```bash - forge build + forge install ``` - Upon successful compilation, you'll find the generated artifacts (like ABI and bytecode) in the specified output directory, by default `out/`. +### Building -2. To format the code, you can run: - ```bash - forge fmt - ``` - or only check the correct formatting without changing the code: +1. Compile the contracts: ```bash - forge fmt --check + forge build ``` -### Testing the contracts -1. To test the contracts, use the following command: +### Testing + +1. Run the test suite: ```bash forge test ``` - or to report on gas usage: +2. For a gas report: ```bash forge test --gas-report ``` -2. To create a snapshot file to disk of each test's gas usage, use: +### Deployment + +To deploy to the Chiado testnet: + +1. Copy `.env.example` to `.env` and set your private key and API keys. +2. Run the deployment script: ```bash - forge snapshot + ./script/deployments/chiadoDeploy.sh ``` -### Deploying the contracts -#### Chiado -To deploy the contracts to the Chiado testnet, run `./chiadoDeploy.sh` and supply a private key and API keys in `.env` file in the root directory (copy `.env.example` and set private information): -```shell -./script/deployments/chiadoDeploy.sh -``` +## Contributing -## Foundry as toolkit +Contributions are welcome! Please feel free to submit a Pull Request. -Foundry consists of: +## License -- **Forge**: Ethereum testing framework (like Truffle, Hardhat and DappTools). -- **Cast**: Swiss army knife for interacting with EVM smart contracts, sending transactions and getting chain data. -- **Anvil**: Local Ethereum node, akin to Ganache, Hardhat Network. -- **Chisel**: Fast, utilitarian, and verbose solidity REPL. +This project is licensed under the [AGPL-3.0 License](LICENSE). -You can find the installation guide for Foundry in their [book.getfoundry.sh - Getting started](https://book.getfoundry.sh/getting-started/installation) +## Disclaimer -Here we re-iterate the most important steps to get you started. +This project is under active development. The code has not completed externally reviews and should not be used in production environments without proper review and testing. -1. You can install precompiled binaries with their toolchain installer: - ```bash - curl -L https://foundry.paradigm.xyz | bash - ``` - and follow the instructions in the terminal. - To instead build from source, see their getting started guide. +## Contact + +For questions or support regarding this project, please contact: + +- About Circles +- Ben + +We appreciate your interest and feedback! \ No newline at end of file diff --git a/docs/docs/index.md b/docs/docs/index.md index af43ac5..d446ee5 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -9,6 +9,13 @@ Welcome to the Circles documentation. This guide will help you understand the Ci - Purpose and goals of Circles - Key concepts: personal currencies, trust networks, and demurrage - Total Supply and Equilibrium + +2. [Advanced Topics](advanced-topics/index.md) + - [Inflation and demurrage calculations](advanced-topics/inflation-demurrage.md) + - [Path-based transactions and flow matrices](advanced-topics/path-based-transactions.md) + - [Group mint policies and treasuries](advanced-topics/group-mint-policies.md) + + -6. [Advanced Topics](advanced-topics/index.md) - - [Inflation and demurrage calculations](advanced-topics/inflation-demurrage.md) - - [Path-based transactions and flow matrices](advanced-topics/path-based-transactions.md) - - [Group mint policies and treasuries](advanced-topics/group-mint-policies.md) + + + + + + Gnosis ChainSAFECircles contracts v2, 2024not built by uscore contractsa networkednode instanceEoAHumans and organizationshub v1tokenContracts v2orGroupas organisationhub v2is CirclesContracts v1Groupsenvisioned extensionsmigrationv1-to-v2single TransferThroughfor v1 PathfinderOperatorscan operate on the Graphintent solvercompetitionpre-/post-hookson intentscommunity dAppseg. CowSwap v2v2 mint auto-blocksNameRegistryCustomTreasuriesStandard TreasuryCirclesis ERC1155VaultGroupsDemurrage ERC20Inflationary ERC20Wrappers(Base) MintPolicyAccount AbstractionExtensionsFlow Matrixand ERC1155ERC20Lift \ No newline at end of file diff --git a/docs/docs/architecture.md b/docs/docs/architecture.md index 6ca4264..a3951f9 100644 --- a/docs/docs/architecture.md +++ b/docs/docs/architecture.md @@ -1 +1,125 @@ -## Architecture +# Circles Architectural Overview + +## Introduction + +Circles is a decentralized economic system built on the Gnosis Chain, designed to create and distribute fair and social money through personal currencies. This overview provides a high-level understanding of the system's architecture and how its various components interact. + +# Circles Architectural Overview + +## System Architecture Diagram + +![Alt text](./20240321-Circles-contracts.svg) + + + Open Circles Architecture diagram in new tab + + +## Core Components + +### Hub v2 (Circles) + +The central contract in the Circles ecosystem is the Hub v2, which serves as the main entry point for interactions with the system. It manages: + +- Registration of humans, organizations, and groups +- Minting of personal currencies +- Trust relationships between entities +- Group creation and management +- Minting collateral into group currencies +- wrapping ERC1155 Circles Ids tokens into ERC20 wrappers + +The Hub v2 contract implements the ERC1155 standard, allowing it to handle multiple token types efficiently. + +[Code: /src/hub/Hub.sol](https://github.com/aboutcircles/circles-contracts-v2/blob/v0.3.6-docs/src/hub/Hub.sol) + +### NameRegistry + +The NameRegistry contract manages the names and metadata associated with Circles accounts. It allows users to set custom names, symbols, and metadata for their personal or group currencies. + +### Migration Contract + +This contract facilitates the migration of tokens and data from Circles v1 to v2. It ensures a smooth transition for existing users and their balances. + +### Standard Treasury + +The Standard Treasury contract handles the collateral for group currencies. It receives and manages the assets backing group Circles. + +### Vault + +The Vault contract (placeholder - details to be added) likely serves as a secure storage for certain assets or data within the Circles ecosystem. + +## Token Representations + +### Circles (ERC1155) + +The core representation of Circles currencies uses the ERC1155 standard, allowing for efficient management of multiple token types (personal and group currencies) within a single contract. + +### Wrappers + +To enhance compatibility with existing DeFi ecosystems, Circles provides ERC20 wrappers: + +1. **Demurrage ERC20**: Represents Circles with the demurrage (decay) factor applied. +2. **Inflationary ERC20**: Represents Circles in their inflationary form, without demurrage applied. + +### ERC20Lift + +The ERC20Lift contract serves as a bridge between the ERC1155 and ERC20 representations, allowing users to wrap and unwrap their Circles tokens as needed. + +## Circles v1 Components (Legacy) + +### Hub v1 + +The original Hub contract from Circles v1, which is being phased out but remains relevant for migration purposes. + +### Token + +The individual ERC20 token contracts for personal currencies in Circles v1. + +## External Interactions + +### Gnosis Chain + +Circles is built on the Gnosis Chain, leveraging its security and efficiency. + +### Safe + +Integration with Safe (formerly Gnosis Safe) provides secure multi-signature wallet functionality for Circles users. + +### EoA (Externally Owned Accounts) + +Standard Ethereum accounts that can interact with the Circles system. + +## Advanced Features and Extensions + +### Intent Solver Competition + +(Placeholder) A mechanism for optimizing transactions and transfers within the Circles network. + +### Pre-/Post-hooks on Intents + +(Placeholder) Additional logic that can be executed before or after certain operations in the system. + +### Flow Matrix and ERC1155 + +A system for managing and executing complex transfers and exchanges of Circles currencies between multiple parties. + +### Single TransferThrough for v1 Pathfinder + +A mechanism to facilitate transfers using trust pathways, likely a carryover or adaptation from the v1 system. + +### Account Abstraction + +(Placeholder) Advanced account management features that may simplify user interactions with the system. + +### Custom Treasuries + +In addition to the Standard Treasury, the system allows for custom treasury implementations to cater to specific group needs. + +### Community dApps + +The architecture supports the development of community-driven decentralized applications, such as a potential CowSwap v2 integration. + +## Conclusion + +The Circles v2 architecture represents a significant evolution from its predecessor, offering a more flexible and scalable system for personal and group currencies. By leveraging advanced smart contract standards like ERC1155 and providing multiple token representations, Circles aims to create a robust ecosystem for social money that can integrate seamlessly with the broader DeFi landscape. + +This architecture balances the need for a cohesive, centralized hub with the flexibility required for diverse use cases and future extensions. As the system continues to evolve, this modular design will allow for the integration of new features and improvements while maintaining backward compatibility and supporting the migration from v1. diff --git a/docs/docs/index.md b/docs/docs/index.md index cb6ca26..581c8ff 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -12,7 +12,7 @@ Welcome to the Circles documentation. This guide will help you understand the Ci 2. [Architectural Overview](architecture.md) -2. [Advanced Topics](advanced-topics/index.md) +3. [Advanced Topics](advanced-topics/index.md) - [Inflation and demurrage calculations](advanced-topics/inflation-demurrage.md) - [Path-based transactions and flow matrices](advanced-topics/path-based-transactions.md) - [Group mint policies and treasuries](advanced-topics/group-mint-policies.md) From 1fbc9df2c92cfd588c4ce683a4d3773929ad2e33 Mon Sep 17 00:00:00 2001 From: Benjamin Bollen Date: Mon, 2 Sep 2024 18:04:32 +0100 Subject: [PATCH 38/46] (docs): architecture overview, upto migration --- docs/docs/architecture.md | 32 ++++++++++++++++++++++++++------ 1 file changed, 26 insertions(+), 6 deletions(-) diff --git a/docs/docs/architecture.md b/docs/docs/architecture.md index a3951f9..2efef79 100644 --- a/docs/docs/architecture.md +++ b/docs/docs/architecture.md @@ -4,8 +4,6 @@ Circles is a decentralized economic system built on the Gnosis Chain, designed to create and distribute fair and social money through personal currencies. This overview provides a high-level understanding of the system's architecture and how its various components interact. -# Circles Architectural Overview - ## System Architecture Diagram ![Alt text](./20240321-Circles-contracts.svg) @@ -25,7 +23,8 @@ The central contract in the Circles ecosystem is the Hub v2, which serves as the - Trust relationships between entities - Group creation and management - Minting collateral into group currencies -- wrapping ERC1155 Circles Ids tokens into ERC20 wrappers +- Wrapping ERC1155 Circles Ids tokens into ERC20 wrappers +- Demurrage of all Circles tokens equally The Hub v2 contract implements the ERC1155 standard, allowing it to handle multiple token types efficiently. @@ -33,11 +32,32 @@ The Hub v2 contract implements the ERC1155 standard, allowing it to handle multi ### NameRegistry -The NameRegistry contract manages the names and metadata associated with Circles accounts. It allows users to set custom names, symbols, and metadata for their personal or group currencies. +The NameRegistry contract manages names, symbols and metadata for avatars (humans, groups, and organizations): + +- Allows humans to register a unique short name (12 characters, base58 encoding) +- Stores custom names for groups and organizations +- Manages custom symbols for group currencies +- Stores and updates metadata digests (eg IPFS CIDs) for avatar profiles +- Names are read by ERC20 contracts for name and symbol + +The NameRegistry plays a role in identity management and human-readable addressing within the Circles system, enhancing user experience and facilitating easier identification of avatars and their associated currencies. + +[Code: /src/names/NameRegistry.sol](https://github.com/aboutcircles/circles-contracts-v2/blob/v0.3.6-docs/src/names/NameRegistry.sol) + +### Migration + +The Migration contract facilitates the transition from Circles v1 to v2, ensuring the ability to migrate token balances: + +- Converts v1 Circles to v2 Circles, accounting for inflation and demurrage +- Uses a linear interpolation method to calculate the conversion rate. Corrects for the original convention in hub v1 where 1/3 CRC per hour is issued (8 CRC per day) +- Allows migration of multiple types of Circles balances in a single transaction by one owner +- Locks v1 tokens in the Migration contract and mints equivalent v2 tokens. +- Ensures upon migrating balances that humans are auto-registered in Hub v2 - so that their token is defined +- owners of Circles in v1 can migrate their balances at any time and for any amount they chose to Circles v2. -### Migration Contract +This Migration system ensures a controlled and secure transition from Circles v1 to v2, maintaining integrity throughout the upgrade process. -This contract facilitates the migration of tokens and data from Circles v1 to v2. It ensures a smooth transition for existing users and their balances. +[Code: /src/migration/Migration.sol](https://github.com/aboutcircles/circles-contracts-v2/blob/v0.3.6-docs/src/migration/Migration.sol) ### Standard Treasury From b206e981145d5246ff629d3fe716ccd50e12e6d7 Mon Sep 17 00:00:00 2001 From: Benjamin Bollen Date: Mon, 2 Sep 2024 18:20:11 +0100 Subject: [PATCH 39/46] (docs): draft on groups, policy and treasury --- docs/docs/architecture.md | 69 +++++++++++++++++++++++++++++++++++---- 1 file changed, 63 insertions(+), 6 deletions(-) diff --git a/docs/docs/architecture.md b/docs/docs/architecture.md index 2efef79..c1dfef2 100644 --- a/docs/docs/architecture.md +++ b/docs/docs/architecture.md @@ -59,13 +59,70 @@ This Migration system ensures a controlled and secure transition from Circles v1 [Code: /src/migration/Migration.sol](https://github.com/aboutcircles/circles-contracts-v2/blob/v0.3.6-docs/src/migration/Migration.sol) -### Standard Treasury -The Standard Treasury contract handles the collateral for group currencies. It receives and manages the assets backing group Circles. - -### Vault - -The Vault contract (placeholder - details to be added) likely serves as a secure storage for certain assets or data within the Circles ecosystem. +### Groups, Policies and Treasury + +The Circles ecosystem includes a sophisticated system for managing group currencies, which involves several interconnected components: + +#### Groups + +- Defined in the Hub contract +- Require a Mint Policy and Treasury for creation +- Can be registered using `hub.registerGroup()` + +#### Standard Treasury + +1. **Purpose**: Manages collateral for group currencies +2. **Key Features**: + - Acts as a factory for Vaults + - Handles minting and redemption of group Circles + - Interacts with Mint Policies for redemption logic +3. **Functions**: + - `onERC1155Received`: Handles single token transfers (minting or redemption) + - `onERC1155BatchReceived`: Handles batch token transfers (minting) + - Creates Vaults for groups as needed + +#### Vaults + +1. **Purpose**: Securely store collateral for group currencies +2. **Key Features**: + - Deployed by Standard Treasury using a factory pattern + - Each group has its own Vault +3. **Functions**: + - `returnCollateral`: Sends collateral back to users during redemption + - `burnCollateral`: Burns collateral as specified by Mint Policy + +#### Base Mint Policy + +1. **Purpose**: Defines rules for minting, burning, and redeeming group currencies +2. **Key Features**: + - Customizable for different group needs + - Default implementation allows all mints/burns and user-specified redemptions +3. **Functions**: + - `beforeMintPolicy`: Validates minting requests + - `beforeBurnPolicy`: Validates burning requests + - `beforeRedeemPolicy`: Specifies redemption logic + +#### System Interaction + +1. **Group Creation**: + - User calls `hub.registerGroup()` + - Hub assigns Standard Treasury + - Standard Treasury creates a Vault for the group + +2. **Minting Group Circles**: + - Collateral transferred to Treasury + - Treasury forwards collateral to group's Vault + - Mint Policy consulted for approval + - Group Circles minted to user + +3. **Redeeming Group Circles**: + - User sends group Circles to Treasury + - Treasury consults Mint Policy for redemption logic + - Vault returns specified collateral to user + - Excess collateral burned if specified by policy + +This system provides a flexible and secure framework for creating and managing group currencies within the Circles ecosystem. It allows for customizable minting and redemption policies while ensuring proper collateralization and secure storage of assets. ## Token Representations From aefcacf4452d9cd2ed384c835c1dd703c309ff10 Mon Sep 17 00:00:00 2001 From: Benjamin Bollen Date: Mon, 2 Sep 2024 18:36:29 +0100 Subject: [PATCH 40/46] (docs): rebalance nav --- docs/docs/architecture.md | 2 +- docs/docs/index.md | 6 +++++- docs/mkdocs.yml | 2 +- 3 files changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/docs/architecture.md b/docs/docs/architecture.md index c1dfef2..fe847f9 100644 --- a/docs/docs/architecture.md +++ b/docs/docs/architecture.md @@ -62,7 +62,7 @@ This Migration system ensures a controlled and secure transition from Circles v1 ### Groups, Policies and Treasury -The Circles ecosystem includes a sophisticated system for managing group currencies, which involves several interconnected components: +Circles allows the definition of group currencies, which involves several interconnected components: #### Groups diff --git a/docs/docs/index.md b/docs/docs/index.md index 581c8ff..d876949 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -11,11 +11,15 @@ Welcome to the Circles documentation. This guide will help you understand the Ci - Total Supply and Equilibrium 2. [Architectural Overview](architecture.md) + - System Architecture Diagram + - Core Components + - Token Representations + - Circles v1 Components (legacy) 3. [Advanced Topics](advanced-topics/index.md) - [Inflation and demurrage calculations](advanced-topics/inflation-demurrage.md) - [Path-based transactions and flow matrices](advanced-topics/path-based-transactions.md) - - [Group mint policies and treasuries](advanced-topics/group-mint-policies.md) +