From aa75d3aec5d5973ff0ad173afc2401784ee5a7c1 Mon Sep 17 00:00:00 2001
From: benjaminbollen <benjaminbollen@users.noreply.github.com>
Date: Mon, 2 Sep 2024 17:37:26 +0000
Subject: [PATCH] deploy: aefcacf4452d9cd2ed384c835c1dd703c309ff10

---
 404.html                                         |  2 --
 about/index.html                                 |  2 --
 advanced-topics/group-mint-policies/index.html   | 16 ++++------------
 advanced-topics/index.html                       |  2 --
 advanced-topics/inflation-demurrage/index.html   |  2 --
 .../path-based-transactions/index.html           |  5 -----
 architecture/index.html                          |  4 +---
 index.html                                       | 14 +++++++++-----
 introduction/index.html                          |  2 --
 search.html                                      |  2 --
 search/search_index.json                         |  2 +-
 11 files changed, 15 insertions(+), 38 deletions(-)

diff --git a/404.html b/404.html
index e0f3f93..18517f6 100644
--- a/404.html
+++ b/404.html
@@ -54,8 +54,6 @@
                   </li>
                   <li class="toctree-l1"><a class="reference internal" href="/advanced-topics/path-based-transactions/">Path-based Transactions</a>
                   </li>
-                  <li class="toctree-l1"><a class="reference internal" href="/advanced-topics/group-mint-policies/">Group Mint Policies</a>
-                  </li>
               </ul>
       </div>
     </div>
diff --git a/about/index.html b/about/index.html
index 2d9d006..f329a91 100644
--- a/about/index.html
+++ b/about/index.html
@@ -67,8 +67,6 @@
                   </li>
                   <li class="toctree-l1"><a class="reference internal" href="../advanced-topics/path-based-transactions/">Path-based Transactions</a>
                   </li>
-                  <li class="toctree-l1"><a class="reference internal" href="../advanced-topics/group-mint-policies/">Group Mint Policies</a>
-                  </li>
               </ul>
       </div>
     </div>
diff --git a/advanced-topics/group-mint-policies/index.html b/advanced-topics/group-mint-policies/index.html
index 0977aa9..f9ae326 100644
--- a/advanced-topics/group-mint-policies/index.html
+++ b/advanced-topics/group-mint-policies/index.html
@@ -5,14 +5,14 @@
     <meta http-equiv="X-UA-Compatible" content="IE=edge" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
       <link rel="shortcut icon" href="../../img/favicon.ico" />
-    <title>Group Mint Policies - Circles Protocol</title>
+    <title>Group mint policies - Circles Protocol</title>
     <link rel="stylesheet" href="../../css/theme.css" />
     <link rel="stylesheet" href="../../css/theme_extra.css" />
         <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/styles/github.min.css" />
     
       <script>
         // Current page data
-        var mkdocs_page_name = "Group Mint Policies";
+        var mkdocs_page_name = "Group mint policies";
         var mkdocs_page_input_path = "advanced-topics/group-mint-policies.md";
         var mkdocs_page_url = null;
       </script>
@@ -56,13 +56,11 @@
                 </li>
               </ul>
               <p class="caption"><span class="caption-text">Advanced Topics</span></p>
-              <ul class="current">
+              <ul>
                   <li class="toctree-l1"><a class="reference internal" href="../inflation-demurrage/">Inflation and Demurrage</a>
                   </li>
                   <li class="toctree-l1"><a class="reference internal" href="../path-based-transactions/">Path-based Transactions</a>
                   </li>
-                  <li class="toctree-l1 current"><a class="reference internal current" href="#">Group Mint Policies</a>
-                  </li>
               </ul>
       </div>
     </div>
@@ -78,8 +76,7 @@
         <div class="rst-content"><div role="navigation" aria-label="breadcrumbs navigation">
   <ul class="wy-breadcrumbs">
     <li><a href="../.." class="icon icon-home" aria-label="Docs"></a></li>
-          <li class="breadcrumb-item">Advanced Topics</li>
-      <li class="breadcrumb-item active">Group Mint Policies</li>
+      <li class="breadcrumb-item active">Group mint policies</li>
     <li class="wy-breadcrumbs-aside">
     </li>
   </ul>
@@ -92,9 +89,6 @@
               
             </div>
           </div><footer>
-    <div class="rst-footer-buttons" role="navigation" aria-label="Footer Navigation">
-        <a href="../path-based-transactions/" class="btn btn-neutral float-left" title="Path-based Transactions"><span class="icon icon-circle-arrow-left"></span> Previous</a>
-    </div>
 
   <hr/>
 
@@ -116,8 +110,6 @@
   <span class="rst-current-version" data-toggle="rst-current-version">
     
     
-      <span><a href="../path-based-transactions/" style="color: #fcfcfc">&laquo; Previous</a></span>
-    
     
   </span>
 </div>
diff --git a/advanced-topics/index.html b/advanced-topics/index.html
index 64eebd1..879de08 100644
--- a/advanced-topics/index.html
+++ b/advanced-topics/index.html
@@ -61,8 +61,6 @@
                   </li>
                   <li class="toctree-l1"><a class="reference internal" href="path-based-transactions/">Path-based Transactions</a>
                   </li>
-                  <li class="toctree-l1"><a class="reference internal" href="group-mint-policies/">Group Mint Policies</a>
-                  </li>
               </ul>
       </div>
     </div>
diff --git a/advanced-topics/inflation-demurrage/index.html b/advanced-topics/inflation-demurrage/index.html
index 737fd05..78bfb3c 100644
--- a/advanced-topics/inflation-demurrage/index.html
+++ b/advanced-topics/inflation-demurrage/index.html
@@ -105,8 +105,6 @@
                   </li>
                   <li class="toctree-l1"><a class="reference internal" href="../path-based-transactions/">Path-based Transactions</a>
                   </li>
-                  <li class="toctree-l1"><a class="reference internal" href="../group-mint-policies/">Group Mint Policies</a>
-                  </li>
               </ul>
       </div>
     </div>
diff --git a/advanced-topics/path-based-transactions/index.html b/advanced-topics/path-based-transactions/index.html
index a328eb1..003e326 100644
--- a/advanced-topics/path-based-transactions/index.html
+++ b/advanced-topics/path-based-transactions/index.html
@@ -119,8 +119,6 @@
     </li>
     </ul>
                   </li>
-                  <li class="toctree-l1"><a class="reference internal" href="../group-mint-policies/">Group Mint Policies</a>
-                  </li>
               </ul>
       </div>
     </div>
@@ -454,7 +452,6 @@ <h2 id="conclusion">Conclusion</h2>
           </div><footer>
     <div class="rst-footer-buttons" role="navigation" aria-label="Footer Navigation">
         <a href="../inflation-demurrage/" class="btn btn-neutral float-left" title="Inflation and Demurrage"><span class="icon icon-circle-arrow-left"></span> Previous</a>
-        <a href="../group-mint-policies/" class="btn btn-neutral float-right" title="Group Mint Policies">Next <span class="icon icon-circle-arrow-right"></span></a>
     </div>
 
   <hr/>
@@ -480,8 +477,6 @@ <h2 id="conclusion">Conclusion</h2>
       <span><a href="../inflation-demurrage/" style="color: #fcfcfc">&laquo; Previous</a></span>
     
     
-      <span><a href="../group-mint-policies/" style="color: #fcfcfc">Next &raquo;</a></span>
-    
   </span>
 </div>
     <script src="../../js/jquery-3.6.0.min.js"></script>
diff --git a/architecture/index.html b/architecture/index.html
index c03fe8c..565a483 100644
--- a/architecture/index.html
+++ b/architecture/index.html
@@ -139,8 +139,6 @@
                   </li>
                   <li class="toctree-l1"><a class="reference internal" href="../advanced-topics/path-based-transactions/">Path-based Transactions</a>
                   </li>
-                  <li class="toctree-l1"><a class="reference internal" href="../advanced-topics/group-mint-policies/">Group Mint Policies</a>
-                  </li>
               </ul>
       </div>
     </div>
@@ -211,7 +209,7 @@ <h3 id="migration">Migration</h3>
 <p>This Migration system ensures a controlled and secure transition from Circles v1 to v2, maintaining integrity throughout the upgrade process.</p>
 <p><a href="https://github.com/aboutcircles/circles-contracts-v2/blob/v0.3.6-docs/src/migration/Migration.sol">Code: /src/migration/Migration.sol</a></p>
 <h3 id="groups-policies-and-treasury">Groups, Policies and Treasury</h3>
