diff --git a/architecture/index.html b/architecture/index.html index 3ec5d5a..b4c3963 100644 --- a/architecture/index.html +++ b/architecture/index.html @@ -88,7 +88,7 @@

Token Representations

Circles (ERC1155)

-

The core representation of Circles currencies uses the ERC1155 standard, allowing for efficient management of multiple token types (personal and group currencies) within a single contract.

-

Wrappers

-

To enhance compatibility with existing DeFi ecosystems, Circles provides ERC20 wrappers:

-
    -
  1. Demurrage ERC20: Represents Circles with the demurrage (decay) factor applied.
    2. -
  2. Inflationary ERC20: Represents Circles in their inflationary form, without demurrage applied.
    3. -
+

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:

+ +

ERC20 Wrappers

+

To enhance compatibility with existing smart contract ecosystems, Circles provides two types of ERC20 wrappers:

+ +

For every Circles identifier (human or group Circles) either/both ERC20 contract can be deployed upon demand by calling hub:wrap(), and it will ensure the ERC20 contract is deployed if it doesn't already exist. ERC20 contracts can also be created explicitly before wrapping.

+

If the ERC20 contract already exists, one can also wrap the ERC1155 Circles into ERC20 by directly sending (the correct Circles) to the relevant ERC20 contract.

+

Both demurrage and inflationary ERC20 Circles can be converted back into demurraged ERC1155 Circles by calling ECR20:unwrap() as the owner of a balance on the desired ERC20 contract.

+

Both approaches allow Circles to interact more seamlessly with standard ERC20-compatible platforms and protocols while preserving the core economic principles of the Circles system.

+

ERC20 contracts also implement ERC-2612, aka ERC20Permit.

+

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.

+

The ERC20Lift contract serves as a factory-bridge between the ERC1155 and ERC20 representations, ensuring ERC20 contracts are deployed (ahead of time).

+

Code: /src/lift/ERC20Lift.sol

Circles v1 Components (Legacy)

Hub v1

The original Hub contract from Circles v1, which is being phased out but remains relevant for migration purposes.

diff --git a/index.html b/index.html index a6d260c..76916c1 100644 --- a/index.html +++ b/index.html @@ -219,5 +219,5 @@

Table of Contents

