Technical overview of

When we talk about Circles we need to separate between the core protocol (basically everything that happens on the blockchain) and a specific frontend/ wallet.

Currently the only frontend for Circles is - in the future we hope to have many more!
You can find the code here: GitHub - CirclesUBI/circles-myxogastria: Webapp and mobile client for Circles

Here is an overview.

  1. Ethereum Node
    this is a xDAI Node that can answer RPC requests

  2. The API can be found here:
    GitHub - CirclesUBI/circles-api: Offchain database and API service for Circles

  3. Gnosis Safe
    Every Circles user controls a Gnosis Safe - by default this Safe has one owner (private/public key pair) which can be derived from the 24 word seed phrase.
    It will be possible (in future versions) to change the owner or add other addresses as owner.
    Soon the Safe can also be loaded in the default Gnosis Safe UI here. The owner does not initiate transactions directly (which has the advantage that no xDAI is required) but instead only signed meta-transactions which are broadcasted to the network via a relay service. The relay service is payed a small amount of Circles for this.

  4. Postgres DB
    Most things stored here is data available from the blockchain. The only 2 exceptions are usernames and photos.

Currently several teams are looking into the option to create fully decentralized wallets. 2 design choices that will make this easier: don’t use the relay service (require the user to hold a tiny amount of xDAI on a signing key); do the pathfinding (max flow) calculation client side.


Thanks a lot for this info and clarification, very insightful.

For people interested in verifying the “backend” logic in the xDai Blockchain the Blockscout Explorer is very useful: there might be other Explorers for the xDai chain as well, any of them would work.


Can you point me to documentation about where the paymentNote is stored? I saw it in the APIs, but don’t find the actual implementation - is it off-chain?

Yes, currently the paymentNote is stored off-chain. You find the implementation here:

The API is documented here: circles-api/ at main · CirclesUBI/circles-api · GitHub