-<p>The Circles ecosystem includes a sophisticated system for managing group currencies, which involves several interconnected components:</p>
+<p>Circles allows the definition of group currencies, which involves several interconnected components:</p>
 <h4 id="groups">Groups</h4>
 <ul>
 <li>Defined in the Hub contract</li>
diff --git a/index.html b/index.html
index 5193d8f..1fd67af 100644
--- a/index.html
+++ b/index.html
@@ -65,8 +65,6 @@
                   </li>
                   <li class="toctree-l1"><a class="reference internal" href="advanced-topics/path-based-transactions/">Path-based Transactions</a>
                   </li>
-                  <li class="toctree-l1"><a class="reference internal" href="advanced-topics/group-mint-policies/">Group Mint Policies</a>
-                  </li>
               </ul>
       </div>
     </div>
@@ -106,13 +104,19 @@ <h2 id="table-of-contents">Table of Contents</h2>
 </li>
 <li>
 <p><a href="architecture/">Architectural Overview</a></p>
+<ul>
+<li>System Architecture Diagram</li>
+<li>Core Components</li>
+<li>Token Representations</li>
+<li>Circles v1 Components (legacy)</li>
+</ul>
 </li>
 <li>
 <p><a href="advanced-topics/">Advanced Topics</a></p>
 <ul>
 <li><a href="advanced-topics/inflation-demurrage/">Inflation and demurrage calculations</a></li>
-<li><a href="advanced-topics/path-based-transactions/">Path-based transactions and flow matrices</a></li>
-<li><a href="advanced-topics/group-mint-policies/">Group mint policies and treasuries</a></li>
+<li><a href="advanced-topics/path-based-transactions/">Path-based transactions and flow matrices</a>
+<!-- - <a href="advanced-topics/group-mint-policies.md">Group mint policies and treasuries</a> --></li>
 </ul>
 </li>
 </ol>
@@ -215,5 +219,5 @@ <h2 id="table-of-contents">Table of Contents</h2>
 
 <!--
 MkDocs version : 1.6.1
-Build Date UTC : 2024-09-02 17:20:57.490830+00:00
+Build Date UTC : 2024-09-02 17:37:24.941199+00:00
 -->
diff --git a/introduction/index.html b/introduction/index.html
index b743e85..72ce743 100644
--- a/introduction/index.html
+++ b/introduction/index.html
@@ -79,8 +79,6 @@
                   </li>
                   <li class="toctree-l1"><a class="reference internal" href="../advanced-topics/path-based-transactions/">Path-based Transactions</a>
                   </li>
-                  <li class="toctree-l1"><a class="reference internal" href="../advanced-topics/group-mint-policies/">Group Mint Policies</a>
-                  </li>
               </ul>
       </div>
     </div>
diff --git a/search.html b/search.html
index 6792292..32ffdde 100644
--- a/search.html
+++ b/search.html
@@ -54,8 +54,6 @@
                   </li>
                   <li class="toctree-l1"><a class="reference internal" href="./advanced-topics/path-based-transactions/">Path-based Transactions</a>
                   </li>
-                  <li class="toctree-l1"><a class="reference internal" href="./advanced-topics/group-mint-policies/">Group Mint Policies</a>
-                  </li>
               </ul>
       </div>
     </div>