diff --git a/search/search_index.json b/search/search_index.json index a52fb25..171d6a4 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 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 The Circles ecosystem includes a system for managing group currencies, which allows communities and actors to create their own Circles with customizable policies. This system involves several interconnected components: Groups Group avatars (unlike human avatars) cannot mint Circles based on time. Rather group Circles are minted by collaterlising existing Circles into the group if the group trusts that collateral - and a group mint policy can further refine the conditions under which minting is possible. Groups register as a group avatar in the Hub contract. They have two registration options: registerGroup() : Uses the StandardTreasury contract (recommended). registerCustomGroup() : Allows the use of a custom treasury contract. It is recommended that all groups rely on the standard treasury contract. Users should exercise caution when interacting with custom groups. Groups require a MintPolicy upon registration, which defines the rules for minting, burning, and redeeming the group's currency. To explicitly mint group Circles, the owner of collateral for a group can call hub:groupMint() . Code: /src/hub/Hub.sol:groupMint() Standard Treasury The Standard Treasury manages collateral for group currencies: Handles minting (indirectly) and redemption of group Circles To mint group circles, the minter must act through the Hub contract: either by calling Hub:groupMint() , upon which the Hub will structure data for the treasury to forward the collateral to the correct vault of the group or over path-based transfers, Circles can be minted into group Circles on the fly if one sends collateral directly to the Standard Treasury without data or with incorrectly structured data, the treasury will reject the transfer to avoid that funds get lost as only the hub controls minting of group tokens if one sends tokens to the treasury with the correct data structure, bypassing the hub contract, the collateral will be locked in the treasury/vault, as the hub will not mint your equivalent group Circles To redeem group Cirlces for the underlying collateral from the Vault , the owner must send the group Circles to the treasury with a correctly structured data package: the treasury decodes the data to check whether the intent is to redeem the treasury passes the user data to the group mint policy, for it to determine the conditions of redemption (treasury is agnostic to data format for group mint policy) the treasury can execute the option of burning a portion of the collateral upon redemption the treasury can return the collateral to the redeemer -- but checks that the policy's burn amount and return amounts add up to the group currency amount onERC1155Received : Handles single token transfers (minting or redemption) onERC1155BatchReceived : Handles batch token transfers (minting) Acts as a factory for Vaults , deployed for each group to hold their collateral Creates Vaults for groups as needed Code: /src/treasury/StandardTreasury.sol Vaults Vaults securely store collateral for group currencies: Deployed by StandardTreasury using a factory pattern External functions only accessible by StandardTreasury Each group has its own Vault to easily query the balance of the vault address for that group Code: /src/treasury/StandardVault.sol Mint Policy Groups can assign a policy contract of their chosing upon registering. Once registered the policy address is immutable, but a policy contract be written: for one specific group, or to be reusable for many groups to rely on, to be stateful or stateless, can be parametrized with settable parameters with some governance can be deployed as an upgradeable proxy contract The BaseMintPolicy is the simplest possible definition for a sensible group policy. It serves as a reference implementation, but developers are invited to explore and build their own policies In general a group (mint) policy must be a contract that implements the rules for minting, burning, and redeeming group currencies: Customizable for different group needs Default implementation ( BaseMintPolicy.sol ) allows all mints/burns and user-specified collateral for redemptions beforeMintPolicy : Validates minting requests beforeBurnPolicy : Validates burning requests beforeRedeemPolicy : Specifies redemption logic Code: /src/groups/BaseMintPolicy.sol System Interaction Group Creation : User calls hub.registerGroup() Hub assigns Standard Treasury Standard Treasury creates a Vault for the group upon first group mint 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 Part of collateral burned if specified by policy This system provides a flexible 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. Remarks Circles permits the creation of groups with custom treasury contracts. However, the community should approach such groups with caution until these foreign treasury contracts have been thoroughly vetted. Groups have the capability to trust and accept other groups as collateral. This feature enables the construction of sophisticated hierarchical group structures. However, it also introduces the possibility of cyclical collateralization. While this doesn't increase the total number of Circles in circulation, it does allow for arbitrary inflation of collateral through repeated cyclic collateralization. To mitigate this risk, groups may implement protective measures within their group mint policy. 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 system for managing group currencies, which allows communities and actors to create their own Circles with customizable policies. This system involves several interconnected components:","title":"Groups, Policies and Treasury"},{"location":"architecture/#groups","text":"Group avatars (unlike human avatars) cannot mint Circles based on time. Rather group Circles are minted by collaterlising existing Circles into the group if the group trusts that collateral - and a group mint policy can further refine the conditions under which minting is possible. Groups register as a group avatar in the Hub contract. They have two registration options: registerGroup() : Uses the StandardTreasury contract (recommended). registerCustomGroup() : Allows the use of a custom treasury contract. It is recommended that all groups rely on the standard treasury contract. Users should exercise caution when interacting with custom groups. Groups require a MintPolicy upon registration, which defines the rules for minting, burning, and redeeming the group's currency. To explicitly mint group Circles, the owner of collateral for a group can call hub:groupMint() . Code: /src/hub/Hub.sol:groupMint()","title":"Groups"},{"location":"architecture/#standard-treasury","text":"The Standard Treasury manages collateral for group currencies: Handles minting (indirectly) and redemption of group Circles To mint group circles, the minter must act through the Hub contract: either by calling Hub:groupMint() , upon which the Hub will structure data for the treasury to forward the collateral to the correct vault of the group or over path-based transfers, Circles can be minted into group Circles on the fly if one sends collateral directly to the Standard Treasury without data or with incorrectly structured data, the treasury will reject the transfer to avoid that funds get lost as only the hub controls minting of group tokens if one sends tokens to the treasury with the correct data structure, bypassing the hub contract, the collateral will be locked in the treasury/vault, as the hub will not mint your equivalent group Circles To redeem group Cirlces for the underlying collateral from the Vault , the owner must send the group Circles to the treasury with a correctly structured data package: the treasury decodes the data to check whether the intent is to redeem the treasury passes the user data to the group mint policy, for it to determine the conditions of redemption (treasury is agnostic to data format for group mint policy) the treasury can execute the option of burning a portion of the collateral upon redemption the treasury can return the collateral to the redeemer -- but checks that the policy's burn amount and return amounts add up to the group currency amount onERC1155Received : Handles single token transfers (minting or redemption) onERC1155BatchReceived : Handles batch token transfers (minting) Acts as a factory for Vaults , deployed for each group to hold their collateral Creates Vaults for groups as needed Code: /src/treasury/StandardTreasury.sol","title":"Standard Treasury"},{"location":"architecture/#vaults","text":"Vaults securely store collateral for group currencies: Deployed by StandardTreasury using a factory pattern External functions only accessible by StandardTreasury Each group has its own Vault to easily query the balance of the vault address for that group Code: /src/treasury/StandardVault.sol","title":"Vaults"},{"location":"architecture/#mint-policy","text":"Groups can assign a policy contract of their chosing upon registering. Once registered the policy address is immutable, but a policy contract be written: for one specific group, or to be reusable for many groups to rely on, to be stateful or stateless, can be parametrized with settable parameters with some governance can be deployed as an upgradeable proxy contract The BaseMintPolicy is the simplest possible definition for a sensible group policy. It serves as a reference implementation, but developers are invited to explore and build their own policies In general a group (mint) policy must be a contract that implements the rules for minting, burning, and redeeming group currencies: Customizable for different group needs Default implementation ( BaseMintPolicy.sol ) allows all mints/burns and user-specified collateral for redemptions beforeMintPolicy : Validates minting requests beforeBurnPolicy : Validates burning requests beforeRedeemPolicy : Specifies redemption logic Code: /src/groups/BaseMintPolicy.sol","title":"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 upon first group mint 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 Part of collateral burned if specified by policy This system provides a flexible 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/#remarks","text":"Circles permits the creation of groups with custom treasury contracts. However, the community should approach such groups with caution until these foreign treasury contracts have been thoroughly vetted. Groups have the capability to trust and accept other groups as collateral. This feature enables the construction of sophisticated hierarchical group structures. However, it also introduces the possibility of cyclical collateralization. While this doesn't increase the total number of Circles in circulation, it does allow for arbitrary inflation of collateral through repeated cyclic collateralization. To mitigate this risk, groups may implement protective measures within their group mint policy.","title":"Remarks"},{"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 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 an economic system that aims to provide a fairly issued, socially-rooted monetary framework, foster community connections and promote active participation in the local economy. Total Supply and Equilibrium The Circles protocol implements an 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 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 an economic system that aims to provide a fairly issued, socially-rooted monetary framework, foster community connections and promote active participation in the local economy.","title":"Demurrage"},{"location":"introduction/#total-supply-and-equilibrium","text":"The Circles protocol implements an 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 The Circles ecosystem includes a system for managing group currencies, which allows communities and actors to create their own Circles with customizable policies. This system involves several interconnected components: Groups Group avatars (unlike human avatars) cannot mint Circles based on time. Rather group Circles are minted by collaterlising existing Circles into the group if the group trusts that collateral - and a group mint policy can further refine the conditions under which minting is possible. Groups register as a group avatar in the Hub contract. They have two registration options: registerGroup() : Uses the StandardTreasury contract (recommended). registerCustomGroup() : Allows the use of a custom treasury contract. It is recommended that all groups rely on the standard treasury contract. Users should exercise caution when interacting with custom groups. Groups require a MintPolicy upon registration, which defines the rules for minting, burning, and redeeming the group's currency. To explicitly mint group Circles, the owner of collateral for a group can call hub:groupMint() . Code: /src/hub/Hub.sol:groupMint() Standard Treasury The Standard Treasury manages collateral for group currencies: Handles minting (indirectly) and redemption of group Circles To mint group circles, the minter must act through the Hub contract: either by calling Hub:groupMint() , upon which the Hub will structure data for the treasury to forward the collateral to the correct vault of the group or over path-based transfers, Circles can be minted into group Circles on the fly if one sends collateral directly to the Standard Treasury without data or with incorrectly structured data, the treasury will reject the transfer to avoid that funds get lost as only the hub controls minting of group tokens if one sends tokens to the treasury with the correct data structure, bypassing the hub contract, the collateral will be locked in the treasury/vault, as the hub will not mint your equivalent group Circles To redeem group Cirlces for the underlying collateral from the Vault , the owner must send the group Circles to the treasury with a correctly structured data package: the treasury decodes the data to check whether the intent is to redeem the treasury passes the user data to the group mint policy, for it to determine the conditions of redemption (treasury is agnostic to data format for group mint policy) the treasury can execute the option of burning a portion of the collateral upon redemption the treasury can return the collateral to the redeemer -- but checks that the policy's burn amount and return amounts add up to the group currency amount onERC1155Received : Handles single token transfers (minting or redemption) onERC1155BatchReceived : Handles batch token transfers (minting) Acts as a factory for Vaults , deployed for each group to hold their collateral Creates Vaults for groups as needed Code: /src/treasury/StandardTreasury.sol Vaults Vaults securely store collateral for group currencies: Deployed by StandardTreasury using a factory pattern External functions only accessible by StandardTreasury Each group has its own Vault to easily query the balance of the vault address for that group Code: /src/treasury/StandardVault.sol Mint Policy Groups can assign a policy contract of their chosing upon registering. Once registered the policy address is immutable, but a policy contract be written: for one specific group, or to be reusable for many groups to rely on, to be stateful or stateless, can be parametrized with settable parameters with some governance can be deployed as an upgradeable proxy contract The BaseMintPolicy is the simplest possible definition for a sensible group policy. It serves as a reference implementation, but developers are invited to explore and build their own policies In general a group (mint) policy must be a contract that implements the rules for minting, burning, and redeeming group currencies: Customizable for different group needs Default implementation ( BaseMintPolicy.sol ) allows all mints/burns and user-specified collateral for redemptions beforeMintPolicy : Validates minting requests beforeBurnPolicy : Validates burning requests beforeRedeemPolicy : Specifies redemption logic Code: /src/groups/BaseMintPolicy.sol System Interaction Group Creation : User calls hub.registerGroup() Hub assigns Standard Treasury Standard Treasury creates a Vault for the group upon first group mint 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 Part of collateral burned if specified by policy This system provides a flexible 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. Remarks Circles permits the creation of groups with custom treasury contracts. However, the community should approach such groups with caution until these foreign treasury contracts have been thoroughly vetted. Groups have the capability to trust and accept other groups as collateral. This feature enables the construction of sophisticated hierarchical group structures. However, it also introduces the possibility of cyclical collateralization. While this doesn't increase the total number of Circles in circulation, it does allow for arbitrary inflation of collateral through repeated cyclic collateralization. To mitigate this risk, groups may implement protective measures within their group mint policy. 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: Code: /src/circles/Circles.sol Code: /src/circles/ERC1155.sol Code: /src/circles/DiscountedBalances.sol Code: /src/circles/Demurrage.sol ERC20 Wrappers To enhance compatibility with existing smart contract ecosystems, Circles provides two types of ERC20 wrappers: Demurrage ERC20 : This wrapper represents Circles with demurrage applied. It results in rebalancing amounts, reflecting the daily decrease in the balances over time over all Circles. Inflationary ERC20 : This wrapper represents Circles in their inflationary form. Balances remain static (when not transacted), but the issuance rate for personal Circles mints increases daily. This mechanism offsets the static supply of Circles in circulation. For every Circles identifier (human or group Circles) either/both ERC20 contract can be deployed upon demand by calling hub:wrap() , and it will ensure the ERC20 contract is deployed if it doesn't already exist. ERC20 contracts can also be created explicitly before wrapping. If the ERC20 contract already exists, one can also wrap the ERC1155 Circles into ERC20 by directly sending (the correct Circles) to the relevant ERC20 contract. Both demurrage and inflationary ERC20 Circles can be converted back into demurraged ERC1155 Circles by calling ECR20:unwrap() as the owner of a balance on the desired ERC20 contract. Both approaches allow Circles to interact more seamlessly with standard ERC20-compatible platforms and protocols while preserving the core economic principles of the Circles system. ERC20 contracts also implement ERC-2612 , aka ERC20Permit . Code: /src/lift/DemurrageCircles.sol Code: /src/lift/ERC20DiscountedBalances.sol Code: /src/lift/InflationaryCircles.sol Code: /src/lift/ERC20InflationaryBalances.sol Code: /src/circles/BatchedDemurrage.sol Code: /src/circles/Demurrage.sol ERC20Lift The ERC20Lift contract serves as a factory-bridge between the ERC1155 and ERC20 representations, ensuring ERC20 contracts are deployed (ahead of time). Code: /src/lift/ERC20Lift.sol 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 system for managing group currencies, which allows communities and actors to create their own Circles with customizable policies. This system involves several interconnected components:","title":"Groups, Policies and Treasury"},{"location":"architecture/#groups","text":"Group avatars (unlike human avatars) cannot mint Circles based on time. Rather group Circles are minted by collaterlising existing Circles into the group if the group trusts that collateral - and a group mint policy can further refine the conditions under which minting is possible. Groups register as a group avatar in the Hub contract. They have two registration options: registerGroup() : Uses the StandardTreasury contract (recommended). registerCustomGroup() : Allows the use of a custom treasury contract. It is recommended that all groups rely on the standard treasury contract. Users should exercise caution when interacting with custom groups. Groups require a MintPolicy upon registration, which defines the rules for minting, burning, and redeeming the group's currency. To explicitly mint group Circles, the owner of collateral for a group can call hub:groupMint() . Code: /src/hub/Hub.sol:groupMint()","title":"Groups"},{"location":"architecture/#standard-treasury","text":"The Standard Treasury manages collateral for group currencies: Handles minting (indirectly) and redemption of group Circles To mint group circles, the minter must act through the Hub contract: either by calling Hub:groupMint() , upon which the Hub will structure data for the treasury to forward the collateral to the correct vault of the group or over path-based transfers, Circles can be minted into group Circles on the fly if one sends collateral directly to the Standard Treasury without data or with incorrectly structured data, the treasury will reject the transfer to avoid that funds get lost as only the hub controls minting of group tokens if one sends tokens to the treasury with the correct data structure, bypassing the hub contract, the collateral will be locked in the treasury/vault, as the hub will not mint your equivalent group Circles To redeem group Cirlces for the underlying collateral from the Vault , the owner must send the group Circles to the treasury with a correctly structured data package: the treasury decodes the data to check whether the intent is to redeem the treasury passes the user data to the group mint policy, for it to determine the conditions of redemption (treasury is agnostic to data format for group mint policy) the treasury can execute the option of burning a portion of the collateral upon redemption the treasury can return the collateral to the redeemer -- but checks that the policy's burn amount and return amounts add up to the group currency amount onERC1155Received : Handles single token transfers (minting or redemption) onERC1155BatchReceived : Handles batch token transfers (minting) Acts as a factory for Vaults , deployed for each group to hold their collateral Creates Vaults for groups as needed Code: /src/treasury/StandardTreasury.sol","title":"Standard Treasury"},{"location":"architecture/#vaults","text":"Vaults securely store collateral for group currencies: Deployed by StandardTreasury using a factory pattern External functions only accessible by StandardTreasury Each group has its own Vault to easily query the balance of the vault address for that group Code: /src/treasury/StandardVault.sol","title":"Vaults"},{"location":"architecture/#mint-policy","text":"Groups can assign a policy contract of their chosing upon registering. Once registered the policy address is immutable, but a policy contract be written: for one specific group, or to be reusable for many groups to rely on, to be stateful or stateless, can be parametrized with settable parameters with some governance can be deployed as an upgradeable proxy contract The BaseMintPolicy is the simplest possible definition for a sensible group policy. It serves as a reference implementation, but developers are invited to explore and build their own policies In general a group (mint) policy must be a contract that implements the rules for minting, burning, and redeeming group currencies: Customizable for different group needs Default implementation ( BaseMintPolicy.sol ) allows all mints/burns and user-specified collateral for redemptions beforeMintPolicy : Validates minting requests beforeBurnPolicy : Validates burning requests beforeRedeemPolicy : Specifies redemption logic Code: /src/groups/BaseMintPolicy.sol","title":"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 upon first group mint 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 Part of collateral burned if specified by policy This system provides a flexible 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/#remarks","text":"Circles permits the creation of groups with custom treasury contracts. However, the community should approach such groups with caution until these foreign treasury contracts have been thoroughly vetted. Groups have the capability to trust and accept other groups as collateral. This feature enables the construction of sophisticated hierarchical group structures. However, it also introduces the possibility of cyclical collateralization. While this doesn't increase the total number of Circles in circulation, it does allow for arbitrary inflation of collateral through repeated cyclic collateralization. To mitigate this risk, groups may implement protective measures within their group mint policy.","title":"Remarks"},{"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: Code: /src/circles/Circles.sol Code: /src/circles/ERC1155.sol Code: /src/circles/DiscountedBalances.sol Code: /src/circles/Demurrage.sol","title":"Circles (ERC1155)"},{"location":"architecture/#erc20-wrappers","text":"To enhance compatibility with existing smart contract ecosystems, Circles provides two types of ERC20 wrappers: Demurrage ERC20 : This wrapper represents Circles with demurrage applied. It results in rebalancing amounts, reflecting the daily decrease in the balances over time over all Circles. Inflationary ERC20 : This wrapper represents Circles in their inflationary form. Balances remain static (when not transacted), but the issuance rate for personal Circles mints increases daily. This mechanism offsets the static supply of Circles in circulation. For every Circles identifier (human or group Circles) either/both ERC20 contract can be deployed upon demand by calling hub:wrap() , and it will ensure the ERC20 contract is deployed if it doesn't already exist. ERC20 contracts can also be created explicitly before wrapping. If the ERC20 contract already exists, one can also wrap the ERC1155 Circles into ERC20 by directly sending (the correct Circles) to the relevant ERC20 contract. Both demurrage and inflationary ERC20 Circles can be converted back into demurraged ERC1155 Circles by calling ECR20:unwrap() as the owner of a balance on the desired ERC20 contract. Both approaches allow Circles to interact more seamlessly with standard ERC20-compatible platforms and protocols while preserving the core economic principles of the Circles system. ERC20 contracts also implement ERC-2612 , aka ERC20Permit . Code: /src/lift/DemurrageCircles.sol Code: /src/lift/ERC20DiscountedBalances.sol Code: /src/lift/InflationaryCircles.sol Code: /src/lift/ERC20InflationaryBalances.sol Code: /src/circles/BatchedDemurrage.sol Code: /src/circles/Demurrage.sol","title":"ERC20 Wrappers"},{"location":"architecture/#erc20lift","text":"The ERC20Lift contract serves as a factory-bridge between the ERC1155 and ERC20 representations, ensuring ERC20 contracts are deployed (ahead of time). Code: /src/lift/ERC20Lift.sol","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 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 an economic system that aims to provide a fairly issued, socially-rooted monetary framework, foster community connections and promote active participation in the local economy. Total Supply and Equilibrium The Circles protocol implements an 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 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 an economic system that aims to provide a fairly issued, socially-rooted monetary framework, foster community connections and promote active participation in the local economy.","title":"Demurrage"},{"location":"introduction/#total-supply-and-equilibrium","text":"The Circles protocol implements an 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