Federation Options for CES2: Inter-Exchange Transaction Architecture

[olivier108]

Context

CES serves 1,000+ exchange groups globally through a single clearing central. As we develop CES2, we need federation architecture that enables:

• Transactions between CES exchanges
• Interoperability with partners (Community Forge, TimeOverflow, Komunitin)
• Decentralisation while managing complexity
• Efficient scaling for expected growth

Current CES Stats (main server incl. Australia)

320 active groups, ~30,000 transactions annually, 4,700 active users
Limited development resources, staged implementation needed

Federation Options

1. Current Clearing Central (Centralised)
   Single server handles all inter-exchange transactions.
   Pros: Simple, proven, minimal effort
   Cons: Single point of failure, blocks decentralisation
2. Credit Commons Protocol (Hierarchical)
   Regional nodes in tree structure, transactions escalate only as needed.
   Note: CES's Clearing Central was upgraded to a Credit Commons node, though CES servers still connect via the original API.
   Pros: Balanced decentralisation, proven DNS-like architecture, regional organization, already partially implemented in CES infrastructure
   Cons: More complex than current system, requires regional coordination, legacy API integration needed
3. Stellar Blockchain (Trust Line Network)
   Already used in Komunitin. Users establish explicit trust relationships, payments route through multiple trust paths (up to 6 hops) with automatic path-finding.
   Pros: Already implemented in partner system, proven at scale, fully decentralised, automatic optimisation
   Cons: Blockchain overhead, may be complex for current traffic levels

Key Questions

Protocol Choice: Which approach best balances decentralisation with implementation complexity?
Phased Implementation: Should we complete the Credit Commons integration (updating CES servers to use Credit Commons API) or explore other federation approaches?
Stellar Integration: Should we leverage existing Komunitin implementation or develop new solution?
Timeline: Implement in Version 4 milestone or prioritise differently?
Migration: Best transition path from centralised approach?

Expert Input Needed

@matslats (Credit Commons Protocol) - hierarchical federation architecture
@michielbdejong (Federated Bookkeeping) - peer-to-peer credit networks for inter-system communication
Community currency developers - practical inter-system trading experience
CES community - inter-exchange functionality requirements

What factors should we prioritise in choosing our federation approach?

[matslats]

This is to clarify about Credit Commons Protocol and Clearing central.
Note that I think option 1 should be removed, I explain why, below.
Tim build clearing central with an API that serves CES internal logic only.
Credit Commons API is intended to be general purpose.
I have switched the engine of clearing central so it is a credit commons node, but retained the old API. That means when CES v1 POSTs to clearing central it is converted into credit commons request processes and the response converted back. Similarly when clearing central forwards a request to CES1 server, it converts the request and converts the response. That means the data storage and config and scope of possibilities are all credcom.
Anyone can set up a credcom node, and any credcom node can register transactions with any other. This means Cforge, CES, CES Taiwan etc can all govern their own ledgers if they want to, make their own trading rules, and still trade with each other.

[matslats]

The most important difference between credit common and Kommunitin API is in what I call the strructures of credit that emerge. Credit commons leads to a tree, and Kommunitin to a mesh.
The tree can be governed at every level, which means managing inevitable trade imbalances. this means more politics but the network is less likely to freeze up because people are near their credit limits.
The mesh has a single rule-set. This means it is easier to set up and join but harder but if you don't join that specific mesh you can't play at all.
We could consider asking Esteve to implement some credit commons rules in the Kommunitin mesh but not before understanding which bits of each system are valuable.

[estevebadia]

Thanks @olivier108 for starting this exciting dicussion and @matslats for joining it! I'll try to summarize my experience with inter-exchange trading so far:

Back in the 2010's decade in Catalunya we had a vibrant movement of exchange communities. We used CES and then IntegralCES, and used the similar inter-exchange trading features of both systems. First of all, let me say that inter-exchange trading proved to be a critical feature for escalating of local community exchange networks, allowing for bigger and richer transactions.