diff --git a/search/search_index.json b/search/search_index.json
index 9e5f8df..c1698c6 100644
--- a/search/search_index.json
+++ b/search/search_index.json
@@ -1 +1 @@
-{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"Circles Documentation Welcome to the Circles documentation. This guide will help you understand the Circles project, its architecture, and core functionalities. Table of Contents Introduction to Circles Brief overview of the Circles project Purpose and goals of Circles Key concepts: personal currencies, trust networks, and demurrage Total Supply and Equilibrium Architectural Overview Advanced Topics Inflation and demurrage calculations Path-based transactions and flow matrices Group mint policies and treasuries","title":"Home"},{"location":"#circles-documentation","text":"Welcome to the Circles documentation. This guide will help you understand the Circles project, its architecture, and core functionalities.","title":"Circles Documentation"},{"location":"#table-of-contents","text":"Introduction to Circles Brief overview of the Circles project Purpose and goals of Circles Key concepts: personal currencies, trust networks, and demurrage Total Supply and Equilibrium Architectural Overview Advanced Topics Inflation and demurrage calculations Path-based transactions and flow matrices Group mint policies and treasuries","title":"Table of Contents"},{"location":"about/","text":"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. 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. 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: 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.","title":"About"},{"location":"about/#about-the-circles-protocol","text":"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.","title":"About the Circles Protocol"},{"location":"about/#disclaimer","text":"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.","title":"Disclaimer"},{"location":"about/#licensing","text":"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.","title":"Licensing"},{"location":"architecture/","text":"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. System Architecture Diagram 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 Demurrage of all Circles tokens equally The Hub v2 contract implements the ERC1155 standard, allowing it to handle multiple token types efficiently. Code: /src/hub/Hub.sol NameRegistry 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 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. This Migration system ensures a controlled and secure transition from Circles v1 to v2, maintaining integrity throughout the upgrade process. Code: /src/migration/Migration.sol 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 Purpose : Manages collateral for group currencies Key Features : Acts as a factory for Vaults Handles minting and redemption of group Circles Interacts with Mint Policies for redemption logic Functions : onERC1155Received : Handles single token transfers (minting or redemption) onERC1155BatchReceived : Handles batch token transfers (minting) Creates Vaults for groups as needed Vaults Purpose : Securely store collateral for group currencies Key Features : Deployed by Standard Treasury using a factory pattern Each group has its own Vault Functions : returnCollateral : Sends collateral back to users during redemption burnCollateral : Burns collateral as specified by Mint Policy Base Mint Policy Purpose : Defines rules for minting, burning, and redeeming group currencies Key Features : Customizable for different group needs Default implementation allows all mints/burns and user-specified redemptions Functions : beforeMintPolicy : Validates minting requests beforeBurnPolicy : Validates burning requests beforeRedeemPolicy : Specifies redemption logic System Interaction Group Creation : User calls hub.registerGroup() Hub assigns Standard Treasury Standard Treasury creates a Vault for the group Minting Group Circles : Collateral transferred to Treasury Treasury forwards collateral to group's Vault Mint Policy consulted for approval Group Circles minted to user 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 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: Demurrage ERC20 : Represents Circles with the demurrage (decay) factor applied. 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.","title":"Architectural Overview"},{"location":"architecture/#circles-architectural-overview","text":"","title":"Circles Architectural Overview"},{"location":"architecture/#introduction","text":"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.","title":"Introduction"},{"location":"architecture/#system-architecture-diagram","text":"Open Circles Architecture diagram in new tab","title":"System Architecture Diagram"},{"location":"architecture/#core-components","text":"","title":"Core Components"},{"location":"architecture/#hub-v2-circles","text":"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 Demurrage of all Circles tokens equally The Hub v2 contract implements the ERC1155 standard, allowing it to handle multiple token types efficiently. Code: /src/hub/Hub.sol","title":"Hub v2 (Circles)"},{"location":"architecture/#nameregistry","text":"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","title":"NameRegistry"},{"location":"architecture/#migration","text":"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. This Migration system ensures a controlled and secure transition from Circles v1 to v2, maintaining integrity throughout the upgrade process. Code: /src/migration/Migration.sol","title":"Migration"},{"location":"architecture/#groups-policies-and-treasury","text":"The Circles ecosystem includes a sophisticated system for managing group currencies, which involves several interconnected components:","title":"Groups, Policies and Treasury"},{"location":"architecture/#groups","text":"Defined in the Hub contract Require a Mint Policy and Treasury for creation Can be registered using hub.registerGroup()","title":"Groups"},{"location":"architecture/#standard-treasury","text":"Purpose : Manages collateral for group currencies Key Features : Acts as a factory for Vaults Handles minting and redemption of group Circles Interacts with Mint Policies for redemption logic Functions : onERC1155Received : Handles single token transfers (minting or redemption) onERC1155BatchReceived : Handles batch token transfers (minting) Creates Vaults for groups as needed","title":"Standard Treasury"},{"location":"architecture/#vaults","text":"Purpose : Securely store collateral for group currencies Key Features : Deployed by Standard Treasury using a factory pattern Each group has its own Vault Functions : returnCollateral : Sends collateral back to users during redemption burnCollateral : Burns collateral as specified by Mint Policy","title":"Vaults"},{"location":"architecture/#base-mint-policy","text":"Purpose : Defines rules for minting, burning, and redeeming group currencies Key Features : Customizable for different group needs Default implementation allows all mints/burns and user-specified redemptions Functions : beforeMintPolicy : Validates minting requests beforeBurnPolicy : Validates burning requests beforeRedeemPolicy : Specifies redemption logic","title":"Base Mint Policy"},{"location":"architecture/#system-interaction","text":"Group Creation : User calls hub.registerGroup() Hub assigns Standard Treasury Standard Treasury creates a Vault for the group Minting Group Circles : Collateral transferred to Treasury Treasury forwards collateral to group's Vault Mint Policy consulted for approval Group Circles minted to user 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.","title":"System Interaction"},{"location":"architecture/#token-representations","text":"","title":"Token Representations"},{"location":"architecture/#circles-erc1155","text":"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.","title":"Circles (ERC1155)"},{"location":"architecture/#wrappers","text":"To enhance compatibility with existing DeFi ecosystems, Circles provides ERC20 wrappers: Demurrage ERC20 : Represents Circles with the demurrage (decay) factor applied. Inflationary ERC20 : Represents Circles in their inflationary form, without demurrage applied.","title":"Wrappers"},{"location":"architecture/#erc20lift","text":"The ERC20Lift contract serves as a bridge between the ERC1155 and ERC20 representations, allowing users to wrap and unwrap their Circles tokens as needed.","title":"ERC20Lift"},{"location":"architecture/#circles-v1-components-legacy","text":"","title":"Circles v1 Components (Legacy)"},{"location":"architecture/#hub-v1","text":"The original Hub contract from Circles v1, which is being phased out but remains relevant for migration purposes.","title":"Hub v1"},{"location":"architecture/#token","text":"The individual ERC20 token contracts for personal currencies in Circles v1.","title":"Token"},{"location":"architecture/#external-interactions","text":"","title":"External Interactions"},{"location":"architecture/#gnosis-chain","text":"Circles is built on the Gnosis Chain, leveraging its security and efficiency.","title":"Gnosis Chain"},{"location":"architecture/#safe","text":"Integration with Safe (formerly Gnosis Safe) provides secure multi-signature wallet functionality for Circles users.","title":"Safe"},{"location":"architecture/#eoa-externally-owned-accounts","text":"Standard Ethereum accounts that can interact with the Circles system.","title":"EoA (Externally Owned Accounts)"},{"location":"architecture/#advanced-features-and-extensions","text":"","title":"Advanced Features and Extensions"},{"location":"architecture/#intent-solver-competition","text":"(Placeholder) A mechanism for optimizing transactions and transfers within the Circles network.","title":"Intent Solver Competition"},{"location":"architecture/#pre-post-hooks-on-intents","text":"(Placeholder) Additional logic that can be executed before or after certain operations in the system.","title":"Pre-/Post-hooks on Intents"},{"location":"architecture/#flow-matrix-and-erc1155","text":"A system for managing and executing complex transfers and exchanges of Circles currencies between multiple parties.","title":"Flow Matrix and ERC1155"},{"location":"architecture/#single-transferthrough-for-v1-pathfinder","text":"A mechanism to facilitate transfers using trust pathways, likely a carryover or adaptation from the v1 system.","title":"Single TransferThrough for v1 Pathfinder"},{"location":"architecture/#account-abstraction","text":"(Placeholder) Advanced account management features that may simplify user interactions with the system.","title":"Account Abstraction"},{"location":"architecture/#custom-treasuries","text":"In addition to the Standard Treasury, the system allows for custom treasury implementations to cater to specific group needs.","title":"Custom Treasuries"},{"location":"architecture/#community-dapps","text":"The architecture supports the development of community-driven decentralized applications, such as a potential CowSwap v2 integration.","title":"Community dApps"},{"location":"architecture/#conclusion","text":"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.","title":"Conclusion"},{"location":"introduction/","text":"Introduction to Circles Brief Overview 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 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 through the equitable issuance of money to all participants. In pursuing this vision, Circles aims to: Introduce community currencies that reduce economic inequality by ensuring a baseline level of economic participation for all. Foster community connections and strengthen local economies through trust-based currency networks. Promote sustainable economic growth by implementing a demurrage system that discourages hoarding and encourages circulation. Provide a flexible framework for various economic experiments and community-driven initiatives. 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 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 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 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: 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: 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 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. 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 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. This system ensures that: The currency remains active and circulating within the community. 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 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: 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). Demurrage Rate: All Circles undergo a 7% annual demurrage, applied on a daily basis. 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. 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 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. Practical Implications: 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. 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. 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.","title":"Introduction"},{"location":"introduction/#introduction-to-circles","text":"","title":"Introduction to Circles"},{"location":"introduction/#brief-overview","text":"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 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.","title":"Brief Overview"},{"location":"introduction/#purpose-and-goals-of-circles","text":"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: Introduce community currencies that reduce economic inequality by ensuring a baseline level of economic participation for all. Foster community connections and strengthen local economies through trust-based currency networks. Promote sustainable economic growth by implementing a demurrage system that discourages hoarding and encourages circulation. Provide a flexible framework for various economic experiments and community-driven initiatives. Empower individuals and communities to have greater control over their economic interactions and monetary systems.","title":"Purpose and Goals of Circles"},{"location":"introduction/#key-concepts","text":"","title":"Key Concepts"},{"location":"introduction/#personal-currencies","text":"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 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.","title":"Personal Currencies"},{"location":"introduction/#trust-networks","text":"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: 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: 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.","title":"Trust Networks"},{"location":"introduction/#demurrage","text":"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. 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 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. This system ensures that: The currency remains active and circulating within the community. 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 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.","title":"Demurrage"},{"location":"introduction/#total-supply-and-equilibrium","text":"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: 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). Demurrage Rate: All Circles undergo a 7% annual demurrage, applied on a daily basis. 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. 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 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. Practical Implications: 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. 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. 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.","title":"Total Supply and Equilibrium"},{"location":"advanced-topics/","text":"Advanced Topics These documents are written as deeper introduction to some of the technical workings of the Circles protocol. Inflation and demurrage calculations Path-based transactions and flow matrices","title":"Advanced Topics"},{"location":"advanced-topics/#advanced-topics","text":"These documents are written as deeper introduction to some of the technical workings of the Circles protocol. Inflation and demurrage calculations Path-based transactions and flow matrices","title":"Advanced Topics"},{"location":"advanced-topics/group-mint-policies/","text":"","title":"Group Mint Policies"},{"location":"advanced-topics/inflation-demurrage/","text":"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 Annual Rate : 7% reduction in token balances per year Daily Application : Calculated and applied on a per-day basis Universal : Affects all Circles tokens equally ERC1155 Interface and Demurrage Circles extends the standard ERC1155 interface to handle demurrage. Key functions include: Balance Queries 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. 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 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 to both sender and receiver if applicable. Token ID Convention Token IDs in Circles are derived from addresses: function toTokenId(address _avatar) public pure returns (uint256) { return uint256(uint160(_avatar)); } Demurrage Calculation Balance Reduction The system reduces token balances daily by a factor calculated as: Daily Factor = (1 - 0.07)^(1/365.25) \u2248 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 On-Demand Calculation : Balance reductions are computed when balances are accessed (through view functions) or computed and updated when modified (through transfers). Token Burning : The reduction in balance burns the amount that gets demurraged, effectively removing these tokens from circulation. Gas Efficiency : On-demand calculation avoids the need for daily update transactions. Precision : 128-bit fixed-point arithmetic ensures high accuracy in calculations, allowing for daily updates. Development Guidelines Always use balanceOf() or balanceOfOnDay() to get current, demurraged balances. On the hub contract, all amounts are to be understood as demurraged amounts on the current day. Be aware that token balances decrease over time, even without explicit transfers or actions. 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. 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 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: 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). Day Calculation : Days are calculated as the number of whole days passed since Inflation Day Zero. 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 When querying balances, the current day is always used to calculate the up-to-date demurraged balance. For future projections, you can specify a different day using balanceOfOnDay() . 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: function convertInflationaryToDemurrageValue(uint256 _amount, uint64 _day) public view returns (uint256) Converts an inflationary amount to its demurraged equivalent as of the specified day. function convertDemurrageToInflationaryValue(uint256 _amount, uint64 _dayUpdated) public view returns (uint256) Converts a demurraged amount as on the day provided to its inflationary equivalent. 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.","title":"Inflation and Demurrage"},{"location":"advanced-topics/inflation-demurrage/#demurrage-mechanism-in-circles-developers-guide","text":"","title":"Demurrage Mechanism in Circles: Developer's Guide"},{"location":"advanced-topics/inflation-demurrage/#overview","text":"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.","title":"Overview"},{"location":"advanced-topics/inflation-demurrage/#key-features-of-demurrage-in-circles","text":"Annual Rate : 7% reduction in token balances per year Daily Application : Calculated and applied on a per-day basis Universal : Affects all Circles tokens equally","title":"Key Features of Demurrage in Circles"},{"location":"advanced-topics/inflation-demurrage/#erc1155-interface-and-demurrage","text":"Circles extends the standard ERC1155 interface to handle demurrage. Key functions include:","title":"ERC1155 Interface and Demurrage"},{"location":"advanced-topics/inflation-demurrage/#balance-queries","text":"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. 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).","title":"Balance Queries"},{"location":"advanced-topics/inflation-demurrage/#transfers","text":"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 to both sender and receiver if applicable.","title":"Transfers"},{"location":"advanced-topics/inflation-demurrage/#token-id-convention","text":"Token IDs in Circles are derived from addresses: function toTokenId(address _avatar) public pure returns (uint256) { return uint256(uint160(_avatar)); }","title":"Token ID Convention"},{"location":"advanced-topics/inflation-demurrage/#demurrage-calculation","text":"","title":"Demurrage Calculation"},{"location":"advanced-topics/inflation-demurrage/#balance-reduction","text":"The system reduces token balances daily by a factor calculated as: Daily Factor = (1 - 0.07)^(1/365.25) \u2248 0.99980813 This results in a compound 7% reduction over a full year.","title":"Balance Reduction"},{"location":"advanced-topics/inflation-demurrage/#practical-effects","text":"A balance of 100 Circles reduces to approximately 99.98081 Circles after one day Over 365 days, 100 Circles reduces to about 93 Circles","title":"Practical Effects"},{"location":"advanced-topics/inflation-demurrage/#implementation-considerations","text":"On-Demand Calculation : Balance reductions are computed when balances are accessed (through view functions) or computed and updated when modified (through transfers). Token Burning : The reduction in balance burns the amount that gets demurraged, effectively removing these tokens from circulation. Gas Efficiency : On-demand calculation avoids the need for daily update transactions. Precision : 128-bit fixed-point arithmetic ensures high accuracy in calculations, allowing for daily updates.","title":"Implementation Considerations"},{"location":"advanced-topics/inflation-demurrage/#development-guidelines","text":"Always use balanceOf() or balanceOfOnDay() to get current, demurraged balances. On the hub contract, all amounts are to be understood as demurraged amounts on the current day. Be aware that token balances decrease over time, even without explicit transfers or actions. 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.","title":"Development Guidelines"},{"location":"advanced-topics/inflation-demurrage/#time-and-day-calculation-in-circles","text":"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.","title":"Time and Day Calculation in Circles"},{"location":"advanced-topics/inflation-demurrage/#the-day-function","text":"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: 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). Day Calculation : Days are calculated as the number of whole days passed since Inflation Day Zero. Usage : This day number is used in all demurrage calculations to determine how much a balance has decreased over time.","title":"The day Function"},{"location":"advanced-topics/inflation-demurrage/#demurrage-vs-inflationary-balances","text":"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.","title":"Demurrage vs Inflationary Balances"},{"location":"advanced-topics/inflation-demurrage/#practical-implications","text":"When querying balances, the current day is always used to calculate the up-to-date demurraged balance. For future projections, you can specify a different day using balanceOfOnDay() . When converting between demurrage and inflationary representations, the day parameter determines the point in time for the conversion.","title":"Practical Implications"},{"location":"advanced-topics/inflation-demurrage/#helper-functions-for-inflationary-conversion","text":"Circles provides two helper functions to convert between demurraged and inflationary representations: function convertInflationaryToDemurrageValue(uint256 _amount, uint64 _day) public view returns (uint256) Converts an inflationary amount to its demurraged equivalent as of the specified day. function convertDemurrageToInflationaryValue(uint256 _amount, uint64 _dayUpdated) public view returns (uint256) Converts a demurraged amount as on the day provided to its inflationary equivalent.","title":"Helper Functions for Inflationary Conversion"},{"location":"advanced-topics/inflation-demurrage/#conclusion","text":"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.","title":"Conclusion"},{"location":"advanced-topics/path-based-transactions/","text":"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 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 A flow matrix consists of the following components: 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. 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). 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. 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, 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 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 (where the arrow means \"trusts\"): 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: +----------+-----+-----+-----+-----+-----+ | | 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): A-B: Alice sends 8 of her own Circles (A) to Bob. (amount = 8, streamSinkId = 0) coordinates (A, A, B) B-D: Bob sends 4 of Charlie's Circles (C) to David. (amount = 4, streamSinkId = 2) coordinates (C, B, D) B-C: Bob sends 5 of his own Circles (B) to Charlie. (amount = 5, streamSinkId = 0) coordinates (B, B, C) B-D: Bob sends 3 of Charlie's Circles (C) to David. (amount = 3, streamSinkId = 1) coordinates (C, D, D) 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). 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: Function Signature function operateFlowMatrix( address[] calldata _flowVertices, FlowEdge[] calldata _flow, Stream[] calldata _streams, bytes calldata _packedCoordinates ) external nonReentrant(0) Key Steps in Processing The function performs several crucial steps: Unpacking Coordinates : The packed coordinates are unpacked into an array of uint16 values. Authorization Check : Ensures all senders (as listed in the streams) have authorized the operator calling this function (with ERC1155::setApprovalForAll() ). Flow Matrix Verification : Checks the correctness of the flow matrix, including trust relationships and avatar registrations. Path Transfers : Executes the individual transfers defined by the flow edges. Acceptance Checks : Calls acceptance checks for the streams and calculates the netted flows. Flow Matching : Ensures the netted flows from streams match the verified flow matrix. The important internal functions that accomplish these above steps are the following: _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. Minting Group Circles along a Path 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. How Group Minting Works in Path Transactions 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. Collateral for Minting : The tokens being sent to the group in this flow edge are used as collateral for minting new group Circles. Automatic Minting : The _groupMint function is called internally, creating new group Circles based on the collateral provided. 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. Implementation Details The _effectPathTransfers function in the Hub contract handles the minting of group Circles within a path: 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 Implicit Minting : Group minting occurs automatically when a group is the receiver in a flow edge, without requiring explicit minting instructions. Collateral Transfer : The tokens sent to the group are transferred to the group's treasury contract as collateral. Mint Policy Checks : The group's mint policy is consulted to ensure the minting operation is valid according to the group's rules. 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). 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 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 Consented Flow Trust Implies a Flow Edge The default behavior for Circles is such that if one avatar trusts another avatar, they attest that: Token Acceptance : They are willing to accept the trusted avatar's personal Circles tokens as payment. 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. Network Facilitation : They contribute to the overall liquidity and connectivity of the Circles network by creating a potential path for transactions. Value Recognition : They recognize some form of value or merit in the trusted avatar's economic activity or contribution to the community. 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. 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 Opt-In Feature : Avatars must explicitly enable consented flow by setting an advanced usage flag. 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. 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. 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. 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): 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. Consented Flow Check : If the sender has consented flow enabled (checked via advancedUsageFlags ), additional checks are performed: The sender must trust the receiver. The receiver must also have consented flow enabled. Return Value : Returns true if the flow is permitted based on the above checks. Returns false otherwise. Implications of Consented Flow Enhanced Security : Provides an additional layer of control for avatars concerned about unauthorized use of their tokens. 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. Network Dynamics : Could influence the overall structure and behavior of the Circles trust network, potentially leading to more tightly-knit, high-trust sub-networks. 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 The Circles ecosystem implements path-based transactions using flow matrices to enable multi-hop transfers of personal and group tokens. This system allows for: Complex transfers between indirectly connected avatars Automatic group token minting within transaction paths 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.","title":"Path-based Transactions"},{"location":"advanced-topics/path-based-transactions/#path-based-transactions-and-flow-matrices","text":"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.","title":"Path-based Transactions and Flow Matrices"},{"location":"advanced-topics/path-based-transactions/#concept-overview","text":"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.","title":"Concept Overview"},{"location":"advanced-topics/path-based-transactions/#flow-matrices","text":"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).","title":"Flow Matrices"},{"location":"advanced-topics/path-based-transactions/#structure-of-a-flow-matrix","text":"A flow matrix consists of the following components: 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. 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). 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. 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, and they get settled on-chain as single path (while still performing the acceptance checks for each stream's receiver).","title":"Structure of a Flow Matrix"},{"location":"advanced-topics/path-based-transactions/#an-example-of-a-flow-matrix","text":"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 (where the arrow means \"trusts\"): 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: +----------+-----+-----+-----+-----+-----+ | | 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.","title":"An example of a flow matrix"},{"location":"advanced-topics/path-based-transactions/#flow-edges-explanation","text":"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): A-B: Alice sends 8 of her own Circles (A) to Bob. (amount = 8, streamSinkId = 0) coordinates (A, A, B) B-D: Bob sends 4 of Charlie's Circles (C) to David. (amount = 4, streamSinkId = 2) coordinates (C, B, D) B-C: Bob sends 5 of his own Circles (B) to Charlie. (amount = 5, streamSinkId = 0) coordinates (B, B, C) B-D: Bob sends 3 of Charlie's Circles (C) to David. (amount = 3, streamSinkId = 1) coordinates (C, D, D) C-E: Charlie sends 5 of David's Circles (D) to Eva. (amount = 5, streamSinkId = 3) coordinates (D, C, E)","title":"Flow edges Explanation"},{"location":"advanced-topics/path-based-transactions/#stream-explanation","text":"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","title":"Stream Explanation"},{"location":"advanced-topics/path-based-transactions/#net-flow-and-consistency-check","text":"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.","title":"Net Flow and Consistency Check"},{"location":"advanced-topics/path-based-transactions/#technical-implementation","text":"The Hub contract implements path-based transactions through the operateFlowMatrix function. Let's break down its key components:","title":"Technical Implementation"},{"location":"advanced-topics/path-based-transactions/#function-signature","text":"function operateFlowMatrix( address[] calldata _flowVertices, FlowEdge[] calldata _flow, Stream[] calldata _streams, bytes calldata _packedCoordinates ) external nonReentrant(0)","title":"Function Signature"},{"location":"advanced-topics/path-based-transactions/#key-steps-in-processing","text":"The function performs several crucial steps: Unpacking Coordinates : The packed coordinates are unpacked into an array of uint16 values. Authorization Check : Ensures all senders (as listed in the streams) have authorized the operator calling this function (with ERC1155::setApprovalForAll() ). Flow Matrix Verification : Checks the correctness of the flow matrix, including trust relationships and avatar registrations. Path Transfers : Executes the individual transfers defined by the flow edges. Acceptance Checks : Calls acceptance checks for the streams and calculates the netted flows. Flow Matching : Ensures the netted flows from streams match the verified flow matrix. The important internal functions that accomplish these above steps are the following: _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.","title":"Key Steps in Processing"},{"location":"advanced-topics/path-based-transactions/#minting-group-circles-along-a-path","text":"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.","title":"Minting Group Circles along a Path"},{"location":"advanced-topics/path-based-transactions/#how-group-minting-works-in-path-transactions","text":"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. Collateral for Minting : The tokens being sent to the group in this flow edge are used as collateral for minting new group Circles. Automatic Minting : The _groupMint function is called internally, creating new group Circles based on the collateral provided. 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.","title":"How Group Minting Works in Path Transactions"},{"location":"advanced-topics/path-based-transactions/#implementation-details","text":"The _effectPathTransfers function in the Hub contract handles the minting of group Circles within a path: 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 ); }","title":"Implementation Details"},{"location":"advanced-topics/path-based-transactions/#key-aspects-of-group-minting-in-paths","text":"Implicit Minting : Group minting occurs automatically when a group is the receiver in a flow edge, without requiring explicit minting instructions. Collateral Transfer : The tokens sent to the group are transferred to the group's treasury contract as collateral. Mint Policy Checks : The group's mint policy is consulted to ensure the minting operation is valid according to the group's rules. 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). 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).","title":"Key Aspects of Group Minting in Paths"},{"location":"advanced-topics/path-based-transactions/#implications-and-benefits","text":"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 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]","title":"Implications and Benefits"},{"location":"advanced-topics/path-based-transactions/#trust-and-consented-flow","text":"","title":"Trust and Consented Flow"},{"location":"advanced-topics/path-based-transactions/#trust-implies-a-flow-edge","text":"The default behavior for Circles is such that if one avatar trusts another avatar, they attest that: Token Acceptance : They are willing to accept the trusted avatar's personal Circles tokens as payment. 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. Network Facilitation : They contribute to the overall liquidity and connectivity of the Circles network by creating a potential path for transactions. Value Recognition : They recognize some form of value or merit in the trusted avatar's economic activity or contribution to the community. 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. 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.","title":"Trust Implies a Flow Edge"},{"location":"advanced-topics/path-based-transactions/#consented-flow","text":"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.","title":"Consented Flow"},{"location":"advanced-topics/path-based-transactions/#key-aspects-of-consented-flow","text":"Opt-In Feature : Avatars must explicitly enable consented flow by setting an advanced usage flag. 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. 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. 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. 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.","title":"Key Aspects of Consented Flow"},{"location":"advanced-topics/path-based-transactions/#behaviour-details","text":"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): 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. Consented Flow Check : If the sender has consented flow enabled (checked via advancedUsageFlags ), additional checks are performed: The sender must trust the receiver. The receiver must also have consented flow enabled. Return Value : Returns true if the flow is permitted based on the above checks. Returns false otherwise.","title":"Behaviour Details"},{"location":"advanced-topics/path-based-transactions/#implications-of-consented-flow","text":"Enhanced Security : Provides an additional layer of control for avatars concerned about unauthorized use of their tokens. 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. Network Dynamics : Could influence the overall structure and behavior of the Circles trust network, potentially leading to more tightly-knit, high-trust sub-networks. 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.","title":"Implications of Consented Flow"},{"location":"advanced-topics/path-based-transactions/#conclusion","text":"The Circles ecosystem implements path-based transactions using flow matrices to enable multi-hop transfers of personal and group tokens. This system allows for: Complex transfers between indirectly connected avatars Automatic group token minting within transaction paths 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.","title":"Conclusion"}]}
\ No newline at end of file
+{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"Circles Documentation Welcome to the Circles documentation. This guide will help you understand the Circles project, its architecture, and core functionalities. Table of Contents Introduction to Circles Brief overview of the Circles project Purpose and goals of Circles Key concepts: personal currencies, trust networks, and demurrage Total Supply and Equilibrium Architectural Overview System Architecture Diagram Core Components Token Representations Circles v1 Components (legacy) Advanced Topics Inflation and demurrage calculations Path-based transactions and flow matrices","title":"Home"},{"location":"#circles-documentation","text":"Welcome to the Circles documentation. This guide will help you understand the Circles project, its architecture, and core functionalities.","title":"Circles Documentation"},{"location":"#table-of-contents","text":"Introduction to Circles Brief overview of the Circles project Purpose and goals of Circles Key concepts: personal currencies, trust networks, and demurrage Total Supply and Equilibrium Architectural Overview System Architecture Diagram Core Components Token Representations Circles v1 Components (legacy) Advanced Topics Inflation and demurrage calculations Path-based transactions and flow matrices","title":"Table of Contents"},{"location":"about/","text":"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. 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. 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: 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.","title":"About"},{"location":"about/#about-the-circles-protocol","text":"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.","title":"About the Circles Protocol"},{"location":"about/#disclaimer","text":"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.","title":"Disclaimer"},{"location":"about/#licensing","text":"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.","title":"Licensing"},{"location":"architecture/","text":"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. System Architecture Diagram 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 Demurrage of all Circles tokens equally The Hub v2 contract implements the ERC1155 standard, allowing it to handle multiple token types efficiently. Code: /src/hub/Hub.sol NameRegistry 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 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. This Migration system ensures a controlled and secure transition from Circles v1 to v2, maintaining integrity throughout the upgrade process. Code: /src/migration/Migration.sol Groups, Policies and Treasury Circles allows the definition of 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 Purpose : Manages collateral for group currencies Key Features : Acts as a factory for Vaults Handles minting and redemption of group Circles Interacts with Mint Policies for redemption logic Functions : onERC1155Received : Handles single token transfers (minting or redemption) onERC1155BatchReceived : Handles batch token transfers (minting) Creates Vaults for groups as needed Vaults Purpose : Securely store collateral for group currencies Key Features : Deployed by Standard Treasury using a factory pattern Each group has its own Vault Functions : returnCollateral : Sends collateral back to users during redemption burnCollateral : Burns collateral as specified by Mint Policy Base Mint Policy Purpose : Defines rules for minting, burning, and redeeming group currencies Key Features : Customizable for different group needs Default implementation allows all mints/burns and user-specified redemptions Functions : beforeMintPolicy : Validates minting requests beforeBurnPolicy : Validates burning requests beforeRedeemPolicy : Specifies redemption logic System Interaction Group Creation : User calls hub.registerGroup() Hub assigns Standard Treasury Standard Treasury creates a Vault for the group Minting Group Circles : Collateral transferred to Treasury Treasury forwards collateral to group's Vault Mint Policy consulted for approval Group Circles minted to user 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 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: Demurrage ERC20 : Represents Circles with the demurrage (decay) factor applied. 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.","title":"Architectural Overview"},{"location":"architecture/#circles-architectural-overview","text":"","title":"Circles Architectural Overview"},{"location":"architecture/#introduction","text":"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.","title":"Introduction"},{"location":"architecture/#system-architecture-diagram","text":"Open Circles Architecture diagram in new tab","title":"System Architecture Diagram"},{"location":"architecture/#core-components","text":"","title":"Core Components"},{"location":"architecture/#hub-v2-circles","text":"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 Demurrage of all Circles tokens equally The Hub v2 contract implements the ERC1155 standard, allowing it to handle multiple token types efficiently. Code: /src/hub/Hub.sol","title":"Hub v2 (Circles)"},{"location":"architecture/#nameregistry","text":"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","title":"NameRegistry"},{"location":"architecture/#migration","text":"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. This Migration system ensures a controlled and secure transition from Circles v1 to v2, maintaining integrity throughout the upgrade process. Code: /src/migration/Migration.sol","title":"Migration"},{"location":"architecture/#groups-policies-and-treasury","text":"Circles allows the definition of group currencies, which involves several interconnected components:","title":"Groups, Policies and Treasury"},{"location":"architecture/#groups","text":"Defined in the Hub contract Require a Mint Policy and Treasury for creation Can be registered using hub.registerGroup()","title":"Groups"},{"location":"architecture/#standard-treasury","text":"Purpose : Manages collateral for group currencies Key Features : Acts as a factory for Vaults Handles minting and redemption of group Circles Interacts with Mint Policies for redemption logic Functions : onERC1155Received : Handles single token transfers (minting or redemption) onERC1155BatchReceived : Handles batch token transfers (minting) Creates Vaults for groups as needed","title":"Standard Treasury"},{"location":"architecture/#vaults","text":"Purpose : Securely store collateral for group currencies Key Features : Deployed by Standard Treasury using a factory pattern Each group has its own Vault Functions : returnCollateral : Sends collateral back to users during redemption burnCollateral : Burns collateral as specified by Mint Policy","title":"Vaults"},{"location":"architecture/#base-mint-policy","text":"Purpose : Defines rules for minting, burning, and redeeming group currencies Key Features : Customizable for different group needs Default implementation allows all mints/burns and user-specified redemptions Functions : beforeMintPolicy : Validates minting requests beforeBurnPolicy : Validates burning requests beforeRedeemPolicy : Specifies redemption logic","title":"Base Mint Policy"},{"location":"architecture/#system-interaction","text":"Group Creation : User calls hub.registerGroup() Hub assigns Standard Treasury Standard Treasury creates a Vault for the group Minting Group Circles : Collateral transferred to Treasury Treasury forwards collateral to group's Vault Mint Policy consulted for approval Group Circles minted to user 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.","title":"System Interaction"},{"location":"architecture/#token-representations","text":"","title":"Token Representations"},{"location":"architecture/#circles-erc1155","text":"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.","title":"Circles (ERC1155)"},{"location":"architecture/#wrappers","text":"To enhance compatibility with existing DeFi ecosystems, Circles provides ERC20 wrappers: Demurrage ERC20 : Represents Circles with the demurrage (decay) factor applied. Inflationary ERC20 : Represents Circles in their inflationary form, without demurrage applied.","title":"Wrappers"},{"location":"architecture/#erc20lift","text":"The ERC20Lift contract serves as a bridge between the ERC1155 and ERC20 representations, allowing users to wrap and unwrap their Circles tokens as needed.","title":"ERC20Lift"},{"location":"architecture/#circles-v1-components-legacy","text":"","title":"Circles v1 Components (Legacy)"},{"location":"architecture/#hub-v1","text":"The original Hub contract from Circles v1, which is being phased out but remains relevant for migration purposes.","title":"Hub v1"},{"location":"architecture/#token","text":"The individual ERC20 token contracts for personal currencies in Circles v1.","title":"Token"},{"location":"architecture/#external-interactions","text":"","title":"External Interactions"},{"location":"architecture/#gnosis-chain","text":"Circles is built on the Gnosis Chain, leveraging its security and efficiency.","title":"Gnosis Chain"},{"location":"architecture/#safe","text":"Integration with Safe (formerly Gnosis Safe) provides secure multi-signature wallet functionality for Circles users.","title":"Safe"},{"location":"architecture/#eoa-externally-owned-accounts","text":"Standard Ethereum accounts that can interact with the Circles system.","title":"EoA (Externally Owned Accounts)"},{"location":"architecture/#advanced-features-and-extensions","text":"","title":"Advanced Features and Extensions"},{"location":"architecture/#intent-solver-competition","text":"(Placeholder) A mechanism for optimizing transactions and transfers within the Circles network.","title":"Intent Solver Competition"},{"location":"architecture/#pre-post-hooks-on-intents","text":"(Placeholder) Additional logic that can be executed before or after certain operations in the system.","title":"Pre-/Post-hooks on Intents"},{"location":"architecture/#flow-matrix-and-erc1155","text":"A system for managing and executing complex transfers and exchanges of Circles currencies between multiple parties.","title":"Flow Matrix and ERC1155"},{"location":"architecture/#single-transferthrough-for-v1-pathfinder","text":"A mechanism to facilitate transfers using trust pathways, likely a carryover or adaptation from the v1 system.","title":"Single TransferThrough for v1 Pathfinder"},{"location":"architecture/#account-abstraction","text":"(Placeholder) Advanced account management features that may simplify user interactions with the system.","title":"Account Abstraction"},{"location":"architecture/#custom-treasuries","text":"In addition to the Standard Treasury, the system allows for custom treasury implementations to cater to specific group needs.","title":"Custom Treasuries"},{"location":"architecture/#community-dapps","text":"The architecture supports the development of community-driven decentralized applications, such as a potential CowSwap v2 integration.","title":"Community dApps"},{"location":"architecture/#conclusion","text":"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.","title":"Conclusion"},{"location":"introduction/","text":"Introduction to Circles Brief Overview 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 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 through the equitable issuance of money to all participants. In pursuing this vision, Circles aims to: Introduce community currencies that reduce economic inequality by ensuring a baseline level of economic participation for all. Foster community connections and strengthen local economies through trust-based currency networks. Promote sustainable economic growth by implementing a demurrage system that discourages hoarding and encourages circulation. Provide a flexible framework for various economic experiments and community-driven initiatives. 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 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 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 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: 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: 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 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. 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 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. This system ensures that: The currency remains active and circulating within the community. 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 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: 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). Demurrage Rate: All Circles undergo a 7% annual demurrage, applied on a daily basis. 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. 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 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. Practical Implications: 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. 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. 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.","title":"Introduction"},{"location":"introduction/#introduction-to-circles","text":"","title":"Introduction to Circles"},{"location":"introduction/#brief-overview","text":"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 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.","title":"Brief Overview"},{"location":"introduction/#purpose-and-goals-of-circles","text":"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: Introduce community currencies that reduce economic inequality by ensuring a baseline level of economic participation for all. Foster community connections and strengthen local economies through trust-based currency networks. Promote sustainable economic growth by implementing a demurrage system that discourages hoarding and encourages circulation. Provide a flexible framework for various economic experiments and community-driven initiatives. Empower individuals and communities to have greater control over their economic interactions and monetary systems.","title":"Purpose and Goals of Circles"},{"location":"introduction/#key-concepts","text":"","title":"Key Concepts"},{"location":"introduction/#personal-currencies","text":"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 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.","title":"Personal Currencies"},{"location":"introduction/#trust-networks","text":"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: 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: 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.","title":"Trust Networks"},{"location":"introduction/#demurrage","text":"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. 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 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. This system ensures that: The currency remains active and circulating within the community. 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 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.","title":"Demurrage"},{"location":"introduction/#total-supply-and-equilibrium","text":"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: 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). Demurrage Rate: All Circles undergo a 7% annual demurrage, applied on a daily basis. 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. 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 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. Practical Implications: 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. 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. 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.","title":"Total Supply and Equilibrium"},{"location":"advanced-topics/","text":"Advanced Topics These documents are written as deeper introduction to some of the technical workings of the Circles protocol. Inflation and demurrage calculations Path-based transactions and flow matrices","title":"Advanced Topics"},{"location":"advanced-topics/#advanced-topics","text":"These documents are written as deeper introduction to some of the technical workings of the Circles protocol. Inflation and demurrage calculations Path-based transactions and flow matrices","title":"Advanced Topics"},{"location":"advanced-topics/group-mint-policies/","text":"","title":"Group mint policies"},{"location":"advanced-topics/inflation-demurrage/","text":"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 Annual Rate : 7% reduction in token balances per year Daily Application : Calculated and applied on a per-day basis Universal : Affects all Circles tokens equally ERC1155 Interface and Demurrage Circles extends the standard ERC1155 interface to handle demurrage. Key functions include: Balance Queries 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. 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 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 to both sender and receiver if applicable. Token ID Convention Token IDs in Circles are derived from addresses: function toTokenId(address _avatar) public pure returns (uint256) { return uint256(uint160(_avatar)); } Demurrage Calculation Balance Reduction The system reduces token balances daily by a factor calculated as: Daily Factor = (1 - 0.07)^(1/365.25) \u2248 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 On-Demand Calculation : Balance reductions are computed when balances are accessed (through view functions) or computed and updated when modified (through transfers). Token Burning : The reduction in balance burns the amount that gets demurraged, effectively removing these tokens from circulation. Gas Efficiency : On-demand calculation avoids the need for daily update transactions. Precision : 128-bit fixed-point arithmetic ensures high accuracy in calculations, allowing for daily updates. Development Guidelines Always use balanceOf() or balanceOfOnDay() to get current, demurraged balances. On the hub contract, all amounts are to be understood as demurraged amounts on the current day. Be aware that token balances decrease over time, even without explicit transfers or actions. 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. 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 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: 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). Day Calculation : Days are calculated as the number of whole days passed since Inflation Day Zero. 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 When querying balances, the current day is always used to calculate the up-to-date demurraged balance. For future projections, you can specify a different day using balanceOfOnDay() . 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: function convertInflationaryToDemurrageValue(uint256 _amount, uint64 _day) public view returns (uint256) Converts an inflationary amount to its demurraged equivalent as of the specified day. function convertDemurrageToInflationaryValue(uint256 _amount, uint64 _dayUpdated) public view returns (uint256) Converts a demurraged amount as on the day provided to its inflationary equivalent. 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.","title":"Inflation and Demurrage"},{"location":"advanced-topics/inflation-demurrage/#demurrage-mechanism-in-circles-developers-guide","text":"","title":"Demurrage Mechanism in Circles: Developer's Guide"},{"location":"advanced-topics/inflation-demurrage/#overview","text":"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.","title":"Overview"},{"location":"advanced-topics/inflation-demurrage/#key-features-of-demurrage-in-circles","text":"Annual Rate : 7% reduction in token balances per year Daily Application : Calculated and applied on a per-day basis Universal : Affects all Circles tokens equally","title":"Key Features of Demurrage in Circles"},{"location":"advanced-topics/inflation-demurrage/#erc1155-interface-and-demurrage","text":"Circles extends the standard ERC1155 interface to handle demurrage. Key functions include:","title":"ERC1155 Interface and Demurrage"},{"location":"advanced-topics/inflation-demurrage/#balance-queries","text":"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. 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).","title":"Balance Queries"},{"location":"advanced-topics/inflation-demurrage/#transfers","text":"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 to both sender and receiver if applicable.","title":"Transfers"},{"location":"advanced-topics/inflation-demurrage/#token-id-convention","text":"Token IDs in Circles are derived from addresses: function toTokenId(address _avatar) public pure returns (uint256) { return uint256(uint160(_avatar)); }","title":"Token ID Convention"},{"location":"advanced-topics/inflation-demurrage/#demurrage-calculation","text":"","title":"Demurrage Calculation"},{"location":"advanced-topics/inflation-demurrage/#balance-reduction","text":"The system reduces token balances daily by a factor calculated as: Daily Factor = (1 - 0.07)^(1/365.25) \u2248 0.99980813 This results in a compound 7% reduction over a full year.","title":"Balance Reduction"},{"location":"advanced-topics/inflation-demurrage/#practical-effects","text":"A balance of 100 Circles reduces to approximately 99.98081 Circles after one day Over 365 days, 100 Circles reduces to about 93 Circles","title":"Practical Effects"},{"location":"advanced-topics/inflation-demurrage/#implementation-considerations","text":"On-Demand Calculation : Balance reductions are computed when balances are accessed (through view functions) or computed and updated when modified (through transfers). Token Burning : The reduction in balance burns the amount that gets demurraged, effectively removing these tokens from circulation. Gas Efficiency : On-demand calculation avoids the need for daily update transactions. Precision : 128-bit fixed-point arithmetic ensures high accuracy in calculations, allowing for daily updates.","title":"Implementation Considerations"},{"location":"advanced-topics/inflation-demurrage/#development-guidelines","text":"Always use balanceOf() or balanceOfOnDay() to get current, demurraged balances. On the hub contract, all amounts are to be understood as demurraged amounts on the current day. Be aware that token balances decrease over time, even without explicit transfers or actions. 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.","title":"Development Guidelines"},{"location":"advanced-topics/inflation-demurrage/#time-and-day-calculation-in-circles","text":"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.","title":"Time and Day Calculation in Circles"},{"location":"advanced-topics/inflation-demurrage/#the-day-function","text":"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: 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). Day Calculation : Days are calculated as the number of whole days passed since Inflation Day Zero. Usage : This day number is used in all demurrage calculations to determine how much a balance has decreased over time.","title":"The day Function"},{"location":"advanced-topics/inflation-demurrage/#demurrage-vs-inflationary-balances","text":"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.","title":"Demurrage vs Inflationary Balances"},{"location":"advanced-topics/inflation-demurrage/#practical-implications","text":"When querying balances, the current day is always used to calculate the up-to-date demurraged balance. For future projections, you can specify a different day using balanceOfOnDay() . When converting between demurrage and inflationary representations, the day parameter determines the point in time for the conversion.","title":"Practical Implications"},{"location":"advanced-topics/inflation-demurrage/#helper-functions-for-inflationary-conversion","text":"Circles provides two helper functions to convert between demurraged and inflationary representations: function convertInflationaryToDemurrageValue(uint256 _amount, uint64 _day) public view returns (uint256) Converts an inflationary amount to its demurraged equivalent as of the specified day. function convertDemurrageToInflationaryValue(uint256 _amount, uint64 _dayUpdated) public view returns (uint256) Converts a demurraged amount as on the day provided to its inflationary equivalent.","title":"Helper Functions for Inflationary Conversion"},{"location":"advanced-topics/inflation-demurrage/#conclusion","text":"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.","title":"Conclusion"},{"location":"advanced-topics/path-based-transactions/","text":"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 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 A flow matrix consists of the following components: 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. 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). 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. 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, 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 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 (where the arrow means \"trusts\"): 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: +----------+-----+-----+-----+-----+-----+ | | 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): A-B: Alice sends 8 of her own Circles (A) to Bob. (amount = 8, streamSinkId = 0) coordinates (A, A, B) B-D: Bob sends 4 of Charlie's Circles (C) to David. (amount = 4, streamSinkId = 2) coordinates (C, B, D) B-C: Bob sends 5 of his own Circles (B) to Charlie. (amount = 5, streamSinkId = 0) coordinates (B, B, C) B-D: Bob sends 3 of Charlie's Circles (C) to David. (amount = 3, streamSinkId = 1) coordinates (C, D, D) 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). 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: Function Signature function operateFlowMatrix( address[] calldata _flowVertices, FlowEdge[] calldata _flow, Stream[] calldata _streams, bytes calldata _packedCoordinates ) external nonReentrant(0) Key Steps in Processing The function performs several crucial steps: Unpacking Coordinates : The packed coordinates are unpacked into an array of uint16 values. Authorization Check : Ensures all senders (as listed in the streams) have authorized the operator calling this function (with ERC1155::setApprovalForAll() ). Flow Matrix Verification : Checks the correctness of the flow matrix, including trust relationships and avatar registrations. Path Transfers : Executes the individual transfers defined by the flow edges. Acceptance Checks : Calls acceptance checks for the streams and calculates the netted flows. Flow Matching : Ensures the netted flows from streams match the verified flow matrix. The important internal functions that accomplish these above steps are the following: _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. Minting Group Circles along a Path 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. How Group Minting Works in Path Transactions 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. Collateral for Minting : The tokens being sent to the group in this flow edge are used as collateral for minting new group Circles. Automatic Minting : The _groupMint function is called internally, creating new group Circles based on the collateral provided. 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. Implementation Details The _effectPathTransfers function in the Hub contract handles the minting of group Circles within a path: 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 Implicit Minting : Group minting occurs automatically when a group is the receiver in a flow edge, without requiring explicit minting instructions. Collateral Transfer : The tokens sent to the group are transferred to the group's treasury contract as collateral. Mint Policy Checks : The group's mint policy is consulted to ensure the minting operation is valid according to the group's rules. 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). 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 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 Consented Flow Trust Implies a Flow Edge The default behavior for Circles is such that if one avatar trusts another avatar, they attest that: Token Acceptance : They are willing to accept the trusted avatar's personal Circles tokens as payment. 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. Network Facilitation : They contribute to the overall liquidity and connectivity of the Circles network by creating a potential path for transactions. Value Recognition : They recognize some form of value or merit in the trusted avatar's economic activity or contribution to the community. 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. 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 Opt-In Feature : Avatars must explicitly enable consented flow by setting an advanced usage flag. 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. 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. 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. 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): 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. Consented Flow Check : If the sender has consented flow enabled (checked via advancedUsageFlags ), additional checks are performed: The sender must trust the receiver. The receiver must also have consented flow enabled. Return Value : Returns true if the flow is permitted based on the above checks. Returns false otherwise. Implications of Consented Flow Enhanced Security : Provides an additional layer of control for avatars concerned about unauthorized use of their tokens. 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. Network Dynamics : Could influence the overall structure and behavior of the Circles trust network, potentially leading to more tightly-knit, high-trust sub-networks. 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 The Circles ecosystem implements path-based transactions using flow matrices to enable multi-hop transfers of personal and group tokens. This system allows for: Complex transfers between indirectly connected avatars Automatic group token minting within transaction paths 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.","title":"Path-based Transactions"},{"location":"advanced-topics/path-based-transactions/#path-based-transactions-and-flow-matrices","text":"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.","title":"Path-based Transactions and Flow Matrices"},{"location":"advanced-topics/path-based-transactions/#concept-overview","text":"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.","title":"Concept Overview"},{"location":"advanced-topics/path-based-transactions/#flow-matrices","text":"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).","title":"Flow Matrices"},{"location":"advanced-topics/path-based-transactions/#structure-of-a-flow-matrix","text":"A flow matrix consists of the following components: 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. 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). 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. 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, and they get settled on-chain as single path (while still performing the acceptance checks for each stream's receiver).","title":"Structure of a Flow Matrix"},{"location":"advanced-topics/path-based-transactions/#an-example-of-a-flow-matrix","text":"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 (where the arrow means \"trusts\"): 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: +----------+-----+-----+-----+-----+-----+ | | 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.","title":"An example of a flow matrix"},{"location":"advanced-topics/path-based-transactions/#flow-edges-explanation","text":"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): A-B: Alice sends 8 of her own Circles (A) to Bob. (amount = 8, streamSinkId = 0) coordinates (A, A, B) B-D: Bob sends 4 of Charlie's Circles (C) to David. (amount = 4, streamSinkId = 2) coordinates (C, B, D) B-C: Bob sends 5 of his own Circles (B) to Charlie. (amount = 5, streamSinkId = 0) coordinates (B, B, C) B-D: Bob sends 3 of Charlie's Circles (C) to David. (amount = 3, streamSinkId = 1) coordinates (C, D, D) C-E: Charlie sends 5 of David's Circles (D) to Eva. (amount = 5, streamSinkId = 3) coordinates (D, C, E)","title":"Flow edges Explanation"},{"location":"advanced-topics/path-based-transactions/#stream-explanation","text":"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","title":"Stream Explanation"},{"location":"advanced-topics/path-based-transactions/#net-flow-and-consistency-check","text":"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.","title":"Net Flow and Consistency Check"},{"location":"advanced-topics/path-based-transactions/#technical-implementation","text":"The Hub contract implements path-based transactions through the operateFlowMatrix function. Let's break down its key components:","title":"Technical Implementation"},{"location":"advanced-topics/path-based-transactions/#function-signature","text":"function operateFlowMatrix( address[] calldata _flowVertices, FlowEdge[] calldata _flow, Stream[] calldata _streams, bytes calldata _packedCoordinates ) external nonReentrant(0)","title":"Function Signature"},{"location":"advanced-topics/path-based-transactions/#key-steps-in-processing","text":"The function performs several crucial steps: Unpacking Coordinates : The packed coordinates are unpacked into an array of uint16 values. Authorization Check : Ensures all senders (as listed in the streams) have authorized the operator calling this function (with ERC1155::setApprovalForAll() ). Flow Matrix Verification : Checks the correctness of the flow matrix, including trust relationships and avatar registrations. Path Transfers : Executes the individual transfers defined by the flow edges. Acceptance Checks : Calls acceptance checks for the streams and calculates the netted flows. Flow Matching : Ensures the netted flows from streams match the verified flow matrix. The important internal functions that accomplish these above steps are the following: _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.","title":"Key Steps in Processing"},{"location":"advanced-topics/path-based-transactions/#minting-group-circles-along-a-path","text":"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.","title":"Minting Group Circles along a Path"},{"location":"advanced-topics/path-based-transactions/#how-group-minting-works-in-path-transactions","text":"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. Collateral for Minting : The tokens being sent to the group in this flow edge are used as collateral for minting new group Circles. Automatic Minting : The _groupMint function is called internally, creating new group Circles based on the collateral provided. 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.","title":"How Group Minting Works in Path Transactions"},{"location":"advanced-topics/path-based-transactions/#implementation-details","text":"The _effectPathTransfers function in the Hub contract handles the minting of group Circles within a path: 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 ); }","title":"Implementation Details"},{"location":"advanced-topics/path-based-transactions/#key-aspects-of-group-minting-in-paths","text":"Implicit Minting : Group minting occurs automatically when a group is the receiver in a flow edge, without requiring explicit minting instructions. Collateral Transfer : The tokens sent to the group are transferred to the group's treasury contract as collateral. Mint Policy Checks : The group's mint policy is consulted to ensure the minting operation is valid according to the group's rules. 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). 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).","title":"Key Aspects of Group Minting in Paths"},{"location":"advanced-topics/path-based-transactions/#implications-and-benefits","text":"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 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]","title":"Implications and Benefits"},{"location":"advanced-topics/path-based-transactions/#trust-and-consented-flow","text":"","title":"Trust and Consented Flow"},{"location":"advanced-topics/path-based-transactions/#trust-implies-a-flow-edge","text":"The default behavior for Circles is such that if one avatar trusts another avatar, they attest that: Token Acceptance : They are willing to accept the trusted avatar's personal Circles tokens as payment. 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. Network Facilitation : They contribute to the overall liquidity and connectivity of the Circles network by creating a potential path for transactions. Value Recognition : They recognize some form of value or merit in the trusted avatar's economic activity or contribution to the community. 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. 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.","title":"Trust Implies a Flow Edge"},{"location":"advanced-topics/path-based-transactions/#consented-flow","text":"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.","title":"Consented Flow"},{"location":"advanced-topics/path-based-transactions/#key-aspects-of-consented-flow","text":"Opt-In Feature : Avatars must explicitly enable consented flow by setting an advanced usage flag. 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. 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. 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. 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.","title":"Key Aspects of Consented Flow"},{"location":"advanced-topics/path-based-transactions/#behaviour-details","text":"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): 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. Consented Flow Check : If the sender has consented flow enabled (checked via advancedUsageFlags ), additional checks are performed: The sender must trust the receiver. The receiver must also have consented flow enabled. Return Value : Returns true if the flow is permitted based on the above checks. Returns false otherwise.","title":"Behaviour Details"},{"location":"advanced-topics/path-based-transactions/#implications-of-consented-flow","text":"Enhanced Security : Provides an additional layer of control for avatars concerned about unauthorized use of their tokens. 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. Network Dynamics : Could influence the overall structure and behavior of the Circles trust network, potentially leading to more tightly-knit, high-trust sub-networks. 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.","title":"Implications of Consented Flow"},{"location":"advanced-topics/path-based-transactions/#conclusion","text":"The Circles ecosystem implements path-based transactions using flow matrices to enable multi-hop transfers of personal and group tokens. This system allows for: Complex transfers between indirectly connected avatars Automatic group token minting within transaction paths 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.","title":"Conclusion"}]}
\ No newline at end of file