It happened that one of the networks experimented with a kind of a basic income feature, monthly adding X to the balance of each member. The network quickly became flooded with all balances (but one) very positive and just a few offers, and people used the inter-exchange feature to spend their credit in other neighbour exchanges. Specifically and generally speaking, country-side exchanges were providing goods to this exchange in the city that could never equilibrate the trade balance. Some producers saw their accounts full of a balance that they could not spend because there were not sufficient attractive offers, and stopped accepting exchanging through the system. In my exhcange, we saw the issue before it was too late and we decided to stop allowing the inter-exchange trade just to protect our producers.

After that, in 2016, we created the Espai de coordinació de monedes socials (Coordination Space for Social Currencies). This was a federation of 7 local exchange communities in Catalunya. This space was created (among others) to address this issue and we created a protocol for safe inter-exchange trading. We decided to set a debit and credit limit to each exchange to be 10% of their anual transaction volume. However this protocol didn't had automatic enforcement and in practice it did not work beyond making people aware of the issue. In fact we found that it was difficult to maintain this coordination space because people from the exchanges in the edges struggled to attend to meetings and we dissoluted the space a couple of years later. There is a different coordination platform for exchanges in País Valencià called XXIV, most of them using the CES platform.

I think this was a prototypical use case for the Credit Commons protocol, but still we struggled to make it really work due to, in my opinion, several reasons:

• The coordination space was complex in terms of decision making. The decision places were still the exchanges, so when we had to take a decision, we needed to decide it in all local exchanges before we could agree in the coordination space. Further, presential meetings were difficult. Also, while some exchanges were central geographically, others were in the edge and it was difficult for them to come to the meetings. Furthermore, each network had its own governing idiosyncrasy and velocity.

• Still some community currencies in Catalunya were not part of this coordination space, either because they didn't had the energy to spend in this extra meetings or because the nature of their community was too different. In this second case I'm talking about local currencies backed by euros and created by local councils. There are a few of them here.

After this experience, I think that actual federation (with meetings etc) among local communities is very difficult and totally impractical in some cases. Decentralized technologies allow for trading between entities without further coordination. Cryptocurrencies apply that at an individual level and I think this is not good because it pushes for more individualism and capitalist society. However I think that this technology suits perfectly when it comes to inter-exchange between communities. And among the different options here, my favorite one is what @matslats calls the credit mesh network. This idea was developed in Ripple (again at the individual level, in a centralized server), then in Ripple Labs (the well-known blockchain network) and also in the Stellar network (similarly to ripple labs).

In this case, each exchange unilaterally defines trustlines with other neighbouring exchanges. In CES terms, the trustline sets the debit limit of a neighbouring exchange globally. This is, the trade imbalance between the two exchanges can't excess X units. That allows for trading between trusted communities, but also allows trading between distant currencies through a path of trustlines. So if A trusts B and B trusts C, then a user in C can buy from a user in A. The trade balance between A and B and between B and C is modified by this transaction. Another example: suppose A trusts B but B does not trust A (for example, A is a time bank and B is an euro-backed local currency). Then a user in B happens to buy from a user in A so the trade balance is positive in favor of the time bank A. Then A users can buy from B users until the trade balance goes to 0.

As @matslats points out, trustlines can get full and therefore stop the trade. Then the administration of both exchanges should act to restore the trade balance (eg: send a trailor of oranges from B to A), or just increase the trust limit if thats fine.

Some final points:

• I think we must provide a way to inter-trade between exchanges not only on the accounting level but also on the offers and needs. And the most important think is that it should be easy to use for users and effectively enable inter-exchange trade.
• The mesh scheme is the one I like more from the political (no need to create superstructures beyond local exchanges) and practical point of view (coordination is hard).
• I'd prefer using a multiple-server message-based protocol instead of using a blockchain for the implementation of the mesh interexchange, but I chose Stellar because it was more suitable existing platform already providing that, and there is no production-grade message-based multi-server mesh network implementation. I know there is people working on it.
• I think we should provide a basic protection method so that an exchange can't get lots products and services from nighbour exchanges without giving back.
• Credit Commons is good enough for me and it doesn't have the cons of using a blockchain (it is a message-based protocol). That's why I've started (with @michielbdejong) to implement it in Komunitin and we achieved a very neat UX using QR codes.
• I think that if in the future the reality makes us to upgrade the credit commons protocol to allow more flexible network topologies, nothing prevents us to do it. But now the tree structure is sufficient and simplifies a lot the implementation.

[matslats]

I commend you @estevebadia on your tackling the root question.
I'd like to reframe what you said to speak to non-technical decision makers:

• Mesh credit offers a less formal way to build trading networks, but those networks will have to work harder to balance trade because they are in many bilateral relationships instead of one multilateral relationship.
• Multilateral relationships require more engagement on the political level, but they also make it easier to balance trade.
  From my perspective, Credit Commons is a more perfect structure for optimising trading relationships, and it exists as an ideal to strive towards, but Catalunya's practical experience shows that an ad hoc structure - a mesh without collective governance of balance limits - will serve their cultural context better.
  Tim's preference last time he mentioned it, was to keep Clearing Central "as it is" which I take to mean "as a multilateral network, with potential for participative, and more active, governance."
  If Clearing Central is the trunk of a Credit commons tree, and Catalunya a branch, then the tree does not care how the accounting is done on that branch. it only cares about the balance of trade and the exchange rate. So Komunitin running a mesh for Catalunia is a hard requirement.
  To trade in Clearing Central Komunitin would need to connect as a Credit Commons node joining a group.
  To serve exiting mutual credit groups Komunitin would need to have balance limit policies rather than limits set by members.
  To replace existing CES functionality, Komunitin would also need balance limit policies between groups.

[estevebadia]

I think it is not really possible to evaluate which of the two schemes is better in general and from a theoretical point of view, and maybe there will come more people with more schemes, so we really need to see what happens in reality. I think that the mesh scheme is more practical and politically aligned, but your points make sense too.

Thats why my approach now is just to somehow enable inter-exchange trading between exchanges in CES (and ideally other systems as well), with the focus more on the user experience than in the actual protocol behind the scenes. Then, see what happens and eventually see what new features are required in the protocol and evolve it organically.

I think the Credit Commons protocol is a perfect candidate for that, since it has a good fitting from the architectural point of view (message-based server-to-server open protocol) and it has born in the right context (Collaborative Finance and Community Currencies movement), it is already somewhat well-know in that context and it is maintained by the right person (you ;)).

I imagine setting up a default simple topology and then be open to evolution. We can setup one CC node per CES instance and a trunk one. From this starting point, we can evolve the tree, the policies implemented in the nodes, or the protocol itself based on actual requirements from communities. Probably we'll need more features on account discoverability, payment workflows, quoting a transaction, currency conversion rates etc before we really need to act on debit limits and policies.

Also very important is to have a federation protocol for offers and needs and profiles beyond transactions, but thats a different topic. So I'm more inclined to work towards good UX for inter-exchange trading because I think this is the way it will actually be used.

[matslats]

I'm happy with that.

[olivier108]

For your information, here is some CES inter-exchange activity data for the past 12 months:
30,000 total transactions
7,500 inter-exchange transactions (25% of total volume)
The vast majority of inter-exchange trades happened in Ecuador, Spain and Greece.
Ecuador : 5,849 (78%)
Spain : 1,295 (17%)
Greece : 132 (1.7%)
Australia : 77 (1%)

What we would wish to achieve :

• User Experience Priority, not specific protocol choice
• Users shouldn't need to know about virtual accounts, trust lines, or technical details
• User friendly features (e.g. Komunitin interface showing automatic currency conversion)
• Being able to allow inter-exchange trades between main CES Network alliance partners : CommunityForge, Integral CES, Komunitin, Time Overflow, CES1
• One interface for all transaction types (local and remote)
• QR code scanning to avoid complex address entry
• Automatic protocol selection hidden from users

[olivier108]

@matslats I'd like to get clearer in my own mind about how federation between
Komunitin groups and CES1 would actually work for trades. I'm not familiar with
Credit Commons or Clearing Central, and I'm not a developer but I look after
infrastructure for the network, and I'm trying to understand the moving parts and
the missing pieces, because inter-trading is a crucial goal for the Community Exchange
Network.

We have a demo instance of CES2 running the Komunitin code at
https://ces2demo.community-exchange.org/, so we have somewhere real to experiment.
What we'd love to try is the simplest possible thing: get a single trade working
between one Komunitin group on that demo and one CES1 group, through Clearing Central
and learn from it before planning anything bigger. Following your point that
Komunitin just needs to connect to Clearing Central as a Credit Commons node to trade
with it, a few plain questions:

1. Versions. Komunitin's Credit Commons code is built against the 0.9.x version
   of your reference software (cc-node / cc-php-lib). Is Clearing Central on that
   same version, or something older? If they differ, is it easier to update Clearing
   Central or to have us match it?

2. Connecting up. What does it actually take to let a new system like Komunitin
   connect to Clearing Central as a node: is that something you or Tim set up? And
   is anything needed on the CES1 group's side, or does connecting to Clearing
   Central make all the CES1 groups reachable automatically?

3. The simplest first trade. Two specifics on our side, so you can tell us
   whether a basic trade needs anything more:

   • Conversion: our node currently treats the transaction quantity as the local
     amount directly: it applies no rate conversion, so it assumes a 1:1 rate. What
     unit does Clearing Central denominate transactions in, and does it handle the
     conversion between currencies, or expect each node to?
   • Steps: our node only creates already-committed transactions, it doesn't yet
     implement the pending→confirm two-step workflow. Does Clearing Central accept a
     direct commit for a basic trade, or does it expect the two-step confirmation?

4. Somewhere safe to try it. Is there a test version of Clearing Central we could
   connect the demo to, so a first experiment doesn't touch real CES balances or
   would you suggest we run a local stand-in first?

The goal isn't to settle the whole federation design here, just to get one real
cross-system trade happening, see where where the frictions are, and take it from there. Happy
to enable the Credit Commons node on the demo and share its details so you can see
what it presents.

[matslats]

Hi,

1 Versions. Clearing central is rather fragile since at the moment the old API is implemented as a wrapper around credit commons. Also ces only supports one workflow, so ideally we would move towards retiring the clearing central v1 API then migrating to a clean clearing central instance. Also note that credit commons addresses take the form of a path name, and this doesn't map very well onto clearing central v1 CEN codes.
2 Connecting In order to trade via a clearing central node, a group must first create an account. There is an API callback to do that (but it should be disabled by default for security reasons!) So it is possible to for a group to join, and list the other groups and maybe even members of those groups if those groups allow and implement the method exposing account names.
3a Conversion rates are fixed and decided by the member group but balance limits are decided by the trunkward group. In order to trade via a clearing central node, a group must first create an account. There is an API callback to do that (but it should be disabled by default for security reasons!) Conversion units are always expressed in terms of the unit of the trunkward group. The twigward node must convert the values when communicating with the trunkward node - in both directions.
3b Steps. Yes this is done via workflow. Every transaction has its own workflow and every node can accept or reject certain workflows. Clearing central 1 supports one workflow. The workflow defines which participants in the transaction (or admin) can transition the transaction between certain states, such as validated, completed, pending and erased.
4 testing. Clearing central has never had a test version, which makes it difficult to work on and it means that test transactions have to be deleted manually. The difficulty is coordinating at least 3 databases because the records have to agree. The credit commons does have a test instance but it may not be maintained right now. If you want to use it I can keep it maintained.
I'm sure you will have more questions...

[olivier108]

@matslats, thank you, this is really helpful!

Thank you for your offer of the Credit Commons test instance: yes please,if you're willing to keep it maintained, we'd like to use it. Given that Clearing Central has no test version and needs three databases to stay in agreement, we could try to prove the plumbing first over pure Credit Commons? Get one trade working between our CES2 demo (as a CC node) and your test instance before we go anywhere near live Clearing Central or a CES1 group. Does that ordering make sense to you: the CC test instance first, the Clearing Central bridge second?

Sorry, a few more questions :-)

1. Topology / trunk. Where does Clearing Central sit in the tree? Is it itself the trunk, or does it connect up to a trunk above it? And for the test instance:
   would our demo attach as a twig directly under it, with the test instance acting as the trunk?

2. Units, to defer the conversion work. You said the twigward node must convert to and from the trunkward group's unit in both directions. Our node doesn't do that yet. For a first test, could we simply set our demo group's unit equal to the trunk unit (a genuine 1:1), so we can prove the connection before we build the conversion?

3. Workflow. You mentioned Clearing Central supports a single workflow. For the test instance, which workflow would a basic trade use, and does it allow a direct commit, or does it require stepping through validated → pending → completed? That tells us whether CES2 needs to implement the state transitions on our side before a first trade.

4. Getting our demo an account. You mentioned a group joins by creating an account via an API callback (disabled by default for security). What would you need from us to let our demo create its node/account on the test instance? We'll share the
   demo's node details so you can see what it presents.

No rush on any of this, I appreciate you engaging.

[matslats]

ok I need to get my shit together because working on credit commons is always very involved. At the same time I'm working to set up a drupal 11 hosting platform, and preparing the Community Forge upgrade from Drupal 7. In 10 days I'm going away for a week.

1. Clearing central is the trunk of the whole ces ecosystem. Stephanie Rearick has a theoretical tree for Humans, but like the demo site the demand is so low, I don't have time to maintain it, and I never know if it is working at any given time. The official demo/test tree is at demo.creditcommons.org which currently has an expired ssl certifcate. That url leads to a browser client which you can plug into the demo nodes, details to follow.
2. yes. The trunkward node knows nothing of its branches' conversion rates
3. I'll give you the workflow code for ces1. It has no pending state and no possibility to erase it. Probably all user-created transactions should have a validated state, but automated transactions might assume the transaction validates.
4. I'll give you the API request to create an account. then you can create accounts with two groups and register transactions.
   A demo server is useful because rather than try to some or all transactions you can just wipe the transactions table(s). This is especially useful when you are trying to get your own software to calculate the right hash for each transaction.

[olivier108]

@matslats understood, no pressure at all, and this is all very useful. Whenever suits you.

Good to have it confirmed that Clearing Central is the trunk. The workflow point is
encouraging too: with no pending or erase state, it sounds like a direct commit might be
enough for a Komunitin↔CES1 trade, rather than the two-step confirmation flow. We'll
know better once we see the workflow code.

Whenever you have a moment, the CES1 workflow code and the account-creation request would let
us start connecting our Komunitin demo to demo.creditcommons.org on our own. Thanks for the
SSL heads-up, we'll work around it.

I'll be at the HUMANs retreat in Belgium too, so we can carry on in person, maybe even sneak
in a little hacking session :-) Really appreciate you taking the time.

[matslats]

ok there is a demo tree now working. the following will help Esteve get started.
Demo client is at demo.creditcommons.org. You can use it as GUI for any of the demo nodes. The demo nodes are:
twig
branch
trunk

Each expects requests as defined in the API document.

The first request a communitin node might make is to request a new account be created. Currently twig does not accept account creation requests from anonymous, but branch does. The request looks like this.
POST http://branch.creditcommons.org/account
{
"acc_id": "mygroupname",
"url": "http://mygroup.komunitin.com",
"min": "-1000" // trunkward group units
"max": "1000" // if not stated will fall back to a default.
}
It responds with its own absolute path, to which you should add 'mygroupname' and save as your node's absolute path. Remember the trunkward node does not know the conversion rate.
When you want to add a transaction here are the clearing centraly legacy workflow codes to use:
_C- the payer created the transaction in completed state, and skipped the validation page.
_C+ the payee created the transaction in completed state, and skipped the validation page.

I think that's all you asked for. I believe it's all working.
Matthew

[olivier108]

@matslats, brilliant, thank you. Standing up the whole demo tree is above and beyond,
and having the account-creation call and the workflow codes spelled out gives us
everything we need to have a proper go at a first trade. Really appreciate it, no doubt
we'll have questions once we dig in. See you in Belgium.